@contentful/experience-design-system-extraction 2.26.1

package/dist/src/extract/stencil.js

@@ -0,0 +1,328 @@
+import { Project, Node, SyntaxKind } from 'ts-morph';
+import { getJsxTagNameNode, isIntrinsicJsxElement } from './tsx-shared.js';
+function isStencilFile(sourceFile) {
+    return sourceFile.getImportDeclarations().some((imp) => imp.getModuleSpecifierValue() === '@stencil/core');
+}
+function kebabToPascal(input) {
+    return input
+        .split('-')
+        .filter(Boolean)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+}
+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 warnings = [];
+    const components = [];
+    for (const sourceFile of project.getSourceFiles()) {
+        try {
+            if (!isStencilFile(sourceFile))
+                continue;
+            const extracted = extractFromSourceFile(sourceFile, warnings);
+            components.push(...extracted);
+            detectFunctionalComponents(sourceFile, warnings);
+        }
+        catch (e) {
+            warnings.push(`Failed to extract from ${sourceFile.getFilePath()}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return {
+        components: components.sort((a, b) => a.name.localeCompare(b.name)),
+        warnings,
+    };
+}

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

@@ -0,0 +1,36 @@
+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[];
+export {};

package/dist/src/extract/structural-slot-evidence.js

@@ -0,0 +1,121 @@
+import { Node, SyntaxKind, } from 'ts-morph';
+import { extractAllowedComponentsFromTypeText } from './slot-allowed-components.js';
+import { isIntrinsicJsxElement } from './tsx-shared.js';
+/**
+ * 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 function collectTypePredicateComponentReferences(sourceFile, ctx) {
+    const found = new Set();
+    const candidates = [
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.FunctionDeclaration),
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.FunctionExpression),
+    ];
+    for (const fn of candidates) {
+        const returnTypeNode = fn.getReturnTypeNode();
+        if (!returnTypeNode || !Node.isTypePredicate(returnTypeNode))
+            continue;
+        const assertedTypeNode = returnTypeNode.getTypeNode();
+        if (!assertedTypeNode)
+            continue;
+        for (const name of extractAllowedComponentsFromTypeText(assertedTypeNode.getText(), ctx)) {
+            found.add(name);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * 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 function collectRuntimeTypeCheckComponentReferences(sourceFile, componentNames) {
+    const found = new Set();
+    const localBindings = collectLocallyBoundNames(sourceFile);
+    for (const binary of sourceFile.getDescendantsOfKind(SyntaxKind.BinaryExpression)) {
+        const operator = binary.getOperatorToken().getText();
+        if (operator !== '===' && operator !== '==')
+            continue;
+        const left = binary.getLeft();
+        const right = binary.getRight();
+        const candidateFromTypeAccess = (typeAccessSide, otherSide) => {
+            if (!Node.isPropertyAccessExpression(typeAccessSide) || typeAccessSide.getName() !== 'type')
+                return undefined;
+            if (!Node.isIdentifier(otherSide) && !Node.isPropertyAccessExpression(otherSide))
+                return undefined;
+            const name = otherSide.getText().split('.').pop();
+            if (!name || !componentNames.has(name))
+                return undefined;
+            const baseIdentifier = Node.isPropertyAccessExpression(otherSide) ? otherSide.getExpression() : otherSide;
+            if (!Node.isIdentifier(baseIdentifier) || !localBindings.has(baseIdentifier.getText()))
+                return undefined;
+            return name;
+        };
+        const match = candidateFromTypeAccess(left, right) ?? candidateFromTypeAccess(right, left);
+        if (match)
+            found.add(match);
+    }
+    return [...found].sort();
+}
+/** Names bound in this file by import or local declaration — used to keep signal B from matching an unrelated same-named identifier that was never actually imported here. */
+function collectLocallyBoundNames(sourceFile) {
+    const names = new Set();
+    for (const imp of sourceFile.getImportDeclarations()) {
+        const defaultImport = imp.getDefaultImport();
+        if (defaultImport)
+            names.add(defaultImport.getText());
+        const namespaceImport = imp.getNamespaceImport();
+        if (namespaceImport)
+            names.add(namespaceImport.getText());
+        for (const named of imp.getNamedImports()) {
+            names.add((named.getAliasNode() ?? named.getNameNode()).getText());
+        }
+    }
+    for (const decl of sourceFile.getVariableDeclarations())
+        names.add(decl.getName());
+    for (const decl of sourceFile.getFunctions()) {
+        const declName = decl.getName();
+        if (declName)
+            names.add(declName);
+    }
+    return names;
+}
+/**
+ * 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 function collectRenderedComponentReferences(funcNode, componentNames, ownComponentName) {
+    const found = new Set();
+    const jsxElements = [
+        ...funcNode.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
+        ...funcNode.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+    ];
+    for (const jsxElement of jsxElements) {
+        const tagName = jsxElement.getTagNameNode().getText();
+        if (isIntrinsicJsxElement(tagName))
+            continue;
+        if (tagName === ownComponentName)
+            continue;
+        if (!componentNames.has(tagName))
+            continue;
+        found.add(tagName);
+    }
+    return [...found].sort();
+}

package/dist/src/extract/svelte.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentExtractionResult, ExtractorOptions } from '../types.js';
+export declare function extractSvelteComponents(filePaths: string[], onProgress?: (p: {
+    filesProcessed: number;
+    componentsFound: number;
+}) => void, opts?: ExtractorOptions): Promise<ComponentExtractionResult>;