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

package/dist/package.json

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

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

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

package/dist/src/extract/astro.js

@@ -0,0 +1,226 @@
+import os from 'node:os';
+import { basename } from 'node:path';
+import { Project, Node } from 'ts-morph';
+import { createSortedExtractionResult, runFileExtractionWorkers } from './file-extraction-workers.js';
+import { resolveTypeProperty } from './resolve-type-property.js';
+import { getSourceLineMetadata } from './source-line-metadata.js';
+function extractAllowedValues(typeText) {
+    // Check if the type is a union of string literals like 'a' | 'b' | 'c'
+    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;
+}
+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;
+}
+function extractBindingPropName(element) {
+    if (element.getText().startsWith('...'))
+        return null;
+    return element.getPropertyNameNode()?.getText() ?? element.getNameNode().getText();
+}
+function createAstroFrontmatterProject() {
+    return new Project({
+        compilerOptions: {
+            strict: false,
+            target: 99,
+            module: 99,
+            allowJs: true,
+        },
+        useInMemoryFileSystem: true,
+        skipAddingFilesFromTsConfig: true,
+    });
+}
+function forEachAstroPropsBinding(frontmatter, visit) {
+    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())
+            visit(element);
+    });
+}
+function extractFallbackPropsFromFrontmatter(frontmatter) {
+    const props = new Map();
+    forEachAstroPropsBinding(frontmatter, (element) => {
+        const propName = extractBindingPropName(element);
+        if (!propName)
+            return;
+        props.set(propName, {
+            name: propName,
+            type: 'any',
+            required: !element.getInitializer(),
+        });
+    });
+    return [...props.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+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));
+}
+function extractPropsFromFrontmatter(frontmatter) {
+    const sf = createAstroFrontmatterProject().createSourceFile('__frontmatter__.ts', frontmatter);
+    const props = [];
+    // Find `interface Props` or `type 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));
+}
+function extractDefaultsFromFrontmatter(frontmatter) {
+    const defaults = new Map();
+    forEachAstroPropsBinding(frontmatter, (element) => {
+        const propName = extractBindingPropName(element);
+        if (!propName)
+            return;
+        const elementInitializer = element.getInitializer();
+        if (!elementInitializer)
+            return;
+        const value = elementInitializer.getText().replace(/^['"]|['"]$/g, '');
+        defaults.set(propName, value);
+    });
+    return defaults;
+}
+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;
+}
+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;
+}
+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;
+}
+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/shared/helpers/file-processing/file-workers.d.ts → file-extraction-workers.d.ts}

@@ -1,9 +1,10 @@
+import type { Project, SourceFile } from 'ts-morph';
 export type FileExtractionOutcome<T, M = undefined> = {
     item: T | null;
     warnings?: string[];
     metadata?: M;
 };
-export type FileExtractionProgress = {
+type FileExtractionProgress = {
     filesProcessed: number;
     componentsFound: number;
 };
@@ -11,3 +12,14 @@ export declare function runFileExtractionWorkers<T, M = undefined>(filePaths: st
     items: T[];
     warnings: string[];
 }>;
+export declare function createSortedExtractionResult<T extends {
+    name: string;
+}>(components: T[], warnings: string[]): {
+    components: T[];
+    warnings: string[];
+};
+export declare function extractProjectSourceFiles<T>(project: Project, extractFile: (sourceFile: SourceFile, warnings: string[]) => T[]): {
+    items: T[];
+    warnings: string[];
+};
+export {};

package/dist/src/extract/{framework-adapters/shared/helpers/file-processing/file-workers.js → file-extraction-workers.js}

@@ -27,3 +27,22 @@ export async function runFileExtractionWorkers(filePaths, concurrency, extractFi
     await Promise.all(Array.from({ length: Math.min(concurrency, filePaths.length) }, worker));
     return { items, warnings };
 }
+export function createSortedExtractionResult(components, warnings) {
+    return {
+        components: components.sort((a, b) => a.name.localeCompare(b.name)),
+        warnings,
+    };
+}
+export function extractProjectSourceFiles(project, extractFile) {
+    const warnings = [];
+    const items = [];
+    for (const sourceFile of project.getSourceFiles()) {
+        try {
+            items.push(...extractFile(sourceFile, warnings));
+        }
+        catch (error) {
+            warnings.push(`Failed to extract from ${sourceFile.getFilePath()}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { items, warnings };
+}

package/dist/src/extract/non-authorable-filter.d.ts

@@ -0,0 +1,17 @@
+import type { RawComponentDefinition } from '../types.js';
+interface NonAuthorableResult {
+    skip: boolean;
+    reason?: string;
+}
+/**
+ * Decides whether a component is non-authorable infrastructure (Context.Provider,
+ * analytics shim, layout-only utility, etc.) and should be filtered out of the
+ * analyze TUI before authoring-token generation.
+ *
+ * Uses prop-shape signals only — no component-name or source-path patterns.
+ * A design system can live anywhere under any naming convention; relying on
+ * suffixes like `*Provider` or paths like `src/lib/` would silently fail in
+ * other repos.
+ */
+export declare function isNonAuthorableComponent(component: RawComponentDefinition): NonAuthorableResult;
+export {};

package/dist/src/extract/non-authorable-filter.js

@@ -0,0 +1,60 @@
+const HANDLER_TYPE_PATTERN = /=>|EventHandler|Dispatch<|SetStateAction/;
+const REF_TYPE_PATTERN = /Ref<|RefObject<|MutableRefObject/;
+function isHandlerOrRefProp(prop) {
+    if (HANDLER_TYPE_PATTERN.test(prop.type))
+        return true;
+    if (REF_TYPE_PATTERN.test(prop.type))
+        return true;
+    if (/^on[A-Z]/.test(prop.name) || /^set[A-Z]/.test(prop.name))
+        return true;
+    if (prop.name === 'ref' || prop.name === 'innerRef')
+        return true;
+    return false;
+}
+/**
+ * Decides whether a component is non-authorable infrastructure (Context.Provider,
+ * analytics shim, layout-only utility, etc.) and should be filtered out of the
+ * analyze TUI before authoring-token generation.
+ *
+ * Uses prop-shape signals only — no component-name or source-path patterns.
+ * A design system can live anywhere under any naming convention; relying on
+ * suffixes like `*Provider` or paths like `src/lib/` would silently fail in
+ * other repos.
+ */
+export function isNonAuthorableComponent(component) {
+    const { props, slots, usesCreateContext } = component;
+    // R1: zero props AND zero slots — nothing for an editor to author.
+    // Catches analytics scripts, GTM tags, layout fixers, security tokens, etc.
+    if (props.length === 0 && slots.length === 0) {
+        return { skip: true, reason: 'component has no props and no slots' };
+    }
+    // R2: createContext source + prop literally named `value` — canonical
+    // `<Context.Provider value={...}>` call site.
+    if (usesCreateContext && props.some((p) => p.name === 'value')) {
+        return {
+            skip: true,
+            reason: 'source uses createContext and component exposes a Context.Provider value prop',
+        };
+    }
+    // R3: createContext source + zero props — Provider wrapper that hard-codes
+    // the context value internally (e.g. FontProvider, BottomSheetProvider).
+    if (usesCreateContext && props.length === 0) {
+        return { skip: true, reason: 'source uses createContext and component has no props' };
+    }
+    // R4: createContext source + exactly one non-handler prop — Provider that
+    // takes the context value as its sole data prop, named after the data
+    // (e.g. `LocaleProvider({ locale })`, `NavigationProvider({ navItems })`).
+    if (usesCreateContext && props.length === 1 && !isHandlerOrRefProp(props[0])) {
+        return {
+            skip: true,
+            reason: 'source uses createContext and component has a single non-handler prop',
+        };
+    }
+    // R5: every prop is a handler/ref — pure data plumbing, no authoring surface.
+    // Catches components like `OsanoCookiePlaceholder({ onBannerLoaded })` or
+    // `FeedbackCard({ setShowModal })`.
+    if (props.length > 0 && props.every(isHandlerOrRefProp)) {
+        return { skip: true, reason: 'every prop is a handler or ref' };
+    }
+    return { skip: false };
+}

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

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