@contentful/experience-design-system-extraction 2.26.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Contentful GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@contentful/experience-design-system-extraction",
+  "version": "2.26.1",
+  "description": "Component extraction engine for the Contentful Experience Design System SDK",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "node": "./dist/src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "nx build experience-design-system-extraction",
+    "typecheck": "nx typecheck experience-design-system-extraction",
+    "clean": "nx clean experience-design-system-extraction",
+    "test": "nx test experience-design-system-extraction",
+    "lint": "nx lint experience-design-system-extraction",
+    "lint:fix": "nx lint:fix experience-design-system-extraction"
+  },
+  "dependencies": {
+    "@vue/compiler-sfc": "^3.5.31",
+    "svelte": "^5.56.4",
+    "ts-morph": "^27.0.2",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "^24.0.4",
+    "@types/node": "^24.0.3",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.0.16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/experience-design-system-sdk-public.git",
+    "directory": "packages/experience-design-system-extraction"
+  },
+  "homepage": "https://github.com/contentful/experience-design-system-sdk-public#readme",
+  "bugs": {
+    "url": "https://github.com/contentful/experience-design-system-sdk-public/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "module": "./src/index.js"
+}

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

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

package/dist/src/extract/astro.js

@@ -0,0 +1,289 @@
+import { basename } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import { Project, Node } from 'ts-morph';
+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 extractFallbackPropsFromFrontmatter(frontmatter) {
+    const project = new Project({
+        compilerOptions: {
+            strict: false,
+            target: 99,
+            module: 99,
+            allowJs: true,
+        },
+        useInMemoryFileSystem: true,
+        skipAddingFilesFromTsConfig: true,
+    });
+    const sf = project.createSourceFile('__frontmatter__.ts', frontmatter);
+    const props = new Map();
+    sf.forEachDescendant((node) => {
+        if (!Node.isVariableDeclaration(node))
+            return;
+        const initializer = node.getInitializer();
+        if (!usesAstroProps(initializer))
+            return;
+        const nameNode = node.getNameNode();
+        if (!Node.isObjectBindingPattern(nameNode))
+            return;
+        for (const element of nameNode.getElements()) {
+            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));
+}
+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 project = new Project({
+        compilerOptions: {
+            strict: false,
+            target: 99, // ESNext
+            module: 99, // ESNext
+            allowJs: true,
+        },
+        useInMemoryFileSystem: true,
+        skipAddingFilesFromTsConfig: true,
+    });
+    const sf = project.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 name = property.getName();
+            const decl = property.getValueDeclaration() ?? property.getDeclarations()[0];
+            if (!decl)
+                continue;
+            const propType = property.getTypeAtLocation(decl);
+            const typeText = propType.getText(decl);
+            const required = !property.isOptional();
+            const allowedValues = extractAllowedValues(typeText);
+            props.push({
+                name,
+                type: typeText,
+                required,
+                ...(allowedValues && { allowedValues }),
+                ...(typeof decl.getStartLineNumber === 'function'
+                    ? {
+                        sourceStartLine: decl.getStartLineNumber(),
+                        sourceEndLine: decl.getEndLineNumber(),
+                    }
+                    : {}),
+            });
+        }
+    }
+    return props.sort((a, b) => a.name.localeCompare(b.name));
+}
+function extractDefaultsFromFrontmatter(frontmatter) {
+    const defaults = new Map();
+    const project = new Project({
+        compilerOptions: {
+            strict: false,
+            target: 99,
+            module: 99,
+            allowJs: true,
+        },
+        useInMemoryFileSystem: true,
+        skipAddingFilesFromTsConfig: true,
+    });
+    const sf = project.createSourceFile('__frontmatter__.ts', frontmatter);
+    sf.forEachDescendant((node) => {
+        if (!Node.isVariableDeclaration(node))
+            return;
+        const initializer = node.getInitializer();
+        if (!initializer)
+            return;
+        if (!usesAstroProps(initializer))
+            return;
+        const nameNode = node.getNameNode();
+        if (!Node.isObjectBindingPattern(nameNode))
+            return;
+        for (const element of nameNode.getElements()) {
+            const propName = extractBindingPropName(element);
+            if (!propName)
+                continue;
+            const elementInitializer = element.getInitializer();
+            if (!elementInitializer)
+                continue;
+            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,
+    };
+}
+const ASTRO_EXTRACT_CONCURRENCY = Number(process.env['EDS_EXTRACT_CONCURRENCY'] ?? 0) || os.cpus().length;
+export async function extractAstroComponents(filePaths, onProgress) {
+    const astroFiles = filePaths.filter((f) => f.endsWith('.astro'));
+    if (astroFiles.length === 0) {
+        return { components: [], warnings: [] };
+    }
+    const warnings = [];
+    const components = [];
+    let filesProcessed = 0;
+    let componentsFound = 0;
+    const queue = [...astroFiles];
+    async function worker() {
+        while (queue.length > 0) {
+            const filePath = queue.shift();
+            if (!filePath)
+                break;
+            try {
+                const source = await readFile(filePath, 'utf-8');
+                const component = extractFromAstroFile(filePath, source);
+                if (component) {
+                    components.push(component);
+                    componentsFound++;
+                }
+            }
+            catch (e) {
+                warnings.push(`Failed to extract from ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            filesProcessed++;
+            onProgress?.({ filesProcessed, componentsFound });
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(ASTRO_EXTRACT_CONCURRENCY, astroFiles.length) }, worker));
+    return {
+        components: components.sort((a, b) => a.name.localeCompare(b.name)),
+        warnings,
+    };
+}

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

@@ -0,0 +1,16 @@
+import type { RawComponentDefinition } from '../types.js';
+export 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;

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