@contentful/experience-design-system-cli 2.2.1

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

@@ -0,0 +1,35 @@
+/**
+ * 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

@@ -0,0 +1,101 @@
+/**
+ * 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/stencil.d.ts

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

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

@@ -0,0 +1,293 @@
+import { Project, Node } from 'ts-morph';
+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 extractProps(classDecl) {
+    const props = [];
+    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 }),
+        });
+    }
+    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(),
+            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/analyze/extract/tsx-shared.d.ts

@@ -0,0 +1,8 @@
+import { Node, type Type } from 'ts-morph';
+export declare function extractAllowedValues(type: Type): string[] | undefined;
+export declare function getNodeDefinitions(node: Node): {
+    getDeclarationNode(): Node | undefined;
+}[];
+export declare function getTypeTargetDeclarations(targetNode: Node, allowWorkspaceImportFallback?: boolean): Node[];
+export declare function getValueTargetDeclarations(targetNode: Node): Node[];
+export declare function getTypeReferenceName(typeNode: Node): string | undefined;