vigiles 5.2.0 → 6.0.0

package/dist/core/generate-harness.js

@@ -0,0 +1,337 @@
+"use strict";
+/**
+ * vigiles generate-harness — emit ONE typed registry over the whole harness.
+ *
+ * The third generated artifact beside `generate-types` (`.d.ts`) and
+ * `generate-schema` (JSON Schema): a `harness.gen.ts` that imports every
+ * `*.spec.ts` in a directory, folds the agents into a `registry`, and asserts
+ * the cross-spec invariants at the TYPE level — so a single `tsc --noEmit`
+ * checks the WHOLE harness as one program (think TanStack's `routeTree.gen.ts`).
+ * See research/whole-harness-codegen.md for the design + the measured perf.
+ *
+ * The shipped scope (the first increment):
+ *  1. DANGLING `delegate` → a `tsc` error. Each `railway()` delegate target is a
+ *     name the generator reads at codegen time; the gen file emits one shallow
+ *     per-edge assertion (`KnownAgentName<"target", AgentName>` — O(N), no
+ *     recursion) that the target resolves to a real agent, else a `tsc` error
+ *     naming the dangling target + its railway.
+ *  2. DUPLICATE agent/skill NAMES → a generator error (this module returns a
+ *     `duplicate` diagnostic; the CLI exits non-zero). This is the O(N) JS check
+ *     the encoding rule mandates — a set-uniqueness MAPPED TYPE is the TS2589
+ *     wall (measured ≈ N=1000), so duplicates are NEVER a type.
+ *  3. The whole-harness CAPABILITY LATTICE: the UNION of every agent's
+ *     `effectSurface(tools, dialect)` — a generator-computed value + type, the
+ *     substrate the future repo-scale capability-diff reads.
+ *  4. CROSS-FILE TYPED COMPOSITION: when a `railway()` success-track step declares
+ *     what it `needs()`, the gen file emits one shallow per-pair assertion
+ *     (`Handoff<OkOf<typeof registry[producer]>, needs>` — O(N), no recursion)
+ *     that the PRIOR step's `result().ok` SUPPLIES it, so a cross-file handoff
+ *     mismatch (a missing field / wrong type) is a `tsc` error naming the field.
+ *     The repo-scale generalization of the per-file `pipe`/`Supplies` composition.
+ *     Scoped to the linear success track; recover/onError (which consume an `err`,
+ *     not the prior `ok`) are a noted follow-up.
+ *
+ * Harness-agnostic: the `dialect` (for the capability lattice) is INJECTED by
+ * the composition root (the CLI), never hard-coded — mirroring `compileAgent` /
+ * `scanPlugin`. The core stays free of any Claude-Code literal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HARNESS_GEN_FILENAME = void 0;
+exports.computeHarnessCapabilities = computeHarnessCapabilities;
+exports.findDuplicateName = findDuplicateName;
+exports.generateHarness = generateHarness;
+exports.findHarnessSpecFiles = findHarnessSpecFiles;
+exports.loadHarnessModel = loadHarnessModel;
+exports.labelFor = labelFor;
+exports.readSpecSource = readSpecSource;
+exports.genOutDir = genOutDir;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const effects_js_1 = require("./effects.js");
+// ---------------------------------------------------------------------------
+// Capability lattice — the O(N) union over every agent's effect surface
+// ---------------------------------------------------------------------------
+/** Rank the purity rungs so the harness purity is the LOOSEST agent's. */
+const PURITY_RANK = {
+    pure: 0,
+    bounded: 1,
+    unrestricted: 2,
+};
+/**
+ * Fold every agent's `effectSurface` into one harness-wide lattice: the union of
+ * each bucket and the loosest purity. An agent with no `tools` inherits all (a
+ * wildcard), so its surface is `unrestricted` — handled by `effectSurface` when
+ * we pass `["*"]`. O(N) over the agents; the per-agent legs are fixed-arity.
+ */
+function computeHarnessCapabilities(agents, dialect) {
+    const readOnly = new Set();
+    const sideEffecting = new Set();
+    const unknown = new Set();
+    let purityRank = 0;
+    for (const a of agents) {
+        // No `tools` line means inherits-all → a wildcard surface (unrestricted).
+        const tools = a.tools && a.tools.length > 0 ? a.tools : ["*"];
+        const surface = (0, effects_js_1.effectSurface)(tools, dialect);
+        for (const t of surface.readOnly)
+            readOnly.add(t);
+        for (const t of surface.sideEffecting)
+            sideEffecting.add(t);
+        for (const t of surface.unknown)
+            unknown.add(t);
+        purityRank = Math.max(purityRank, PURITY_RANK[surface.purity]);
+    }
+    const PURITY_BY_RANK = [
+        "pure",
+        "bounded",
+        "unrestricted",
+    ];
+    const purity = PURITY_BY_RANK[purityRank];
+    return {
+        readOnly: [...readOnly].sort(),
+        sideEffecting: [...sideEffecting].sort(),
+        unknown: [...unknown].sort(),
+        purity,
+    };
+}
+// ---------------------------------------------------------------------------
+// Duplicate-name detection — the O(N) JS check (NOT a type; the TS2589-safe path)
+// ---------------------------------------------------------------------------
+/**
+ * Find the FIRST pair of agents that declare the same `name`. O(N) over the
+ * agents — the set-cardinality check the encoding rule says must live in the JS
+ * generator, never as an N×N mapped type (the measured TS2589 wall). Returns
+ * `undefined` when names are unique.
+ */
+function findDuplicateName(agents) {
+    const seen = new Map();
+    for (const a of agents) {
+        const prior = seen.get(a.name);
+        if (prior !== undefined) {
+            return {
+                name: a.name,
+                first: prior,
+                second: a.file,
+                message: `duplicate agent name "${a.name}" — declared in both ${prior} and ${a.file}`,
+            };
+        }
+        seen.set(a.name, a.file);
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Emission — the pure core (string in, string out, fully testable, no fs read)
+// ---------------------------------------------------------------------------
+/** A valid TS identifier derived from a registry key (for the import binding). */
+function identFor(key) {
+    const safe = key.replace(/[^A-Za-z0-9_]/g, "_");
+    return /^[A-Za-z_]/.test(safe) ? safe : `_${safe}`;
+}
+/** Relativize an import path against the gen file's directory (POSIX `./…`). */
+function relImport(fromDir, toFile) {
+    let r = (0, node_path_1.relative)(fromDir, toFile).replace(/\\/g, "/");
+    if (!r.startsWith("."))
+        r = "./" + r;
+    return r;
+}
+/**
+ * Emit the cross-file handoff assertions. For each consecutive success-track
+ * pair whose CONSUMER declares `needs`, read the PRODUCER's `result().ok` off
+ * the registry (`OkOf<typeof registry[from]>`) and assert `Handoff<producerOk,
+ * needs>` is `true`. A missing field / wrong type collapses it to
+ * `{ __handoff_error: … }`, so `= true` is a tsc error naming the field — across
+ * files, at edit time. One shallow assertion per pair (O(N), no recursion).
+ */
+function handoffCheckLines(handoffs) {
+    const L = [
+        "// CHECK: every declared handoff lines up — the producer's result().ok",
+        "// must SUPPLY the consumer's needs. A mismatch makes `Handoff<…>` a",
+        "// `{ __handoff_error: … }` object, so `= true` is a tsc error naming the field.",
+    ];
+    handoffs.forEach((h, i) => {
+        const needsLiteral = `{ ${Object.entries(h.needs)
+            .map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`)
+            .join("; ")} }`;
+        L.push(`const _handoff_${String(i)}: Handoff<OkOf<typeof registry[${JSON.stringify(h.from)}]>, ${needsLiteral}> = true;`);
+        L.push(`void _handoff_${String(i)}; // ${h.railway}: ${h.from} → ${h.to}`);
+    });
+    L.push("");
+    return L;
+}
+/**
+ * Generate the `harness.gen.ts` source over an already-loaded `HarnessModel`.
+ *
+ * Pure: no filesystem read, no spec loading — just string emission + the two
+ * O(N) computations (capability lattice + duplicate check). The fs/scan wrapper
+ * (`loadHarnessModel`) feeds this.
+ */
+function generateHarness(model, options) {
+    const { dialect, outDir } = options;
+    const specImport = options.specImport ?? "vigiles/spec";
+    // Stable order: agents sorted by name (deterministic output → clean diffs).
+    const agents = [...model.agents].sort((a, b) => a.name.localeCompare(b.name));
+    const duplicate = findDuplicateName(agents);
+    const capabilities = computeHarnessCapabilities(agents, dialect);
+    // Each agent gets a unique import binding. The registry key is the agent name.
+    const bindings = agents.map((a) => ({
+        ...a,
+        ident: identFor(a.name),
+        import: relImport(outDir, a.file),
+    }));
+    const L = [];
+    L.push("// AUTO-GENERATED by `vigiles generate-harness` — DO NOT EDIT.");
+    L.push("// One typed registry over every *.spec.ts in the harness, so a single");
+    L.push("// `tsc --noEmit` cross-checks the WHOLE harness as one program.");
+    L.push("// Regenerate with `vigiles generate-harness` (wired to a spec guard).");
+    L.push("");
+    const handoffs = model.handoffs ?? [];
+    const specTypeImports = handoffs.length > 0 ? "KnownAgentName, Handoff, OkOf" : "KnownAgentName";
+    L.push(`import type { ${specTypeImports} } from ${JSON.stringify(specImport)};`);
+    L.push("");
+    for (const b of bindings) {
+        L.push(`import ${b.ident} from ${JSON.stringify(b.import)};`);
+    }
+    L.push("");
+    // The registry record. `as const` keeps each value's precise type for the
+    // future cross-file handoff check; today the registry is keyed by agent name.
+    L.push("export const registry = {");
+    for (const b of bindings) {
+        L.push(`  ${JSON.stringify(b.name)}: ${b.ident},`);
+    }
+    L.push("} as const;");
+    L.push("");
+    // The literal union of every agent name. The generator emits this (the value's
+    // `name` field is `string`, not a literal, so the union can't be recovered
+    // from the imported type — the generator KNOWS the names, so it writes them).
+    L.push("// The literal union of every agent name in the harness — the set every");
+    L.push("// delegate target is checked against (the dangling-delegate basis).");
+    if (bindings.length === 0) {
+        L.push("export type AgentName = never;");
+    }
+    else {
+        L.push("export type AgentName =");
+        bindings.forEach((b, i) => {
+            const tail = i === bindings.length - 1 ? ";" : "";
+            L.push(`  | ${JSON.stringify(b.name)}${tail}`);
+        });
+    }
+    L.push("");
+    // ---- CHECK: dangling delegate → tsc error (one shallow assertion per edge) --
+    if (model.edges.length > 0) {
+        L.push("// CHECK: every delegate target resolves to a real agent. A dangling");
+        L.push("// target makes `KnownAgentName<target, AgentName>` a `{ __dangling_delegate }`");
+        L.push("// object, so assigning `true` to it is a tsc error naming the target.");
+        model.edges.forEach((e, i) => {
+            L.push(`const _edge_${String(i)}: KnownAgentName<${JSON.stringify(e.target)}, AgentName, ${JSON.stringify(e.from)}> = true;`);
+            L.push(`void _edge_${String(i)}; // ${e.from} → ${e.target}`);
+        });
+        L.push("");
+    }
+    // ---- CHECK: cross-file handoff → tsc error (one shallow assertion per pair) -
+    if (handoffs.length > 0)
+        L.push(...handoffCheckLines(handoffs));
+    // ---- The whole-harness capability lattice (a generator-computed value) ------
+    L.push("// The whole-harness capability lattice — the UNION of every agent's");
+    L.push("// effect surface. The substrate a repo-scale capability-diff reads.");
+    L.push("export const harnessCapabilities = {");
+    L.push(`  readOnly: ${JSON.stringify(capabilities.readOnly)},`);
+    L.push(`  sideEffecting: ${JSON.stringify(capabilities.sideEffecting)},`);
+    L.push(`  unknown: ${JSON.stringify(capabilities.unknown)},`);
+    L.push(`  purity: ${JSON.stringify(capabilities.purity)},`);
+    L.push("} as const;");
+    L.push("");
+    return {
+        gen: L.join("\n") + "\n",
+        capabilities,
+        duplicate,
+        agentCount: agents.length,
+        edgeCount: model.edges.length,
+        handoffCount: handoffs.length,
+    };
+}
+/** Discover every `*.spec.ts` directly under `dir` (non-recursive, sorted). */
+function findHarnessSpecFiles(dir) {
+    return (0, node_fs_1.readdirSync)(dir)
+        .filter((f) => f.endsWith(".spec.ts"))
+        .sort();
+}
+/**
+ * Build a `HarnessModel` from `dir`'s spec files using a caller-supplied
+ * `load(file) → value` (the CLI injects its `loadSpec`, so this stays
+ * fs/runtime-agnostic and unit-testable with fakes). Agents become registry
+ * entries; railways contribute delegate edges (steps + recover + onError).
+ */
+async function loadHarnessModel(dir, load) {
+    const files = findHarnessSpecFiles(dir);
+    const agents = [];
+    const edges = [];
+    const handoffs = [];
+    for (const file of files) {
+        const abs = `${dir}/${file}`;
+        const spec = await load(abs);
+        if (!spec)
+            continue;
+        if (spec._specType === "agent" && typeof spec.name === "string") {
+            agents.push({ name: spec.name, tools: spec.tools, file: abs });
+        }
+        else if (spec._specType === "railway" && typeof spec.name === "string") {
+            edges.push(...railwayEdges(spec.name, spec));
+            handoffs.push(...railwayHandoffs(spec.name, spec.steps ?? []));
+        }
+    }
+    return { agents, edges, handoffs };
+}
+/** The delegate edges a railway contributes (steps + recover + onError). */
+function railwayEdges(from, spec) {
+    const out = [];
+    const push = (agentName) => {
+        if (typeof agentName === "string")
+            out.push({ from, target: agentName });
+    };
+    for (const step of spec.steps ?? [])
+        push(step.agent);
+    push(spec.recover?.step?.agent);
+    push(spec.onError?.agent);
+    return out;
+}
+/**
+ * The cross-file handoff edges a railway contributes: each consecutive
+ * success-track pair whose CONSUMER declares `needs` asserts the PRODUCER (the
+ * prior step) supplies it. Scoped to the LINEAR success track — recover/onError
+ * consume an `err`, not the prior `ok`, so they are a noted follow-up.
+ */
+function railwayHandoffs(railwayName, steps) {
+    const out = [];
+    for (let i = 1; i < steps.length; i++) {
+        const producer = steps[i - 1].agent;
+        const consumer = steps[i].agent;
+        const need = steps[i].needs;
+        if (need &&
+            Object.keys(need).length > 0 &&
+            typeof producer === "string" &&
+            typeof consumer === "string") {
+            out.push({
+                railway: railwayName,
+                from: producer,
+                to: consumer,
+                needs: need,
+            });
+        }
+    }
+    return out;
+}
+/** Convenience: the gen file's basename, used by the CLI default out path. */
+exports.HARNESS_GEN_FILENAME = "harness.gen.ts";
+/** Relative label for a path under cwd (CLI-only nicety; pure). */
+function labelFor(cwd, abs) {
+    const r = (0, node_path_1.relative)(cwd, abs);
+    return r === "" ? (0, node_path_1.basename)(abs) : r;
+}
+/** Read a spec file's raw text (helper exposed for callers that need the source). */
+function readSpecSource(absFile) {
+    return (0, node_fs_1.readFileSync)(absFile, "utf-8");
+}
+/** The directory a gen file at `outFile` lives in (helper for the CLI). */
+function genOutDir(outFile) {
+    return (0, node_path_1.dirname)(outFile);
+}
+//# sourceMappingURL=generate-harness.js.map