@contentful/experience-design-system-cli 2.12.4-dev-build-5aa6a69.0 → 2.12.4-dev-build-ff57340.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.12.4-dev-build-5aa6a69.0",
+  "version": "2.12.4-dev-build-ff57340.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/analyze/command.js

@@ -6,7 +6,8 @@ import { extractComponents } from './extract/pipeline.js';
 import { AnalyzeView } from './tui/AnalyzeView.js';
 import { registerAnalyzeEditCommand } from './select/command.js';
 import { registerAnalyzeSelectAgentCommand } from './select-agent/command.js';
-import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents, storeScannedFiles, } from '../session/db.js';
+import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents, storeScannedFiles, storeSlotCycles, } from '../session/db.js';
+import { findSlotCycles, suggestCycleBreakEdge } from './cycle-detection.js';
 import { preClassifyComponent } from './pre-classify.js';
 import { isNonAuthorableComponent } from './extract/non-authorable-filter.js';
 import { computeExtractionScore, deriveNeedsReview } from './extract/scoring.js';
@@ -191,6 +192,20 @@ export function registerAnalyzeCommand(program) {
         }
         const validatedComponents = validateExtractedComponents(filteredComponents);
         storeRawComponents(db, sessionId, validatedComponents);
+        // INTEG-4401: post-extract slot-dependency cycle detection. The apply
+        // worker rejects cyclic slot graphs at push time, so we surface the
+        // same violation locally as a soft warning here (TUI reads
+        // slot_cycles) and as a hard block at manifest finalization.
+        const cycleInput = validatedComponents.map((c) => ({
+            name: c.name,
+            slots: c.slots.map((s) => ({ name: s.name, allowedComponents: s.allowedComponents })),
+        }));
+        const cycles = findSlotCycles(cycleInput);
+        const withBreaks = cycles.map((cycle) => ({
+            ...cycle,
+            suggestedBreak: suggestCycleBreakEdge(cycle, cycles),
+        }));
+        storeSlotCycles(db, sessionId, withBreaks);
         storeScannedFiles(db, sessionId, sourceFiles.map((f) => relative(projectRoot, f)));
         updateStep(db, stepId, 'complete', { sessionId });
         db.close();

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

@@ -0,0 +1,93 @@
+/**
+ * Slot-dependency cycle detection.
+ *
+ * The Contentful Experience Design System backend rejects component manifests
+ * that contain slot-dependency cycles at apply time — a topo-sort in the
+ * apply worker refuses to create component types whose slot's
+ * `$allowedComponents` transitively point back at themselves. Reference:
+ * `experience-design-system-integrations` / services/design-system-sources-apply-worker/src/topo-sort.ts.
+ *
+ * We surface the same check locally so the wizard can:
+ *   1. warn the operator at extract time (soft) with sidebar badges + banner,
+ *   2. hard-block the push at manifest-finalization time before any API call.
+ *
+ * The algorithm is Johnson's — an O((V + E)(C + 1)) enumeration of all
+ * elementary (simple) cycles in a directed graph. We need *elementary*
+ * cycles rather than just cycle-existence because an operator can have
+ * multiple independent cycles they need to address separately, and each
+ * gets its own suggested fix.
+ *
+ * Johnson's algorithm reference: Donald B. Johnson, "Finding all the
+ * elementary circuits of a directed graph." SIAM J. Comput., 4(1):77-84, 1975.
+ */
+/** 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 {
+    /** Component names visited, with the first repeated at the end. */
+    path: string[];
+    /** Ordered edges forming the cycle. `edges.length === path.length - 1`. */
+    edges: SlotEdge[];
+}
+/** Input shape mirroring the slot definition on CDFComponentEntry. */
+export interface ComponentSlotInfo {
+    name: string;
+    slots: Array<{
+        name: string;
+        allowedComponents?: string[];
+    }>;
+}
+/**
+ * Johnson's algorithm — enumerates all elementary (simple) cycles in the
+ * slot-dependency graph. Self-loops are handled as a degenerate first pass
+ * because Tarjan's SCC decomposition assigns a self-looping node to its own
+ * single-node SCC, which Johnson's inner loop otherwise skips.
+ */
+export declare function findSlotCycles(components: ComponentSlotInfo[]): SlotCycle[];
+/**
+ * Pick which edge is the best candidate to remove to break a cycle.
+ * Heuristic: prefer removing the edge whose `toComponent` appears most often
+ * as a destination across all cycles — that "hub" node is the biggest
+ * contributor and removing an inbound edge to it likely breaks multiple
+ * cycles at once. Falls back to the first edge in the cycle for
+ * deterministic output when all candidates are tied.
+ */
+export declare function suggestCycleBreakEdge(cycle: SlotCycle, allCycles: SlotCycle[]): SlotEdge;
+/**
+ * Format a cycle for the compact banner:
+ *   `CardA → header → CardB → footer → CardA`
+ *
+ * Truncates at `maxHops` edges (default 8), inserting `…` mid-path so the
+ * beginning and end remain visible. A hop is one edge; the returned string
+ * for an n-edge cycle contains n+1 component names.
+ *
+ * Kept for backend/log/error use where a single string is required (see
+ * `assertNoSlotCycles` in `apply/command.ts`). The TUI banner + detail panel
+ * use `formatCyclePathSegments` instead so slot names can be visually
+ * distinguished from component names.
+ */
+export declare function formatCyclePath(cycle: SlotCycle, maxHops?: number): string;
+/**
+ * A single token in the rendered cycle path — either a component name, a
+ * slot name (wrapped in brackets for monochrome legibility), or the arrow
+ * separator between them. The TUI colorizes each kind independently.
+ *
+ * Slots are rendered as `[slotName]` so the visual distinction survives when
+ * ANSI colors are stripped (log files, redirection, dumb terminals).
+ */
+export interface CyclePathSegment {
+    kind: 'component' | 'slot' | 'arrow';
+    text: string;
+}
+/**
+ * Segment-oriented counterpart to `formatCyclePath`. Preserves the same
+ * 8-hop truncation semantics but returns each token classified so the
+ * renderer can color slots (cyan) and components (default) independently.
+ * The truncation marker `…` is emitted as a bare component segment because
+ * it stands in for one or more component nodes.
+ */
+export declare function formatCyclePathSegments(cycle: SlotCycle, maxHops?: number): CyclePathSegment[];

package/dist/src/analyze/cycle-detection.js

@@ -0,0 +1,326 @@
+/**
+ * Slot-dependency cycle detection.
+ *
+ * The Contentful Experience Design System backend rejects component manifests
+ * that contain slot-dependency cycles at apply time — a topo-sort in the
+ * apply worker refuses to create component types whose slot's
+ * `$allowedComponents` transitively point back at themselves. Reference:
+ * `experience-design-system-integrations` / services/design-system-sources-apply-worker/src/topo-sort.ts.
+ *
+ * We surface the same check locally so the wizard can:
+ *   1. warn the operator at extract time (soft) with sidebar badges + banner,
+ *   2. hard-block the push at manifest-finalization time before any API call.
+ *
+ * The algorithm is Johnson's — an O((V + E)(C + 1)) enumeration of all
+ * elementary (simple) cycles in a directed graph. We need *elementary*
+ * cycles rather than just cycle-existence because an operator can have
+ * multiple independent cycles they need to address separately, and each
+ * gets its own suggested fix.
+ *
+ * Johnson's algorithm reference: Donald B. Johnson, "Finding all the
+ * elementary circuits of a directed graph." SIAM J. Comput., 4(1):77-84, 1975.
+ */
+function buildGraph(components) {
+    const nodes = [];
+    const seen = new Set();
+    for (const c of components) {
+        if (seen.has(c.name))
+            continue;
+        seen.add(c.name);
+        nodes.push(c.name);
+    }
+    const adjacency = new Map();
+    for (const node of nodes)
+        adjacency.set(node, []);
+    for (const comp of components) {
+        const outgoing = adjacency.get(comp.name);
+        if (!outgoing)
+            continue;
+        for (const slot of comp.slots) {
+            const allowed = slot.allowedComponents ?? [];
+            for (const target of allowed) {
+                if (!seen.has(target))
+                    continue; // unknown / external — ignore
+                outgoing.push({ target, slotName: slot.name });
+            }
+        }
+    }
+    return { nodes, adjacency };
+}
+/**
+ * Tarjan's strongly-connected-components algorithm — used by Johnson's
+ * algorithm to constrain cycle search to one SCC at a time. Returns SCCs in
+ * reverse-topological order.
+ */
+function stronglyConnectedComponents(nodes, adjacency) {
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    let counter = 0;
+    const nodeSet = new Set(nodes);
+    function strongconnect(v) {
+        index.set(v, counter);
+        lowlink.set(v, counter);
+        counter += 1;
+        stack.push(v);
+        onStack.add(v);
+        const neighbours = adjacency.get(v) ?? [];
+        for (const { target } of neighbours) {
+            if (!nodeSet.has(target))
+                continue;
+            if (!index.has(target)) {
+                strongconnect(target);
+                lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(target)));
+            }
+            else if (onStack.has(target)) {
+                lowlink.set(v, Math.min(lowlink.get(v), index.get(target)));
+            }
+        }
+        if (lowlink.get(v) === index.get(v)) {
+            const scc = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                scc.push(w);
+            } while (w !== v);
+            sccs.push(scc);
+        }
+    }
+    for (const node of nodes) {
+        if (!index.has(node))
+            strongconnect(node);
+    }
+    return sccs;
+}
+/**
+ * Given a specific traversal `path` (component names) and the edge multiset
+ * we walked to build it, materialize a `SlotCycle`. Because multiple parallel
+ * edges may exist between the same two components (different slot names), we
+ * carry the exact edges along the search rather than reconstructing them from
+ * the node path.
+ */
+function makeCycle(path, edges) {
+    return { path: [...path, path[0]], edges: [...edges] };
+}
+/**
+ * Johnson's algorithm — enumerates all elementary (simple) cycles in the
+ * slot-dependency graph. Self-loops are handled as a degenerate first pass
+ * because Tarjan's SCC decomposition assigns a self-looping node to its own
+ * single-node SCC, which Johnson's inner loop otherwise skips.
+ */
+export function findSlotCycles(components) {
+    if (components.length === 0)
+        return [];
+    const { nodes, adjacency } = buildGraph(components);
+    if (nodes.length === 0)
+        return [];
+    const cycles = [];
+    // Degenerate case: self-loops. For any component whose slot allows itself,
+    // emit a length-1 cycle before invoking Johnson's inner loop — Tarjan's
+    // trivial single-node SCC test in Johnson's original paper only counts as
+    // an SCC if the node participates in an edge, which we replicate here.
+    for (const node of nodes) {
+        const outgoing = adjacency.get(node) ?? [];
+        for (const edge of outgoing) {
+            if (edge.target === node) {
+                cycles.push({
+                    path: [node, node],
+                    edges: [{ fromComponent: node, slotName: edge.slotName, toComponent: node }],
+                });
+            }
+        }
+    }
+    // Johnson's main algorithm — iterate over remaining nodes in a fixed order,
+    // decomposing the subgraph induced by `{node, ...higherOrder}` into SCCs,
+    // and running the blocked-list circuit search rooted at the least node of
+    // each non-trivial SCC. This is the classic formulation from the paper.
+    const nodeOrder = [...nodes].sort();
+    let remaining = [...nodeOrder];
+    while (remaining.length > 0) {
+        const subgraphNodes = remaining;
+        const sccs = stronglyConnectedComponents(subgraphNodes, adjacency).filter((scc) => {
+            if (scc.length > 1)
+                return true;
+            // Non-trivial single-node SCC iff the node has a self-loop within the
+            // subgraph. We already emitted those above, so exclude here.
+            return false;
+        });
+        if (sccs.length === 0)
+            break;
+        // Pick the SCC containing the lexicographically-smallest node — mirrors
+        // the "least vertex" root selection in Johnson's paper.
+        let startNode = null;
+        let startScc = null;
+        for (const scc of sccs) {
+            const min = [...scc].sort()[0];
+            if (startNode === null || min < startNode) {
+                startNode = min;
+                startScc = scc;
+            }
+        }
+        if (startNode === null || startScc === null)
+            break;
+        const sccSet = new Set(startScc);
+        const blocked = new Set();
+        const blockedMap = new Map();
+        const pathStack = [];
+        const edgeStack = [];
+        function unblock(u) {
+            blocked.delete(u);
+            const dependents = blockedMap.get(u);
+            if (!dependents)
+                return;
+            for (const w of dependents) {
+                if (blocked.has(w))
+                    unblock(w);
+            }
+            dependents.clear();
+        }
+        function circuit(v, root) {
+            let foundCycle = false;
+            pathStack.push(v);
+            blocked.add(v);
+            const outgoing = adjacency.get(v) ?? [];
+            for (const { target: w, slotName } of outgoing) {
+                if (!sccSet.has(w))
+                    continue;
+                edgeStack.push({ fromComponent: v, slotName, toComponent: w });
+                if (w === root) {
+                    cycles.push(makeCycle(pathStack, edgeStack));
+                    foundCycle = true;
+                }
+                else if (!blocked.has(w)) {
+                    if (circuit(w, root))
+                        foundCycle = true;
+                }
+                edgeStack.pop();
+            }
+            if (foundCycle) {
+                unblock(v);
+            }
+            else {
+                for (const { target: w } of outgoing) {
+                    if (!sccSet.has(w))
+                        continue;
+                    let deps = blockedMap.get(w);
+                    if (!deps) {
+                        deps = new Set();
+                        blockedMap.set(w, deps);
+                    }
+                    deps.add(v);
+                }
+            }
+            pathStack.pop();
+            return foundCycle;
+        }
+        circuit(startNode, startNode);
+        // Remove `startNode` from consideration and repeat with the reduced
+        // subgraph. In classic Johnson's this is done by re-running SCC on the
+        // subgraph induced by the remaining nodes.
+        remaining = remaining.filter((n) => n !== startNode);
+    }
+    return cycles;
+}
+/**
+ * Pick which edge is the best candidate to remove to break a cycle.
+ * Heuristic: prefer removing the edge whose `toComponent` appears most often
+ * as a destination across all cycles — that "hub" node is the biggest
+ * contributor and removing an inbound edge to it likely breaks multiple
+ * cycles at once. Falls back to the first edge in the cycle for
+ * deterministic output when all candidates are tied.
+ */
+export function suggestCycleBreakEdge(cycle, allCycles) {
+    if (cycle.edges.length === 0) {
+        throw new Error('suggestCycleBreakEdge: cycle has no edges');
+    }
+    const indegree = new Map();
+    for (const c of allCycles) {
+        for (const edge of c.edges) {
+            indegree.set(edge.toComponent, (indegree.get(edge.toComponent) ?? 0) + 1);
+        }
+    }
+    let best = cycle.edges[0];
+    let bestScore = indegree.get(best.toComponent) ?? 0;
+    for (const edge of cycle.edges) {
+        const score = indegree.get(edge.toComponent) ?? 0;
+        if (score > bestScore) {
+            best = edge;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * Format a cycle for the compact banner:
+ *   `CardA → header → CardB → footer → CardA`
+ *
+ * Truncates at `maxHops` edges (default 8), inserting `…` mid-path so the
+ * beginning and end remain visible. A hop is one edge; the returned string
+ * for an n-edge cycle contains n+1 component names.
+ *
+ * Kept for backend/log/error use where a single string is required (see
+ * `assertNoSlotCycles` in `apply/command.ts`). The TUI banner + detail panel
+ * use `formatCyclePathSegments` instead so slot names can be visually
+ * distinguished from component names.
+ */
+export function formatCyclePath(cycle, maxHops = 8) {
+    const arrow = ' → ';
+    const parts = [];
+    // Interleave: component, slot, component, slot, ..., final component
+    // path.length === edges.length + 1.
+    for (let i = 0; i < cycle.edges.length; i += 1) {
+        parts.push(cycle.path[i]);
+        parts.push(cycle.edges[i].slotName);
+    }
+    parts.push(cycle.path[cycle.path.length - 1]);
+    if (cycle.edges.length <= maxHops) {
+        return parts.join(arrow);
+    }
+    // Truncated: keep the first `keep` edges' worth of tokens and the final
+    // component. Two "tokens per hop" (component + slot) plus the trailing
+    // component name.
+    const keepHops = Math.max(1, maxHops - 1);
+    const keepTokens = keepHops * 2;
+    const head = parts.slice(0, keepTokens).join(arrow);
+    const tail = parts[parts.length - 1];
+    return `${head}${arrow}…${arrow}${tail}`;
+}
+/**
+ * Segment-oriented counterpart to `formatCyclePath`. Preserves the same
+ * 8-hop truncation semantics but returns each token classified so the
+ * renderer can color slots (cyan) and components (default) independently.
+ * The truncation marker `…` is emitted as a bare component segment because
+ * it stands in for one or more component nodes.
+ */
+export function formatCyclePathSegments(cycle, maxHops = 8) {
+    // Interleaved [component, slot, component, slot, ..., component] token list
+    // matching `formatCyclePath`'s parts array, but classified.
+    const raw = [];
+    for (let i = 0; i < cycle.edges.length; i += 1) {
+        raw.push({ kind: 'component', text: cycle.path[i] });
+        raw.push({ kind: 'slot', text: `[${cycle.edges[i].slotName}]` });
+    }
+    raw.push({ kind: 'component', text: cycle.path[cycle.path.length - 1] });
+    const withArrows = (segs) => {
+        const out = [];
+        for (let i = 0; i < segs.length; i += 1) {
+            if (i > 0)
+                out.push({ kind: 'arrow', text: ' → ' });
+            out.push(segs[i]);
+        }
+        return out;
+    };
+    if (cycle.edges.length <= maxHops) {
+        return withArrows(raw);
+    }
+    // Match `formatCyclePath` truncation: keep the first (maxHops-1)*2 tokens
+    // plus a "…" placeholder plus the trailing component.
+    const keepHops = Math.max(1, maxHops - 1);
+    const keepTokens = keepHops * 2;
+    const head = raw.slice(0, keepTokens);
+    const tail = raw[raw.length - 1];
+    return withArrows([...head, { kind: 'component', text: '…' }, tail]);
+}

package/dist/src/analyze/select/tui/components/FieldEditor.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { findSlotCycles, type ComponentSlotInfo } from '../../../cycle-detection.js';
 /** Per-prop / per-component metadata captured by the extractor + generate phase.
  * Optional; when omitted, the FieldEditor renders without rationale/source
  * affordances (backwards-compatible with mounts that pre-date Feature 1). */
@@ -63,6 +64,28 @@ type FieldEditorProps = {
      * description editors, string default editors, and value-list text entry.
      */
     onTextEntryActiveChange?: (active: boolean) => void;
+    /**
+     * INTEG-4401: project-wide slot graph. When supplied, the
+     * $allowedComponents add-mode shows a cycle-filtered picker. Optional.
+     */
+    projectSlotGraph?: ComponentSlotInfo[];
+    /**
+     * INTEG-4401: name of the component being edited. Self-loop guard +
+     * self-entry replacement in the cycle simulation.
+     */
+    currentComponentName?: string;
 };
-export declare function FieldEditor({ value, width, height, active, onChange, onSave, onDiscard, onExit, metadata, onTogglePropRationale, onToggleComponentRationale, onToggleSourceExternal, onTextEntryActiveChange, }: FieldEditorProps): React.ReactElement;
+/** Simulate adding a candidate to a slot; replaces self-entry with live edits. */
+export declare function simulateGraphWithCandidate(projectSlotGraph: ComponentSlotInfo[], selfName: string, currentSlots: {
+    name: string;
+    allowedComponents: string[];
+}[], targetSlotName: string, candidate: string): ComponentSlotInfo[];
+/** True iff `next` contains a cycle whose canonical edge set is absent in `before`. */
+export declare function introducesNewCycle(before: ReturnType<typeof findSlotCycles>, next: ReturnType<typeof findSlotCycles>): boolean;
+/** Candidate names that can be added to a slot without creating a new cycle. */
+export declare function computeAllowedComponentCandidates(projectSlotGraph: ComponentSlotInfo[], selfName: string, currentSlots: {
+    name: string;
+    allowedComponents: string[];
+}[], targetSlotName: string): string[];
+export declare function FieldEditor({ value, width, height, active, onChange, onSave, onDiscard, onExit, metadata, onTogglePropRationale, onToggleComponentRationale, onToggleSourceExternal, onTextEntryActiveChange, projectSlotGraph, currentComponentName, }: FieldEditorProps): React.ReactElement;
 export {};