@intentius/chant 0.13.0 → 0.15.0

package/src/components/discover.test.ts

@@ -0,0 +1,352 @@
+/**
+ * Discovery tests for the typed `Component` authoring form (#560, epic #551).
+ *
+ * Mirrors `../discovery/index.test.ts`'s style (write real `.ts` fixture
+ * files to a temp dir, run the discovery entrypoint, assert on the returned
+ * map) rather than `../op/discover.test.ts`'s (which discovers from the git
+ * root against real example files) since `discoverComponents`, like
+ * `discover()`, takes an explicit path rather than always walking from the
+ * repo root.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { discoverComponents } from "./discover";
+
+describe("discoverComponents", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-component-discover-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("returns empty result for an empty directory", async () => {
+    const result = await discoverComponents(testDir);
+    expect(result.components.size).toBe(0);
+    expect(result.sourceFiles).toEqual([]);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("discovers a component from a single *.component.ts file", async () => {
+    await writeFile(
+      join(testDir, "search.component.ts"),
+      `
+        export const searchService = {
+          name: "search-service",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell", command: "echo ok" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.errors).toEqual([]);
+    expect(result.components.size).toBe(1);
+    expect(result.components.has("search-service")).toBe(true);
+    expect(result.components.get("search-service")?.exportName).toBe("searchService");
+    expect(result.sourceFiles).toHaveLength(1);
+    expect(result.sourceFiles[0]).toMatch(/search\.component\.ts$/);
+  });
+
+  test("discovers multiple components across multiple files, keyed by component.name not export name", async () => {
+    await writeFile(
+      join(testDir, "a.component.ts"),
+      `
+        export const foo = {
+          name: "svc-a",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "b.component.ts"),
+      `
+        export const bar = {
+          name: "svc-b",
+          dependsOn: ["svc-a"],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.errors).toEqual([]);
+    expect(result.components.size).toBe(2);
+    expect([...result.components.keys()].sort()).toEqual(["svc-a", "svc-b"]);
+    expect(result.sourceFiles).toHaveLength(2);
+  });
+
+  test("discovers multiple components exported from one file (any export name, not just default)", async () => {
+    await writeFile(
+      join(testDir, "multi.component.ts"),
+      `
+        export const first = {
+          name: "first-comp",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+        export const second = {
+          name: "second-comp",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.errors).toEqual([]);
+    expect(result.components.size).toBe(2);
+    expect(result.components.has("first-comp")).toBe(true);
+    expect(result.components.has("second-comp")).toBe(true);
+  });
+
+  test("ignores non-.component.ts files, even if they export a Component-shaped value", async () => {
+    await writeFile(
+      join(testDir, "not-a-component.ts"),
+      `
+        export const sneaky = {
+          name: "sneaky",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.components.size).toBe(0);
+    expect(result.sourceFiles).toEqual([]);
+  });
+
+  test("excludes .test.component.ts / .spec.component.ts files", async () => {
+    await writeFile(
+      join(testDir, "real.component.ts"),
+      `
+        export const real = {
+          name: "real",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "fixture.test.component.ts"),
+      `
+        export const testOnly = {
+          name: "test-only",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.components.size).toBe(1);
+    expect(result.components.has("real")).toBe(true);
+    expect(result.components.has("test-only")).toBe(false);
+    expect(result.sourceFiles).toHaveLength(1);
+  });
+
+  test("ignores non-Component-shaped exports from a *.component.ts file", async () => {
+    await writeFile(
+      join(testDir, "mixed.component.ts"),
+      `
+        export const realComponent = {
+          name: "real-component",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+        export const helper = { foo: "bar" };
+        export const CONST = 42;
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.components.size).toBe(1);
+    expect(result.components.has("real-component")).toBe(true);
+  });
+
+  test("recurses into nested directories", async () => {
+    const subDir = join(testDir, "services", "search");
+    await mkdir(subDir, { recursive: true });
+    await writeFile(
+      join(subDir, "search.component.ts"),
+      `
+        export const searchService = {
+          name: "search-service",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.components.size).toBe(1);
+    expect(result.components.has("search-service")).toBe(true);
+    expect(result.sourceFiles[0]).toMatch(/search\.component\.ts$/);
+  });
+
+  test("skips node_modules", async () => {
+    const nm = join(testDir, "node_modules", "some-pkg");
+    await mkdir(nm, { recursive: true });
+    await writeFile(
+      join(nm, "vendored.component.ts"),
+      `
+        export const vendored = {
+          name: "vendored",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.components.size).toBe(0);
+    expect(result.sourceFiles).toEqual([]);
+  });
+
+  test("reports a duplicate component name across two files as a resolution error", async () => {
+    await writeFile(
+      join(testDir, "one.component.ts"),
+      `
+        export const svc = {
+          name: "dup",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "two.component.ts"),
+      `
+        export const svcAgain = {
+          name: "dup",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors[0]?.type).toBe("resolution");
+    expect(result.errors[0]?.message).toMatch(/Duplicate component name "dup"/);
+    // The first one found is kept; discovery continues rather than aborting.
+    expect(result.components.has("dup")).toBe(true);
+  });
+
+  test("collects an import error (syntax error) and continues processing other files", async () => {
+    await writeFile(
+      join(testDir, "good.component.ts"),
+      `
+        export const good = {
+          name: "good",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "bad.component.ts"),
+      `
+        export const bad = {
+          name: "bad"
+          dependsOn: [],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.components.has("good")).toBe(true);
+    expect(result.errors.some((e) => e.type === "import")).toBe(true);
+  });
+
+  test("the first chant.config.ts encountered becomes the source root and is still scanned", async () => {
+    // Matches findInfraFiles's own rule: the *first* config directory found
+    // becomes `sourceRoot` and is descended into, same as any other
+    // directory — the skip only applies to a *second* nested config found
+    // after that (see the next test).
+    const childDir = join(testDir, "child-project");
+    await mkdir(childDir, { recursive: true });
+    await writeFile(join(childDir, "chant.config.ts"), `export default {};`);
+    await writeFile(
+      join(childDir, "child.component.ts"),
+      `
+        export const childSvc = {
+          name: "child-svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "root.component.ts"),
+      `
+        export const rootSvc = {
+          name: "root-svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    expect(result.components.has("root-svc")).toBe(true);
+    expect(result.components.has("child-svc")).toBe(true);
+  });
+
+  test("a second nested chant.config.ts (a true child project) is not descended into", async () => {
+    const firstConfigDir = join(testDir, "first-config");
+    const nestedChildProject = join(firstConfigDir, "nested-child-project");
+    await mkdir(nestedChildProject, { recursive: true });
+    await writeFile(join(firstConfigDir, "chant.config.ts"), `export default {};`);
+    await writeFile(join(nestedChildProject, "chant.config.ts"), `export default {};`);
+    await writeFile(
+      join(firstConfigDir, "first.component.ts"),
+      `
+        export const firstSvc = {
+          name: "first-svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+    await writeFile(
+      join(nestedChildProject, "nested.component.ts"),
+      `
+        export const nestedSvc = {
+          name: "nested-svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    const result = await discoverComponents(testDir);
+
+    // first-config/ has no config above it, so it becomes the source root
+    // and is scanned; nested-child-project/'s own chant.config.ts is the
+    // *second* config encountered, so it is treated as a separate project
+    // scope and not descended into.
+    expect(result.components.has("first-svc")).toBe(true);
+    expect(result.components.has("nested-svc")).toBe(false);
+  });
+});

package/src/components/discover.ts

@@ -0,0 +1,167 @@
+/**
+ * Component discovery — Phase 2 (#560, epic #551).
+ *
+ * Mirrors chant's existing declarable discovery
+ * (`../discovery/index.ts`'s `discover()`, built on `findInfraFiles`) as
+ * closely as a structurally distinct type allows, and borrows its
+ * file-suffix convention from Op discovery
+ * (`../op/discover.ts`'s `discoverOps()`, `*.op.ts`): a component is any
+ * `Component`-shaped value (see `./component.ts`'s `isComponent`) exported
+ * (by any export name, not just `default`) from a `*.component.ts` file.
+ *
+ * Why a dedicated convention rather than folding into `discover()`:
+ * `Declarable` (`../declarable.ts`) is a lexicon-resource marker —
+ * `{ lexicon, entityType, kind, [DECLARABLE_MARKER]: true }` — and a
+ * `Component` has none of that shape (no `lexicon`, and its `deploy`
+ * composition is data the capability driver interprets, not a serializable
+ * lexicon resource). Reusing `collectEntities`/`isDeclarable` would mean
+ * either stretching the `Declarable` marker to cover an unrelated shape or
+ * silently ignoring components during the existing walk. A parallel,
+ * purpose-built collector keeps both conventions simple: `*.ts` + the
+ * `Declarable` marker for resources, `*.component.ts` + the `Component`
+ * shape for components — exactly how `*.op.ts` is already a parallel,
+ * purpose-built convention for Ops.
+ *
+ * Filename convention (`*.component.ts`) is documented here rather than
+ * inferred from export shape alone so a project can `grep` for its
+ * components the same way it can for `*.op.ts` files, and so discovery does
+ * not have to import (and risk side-effecting) every `.ts` file in the
+ * project looking for stray `Component`-shaped objects.
+ */
+
+import { readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+import { DiscoveryError } from "../errors";
+import { isComponent, type Component } from "./component";
+
+/** One discovered component, paired with the file it was exported from. */
+export interface DiscoveredComponent {
+  component: Component;
+  /** The export name the component was found under (informational; components are keyed by their own `.name`, not this). */
+  exportName: string;
+  filePath: string;
+}
+
+export interface ComponentDiscoveryResult {
+  /** Discovered components, keyed by `component.name` (the schema identity), not by export name or file. */
+  components: Map<string, DiscoveredComponent>;
+  /** Every `*.component.ts` file that was scanned. */
+  sourceFiles: string[];
+  errors: DiscoveryError[];
+}
+
+/**
+ * Recursively find every `*.component.ts` file under `path`, the same
+ * child-project boundary rule `findInfraFiles` (`../discovery/files.ts`)
+ * uses: a subdirectory with its own `chant.config.ts` is a separate scope
+ * once the outer project's own source root has been established.
+ */
+async function findComponentFiles(path: string): Promise<string[]> {
+  const files: string[] = [];
+  let sourceRoot: string | null = null;
+
+  async function scanDirectory(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        // Skip dependency and tool/VCS directories: component sources never live
+        // in them, and descending in is both wasted work and a correctness bug —
+        // e.g. a CI runner like gitlab-ci-local stages a copy of the project
+        // under `.gitlab-ci-local/`, which discovery would otherwise pick up as
+        // duplicate component names alongside the originals.
+        if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+
+        const configPath = join(fullPath, "chant.config.ts");
+        if (existsSync(configPath)) {
+          if (sourceRoot === null) {
+            sourceRoot = fullPath;
+          } else {
+            continue;
+          }
+        }
+        await scanDirectory(fullPath);
+      } else if (
+        entry.isFile() &&
+        entry.name.endsWith(".component.ts") &&
+        !entry.name.endsWith(".test.component.ts") &&
+        !entry.name.endsWith(".spec.component.ts")
+      ) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  await scanDirectory(path);
+  return files;
+}
+
+/**
+ * Discover every `Component` declared under `path`: scan for `*.component.ts`
+ * files, import each, and collect every export whose value satisfies
+ * `isComponent` (any export name — not just `default` — so a file may
+ * declare several related components, matching how a resource file can
+ * export several `Declarable`s). Duplicate `component.name` across files (or
+ * within one file) is a discovery error, matching `collectEntities`'s
+ * duplicate-export handling and `discoverOps`'s duplicate-Op-name handling —
+ * except the identity compared is the schema-level `name` field, since two
+ * different export bindings could otherwise declare the same component name
+ * and silently collide at deploy time.
+ */
+export async function discoverComponents(path: string): Promise<ComponentDiscoveryResult> {
+  const errors: DiscoveryError[] = [];
+  const sourceFiles = await findComponentFiles(path);
+  const components = new Map<string, DiscoveredComponent>();
+  const nameToFile = new Map<string, string>();
+
+  for (const filePath of sourceFiles) {
+    let exports: Record<string, unknown>;
+    try {
+      // Resolve to an absolute file:// URL before importing. A relative
+      // `filePath` (e.g. from `chant build --components --generate`, which passes
+      // a bare "." path) would otherwise be treated by `import()` as a bare
+      // package specifier and fail with "Cannot find package 'x.component.ts'".
+      exports = await import(pathToFileURL(resolve(filePath)).href);
+    } catch (err) {
+      errors.push(new DiscoveryError(filePath, err instanceof Error ? err.message : String(err), "import"));
+      continue;
+    }
+
+    for (const [exportName, value] of Object.entries(exports)) {
+      if (!isComponent(value)) continue;
+
+      const existingFile = nameToFile.get(value.name);
+      if (existingFile && existingFile !== filePath) {
+        errors.push(
+          new DiscoveryError(
+            filePath,
+            `Duplicate component name "${value.name}" in ${filePath} and ${existingFile}`,
+            "resolution",
+          ),
+        );
+        continue;
+      }
+      const existing = components.get(value.name);
+      if (existing && existing.component !== value) {
+        errors.push(
+          new DiscoveryError(filePath, `Duplicate component name "${value.name}" in ${filePath}`, "resolution"),
+        );
+        continue;
+      }
+
+      nameToFile.set(value.name, filePath);
+      components.set(value.name, { component: value, exportName, filePath });
+    }
+  }
+
+  return { components, sourceFiles, errors };
+}

package/src/components/driver-output.ts

@@ -0,0 +1,71 @@
+/**
+ * Renderers for `chant run --components` (#585) — the interpret driver's CLI
+ * output. Mirrors `../op/local-output.ts`'s `renderHuman`/`renderJson` pair
+ * for Ops: both consume the same `DriverRunResult` (`./driver.ts`);
+ * `renderDriverHuman` is the default (logs to stderr), `renderDriverJson`
+ * prints the machine-readable result as JSON on stdout and nothing else.
+ */
+
+import type { DriverRunResult, DriverStepRecord } from "./driver";
+
+type Writer = (line: string) => void;
+
+const stderr: Writer = (line) => process.stderr.write(line + "\n");
+const stdout: Writer = (line) => process.stdout.write(line + "\n");
+
+function formatDuration(ms: number): string {
+  return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
+function statusMark(status: DriverStepRecord["status"]): string {
+  switch (status) {
+    case "ok":
+      return "✓";
+    case "fail":
+      return "✗";
+    case "rolled-back":
+      return "↺";
+    default:
+      return "•";
+  }
+}
+
+/**
+ * Render an interpret-driver run result as human-readable progress. Defaults
+ * to stderr so stdout stays clean for piping (the `--json` renderer owns
+ * stdout). Groups records by component, then by phase, matching the driver's
+ * own wave/phase/step nesting.
+ */
+export function renderDriverHuman(result: DriverRunResult, write: Writer = stderr): void {
+  for (const componentResult of result.results) {
+    write(`[component] ${componentResult.component}`);
+    let currentPhase: string | undefined;
+    for (const record of componentResult.records) {
+      if (record.phase !== currentPhase) {
+        currentPhase = record.phase;
+        write(`  [phase] ${currentPhase}`);
+      }
+      const mark = statusMark(record.status);
+      if (record.status === "skipped") {
+        write(`    ${mark} ${record.kind}   skipped`);
+      } else {
+        write(`    ${mark} ${record.kind}   ${formatDuration(record.durationMs)}`);
+      }
+      if (record.error) {
+        write(`      ${record.error}`);
+      }
+    }
+    write(componentResult.ok ? `  component "${componentResult.component}" completed` : `  component "${componentResult.component}" failed`);
+  }
+
+  if (result.ok) {
+    write(`interpret run completed (${result.order.length} component(s))`);
+  } else {
+    write(`interpret run failed at component "${result.failedComponent}"`);
+  }
+}
+
+/** Render an interpret-driver run result as JSON on stdout (and nothing else on stdout). */
+export function renderDriverJson(result: DriverRunResult, write: Writer = stdout): void {
+  write(JSON.stringify(result));
+}