@contentful/experience-design-system-extraction 2.36.2-dev-build-a6f80ae6.0 → 2.36.2-dev-build-7907fec3.0

package/dist/src/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/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/extract/slot-detection.js

@@ -1,98 +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'];
-function normalizeReactNodeType(typeText) {
-    return typeText
-        .replace(/\s+/g, ' ')
-        .trim()
-        .split('|')
-        .map((part) => part.trim())
-        .filter((part) => part !== 'null' && part !== 'undefined')
-        .join(' | ');
-}
-/**
- * Checks if a type string represents a ReactNode/ReactElement/JSX.Element type,
- * including unions with null/undefined.
- */
-export function isReactNodeType(typeText) {
-    const stripped = normalizeReactNodeType(typeText);
-    // 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 stripped = normalizeReactNodeType(typeText);
-    // 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/extract/stencil.js

@@ -1,312 +0,0 @@
-import { Project, Node, SyntaxKind } from 'ts-morph';
-import { getJsxTagNameNode, isIntrinsicJsxElement, kebabToPascal } from './tsx-shared.js';
-import { createSortedExtractionResult, extractProjectSourceFiles } from './file-extraction-workers.js';
-function isStencilFile(sourceFile) {
-    return sourceFile.getImportDeclarations().some((imp) => imp.getModuleSpecifierValue() === '@stencil/core');
-}
-function getComponentTag(classDecl) {
-    for (const decorator of classDecl.getDecorators()) {
-        if (decorator.getName() !== 'Component')
-            continue;
-        const args = decorator.getArguments();
-        if (args.length === 0)
-            continue;
-        const arg = args[0];
-        if (!Node.isObjectLiteralExpression(arg))
-            continue;
-        const tagProp = arg.getProperty('tag');
-        if (!tagProp || !Node.isPropertyAssignment(tagProp))
-            continue;
-        const initializer = tagProp.getInitializer();
-        if (!initializer || !Node.isStringLiteral(initializer))
-            continue;
-        return initializer.getLiteralValue();
-    }
-    return undefined;
-}
-function hasDecorator(node, decoratorName) {
-    if (!Node.isPropertyDeclaration(node))
-        return false;
-    return node.getDecorators().some((d) => d.getName() === decoratorName);
-}
-function extractAllowedValues(typeText) {
-    // Match inline string literal unions: 'a' | 'b' | 'c'
-    const literalPattern = /^'[^']*'(?:\s*\|\s*'[^']*')+$/;
-    if (!literalPattern.test(typeText.trim()))
-        return undefined;
-    const values = typeText
-        .split('|')
-        .map((v) => v.trim().replace(/^'|'$/g, ''))
-        .filter(Boolean)
-        .sort();
-    return values.length >= 2 ? values : undefined;
-}
-function collectIntrinsicDomAttributeProps(classDecl, propNames) {
-    const domAttributeProps = new Set();
-    const renderMethod = classDecl.getMethod('render');
-    if (!renderMethod)
-        return domAttributeProps;
-    for (const attribute of renderMethod.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
-        const tagName = getJsxTagNameNode(attribute)?.getText();
-        const attributeName = attribute.getNameNode().getText();
-        if (!tagName || !propNames.has(attributeName) || !isIntrinsicJsxElement(tagName)) {
-            continue;
-        }
-        const initializer = attribute.getInitializer();
-        if (!initializer || !Node.isJsxExpression(initializer))
-            continue;
-        const expression = initializer.getExpression();
-        if (!expression || !Node.isPropertyAccessExpression(expression))
-            continue;
-        if (!Node.isThisExpression(expression.getExpression()))
-            continue;
-        if (expression.getName() !== attributeName)
-            continue;
-        domAttributeProps.add(attributeName);
-    }
-    return domAttributeProps;
-}
-function extractProps(classDecl) {
-    const props = [];
-    const propNames = new Set(classDecl
-        .getProperties()
-        .filter((property) => hasDecorator(property, 'Prop'))
-        .map((property) => property.getName()));
-    const intrinsicDomAttributeProps = collectIntrinsicDomAttributeProps(classDecl, propNames);
-    for (const property of classDecl.getProperties()) {
-        if (!hasDecorator(property, 'Prop'))
-            continue;
-        const name = property.getName();
-        const typeNode = property.getTypeNode();
-        const typeText = typeNode ? typeNode.getText() : 'unknown';
-        const hasQuestionToken = property.hasQuestionToken();
-        const hasExclamation = property.hasExclamationToken();
-        const initializer = property.getInitializer();
-        let defaultValue;
-        if (initializer) {
-            if (Node.isStringLiteral(initializer)) {
-                defaultValue = initializer.getLiteralValue();
-            }
-            else {
-                defaultValue = initializer.getText();
-            }
-        }
-        const isRequired = hasExclamation || (!hasQuestionToken && !initializer);
-        // JSDoc description
-        const jsDocs = property.getJsDocs();
-        let description;
-        let isDeprecated = false;
-        if (jsDocs.length > 0) {
-            const jsDoc = jsDocs[0];
-            description = jsDoc.getDescription().trim() || undefined;
-            for (const tag of jsDoc.getTags()) {
-                if (tag.getTagName() === 'deprecated') {
-                    isDeprecated = true;
-                    // The deprecated tag may carry a message (e.g. "@deprecated Use size instead.")
-                    const tagComment = tag.getCommentText()?.trim();
-                    if (tagComment && !description) {
-                        description = tagComment;
-                    }
-                }
-            }
-        }
-        if (isDeprecated && description) {
-            description = `[DEPRECATED] ${description}`;
-        }
-        else if (isDeprecated) {
-            description = '[DEPRECATED]';
-        }
-        const allowedValues = extractAllowedValues(typeText);
-        props.push({
-            name,
-            type: typeText,
-            required: isRequired,
-            ...(defaultValue !== undefined && { defaultValue }),
-            ...(description && { description }),
-            ...(allowedValues && { allowedValues }),
-            ...(intrinsicDomAttributeProps.has(name) && { domAttribute: true }),
-            sourceStartLine: property.getStartLineNumber(),
-            sourceEndLine: property.getEndLineNumber(),
-        });
-    }
-    return props.sort((a, b) => a.name.localeCompare(b.name));
-}
-function normalizeSlotName(name) {
-    const normalizedName = name && name.length > 0 ? name : 'default';
-    return {
-        name: normalizedName,
-        isDefault: normalizedName === 'default',
-    };
-}
-function extractSlots(classDecl, warnings, componentName) {
-    const slots = new Map();
-    const upsertSlot = (slot) => {
-        const existing = slots.get(slot.name);
-        if (!existing) {
-            slots.set(slot.name, slot);
-            return;
-        }
-        slots.set(slot.name, {
-            ...existing,
-            ...slot,
-            description: existing.description ?? slot.description,
-        });
-    };
-    const jsDocs = classDecl.getJsDocs();
-    for (const jsDoc of jsDocs) {
-        for (const tag of jsDoc.getTags()) {
-            if (tag.getTagName() !== 'slot')
-                continue;
-            const comment = tag.getCommentText()?.trim();
-            if (!comment)
-                continue;
-            if (comment.startsWith('{')) {
-                try {
-                    const parsed = JSON.parse(comment);
-                    const slot = normalizeSlotName(parsed.name);
-                    let description = parsed.description || undefined;
-                    if (parsed.isDeprecated && description) {
-                        description = `[DEPRECATED] ${description}`;
-                    }
-                    else if (parsed.isDeprecated) {
-                        description = '[DEPRECATED]';
-                    }
-                    upsertSlot({
-                        ...slot,
-                        ...(description && { description }),
-                    });
-                    continue;
-                }
-                catch {
-                    warnings.push(`Failed to parse @slot JSDoc in ${componentName}: invalid JSON "${comment}"`);
-                    continue;
-                }
-            }
-            const match = comment.match(/^(?:(\S+)\s*-\s*)?(.*)$/s);
-            if (!match)
-                continue;
-            const [, rawName, rawDescription] = match;
-            const slot = normalizeSlotName(rawName);
-            const description = rawDescription.trim() || undefined;
-            upsertSlot({
-                ...slot,
-                ...(description && { description }),
-            });
-        }
-    }
-    for (const method of classDecl.getMethods()) {
-        method.forEachDescendant((node) => {
-            if (!Node.isJsxSelfClosingElement(node) && !Node.isJsxElement(node))
-                return;
-            const openingElement = Node.isJsxElement(node) ? node.getOpeningElement() : node;
-            const tagName = openingElement.getTagNameNode().getText();
-            const slotAttribute = openingElement
-                .getAttributes()
-                .find((attribute) => Node.isJsxAttribute(attribute) && attribute.getNameNode().getText() === 'slot');
-            if (tagName === 'slot') {
-                const nameAttribute = openingElement
-                    .getAttributes()
-                    .find((attribute) => Node.isJsxAttribute(attribute) && attribute.getNameNode().getText() === 'name');
-                const initializer = Node.isJsxAttribute(nameAttribute) ? nameAttribute.getInitializer() : undefined;
-                const name = initializer && Node.isStringLiteral(initializer)
-                    ? initializer.getLiteralValue()
-                    : initializer && Node.isJsxExpression(initializer)
-                        ? (initializer.getExpression()?.getText() ?? '')
-                        : '';
-                upsertSlot({
-                    ...normalizeSlotName(name),
-                });
-                return;
-            }
-            if (!Node.isJsxAttribute(slotAttribute))
-                return;
-            const initializer = slotAttribute.getInitializer();
-            if (!initializer || !Node.isStringLiteral(initializer))
-                return;
-            const name = initializer.getLiteralValue();
-            if (!name)
-                return;
-            upsertSlot({
-                name,
-                isDefault: false,
-            });
-        });
-    }
-    return [...slots.values()].sort((a, b) => a.name.localeCompare(b.name));
-}
-function detectEvents(classDecl) {
-    const eventNames = [];
-    for (const property of classDecl.getProperties()) {
-        if (!hasDecorator(property, 'Event'))
-            continue;
-        eventNames.push(property.getName());
-    }
-    return eventNames.sort();
-}
-function extractFromSourceFile(sourceFile, warnings) {
-    const components = [];
-    for (const classDecl of sourceFile.getClasses()) {
-        const tag = getComponentTag(classDecl);
-        if (!tag)
-            continue;
-        const name = kebabToPascal(tag);
-        const props = extractProps(classDecl);
-        const slots = extractSlots(classDecl, warnings, name);
-        const eventNames = detectEvents(classDecl);
-        if (eventNames.length > 0) {
-            warnings.push(`Component ${name} has ${eventNames.length} events not captured: ${eventNames.join(', ')}`);
-        }
-        components.push({
-            name,
-            source: sourceFile.getFilePath(),
-            sourcePath: sourceFile.getFilePath(),
-            framework: 'stencil',
-            props,
-            slots,
-        });
-    }
-    return components;
-}
-function detectFunctionalComponents(sourceFile, warnings) {
-    for (const [exportName, declarations] of sourceFile.getExportedDeclarations()) {
-        for (const decl of declarations) {
-            if (!Node.isVariableDeclaration(decl))
-                continue;
-            const typeNode = decl.getTypeNode();
-            if (!typeNode)
-                continue;
-            const typeText = typeNode.getText();
-            if (!typeText.startsWith('FunctionalComponent'))
-                continue;
-            warnings.push(`Stencil FunctionalComponent detected but not extracted: ${exportName} in ${sourceFile.getFilePath()}`);
-        }
-    }
-}
-export async function extractStencilComponents(filePaths) {
-    const tsxFiles = filePaths.filter((f) => /\.[jt]sx$/.test(f));
-    if (tsxFiles.length === 0) {
-        return { components: [], warnings: [] };
-    }
-    const project = new Project({
-        compilerOptions: {
-            jsx: 1, // JsxEmit.Preserve
-            target: 99, // ScriptTarget.ESNext
-            module: 99, // ModuleKind.ESNext
-            moduleResolution: 100, // ModuleResolutionKind.Bundler
-            skipLibCheck: true,
-            allowJs: true,
-        },
-        skipAddingFilesFromTsConfig: true,
-    });
-    for (const filePath of tsxFiles) {
-        project.addSourceFileAtPath(filePath);
-    }
-    const { items: components, warnings } = extractProjectSourceFiles(project, (sourceFile, sourceWarnings) => {
-        if (!isStencilFile(sourceFile))
-            return [];
-        const extracted = extractFromSourceFile(sourceFile, sourceWarnings);
-        detectFunctionalComponents(sourceFile, sourceWarnings);
-        return extracted;
-    });
-    return createSortedExtractionResult(components, warnings);
-}

package/dist/src/extract/structural-slot-evidence.d.ts

@@ -1,63 +0,0 @@
-import { type FunctionDeclaration, type ArrowFunction, type FunctionExpression, type SourceFile } from 'ts-morph';
-import { type AllowedComponentsContext } from './slot-allowed-components.js';
-type FunctionLike = FunctionDeclaration | ArrowFunction | FunctionExpression;
-/**
- * Structural composition evidence: parent→child relationships a component's
- * source implies through *usage*, not through a declared slot contract
- * (`ReactElement<XProps>` on the slot's own prop type, `@allowedComponents`,
- * a mapping-layer keyword). Declared contracts still win on conflict — see
- * the `structural` provenance rank in the CLI's composition merge — this is
- * a lower-trust supplementary signal for the common case where a component
- * accepts `children: ReactNode` and narrows it at runtime instead.
- */
-/**
- * Signal A — a type-predicate function anywhere in the file asserts a value
- * `is ReactElement<XProps>` (e.g. `function isFooElement(c): c is
- * ReactElement<FooProps>`). Common alongside a runtime `Children.map` /
- * `cloneElement` narrowing pattern where the slot's own prop type is a bare
- * `ReactNode` and carries no generic for the typed-slot extractor to read.
- */
-export declare function collectTypePredicateComponentReferences(sourceFile: SourceFile, ctx: AllowedComponentsContext): string[];
-/**
- * Signal B — a runtime identity check against a known component, e.g.
- * `isValidElement(child) && child.type === BlueAccordionItem`. `.type` on a
- * React element is the actual component reference, so this is direct
- * evidence the checked value is expected to BE that component — not a name
- * guess, an identity comparison against the real imported binding.
- */
-export declare function collectRuntimeTypeCheckComponentReferences(sourceFile: SourceFile, componentNames: ReadonlySet<string>): string[];
-/**
- * Signal C — a component's own render body literally instantiates another
- * known local component as JSX (e.g. `<CardHeader/>` inside `Card`'s
- * return). Direct structural nesting, not a slot being filled with
- * caller-supplied content — the weakest-trust signal, kept last in the rank.
- */
-export declare function collectRenderedComponentReferences(funcNode: FunctionLike, componentNames: ReadonlySet<string>, ownComponentName: string): string[];
-/**
- * Signal D — data-array render: the component's render body maps an array-
- * typed prop to a known child component (e.g. `{items.map(x => <ItemRow
- * .../>)}` inside a parent whose `items` prop is a plain data array).
- *
- * Fires only when ALL strict-gating conditions hold, to keep false positives
- * off in the common case where mapping over data doesn't imply an authorable
- * compositional slot. Conditions are listed in check order (cheap fails
- * first) so the loop-body labels line up 1-to-1 with this list:
- *
- *   1. The `.map` callee is an identifier that matches a declared prop on
- *      the parent (`propNames`).
- *   2. The prop's declared type text is a plain data array — not
- *      `ReactNode[]` / `ReactElement<...>[]` / `React.ReactNode[]`, etc.
- *      (those cases are already covered by the typed-slot pass, so firing
- *      this signal for them would double-count.)
- *   3. The callback returns a JSX element whose tag is an identifier
- *      resolving to a known component (`componentNames`).
- *   4. That child component is NOT rendered anywhere else in the parent's
- *      body — the map is the only render site.
- *
- * When all four hold, the mapped child is a strong candidate for a
- * synthesised default slot on the parent — the extractor treats it that way
- * only when there's no other slot to hang the evidence on (see the caller in
- * react.ts).
- */
-export declare function collectArrayMapRenderComponentReferences(funcNode: FunctionLike, componentNames: ReadonlySet<string>, ownComponentName: string, propTypesByName: ReadonlyMap<string, string>): string[];
-export {};