@intentius/chant 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/commands/describe.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect } from "vitest";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { describeCommand } from "./describe";
+
+// The #203 layered-config example: one WebApp instantiated for dev/staging/prod
+// from layered (spread) config. describe v1 projects the effective, resolved
+// config for one named component over it.
+const exampleSrc = resolve(
+  fileURLToPath(import.meta.url),
+  "../../../../../../lexicons/k8s/examples/layered-config/src",
+);
+
+function opts(component: string, format: "text" | "json" = "json") {
+  return { component, path: exampleSrc, format };
+}
+
+describe("describeCommand (resolved view, v1)", () => {
+  test("describes a composite instance by its export name (grouped resources)", async () => {
+    const r = await describeCommand(opts("prodApp"));
+    expect(r.success).toBe(true);
+    expect(r.composite).toBe(true);
+    const names = r.resources.map((x) => x.name).sort();
+    expect(names).toEqual([
+      "prodAppDeployment",
+      "prodAppIngress",
+      "prodAppPdb",
+      "prodAppService",
+    ]);
+  });
+
+  test("shows the effective, fully-resolved props (post-merge)", async () => {
+    const r = await describeCommand(opts("prodApp"));
+    const dep = r.resources.find((x) => x.entityType.endsWith("Deployment"))!;
+    const props = dep.props as { spec: { replicas: number }; metadata: { labels: Record<string, string> } };
+    // prod overrode replicas; base labels merged with prod-only ones.
+    expect(props.spec.replicas).toBe(6);
+    expect(props.metadata.labels["app.kubernetes.io/part-of"]).toBe("acme-web"); // base layer
+    expect(props.metadata.labels["acme.io/env"]).toBe("prod"); // env layer
+    expect(props.metadata.labels["acme.io/tier"]).toBe("critical"); // prod-only
+  });
+
+  test("environments resolve to different effective configs", async () => {
+    const dev = await describeCommand(opts("devApp"));
+    const devDep = dev.resources.find((x) => x.entityType.endsWith("Deployment"))!;
+    const devProps = devDep.props as { spec: { replicas: number }; metadata: { labels: Record<string, string> } };
+    expect(devProps.spec.replicas).toBe(2); // base default, not overridden in dev
+    expect(devProps.metadata.labels["acme.io/env"]).toBe("dev");
+    expect(devProps.metadata.labels["acme.io/tier"]).toBeUndefined(); // prod-only key absent
+    // dev declares no ingress; prod does.
+    expect(dev.resources.some((x) => x.entityType.endsWith("Ingress"))).toBe(false);
+  });
+
+  test("describes a single declarable by exact name (not a composite)", async () => {
+    const r = await describeCommand(opts("devAppService"));
+    expect(r.success).toBe(true);
+    expect(r.composite).toBe(false);
+    expect(r.resources).toHaveLength(1);
+    expect(r.resources[0].entityType).toBe("K8s::Core::Service");
+  });
+
+  test("unknown component fails with the known-component list", async () => {
+    const r = await describeCommand(opts("doesNotExist"));
+    expect(r.success).toBe(false);
+    expect(r.output).toContain("No component");
+    expect(r.output).toContain("prodAppDeployment");
+  });
+
+  test("text format renders the component header and props", async () => {
+    const r = await describeCommand(opts("prodApp", "text"));
+    expect(r.output).toContain("prodApp");
+    expect(r.output).toContain("K8s::Apps::Deployment");
+    expect(r.output).toContain("web-prod");
+  });
+});

package/src/cli/commands/describe.ts

@@ -0,0 +1,141 @@
+import { resolve } from "path";
+import { discover } from "../../discovery/index";
+import type { Declarable } from "../../declarable";
+import { formatSuccess, formatBold } from "../format";
+
+/**
+ * `chant describe <component>` — project the effective, fully-resolved
+ * configuration for one named component, offline (source only; no live calls).
+ *
+ * `chant list` shows inventory and `chant graph` shows edges; neither shows the
+ * resolved property bag for a single thing. `describe` does: for a layered
+ * config (see the layered-config guide) it answers "what is the effective config
+ * for this component, after every spread/override?" without merging the layers
+ * by hand.
+ */
+export interface DescribeOptions {
+  /** The component to describe — a named export (declarable or composite instance). */
+  component: string;
+  /** Path to the infrastructure directory. */
+  path: string;
+  /** Output format. */
+  format: "text" | "json";
+}
+
+/** One resolved resource produced by the component. */
+export interface DescribedResource {
+  name: string;
+  lexicon: string;
+  entityType: string;
+  kind: string;
+  /** The resolved (post-merge, post-composite-expansion) property bag. */
+  props: unknown;
+}
+
+export interface DescribeResult {
+  success: boolean;
+  component: string;
+  /** True when the component is a composite instance (≥1 produced resource by prefix). */
+  composite: boolean;
+  resources: DescribedResource[];
+  output: string;
+}
+
+/** Read a discovered entity's resolved props (same accessor the build pipeline uses). */
+function readProps(entity: Declarable): unknown {
+  return "props" in entity ? (entity as { props: unknown }).props : undefined;
+}
+
+/**
+ * Find the entities a component name refers to. A composite instance is
+ * flattened at discovery: `WebApp(x)` exported as `foo` becomes `fooDeployment`,
+ * `fooService`, … — so an exact-name miss falls back to grouping entities whose
+ * name is the export prefix followed by a capitalized result key.
+ */
+function matchComponent(
+  entities: Map<string, Declarable>,
+  component: string,
+): { matched: Array<[string, Declarable]>; composite: boolean } {
+  const exact = entities.get(component);
+  if (exact) return { matched: [[component, exact]], composite: false };
+
+  const grouped = [...entities].filter(
+    ([n]) =>
+      n.length > component.length &&
+      n.startsWith(component) &&
+      n.charAt(component.length) === n.charAt(component.length).toUpperCase() &&
+      n.charAt(component.length) !== n.charAt(component.length).toLowerCase(),
+  );
+  grouped.sort((a, b) => a[0].localeCompare(b[0]));
+  return { matched: grouped, composite: grouped.length > 0 };
+}
+
+export async function describeCommand(options: DescribeOptions): Promise<DescribeResult> {
+  const infraPath = resolve(options.path);
+  const result = await discover(infraPath);
+
+  if (result.errors.length > 0) {
+    return {
+      success: false,
+      component: options.component,
+      composite: false,
+      resources: [],
+      output: result.errors.map((e) => e.message).join("\n"),
+    };
+  }
+
+  const { matched, composite } = matchComponent(result.entities, options.component);
+
+  if (matched.length === 0) {
+    const known = [...result.entities.keys()].sort().join(", ");
+    return {
+      success: false,
+      component: options.component,
+      composite: false,
+      resources: [],
+      output: `No component "${options.component}" found.\nKnown components: ${known || "(none)"}`,
+    };
+  }
+
+  const resources: DescribedResource[] = matched.map(([name, decl]) => ({
+    name,
+    lexicon: decl.lexicon ?? "",
+    entityType: decl.entityType ?? "",
+    kind: decl.kind ?? "resource",
+    props: readProps(decl),
+  }));
+
+  const output =
+    options.format === "json"
+      ? JSON.stringify({ component: options.component, composite, resources }, null, 2)
+      : formatText(options.component, composite, resources);
+
+  return { success: true, component: options.component, composite, resources, output };
+}
+
+/** Human-readable effective-config view. */
+function formatText(component: string, composite: boolean, resources: DescribedResource[]): string {
+  const lines: string[] = [];
+  const header = composite
+    ? `${formatBold(component)} — composite instance, ${resources.length} resource(s)`
+    : `${formatBold(component)}`;
+  lines.push(header);
+  for (const r of resources) {
+    lines.push("");
+    lines.push(`  ${formatBold(r.name)}  (${r.entityType})`);
+    const propsJson = JSON.stringify(r.props ?? {}, null, 2)
+      .split("\n")
+      .map((l) => `    ${l}`)
+      .join("\n");
+    lines.push(propsJson);
+  }
+  return lines.join("\n");
+}
+
+/** Print a describe result to the console. */
+export function printDescribeResult(result: DescribeResult): void {
+  if (result.output) console.log(result.output);
+  if (result.success) {
+    console.error(formatSuccess(`Described ${formatBold(result.component)}`));
+  }
+}

package/src/cli/handlers/misc.ts

@@ -1,4 +1,5 @@
 import { listCommand, printListResult } from "../commands/list";
+import { describeCommand, printDescribeResult } from "../commands/describe";
 import { importCommand, importFromLive, printImportResult } from "../commands/import";
 import type { ResourceSelector } from "../../lexicon";
 import { formatError, formatSuccess, formatWarning } from "../format";
@@ -21,6 +22,35 @@ export async function runList(ctx: CommandContext): Promise<number> {
   return result.success ? 0 : 1;
 }
 
+export async function runDescribe(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  // `chant describe <component> [path]` — component is the first positional
+  // (args.path), the optional project dir is the second (args.extraPositional).
+  const component = args.path;
+  if (!component || component === ".") {
+    console.error(formatError({
+      message: "Component is required: chant describe <component> [path]",
+      hint: "Run `chant list` to see component names.",
+    }));
+    return 1;
+  }
+
+  const describeFormat = (args.format || "text") as "text" | "json";
+  if (describeFormat !== "text" && describeFormat !== "json") {
+    console.error(formatError({ message: `Invalid format for describe: ${describeFormat}. Expected 'text' or 'json'.` }));
+    return 1;
+  }
+
+  const result = await describeCommand({
+    component,
+    path: args.extraPositional ?? ".",
+    format: describeFormat,
+  });
+
+  printDescribeResult(result);
+  return result.success ? 0 : 1;
+}
+
 export async function runImport(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
 

package/src/cli/main.ts

@@ -11,7 +11,7 @@ import { runLint } from "./handlers/lint";
 import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDevUnknown } from "./handlers/dev";
 import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
-import { runList, runImport, runUpdate, runDoctor } from "./handlers/misc";
+import { runList, runDescribe, runImport, runUpdate, runDoctor } from "./handlers/misc";
 import { runMigrate } from "./handlers/migrate";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecyclePlan, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runGraph } from "./handlers/graph";
@@ -154,6 +154,7 @@ Commands:
   build                 Build infrastructure from specification files
   lint                  Check specifications for issues
   list                  List discovered entities
+  describe              Show the effective config for one component
   import                Import external template into TypeScript
   migrate <file>        Translate a workflow between lexicons
                         (default: --from github --to gitlab)
@@ -230,6 +231,8 @@ Examples:
   chant lint ./infra/ --watch
   chant list ./infra/
   chant list ./infra/ --format json
+  chant describe myComponent src/
+  chant describe myComponent src/ --format json
 `);
 }
 
@@ -265,6 +268,7 @@ const registry: CommandDef[] = [
   { name: "build", requiresPlugins: true, handler: runBuild },
   { name: "lint", handler: runLint },
   { name: "list", handler: runList },
+  { name: "describe", handler: runDescribe },
   { name: "import", handler: runImport },
   { name: "migrate", handler: runMigrate },
   { name: "init", handler: runInit },