@contentful/experience-design-system-cli 2.14.2 → 2.15.0

package/dist/src/analyze/composition/agent-parser/resolve-via-parser.d.ts

@@ -0,0 +1,46 @@
+import type { CompositionEdge } from '../interchange-schema.js';
+export type ResolveViaParserResult = {
+    edges: CompositionEdge[];
+    warnings: string[];
+    /** True when authoring/execution failed and the caller should fall back to
+     *  direct edge-emission (or no composition). */
+    usedFallback: boolean;
+    /** The authored parser source, when one ran successfully (for caching). */
+    parserSource?: string;
+};
+/**
+ * Agent-authored parser path (spec: agent-authored-parser, Phase 2).
+ *
+ * Ask the agent to WRITE a pure `(ctx) => Edge[]` parser, run it in the
+ * sandbox, and verify its edges against the component name set. One repair
+ * round if the authored parser fails to run; otherwise signal fallback. The
+ * agent call is injected so this is testable without spawning a subprocess.
+ */
+export declare function resolveViaAgentParser(input: {
+    /** Files inlined into the authoring prompt — a bounded candidate sample so
+     *  the agent sees the convention without ingesting the whole repo. */
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Files the authored parser actually RUNS over in the sandbox. Defaults to
+     *  `files`; pass the full scanned set here so the parser is never starved by
+     *  the prompt-side candidate filter (the filter stops being load-bearing). */
+    runtimeFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    componentNames: Set<string>;
+    runAgentFn: (opts: {
+        prompt: string;
+    }) => Promise<string>;
+    instructionOverride?: string;
+    onPhase?: (phase: string) => void;
+    timeoutMs?: number;
+    /** When true, a parser that runs cleanly but emits ZERO verified edges is
+     *  treated as suspicious (the candidate files contain composition markers, so
+     *  0 edges usually means a broken parser, not a genuinely flat repo) and gets
+     *  one repair round. Off by default so genuinely-empty repos don't pay a
+     *  wasted retry. The caller sets it from marker presence in the candidates. */
+    retryOnEmpty?: boolean;
+}): Promise<ResolveViaParserResult>;

package/dist/src/analyze/composition/agent-parser/resolve-via-parser.js

@@ -0,0 +1,88 @@
+import { buildAuthorPrompt } from './author-prompt.js';
+import { extractParserSource } from './extract-parser.js';
+import { runParserInSandbox } from './sandbox.js';
+import { loadPrompt } from './load-prompt.js';
+/**
+ * Agent-authored parser path (spec: agent-authored-parser, Phase 2).
+ *
+ * Ask the agent to WRITE a pure `(ctx) => Edge[]` parser, run it in the
+ * sandbox, and verify its edges against the component name set. One repair
+ * round if the authored parser fails to run; otherwise signal fallback. The
+ * agent call is injected so this is testable without spawning a subprocess.
+ */
+export async function resolveViaAgentParser(input) {
+    const warnings = [];
+    const componentNamesArr = [...input.componentNames];
+    const ctx = { files: input.runtimeFiles ?? input.files, componentNames: componentNamesArr };
+    const verify = (edges) => {
+        const out = [];
+        for (const e of edges) {
+            // A component cannot be its own composite parent. Self-edges are a common
+            // parser bug (matching a component's own name in its own source) and, left
+            // in, masquerade as one-node cycles downstream.
+            if (e.parent === e.child) {
+                warnings.push(`parser edge dropped: self-edge "${e.parent}→${e.child}"`);
+                continue;
+            }
+            if (!input.componentNames.has(e.parent)) {
+                warnings.push(`parser edge dropped: unknown parent "${e.parent}" (${e.parent}→${e.child})`);
+                continue;
+            }
+            if (!input.componentNames.has(e.child)) {
+                warnings.push(`parser edge dropped: unknown child "${e.child}" (${e.parent}→${e.child})`);
+                continue;
+            }
+            out.push(e);
+        }
+        return out;
+    };
+    // Attempt: author → extract → sandbox. Returns null on a fallback-worthy miss.
+    const attempt = async (prompt) => {
+        input.onPhase?.('authoring');
+        const raw = await input.runAgentFn({ prompt });
+        const source = extractParserSource(raw);
+        if (source === null)
+            return { error: 'agent output had no parser-shaped code block (expected `export default function (ctx) {…}`)' };
+        input.onPhase?.('parsing');
+        const res = await runParserInSandbox(source, ctx, input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {});
+        if (res.error)
+            return { error: res.error };
+        return { edges: res.edges, source };
+    };
+    const basePrompt = buildAuthorPrompt(input.files, componentNamesArr, input.instructionOverride);
+    const first = await attempt(basePrompt);
+    if ('edges' in first) {
+        const verified = verify(first.edges);
+        // Suspiciously-empty guard: a parser that ran cleanly but emitted no usable
+        // edges, when the candidates DO contain composition markers, is almost
+        // always broken (wrong parent attribution, wrong pattern). Give it one
+        // repair round rather than silently returning nothing.
+        if (verified.length > 0 || !input.retryOnEmpty) {
+            return { edges: verified, warnings, usedFallback: false, parserSource: first.source };
+        }
+        warnings.push('parser produced 0 usable edges despite composition markers — retrying once');
+        const emptyRepairPrompt = `${basePrompt}\n\n${loadPrompt('composition-parser-repair-empty.md').trim()}`;
+        const retry = await attempt(emptyRepairPrompt);
+        if ('edges' in retry) {
+            const retried = verify(retry.edges);
+            // Prefer the retry when it found something; otherwise keep the first
+            // parser (it at least ran) rather than discarding a working artifact.
+            if (retried.length > 0) {
+                return { edges: retried, warnings, usedFallback: false, parserSource: retry.source };
+            }
+            warnings.push('repair still produced 0 edges — keeping the original parser');
+            return { edges: verified, warnings, usedFallback: false, parserSource: first.source };
+        }
+        warnings.push(`repair attempt failed: ${retry.error} — keeping the original (empty) parser`);
+        return { edges: verified, warnings, usedFallback: false, parserSource: first.source };
+    }
+    // One repair round — tell the agent what went wrong and try again.
+    warnings.push(`parser attempt failed: ${first.error} — retrying once`);
+    const repairPrompt = `${basePrompt}\n\n${loadPrompt('composition-parser-repair-error.md').trim().replace('{{error}}', first.error)}`;
+    const second = await attempt(repairPrompt);
+    if ('edges' in second) {
+        return { edges: verify(second.edges), warnings, usedFallback: false, parserSource: second.source };
+    }
+    warnings.push(`parser attempt failed again: ${second.error} — falling back`);
+    return { edges: [], warnings, usedFallback: true };
+}

package/dist/src/analyze/composition/agent-parser/sandbox.d.ts

@@ -0,0 +1,45 @@
+import type { CompositionEdge } from '../interchange-schema.js';
+export type SandboxCtx = {
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    componentNames: string[];
+};
+export type SandboxResult = {
+    edges: CompositionEdge[];
+    error?: string;
+};
+/**
+ * Execute agent-authored parser source under three nested jails (spec:
+ * dsi-agent-authored-parser-design, Phase 1 — the security core).
+ *
+ * OUTER — a throwaway child `node` process: `env: {}` (no secrets/tokens leak
+ * even on a full escape), a heap cap (`--max-old-space-size`, OOM self-kills),
+ * and a wall-clock `SIGKILL` the parent enforces for any hang (sync or async).
+ *
+ * PERMISSION — the child runs with `--permission` and NO `--allow-fs-*`, so
+ * the Node runtime denies filesystem access, child_process spawning, worker
+ * creation, and native addons (ERR_ACCESS_DENIED). The parser needs none —
+ * its files arrive via stdin as ctx — so even a vm escape reaching
+ * `require('node:fs')`/`child_process` is stopped at the runtime layer.
+ *
+ * INNER — a `node:vm` context created from a null-prototype object, an
+ * ALLOW-LIST: it has only ECMAScript intrinsics (Object/Array/JSON/Math/RegExp
+ * …). There is no `process`, `require`, `Buffer`, `fetch`, timers, or module
+ * loader in scope, so the parser cannot reach them — and only STRINGS cross
+ * the boundary (source + JSON-encoded ctx), so there is no host-object handle
+ * for the classic `this.constructor.constructor('return process')()` escape to
+ * climb. `vm.runInContext(..., { timeout })` kills sync infinite loops.
+ *
+ * The parser must be SYNCHRONOUS — an async/thenable return is rejected, which
+ * closes the async-timeout gap (vm `timeout` covers sync execution only).
+ *
+ * Any failure — throw, timeout, OOM, denied access, bad/async return, compile
+ * error — resolves to `{ edges: [], error }` and is NEVER thrown. Returned
+ * edges are shape-validated here; the caller still re-verifies parent/child
+ * against the component name set.
+ */
+export declare function runParserInSandbox(source: string, ctx: SandboxCtx, opts?: {
+    timeoutMs?: number;
+}): Promise<SandboxResult>;

package/dist/src/analyze/composition/agent-parser/sandbox.js

@@ -0,0 +1,187 @@
+import { spawn } from 'node:child_process';
+const DEFAULT_TIMEOUT_MS = 5000;
+const HEAP_CAP_MB = 128;
+const MAX_INPUT_BYTES = 8 * 1024 * 1024; // refuse absurd ctx up front
+/**
+ * Execute agent-authored parser source under three nested jails (spec:
+ * dsi-agent-authored-parser-design, Phase 1 — the security core).
+ *
+ * OUTER — a throwaway child `node` process: `env: {}` (no secrets/tokens leak
+ * even on a full escape), a heap cap (`--max-old-space-size`, OOM self-kills),
+ * and a wall-clock `SIGKILL` the parent enforces for any hang (sync or async).
+ *
+ * PERMISSION — the child runs with `--permission` and NO `--allow-fs-*`, so
+ * the Node runtime denies filesystem access, child_process spawning, worker
+ * creation, and native addons (ERR_ACCESS_DENIED). The parser needs none —
+ * its files arrive via stdin as ctx — so even a vm escape reaching
+ * `require('node:fs')`/`child_process` is stopped at the runtime layer.
+ *
+ * INNER — a `node:vm` context created from a null-prototype object, an
+ * ALLOW-LIST: it has only ECMAScript intrinsics (Object/Array/JSON/Math/RegExp
+ * …). There is no `process`, `require`, `Buffer`, `fetch`, timers, or module
+ * loader in scope, so the parser cannot reach them — and only STRINGS cross
+ * the boundary (source + JSON-encoded ctx), so there is no host-object handle
+ * for the classic `this.constructor.constructor('return process')()` escape to
+ * climb. `vm.runInContext(..., { timeout })` kills sync infinite loops.
+ *
+ * The parser must be SYNCHRONOUS — an async/thenable return is rejected, which
+ * closes the async-timeout gap (vm `timeout` covers sync execution only).
+ *
+ * Any failure — throw, timeout, OOM, denied access, bad/async return, compile
+ * error — resolves to `{ edges: [], error }` and is NEVER thrown. Returned
+ * edges are shape-validated here; the caller still re-verifies parent/child
+ * against the component name set.
+ */
+export function runParserInSandbox(source, ctx, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let input;
+        try {
+            input = JSON.stringify({ source, ctx, timeoutMs });
+        }
+        catch {
+            resolve({ edges: [], error: 'ctx is not serializable' });
+            return;
+        }
+        if (input.length > MAX_INPUT_BYTES) {
+            resolve({ edges: [], error: 'parser input exceeds size limit' });
+            return;
+        }
+        let settled = false;
+        let stdout = '';
+        let stderr = '';
+        const child = spawn(process.execPath, [
+            // Node Permission Model (Node ≥20/24): deny fs, child_process, worker,
+            // and native addons at the RUNTIME level. We pass NO --allow-fs-* — the
+            // parser needs no disk access (its files arrive via stdin as ctx), so
+            // even if the vm allow-list were escaped and `require('node:fs')` were
+            // reached, reads are denied (ERR_ACCESS_DENIED) and spawning is denied
+            // by default. Third jail layer beneath process-isolation + vm.
+            '--permission',
+            `--max-old-space-size=${HEAP_CAP_MB}`,
+            '--input-type=module',
+            '-e',
+            RUNNER,
+        ], 
+        // No inherited env (secrets stay out of the jail), neutral cwd, no argv.
+        { env: {}, cwd: process.cwd(), stdio: ['pipe', 'pipe', 'pipe'] });
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+            resolve(r);
+        };
+        // Wall-clock backstop (covers async hangs the vm timeout can't). Grace over
+        // the inner timeout so the vm-level error is preferred when it fires first.
+        const timer = setTimeout(() => done({ edges: [], error: `parser timed out after ${timeoutMs}ms` }), timeoutMs + 1000);
+        child.stdout.on('data', (c) => {
+            stdout += String(c);
+        });
+        child.stderr.on('data', (c) => {
+            stderr += String(c);
+        });
+        child.on('error', (e) => done({ edges: [], error: `sandbox spawn failed: ${e.message}` }));
+        child.on('close', (code, signal) => {
+            if (settled)
+                return;
+            if (signal === 'SIGKILL') {
+                done({ edges: [], error: 'parser killed (timeout or memory limit)' });
+                return;
+            }
+            let msg;
+            try {
+                msg = JSON.parse(stdout);
+            }
+            catch {
+                done({
+                    edges: [],
+                    error: `sandbox produced no result (code ${code})${stderr ? `: ${stderr.slice(0, 200)}` : ''}`,
+                });
+                return;
+            }
+            if (msg.ok)
+                done({ edges: sanitizeEdges(msg.edges) });
+            else
+                done({ edges: [], error: msg.error ?? 'parser failed' });
+        });
+        try {
+            child.stdin.on('error', () => { });
+            child.stdin.write(input);
+            child.stdin.end();
+        }
+        catch {
+            done({ edges: [], error: 'failed to send input to sandbox' });
+        }
+    });
+}
+/** Keep only well-formed edges: parent+child non-empty strings. */
+function sanitizeEdges(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const e of raw) {
+        if (!e || typeof e !== 'object')
+            continue;
+        const rec = e;
+        if (typeof rec.parent !== 'string' || rec.parent === '')
+            continue;
+        if (typeof rec.child !== 'string' || rec.child === '')
+            continue;
+        const edge = { parent: rec.parent, child: rec.child, provenance: 'adapter:agent-parser' };
+        if (typeof rec.slot === 'string' && rec.slot !== '')
+            edge.slot = rec.slot;
+        if (typeof rec.confidence === 'number' && rec.confidence >= 1 && rec.confidence <= 5)
+            edge.confidence = rec.confidence;
+        out.push(edge);
+    }
+    return out;
+}
+/**
+ * Child-process runner (trusted — OUR code). Reads {source, ctx, timeoutMs}
+ * from stdin, runs the parser inside a vm allow-list context, writes a single
+ * JSON result to stdout. Only strings enter the vm; only a JSON string leaves.
+ */
+const RUNNER = `
+import vm from 'node:vm';
+let input = '';
+process.stdin.on('data', (c) => (input += c));
+process.stdin.on('end', () => {
+  let out;
+  try {
+    const { source, ctx, timeoutMs } = JSON.parse(input);
+    // Null-prototype global: no inherited host props. The context still gets
+    // ECMAScript intrinsics (Object/Array/JSON/Function/Math/RegExp), but NOT
+    // process/require/Buffer/timers/module.
+    const context = vm.createContext(Object.create(null));
+    // Cross the boundary as PRIMITIVES only — no host object/function handle
+    // for a prototype-chain escape to grab.
+    context.__source = String(source);
+    context.__ctxJson = JSON.stringify(ctx);
+    const bootstrap = [
+      '(function () {',
+      '  var ctx = JSON.parse(__ctxJson);',
+      "  var body = String(__source).replace(/export\\\\s+default\\\\s+/, 'return ');",
+      '  var factory = Function(body);',          // the vm context's own Function
+      '  var parser = factory();',
+      "  if (typeof parser !== 'function') return JSON.stringify({ ok: false, error: 'parser source did not resolve to a function' });",
+      '  var result = parser(ctx);',
+      "  if (result && typeof result.then === 'function') return JSON.stringify({ ok: false, error: 'parser must be synchronous' });",
+      "  if (!Array.isArray(result)) return JSON.stringify({ ok: false, error: 'parser did not return an array' });",
+      '  return JSON.stringify({ ok: true, edges: result });',
+      '})()',
+    ].join('\\n');
+    out = vm.runInContext(bootstrap, context, { timeout: timeoutMs });
+  } catch (e) {
+    out = JSON.stringify({ ok: false, error: String(e && e.message ? e.message : e) });
+  }
+  try { process.stdout.write(typeof out === 'string' ? out : JSON.stringify({ ok: false, error: 'no result' })); }
+  catch { process.stdout.write(JSON.stringify({ ok: false, error: 'result not serializable' })); }
+});
+`;

package/dist/src/analyze/composition/apply-mapping.d.ts

@@ -0,0 +1,22 @@
+import type { RawComponentDefinition } from '../../types.js';
+import type { CompositionEdge } from './interchange-schema.js';
+export type ApplyMappingResult = {
+    components: RawComponentDefinition[];
+    warnings: string[];
+};
+/**
+ * Enrichment pass (spec T7): merge a resolved composition edge list into the
+ * extracted components' `allowedComponents`. Runs AFTER extraction; it is the
+ * mapping resolver's entire job — populating the one field every downstream
+ * graph consumer reads.
+ *
+ * Slot targeting:
+ *  - edge.slot present + slot exists → write there.
+ *  - edge.slot present + slot missing → synthesize for high-trust
+ *    (typed-slot / adapter) edges; drop-and-warn for `agent` edges.
+ *  - edge.slot absent → default slot (isDefault), synthesized if none exists.
+ *
+ * Edges naming unknown parents/children are dropped-and-warned (§1.3). Inputs
+ * are not mutated; a deep-enough clone of touched slots is returned.
+ */
+export declare function applyMapping(components: RawComponentDefinition[], edges: CompositionEdge[]): ApplyMappingResult;

package/dist/src/analyze/composition/apply-mapping.js

@@ -0,0 +1,67 @@
+/**
+ * Enrichment pass (spec T7): merge a resolved composition edge list into the
+ * extracted components' `allowedComponents`. Runs AFTER extraction; it is the
+ * mapping resolver's entire job — populating the one field every downstream
+ * graph consumer reads.
+ *
+ * Slot targeting:
+ *  - edge.slot present + slot exists → write there.
+ *  - edge.slot present + slot missing → synthesize for high-trust
+ *    (typed-slot / adapter) edges; drop-and-warn for `agent` edges.
+ *  - edge.slot absent → default slot (isDefault), synthesized if none exists.
+ *
+ * Edges naming unknown parents/children are dropped-and-warned (§1.3). Inputs
+ * are not mutated; a deep-enough clone of touched slots is returned.
+ */
+export function applyMapping(components, edges) {
+    const warnings = [];
+    const names = new Set(components.map((c) => c.name));
+    // Clone components (and their slots) so inputs stay untouched.
+    const cloned = components.map((c) => ({
+        ...c,
+        slots: c.slots.map((s) => ({
+            ...s,
+            ...(s.allowedComponents ? { allowedComponents: [...s.allowedComponents] } : {}),
+        })),
+    }));
+    const byName = new Map(cloned.map((c) => [c.name, c]));
+    const isHighTrust = (p) => p === 'user' || p === 'typed-slot' || p.startsWith('adapter:');
+    const addAllowed = (slot, child) => {
+        const set = new Set(slot.allowedComponents ?? []);
+        set.add(child);
+        slot.allowedComponents = [...set];
+    };
+    for (const edge of edges) {
+        if (!names.has(edge.parent)) {
+            warnings.push(`dropped edge: unknown parent component "${edge.parent}" (${edge.parent}→${edge.child})`);
+            continue;
+        }
+        if (!names.has(edge.child)) {
+            warnings.push(`dropped edge: unknown child component "${edge.child}" (${edge.parent}→${edge.child})`);
+            continue;
+        }
+        const parent = byName.get(edge.parent);
+        if (edge.slot) {
+            const named = parent.slots.find((s) => s.name === edge.slot);
+            if (named) {
+                addAllowed(named, edge.child);
+                continue;
+            }
+            if (isHighTrust(edge.provenance)) {
+                const synthesized = { name: edge.slot, isDefault: false, allowedComponents: [edge.child] };
+                parent.slots.push(synthesized);
+                continue;
+            }
+            warnings.push(`dropped edge: slot "${edge.slot}" not found on "${edge.parent}" (agent-provenance; ${edge.parent}→${edge.child})`);
+            continue;
+        }
+        // Default slot.
+        let def = parent.slots.find((s) => s.isDefault);
+        if (!def) {
+            def = { name: 'children', isDefault: true, allowedComponents: [] };
+            parent.slots.push(def);
+        }
+        addAllowed(def, edge.child);
+    }
+    return { components: cloned, warnings };
+}

package/dist/src/analyze/composition/candidate-critic-agent.d.ts

@@ -0,0 +1,7 @@
+export declare function buildDirCriticPrompt(dirs: string[]): string;
+/**
+ * Parse the agent's reply into the chosen directories, keeping only ones that
+ * were offered (no injection). Lenient: extracts the first JSON array from
+ * surrounding prose; malformed / absent → [].
+ */
+export declare function parseDirCriticReply(reply: string, offered: string[]): string[];

package/dist/src/analyze/composition/candidate-critic-agent.js

@@ -0,0 +1,39 @@
+/**
+ * Prompt + reply parser for the directory completeness critic. Cheap: the
+ * agent sees only directory NAMES (no file contents) and returns which look
+ * like they might hold composition/mapping declarations.
+ */
+import { loadPrompt } from './agent-parser/load-prompt.js';
+export function buildDirCriticPrompt(dirs) {
+    return [loadPrompt('composition-dir-critic.md').trim(), '', 'Directories:', ...dirs.map((d) => `- ${d}`)].join('\n');
+}
+/**
+ * Parse the agent's reply into the chosen directories, keeping only ones that
+ * were offered (no injection). Lenient: extracts the first JSON array from
+ * surrounding prose; malformed / absent → [].
+ */
+export function parseDirCriticReply(reply, offered) {
+    const start = reply.indexOf('[');
+    const end = reply.indexOf(']', start);
+    if (start === -1 || end === -1)
+        return [];
+    let arr;
+    try {
+        arr = JSON.parse(reply.slice(start, end + 1));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(arr))
+        return [];
+    const offeredSet = new Set(offered);
+    const out = [];
+    const seen = new Set();
+    for (const v of arr) {
+        if (typeof v === 'string' && offeredSet.has(v) && !seen.has(v)) {
+            seen.add(v);
+            out.push(v);
+        }
+    }
+    return out;
+}

package/dist/src/analyze/composition/candidate-critic.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Completeness critic for the candidate-file filter (design: the heuristic can
+ * miss a composition-layer directory whose name we didn't anticipate). We show
+ * the agent the DIRECTORIES it did NOT pick — names only, no file contents, so
+ * it's cheap — and let it flag ones that look promising from the path alone.
+ * Flagged dirs' files are folded into the prompt sample.
+ *
+ * This only widens the AUTHORING-PROMPT sample; the parser already runs over
+ * every file at runtime, so this is purely "help the agent see the convention",
+ * never a correctness dependency.
+ */
+type FileLike = {
+    path: string;
+    content: string;
+};
+/** Directories present in `all` but with no file in `selected`, sorted+deduped. */
+export declare function uncoveredDirectories(all: FileLike[], selected: FileLike[]): string[];
+/** Union `selected` with every `all` file whose directory is in `chosenDirs`. */
+export declare function expandCandidatesByDirs(all: FileLike[], selected: FileLike[], chosenDirs: string[]): FileLike[];
+export type CritiqueResult = {
+    files: FileLike[];
+    addedDirs: string[];
+};
+/**
+ * Run the completeness critic. `askDirs` receives the uncovered directory names
+ * and returns the subset the agent judges composition-relevant. We only honor
+ * dirs that were actually offered (no injection), and any error from the agent
+ * falls back to the original selection — the critic can only ever ADD, never
+ * break resolution.
+ */
+export declare function critiqueCandidates(all: FileLike[], selected: FileLike[], askDirs: (dirs: string[]) => Promise<string[]>): Promise<CritiqueResult>;
+export {};

package/dist/src/analyze/composition/candidate-critic.js

@@ -0,0 +1,63 @@
+/**
+ * Completeness critic for the candidate-file filter (design: the heuristic can
+ * miss a composition-layer directory whose name we didn't anticipate). We show
+ * the agent the DIRECTORIES it did NOT pick — names only, no file contents, so
+ * it's cheap — and let it flag ones that look promising from the path alone.
+ * Flagged dirs' files are folded into the prompt sample.
+ *
+ * This only widens the AUTHORING-PROMPT sample; the parser already runs over
+ * every file at runtime, so this is purely "help the agent see the convention",
+ * never a correctness dependency.
+ */
+function dirOf(path) {
+    const i = path.lastIndexOf('/');
+    return i === -1 ? '' : path.slice(0, i);
+}
+/** Directories present in `all` but with no file in `selected`, sorted+deduped. */
+export function uncoveredDirectories(all, selected) {
+    const coveredDirs = new Set(selected.map((f) => dirOf(f.path)));
+    const out = new Set();
+    for (const f of all) {
+        const d = dirOf(f.path);
+        if (d !== '' && !coveredDirs.has(d))
+            out.add(d);
+    }
+    return [...out].sort();
+}
+/** Union `selected` with every `all` file whose directory is in `chosenDirs`. */
+export function expandCandidatesByDirs(all, selected, chosenDirs) {
+    const chosen = new Set(chosenDirs);
+    const seen = new Set(selected.map((f) => f.path));
+    const out = [...selected];
+    for (const f of all) {
+        if (chosen.has(dirOf(f.path)) && !seen.has(f.path)) {
+            seen.add(f.path);
+            out.push(f);
+        }
+    }
+    return out;
+}
+/**
+ * Run the completeness critic. `askDirs` receives the uncovered directory names
+ * and returns the subset the agent judges composition-relevant. We only honor
+ * dirs that were actually offered (no injection), and any error from the agent
+ * falls back to the original selection — the critic can only ever ADD, never
+ * break resolution.
+ */
+export async function critiqueCandidates(all, selected, askDirs) {
+    const uncovered = uncoveredDirectories(all, selected);
+    if (uncovered.length === 0)
+        return { files: selected, addedDirs: [] };
+    let chosen;
+    try {
+        chosen = await askDirs(uncovered);
+    }
+    catch {
+        return { files: selected, addedDirs: [] };
+    }
+    const offered = new Set(uncovered);
+    const addedDirs = [...new Set(chosen)].filter((d) => offered.has(d)).sort();
+    if (addedDirs.length === 0)
+        return { files: selected, addedDirs: [] };
+    return { files: expandCandidatesByDirs(all, selected, addedDirs), addedDirs };
+}

package/dist/src/analyze/composition/candidate-files.d.ts

@@ -0,0 +1,34 @@
+export declare const CANDIDATE_NAME_PATTERNS: RegExp[];
+export declare const CANDIDATE_CONTENT_MARKERS: string[];
+export declare const CANDIDATE_TOKEN_BUDGET = 6000;
+/**
+ * Token ceiling for the candidate set INLINED into a single agent prompt.
+ * Sized to stay under a 200k-context model once the agent's own system prompt
+ * + tool definitions (~105k observed) are added, so a large design system
+ * (hundreds of components → many matched files) can't overflow the request and
+ * fail resolution. Files beyond the budget are dropped (with a warning), not
+ * silently truncated. Distinct from `CANDIDATE_TOKEN_BUDGET`, which sizes the
+ * unused per-batch chunking.
+ */
+export declare const PROMPT_CANDIDATE_TOKEN_BUDGET = 80000;
+export type CandidateFile = {
+    path: string;
+    content: string;
+};
+export type SelectedCandidate = CandidateFile & {
+    reason: string;
+};
+export declare function selectCandidateFiles(files: CandidateFile[]): SelectedCandidate[];
+/**
+ * Cap a candidate set to what fits in a single agent prompt (see
+ * `PROMPT_CANDIDATE_TOKEN_BUDGET`). Files are kept smallest-first so the budget
+ * admits the most declarations; deterministic tie-break by path. Returns the
+ * kept files plus the paths dropped so the caller can warn (silent truncation
+ * would read as "resolved everything" when it didn't).
+ */
+export declare function capCandidatesToPromptBudget<T extends CandidateFile>(files: T[], budget?: number): {
+    kept: T[];
+    dropped: T[];
+};
+export declare function sliceDeclarationRegions(content: string, markers?: string[], window?: number): string[];
+export declare function batchCandidates(files: CandidateFile[], budget?: number): CandidateFile[][];