@contentful/experience-design-system-cli 2.12.4-dev-build-9c819d8.0 → 2.13.1-dev-build-847dead.0

package/dist/src/analyze/extract/scoring.d.ts

@@ -1,12 +0,0 @@
-import type { RawComponentDefinition } from '../../types.js';
-export type ExtractionConfidence = 1 | 2 | 3 | 4 | 5;
-export type ExtractionScore = {
-    confidence: ExtractionConfidence;
-    reasons: string[];
-};
-export interface ExtractionScoreOptions {
-    additionalIssueCount?: number;
-    additionalReasons?: string[];
-}
-export declare function computeExtractionScore(component: RawComponentDefinition, options?: ExtractionScoreOptions): ExtractionScore;
-export declare function deriveNeedsReview(confidence: ExtractionConfidence): boolean;

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

@@ -1,108 +0,0 @@
-// Prop type strings that indicate the extractor couldn't resolve a concrete type
-const OPAQUE_TYPES = new Set(['any', 'unknown', 'object', 'Record<string, unknown>', 'Record<string, any>']);
-// Prop names that are non-obvious and benefit from a description
-const OBVIOUS_PROP_NAMES = new Set([
-    'className',
-    'style',
-    'id',
-    'children',
-    'disabled',
-    'hidden',
-    'onClick',
-    'onChange',
-    'onSubmit',
-    'onBlur',
-    'onFocus',
-    'href',
-    'src',
-    'alt',
-    'type',
-    'value',
-    'checked',
-    'placeholder',
-    'label',
-    'title',
-    'name',
-    'required',
-    'readOnly',
-    'autoFocus',
-    'tabIndex',
-    'role',
-    'aria-label',
-    'aria-describedby',
-]);
-// A union is "wide" if it mixes 3+ distinct base primitive types (ignoring nullability modifiers).
-// e.g. "string | number | boolean" → wide. "string | null | undefined" → NOT wide (just nullable string).
-function isWidePrimitiveUnion(type) {
-    const parts = type.split('|').map((p) => p.trim());
-    if (parts.length < 3)
-        return false;
-    const basePrimitives = new Set(['string', 'number', 'boolean']);
-    const nullability = new Set(['null', 'undefined']);
-    const baseCount = parts.filter((p) => basePrimitives.has(p)).length;
-    const nullabilityCount = parts.filter((p) => nullability.has(p)).length;
-    return baseCount >= 3 || (baseCount >= 2 && nullabilityCount > 0 && baseCount + nullabilityCount >= 3);
-}
-// Count the number of issues found for scoring
-function countIssues(component, options = {}) {
-    let count = 0;
-    const reasons = [];
-    if (component.props.length === 0 && component.slots.length === 0) {
-        count++;
-        reasons.push('no-props-or-slots');
-    }
-    if (component.props.length > 50) {
-        count++;
-        reasons.push(`high-prop-count:${component.props.length}`);
-    }
-    for (const prop of component.props) {
-        if (OPAQUE_TYPES.has(prop.type.trim())) {
-            count++;
-            reasons.push(`opaque-type:${prop.name}`);
-            break;
-        }
-        if (isWidePrimitiveUnion(prop.type)) {
-            count++;
-            reasons.push(`wide-union:${prop.name}`);
-            break;
-        }
-        if (!prop.description && !OBVIOUS_PROP_NAMES.has(prop.name)) {
-            count++;
-            reasons.push('props-missing-description');
-            break;
-        }
-    }
-    count += options.additionalIssueCount ?? 0;
-    if (options.additionalReasons && options.additionalReasons.length > 0) {
-        reasons.push(...options.additionalReasons);
-    }
-    return { count, reasons: [...new Set(reasons)] };
-}
-// Maps issue count to a 1–5 confidence scale:
-//   0 issues → 5 (clean)
-//   1 issue  → 4 (minor concern)
-//   2 issues → 3 (moderate concern)
-//   3 issues → 2 (significant concern)
-//   4+ issues → 1 (likely wrong)
-function issueCountToConfidence(count) {
-    if (count === 0)
-        return 5;
-    if (count === 1)
-        return 4;
-    if (count === 2)
-        return 3;
-    if (count === 3)
-        return 2;
-    return 1;
-}
-export function computeExtractionScore(component, options = {}) {
-    const { count, reasons } = countIssues(component, options);
-    return {
-        confidence: issueCountToConfidence(count),
-        reasons,
-    };
-}
-// Flag components scoring 2 or below for human review
-export function deriveNeedsReview(confidence) {
-    return confidence <= 2;
-}

package/dist/src/analyze/extract/slot-allowed-components.d.ts

@@ -1,8 +0,0 @@
-export interface AllowedComponentsContext {
-    /** e.g. { HeadingProps -> Heading, ButtonProps -> Button } */
-    propsToComponent: ReadonlyMap<string, string>;
-    /** ComponentType names known to the project (post-filter). */
-    componentNames: ReadonlySet<string>;
-}
-export declare function extractAllowedComponentsFromTypeText(typeText: string, ctx: AllowedComponentsContext): string[];
-export declare function extractAllowedComponentsFromJsdoc(jsdocText: string, componentNames: ReadonlySet<string>): string[];

package/dist/src/analyze/extract/slot-allowed-components.js

@@ -1,40 +0,0 @@
-// Matches ReactElement<XProps> and ReactElement<XProps, ...> (TS often
-// expands the second generic argument to string | JSXElementConstructor<any>).
-// Only the first generic argument (the props type name) is captured.
-const REACT_ELEMENT_GENERIC = /(?:React\.)?ReactElement\s*<\s*([A-Za-z_$][\w$.]*)(?![\w$.])/g;
-const SVELTE_SNIPPET_TUPLE = /Snippet\s*<\s*\[([^\]]*)\]\s*>/g;
-const IDENTIFIER = /[A-Za-z_$][\w$.]*/g;
-export function extractAllowedComponentsFromTypeText(typeText, ctx) {
-    const found = new Set();
-    const record = (propsTypeName) => {
-        const componentName = ctx.propsToComponent.get(propsTypeName);
-        if (componentName && ctx.componentNames.has(componentName))
-            found.add(componentName);
-    };
-    REACT_ELEMENT_GENERIC.lastIndex = 0;
-    let m;
-    while ((m = REACT_ELEMENT_GENERIC.exec(typeText)) !== null)
-        record(m[1]);
-    SVELTE_SNIPPET_TUPLE.lastIndex = 0;
-    while ((m = SVELTE_SNIPPET_TUPLE.exec(typeText)) !== null) {
-        const tupleBody = m[1];
-        IDENTIFIER.lastIndex = 0;
-        let id;
-        while ((id = IDENTIFIER.exec(tupleBody)) !== null)
-            record(id[0]);
-    }
-    return [...found].sort();
-}
-const JSDOC_TAG = /@allowedComponents\s+([^\n*]+)/;
-export function extractAllowedComponentsFromJsdoc(jsdocText, componentNames) {
-    const m = JSDOC_TAG.exec(jsdocText);
-    if (!m)
-        return [];
-    const found = new Set();
-    for (const raw of m[1].split(',')) {
-        const name = raw.trim();
-        if (name && componentNames.has(name))
-            found.add(name);
-    }
-    return [...found].sort();
-}

package/dist/src/analyze/extract/slot-detection.d.ts

@@ -1,35 +0,0 @@
-/**
- * Slot detection utilities for ReactNode-typed props.
- *
- * Props whose type resolves to ReactNode/ReactElement/JSX.Element are treated
- * as slots rather than plain props — unless their name is in the content-name
- * exception list (label, title, description, etc.).
- *
- * Array ReactNode types (e.g. ReactNode[]) ALWAYS become slots, even if the
- * prop name is in the exception list.
- */
-/**
- * Prop names that should remain as props even when typed as ReactNode.
- * These are typically text-content names, not composable slots.
- */
-export declare const CONTENT_NAME_EXCEPTIONS: Set<string>;
-/**
- * Checks if a type string represents a ReactNode/ReactElement/JSX.Element type,
- * including unions with null/undefined.
- */
-export declare function isReactNodeType(typeText: string): boolean;
-/**
- * Checks if a type string represents an array of ReactNode.
- * Examples: ReactNode[], React.ReactNode[], Array<ReactNode>
- */
-export declare function isArrayReactNodeType(typeText: string): boolean;
-/**
- * Determines whether a prop should be converted to a slot based on its name and type.
- *
- * Rules:
- * 1. If the type is not a ReactNode type → false
- * 2. If the type is an array ReactNode → true (overrides exception list)
- * 3. If the name is in the content-name exception list → false
- * 4. Otherwise → true
- */
-export declare function shouldBeSlot(propName: string, typeText: string): boolean;

package/dist/src/analyze/extract/slot-detection.js

@@ -1,101 +0,0 @@
-/**
- * Slot detection utilities for ReactNode-typed props.
- *
- * Props whose type resolves to ReactNode/ReactElement/JSX.Element are treated
- * as slots rather than plain props — unless their name is in the content-name
- * exception list (label, title, description, etc.).
- *
- * Array ReactNode types (e.g. ReactNode[]) ALWAYS become slots, even if the
- * prop name is in the exception list.
- */
-/**
- * Prop names that should remain as props even when typed as ReactNode.
- * These are typically text-content names, not composable slots.
- */
-export const CONTENT_NAME_EXCEPTIONS = new Set([
-    'label',
-    'title',
-    'description',
-    'text',
-    'caption',
-    'message',
-    'placeholder',
-    'tooltip',
-    'heading',
-    'subheading',
-    'body',
-    'summary',
-    'excerpt',
-]);
-const REACT_NODE_EXACT_PATTERNS = ['ReactNode', 'React.ReactNode', 'ReactElement', 'React.ReactElement', 'JSX.Element'];
-/**
- * Checks if a type string represents a ReactNode/ReactElement/JSX.Element type,
- * including unions with null/undefined.
- */
-export function isReactNodeType(typeText) {
-    const normalized = typeText.replace(/\s+/g, ' ').trim();
-    // Strip optional markers and union with null/undefined
-    const stripped = normalized
-        .split('|')
-        .map((part) => part.trim())
-        .filter((part) => part !== 'null' && part !== 'undefined')
-        .join(' | ');
-    // Check exact match (after stripping null/undefined union members)
-    if (REACT_NODE_EXACT_PATTERNS.includes(stripped)) {
-        return true;
-    }
-    // Check array patterns
-    if (isArrayReactNodeType(typeText)) {
-        return true;
-    }
-    return false;
-}
-/**
- * Checks if a type string represents an array of ReactNode.
- * Examples: ReactNode[], React.ReactNode[], Array<ReactNode>
- */
-export function isArrayReactNodeType(typeText) {
-    const normalized = typeText.replace(/\s+/g, ' ').trim();
-    // Strip optional markers and union with null/undefined
-    const stripped = normalized
-        .split('|')
-        .map((part) => part.trim())
-        .filter((part) => part !== 'null' && part !== 'undefined')
-        .join(' | ');
-    // Pattern: ReactNode[] or React.ReactNode[] etc.
-    for (const pattern of REACT_NODE_EXACT_PATTERNS) {
-        if (stripped === `${pattern}[]`) {
-            return true;
-        }
-    }
-    // Pattern: Array<ReactNode> or Array<React.ReactNode> etc.
-    for (const pattern of REACT_NODE_EXACT_PATTERNS) {
-        if (stripped === `Array<${pattern}>`) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Determines whether a prop should be converted to a slot based on its name and type.
- *
- * Rules:
- * 1. If the type is not a ReactNode type → false
- * 2. If the type is an array ReactNode → true (overrides exception list)
- * 3. If the name is in the content-name exception list → false
- * 4. Otherwise → true
- */
-export function shouldBeSlot(propName, typeText) {
-    if (!isReactNodeType(typeText)) {
-        return false;
-    }
-    // Array ReactNode always becomes a slot, even for exception names
-    if (isArrayReactNodeType(typeText)) {
-        return true;
-    }
-    // Check exception list
-    if (CONTENT_NAME_EXCEPTIONS.has(propName)) {
-        return false;
-    }
-    return true;
-}

package/dist/src/analyze/extract/source-inspection.d.ts

@@ -1,13 +0,0 @@
-import type { RawComponentDefinition } from '../../types.js';
-export declare const HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON = "data-fetch-wrapper";
-export declare const POSSIBLE_DATA_FETCH_WRAPPER_REASON = "possible-data-fetch-wrapper";
-export declare const ZERO_SURFACE_RENDERED_UI_REASON = "zero-surface:rendered-ui";
-export interface ComponentSourceInspection {
-    wrapperConfidence: 0 | 1 | 2 | 3 | 4 | 5;
-    reviewReasons: string[];
-    keepDespiteZeroSurface: boolean;
-}
-export declare function inspectComponentSource(component: RawComponentDefinition): Promise<ComponentSourceInspection>;
-export declare function isDataWrapperReviewReason(reason: string): boolean;
-export declare function describeReviewReason(reason: string): string;
-export declare function describeReviewReasons(reasons: string[]): string[];

package/dist/src/analyze/extract/source-inspection.js

@@ -1,189 +0,0 @@
-import { readFile } from 'node:fs/promises';
-export const HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON = 'data-fetch-wrapper';
-export const POSSIBLE_DATA_FETCH_WRAPPER_REASON = 'possible-data-fetch-wrapper';
-export const ZERO_SURFACE_RENDERED_UI_REASON = 'zero-surface:rendered-ui';
-const DATA_WRAPPER_REASON_PREFIX = 'data-wrapper:';
-const INFRA_PROP_NAMES = new Set(['id', 'locale', 'preview', 'slug', 'topic', 'previousComponent', '__typename']);
-const VISIBLE_UI_TAG_PATTERN = /<(?:[A-Z][A-Za-z0-9_.]*|div|span|section|main|article|header|footer|nav|aside|img|video|p|h[1-6]|ul|ol|li|button|input|textarea|select|form|label|table|tbody|thead|tr|td|th)\b/;
-const GENERATED_IMPORT_PATTERN = /from\s+['"][^'"]*__generated[^'"]*['"]/;
-const GENERATED_QUERY_HOOK_PATTERN = /\buse[A-Z][A-Za-z0-9]*(?:Lazy|Suspense)?Query\s*\(/;
-const GQL_FILENAME_PATTERN = /(?:-gql|-ggl)\.[cm]?[jt]sx?$/i;
-const LOADING_NULL_GUARD_PATTERN = /if\s*\([^)]*(?:isLoading|loading|!data|!\w+Collection|!\w+Item|!\w+)\s*[^)]*\)\s*return\s+null\b/;
-const IMPORT_PATTERN = /import\s+(?:type\s+)?(.+?)\s+from\s+['"]([^'"]+)['"]/g;
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function parseImportedNames(importClause) {
-    const trimmed = importClause.trim();
-    if (!trimmed)
-        return [];
-    const names = [];
-    const defaultAndNamed = trimmed.split(',').map((part) => part.trim());
-    for (const part of defaultAndNamed) {
-        if (!part)
-            continue;
-        if (part.startsWith('{') && part.endsWith('}')) {
-            for (const named of part
-                .slice(1, -1)
-                .split(',')
-                .map((item) => item.trim())
-                .filter(Boolean)) {
-                const [local] = named.split(/\s+as\s+/i);
-                if (local)
-                    names.push(local.trim());
-            }
-            continue;
-        }
-        const [local] = part.split(/\s+as\s+/i);
-        if (local)
-            names.push(local.trim());
-    }
-    return names;
-}
-function collectSiblingRendererImports(sourceText) {
-    const names = new Set();
-    for (const match of sourceText.matchAll(IMPORT_PATTERN)) {
-        const importClause = match[1]?.trim() ?? '';
-        const importPath = match[2]?.trim() ?? '';
-        if (!importPath.startsWith('./'))
-            continue;
-        if (importPath.includes('__generated'))
-            continue;
-        if (/-g(?:ql|gl)(?:$|\.)/i.test(importPath))
-            continue;
-        for (const name of parseImportedNames(importClause)) {
-            if (name)
-                names.add(name);
-        }
-    }
-    return [...names];
-}
-function hasSiblingForwardRender(sourceText, siblingImports) {
-    return siblingImports.some((name) => {
-        const renderPattern = new RegExp(`<${escapeRegExp(name)}\\b[\\s\\S]*?(?:/>|</${escapeRegExp(name)}>)`);
-        if (!renderPattern.test(sourceText))
-            return false;
-        const siblingSpreadPattern = new RegExp(`<${escapeRegExp(name)}\\b[^>]*\\{\\.\\.\\.(?!props\\b)[^}]+\\}`);
-        const propsPlusSiblingSpreadPattern = new RegExp(`<${escapeRegExp(name)}\\b[^>]*\\{\\.\\.\\.props\\}[^>]*\\{\\.\\.\\.(?!props\\b)[^}]+\\}`);
-        return siblingSpreadPattern.test(sourceText) || propsPlusSiblingSpreadPattern.test(sourceText);
-    });
-}
-function hasVisibleUiRender(sourceText) {
-    return /return\s*(?:\(|<)/.test(sourceText) && VISIBLE_UI_TAG_PATTERN.test(sourceText);
-}
-function infraPropNames(component) {
-    const props = component.props.map((prop) => prop.name);
-    return props.length > 0 && props.every((prop) => INFRA_PROP_NAMES.has(prop)) ? props : [];
-}
-function scoreToConfidence(score) {
-    if (score <= 0)
-        return 0;
-    if (score <= 2)
-        return 2;
-    if (score <= 4)
-        return 3;
-    if (score <= 6)
-        return 4;
-    return 5;
-}
-function dedupeReasons(reasons) {
-    return [...new Set(reasons)];
-}
-export async function inspectComponentSource(component) {
-    let sourceText = '';
-    try {
-        sourceText = await readFile(component.source, 'utf8');
-    }
-    catch {
-        return {
-            wrapperConfidence: 0,
-            reviewReasons: [],
-            keepDespiteZeroSurface: false,
-        };
-    }
-    const reviewReasons = [];
-    let wrapperScore = 0;
-    const hasGeneratedQueryHook = GENERATED_IMPORT_PATTERN.test(sourceText) && GENERATED_QUERY_HOOK_PATTERN.test(sourceText);
-    const infraProps = infraPropNames(component);
-    const siblingImports = collectSiblingRendererImports(sourceText);
-    if (GQL_FILENAME_PATTERN.test(component.source)) {
-        reviewReasons.push('data-wrapper:gql-filename');
-        wrapperScore += 1;
-    }
-    if (hasGeneratedQueryHook) {
-        reviewReasons.push('data-wrapper:generated-query-hook');
-        wrapperScore += 3;
-    }
-    // Require corroboration from a stronger signal before counting sibling imports —
-    // otherwise any composed component that imports two sub-components scores +1 here.
-    if (siblingImports.length > 0 && (hasGeneratedQueryHook || infraProps.length > 0)) {
-        reviewReasons.push('data-wrapper:sibling-renderer-import');
-        wrapperScore += 1;
-    }
-    if (hasSiblingForwardRender(sourceText, siblingImports)) {
-        reviewReasons.push('data-wrapper:fetch-forward-render');
-        wrapperScore += 3;
-    }
-    if (sourceText.includes('useContentfulLiveUpdates(') || sourceText.includes('useContentfulContext(')) {
-        reviewReasons.push('data-wrapper:contentful-runtime');
-        wrapperScore += 1;
-    }
-    if (infraProps.length > 0) {
-        reviewReasons.push('data-wrapper:infra-props');
-        wrapperScore += 2;
-    }
-    if (LOADING_NULL_GUARD_PATTERN.test(sourceText)) {
-        reviewReasons.push('data-wrapper:loading-null-guard');
-        wrapperScore += 1;
-    }
-    const wrapperConfidence = scoreToConfidence(wrapperScore);
-    if (wrapperConfidence >= 4) {
-        reviewReasons.unshift(HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON);
-    }
-    else if (wrapperConfidence === 3) {
-        reviewReasons.unshift(POSSIBLE_DATA_FETCH_WRAPPER_REASON);
-    }
-    const keepDespiteZeroSurface = component.props.length === 0 && component.slots.length === 0 && hasVisibleUiRender(sourceText);
-    if (keepDespiteZeroSurface) {
-        reviewReasons.push(ZERO_SURFACE_RENDERED_UI_REASON);
-    }
-    return {
-        wrapperConfidence,
-        reviewReasons: dedupeReasons(reviewReasons),
-        keepDespiteZeroSurface,
-    };
-}
-export function isDataWrapperReviewReason(reason) {
-    return (reason === HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON ||
-        reason === POSSIBLE_DATA_FETCH_WRAPPER_REASON ||
-        reason.startsWith(DATA_WRAPPER_REASON_PREFIX));
-}
-export function describeReviewReason(reason) {
-    switch (reason) {
-        case HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON:
-            return 'high-confidence data-fetch wrapper';
-        case POSSIBLE_DATA_FETCH_WRAPPER_REASON:
-            return 'possible data-fetch wrapper';
-        case 'data-wrapper:gql-filename':
-            return 'source file follows a gql wrapper naming pattern';
-        case 'data-wrapper:generated-query-hook':
-            return 'imports and calls a generated query hook';
-        case 'data-wrapper:sibling-renderer-import':
-            return 'imports a sibling renderer from the same folder';
-        case 'data-wrapper:fetch-forward-render':
-            return 'forwards fetched data into a sibling renderer';
-        case 'data-wrapper:contentful-runtime':
-            return 'uses Contentful runtime hooks';
-        case 'data-wrapper:infra-props':
-            return 'only exposes infra-fetch props';
-        case 'data-wrapper:loading-null-guard':
-            return 'returns early while loading or when fetched data is missing';
-        case ZERO_SURFACE_RENDERED_UI_REASON:
-            return 'source renders visible/compositional UI despite zero extracted props and slots';
-        default:
-            return reason;
-    }
-}
-export function describeReviewReasons(reasons) {
-    return dedupeReasons(reasons.map(describeReviewReason));
-}

package/dist/src/analyze/extract/stencil.d.ts

@@ -1,2 +0,0 @@
-import type { ComponentExtractionResult } from '../../types.js';
-export declare function extractStencilComponents(filePaths: string[]): Promise<ComponentExtractionResult>;