@contentful/experience-design-system-cli 2.5.2 → 2.5.3-dev-build-b2e98f1.0

package/README.md

@@ -12,6 +12,8 @@ analyze extract   →   analyze select-agent   →   generate components   →
 
 `analyze select-agent` uses an AI agent to decide which extracted components belong in Contentful Experience Orchestration. You can substitute it with `analyze select` for manual/pattern-based selection.
 
+**Determinism boundary.** `analyze extract` is fully deterministic: ts-morph AST parsing produces the same component list and prop shape on every run, then a deterministic pre-classifier and a structural non-authorable filter (see below) shape the output. AI enters the pipeline at `analyze select-agent` and `generate components`, where coding agents make per-component decisions. This split keeps the extracted artifact reproducible and inspectable — if an extracted component looks wrong, the cause is in the rules, not in agent variability.
+
 All intermediate data flows through a local SQLite session database (`~/.contentful/experience-design-system-cli/pipeline.db`). No JSON files are written between steps — each command reads its inputs from the session and writes its outputs back to it. Use `print` to export session data to JSON files on demand (e.g. for inspection or manual validation).
 
 ---
@@ -91,6 +93,18 @@ Scans `.tsx`, `.ts`, `.jsx`, `.js`, `.vue`, and `.astro` files. Ignores `node_mo
 
 Writes extracted components to the session database and prints `session=<id>` to stdout. In an interactive terminal, a scrollable TUI displays the extraction summary (including a warning for any components with 0 props and 0 slots); press `q` or `Enter` to exit.
 
+#### Non-authorable component filter
+
+Before storing components, `analyze extract` runs a deterministic filter that drops infrastructure components which have no authoring surface (Context providers, analytics shims, security utilities, layout helpers). The filter uses prop-shape signals only — no component-name or source-path patterns — so it works regardless of how a host repo organizes its design system. A component is dropped if **any** of:
+
+1. Zero props and zero slots.
+2. Source calls `createContext()` and the component has a prop literally named `value`.
+3. Source calls `createContext()` and the component has zero props.
+4. Source calls `createContext()` and the component has exactly one non-handler prop.
+5. Every prop is a handler or ref (function-typed, `EventHandler`, `Dispatch`, `SetStateAction`, `Ref<>`, name starts with `on`/`set`, or named `ref`/`innerRef`).
+
+Each dropped component is reported as a warning (`Skipped non-authorable component: <Name> (<reason>)`) so the operator can audit. The rule set was selected via Monte-Carlo evaluation against a hand-labelled corpus to maximize precision (zero false positives) over recall — components that look like normal authoring surface but are actually infrastructure are deferred to the AI selection stage rather than dropped here.
+
 ---
 
 ### `analyze select`

package/dist/package.json

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

package/dist/src/analyze/command.js

@@ -8,6 +8,7 @@ import { registerAnalyzeEditCommand } from './select/command.js';
 import { registerAnalyzeSelectAgentCommand } from './select-agent/command.js';
 import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents } from '../session/db.js';
 import { preClassifyComponent } from './pre-classify.js';
+import { isNonAuthorableComponent } from './extract/non-authorable-filter.js';
 const SCANNED_FILE_EXTENSIONS = new Set(['.astro', '.js', '.jsx', '.ts', '.tsx', '.vue']);
 const IGNORED_DIRECTORY_NAMES = new Set([
     '.git',
@@ -121,23 +122,32 @@ export function registerAnalyzeCommand(program) {
         });
         const stepId = createStep(db, sessionId, 'analyze extract', { project: projectRoot });
         const classifiedComponents = extraction.components.map(preClassifyComponent);
-        storeRawComponents(db, sessionId, classifiedComponents);
+        const filteredComponents = [];
+        const filterWarnings = [];
+        for (const component of classifiedComponents) {
+            const verdict = isNonAuthorableComponent(component);
+            if (verdict.skip) {
+                filterWarnings.push(`Skipped non-authorable component: ${component.name} (${verdict.reason})`);
+                continue;
+            }
+            filteredComponents.push(component);
+        }
+        storeRawComponents(db, sessionId, filteredComponents);
         updateStep(db, stepId, 'complete', { sessionId });
         db.close();
-        const zeroPropComponents = classifiedComponents.filter((c) => c.props.length === 0 && c.slots.length === 0);
+        const allWarnings = [...extraction.warnings, ...filterWarnings];
         const analyzeResult = {
             sourceDirectory,
             sessionId,
             fileCount: sourceFiles.length,
-            components: classifiedComponents.map((c) => ({
+            components: filteredComponents.map((c) => ({
                 name: c.name,
                 framework: c.framework,
                 propCount: c.props.length,
                 slotCount: c.slots.length,
-                warnings: extraction.warnings.filter((w) => w.startsWith(c.name + ':')),
+                warnings: allWarnings.filter((w) => w.startsWith(c.name + ':')),
             })),
-            totalWarnings: extraction.warnings.length,
-            zeroPropComponents: zeroPropComponents.map((c) => ({ name: c.name, source: c.source })),
+            totalWarnings: allWarnings.length,
         };
         if (process.stdout.isTTY) {
             const { waitUntilExit } = render(createElement(AnalyzeView, {
@@ -153,15 +163,9 @@ export function registerAnalyzeCommand(program) {
                 `Scanned ${pluralize(sourceFiles.length, 'source file')} in ${sourceDirectory}`,
                 `Extracted ${pluralize(extraction.components.length, 'component')}`,
             ];
-            if (zeroPropComponents.length > 0) {
-                summaryLines.push(`Warning: ${pluralize(zeroPropComponents.length, 'component')} extracted with 0 props and 0 slots:`);
-                summaryLines.push(...zeroPropComponents.map((c) => `  ${c.name} (${c.source})`));
-                summaryLines.push('These may be Storybook stories, context providers, or SSR utilities.');
-                summaryLines.push("Review them in 'analyze select' before generating.");
-            }
-            if (extraction.warnings.length > 0) {
-                summaryLines.push(`Warnings (${extraction.warnings.length}):`);
-                summaryLines.push(...extraction.warnings.map((w) => `- ${w}`));
+            if (allWarnings.length > 0) {
+                summaryLines.push(`Warnings (${allWarnings.length}):`);
+                summaryLines.push(...allWarnings.map((w) => `- ${w}`));
             }
             else {
                 summaryLines.push('Warnings: none');

package/dist/src/analyze/extract/non-authorable-filter.d.ts

@@ -0,0 +1,16 @@
+import type { RawComponentDefinition } from '../../types.js';
+export interface NonAuthorableResult {
+    skip: boolean;
+    reason?: string;
+}
+/**
+ * Decides whether a component is non-authorable infrastructure (Context.Provider,
+ * analytics shim, layout-only utility, etc.) and should be filtered out of the
+ * analyze TUI before authoring-token generation.
+ *
+ * Uses prop-shape signals only — no component-name or source-path patterns.
+ * A design system can live anywhere under any naming convention; relying on
+ * suffixes like `*Provider` or paths like `src/lib/` would silently fail in
+ * other repos.
+ */
+export declare function isNonAuthorableComponent(component: RawComponentDefinition): NonAuthorableResult;

package/dist/src/analyze/extract/non-authorable-filter.js

@@ -0,0 +1,60 @@
+const HANDLER_TYPE_PATTERN = /=>|EventHandler|Dispatch<|SetStateAction/;
+const REF_TYPE_PATTERN = /Ref<|RefObject<|MutableRefObject/;
+function isHandlerOrRefProp(prop) {
+    if (HANDLER_TYPE_PATTERN.test(prop.type))
+        return true;
+    if (REF_TYPE_PATTERN.test(prop.type))
+        return true;
+    if (/^on[A-Z]/.test(prop.name) || /^set[A-Z]/.test(prop.name))
+        return true;
+    if (prop.name === 'ref' || prop.name === 'innerRef')
+        return true;
+    return false;
+}
+/**
+ * Decides whether a component is non-authorable infrastructure (Context.Provider,
+ * analytics shim, layout-only utility, etc.) and should be filtered out of the
+ * analyze TUI before authoring-token generation.
+ *
+ * Uses prop-shape signals only — no component-name or source-path patterns.
+ * A design system can live anywhere under any naming convention; relying on
+ * suffixes like `*Provider` or paths like `src/lib/` would silently fail in
+ * other repos.
+ */
+export function isNonAuthorableComponent(component) {
+    const { props, slots, usesCreateContext } = component;
+    // R1: zero props AND zero slots — nothing for an editor to author.
+    // Catches analytics scripts, GTM tags, layout fixers, security tokens, etc.
+    if (props.length === 0 && slots.length === 0) {
+        return { skip: true, reason: 'component has no props and no slots' };
+    }
+    // R2: createContext source + prop literally named `value` — canonical
+    // `<Context.Provider value={...}>` call site.
+    if (usesCreateContext && props.some((p) => p.name === 'value')) {
+        return {
+            skip: true,
+            reason: 'source uses createContext and component exposes a Context.Provider value prop',
+        };
+    }
+    // R3: createContext source + zero props — Provider wrapper that hard-codes
+    // the context value internally (e.g. FontProvider, BottomSheetProvider).
+    if (usesCreateContext && props.length === 0) {
+        return { skip: true, reason: 'source uses createContext and component has no props' };
+    }
+    // R4: createContext source + exactly one non-handler prop — Provider that
+    // takes the context value as its sole data prop, named after the data
+    // (e.g. `LocaleProvider({ locale })`, `NavigationProvider({ navItems })`).
+    if (usesCreateContext && props.length === 1 && !isHandlerOrRefProp(props[0])) {
+        return {
+            skip: true,
+            reason: 'source uses createContext and component has a single non-handler prop',
+        };
+    }
+    // R5: every prop is a handler/ref — pure data plumbing, no authoring surface.
+    // Catches components like `OsanoCookiePlaceholder({ onBannerLoaded })` or
+    // `FeedbackCard({ setShowModal })`.
+    if (props.length > 0 && props.every(isHandlerOrRefProp)) {
+        return { skip: true, reason: 'every prop is a handler or ref' };
+    }
+    return { skip: false };
+}

package/dist/src/analyze/extract/react.js

@@ -233,6 +233,14 @@ function getBoundedImportedJsxDomSurface(tagNameNode) {
 function isStencilFile(sourceFile) {
     return sourceFile.getImportDeclarations().some((imp) => imp.getModuleSpecifierValue() === '@stencil/core');
 }
+function sourceFileUsesCreateContext(sourceFile) {
+    // Match React.createContext(...) and createContext(...) call expressions
+    return sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression).some((call) => {
+        const expr = call.getExpression();
+        const text = expr.getText();
+        return text === 'createContext' || text === 'React.createContext';
+    });
+}
 function isNextJsComponent(filePath, exportedNames) {
     const normalized = filePath.replace(/\\/g, '/');
     const isAppRouterFile = /\/app\/.*\/(page|layout)\.[jt]sx?$/.test(normalized);
@@ -1634,6 +1642,7 @@ export async function extractReactComponents(filePaths) {
 function extractFromSourceFile(sourceFile, isNext) {
     const components = [];
     const exported = sourceFile.getExportedDeclarations();
+    const usesCreateContext = sourceFileUsesCreateContext(sourceFile);
     for (const [exportKey, declarations] of exported) {
         let name = exportKey;
         if (exportKey === 'default') {
@@ -1668,6 +1677,7 @@ function extractFromSourceFile(sourceFile, isNext) {
                 framework: isNext ? 'next' : 'react',
                 props: [],
                 slots: [],
+                ...(usesCreateContext && { usesCreateContext: true }),
             });
             continue;
         }
@@ -1752,6 +1762,7 @@ function extractFromSourceFile(sourceFile, isNext) {
             framework: isNext ? 'next' : 'react',
             props: propsAfterSlotExpansion,
             slots: finalSlots,
+            ...(usesCreateContext && { usesCreateContext: true }),
         });
     }
     return components;

package/dist/src/analyze/tui/AnalyzeView.d.ts

@@ -11,10 +11,6 @@ export type AnalyzeViewResult = {
         warnings: string[];
     }>;
     totalWarnings: number;
-    zeroPropComponents?: Array<{
-        name: string;
-        source: string;
-    }>;
 };
 type AnalyzeViewProps = {
     result: AnalyzeViewResult;

package/dist/src/analyze/tui/AnalyzeView.js

@@ -31,7 +31,7 @@ export function AnalyzeView({ result, onExit }) {
     return (_jsxs(Box, { flexDirection: "column", children: [_jsx(TopBar, { subcommand: "analyze", hints: [
                     { key: '?', label: 'help' },
                     { key: 'q', label: 'quit' },
-                ] }), _jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsx(Text, { children: 'Scanned ' + result.fileCount + ' source files in ' + result.sourceDirectory }), _jsx(Text, { children: 'Extracted ' + result.components.length + ' components' }), _jsx(Text, { dimColor: true, children: 'Session: ' + result.sessionId }), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, children: "Components" }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components.slice(scrollOffset).map((component) => (_jsxs(Box, { children: [component.warnings.length > 0 && _jsx(Text, { color: "yellow", children: "\u26A0 " }), component.warnings.length === 0 && _jsx(Text, { children: " " }), _jsx(Text, { children: truncateName(component.name).padEnd(20) }), _jsx(Text, { dimColor: true, children: component.framework.padEnd(10) }), _jsx(Text, { children: (component.propCount + ' props').padEnd(10) }), _jsx(Text, { children: component.slotCount + ' ' + (component.slotCount === 1 ? 'slot' : 'slots') }), component.warnings.length > 0 && (_jsx(Text, { color: "yellow", children: '  ' + component.warnings.length + ' warning' + (component.warnings.length === 1 ? '' : 's') }))] }, component.name))), result.zeroPropComponents && result.zeroPropComponents.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, color: "yellow", children: 'Zero-prop components (' + result.zeroPropComponents.length + ')' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { color: "yellow", children: '  These may be Storybook stories, context providers, or SSR utilities.' }), _jsx(Text, { color: "yellow", children: '  Review them in `analyze select` before generating.' }), _jsx(Text, { children: " " }), result.zeroPropComponents.map((c) => (_jsx(Text, { color: "yellow", children: '  ' + c.name + ' (' + c.source + ')' }, c.name)))] })), result.totalWarnings > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, color: "yellow", children: 'Warnings (' + result.totalWarnings + ')' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components
+                ] }), _jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsx(Text, { children: 'Scanned ' + result.fileCount + ' source files in ' + result.sourceDirectory }), _jsx(Text, { children: 'Extracted ' + result.components.length + ' components' }), _jsx(Text, { dimColor: true, children: 'Session: ' + result.sessionId }), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, children: "Components" }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components.slice(scrollOffset).map((component) => (_jsxs(Box, { children: [component.warnings.length > 0 && _jsx(Text, { color: "yellow", children: "\u26A0 " }), component.warnings.length === 0 && _jsx(Text, { children: " " }), _jsx(Text, { children: truncateName(component.name).padEnd(20) }), _jsx(Text, { dimColor: true, children: component.framework.padEnd(10) }), _jsx(Text, { children: (component.propCount + ' props').padEnd(10) }), _jsx(Text, { children: component.slotCount + ' ' + (component.slotCount === 1 ? 'slot' : 'slots') }), component.warnings.length > 0 && (_jsx(Text, { color: "yellow", children: '  ' + component.warnings.length + ' warning' + (component.warnings.length === 1 ? '' : 's') }))] }, component.name))), result.totalWarnings > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, color: "yellow", children: 'Warnings (' + result.totalWarnings + ')' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components
                                 .filter((c) => c.warnings.length > 0)
                                 .flatMap((c) => c.warnings.map((w) => ({ component: c.name, warning: w })))
                                 .map((w, i) => (_jsx(Text, { color: "yellow", children: '  ⚠ ' + w.component + ': ' + w.warning }, i)))] })), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: 'Run: analyze select --session ' + result.sessionId }), _jsx(Text, { children: " " })] }), _jsx(Box, { borderStyle: "single", paddingX: 1, children: _jsx(Text, { dimColor: true, children: "Press Enter or q to exit" }) })] }));

package/dist/src/apply/api-client.js

@@ -48,12 +48,8 @@ export class ImportApiClient {
         };
     }
     async validateToken() {
-        // /users/me is the canonical "is this token valid" endpoint — it doesn't enforce
-        // space-membership rules that don't apply to the design-systems API path, so it
-        // doesn't false-positive 401 for tokens that are entitled to call import endpoints
-        // but lack the role assignments public CMA's SpacesController/EnvironmentsController
-        // require. Per-space/per-org authorization is enforced by the design-systems API itself
-        // on the actual preview/apply call.
+        // /users/me is the canonical token-validity endpoint — avoids space-membership
+        // false positives that don't apply to the design-systems API authorization path.
         const url = `${this.host}/users/me`;
         const res = await request(url, { token: this.token });
         if (res.status === 401) {

package/dist/src/apply/command.js

@@ -1,5 +1,5 @@
-import { createElement } from 'react';
-import { render } from 'ink';
+import { createElement, useState } from 'react';
+import { render, useInput } from 'ink';
 import { access, readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { validateCDF, flattenDTCG, validateDTCG, buildManifest, buildFilteredManifest, } from '@contentful/experience-design-system-types';
@@ -7,8 +7,6 @@ import { ApiError, ImportApiClient } from './api-client.js';
 import { openPipelineDb, loadCDFComponents } from '../session/db.js';
 import { ServerPreviewApp, ServerPreviewConfirm, ServerApplyProgress, ServerApplyDone } from './tui/ServerApplyView.js';
 import { SelectView, makeSelectKey } from './tui/SelectView.js';
-import { useState } from 'react';
-import { useInput } from 'ink';
 function die(message) {
     process.stderr.write(`${message}\n`);
     process.exit(1);

package/dist/src/types.d.ts

@@ -28,6 +28,12 @@ export interface RawComponentDefinition {
     framework: 'react' | 'next' | 'vue' | 'astro' | 'web-component' | 'stencil';
     props: RawPropDefinition[];
     slots: RawSlotDefinition[];
+    /**
+     * True when the source file declaring this component calls
+     * React.createContext / createContext. Used downstream to filter
+     * non-authorable context-provider components.
+     */
+    usesCreateContext?: boolean;
 }
 export interface ComponentExtractionResult {
     components: RawComponentDefinition[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.5.2",
+  "version": "2.5.3-dev-build-b2e98f1.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,7 @@
     "react-dom": "^18.3.1",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.5.2"
+    "@contentful/experience-design-system-types": "2.5.3-dev-build-b2e98f1.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/skills/generate-components.md

@@ -109,7 +109,7 @@ Exactly **6** valid types:
 | `token` | Design-token-linked prop — requires `token_kind` |
 | `boolean` | Boolean toggle props (visible, disabled, enabled, etc.) |
 
-> **IMPORTANT: No `number` type.** The EMA Phase 2 API only supports the `String` design property variant for numeric values. All numeric props must use `cdf_type: "string"` with the number as a string default (e.g. `"0"`, `"100"`). Boolean props can now use `cdf_type: "boolean"` directly.
+> **IMPORTANT: No `number` type.** The design-systems API only supports the `String` design property variant for numeric values. All numeric props must use `cdf_type: "string"` with the number as a string default (e.g. `"0"`, `"100"`). Boolean props can now use `cdf_type: "boolean"` directly.
 
 > **Avoid `link` type for simple URL props.** Props named `href`, `url`, or holding plain URL strings → `cdf_type: "string"`, `cdf_category: "content"`. Reserve `link` for props that hold a reference to another Contentful entry.
 
@@ -337,7 +337,7 @@ Before emitting any tool calls, verify:
 7. `required` values are JSON booleans, not strings
 8. Framework internals (`ref`, event handlers, test IDs) are excluded — `className`, `style`, and `styles` are classified as `string` design props; discrete positional/geometric props (`top`, `bottom`, `left`, `right`, `rotation`, etc.) are also classified
 9. No `cdf_type: "link"` used — `link` is reserved and rejected by the CLI parser
-10. No `cdf_type: "number"` used — this is not a valid P2 type; use `"string"` with numeric defaults. `cdf_type: "boolean"` IS valid — use it for boolean toggle props.
+10. No `cdf_type: "number"` used — this is not a supported type; use `"string"` with numeric defaults. `cdf_type: "boolean"` IS valid — use it for boolean toggle props.
 
 After the run completes, the developer can validate the pipeline output with: