@intentius/chant 0.124.13 → 0.124.14

package/dist/components/discover.js

@@ -0,0 +1,189 @@
+/**
+ * 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.
+ *
+ * chant #1051 — `discoverComponents` unconditionally `await import()`s every
+ * discovered file in the CLI's own process, the same exposure #1045 Phase 2
+ * closed for lexicon-resource discovery (`../discovery/index.ts`'s
+ * `discover({ sandbox: true })`). `{ sandbox: true }` here runs that import
+ * (and the duplicate-name collection below) together, isolated, in one
+ * sandboxed child process instead — see `./sandbox/driver.ts`/`./sandbox/
+ * run.ts`. Materially simpler than the entity path: a `Component` is plain
+ * JSON (no `AttrRef` cross-references), so the child can hand back its result
+ * with a bare `JSON.stringify` — no entity-wire codec needed (`projectToJson`,
+ * `./component.ts`, already proves the plain-JSON round-trip).
+ */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DiscoveryError } from "../errors.js";
+import { isComponent } from "./component.js";
+import { buildParamValues } from "../build-params.js";
+import { setBuildParams } from "../params.js";
+import { hasDiscoveryMarkerSync } from "../discovery/files.js";
+import { resolveDiscoveryGlobs } from "../config.js";
+import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk.js";
+import { ensureTypeScriptLoader } from "../ts-loader.js";
+/**
+ * Every `*.component.ts` file under `path`, through the one discovery walk
+ * (`../discovery/walk.ts`, #2527): the same dot-directory, `dist`,
+ * git-ignore and child-project rules as source discovery, the project's
+ * `exclude`/`include` globs and the skip marker (#2519). Scanned from outside
+ * any project, every child project is read.
+ */
+async function findComponentFiles(path) {
+    return walkDiscovery({
+        walker: "components",
+        root: path,
+        globs: await resolveDiscoveryGlobs(path),
+        excludeDirs: await workspaceMemberDirs(path),
+        accept: (name, full) => name.endsWith(".component.ts") &&
+            !name.endsWith(".test.component.ts") &&
+            !name.endsWith(".spec.component.ts") &&
+            !hasDiscoveryMarkerSync(full),
+    });
+}
+/**
+ * Collect every `Component`-shaped export from already-imported `modules`,
+ * enforcing the duplicate-`component.name` rule (across files, or within one
+ * file): 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. `existing.component !== value` — object
+ * identity, not deep equality — is what lets the SAME component re-exported
+ * under several bindings pass through without tripping the duplicate check.
+ *
+ * Split out from {@link discoverComponents} (#1051) precisely because that
+ * identity check has to run on the LIVE, still-in-memory export values —
+ * identity does not survive a process boundary. That means this function
+ * must run wherever `modules` were actually imported: in this process for
+ * the default (unsandboxed) path below, or inside the sandboxed child for
+ * `{ sandbox: true }` (`./sandbox/driver.ts`, which bundles and calls this
+ * same function), mirroring how `collectEntities` runs inside `../discovery/
+ * sandbox/driver.ts` for the lexicon-resource run-fallback set (chant #1045
+ * Phase 2).
+ */
+export function collectComponents(modules) {
+    const errors = [];
+    const components = new Map();
+    const nameToFile = new Map();
+    for (const { file: filePath, exports } of modules) {
+        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, errors };
+}
+/**
+ * Import every already-discovered `*.component.ts` file in THIS process (the
+ * unsandboxed default) and collect their `Component`-shaped exports.
+ */
+async function importAndCollectComponents(sourceFiles) {
+    const modules = [];
+    const importErrors = [];
+    for (const filePath of sourceFiles) {
+        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'".
+            ensureTypeScriptLoader();
+            const exports = await import(pathToFileURL(resolve(filePath)).href);
+            modules.push({ file: filePath, exports });
+        }
+        catch (err) {
+            importErrors.push(new DiscoveryError(filePath, err instanceof Error ? err.message : String(err), "import"));
+        }
+    }
+    const { components, errors: collectErrors } = collectComponents(modules);
+    return { components, errors: [...importErrors, ...collectErrors] };
+}
+/**
+ * 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). See {@link collectComponents} for the
+ * duplicate-name rule.
+ *
+ * `{ sandbox: true }` (#1051) imports every file together, isolated, in one
+ * sandboxed child process instead (`./sandbox/run.ts`) — the same isolation
+ * `discover({ sandbox: true })` (`../discovery/index.ts`) gives lexicon
+ * resources, chant #1045 Phase 2.
+ */
+export async function discoverComponents(path, options) {
+    // chant #1108 — populate the shared build-time-parameters object BEFORE
+    // scanning/importing any *.component.ts file below, so a live `import {
+    // params } from "@intentius/chant/params"` inside a component file
+    // observes this invocation's resolved values instead of an empty object.
+    // Unconditional (not just when `buildParams` is set) so a stale value from
+    // a PRIOR discoverComponents() call in the same process (tests, several
+    // `--components` subcommands run back-to-back) never leaks into a call
+    // that supplied none — mirrors ../discovery/index.ts's `discover()`,
+    // identical rationale.
+    setBuildParams(buildParamValues(options?.buildParams ?? []));
+    const sourceFiles = await findComponentFiles(path);
+    if (options?.sandbox && sourceFiles.length > 0) {
+        // Dynamic, not static — for the same reason `../discovery/index.ts`
+        // dynamically imports its own `./sandbox/run`: that module (transitively)
+        // imports `esbuild`, a large package with its own module-scope filesystem
+        // access, and this module is reachable from `@intentius/chant`'s package
+        // root, which project source commonly imports. A static import here would
+        // make `esbuild` bundled and eagerly evaluated by any build of a project
+        // that itself imports chant. A dynamic import is only ever actually
+        // reached here, at runtime, when a caller opts into `sandbox: true`.
+        try {
+            const { discoverComponentsSandboxed } = await import("./sandbox/run.js");
+            const result = await discoverComponentsSandboxed(sourceFiles, path);
+            return { components: result.components, sourceFiles, errors: result.errors };
+        }
+        catch (err) {
+            return {
+                components: new Map(),
+                sourceFiles,
+                errors: [new DiscoveryError(path, err instanceof Error ? err.message : String(err), "resolution")],
+            };
+        }
+    }
+    const { components, errors } = await importAndCollectComponents(sourceFiles);
+    return { components, sourceFiles, errors };
+}

package/dist/components/driver-output.js

@@ -0,0 +1,86 @@
+/**
+ * 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 { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note.js";
+const stderr = (line) => process.stderr.write(line + "\n");
+const stdout = (line) => process.stdout.write(line + "\n");
+function formatDuration(ms) {
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+function statusMark(status) {
+    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, write = stderr) {
+    for (const componentResult of result.results) {
+        write(`[component] ${componentResult.component}`);
+        let currentPhase;
+        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.approval) {
+                write(`      [approved] ${record.approval.resolvedBy} at ${record.approval.timestamp}` +
+                    (record.approval.url ? ` (${record.approval.url})` : ""));
+            }
+            if (record.error) {
+                write(`      ${record.error}`);
+            }
+        }
+        write(componentResult.status === "ok"
+            ? `  component "${componentResult.component}" completed`
+            : componentResult.status === "gated"
+                ? `  component "${componentResult.component}" gated on "${componentResult.gate?.gate ?? "?"}"`
+                : `  component "${componentResult.component}" failed`);
+    }
+    if (result.status === "ok") {
+        write(`interpret run completed (${result.order.length} component(s))`);
+    }
+    else if (result.status === "gated") {
+        write(`interpret run is gated at component "${result.gatedComponent}"`);
+        // #2310: this run's own append reached only the local chant/lifecycle
+        // branch. The gate still stands correctly — but an operator elsewhere
+        // cannot see the pending fact to approve it.
+        if (result.gatePushed === false && isLifecycleLocalNote(result.gatePushWarning)) {
+            write(`  note    : ${LIFECYCLE_LOCAL_NOTE}`);
+        }
+        else if (result.gatePushed === false) {
+            write(`  warning : the pending fact was not pushed to the remote — ` +
+                (result.gatePushWarning ?? "it exists only in this checkout") +
+                `. An operator elsewhere cannot approve it until it does.`);
+        }
+    }
+    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, write = stdout) {
+    write(JSON.stringify(result));
+}