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

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

@@ -0,0 +1,131 @@
+export const CANDIDATE_NAME_PATTERNS = [/mapping/i, /meta/i, /registry/i, /schema/i, /composition/i];
+export const CANDIDATE_CONTENT_MARKERS = [
+    'requiredParent',
+    'withParentType',
+    'allowedTagNames',
+    'createContext',
+    'MappingContext',
+    'allowedComponents',
+];
+export 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 const PROMPT_CANDIDATE_TOKEN_BUDGET = 80_000;
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_SLICE_WINDOW = 3;
+function matchReason(file) {
+    // Test the name patterns against EVERY path segment (directory names + the
+    // basename), not just the basename. A mapping-layer file that only DEFINES a
+    // component — e.g. src/mapping/call_to_action.ts, no withParentType of its
+    // own — must still be selected so the resolver can resolve OTHER files'
+    // parent references to it. Matching only the basename silently dropped these.
+    const segments = file.path.split('/').filter((s) => s !== '');
+    for (const pattern of CANDIDATE_NAME_PATTERNS) {
+        if (segments.some((seg) => pattern.test(seg))) {
+            return `name:${pattern.source.toLowerCase()}`;
+        }
+    }
+    for (const marker of CANDIDATE_CONTENT_MARKERS) {
+        if (file.content.includes(marker))
+            return `content:${marker}`;
+    }
+    return undefined;
+}
+export function selectCandidateFiles(files) {
+    const selected = [];
+    const seen = new Set();
+    for (const file of files) {
+        if (seen.has(file.path))
+            continue;
+        const reason = matchReason(file);
+        if (reason === undefined)
+            continue;
+        seen.add(file.path);
+        selected.push({ path: file.path, content: file.content, reason });
+    }
+    return selected;
+}
+/**
+ * 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 function capCandidatesToPromptBudget(files, budget = PROMPT_CANDIDATE_TOKEN_BUDGET) {
+    const ordered = [...files].sort((a, b) => a.content.length - b.content.length || a.path.localeCompare(b.path));
+    const kept = [];
+    const dropped = [];
+    let spent = 0;
+    for (const file of ordered) {
+        const cost = tokenCost(file);
+        if (spent + cost > budget) {
+            dropped.push(file);
+            continue;
+        }
+        kept.push(file);
+        spent += cost;
+    }
+    return { kept, dropped };
+}
+export function sliceDeclarationRegions(content, markers = CANDIDATE_CONTENT_MARKERS, window = DEFAULT_SLICE_WINDOW) {
+    const lines = content.split('\n');
+    const hitLines = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (markers.some((marker) => lines[i].includes(marker)))
+            hitLines.push(i);
+    }
+    if (hitLines.length === 0)
+        return [];
+    const ranges = [];
+    for (const hit of hitLines) {
+        const start = Math.max(0, hit - window);
+        const end = Math.min(lines.length - 1, hit + window);
+        const last = ranges[ranges.length - 1];
+        if (last && start <= last.end + 1) {
+            last.end = Math.max(last.end, end);
+        }
+        else {
+            ranges.push({ start, end });
+        }
+    }
+    return ranges.map((r) => lines.slice(r.start, r.end + 1).join('\n'));
+}
+function tokenCost(file) {
+    return Math.ceil(file.content.length / CHARS_PER_TOKEN);
+}
+export function batchCandidates(files, budget = CANDIDATE_TOKEN_BUDGET) {
+    const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+    const batches = [];
+    let current = [];
+    let currentCost = 0;
+    for (const file of sorted) {
+        const cost = tokenCost(file);
+        if (cost > budget) {
+            if (current.length > 0) {
+                batches.push(current);
+                current = [];
+                currentCost = 0;
+            }
+            batches.push([file]);
+            continue;
+        }
+        if (current.length > 0 && currentCost + cost > budget) {
+            batches.push(current);
+            current = [];
+            currentCost = 0;
+        }
+        current.push(file);
+        currentCost += cost;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}

package/dist/src/analyze/composition/composition-cache-key.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Derive the `input_hash` for a composition-cache entry (stored in the pipeline
+ * DB's `composition_cache` table). Content-addresses the candidate file set
+ * (order-independent) plus the producing agent and the resolution kind, so a
+ * re-run over unchanged files reuses the (token-costly) agent output.
+ *
+ * Content-hashing — not mtime — means a no-op `git checkout` that only bumps
+ * mtime is still a hit. Prompt/skill changes are handled by the `cli_version`
+ * column on the row (see `getCliCacheVersion`), so no separate resolver-version
+ * constant is needed here.
+ */
+export declare function buildCompositionInputHash(input: {
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    agent: string;
+    kind: 'parser' | 'edges';
+}): string;

package/dist/src/analyze/composition/composition-cache-key.js

@@ -0,0 +1,19 @@
+import { hashContent } from '../../session/cache-keys.js';
+/**
+ * Derive the `input_hash` for a composition-cache entry (stored in the pipeline
+ * DB's `composition_cache` table). Content-addresses the candidate file set
+ * (order-independent) plus the producing agent and the resolution kind, so a
+ * re-run over unchanged files reuses the (token-costly) agent output.
+ *
+ * Content-hashing — not mtime — means a no-op `git checkout` that only bumps
+ * mtime is still a hit. Prompt/skill changes are handled by the `cli_version`
+ * column on the row (see `getCliCacheVersion`), so no separate resolver-version
+ * constant is needed here.
+ */
+export function buildCompositionInputHash(input) {
+    const fileDigest = input.files
+        .map((f) => `${f.path} ${hashContent(f.content)}`)
+        .sort()
+        .join('');
+    return hashContent(`${input.kind}:agent:${input.agent}\n${fileDigest}`);
+}

package/dist/src/analyze/composition/interchange-schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The CLI-owned composition interchange format (spec T1).
+ *
+ * Two views of the same data:
+ *  - `InterchangeMap` — the human-authored / on-disk `{ version, groups }`
+ *    shape (parent → children). This is what `--composition-map` consumes and
+ *    `--generate-map` emits.
+ *  - `CompositionEdge[]` — the flat internal runtime view, one edge per
+ *    parent→child relationship, carrying optional `slot` (T7), `confidence`,
+ *    and `provenance`. Easier to merge/dedupe across sources (T2).
+ *
+ * This module owns both shapes and the converters between them.
+ */
+export type EdgeProvenance = 'user' | 'typed-slot' | `adapter:${string}` | 'agent';
+export type CompositionEdge = {
+    parent: string;
+    child: string;
+    /** Optional named slot (T7). Default slot when omitted. */
+    slot?: string;
+    /** 1–5 scale, same as select/reject agent tools. */
+    confidence?: number;
+    provenance: EdgeProvenance;
+};
+export type InterchangeMap = {
+    version: 1;
+    groups: Record<string, string[]>;
+};
+export type ValidateResult = {
+    valid: true;
+    map: InterchangeMap;
+} | {
+    valid: false;
+    errors: string[];
+};
+export declare function validateInterchangeMap(input: unknown): ValidateResult;
+export declare function groupsToEdges(map: InterchangeMap, provenance: EdgeProvenance): CompositionEdge[];
+export declare function edgesToGroups(edges: CompositionEdge[]): InterchangeMap;

package/dist/src/analyze/composition/interchange-schema.js

@@ -0,0 +1,61 @@
+/**
+ * The CLI-owned composition interchange format (spec T1).
+ *
+ * Two views of the same data:
+ *  - `InterchangeMap` — the human-authored / on-disk `{ version, groups }`
+ *    shape (parent → children). This is what `--composition-map` consumes and
+ *    `--generate-map` emits.
+ *  - `CompositionEdge[]` — the flat internal runtime view, one edge per
+ *    parent→child relationship, carrying optional `slot` (T7), `confidence`,
+ *    and `provenance`. Easier to merge/dedupe across sources (T2).
+ *
+ * This module owns both shapes and the converters between them.
+ */
+export function validateInterchangeMap(input) {
+    const errors = [];
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return { valid: false, errors: ['interchange map must be a JSON object'] };
+    }
+    const obj = input;
+    if (obj.version !== 1) {
+        errors.push(`unsupported interchange version: expected 1, got ${JSON.stringify(obj.version)}`);
+    }
+    if (typeof obj.groups !== 'object' || obj.groups === null || Array.isArray(obj.groups)) {
+        errors.push('interchange map must have a `groups` object');
+        return { valid: false, errors };
+    }
+    const groups = obj.groups;
+    for (const [parent, children] of Object.entries(groups)) {
+        if (!Array.isArray(children) || !children.every((c) => typeof c === 'string')) {
+            errors.push(`groups["${parent}"] must be an array of strings`);
+        }
+    }
+    if (errors.length > 0)
+        return { valid: false, errors };
+    return { valid: true, map: { version: 1, groups: groups } };
+}
+export function groupsToEdges(map, provenance) {
+    const seen = new Set();
+    const edges = [];
+    for (const [parent, children] of Object.entries(map.groups)) {
+        for (const child of children) {
+            const key = `${parent}::${child}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            edges.push({ parent, child, provenance });
+        }
+    }
+    return edges;
+}
+export function edgesToGroups(edges) {
+    const groups = {};
+    for (const { parent, child } of edges) {
+        (groups[parent] ??= new Set()).add(child);
+    }
+    const out = {};
+    for (const parent of Object.keys(groups).sort()) {
+        out[parent] = [...groups[parent]].sort();
+    }
+    return { version: 1, groups: out };
+}

package/dist/src/analyze/composition/merge-edges.d.ts

@@ -0,0 +1,19 @@
+import type { CompositionEdge, EdgeProvenance } from './interchange-schema.js';
+export type EdgeConflict = {
+    parent: string;
+    child: string;
+    winner: EdgeProvenance;
+    loser: EdgeProvenance;
+};
+export type MergeResult = {
+    edges: CompositionEdge[];
+    conflicts: EdgeConflict[];
+};
+/**
+ * Union all edges, resolving conflicts by provenance rank. A conflict is two
+ * edges that share `parent::child` but disagree on existence-detail (here:
+ * slot placement). The higher-ranked edge wins; the loser is recorded (never
+ * silently dropped) so the review UI can surface it. Identical edges (same
+ * parent/child/slot) collapse to the highest-ranked copy with no conflict.
+ */
+export declare function mergeEdges(all: CompositionEdge[]): MergeResult;

package/dist/src/analyze/composition/merge-edges.js

@@ -0,0 +1,50 @@
+/**
+ * Provenance rank (spec T2). Lower number = higher trust = wins conflicts.
+ *   1 user  >  2 typed-slot  >  3 adapter:*  >  4 agent
+ */
+function rank(p) {
+    if (p === 'user')
+        return 1;
+    if (p === 'typed-slot')
+        return 2;
+    if (p.startsWith('adapter:'))
+        return 3;
+    return 4; // agent
+}
+/**
+ * Union all edges, resolving conflicts by provenance rank. A conflict is two
+ * edges that share `parent::child` but disagree on existence-detail (here:
+ * slot placement). The higher-ranked edge wins; the loser is recorded (never
+ * silently dropped) so the review UI can surface it. Identical edges (same
+ * parent/child/slot) collapse to the highest-ranked copy with no conflict.
+ */
+export function mergeEdges(all) {
+    const byKey = new Map();
+    const conflicts = [];
+    for (const edge of all) {
+        const key = `${edge.parent}::${edge.child}`;
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, edge);
+            continue;
+        }
+        const sameSlot = (existing.slot ?? '') === (edge.slot ?? '');
+        if (sameSlot) {
+            // Identical relationship — keep the higher-ranked provenance, no conflict.
+            if (rank(edge.provenance) < rank(existing.provenance))
+                byKey.set(key, edge);
+            continue;
+        }
+        // Slot placement disagreement → conflict. Higher rank wins.
+        const winnerEdge = rank(edge.provenance) < rank(existing.provenance) ? edge : existing;
+        const loserEdge = winnerEdge === edge ? existing : edge;
+        byKey.set(key, winnerEdge);
+        conflicts.push({
+            parent: edge.parent,
+            child: edge.child,
+            winner: winnerEdge.provenance,
+            loser: loserEdge.provenance,
+        });
+    }
+    return { edges: [...byKey.values()], conflicts };
+}

package/dist/src/analyze/composition/parse-map-edges.d.ts

@@ -0,0 +1,16 @@
+import type { CompositionEdge } from './interchange-schema.js';
+/**
+ * Lenient JSONL parser for the composition-mapping agent's tool-call output
+ * (spec T4). Mirrors `parseSelectToolCallLines` / `parseToolCallLines` in
+ * `src/generate/agent-runner.ts`: one JSON object per line, each with a `tool`
+ * field from a fixed allowlist. A line that fails JSON.parse or validation is
+ * DROPPED into `warnings[]` (with a reason) and parsing CONTINUES — no retry,
+ * no throw. Non-`{` prose and blank lines are skipped silently.
+ */
+export type ParseMapEdgesResult = {
+    edges: CompositionEdge[];
+    warnings: string[];
+};
+export declare function parseMapEdges(raw: string, opts: {
+    componentNames: Set<string>;
+}): ParseMapEdgesResult;

package/dist/src/analyze/composition/parse-map-edges.js

@@ -0,0 +1,55 @@
+const VALID_MAP_TOOL_NAMES = new Set(['map_edge']);
+export function parseMapEdges(raw, opts) {
+    const edges = [];
+    const warnings = [];
+    const { componentNames } = opts;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            warnings.push(`unparseable line: ${trimmed.slice(0, 120)}`);
+            continue;
+        }
+        if (typeof obj !== 'object' || obj === null || !('tool' in obj))
+            continue;
+        const rec = obj;
+        if (!VALID_MAP_TOOL_NAMES.has(rec.tool)) {
+            warnings.push(`unknown tool: ${String(rec.tool)}`);
+            continue;
+        }
+        if (typeof rec.parent !== 'string' || !rec.parent || typeof rec.child !== 'string' || !rec.child) {
+            warnings.push('map_edge missing parent/child — skipped');
+            continue;
+        }
+        const { parent, child } = rec;
+        // Verification (spec §1.3): both endpoints must name a known component.
+        if (!componentNames.has(parent)) {
+            warnings.push(`map_edge names unknown component (parent): ${parent} — skipped`);
+            continue;
+        }
+        if (!componentNames.has(child)) {
+            warnings.push(`map_edge names unknown component (child): ${child} — skipped`);
+            continue;
+        }
+        const edge = { parent, child, provenance: 'agent' };
+        if (typeof rec.slot === 'string' && rec.slot) {
+            edge.slot = rec.slot;
+        }
+        if (rec.confidence !== undefined) {
+            if (typeof rec.confidence === 'number' && rec.confidence >= 1 && rec.confidence <= 5) {
+                edge.confidence = rec.confidence;
+            }
+            else {
+                // Lenient: keep the edge, drop the bad confidence, record a warning.
+                warnings.push(`map_edge (${parent}→${child}): invalid confidence ${String(rec.confidence)} — edge kept without confidence`);
+            }
+        }
+        edges.push(edge);
+    }
+    return { edges, warnings };
+}

package/dist/src/analyze/composition/resolve-mapping-cli.d.ts

@@ -0,0 +1,23 @@
+import { type InterchangeMap } from './interchange-schema.js';
+export type CompositionCliOptions = {
+    /** `--composition-map <path>` — hand-authored interchange file. */
+    compositionMap?: string;
+    /** `--composition-agent` — opt into agentic resolution. */
+    compositionAgent?: boolean;
+    /** `--composition-refresh` — force the agent to run even over resolved residue. */
+    compositionRefresh?: boolean;
+};
+export type LoadUserMapResult = {
+    ok: true;
+    map: InterchangeMap;
+} | {
+    ok: false;
+    error: string;
+};
+/** Read + validate a hand-authored interchange map (spec T1 / §1.2 third mechanism). */
+export declare function loadUserMap(path: string): Promise<LoadUserMapResult>;
+export type ResolvedCompositionSources = {
+    useAgent: boolean;
+    forceAgent: boolean;
+};
+export declare function resolveCompositionSources(opts: CompositionCliOptions): ResolvedCompositionSources;

package/dist/src/analyze/composition/resolve-mapping-cli.js

@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises';
+import { validateInterchangeMap } from './interchange-schema.js';
+/** Read + validate a hand-authored interchange map (spec T1 / §1.2 third mechanism). */
+export async function loadUserMap(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return { ok: false, error: `--composition-map: file not found: ${path}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, error: `--composition-map: not valid JSON: ${path}` };
+    }
+    const res = validateInterchangeMap(parsed);
+    if (!res.valid)
+        return { ok: false, error: `--composition-map: ${res.errors.join('; ')}` };
+    return { ok: true, map: res.map };
+}
+export function resolveCompositionSources(opts) {
+    return {
+        useAgent: !!opts.compositionAgent,
+        forceAgent: !!opts.compositionRefresh,
+    };
+}

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

@@ -0,0 +1,59 @@
+import type { RawComponentDefinition } from '../../types.js';
+import { type CompositionEdge, type InterchangeMap } from './interchange-schema.js';
+import { type EdgeConflict } from './merge-edges.js';
+export type ResolveMappingResult = {
+    components: RawComponentDefinition[];
+    edges: CompositionEdge[];
+    conflicts: EdgeConflict[];
+    warnings: string[];
+};
+/**
+ * Orchestrate composition-map acquisition (spec T2) and enrichment (T7).
+ *
+ * Sources by rank: user map (1) > typed-slot / "code slots" (2) > agent (4).
+ * ALL sources — including the code slots already on the incoming components —
+ * are fed into one ranked merge and unioned; non-conflicting edges from every
+ * source survive, and on a conflict (same parent+child, different slot) the
+ * higher-rank source wins and the loser is recorded. The agent runs only when
+ * `useAgent`/`forceAgent` is set AND there is residue a higher-rank source
+ * didn't cover (routing/cost optimization) — `forceAgent` bypasses that
+ * suppression but never changes rank.
+ *
+ * `runAgentFn` is injected (returns the agent's raw stdout) so this is
+ * testable without spawning a subprocess.
+ */
+export declare function resolveMapping(input: {
+    components: RawComponentDefinition[];
+    userMap?: InterchangeMap;
+    useAgent?: boolean;
+    forceAgent?: boolean;
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    runAgentFn: (opts: {
+        prompt: string;
+        files: Array<{
+            path: string;
+            content: string;
+        }>;
+    }) => Promise<string>;
+    buildPrompt?: (files: Array<{
+        path: string;
+        content: string;
+    }>, componentNames: string[]) => string;
+    /**
+     * Custom instruction preamble (from `--prompt composition=...`). Replaces the
+     * default guidance line ONLY; the machine-readable output contract + the
+     * component-name allowlist + candidate files are always appended so the
+     * JSONL parser keeps working regardless of the override.
+     */
+    promptOverride?: string;
+    /**
+     * Pre-resolved edges from an external source (e.g. the agent-authored parser
+     * path). They join the ranked merge at their own provenance rank alongside
+     * code slots and the user map. Callers using this typically set
+     * `useAgent: false` since they've already run their own resolution.
+     */
+    extraEdges?: CompositionEdge[];
+}): Promise<ResolveMappingResult>;

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

@@ -0,0 +1,94 @@
+import { groupsToEdges } from './interchange-schema.js';
+import { mergeEdges } from './merge-edges.js';
+import { parseMapEdges } from './parse-map-edges.js';
+import { applyMapping } from './apply-mapping.js';
+import { loadPrompt } from './agent-parser/load-prompt.js';
+/**
+ * Orchestrate composition-map acquisition (spec T2) and enrichment (T7).
+ *
+ * Sources by rank: user map (1) > typed-slot / "code slots" (2) > agent (4).
+ * ALL sources — including the code slots already on the incoming components —
+ * are fed into one ranked merge and unioned; non-conflicting edges from every
+ * source survive, and on a conflict (same parent+child, different slot) the
+ * higher-rank source wins and the loser is recorded. The agent runs only when
+ * `useAgent`/`forceAgent` is set AND there is residue a higher-rank source
+ * didn't cover (routing/cost optimization) — `forceAgent` bypasses that
+ * suppression but never changes rank.
+ *
+ * `runAgentFn` is injected (returns the agent's raw stdout) so this is
+ * testable without spawning a subprocess.
+ */
+export async function resolveMapping(input) {
+    const componentNames = new Set(input.components.map((c) => c.name));
+    const collected = [];
+    const agentWarnings = [];
+    // Rank 2 — typed-slot ("code slots") already resolved by the AST extractor.
+    // Feed them into the ranked merge so a conflicting lower-rank edge (agent
+    // placing the same child in a different slot) LOSES to code rather than being
+    // unioned in alongside it.
+    for (const c of input.components) {
+        for (const slot of c.slots) {
+            for (const child of slot.allowedComponents ?? []) {
+                collected.push({ parent: c.name, child, slot: slot.name, provenance: 'typed-slot' });
+            }
+        }
+    }
+    // Rank 1 — user-provided map.
+    if (input.userMap) {
+        collected.push(...groupsToEdges(input.userMap, 'user'));
+    }
+    // Externally pre-resolved edges (e.g. agent-authored parser, rank 3).
+    if (input.extraEdges) {
+        collected.push(...input.extraEdges);
+    }
+    // Routing: which parents are already covered by a higher-rank source?
+    const coveredParents = new Set(collected.map((e) => e.parent));
+    const residueParents = input.components.map((c) => c.name).filter((n) => !coveredParents.has(n));
+    // Rank 4 — agent. Runs when enabled AND (forced OR there is residue).
+    const shouldRunAgent = (input.useAgent || input.forceAgent) && (input.forceAgent || residueParents.length > 0);
+    if (shouldRunAgent) {
+        const prompt = input.buildPrompt
+            ? input.buildPrompt(input.files, [...componentNames])
+            : defaultPrompt(input.files, [...componentNames], input.promptOverride);
+        const raw = await input.runAgentFn({ prompt, files: input.files });
+        const parsed = parseMapEdges(raw, { componentNames });
+        collected.push(...parsed.edges);
+        agentWarnings.push(...parsed.warnings);
+    }
+    const merged = mergeEdges(collected);
+    // Apply the merged edges onto components whose allowedComponents are cleared,
+    // so the ranked merge is authoritative — a code edge that lost to a rank-1
+    // user override is actually gone, not left behind on the original slot.
+    // Slot structure is preserved; only the composition constraint is reset.
+    const base = input.components.map((c) => ({
+        ...c,
+        slots: c.slots.map((s) => {
+            const { allowedComponents: _drop, ...rest } = s;
+            return rest;
+        }),
+    }));
+    const applied = applyMapping(base, merged.edges);
+    return {
+        components: applied.components,
+        edges: merged.edges,
+        conflicts: merged.conflicts,
+        warnings: [...agentWarnings, ...applied.warnings],
+    };
+}
+function defaultPrompt(files, componentNames, promptOverride) {
+    const fileBlocks = files.map((f) => `--- ${f.path} ---\n${f.content}`).join('\n\n');
+    // The override replaces only the leading instruction; the output contract,
+    // name allowlist, and candidate files are always appended so the JSONL
+    // parser keeps working.
+    const instruction = promptOverride?.trim() ? promptOverride.trim() : loadPrompt('composition-edges.md').trim();
+    return [
+        instruction,
+        '',
+        'Emit one JSON object per line, each: {"tool":"map_edge","parent":"<Name>","child":"<Name>","slot"?:"<slot>","confidence"?:1-5,"reason":"<cite the file + declaration>"}.',
+        'Use ONLY these exact component names (an edge naming anything else is dropped):',
+        componentNames.join(', '),
+        '',
+        'Candidate files:',
+        fileBlocks,
+    ].join('\n');
+}

package/dist/src/analyze/cycle-detection.d.ts

@@ -0,0 +1,27 @@
+/** A directed edge in the slot-dependency graph. */
+export interface SlotEdge {
+    fromComponent: string;
+    slotName: string;
+    toComponent: string;
+}
+/** A single elementary cycle, with `path[0] === path[path.length - 1]`. */
+export interface SlotCycle {
+    path: string[];
+    edges: SlotEdge[];
+}
+/** Input shape mirroring the slot definition on CDFComponentEntry. */
+export interface ComponentSlotInfo {
+    name: string;
+    slots: Array<{
+        name: string;
+        allowedComponents?: string[];
+    }>;
+}
+export declare function findSlotCycles(components: ComponentSlotInfo[]): SlotCycle[];
+export declare function suggestCycleBreakEdge(cycle: SlotCycle, allCycles: SlotCycle[]): SlotEdge;
+export declare function formatCyclePath(cycle: SlotCycle, maxHops?: number): string;
+export interface CyclePathSegment {
+    kind: 'component' | 'slot' | 'arrow';
+    text: string;
+}
+export declare function formatCyclePathSegments(cycle: SlotCycle, maxHops?: number): CyclePathSegment[];