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

package/dist/src/extract/framework-adapters/shared/helpers/resolve-tsx-tsconfig-path.js

@@ -0,0 +1,93 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import ts from 'typescript';
+const nearestTsConfigPathCache = new Map();
+const tsConfigPathsCache = new Map();
+export function matchTsConfigPathPattern(pattern, specifier) {
+    if (!pattern.includes('*'))
+        return { matched: pattern === specifier };
+    const [prefix, suffix] = pattern.split('*');
+    if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix))
+        return { matched: false };
+    return {
+        matched: true,
+        wildcard: specifier.slice(prefix.length, specifier.length - suffix.length),
+    };
+}
+export function substituteTsConfigPathTarget(targetPattern, wildcard) {
+    return wildcard === undefined ? targetPattern : targetPattern.replace('*', wildcard);
+}
+function findNearestTsConfigPath(filePath) {
+    if (nearestTsConfigPathCache.has(filePath))
+        return nearestTsConfigPathCache.get(filePath) ?? undefined;
+    let currentDir = dirname(filePath);
+    while (true) {
+        for (const candidateName of ['tsconfig.json', 'jsconfig.json']) {
+            const candidatePath = join(currentDir, candidateName);
+            if (existsSync(candidatePath)) {
+                nearestTsConfigPathCache.set(filePath, candidatePath);
+                return candidatePath;
+            }
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            nearestTsConfigPathCache.set(filePath, null);
+            return undefined;
+        }
+        currentDir = parentDir;
+    }
+}
+function getTsConfigPaths(tsConfigPath) {
+    if (tsConfigPathsCache.has(tsConfigPath))
+        return tsConfigPathsCache.get(tsConfigPath) ?? undefined;
+    const configFile = ts.readConfigFile(tsConfigPath, ts.sys.readFile);
+    if (configFile.error || !configFile.config) {
+        tsConfigPathsCache.set(tsConfigPath, null);
+        return undefined;
+    }
+    const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, dirname(tsConfigPath));
+    const paths = parsedConfig.options.paths;
+    if (!paths || Object.keys(paths).length === 0) {
+        tsConfigPathsCache.set(tsConfigPath, null);
+        return undefined;
+    }
+    const baseUrl = parsedConfig.options.baseUrl ?? dirname(tsConfigPath);
+    const result = { baseUrl, paths };
+    tsConfigPathsCache.set(tsConfigPath, result);
+    return result;
+}
+export function resolveImportSourcePath(basePath) {
+    const candidates = [
+        basePath,
+        `${basePath}.ts`,
+        `${basePath}.tsx`,
+        `${basePath}.js`,
+        `${basePath}.jsx`,
+        join(basePath, 'index.ts'),
+        join(basePath, 'index.tsx'),
+        join(basePath, 'index.js'),
+        join(basePath, 'index.jsx'),
+    ];
+    return candidates.find((candidatePath) => existsSync(candidatePath));
+}
+export function resolveRepoLocalAliasImportPath(importingFilePath, moduleSpecifier) {
+    const nearestTsConfigPath = findNearestTsConfigPath(importingFilePath);
+    if (!nearestTsConfigPath)
+        return undefined;
+    const tsConfigPaths = getTsConfigPaths(nearestTsConfigPath);
+    if (!tsConfigPaths)
+        return undefined;
+    for (const [pattern, targets] of Object.entries(tsConfigPaths.paths)) {
+        const match = matchTsConfigPathPattern(pattern, moduleSpecifier);
+        if (!match.matched)
+            continue;
+        for (const targetPattern of targets) {
+            const substitutedTarget = substituteTsConfigPathTarget(targetPattern, match.wildcard);
+            const resolvedPath = resolve(tsConfigPaths.baseUrl, substitutedTarget);
+            const sourceFilePath = resolveImportSourcePath(resolvedPath);
+            if (sourceFilePath)
+                return sourceFilePath;
+        }
+    }
+    return undefined;
+}

package/dist/src/extract/framework-adapters/shared/helpers/resolve-tsx-workspace-imports.d.ts

@@ -0,0 +1,6 @@
+import { Node } from 'ts-morph';
+import { matchTsConfigPathPattern, substituteTsConfigPathTarget, resolveImportSourcePath } from './resolve-tsx-tsconfig-path.js';
+export { matchTsConfigPathPattern, substituteTsConfigPathTarget };
+export declare function isBareModuleSpecifier(moduleSpecifier: string): boolean;
+export declare function resolveWorkspaceImportSpecifierDeclarations(importSpecifier: Node, referenceNode: Node): Node[];
+export { resolveImportSourcePath };

package/dist/src/extract/framework-adapters/shared/helpers/resolve-tsx-workspace-imports.js

@@ -0,0 +1,58 @@
+import { join } from 'node:path';
+import { Node } from 'ts-morph';
+import { matchTsConfigPathPattern, substituteTsConfigPathTarget, resolveImportSourcePath, resolveRepoLocalAliasImportPath, } from './resolve-tsx-tsconfig-path.js';
+import { findWorkspacePackageEntrySourceFile } from './find-tsx-workspace-package.js';
+export { matchTsConfigPathPattern, substituteTsConfigPathTarget };
+export function isBareModuleSpecifier(moduleSpecifier) {
+    return !moduleSpecifier.startsWith('.') && !moduleSpecifier.startsWith('/');
+}
+function findProjectSourceFileByImportPath(project, resolvedPath) {
+    const candidatePaths = [
+        resolvedPath,
+        `${resolvedPath}.ts`,
+        `${resolvedPath}.tsx`,
+        `${resolvedPath}.js`,
+        `${resolvedPath}.jsx`,
+        join(resolvedPath, 'index.ts'),
+        join(resolvedPath, 'index.tsx'),
+        join(resolvedPath, 'index.js'),
+        join(resolvedPath, 'index.jsx'),
+    ];
+    for (const candidatePath of candidatePaths) {
+        const sourceFile = project.getSourceFile(candidatePath);
+        if (sourceFile)
+            return sourceFile;
+    }
+    return undefined;
+}
+function findRepoLocalAliasSourceFile(originSourceFile, moduleSpecifier) {
+    const resolvedPath = resolveRepoLocalAliasImportPath(originSourceFile.getFilePath(), moduleSpecifier);
+    if (!resolvedPath)
+        return undefined;
+    return findProjectSourceFileByImportPath(originSourceFile.getProject(), resolvedPath);
+}
+function getExportedDeclarationsForImportSpecifier(importSpecifier, sourceFile) {
+    if (!Node.isImportSpecifier(importSpecifier))
+        return [];
+    const exportedName = importSpecifier.getNameNode().getText();
+    return sourceFile.getExportedDeclarations().get(exportedName) ?? [];
+}
+export function resolveWorkspaceImportSpecifierDeclarations(importSpecifier, referenceNode) {
+    if (!Node.isImportSpecifier(importSpecifier))
+        return [];
+    const importDeclaration = importSpecifier.getImportDeclaration();
+    const moduleSpecifierSourceFile = importDeclaration.getModuleSpecifierSourceFile();
+    if (moduleSpecifierSourceFile)
+        return getExportedDeclarationsForImportSpecifier(importSpecifier, moduleSpecifierSourceFile);
+    const moduleSpecifier = importDeclaration.getModuleSpecifierValue();
+    if (!isBareModuleSpecifier(moduleSpecifier))
+        return [];
+    const workspaceEntrySourceFile = findWorkspacePackageEntrySourceFile(referenceNode.getSourceFile(), moduleSpecifier);
+    if (workspaceEntrySourceFile)
+        return getExportedDeclarationsForImportSpecifier(importSpecifier, workspaceEntrySourceFile);
+    const aliasedSourceFile = findRepoLocalAliasSourceFile(referenceNode.getSourceFile(), moduleSpecifier);
+    if (!aliasedSourceFile)
+        return [];
+    return getExportedDeclarationsForImportSpecifier(importSpecifier, aliasedSourceFile);
+}
+export { resolveImportSourcePath };

package/dist/src/extract/framework-adapters/shared/helpers/tsx-node-utils.d.ts

@@ -0,0 +1,13 @@
+import { Node, type Type } from 'ts-morph';
+export declare function kebabToPascal(input: string): string;
+export declare function extractAllowedValues(type: Type): string[] | undefined;
+export declare function isIntrinsicJsxElement(tagName: string): boolean;
+export declare function getJsxTagNameNode(node: Node): Node | 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 getTypeReferenceTargetNode(typeNode: Node): Node | undefined;
+export declare function getTypeReferenceArguments(typeNode: Node): Node[];
+export declare function getTypeReferenceName(typeNode: Node): string | undefined;

package/dist/src/extract/framework-adapters/shared/helpers/tsx-node-utils.js

@@ -0,0 +1,76 @@
+import { Node, SyntaxKind } from 'ts-morph';
+import { resolveWorkspaceImportSpecifierDeclarations } from './resolve-tsx-workspace-imports.js';
+export function kebabToPascal(input) {
+    return input
+        .split('-')
+        .filter(Boolean)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+}
+export function extractAllowedValues(type) {
+    if (!type.isUnion())
+        return undefined;
+    const literals = type
+        .getUnionTypes()
+        .filter((t) => t.isStringLiteral())
+        .map((t) => t.getLiteralValueOrThrow());
+    return literals.length >= 2 ? literals.sort() : undefined;
+}
+export function isIntrinsicJsxElement(tagName) {
+    return /^[a-z][A-Za-z0-9]*$/.test(tagName);
+}
+export function getJsxTagNameNode(node) {
+    const openingElement = node.getFirstAncestorByKind(SyntaxKind.JsxOpeningElement);
+    const selfClosingElement = node.getFirstAncestorByKind(SyntaxKind.JsxSelfClosingElement);
+    return openingElement?.getTagNameNode() ?? selfClosingElement?.getTagNameNode();
+}
+export function getNodeDefinitions(node) {
+    const anyNode = node;
+    return anyNode.getDefinitions?.() ?? [];
+}
+export function getTypeTargetDeclarations(targetNode, allowWorkspaceImportFallback = false) {
+    return getNodeDefinitions(targetNode).flatMap((definition) => {
+        const declaration = definition.getDeclarationNode();
+        if (!declaration)
+            return [];
+        if (!allowWorkspaceImportFallback || !Node.isImportSpecifier(declaration)) {
+            return [declaration];
+        }
+        const resolvedDeclarations = resolveWorkspaceImportSpecifierDeclarations(declaration, targetNode);
+        return resolvedDeclarations.length > 0 ? resolvedDeclarations : [declaration];
+    });
+}
+export function getValueTargetDeclarations(targetNode) {
+    return getNodeDefinitions(targetNode).flatMap((definition) => {
+        const declaration = definition.getDeclarationNode();
+        if (!declaration)
+            return [];
+        if (!Node.isImportSpecifier(declaration)) {
+            return [declaration];
+        }
+        const resolvedDeclarations = resolveWorkspaceImportSpecifierDeclarations(declaration, targetNode);
+        return resolvedDeclarations.length > 0 ? resolvedDeclarations : [declaration];
+    });
+}
+export function getTypeReferenceTargetNode(typeNode) {
+    if (Node.isTypeReference(typeNode))
+        return typeNode.getTypeName();
+    if (Node.isExpressionWithTypeArguments(typeNode))
+        return typeNode.getExpression();
+    return undefined;
+}
+export function getTypeReferenceArguments(typeNode) {
+    if (Node.isTypeReference(typeNode) || Node.isExpressionWithTypeArguments(typeNode)) {
+        return typeNode.getTypeArguments();
+    }
+    return [];
+}
+export function getTypeReferenceName(typeNode) {
+    if (Node.isTypeReference(typeNode)) {
+        return typeNode.getTypeName().getText().split('.').pop();
+    }
+    if (Node.isExpressionWithTypeArguments(typeNode)) {
+        return typeNode.getExpression().getText().split('.').pop();
+    }
+    return undefined;
+}

package/dist/src/extract/framework-adapters/shared/helpers/tsx-renderable-exports.d.ts

@@ -0,0 +1,12 @@
+import { Node, type SourceFile } from 'ts-morph';
+import type { ExtractionExclusion } from '../../../types/component.js';
+export declare function resolveDefaultExportName(declarations: Node[], exported: {
+    has(name: string): boolean;
+}, allowVariableDeclaration?: boolean): string | undefined;
+export declare function getRenderableExports(sourceFile: SourceFile, exclusions: ExtractionExclusion[], options: {
+    allowVariableDeclaration?: boolean;
+    hookReason: string;
+}): Array<{
+    name: string;
+    declarations: Node[];
+}>;

package/dist/src/extract/framework-adapters/shared/helpers/tsx-renderable-exports.js

@@ -0,0 +1,35 @@
+import { Node } from 'ts-morph';
+export function resolveDefaultExportName(declarations, exported, allowVariableDeclaration = false) {
+    const declaration = declarations[0];
+    const name = Node.isFunctionDeclaration(declaration)
+        ? declaration.getName()
+        : allowVariableDeclaration && Node.isVariableDeclaration(declaration)
+            ? declaration.getName()
+            : undefined;
+    if (!name || !/^[A-Z]/.test(name) || exported.has(name))
+        return undefined;
+    return name;
+}
+export function getRenderableExports(sourceFile, exclusions, options) {
+    const renderable = [];
+    const exported = sourceFile.getExportedDeclarations();
+    for (const [exportKey, declarations] of exported) {
+        const name = exportKey === 'default'
+            ? resolveDefaultExportName(declarations, exported, options.allowVariableDeclaration)
+            : exportKey;
+        if (!name || !/^[A-Z]/.test(name))
+            continue;
+        if (name.startsWith('use')) {
+            exclusions.push({
+                itemType: 'component',
+                name,
+                source: sourceFile.getFilePath(),
+                reason: options.hookReason,
+                stage: 'component-filter',
+            });
+            continue;
+        }
+        renderable.push({ name, declarations });
+    }
+    return renderable;
+}

package/dist/src/extract/framework-adapters/shared/helpers/tsx-shared.d.ts

@@ -0,0 +1,14 @@
+import { Project, type SourceFile } from 'ts-morph';
+import type { ExtractionExclusion } from '../../../types/component.js';
+export { kebabToPascal, extractAllowedValues, isIntrinsicJsxElement, getJsxTagNameNode, getNodeDefinitions, getTypeTargetDeclarations, getValueTargetDeclarations, getTypeReferenceName, } from './tsx-node-utils.js';
+export { resolveDefaultExportName, getRenderableExports } from './tsx-renderable-exports.js';
+export declare function getTsxExtractionContext(filePaths: string[], componentFilePattern: RegExp): {
+    componentFiles: string[];
+    project: Project;
+} | undefined;
+export declare function extractTsxComponents<T>(filePaths: string[], componentFilePattern: RegExp, extract: (sourceFile: SourceFile, exclusions: ExtractionExclusion[]) => T[]): {
+    components: T[];
+    warnings: string[];
+    exclusions: ExtractionExclusion[];
+    project?: Project;
+};

package/dist/src/extract/framework-adapters/shared/helpers/tsx-shared.js

@@ -0,0 +1,54 @@
+import { Project } from 'ts-morph';
+export { kebabToPascal, extractAllowedValues, isIntrinsicJsxElement, getJsxTagNameNode, getNodeDefinitions, getTypeTargetDeclarations, getValueTargetDeclarations, getTypeReferenceName, } from './tsx-node-utils.js';
+export { resolveDefaultExportName, getRenderableExports } from './tsx-renderable-exports.js';
+function createTsxProject(filePaths) {
+    const project = new Project({
+        compilerOptions: {
+            jsx: 1,
+            target: 99,
+            module: 99,
+            moduleResolution: 100,
+            skipLibCheck: true,
+            allowJs: true,
+        },
+        skipAddingFilesFromTsConfig: true,
+    });
+    for (const filePath of filePaths) {
+        project.addSourceFileAtPath(filePath);
+    }
+    return project;
+}
+function getTsxProjectFiles(filePaths) {
+    return filePaths.filter((filePath) => /\.[jt]sx?$/.test(filePath) && !filePath.endsWith('.d.ts'));
+}
+export function getTsxExtractionContext(filePaths, componentFilePattern) {
+    const componentFiles = filePaths.filter((filePath) => componentFilePattern.test(filePath));
+    if (componentFiles.length === 0)
+        return undefined;
+    return {
+        componentFiles,
+        project: createTsxProject(getTsxProjectFiles(filePaths)),
+    };
+}
+export function extractTsxComponents(filePaths, componentFilePattern, extract) {
+    const extractionContext = getTsxExtractionContext(filePaths, componentFilePattern);
+    if (!extractionContext) {
+        return { components: [], warnings: [], exclusions: [] };
+    }
+    const { componentFiles, project } = extractionContext;
+    const components = [];
+    const warnings = [];
+    const exclusions = [];
+    for (const filePath of componentFiles) {
+        try {
+            const sourceFile = project.getSourceFile(filePath);
+            if (!sourceFile)
+                continue;
+            components.push(...extract(sourceFile, exclusions));
+        }
+        catch (e) {
+            warnings.push(`Failed to extract from ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return { components, warnings, exclusions, project };
+}

package/dist/src/extract/{stencil.d.ts → framework-adapters/stencil/extractor.d.ts}

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

package/dist/src/extract/framework-adapters/stencil/extractor.js

@@ -0,0 +1,82 @@
+import { Project, Node } from 'ts-morph';
+import { kebabToPascal } from '../shared/helpers/tsx-shared.js';
+import { createSortedExtractionResult } from '../shared/helpers/file-processing/result-normalizer.js';
+import { extractProjectSourceFiles } from '../shared/helpers/file-processing/project-source-files.js';
+import { isStencilFile, readComponentTag, hasPropertyDecorator } from './helpers/detect-stencil-class.js';
+import { extractStencilProps } from './helpers/extract-stencil-props.js';
+import { extractStencilSlots } from './helpers/extract-stencil-slots.js';
+function collectEventNames(classDecl) {
+    const eventNames = [];
+    for (const property of classDecl.getProperties()) {
+        if (!hasPropertyDecorator(property, 'Event'))
+            continue;
+        eventNames.push(property.getName());
+    }
+    return eventNames.sort();
+}
+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;
+            if (!typeNode.getText().startsWith('FunctionalComponent'))
+                continue;
+            warnings.push(`Stencil FunctionalComponent detected but not extracted: ${exportName} in ${sourceFile.getFilePath()}`);
+        }
+    }
+}
+function extractFromStencilSourceFile(sourceFile, warnings) {
+    const components = [];
+    for (const classDecl of sourceFile.getClasses()) {
+        const tag = readComponentTag(classDecl);
+        if (!tag)
+            continue;
+        const name = kebabToPascal(tag);
+        const props = extractStencilProps(classDecl);
+        const slots = extractStencilSlots(classDecl, warnings, name);
+        const eventNames = collectEventNames(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;
+}
+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 = extractFromStencilSourceFile(sourceFile, sourceWarnings);
+        detectFunctionalComponents(sourceFile, sourceWarnings);
+        return extracted;
+    });
+    return createSortedExtractionResult(components, warnings);
+}

package/dist/src/extract/framework-adapters/stencil/helpers/detect-stencil-class.d.ts

@@ -0,0 +1,7 @@
+import { Node, type SourceFile, type ClassDeclaration } from 'ts-morph';
+/** Returns true when the file imports from @stencil/core — used to skip non-Stencil files. */
+export declare function isStencilFile(sourceFile: SourceFile): boolean;
+/** Reads the `tag` value from the @Component({ tag: '...' }) decorator on a class. */
+export declare function readComponentTag(classDecl: ClassDeclaration): string | undefined;
+/** Returns true when the node is a property declaration with a given decorator name. */
+export declare function hasPropertyDecorator(node: Node, decoratorName: string): boolean;

package/dist/src/extract/framework-adapters/stencil/helpers/detect-stencil-class.js

@@ -0,0 +1,32 @@
+import { Node } from 'ts-morph';
+/** Returns true when the file imports from @stencil/core — used to skip non-Stencil files. */
+export function isStencilFile(sourceFile) {
+    return sourceFile.getImportDeclarations().some((imp) => imp.getModuleSpecifierValue() === '@stencil/core');
+}
+/** Reads the `tag` value from the @Component({ tag: '...' }) decorator on a class. */
+export function readComponentTag(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;
+}
+/** Returns true when the node is a property declaration with a given decorator name. */
+export function hasPropertyDecorator(node, decoratorName) {
+    if (!Node.isPropertyDeclaration(node))
+        return false;
+    return node.getDecorators().some((d) => d.getName() === decoratorName);
+}

package/dist/src/extract/framework-adapters/stencil/helpers/extract-stencil-props.d.ts

@@ -0,0 +1,5 @@
+import { type ClassDeclaration } from 'ts-morph';
+import type { RawPropDefinition } from '../../../types/component.js';
+export { parseAllowedValues, collectDomAttributePropNames } from './stencil-prop-helpers.js';
+/** Extracts all @Prop-decorated properties from a Stencil class as RawPropDefinitions. */
+export declare function extractStencilProps(classDecl: ClassDeclaration): RawPropDefinition[];

package/dist/src/extract/framework-adapters/stencil/helpers/extract-stencil-props.js

@@ -0,0 +1,62 @@
+import { Node } from 'ts-morph';
+import { hasPropertyDecorator } from './detect-stencil-class.js';
+import { parseAllowedValues, collectDomAttributePropNames } from './stencil-prop-helpers.js';
+export { parseAllowedValues, collectDomAttributePropNames } from './stencil-prop-helpers.js';
+/** Extracts all @Prop-decorated properties from a Stencil class as RawPropDefinitions. */
+export function extractStencilProps(classDecl) {
+    const props = [];
+    const propNames = new Set(classDecl
+        .getProperties()
+        .filter((property) => hasPropertyDecorator(property, 'Prop'))
+        .map((property) => property.getName()));
+    const domAttributePropNames = collectDomAttributePropNames(classDecl, propNames);
+    for (const property of classDecl.getProperties()) {
+        if (!hasPropertyDecorator(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) {
+            defaultValue = Node.isStringLiteral(initializer) ? initializer.getLiteralValue() : initializer.getText();
+        }
+        const isRequired = hasExclamation || (!hasQuestionToken && !initializer);
+        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;
+                    const tagComment = tag.getCommentText()?.trim();
+                    if (tagComment && !description)
+                        description = tagComment;
+                }
+            }
+        }
+        if (isDeprecated && description) {
+            description = `[DEPRECATED] ${description}`;
+        }
+        else if (isDeprecated) {
+            description = '[DEPRECATED]';
+        }
+        const allowedValues = parseAllowedValues(typeText);
+        props.push({
+            name,
+            type: typeText,
+            required: isRequired,
+            ...(defaultValue !== undefined && { defaultValue }),
+            ...(description && { description }),
+            ...(allowedValues && { allowedValues }),
+            ...(domAttributePropNames.has(name) && { domAttribute: true }),
+            sourceStartLine: property.getStartLineNumber(),
+            sourceEndLine: property.getEndLineNumber(),
+        });
+    }
+    return props.sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/src/extract/framework-adapters/stencil/helpers/extract-stencil-slots.d.ts

@@ -0,0 +1,6 @@
+import { type ClassDeclaration } from 'ts-morph';
+import type { RawSlotDefinition } from '../../../types/component.js';
+/** Normalises a raw slot name string to a RawSlotDefinition, treating blank/undefined as "default". */
+export declare function parseStencilSlot(name: string | undefined): RawSlotDefinition;
+/** Extracts all slots from a Stencil class — via @slot JSDoc tags and template <slot> elements. */
+export declare function extractStencilSlots(classDecl: ClassDeclaration, warnings: string[], componentName: string): RawSlotDefinition[];

package/dist/src/extract/framework-adapters/stencil/helpers/extract-stencil-slots.js

@@ -0,0 +1,87 @@
+import { Node } from 'ts-morph';
+import { collectJsDocSlotComments } from '../../shared/helpers/collect-jsdoc-slot-comments.js';
+/** Normalises a raw slot name string to a RawSlotDefinition, treating blank/undefined as "default". */
+export function parseStencilSlot(name) {
+    const normalizedName = name && name.length > 0 ? name : 'default';
+    return { name: normalizedName, isDefault: normalizedName === 'default' };
+}
+/** Extracts all slots from a Stencil class — via @slot JSDoc tags and template <slot> elements. */
+export function extractStencilSlots(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,
+        });
+    };
+    // JSDoc @slot tags
+    for (const comment of collectJsDocSlotComments(classDecl)) {
+        if (comment.startsWith('{')) {
+            try {
+                const parsed = JSON.parse(comment);
+                const slot = parseStencilSlot(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 = parseStencilSlot(rawName);
+        const description = rawDescription.trim() || undefined;
+        upsertSlot({ ...slot, ...(description && { description }) });
+    }
+    // Template <slot> elements
+    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({ ...parseStencilSlot(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));
+}