@contentful/experience-design-system-cli 2.26.1-dev-build-64063df.0 → 2.26.1-dev-build-f1d1f30.0

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

@@ -1,61 +0,0 @@
-/**
- * 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/manifest-doc-evidence.js

@@ -1,136 +0,0 @@
-import { dirname } from 'node:path';
-/**
- * Prompt-injection safeguard for this signal: both parsers below are plain
- * deterministic code, never an LLM prompt. `manifest.json`/`AGENTS.md`
- * content is attacker-adjacent (Figma-authored / free-form prose respectively)
- * but it only ever flows through JSON field access and a fixed regex, then is
- * validated against the real `componentNames` allowlist before an edge is
- * emitted — there is no path from this file's content to model instructions.
- */
-/** Figma/manifest names are kebab-case (`blue-accordion-item`); React exports are PascalCase. */
-export function kebabToPascal(name) {
-    return name
-        .split('-')
-        .filter(Boolean)
-        .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1))
-        .join('');
-}
-/**
- * Deterministic parse of a Figma-exported `manifest.json` — no LLM involved.
- * Schema (confirmed against a real design-system manifest):
- *   { component: { name: "blue-accordion" },
- *     variantsMeta: { componentPropertyDefinitions: {
- *       "Slot#1533:33": { type: "SLOT", preferredValues: [{ name: "blue-accordion-item" }] }
- *     } } }
- * The manifest's own `component.name` identifies its owning/parent component
- * (more robust than inferring from directory proximity, since manifest.json
- * typically lives one level below the component's source file, e.g. in a
- * sibling `design/` directory).
- */
-export function collectManifestEdges(files, componentNames) {
-    const edges = [];
-    const seen = new Set();
-    for (const file of files) {
-        if (!file.path.endsWith('manifest.json'))
-            continue;
-        let parsed;
-        try {
-            parsed = JSON.parse(file.content);
-        }
-        catch {
-            continue;
-        }
-        if (typeof parsed !== 'object' || parsed === null)
-            continue;
-        const root = parsed;
-        const component = root.component;
-        const rawParentName = typeof component === 'object' &&
-            component !== null &&
-            typeof component.name === 'string'
-            ? component.name
-            : undefined;
-        if (!rawParentName)
-            continue;
-        const parent = kebabToPascal(rawParentName);
-        if (!componentNames.has(parent))
-            continue;
-        const variantsMeta = root.variantsMeta;
-        const propDefs = typeof variantsMeta === 'object' && variantsMeta !== null
-            ? variantsMeta.componentPropertyDefinitions
-            : undefined;
-        if (typeof propDefs !== 'object' || propDefs === null)
-            continue;
-        for (const def of Object.values(propDefs)) {
-            if (typeof def !== 'object' || def === null)
-                continue;
-            const defObj = def;
-            if (defObj.type !== 'SLOT')
-                continue;
-            const preferredValues = Array.isArray(defObj.preferredValues) ? defObj.preferredValues : [];
-            for (const value of preferredValues) {
-                if (typeof value !== 'object' || value === null)
-                    continue;
-                const rawChildName = value.name;
-                if (typeof rawChildName !== 'string')
-                    continue;
-                const child = kebabToPascal(rawChildName);
-                if (!componentNames.has(child) || child === parent)
-                    continue;
-                const key = `${parent}::${child}`;
-                if (seen.has(key))
-                    continue;
-                seen.add(key);
-                edges.push({ parent, child, provenance: 'manifest' });
-            }
-        }
-    }
-    return edges;
-}
-const DOC_COMPOSITION_KEYWORDS = ['slot', 'child', 'children', 'compose', 'nested', 'contains', 'wraps'];
-const BOLD_BACKTICK = /\*\*`([^`]+)`\*\*/g;
-/**
- * Deterministic parse of a component-level `AGENTS.md` — no LLM involved.
- * Only a bold-backtick component mention (`` **`ComponentName`** ``) on a
- * line that ALSO carries a composition keyword is accepted, e.g. "Direct
- * **`AccordionItem`** children only." A bare cross-reference mention (no
- * composition keyword on the same line, e.g. "see `other-component`") is
- * rejected — it isn't asserting a parent-child relationship.
- *
- * The doc's owning component is resolved by directory colocation: the
- * component whose `sourcePath` sits in the same directory as the doc file
- * (the real-world convention — `<component>/AGENTS.md` next to
- * `<component>/Component.tsx`).
- */
-export function collectAgentsDocEdges(files, components, componentNames) {
-    const edges = [];
-    const seen = new Set();
-    for (const file of files) {
-        if (!file.path.endsWith('AGENTS.md'))
-            continue;
-        const docDir = dirname(file.path);
-        const parent = components.find((c) => c.sourcePath && dirname(c.sourcePath) === docDir)?.name;
-        if (!parent || !componentNames.has(parent))
-            continue;
-        for (const line of file.content.split('\n')) {
-            const lower = line.toLowerCase();
-            if (!DOC_COMPOSITION_KEYWORDS.some((kw) => lower.includes(kw)))
-                continue;
-            for (const match of line.matchAll(BOLD_BACKTICK)) {
-                const raw = match[1];
-                const candidate = componentNames.has(raw) ? raw : kebabToPascal(raw);
-                if (!componentNames.has(candidate) || candidate === parent)
-                    continue;
-                const key = `${parent}::${candidate}`;
-                if (seen.has(key))
-                    continue;
-                seen.add(key);
-                edges.push({ parent, child: candidate, provenance: 'doc' });
-            }
-        }
-    }
-    return edges;
-}
-/** Both deterministic sources, combined for the `extraEdges` wiring in command.ts. */
-export function collectManifestDocEdges(files, components, componentNames) {
-    return [...collectManifestEdges(files, componentNames), ...collectAgentsDocEdges(files, components, componentNames)];
-}

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

@@ -1,70 +0,0 @@
-/**
- * Provenance rank (spec T2). Lower number = higher trust = wins conflicts.
- *   1 user  >  2 typed-slot  >  3 structural  >  4 manifest  >  5 doc  >
- *   6 adapter:*  >  7 agent
- *
- * `structural` sits just below a declared slot contract: it's usage evidence
- * (a runtime type-predicate function, a `.type === Component` identity check,
- * direct JSX instantiation — see `structural-slot-evidence.ts`) rather than a
- * typed generic or explicit marker, so a declared contract always overrides
- * it on conflict, but it still outranks the LLM agent.
- *
- * `manifest` (Figma-generated `manifest.json` SLOT declarations) and `doc`
- * (component `AGENTS.md` prose) are both deterministically parsed — no LLM
- * ever reads their content for this signal — but they describe design intent
- * rather than the shipped code, so they sit below code-derived evidence.
- * `manifest` outranks `doc` since it's structured/systematic; free-form
- * prose is the least verifiable of the code-adjacent signals.
- */
-function rank(p) {
-    if (p === 'user')
-        return 1;
-    if (p === 'typed-slot')
-        return 2;
-    if (p === 'structural')
-        return 3;
-    if (p === 'manifest')
-        return 4;
-    if (p === 'doc')
-        return 5;
-    if (p.startsWith('adapter:'))
-        return 6;
-    return 7; // 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.js

@@ -1,55 +0,0 @@
-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.js

@@ -1,29 +0,0 @@
-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.js

@@ -1,111 +0,0 @@
-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) > structural
- * usage evidence (3) > manifest (4) > doc (5) > adapter-resolved / extraEdges
- * (6) > agent (7). Manifest/doc edges are computed deterministically outside
- * this function (see manifest-doc-evidence.ts) and joined via `extraEdges`.
- * 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 3 — structural usage evidence (runtime type-predicate, `.type ===`
-    // identity check, or direct JSX nesting — see structural-slot-evidence.ts).
-    // Lower trust than a declared slot contract, but still code-derived, so it
-    // outranks the agent and suppresses a redundant agent run when it alone
-    // covers a parent.
-    for (const c of input.components) {
-        for (const slot of c.slots) {
-            for (const child of slot.structuralAllowedComponents ?? []) {
-                collected.push({ parent: c.name, child, slot: slot.name, provenance: 'structural' });
-            }
-        }
-    }
-    // Rank 1 — user-provided map.
-    if (input.userMap) {
-        collected.push(...groupsToEdges(input.userMap, 'user'));
-    }
-    // Externally pre-resolved edges — manifest (4), doc (5), adapter-authored
-    // parser (6) — each edge carries its own provenance, so this loop is rank-
-    // agnostic; the merge below sorts it out.
-    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 7 — 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');
-}