@contentful/experience-design-system-extraction 2.26.1

package/dist/src/index.d.ts

@@ -0,0 +1,20 @@
+export type { RawComponentDefinition, RawPropDefinition, RawSlotDefinition, ComponentExtractionResult, ExtractorProgress, ExtractorOptions, ComponentExtractor, ExtractionValidationIssue, ExtractionValidationIssueCode, } from './types.js';
+export { stripScoringFields } from './types.js';
+export { extractComponents } from './extract/pipeline.js';
+export { extractReactComponents } from './extract/react.js';
+export { extractVueComponents } from './extract/vue.js';
+export { extractVueTsxComponents } from './extract/vue-tsx.js';
+export { extractStencilComponents } from './extract/stencil.js';
+export { extractAstroComponents } from './extract/astro.js';
+export { extractWebComponentDefinitions } from './extract/web-components.js';
+export { extractSvelteComponents } from './extract/svelte.js';
+export { extractAllowedComponentsFromTypeText, extractAllowedComponentsFromJsdoc, } from './extract/slot-allowed-components.js';
+export { isNonAuthorableComponent } from './extract/non-authorable-filter.js';
+export { computeExtractionScore, deriveNeedsReview } from './extract/scoring.js';
+export type { ExtractionScore, ExtractionScoreOptions, ExtractionConfidence } from './extract/scoring.js';
+export { inspectComponentSource, describeReviewReasons, describeReviewReason, isDataWrapperReviewReason, HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON, POSSIBLE_DATA_FETCH_WRAPPER_REASON, ZERO_SURFACE_RENDERED_UI_REASON, } from './extract/source-inspection.js';
+export type { ComponentSourceInspection } from './extract/source-inspection.js';
+export { validateExtractedComponents, shouldExcludeDueToValidation, formatExclusionWarning, } from './extract/validate.js';
+export { CONTENT_NAME_EXCEPTIONS, isReactNodeType, isArrayReactNodeType, shouldBeSlot, } from './extract/slot-detection.js';
+export { preClassifyProp, preClassifyComponent } from './pre-classify.js';
+export type { PreClassification } from './pre-classify.js';

package/dist/src/index.js

@@ -0,0 +1,22 @@
+export { stripScoringFields } from './types.js';
+// Core extraction pipeline
+export { extractComponents } from './extract/pipeline.js';
+// Framework-specific extractors
+export { extractReactComponents } from './extract/react.js';
+export { extractVueComponents } from './extract/vue.js';
+export { extractVueTsxComponents } from './extract/vue-tsx.js';
+export { extractStencilComponents } from './extract/stencil.js';
+export { extractAstroComponents } from './extract/astro.js';
+export { extractWebComponentDefinitions } from './extract/web-components.js';
+export { extractSvelteComponents } from './extract/svelte.js';
+export { extractAllowedComponentsFromTypeText, extractAllowedComponentsFromJsdoc, } from './extract/slot-allowed-components.js';
+// Post-extraction filtering and scoring
+export { isNonAuthorableComponent } from './extract/non-authorable-filter.js';
+export { computeExtractionScore, deriveNeedsReview } from './extract/scoring.js';
+export { inspectComponentSource, describeReviewReasons, describeReviewReason, isDataWrapperReviewReason, HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON, POSSIBLE_DATA_FETCH_WRAPPER_REASON, ZERO_SURFACE_RENDERED_UI_REASON, } from './extract/source-inspection.js';
+// Validation
+export { validateExtractedComponents, shouldExcludeDueToValidation, formatExclusionWarning, } from './extract/validate.js';
+// Slot detection helpers
+export { CONTENT_NAME_EXCEPTIONS, isReactNodeType, isArrayReactNodeType, shouldBeSlot, } from './extract/slot-detection.js';
+// Pre-classification
+export { preClassifyProp, preClassifyComponent } from './pre-classify.js';

package/dist/src/pre-classify.d.ts

@@ -0,0 +1,17 @@
+import type { RawPropDefinition, RawComponentDefinition } from './types.js';
+export interface PreClassification {
+    category: 'content' | 'design' | 'state' | 'exclude';
+    cdfTypeHint?: 'string' | 'enum' | 'richtext' | 'media' | 'boolean';
+}
+/**
+ * Deterministic pre-classification rule engine.
+ * Applies rules in priority order and returns on the first match.
+ */
+export declare function preClassifyProp(prop: RawPropDefinition): PreClassification | undefined;
+/**
+ * Applies pre-classification to all props in a component definition.
+ * - Leaves existing category values unchanged
+ * - Sets category for content/design/state matches
+ * - Removes props that match an exclusion rule so they cannot reach agent classification
+ */
+export declare function preClassifyComponent(component: RawComponentDefinition): RawComponentDefinition;

package/dist/src/pre-classify.js

@@ -0,0 +1,225 @@
+/**
+ * Determines whether a type string represents a simple/primitive type
+ * (string, boolean, number, or string literal union) vs a complex type
+ * (object, function, array, generic, etc.).
+ */
+function isSimpleType(type) {
+    const t = type.trim();
+    if (t === 'string' || t === 'boolean' || t === 'number')
+        return true;
+    // String literal union (e.g., "'a' | 'b'")
+    if (isStringLiteralUnion(t))
+        return true;
+    return false;
+}
+function isStringLiteralUnion(type) {
+    return type.includes('|') && type.includes("'");
+}
+function isBooleanType(type) {
+    return type.trim() === 'boolean';
+}
+function isStringType(type) {
+    return type.trim() === 'string';
+}
+function isNumberType(type) {
+    return type.trim() === 'number';
+}
+function isComplexType(type) {
+    return !isSimpleType(type);
+}
+const DOM_PASS_THROUGH_PROPS = new Set([
+    // Bare HTML / framework styling pass-through
+    'className',
+    'class',
+    'classes',
+    'classNames',
+    'rootClassName',
+    'prefixCls',
+    'style',
+    'styles',
+    // Bare HTML attributes
+    'id',
+    'role',
+    'tabIndex',
+    'tabindex',
+    'htmlFor',
+    'for',
+    'slot',
+    'is',
+    'lang',
+    'dir',
+    'hidden',
+    'draggable',
+    'spellCheck',
+    'spellcheck',
+    'contentEditable',
+    'contenteditable',
+    'inputMode',
+    'inputmode',
+    'autoComplete',
+    'autocomplete',
+    'autoFocus',
+    'autofocus',
+    'translate',
+    'part',
+    'exportparts',
+    'aria',
+    // Framework theming / pass-through escape hatches — dev-facing, never marketer-configurable
+    'dt',
+    'pt',
+    'ptOptions',
+    'unstyled',
+    'sx',
+    // Polymorphic component props — change rendered HTML/component, not marketer-visible behavior
+    'as',
+    'element',
+    'component',
+    // QA / vendor test attributes
+    'dataQa',
+    'data-qa',
+    // Vue v-model internals — framework wiring, never marketer-configurable
+    'modelValue',
+    'modelModifiers',
+]);
+function isDomPassThroughProp(name) {
+    if (DOM_PASS_THROUGH_PROPS.has(name))
+        return true;
+    // aria-label, aria-hidden, ariaLabel, ariaHidden — both kebab and camel forms
+    if (/^aria[-A-Z]/.test(name))
+        return true;
+    if (name.startsWith('data-'))
+        return true;
+    return false;
+}
+/**
+ * Deterministic pre-classification rule engine.
+ * Applies rules in priority order and returns on the first match.
+ */
+export function preClassifyProp(prop) {
+    const { name, type } = prop;
+    // Rule 1: Event handlers
+    // name starts with `on` + uppercase, OR type contains `=> void` or `EventHandler`
+    if (/^on[A-Z]/.test(name) || type.includes('=> void') || type.includes('EventHandler')) {
+        return { category: 'exclude' };
+    }
+    // Rule 2: Refs
+    if (name === 'ref' || name === 'innerRef' || type.includes('Ref<') || type.includes('RefObject<')) {
+        return { category: 'exclude' };
+    }
+    // Rule 3: Test IDs
+    if (name === 'testId' || name === 'data-testid' || name === 'dataTestId') {
+        return { category: 'exclude' };
+    }
+    // Rule 4: Key prop
+    if (name === 'key') {
+        return { category: 'exclude' };
+    }
+    // Rule 5: Dispatch/setter
+    if (type.includes('Dispatch<') || type.includes('SetStateAction')) {
+        return { category: 'exclude' };
+    }
+    // Rule 6: DOM / a11y / framework pass-through props
+    // These are escape hatches developers use to wire components into the DOM.
+    // Marketers should never configure them in the ExO editor; exposing them
+    // generates noise that obscures the props that actually carry intent.
+    if (isDomPassThroughProp(name)) {
+        return { category: 'exclude' };
+    }
+    // `name` is overloaded: form controls forward it to the DOM, while icons,
+    // flags, and animations often use it as an authorable semantic selector.
+    // Exclude only when the extractor retained concrete DOM provenance.
+    if (name === 'name' && prop.domAttribute) {
+        return { category: 'exclude' };
+    }
+    // Rule 7: String literal union
+    if (isStringLiteralUnion(type)) {
+        return { category: 'design', cdfTypeHint: 'enum' };
+    }
+    // Rule 8: Design name patterns (only for simple types)
+    if (!isComplexType(type)) {
+        const designNameStart = /^(variant|size|spacing|gap|color|bg|theme|align|layout|orientation|position)/i;
+        const designNameEnd = /(Color|Size|Variant|Style)$/;
+        if (designNameStart.test(name) || designNameEnd.test(name)) {
+            return { category: 'design', cdfTypeHint: 'string' };
+        }
+    }
+    // Rule 10: Boolean + state names (checked before rule 9 since state names
+    // like "disabled" would otherwise match the visual toggle prefix "disable")
+    if (isBooleanType(type)) {
+        const stateNames = ['disabled', 'loading', 'expanded', 'isOpen', 'selected', 'checked', 'active', 'preview'];
+        if (stateNames.includes(name)) {
+            return { category: 'state', cdfTypeHint: 'boolean' };
+        }
+    }
+    // Rule 9: Boolean + visual toggle name
+    if (isBooleanType(type)) {
+        const visualToggle = /^(hide|show|enable|disable|vertical|horizontal|reverse|bold|italic|imageOn|with)/i;
+        if (visualToggle.test(name)) {
+            return { category: 'design', cdfTypeHint: 'boolean' };
+        }
+    }
+    // Rule 11: State identifiers
+    if (name === 'componentId' || name === 'sectionKey' || name === 'locale' || name === 'variantIndex') {
+        return { category: 'state', cdfTypeHint: 'string' };
+    }
+    // Rule 12: URL patterns (string type only)
+    if (isStringType(type)) {
+        const urlNameStart = /^(href|url|link|src)/i;
+        const urlNameEnd = /(Url|Href|Link|Src)$/;
+        if (urlNameStart.test(name) || urlNameEnd.test(name)) {
+            return { category: 'content', cdfTypeHint: 'string' };
+        }
+    }
+    // Rule 13: Text patterns (string type only)
+    if (isStringType(type)) {
+        const textNameStart = /^(label|title|text|description|caption|heading|subheading|body|alt|name|placeholder|summary)/i;
+        const textNameEnd = /(Text|Label|Title|Name)$/;
+        if (textNameStart.test(name) || textNameEnd.test(name)) {
+            return { category: 'content', cdfTypeHint: 'string' };
+        }
+    }
+    // Rule 14: Remaining strings
+    if (isStringType(type)) {
+        return { category: 'content', cdfTypeHint: 'string' };
+    }
+    // Rule 15: Remaining booleans
+    if (isBooleanType(type)) {
+        return { category: 'design', cdfTypeHint: 'boolean' };
+    }
+    // Rule 16: Remaining numbers
+    if (isNumberType(type)) {
+        return { category: 'design', cdfTypeHint: 'string' };
+    }
+    // Rule 17: Complex/object/function/array types — no hint
+    return undefined;
+}
+/**
+ * Applies pre-classification to all props in a component definition.
+ * - Leaves existing category values unchanged
+ * - Sets category for content/design/state matches
+ * - Removes props that match an exclusion rule so they cannot reach agent classification
+ */
+export function preClassifyComponent(component) {
+    const props = component.props.flatMap((prop) => {
+        const result = preClassifyProp(prop);
+        // Excluded props are developer-facing wiring and must not be included in
+        // the component payload passed to classification or generation, even if a
+        // prior step assigned them a category.
+        if (result?.category === 'exclude') {
+            return [];
+        }
+        // Provenance is extraction-only evidence. Do not add it to the payload
+        // presented to downstream agents.
+        const { domAttribute: _domAttribute, ...authorableProp } = prop;
+        // If category is already set, leave unchanged
+        if (prop.category) {
+            return [authorableProp];
+        }
+        if (!result) {
+            return [authorableProp];
+        }
+        // Set category hint
+        return [{ ...authorableProp, category: result.category }];
+    });
+    return { ...component, props };
+}

package/dist/src/types.d.ts

@@ -0,0 +1,91 @@
+export type ExtractionValidationIssueCode = 'EMPTY_COMPONENT_NAME' | 'EMPTY_PROP_NAME' | 'EMPTY_SLOT_NAME' | 'PROP_SLOT_NAME_COLLISION' | 'DUPLICATE_COMPONENT_NAME' | 'EMPTY_COMPONENT' | 'SERVER_VALIDATION_FAILED';
+export type ExtractionValidationIssue = {
+    severity: 'error' | 'warning';
+    code: ExtractionValidationIssueCode;
+    message: string;
+    field?: string;
+};
+export interface RawPropDefinition {
+    name: string;
+    type: string;
+    required: boolean;
+    /**
+     * True when extraction can prove that the prop is forwarded to the
+     * same-named attribute on an intrinsic DOM element. This distinguishes
+     * overloaded names such as the form attribute `name` from semantic props
+     * that select visible content (for example an icon or flag name).
+     */
+    domAttribute?: boolean;
+    category?: 'content' | 'design' | 'state';
+    defaultValue?: string;
+    allowedValues?: string[];
+    description?: string;
+    tokenReference?: string;
+    /** 1-indexed source line where this prop's declaration begins; relative to RawComponentDefinition.source. */
+    sourceStartLine?: number;
+    /** 1-indexed inclusive source line where this prop's declaration ends; relative to RawComponentDefinition.source. */
+    sourceEndLine?: number;
+}
+export interface RawSlotDefinition {
+    name: string;
+    isDefault: boolean;
+    description?: string;
+    allowedComponents?: string[];
+    /**
+     * Component names implied by usage evidence (a runtime type-predicate
+     * function, a `.type === Component` identity check, or direct JSX
+     * instantiation) rather than a declared slot contract. Kept separate from
+     * `allowedComponents` so downstream provenance stays honest — this is a
+     * lower-trust signal that a declared contract always overrides.
+     */
+    structuralAllowedComponents?: string[];
+}
+export interface RawComponentDefinition {
+    name: string;
+    source: string;
+    framework: 'react' | 'next' | 'vue' | 'astro' | 'web-component' | 'stencil' | 'svelte';
+    props: RawPropDefinition[];
+    slots: RawSlotDefinition[];
+    /**
+     * True when the source file declaring this component calls
+     * React.createContext / createContext. Used downstream to filter
+     * non-authorable context-provider components.
+     */
+    usesCreateContext?: boolean;
+    extractionConfidence?: number | null;
+    reviewReasons?: string[];
+    needsReview?: boolean;
+    validationIssues?: ExtractionValidationIssue[];
+    /** Absolute path to the source file this component was extracted from. Null for synthesized / multi-file. */
+    sourcePath?: string;
+}
+export interface ComponentExtractionResult {
+    components: RawComponentDefinition[];
+    warnings: string[];
+}
+export type ExtractorProgress = {
+    filesProcessed: number;
+    componentsFound: number;
+};
+/**
+ * Optional extraction-time settings forwarded from the CLI through the
+ * pipeline to each extractor. Only the Svelte extractor currently consumes
+ * any of these; other extractors ignore the value.
+ */
+export interface ExtractorOptions {
+    /**
+     * Whether the Svelte extractor should run a retry pass for components whose
+     * declared Props type couldn't be resolved on the first pass (cross-package
+     * extends, path-alias-only types, etc.). See svelte.ts for the policy.
+     */
+    resolveUnreachable?: 'auto' | 'always' | 'never';
+    /** Absolute project root — used by the retry pass to locate tsconfig.json and node_modules. */
+    projectRoot?: string;
+}
+export interface ComponentExtractor {
+    name: string;
+    fileFilter: (filePath: string) => boolean;
+    extract(filePaths: string[], onProgress?: (p: ExtractorProgress) => void, opts?: ExtractorOptions): Promise<ComponentExtractionResult>;
+}
+/** Strip internal scoring fields before serialising a RawComponentDefinition for display or editing. */
+export declare function stripScoringFields({ extractionConfidence: _c, reviewReasons: _r, needsReview: _n, ...rest }: RawComponentDefinition): Omit<RawComponentDefinition, 'extractionConfidence' | 'reviewReasons' | 'needsReview'>;

package/dist/src/types.js

@@ -0,0 +1,4 @@
+/** Strip internal scoring fields before serialising a RawComponentDefinition for display or editing. */
+export function stripScoringFields({ extractionConfidence: _c, reviewReasons: _r, needsReview: _n, ...rest }) {
+    return rest;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "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/"
+  ],
+  "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"
+  },
+  "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"
+  }
+}