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

package/dist/src/extract/helpers/evidence/ast/get-jsx-ast-data.js

@@ -0,0 +1,85 @@
+import { Node } from 'ts-morph';
+/** Collects all names bound in the file via imports or top-level declarations. */
+export function collectLocallyBoundNames(sourceFile) {
+    const names = new Set();
+    for (const imp of sourceFile.getImportDeclarations()) {
+        const defaultImport = imp.getDefaultImport();
+        if (defaultImport)
+            names.add(defaultImport.getText());
+        const namespaceImport = imp.getNamespaceImport();
+        if (namespaceImport)
+            names.add(namespaceImport.getText());
+        for (const named of imp.getNamedImports()) {
+            names.add((named.getAliasNode() ?? named.getNameNode()).getText());
+        }
+    }
+    for (const decl of sourceFile.getVariableDeclarations())
+        names.add(decl.getName());
+    for (const decl of sourceFile.getFunctions()) {
+        const declName = decl.getName();
+        if (declName)
+            names.add(declName);
+    }
+    return names;
+}
+/**
+ * Returns the tag identifier of the JSX element a callback returns, or
+ * `undefined` if the callback doesn't return exactly one identifier-tagged JSX element.
+ */
+export function getReturnedJsxTagName(callback) {
+    const body = callback.getBody();
+    const jsxNode = unwrapReturnedJsx(body);
+    if (!jsxNode)
+        return undefined;
+    if (Node.isJsxSelfClosingElement(jsxNode) || Node.isJsxOpeningElement(jsxNode)) {
+        return jsxNode.getTagNameNode().getText();
+    }
+    if (Node.isJsxElement(jsxNode)) {
+        return jsxNode.getOpeningElement().getTagNameNode().getText();
+    }
+    return undefined;
+}
+/** Unwraps a JSX node from an expression body, block body return, or parenthesized expression. */
+export function unwrapReturnedJsx(bodyOrExpr) {
+    if (Node.isJsxElement(bodyOrExpr) ||
+        Node.isJsxSelfClosingElement(bodyOrExpr) ||
+        Node.isJsxOpeningElement(bodyOrExpr)) {
+        return bodyOrExpr;
+    }
+    if (Node.isJsxFragment(bodyOrExpr)) {
+        return unwrapSingleJsxChildOfFragment(bodyOrExpr);
+    }
+    if (Node.isParenthesizedExpression(bodyOrExpr)) {
+        return unwrapReturnedJsx(bodyOrExpr.getExpression());
+    }
+    if (Node.isBlock(bodyOrExpr)) {
+        const returns = bodyOrExpr.getStatements().filter(Node.isReturnStatement);
+        if (returns.length !== 1)
+            return undefined;
+        const expr = returns[0].getExpression();
+        if (!expr)
+            return undefined;
+        return unwrapReturnedJsx(expr);
+    }
+    return undefined;
+}
+/** Returns the single JSX child of a fragment, or undefined if the fragment has 0 or 2+ children. */
+export function unwrapSingleJsxChildOfFragment(fragment) {
+    if (!Node.isJsxFragment(fragment))
+        return undefined;
+    const jsxChildren = fragment
+        .getJsxChildren()
+        .filter((child) => Node.isJsxElement(child) || Node.isJsxSelfClosingElement(child));
+    if (jsxChildren.length !== 1)
+        return undefined;
+    return jsxChildren[0];
+}
+const JSX_CARRYING_TYPE_TOKENS = ['ReactNode', 'ReactElement', 'JSX.Element'];
+/** Returns true when the type text refers to a React JSX-carrying type (ReactNode, ReactElement, JSX.Element). */
+export function isJsxCarryingTypeText(typeText) {
+    for (const token of JSX_CARRYING_TYPE_TOKENS) {
+        if (typeText.includes(token))
+            return true;
+    }
+    return false;
+}

package/dist/src/extract/helpers/evidence/collect-jsx-component-references.d.ts

@@ -0,0 +1,5 @@
+import { type SourceFile } from 'ts-morph';
+import { type AllowedComponentsContext } from './collect-allowed-component-names.js';
+export { collectRenderedComponentReferences, collectArrayMapRenderComponentReferences, } from './ast/collect-structural-jsx-evidence.js';
+export declare function collectTypePredicateComponentReferences(sourceFile: SourceFile, ctx: AllowedComponentsContext): string[];
+export declare function collectRuntimeTypeCheckComponentReferences(sourceFile: SourceFile, componentNames: ReadonlySet<string>): string[];

package/dist/src/extract/helpers/evidence/collect-jsx-component-references.js

@@ -0,0 +1,52 @@
+import { Node, SyntaxKind, } from 'ts-morph';
+import { extractAllowedComponentsFromTypeText, } from './collect-allowed-component-names.js';
+import { collectLocallyBoundNames } from './ast/get-jsx-ast-data.js';
+export { collectRenderedComponentReferences, collectArrayMapRenderComponentReferences, } from './ast/collect-structural-jsx-evidence.js';
+export function collectTypePredicateComponentReferences(sourceFile, ctx) {
+    const found = new Set();
+    const candidates = [
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.FunctionDeclaration),
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.FunctionExpression),
+    ];
+    for (const fn of candidates) {
+        const returnTypeNode = fn.getReturnTypeNode();
+        if (!returnTypeNode || !Node.isTypePredicate(returnTypeNode))
+            continue;
+        const assertedTypeNode = returnTypeNode.getTypeNode();
+        if (!assertedTypeNode)
+            continue;
+        for (const name of extractAllowedComponentsFromTypeText(assertedTypeNode.getText(), ctx)) {
+            found.add(name);
+        }
+    }
+    return [...found].sort();
+}
+export function collectRuntimeTypeCheckComponentReferences(sourceFile, componentNames) {
+    const found = new Set();
+    const localBindings = collectLocallyBoundNames(sourceFile);
+    for (const binary of sourceFile.getDescendantsOfKind(SyntaxKind.BinaryExpression)) {
+        const operator = binary.getOperatorToken().getText();
+        if (operator !== '===' && operator !== '==')
+            continue;
+        const left = binary.getLeft();
+        const right = binary.getRight();
+        const candidateFromTypeAccess = (typeAccessSide, otherSide) => {
+            if (!Node.isPropertyAccessExpression(typeAccessSide) || typeAccessSide.getName() !== 'type')
+                return undefined;
+            if (!Node.isIdentifier(otherSide) && !Node.isPropertyAccessExpression(otherSide))
+                return undefined;
+            const name = otherSide.getText().split('.').pop();
+            if (!name || !componentNames.has(name))
+                return undefined;
+            const baseIdentifier = Node.isPropertyAccessExpression(otherSide) ? otherSide.getExpression() : otherSide;
+            if (!Node.isIdentifier(baseIdentifier) || !localBindings.has(baseIdentifier.getText()))
+                return undefined;
+            return name;
+        };
+        const match = candidateFromTypeAccess(left, right) ?? candidateFromTypeAccess(right, left);
+        if (match)
+            found.add(match);
+    }
+    return [...found].sort();
+}

package/dist/src/extract/helpers/evidence/detect-slot-from-prop.d.ts

@@ -0,0 +1,16 @@
+export { isReactNodeType, isArrayReactNodeType } from './ast/detect-react-node-types.js';
+/**
+ * Prop names that should remain as props even when typed as ReactNode.
+ * These are typically text-content names, not composable slots.
+ */
+export declare const CONTENT_NAME_EXCEPTIONS: Set<string>;
+/**
+ * Determines whether a prop should be converted to a slot based on its name and type.
+ *
+ * Rules:
+ * 1. If the type is not a ReactNode type → false
+ * 2. If the type is an array ReactNode → true (overrides exception list)
+ * 3. If the name is in the content-name exception list → false
+ * 4. Otherwise → true
+ */
+export declare function shouldBeSlot(propName: string, typeText: string): boolean;

package/dist/src/extract/helpers/evidence/detect-slot-from-prop.js

@@ -0,0 +1,39 @@
+export { isReactNodeType, isArrayReactNodeType } from './ast/detect-react-node-types.js';
+import { isReactNodeType, isArrayReactNodeType } from './ast/detect-react-node-types.js';
+/**
+ * Prop names that should remain as props even when typed as ReactNode.
+ * These are typically text-content names, not composable slots.
+ */
+export const CONTENT_NAME_EXCEPTIONS = new Set([
+    'label',
+    'title',
+    'description',
+    'text',
+    'caption',
+    'message',
+    'placeholder',
+    'tooltip',
+    'heading',
+    'subheading',
+    'body',
+    'summary',
+    'excerpt',
+]);
+/**
+ * Determines whether a prop should be converted to a slot based on its name and type.
+ *
+ * Rules:
+ * 1. If the type is not a ReactNode type → false
+ * 2. If the type is an array ReactNode → true (overrides exception list)
+ * 3. If the name is in the content-name exception list → false
+ * 4. Otherwise → true
+ */
+export function shouldBeSlot(propName, typeText) {
+    if (!isReactNodeType(typeText))
+        return false;
+    if (isArrayReactNodeType(typeText))
+        return true;
+    if (CONTENT_NAME_EXCEPTIONS.has(propName))
+        return false;
+    return true;
+}

package/dist/src/extract/orchestrator/execute-extraction-orchestrator.d.ts

@@ -0,0 +1,13 @@
+import type { ExtractorProgress } from '../types/component.js';
+import type { ExtractionEndpointResponse } from '../types/contract.js';
+import type { ExtractorOptions } from '../types/options.js';
+export interface ExtractionOrchestratorRequest extends ExtractorOptions {
+    readonly filePaths: readonly string[];
+    onProgress?: (progress: ExtractorProgress) => void;
+}
+/**
+ * Executes the extraction use case after the controller has validated the
+ * public request. Owns extraction-time classification, inspection,
+ * quality signals, scoring, and validation, but not transport or persistence.
+ */
+export declare function executeExtractionOrchestrator(request: ExtractionOrchestratorRequest): Promise<ExtractionEndpointResponse>;

package/dist/src/extract/orchestrator/execute-extraction-orchestrator.js

@@ -0,0 +1,17 @@
+import { extractComponents } from '../services/extraction/extract-components.js';
+import { preClassifyComponent } from '../services/classification/classify-component-props.js';
+import { evaluateExtractionQuality } from '../services/quality/evaluate-extraction-quality.js';
+/**
+ * Executes the extraction use case after the controller has validated the
+ * public request. Owns extraction-time classification, inspection,
+ * quality signals, scoring, and validation, but not transport or persistence.
+ */
+export async function executeExtractionOrchestrator(request) {
+    const filePaths = [...request.filePaths];
+    const extraction = await extractComponents(filePaths, request.onProgress, {
+        ...(request.resolveUnreachable !== undefined ? { resolveUnreachable: request.resolveUnreachable } : {}),
+        ...(request.projectRoot !== undefined ? { projectRoot: request.projectRoot } : {}),
+    });
+    const classifiedComponents = extraction.components.map(preClassifyComponent);
+    return evaluateExtractionQuality(classifiedComponents, extraction.warnings);
+}

package/dist/src/{pre-classify.d.ts → extract/services/classification/classify-component-props.d.ts}

@@ -1,8 +1,6 @@
-import type { RawPropDefinition, RawComponentDefinition } from './types.js';
-export interface PreClassification {
-    category: 'content' | 'design' | 'state' | 'exclude';
-    cdfTypeHint?: 'string' | 'enum' | 'richtext' | 'media' | 'boolean';
-}
+import type { RawPropDefinition, RawComponentDefinition } from '../../types/component.js';
+import type { PreClassification } from '../../types/classification.js';
+export type { PreClassification } from '../../types/classification.js';
 /**
  * Deterministic pre-classification rule engine.
  * Applies rules in priority order and returns on the first match.

package/dist/src/{pre-classify.js → extract/services/classification/classify-component-props.js}

@@ -1,96 +1,5 @@
-/**
- * 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;
-}
+import { isStringLiteralUnion, isBooleanType, isStringType, isNumberType, isComplexType, } from './helpers/check-prop-types.js';
+import { isDomPassThroughProp } from './helpers/detect-dom-props.js';
 /**
  * Deterministic pre-classification rule engine.
  * Applies rules in priority order and returns on the first match.
@@ -98,7 +7,6 @@ function isDomPassThroughProp(name) {
 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' };
     }
@@ -119,9 +27,6 @@ export function preClassifyProp(prop) {
         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' };
     }
@@ -211,15 +116,18 @@ export function preClassifyComponent(component) {
         // 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 [
+            {
+                ...authorableProp,
+                category: result.category,
+            },
+        ];
     });
     return { ...component, props };
 }

package/dist/src/extract/services/classification/helpers/check-prop-types.d.ts

@@ -0,0 +1,7 @@
+/** Primitive-type predicates used by the classification rule engine. */
+export declare function isStringLiteralUnion(type: string): boolean;
+export declare function isSimpleType(type: string): boolean;
+export declare function isBooleanType(type: string): boolean;
+export declare function isStringType(type: string): boolean;
+export declare function isNumberType(type: string): boolean;
+export declare function isComplexType(type: string): boolean;

package/dist/src/extract/services/classification/helpers/check-prop-types.js

@@ -0,0 +1,22 @@
+/** Primitive-type predicates used by the classification rule engine. */
+export function isStringLiteralUnion(type) {
+    return type.includes('|') && type.includes("'");
+}
+export function isSimpleType(type) {
+    const t = type.trim();
+    if (t === 'string' || t === 'boolean' || t === 'number')
+        return true;
+    return isStringLiteralUnion(t);
+}
+export function isBooleanType(type) {
+    return type.trim() === 'boolean';
+}
+export function isStringType(type) {
+    return type.trim() === 'string';
+}
+export function isNumberType(type) {
+    return type.trim() === 'number';
+}
+export function isComplexType(type) {
+    return !isSimpleType(type);
+}

package/dist/src/extract/services/classification/helpers/detect-dom-props.d.ts

@@ -0,0 +1,2 @@
+/** Returns true when the prop name is a DOM attribute, a11y attribute, or framework pass-through escape hatch. */
+export declare function isDomPassThroughProp(name: string): boolean;

package/dist/src/extract/services/classification/helpers/detect-dom-props.js

@@ -0,0 +1,63 @@
+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',
+]);
+/** Returns true when the prop name is a DOM attribute, a11y attribute, or framework pass-through escape hatch. */
+export 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;
+    return name.startsWith('data-');
+}

package/dist/src/extract/services/deduplication/deduplicate-components.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentExtractionResult } from '../../types/component.js';
+export declare function deduplicateComponents(results: readonly ComponentExtractionResult[]): ComponentExtractionResult;

package/dist/src/extract/services/deduplication/deduplicate-components.js

@@ -0,0 +1,58 @@
+import { resolveComponentScopeInfo, resolveTopLevelFamilyName, resolveDeduplicationScopeKey, selectPreferredComponentSource, } from './helpers/component-path-scoring.js';
+export function deduplicateComponents(results) {
+    const allWarnings = [];
+    const exclusions = [];
+    const componentsByKey = new Map();
+    const keysByName = new Map();
+    const topLevelFamiliesByRoot = new Map();
+    for (const result of results) {
+        for (const component of result.components) {
+            const scopeInfo = resolveComponentScopeInfo(component.source);
+            if (!scopeInfo)
+                continue;
+            const familyName = resolveTopLevelFamilyName(scopeInfo.relativeSegments);
+            if (!familyName)
+                continue;
+            const existingFamilies = topLevelFamiliesByRoot.get(scopeInfo.rootKey) ?? new Set();
+            existingFamilies.add(familyName);
+            topLevelFamiliesByRoot.set(scopeInfo.rootKey, existingFamilies);
+        }
+    }
+    for (const result of results) {
+        allWarnings.push(...result.warnings);
+        exclusions.push(...(result.exclusions ?? []));
+        for (const component of result.components) {
+            const scopeKey = resolveDeduplicationScopeKey(component.source, component.name, topLevelFamiliesByRoot);
+            const identityKey = `${component.name}::${scopeKey}`;
+            const existing = componentsByKey.get(identityKey);
+            if (existing) {
+                const selected = selectPreferredComponentSource(existing, component);
+                allWarnings.push(`Duplicate component "${component.name}" found in ${component.source} (already seen in ${existing.source}); ${selected.reason}`);
+                exclusions.push({
+                    itemType: 'component',
+                    name: selected.loser.name,
+                    source: selected.loser.source,
+                    reason: `duplicate identity; ${selected.reason}`,
+                    stage: 'duplicate-filter',
+                });
+                componentsByKey.set(identityKey, selected.winner);
+                continue;
+            }
+            const existingKeys = keysByName.get(component.name) ?? [];
+            const crossPackageKey = existingKeys.find((key) => key !== identityKey);
+            if (crossPackageKey) {
+                const crossPackageComponent = componentsByKey.get(crossPackageKey);
+                if (crossPackageComponent) {
+                    allWarnings.push(`Component name collision "${component.name}" found in ${component.source} (also seen in ${crossPackageComponent.source})`);
+                }
+            }
+            componentsByKey.set(identityKey, component);
+            keysByName.set(component.name, [...existingKeys, identityKey]);
+        }
+    }
+    return {
+        components: [...componentsByKey.values()].sort((a, b) => a.name.localeCompare(b.name)),
+        warnings: allWarnings,
+        exclusions,
+    };
+}

package/dist/src/extract/services/deduplication/helpers/component-path-analysis.d.ts

@@ -0,0 +1,10 @@
+export declare function scoreComponentSourcePath(filePath: string): number;
+export declare function resolvePackageRootInfo(segments: string[]): {
+    rootSegments: string[];
+    relativeSegments: string[];
+} | null;
+export declare function resolveComponentScopeInfo(filePath: string): {
+    rootKey: string;
+    relativeSegments: string[];
+} | null;
+export declare function resolveTopLevelFamilyName(relativeSegments: string[]): string | null;

package/dist/src/extract/services/deduplication/helpers/component-path-analysis.js

@@ -0,0 +1,85 @@
+export function scoreComponentSourcePath(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const segments = normalized.split('/').filter(Boolean);
+    const filename = segments.at(-1) ?? '';
+    const basename = filename.replace(/\.[^.]+$/, '');
+    let score = 0;
+    if (/^index\.[jt]sx?$/.test(filename))
+        score += 100;
+    if (basename && segments.at(-2) === basename)
+        score -= 10;
+    score -= segments.filter((segment) => segment === 'components').length * 8;
+    score -= segments.length;
+    return score;
+}
+export function resolvePackageRootInfo(segments) {
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if ((segment === '.packages' || segment === 'packages') && segments[index + 1]) {
+            return {
+                rootSegments: segments.slice(0, index + 2),
+                relativeSegments: segments.slice(index + 2),
+            };
+        }
+    }
+    const srcIndex = segments.lastIndexOf('src');
+    if (srcIndex >= 0) {
+        return {
+            rootSegments: segments.slice(0, srcIndex),
+            relativeSegments: segments.slice(srcIndex),
+        };
+    }
+    return null;
+}
+export function resolveComponentScopeInfo(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const segments = normalized.split('/').filter(Boolean);
+    const rootInfo = resolvePackageRootInfo(segments);
+    if (!rootInfo)
+        return null;
+    return {
+        rootKey: rootInfo.rootSegments.join('/'),
+        relativeSegments: rootInfo.relativeSegments,
+    };
+}
+export function resolveTopLevelFamilyName(relativeSegments) {
+    const [first, second, third] = relativeSegments;
+    if (relativeSegments.length === 1 && first)
+        return first.replace(/\.[^.]+$/, '');
+    if (first === 'src' && second === 'components' && third) {
+        const fileSegment = relativeSegments[3];
+        if (fileSegment &&
+            (fileSegment === `${third}.tsx` ||
+                fileSegment === `${third}.ts` ||
+                fileSegment === 'index.tsx' ||
+                fileSegment === 'index.ts')) {
+            return third;
+        }
+        return null;
+    }
+    if (first === 'src' && second) {
+        const fileSegment = relativeSegments[2];
+        if (fileSegment &&
+            (fileSegment === `${second}.vue` ||
+                fileSegment === `${second}.tsx` ||
+                fileSegment === `${second}.ts` ||
+                fileSegment === 'index.tsx' ||
+                fileSegment === 'index.ts' ||
+                fileSegment === 'index.vue')) {
+            return second;
+        }
+        return null;
+    }
+    if (first) {
+        const fileSegment = relativeSegments[1];
+        if (fileSegment === `${first}.tsx` ||
+            fileSegment === `${first}.ts` ||
+            fileSegment === `${first}.vue` ||
+            fileSegment === 'index.tsx' ||
+            fileSegment === 'index.ts' ||
+            fileSegment === 'index.vue') {
+            return first;
+        }
+    }
+    return null;
+}

package/dist/src/extract/services/deduplication/helpers/component-path-scoring.d.ts

@@ -0,0 +1,10 @@
+import type { RawComponentDefinition } from '../../../types/component.js';
+import { scoreComponentSourcePath, resolvePackageRootInfo, resolveComponentScopeInfo, resolveTopLevelFamilyName } from './component-path-analysis.js';
+export { scoreComponentSourcePath, resolvePackageRootInfo, resolveComponentScopeInfo, resolveTopLevelFamilyName };
+export declare function isWithinComponentFamily(relativeSegments: string[], componentName: string): boolean;
+export declare function resolveDeduplicationScopeKey(filePath: string, componentName: string, topLevelFamiliesByRoot: Map<string, Set<string>>): string;
+export declare function selectPreferredComponentSource(existing: RawComponentDefinition, candidate: RawComponentDefinition): {
+    winner: RawComponentDefinition;
+    loser: RawComponentDefinition;
+    reason: string;
+};