@contentful/experience-design-system-extraction 2.36.2-dev-build-3425e8d3.0 → 2.36.2-dev-build-3b8c3735.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-extraction",
-  "version": "2.36.2-dev-build-3425e8d3.0",
+  "version": "2.36.2-dev-build-3b8c3735.0",
   "description": "Component extraction engine for the Contentful Experience Design System SDK",
   "license": "MIT",
   "type": "module",

package/dist/src/extract/controller/extract-controller.d.ts

@@ -0,0 +1,10 @@
+import type { ExtractionEndpointRequest, ExtractionEndpointResponse } from '../types/contract.js';
+export type { ExtractionEndpointProgress, ExtractionEndpointRequest, ExtractionEndpointResponse, } from '../types/contract.js';
+/**
+ * Stable in-process extraction contract.
+ *
+ * The controller owns public request validation and progress translation. The
+ * extraction service owns source analysis and quality policy; neither layer
+ * scans directories, invokes agents, or persists sessions.
+ */
+export declare function extractEndpoint(request: ExtractionEndpointRequest): Promise<ExtractionEndpointResponse>;

package/dist/src/extract/controller/extract-controller.js

@@ -0,0 +1,33 @@
+import { executeExtractionOrchestrator } from '../orchestrator/execute-extraction-orchestrator.js';
+import { validateRequest } from './helpers/validate-endpoint-request.js';
+/**
+ * Stable in-process extraction contract.
+ *
+ * The controller owns public request validation and progress translation. The
+ * extraction service owns source analysis and quality policy; neither layer
+ * scans directories, invokes agents, or persists sessions.
+ */
+export async function extractEndpoint(request) {
+    validateRequest(request);
+    const filePaths = [...request.filePaths];
+    const result = await executeExtractionOrchestrator({
+        filePaths,
+        ...(request.resolveUnreachable !== undefined ? { resolveUnreachable: request.resolveUnreachable } : {}),
+        ...(request.projectRoot !== undefined ? { projectRoot: request.projectRoot } : {}),
+        onProgress: ({ filesProcessed, componentsFound }) => {
+            request.onProgress?.({
+                phase: 'extract',
+                filesProcessed,
+                totalFiles: filePaths.length,
+                componentsFound,
+            });
+        },
+    });
+    request.onProgress?.({
+        phase: 'extract',
+        filesProcessed: filePaths.length,
+        totalFiles: filePaths.length,
+        componentsFound: result.components.length,
+    });
+    return result;
+}

package/dist/src/extract/controller/helpers/validate-endpoint-request.d.ts

@@ -0,0 +1,2 @@
+import type { ExtractionEndpointRequest } from '../../types/contract.js';
+export declare function validateRequest(request: ExtractionEndpointRequest): void;

package/dist/src/extract/controller/helpers/validate-endpoint-request.js

@@ -0,0 +1,24 @@
+export function validateRequest(request) {
+    if (request === null || typeof request !== 'object') {
+        throw new TypeError('extractEndpoint requires a request object');
+    }
+    if (!Array.isArray(request.filePaths)) {
+        throw new TypeError('extractEndpoint requires filePaths to be an array');
+    }
+    if (request.filePaths.some((filePath) => typeof filePath !== 'string' || filePath.trim().length === 0)) {
+        throw new TypeError('extractEndpoint requires filePaths to contain non-empty strings');
+    }
+    if (request.projectRoot !== undefined &&
+        (typeof request.projectRoot !== 'string' || request.projectRoot.trim().length === 0)) {
+        throw new TypeError('extractEndpoint requires projectRoot to be a non-empty string when provided');
+    }
+    if (request.resolveUnreachable !== undefined &&
+        request.resolveUnreachable !== 'auto' &&
+        request.resolveUnreachable !== 'always' &&
+        request.resolveUnreachable !== 'never') {
+        throw new TypeError("extractEndpoint requires resolveUnreachable to be 'auto', 'always', or 'never'");
+    }
+    if (request.onProgress !== undefined && typeof request.onProgress !== 'function') {
+        throw new TypeError('extractEndpoint requires onProgress to be a function when provided');
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { ComponentExtractionResult } from '../types.js';
+import type { ComponentExtractionResult } from '../../types/component.js';
 export declare function extractAstroComponents(filePaths: string[], onProgress?: (p: {
     filesProcessed: number;
     componentsFound: number;

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

@@ -0,0 +1,45 @@
+import os from 'node:os';
+import { basename } from 'node:path';
+import { runFileExtractionWorkers } from '../shared/helpers/file-processing/file-workers.js';
+import { createSortedExtractionResult } from '../shared/helpers/file-processing/result-normalizer.js';
+import { extractFallbackPropsFromFrontmatter, extractPropsFromFrontmatter, extractDefaultsFromFrontmatter, mergeProps, } from './frontmatter.js';
+import { extractSlotsFromTemplate, extractSlotsFromFrontmatter, mergeSlots } from './slots.js';
+function extractFromAstroFile(filePath, source) {
+    const name = basename(filePath, '.astro');
+    // Split on `---` fences: frontmatter is between first and second `---`.
+    // If there is no `---`, the entire file is a template-only component.
+    const fenceIndex = source.startsWith('---') ? 0 : -1;
+    let frontmatter = '';
+    let template = source;
+    if (fenceIndex !== -1) {
+        const endFenceIndex = source.indexOf('---', fenceIndex + 3);
+        if (endFenceIndex !== -1) {
+            frontmatter = source.slice(fenceIndex + 3, endFenceIndex);
+            template = source.slice(endFenceIndex + 3);
+        }
+    }
+    const props = frontmatter
+        ? mergeProps(extractFallbackPropsFromFrontmatter(frontmatter), extractPropsFromFrontmatter(frontmatter))
+        : [];
+    const defaults = frontmatter ? extractDefaultsFromFrontmatter(frontmatter) : new Map();
+    const propsWithDefaults = props.map((p) => {
+        const defaultValue = defaults.get(p.name);
+        return defaultValue ? { ...p, defaultValue } : p;
+    });
+    const slots = mergeSlots(extractSlotsFromTemplate(template), extractSlotsFromFrontmatter(frontmatter));
+    return {
+        name,
+        source: filePath,
+        sourcePath: filePath,
+        framework: 'astro',
+        props: propsWithDefaults,
+        slots,
+    };
+}
+export async function extractAstroComponents(filePaths, onProgress) {
+    const astroFiles = filePaths.filter((f) => f.endsWith('.astro'));
+    const { items: components, warnings } = await runFileExtractionWorkers(astroFiles, os.cpus().length, async (filePath, source) => ({
+        item: extractFromAstroFile(filePath, source),
+    }), (filePath, error) => `Failed to extract from ${filePath}: ${error instanceof Error ? error.message : String(error)}`, onProgress);
+    return createSortedExtractionResult(components, warnings);
+}

package/dist/src/extract/framework-adapters/astro/frontmatter.d.ts

@@ -0,0 +1,11 @@
+import type { RawPropDefinition } from '../../types/component.js';
+/** Returns the string literals from a union type like `'a' | 'b' | 'c'`, or undefined if fewer than two are found. */
+export declare function extractAllowedValues(typeText: string): string[] | undefined;
+/** Reads prop names and requiredness from destructured `Astro.props` bindings when no typed Props interface exists. */
+export declare function extractFallbackPropsFromFrontmatter(frontmatter: string): RawPropDefinition[];
+/** Reads typed props from an `interface Props` or `type Props = ...` declaration in the frontmatter. */
+export declare function extractPropsFromFrontmatter(frontmatter: string): RawPropDefinition[];
+/** Reads default values from destructuring initializers in `const { foo = 'bar' } = Astro.props`. */
+export declare function extractDefaultsFromFrontmatter(frontmatter: string): Map<string, string>;
+/** Merges multiple prop arrays, preferring later entries on name collision and treating a prop as required only if all sources require it. */
+export declare function mergeProps(...propGroups: RawPropDefinition[][]): RawPropDefinition[];

package/dist/src/extract/framework-adapters/astro/frontmatter.js

@@ -0,0 +1,96 @@
+import { resolveTypeProperty } from '../shared/helpers/resolve-type-symbol.js';
+import { getSourceLineMetadata } from '../shared/helpers/get-node-source-lines.js';
+import { createAstroFrontmatterProject, collectAstroPropsBindings, extractBindingPropName, } from './helpers/collect-astro-props-bindings.js';
+/** Returns the string literals from a union type like `'a' | 'b' | 'c'`, or undefined if fewer than two are found. */
+export function extractAllowedValues(typeText) {
+    const parts = typeText.split('|').map((p) => p.trim());
+    const literals = parts.filter((p) => /^['"]/.test(p)).map((p) => p.replace(/^['"]|['"]$/g, ''));
+    return literals.length >= 2 ? literals.sort() : undefined;
+}
+/** Reads prop names and requiredness from destructured `Astro.props` bindings when no typed Props interface exists. */
+export function extractFallbackPropsFromFrontmatter(frontmatter) {
+    const props = new Map();
+    for (const element of collectAstroPropsBindings(frontmatter)) {
+        const propName = extractBindingPropName(element);
+        if (!propName)
+            continue;
+        props.set(propName, {
+            name: propName,
+            type: 'any',
+            required: !element.getInitializer(),
+        });
+    }
+    return [...props.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Reads typed props from an `interface Props` or `type Props = ...` declaration in the frontmatter. */
+export function extractPropsFromFrontmatter(frontmatter) {
+    const sf = createAstroFrontmatterProject().createSourceFile('__frontmatter__.ts', frontmatter);
+    const props = [];
+    const propsInterface = sf.getInterface('Props');
+    const propsTypeAlias = sf.getTypeAlias('Props');
+    if (propsInterface) {
+        for (const member of propsInterface.getProperties()) {
+            const name = member.getName();
+            const typeText = member.getTypeNode()?.getText() ?? 'any';
+            const required = !member.hasQuestionToken();
+            const allowedValues = extractAllowedValues(typeText);
+            props.push({
+                name,
+                type: typeText,
+                required,
+                ...(allowedValues && { allowedValues }),
+                sourceStartLine: member.getStartLineNumber(),
+                sourceEndLine: member.getEndLineNumber(),
+            });
+        }
+    }
+    else if (propsTypeAlias) {
+        const type = propsTypeAlias.getType();
+        for (const property of type.getProperties()) {
+            const resolved = resolveTypeProperty(property);
+            if (!resolved)
+                continue;
+            const { name, declaration: decl, typeText, required } = resolved;
+            const allowedValues = extractAllowedValues(typeText);
+            props.push({
+                name,
+                type: typeText,
+                required,
+                ...(allowedValues && { allowedValues }),
+                ...getSourceLineMetadata(decl),
+            });
+        }
+    }
+    return props.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Reads default values from destructuring initializers in `const { foo = 'bar' } = Astro.props`. */
+export function extractDefaultsFromFrontmatter(frontmatter) {
+    const defaults = new Map();
+    for (const element of collectAstroPropsBindings(frontmatter)) {
+        const propName = extractBindingPropName(element);
+        if (!propName)
+            continue;
+        const elementInitializer = element.getInitializer();
+        if (!elementInitializer)
+            continue;
+        defaults.set(propName, elementInitializer.getText().replace(/^['"]|['"]$/g, ''));
+    }
+    return defaults;
+}
+/** Merges multiple prop arrays, preferring later entries on name collision and treating a prop as required only if all sources require it. */
+export function mergeProps(...propGroups) {
+    const merged = new Map();
+    for (const props of propGroups) {
+        for (const prop of props) {
+            const existing = merged.get(prop.name);
+            merged.set(prop.name, existing
+                ? {
+                    ...existing,
+                    ...prop,
+                    required: existing.required && prop.required,
+                }
+                : prop);
+        }
+    }
+    return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/src/extract/framework-adapters/astro/helpers/collect-astro-props-bindings.d.ts

@@ -0,0 +1,4 @@
+import { Project } from 'ts-morph';
+export declare function createAstroFrontmatterProject(): Project;
+export declare function extractBindingPropName(element: import('ts-morph').BindingElement): string | null;
+export declare function collectAstroPropsBindings(frontmatter: string): import('ts-morph').BindingElement[];

package/dist/src/extract/framework-adapters/astro/helpers/collect-astro-props-bindings.js

@@ -0,0 +1,47 @@
+import { Node, Project } from 'ts-morph';
+export function createAstroFrontmatterProject() {
+    return new Project({
+        compilerOptions: { strict: false, target: 99, module: 99, allowJs: true },
+        useInMemoryFileSystem: true,
+        skipAddingFilesFromTsConfig: true,
+    });
+}
+function usesAstroProps(initializer) {
+    if (!initializer)
+        return false;
+    if (initializer.getText() === 'Astro.props')
+        return true;
+    let found = false;
+    initializer.forEachDescendant((node) => {
+        if (found)
+            return false;
+        if (Node.isPropertyAccessExpression(node) && node.getText() === 'Astro.props') {
+            found = true;
+            return false;
+        }
+        return undefined;
+    });
+    return found;
+}
+export function extractBindingPropName(element) {
+    if (element.getText().startsWith('...'))
+        return null;
+    return element.getPropertyNameNode()?.getText() ?? element.getNameNode().getText();
+}
+export function collectAstroPropsBindings(frontmatter) {
+    const elements = [];
+    const sf = createAstroFrontmatterProject().createSourceFile('__frontmatter__.ts', frontmatter);
+    sf.forEachDescendant((node) => {
+        if (!Node.isVariableDeclaration(node))
+            return;
+        const initializer = node.getInitializer();
+        if (!initializer || !usesAstroProps(initializer))
+            return;
+        const nameNode = node.getNameNode();
+        if (!Node.isObjectBindingPattern(nameNode))
+            return;
+        for (const element of nameNode.getElements())
+            elements.push(element);
+    });
+    return elements;
+}

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

@@ -0,0 +1,7 @@
+import type { RawSlotDefinition } from '../../types/component.js';
+/** Finds `<slot name="...">` tags in the Astro template section. */
+export declare function extractSlotsFromTemplate(template: string): RawSlotDefinition[];
+/** Finds `Astro.slots.render('name')` calls in the frontmatter to detect programmatically-rendered slots. */
+export declare function extractSlotsFromFrontmatter(frontmatter: string): RawSlotDefinition[];
+/** Merges slot arrays, keeping the first occurrence of each name. */
+export declare function mergeSlots(...slotGroups: RawSlotDefinition[][]): RawSlotDefinition[];

package/dist/src/extract/framework-adapters/astro/slots.js

@@ -0,0 +1,44 @@
+/** Finds `<slot name="...">` tags in the Astro template section. */
+export function extractSlotsFromTemplate(template) {
+    const slots = [];
+    const seen = new Set();
+    const slotRegex = /<slot(?:\s+name=["']([^"']+)["'])?\s*\/?>/g;
+    let match;
+    while ((match = slotRegex.exec(template)) !== null) {
+        const slotName = match[1] ?? 'default';
+        if (!seen.has(slotName)) {
+            seen.add(slotName);
+            slots.push({ name: slotName, isDefault: slotName === 'default' });
+        }
+    }
+    return slots;
+}
+/** Finds `Astro.slots.render('name')` calls in the frontmatter to detect programmatically-rendered slots. */
+export function extractSlotsFromFrontmatter(frontmatter) {
+    const slots = [];
+    const seen = new Set();
+    const slotRenderRegex = /Astro\.slots\.render\(\s*['"]([^'"]+)['"]\s*\)/g;
+    let match;
+    while ((match = slotRenderRegex.exec(frontmatter)) !== null) {
+        const slotName = match[1];
+        if (!seen.has(slotName)) {
+            seen.add(slotName);
+            slots.push({ name: slotName, isDefault: slotName === 'default' });
+        }
+    }
+    return slots;
+}
+/** Merges slot arrays, keeping the first occurrence of each name. */
+export function mergeSlots(...slotGroups) {
+    const merged = [];
+    const seen = new Set();
+    for (const slots of slotGroups) {
+        for (const slot of slots) {
+            if (seen.has(slot.name))
+                continue;
+            seen.add(slot.name);
+            merged.push(slot);
+        }
+    }
+    return merged;
+}

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

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

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

@@ -0,0 +1,31 @@
+import { extractTsxComponents } from '../shared/helpers/tsx-shared.js';
+import { resolveReactAllowedComponents } from './helpers/extract-react-allowed-components.js';
+import { synthesizeReactStructuralSlots } from './helpers/synthesize-react-structural-slots.js';
+import { resolveReactPropForwarding } from './helpers/resolve-react-prop-forwarding.js';
+import { extractFromReactSourceFile } from './helpers/extract-from-react-source-file.js';
+function isStencilFile(sourceFile) {
+    return sourceFile.getImportDeclarations().some((imp) => imp.getModuleSpecifierValue() === '@stencil/core');
+}
+function isNextJsComponent(filePath, exportedNames) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const isAppRouterFile = /\/app\/.*\/(page|layout)\.[jt]sx?$/.test(normalized);
+    const hasNextExports = exportedNames.some((name) => name === 'generateMetadata' || name === 'generateStaticParams');
+    return isAppRouterFile || hasNextExports;
+}
+export async function extractReactComponents(filePaths) {
+    const { components, warnings, exclusions, project } = extractTsxComponents(filePaths, /\.[jt]sx$/, (sourceFile, exclusions) => {
+        if (isStencilFile(sourceFile))
+            return [];
+        const fileExports = [...sourceFile.getExportedDeclarations().keys()];
+        const isNext = isNextJsComponent(sourceFile.getFilePath(), fileExports);
+        return extractFromReactSourceFile(sourceFile, isNext, exclusions);
+    });
+    resolveReactAllowedComponents(components);
+    synthesizeReactStructuralSlots(components, project);
+    resolveReactPropForwarding(components);
+    return {
+        components: components.sort((a, b) => a.name.localeCompare(b.name)),
+        warnings,
+        exclusions,
+    };
+}

package/dist/src/extract/framework-adapters/react/helpers/collect-dom-wrapper-contexts.d.ts

@@ -0,0 +1,4 @@
+import { Node } from 'ts-morph';
+import { type ExpandableDomAttributeWrapperContext } from './dom-attribute-surfaces.js';
+export declare function getStringLiteralTypeValues(typeNode: Node): string[];
+export declare function collectExpandableDomAttributeWrapperContexts(typeNode: Node, seen?: Set<Node<import("ts-morph").ts.Node>>, excludedProps?: Set<string>): ExpandableDomAttributeWrapperContext[];

package/dist/src/extract/framework-adapters/react/helpers/collect-dom-wrapper-contexts.js

@@ -0,0 +1,73 @@
+import { Node } from 'ts-morph';
+import { getTypeReferenceName, getNodeDefinitions } from '../../shared/helpers/tsx-shared.js';
+import { getTypeReferenceTargetNode, getTypeReferenceArguments } from '../../shared/helpers/tsx-node-utils.js';
+import { isExpandableDomAttributeWrapperName, } from './dom-attribute-surfaces.js';
+export function getStringLiteralTypeValues(typeNode) {
+    if (Node.isLiteralTypeNode(typeNode)) {
+        const literal = typeNode.getLiteral();
+        if (Node.isStringLiteral(literal))
+            return [literal.getLiteralText()];
+    }
+    if (!Node.isUnionTypeNode(typeNode))
+        return [];
+    return typeNode.getTypeNodes().flatMap((n) => getStringLiteralTypeValues(n));
+}
+export function collectExpandableDomAttributeWrapperContexts(typeNode, seen = new Set(), excludedProps = new Set()) {
+    if (seen.has(typeNode))
+        return [];
+    seen.add(typeNode);
+    if (Node.isParenthesizedTypeNode(typeNode) || Node.isTypeOperatorTypeNode(typeNode)) {
+        return collectExpandableDomAttributeWrapperContexts(typeNode.getTypeNode(), seen, excludedProps);
+    }
+    if (Node.isIntersectionTypeNode(typeNode) || Node.isUnionTypeNode(typeNode)) {
+        return typeNode
+            .getTypeNodes()
+            .flatMap((child) => collectExpandableDomAttributeWrapperContexts(child, seen, excludedProps));
+    }
+    const typeReferenceTarget = getTypeReferenceTargetNode(typeNode);
+    if (typeReferenceTarget) {
+        const typeName = getTypeReferenceName(typeNode);
+        if (!typeName)
+            return [];
+        const typeArguments = getTypeReferenceArguments(typeNode);
+        if (isExpandableDomAttributeWrapperName(typeName)) {
+            return [{ name: typeName, excludedProps: new Set(excludedProps) }];
+        }
+        if (typeName === 'Omit') {
+            const [wrappedType, omittedProps] = typeArguments;
+            if (!wrappedType)
+                return [];
+            const nextExcludedProps = new Set(excludedProps);
+            if (omittedProps) {
+                for (const value of getStringLiteralTypeValues(omittedProps))
+                    nextExcludedProps.add(value);
+            }
+            return collectExpandableDomAttributeWrapperContexts(wrappedType, seen, nextExcludedProps);
+        }
+        if (typeName === 'Partial' || typeName === 'Readonly' || typeName === 'Required' || typeName === 'NonNullable') {
+            const wrappedType = typeArguments[0];
+            if (!wrappedType)
+                return [];
+            return collectExpandableDomAttributeWrapperContexts(wrappedType, seen, excludedProps);
+        }
+        for (const definition of getNodeDefinitions(typeReferenceTarget)) {
+            const declaration = definition.getDeclarationNode();
+            if (!declaration)
+                continue;
+            if (Node.isInterfaceDeclaration(declaration)) {
+                return declaration
+                    .getHeritageClauses()
+                    .flatMap((clause) => clause
+                    .getTypeNodes()
+                    .flatMap((heritageTypeNode) => collectExpandableDomAttributeWrapperContexts(heritageTypeNode, seen, excludedProps)));
+            }
+            if (Node.isTypeAliasDeclaration(declaration)) {
+                const aliasedTypeNode = declaration.getTypeNode();
+                if (!aliasedTypeNode)
+                    return [];
+                return collectExpandableDomAttributeWrapperContexts(aliasedTypeNode, seen, excludedProps);
+            }
+        }
+    }
+    return [];
+}

package/dist/src/extract/framework-adapters/react/helpers/collect-prop-dataflow.d.ts

@@ -0,0 +1,14 @@
+import { type ParameterDeclaration } from 'ts-morph';
+import { type FunctionLike } from './resolve-component-function.js';
+export type PropForwardingEdge = {
+    sourceProp: string;
+    targetComponentIdentity: string;
+    targetProp: string;
+};
+export type PropDataflow = {
+    intrinsicDomProps: Set<string>;
+    componentEdges: PropForwardingEdge[];
+};
+export declare function getComponentIdentity(func: FunctionLike): string;
+/** Trace only statically resolvable, component-local prop dataflow into JSX. */
+export declare function collectPropDataflow(func: FunctionLike, param: ParameterDeclaration, availablePropNames: Set<string>): PropDataflow;