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

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

@@ -0,0 +1,73 @@
+import { scoreComponentSourcePath, resolvePackageRootInfo, resolveComponentScopeInfo, resolveTopLevelFamilyName, } from './component-path-analysis.js';
+export { scoreComponentSourcePath, resolvePackageRootInfo, resolveComponentScopeInfo, resolveTopLevelFamilyName };
+export function isWithinComponentFamily(relativeSegments, componentName) {
+    const [first, second, third] = relativeSegments;
+    const componentFilenames = new Set([
+        `${componentName}.tsx`,
+        `${componentName}.ts`,
+        `${componentName}.vue`,
+        'index.tsx',
+        'index.ts',
+        'index.vue',
+    ]);
+    if (relativeSegments.length === 1) {
+        return new Set([`${componentName}.tsx`, `${componentName}.ts`, `${componentName}.vue`]).has(first);
+    }
+    if (first === 'src' && second === 'components' && third === componentName)
+        return true;
+    if (first === 'components' && second === componentName)
+        return true;
+    if (first === 'src' && second === componentName)
+        return true;
+    if (first === componentName)
+        return componentFilenames.has(second) || relativeSegments.length > 2;
+    return false;
+}
+export function resolveDeduplicationScopeKey(filePath, componentName, topLevelFamiliesByRoot) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const scopeInfo = resolveComponentScopeInfo(filePath);
+    if (!scopeInfo)
+        return normalized;
+    const { rootKey, relativeSegments } = scopeInfo;
+    const topLevelFamilies = topLevelFamiliesByRoot.get(rootKey);
+    if (topLevelFamilies?.has(componentName) && isWithinComponentFamily(relativeSegments, componentName)) {
+        return `${rootKey}::${componentName}`;
+    }
+    const [first, second, third] = relativeSegments;
+    if (first === 'src' && second === 'components' && third)
+        return `${rootKey}/src/components/${third}`;
+    if (first === 'components' && second)
+        return `${rootKey}/components/${second}`;
+    if (first === 'src' && second && relativeSegments.length > 2)
+        return `${rootKey}/src/${second}`;
+    if (first && relativeSegments.length > 1)
+        return `${rootKey}/${first}`;
+    return rootKey;
+}
+export function selectPreferredComponentSource(existing, candidate) {
+    const existingScore = scoreComponentSourcePath(existing.source);
+    const candidateScore = scoreComponentSourcePath(candidate.source);
+    if (candidateScore > existingScore)
+        return {
+            winner: candidate,
+            loser: existing,
+            reason: `preferred ${candidate.source} over ${existing.source} based on path heuristics`,
+        };
+    if (candidateScore < existingScore)
+        return {
+            winner: existing,
+            loser: candidate,
+            reason: `kept ${existing.source} over ${candidate.source} based on path heuristics`,
+        };
+    if (candidate.source.length < existing.source.length)
+        return {
+            winner: candidate,
+            loser: existing,
+            reason: `preferred shorter path ${candidate.source} over ${existing.source}`,
+        };
+    return {
+        winner: existing,
+        loser: candidate,
+        reason: `kept ${existing.source} over ${candidate.source} by stable first-seen order`,
+    };
+}

package/dist/src/extract/services/extraction/extract-components.d.ts

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

package/dist/src/extract/services/extraction/extract-components.js

@@ -0,0 +1,19 @@
+import { deduplicateComponents } from '../deduplication/deduplicate-components.js';
+import { extractorRegistry, routeFilesToExtractors } from './helpers/register-extractors.js';
+import { runExtractorBatches } from './helpers/run-extractor-batches.js';
+import { collectSvelteKitRouteExclusions } from './helpers/collect-sveltekit-route-exclusions.js';
+import { filterHookComponents } from './helpers/filter-hook-components.js';
+export async function extractComponents(filePaths, onProgress, opts) {
+    const routeExclusions = collectSvelteKitRouteExclusions(filePaths);
+    const routedFiles = routeFilesToExtractors(filePaths, extractorRegistry);
+    const results = await runExtractorBatches(routedFiles, onProgress, opts);
+    const deduplicated = deduplicateComponents(results);
+    const { components, exclusions: hookExclusions, warnings: hookWarnings, } = filterHookComponents(deduplicated.components);
+    deduplicated.warnings.push(...hookWarnings);
+    const allExclusions = [...routeExclusions, ...hookExclusions, ...(deduplicated.exclusions ?? [])];
+    return {
+        components,
+        warnings: deduplicated.warnings,
+        ...(allExclusions.length > 0 ? { exclusions: allExclusions } : {}),
+    };
+}

package/dist/src/extract/services/extraction/helpers/collect-sveltekit-route-exclusions.d.ts

@@ -0,0 +1,2 @@
+import type { ExtractionExclusion } from '../../../types/component.js';
+export declare function collectSvelteKitRouteExclusions(filePaths: string[]): ExtractionExclusion[];

package/dist/src/extract/services/extraction/helpers/collect-sveltekit-route-exclusions.js

@@ -0,0 +1,18 @@
+export function collectSvelteKitRouteExclusions(filePaths) {
+    return filePaths.flatMap((filePath) => {
+        if (!filePath.endsWith('.svelte'))
+            return [];
+        const name = filePath.replace(/\\/g, '/').split('/').pop() ?? '';
+        if (!/^\+(page|layout|error)\.svelte$/.test(name))
+            return [];
+        return [
+            {
+                itemType: 'file',
+                name,
+                source: filePath,
+                reason: 'SvelteKit route entrypoints are framework-managed, not authorable components',
+                stage: 'file-filter',
+            },
+        ];
+    });
+}

package/dist/src/extract/services/extraction/helpers/filter-hook-components.d.ts

@@ -0,0 +1,6 @@
+import type { ExtractionExclusion, RawComponentDefinition } from '../../../types/component.js';
+export declare function filterHookComponents(components: RawComponentDefinition[]): {
+    components: RawComponentDefinition[];
+    exclusions: ExtractionExclusion[];
+    warnings: string[];
+};

package/dist/src/extract/services/extraction/helpers/filter-hook-components.js

@@ -0,0 +1,18 @@
+export function filterHookComponents(components) {
+    const exclusions = [];
+    const warnings = [];
+    const kept = components.filter((component) => {
+        if (!/^use[A-Z]/.test(component.name))
+            return true;
+        warnings.push(`Skipped hook: ${component.name} (hooks are not renderable components)`);
+        exclusions.push({
+            itemType: 'component',
+            name: component.name,
+            source: component.source,
+            reason: 'Hook names are not renderable components',
+            stage: 'component-filter',
+        });
+        return false;
+    });
+    return { components: kept, exclusions, warnings };
+}

package/dist/src/extract/services/extraction/helpers/register-extractors.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentExtractor } from '../../../types/component-extractor.js';
+export interface ExtractorFileGroup {
+    extractor: ComponentExtractor;
+    filePaths: string[];
+}
+/** Ordered adapter registration; overlapping filters intentionally allow a file to be inspected by multiple adapters. */
+export declare const extractorRegistry: readonly ComponentExtractor[];
+export declare function routeFilesToExtractors(filePaths: readonly string[], extractors?: readonly ComponentExtractor[]): ExtractorFileGroup[];

package/dist/src/extract/services/extraction/helpers/register-extractors.js

@@ -0,0 +1,71 @@
+import { extractAstroComponents } from '../../../framework-adapters/astro/extractor.js';
+import { extractReactComponents } from '../../../framework-adapters/react/extractor.js';
+import { extractStencilComponents } from '../../../framework-adapters/stencil/extractor.js';
+import { extractSvelteComponents } from '../../../framework-adapters/svelte/extractor.js';
+import { extractVueTsxComponents } from '../../../framework-adapters/vue-tsx/extractor.js';
+import { extractVueComponents } from '../../../framework-adapters/vue/extractor.js';
+import { extractWebComponentDefinitions } from '../../../framework-adapters/web-components/extractor.js';
+/** Ordered adapter registration; overlapping filters intentionally allow a file to be inspected by multiple adapters. */
+export const extractorRegistry = [
+    {
+        name: 'stencil',
+        fileFilter: (filePath) => /\.[jt]sx$/.test(filePath),
+        extract: extractStencilComponents,
+    },
+    {
+        name: 'react',
+        fileFilter: (filePath) => /\.[jt]sx?$/.test(filePath) && !filePath.endsWith('.d.ts'),
+        extract: extractReactComponents,
+    },
+    {
+        name: 'vue-tsx',
+        fileFilter: (filePath) => /\.[jt]sx?$/.test(filePath) && !filePath.endsWith('.d.ts'),
+        extract: extractVueTsxComponents,
+    },
+    {
+        name: 'vue',
+        fileFilter: (filePath) => filePath.endsWith('.vue'),
+        extract: extractVueComponents,
+    },
+    {
+        name: 'astro',
+        fileFilter: (filePath) => filePath.endsWith('.astro'),
+        extract: extractAstroComponents,
+    },
+    {
+        name: 'web-components',
+        fileFilter: (filePath) => /\.[jt]s$/.test(filePath) && !/\.[jt]sx$/.test(filePath) && !filePath.endsWith('.d.ts'),
+        extract: extractWebComponentDefinitions,
+    },
+    {
+        name: 'svelte',
+        fileFilter: (filePath) => {
+            if (!filePath.endsWith('.svelte'))
+                return false;
+            const filename = filePath.replace(/\\/g, '/').split('/').pop() ?? '';
+            if (/^\+(page|layout|error)\.svelte$/.test(filename))
+                return false;
+            return true;
+        },
+        extract: extractSvelteComponents,
+    },
+];
+export function routeFilesToExtractors(filePaths, extractors = extractorRegistry) {
+    const filesByExtractor = new Map();
+    for (const extractor of extractors) {
+        filesByExtractor.set(extractor, []);
+    }
+    for (const filePath of filePaths) {
+        for (const extractor of extractors) {
+            if (extractor.fileFilter(filePath)) {
+                filesByExtractor.get(extractor)?.push(filePath);
+            }
+        }
+    }
+    return extractors
+        .map((extractor) => ({
+        extractor,
+        filePaths: filesByExtractor.get(extractor) ?? [],
+    }))
+        .filter(({ filePaths: groupedFilePaths }) => groupedFilePaths.length > 0);
+}

package/dist/src/extract/services/extraction/helpers/run-extractor-batches.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentExtractionResult, ExtractorProgress } from '../../../types/component.js';
+import type { ExtractorOptions } from '../../../types/options.js';
+import type { ExtractorFileGroup } from './register-extractors.js';
+export declare function runExtractorBatches(batches: readonly ExtractorFileGroup[], onProgress?: (progress: ExtractorProgress) => void, options?: ExtractorOptions): Promise<ComponentExtractionResult[]>;

package/dist/src/extract/services/extraction/helpers/run-extractor-batches.js

@@ -0,0 +1,24 @@
+export async function runExtractorBatches(batches, onProgress, options) {
+    const perExtractorFiles = new Map();
+    const perExtractorComponents = new Map();
+    let totalFilesProcessed = 0;
+    let totalComponentsFound = 0;
+    return Promise.all(batches.map(async ({ extractor, filePaths }) => {
+        if (filePaths.length === 0)
+            return { components: [], warnings: [] };
+        perExtractorFiles.set(extractor, 0);
+        perExtractorComponents.set(extractor, 0);
+        return extractor.extract(filePaths, (progress) => {
+            const previousFiles = perExtractorFiles.get(extractor) ?? 0;
+            const previousComponents = perExtractorComponents.get(extractor) ?? 0;
+            totalFilesProcessed += progress.filesProcessed - previousFiles;
+            totalComponentsFound += progress.componentsFound - previousComponents;
+            perExtractorFiles.set(extractor, progress.filesProcessed);
+            perExtractorComponents.set(extractor, progress.componentsFound);
+            onProgress?.({
+                filesProcessed: totalFilesProcessed,
+                componentsFound: totalComponentsFound,
+            });
+        }, options);
+    }));
+}

package/dist/src/extract/services/quality/evaluate-extraction-quality.d.ts

@@ -0,0 +1,4 @@
+import type { RawComponentDefinition } from '../../types/component.js';
+import type { ExtractionEndpointResponse } from '../../types/contract.js';
+/** Applies inspection, authorability, scoring, review, and validation policies to extracted models. */
+export declare function evaluateExtractionQuality(components: readonly RawComponentDefinition[], initialWarnings?: readonly string[]): Promise<ExtractionEndpointResponse>;

package/dist/src/extract/services/quality/evaluate-extraction-quality.js

@@ -0,0 +1,61 @@
+import { hasNoAuthoringSurface } from './helpers/authorability/evaluate-authorability.js';
+import { computeExtractionScore, deriveNeedsReview } from './helpers/scoring/compute-extraction-score.js';
+import { inspectComponentSource, describeReviewReasons } from './helpers/inspection/inspect-component-source.js';
+import { validateExtractedComponents } from './helpers/inspection/validate-extracted-components.js';
+function wrapperConfidenceToIssueCount(confidence) {
+    if (confidence >= 4)
+        return 2;
+    if (confidence === 3)
+        return 1;
+    return 0;
+}
+/** Applies inspection, authorability, scoring, review, and validation policies to extracted models. */
+export async function evaluateExtractionQuality(components, initialWarnings = []) {
+    const inspectedComponents = await Promise.all(components.map(async (component) => ({
+        component,
+        inspection: await inspectComponentSource(component),
+    })));
+    const scoredComponents = [];
+    const warnings = [...initialWarnings];
+    for (const { component, inspection } of inspectedComponents) {
+        const verdict = hasNoAuthoringSurface(component);
+        const keepDespiteZeroSurface = verdict.skip && verdict.reason === 'component has no props and no slots' && inspection.keepDespiteZeroSurface;
+        const retainedForReview = verdict.skip && !keepDespiteZeroSurface;
+        if (retainedForReview) {
+            warnings.push(`${component.name}: requires operator review (${verdict.reason})`);
+        }
+        if (keepDespiteZeroSurface) {
+            warnings.push(`${component.name}: retained despite 0 props/slots because the source renders visible or compositional UI`);
+        }
+        if (inspection.reviewReasons.length > 0) {
+            const reviewNotes = describeReviewReasons(inspection.reviewReasons)
+                .filter((note) => note !== 'high-confidence data-fetch wrapper')
+                .join('; ');
+            if (reviewNotes)
+                warnings.push(`${component.name}: ${reviewNotes}`);
+        }
+        const extractorReasons = component.reviewReasons ?? [];
+        const nonAuthorableReason = retainedForReview ? [`non-authorable:${verdict.reason}`] : [];
+        const { confidence, reasons } = computeExtractionScore(component, {
+            additionalIssueCount: wrapperConfidenceToIssueCount(inspection.wrapperConfidence) +
+                extractorReasons.length +
+                nonAuthorableReason.length,
+            additionalReasons: [...extractorReasons, ...inspection.reviewReasons, ...nonAuthorableReason],
+        });
+        scoredComponents.push({
+            ...component,
+            extractionConfidence: confidence,
+            reviewReasons: reasons,
+            needsReview: deriveNeedsReview(confidence) ||
+                inspection.wrapperConfidence >= 4 ||
+                inspection.keepDespiteZeroSurface ||
+                retainedForReview ||
+                extractorReasons.includes('props-type-unresolved') ||
+                (component.needsReview ?? false),
+        });
+    }
+    return {
+        components: validateExtractedComponents(scoredComponents),
+        warnings,
+    };
+}

package/dist/src/extract/services/quality/helpers/authorability/evaluate-authorability.d.ts

@@ -0,0 +1,28 @@
+import type { RawComponentDefinition, RawPropDefinition, RawSlotDefinition } from '../../../../types/component.js';
+export interface AuthoringSurfaceCheck {
+    skip: boolean;
+    reason?: string;
+}
+/** Returns true when the prop is an event-handler function or a React ref — not something a content editor configures. */
+export declare function isHandlerOrRefProp(prop: RawPropDefinition): boolean;
+/** Rule 1: no props AND no slots — analytics scripts, GTM tags, layout fixers, security tokens, etc. */
+export declare function hasNoPropsAndNoSlots(props: RawPropDefinition[], slots: RawSlotDefinition[]): boolean;
+/** Rule 2: createContext source with a prop literally named `value` — the canonical `<Context.Provider value={...}>` call site. */
+export declare function isContextProviderWithValueProp(props: RawPropDefinition[], usesCreateContext: boolean | undefined): boolean;
+/** Rule 3: createContext source with zero props — a Provider that hard-codes its context value internally (e.g. FontProvider). */
+export declare function isHardwiredContextProvider(props: RawPropDefinition[], usesCreateContext: boolean | undefined): boolean;
+/** Rule 4: createContext source with exactly one non-handler prop — a Provider that takes its context value as a single data prop (e.g. LocaleProvider, NavigationProvider). */
+export declare function isSingleDataPropContextWrapper(props: RawPropDefinition[], usesCreateContext: boolean | undefined): boolean;
+/** Rule 5: every prop is an event handler or ref — pure plumbing with no authoring surface (e.g. OsanoCookiePlaceholder({ onBannerLoaded })). */
+export declare function hasOnlyEventHandlers(props: RawPropDefinition[]): boolean;
+/**
+ * Checks whether a component has no surface for a content editor to configure.
+ * Returns { skip: true, reason } for infrastructure components that should be
+ * flagged for operator review 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 hasNoAuthoringSurface(component: RawComponentDefinition): AuthoringSurfaceCheck;

package/dist/src/extract/services/quality/helpers/authorability/evaluate-authorability.js

@@ -0,0 +1,67 @@
+const HANDLER_TYPE_PATTERN = /=>|EventHandler|Dispatch<|SetStateAction/;
+const REF_TYPE_PATTERN = /Ref<|RefObject<|MutableRefObject/;
+/** Returns true when the prop is an event-handler function or a React ref — not something a content editor configures. */
+export 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;
+}
+/** Rule 1: no props AND no slots — analytics scripts, GTM tags, layout fixers, security tokens, etc. */
+export function hasNoPropsAndNoSlots(props, slots) {
+    return props.length === 0 && slots.length === 0;
+}
+/** Rule 2: createContext source with a prop literally named `value` — the canonical `<Context.Provider value={...}>` call site. */
+export function isContextProviderWithValueProp(props, usesCreateContext) {
+    return !!usesCreateContext && props.some((p) => p.name === 'value');
+}
+/** Rule 3: createContext source with zero props — a Provider that hard-codes its context value internally (e.g. FontProvider). */
+export function isHardwiredContextProvider(props, usesCreateContext) {
+    return !!usesCreateContext && props.length === 0;
+}
+/** Rule 4: createContext source with exactly one non-handler prop — a Provider that takes its context value as a single data prop (e.g. LocaleProvider, NavigationProvider). */
+export function isSingleDataPropContextWrapper(props, usesCreateContext) {
+    return !!usesCreateContext && props.length === 1 && !isHandlerOrRefProp(props[0]);
+}
+/** Rule 5: every prop is an event handler or ref — pure plumbing with no authoring surface (e.g. OsanoCookiePlaceholder({ onBannerLoaded })). */
+export function hasOnlyEventHandlers(props) {
+    return props.length > 0 && props.every(isHandlerOrRefProp);
+}
+/**
+ * Checks whether a component has no surface for a content editor to configure.
+ * Returns { skip: true, reason } for infrastructure components that should be
+ * flagged for operator review 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 hasNoAuthoringSurface(component) {
+    const { props, slots, usesCreateContext } = component;
+    if (hasNoPropsAndNoSlots(props, slots))
+        return { skip: true, reason: 'component has no props and no slots' };
+    if (isContextProviderWithValueProp(props, usesCreateContext))
+        return {
+            skip: true,
+            reason: 'source uses createContext and component exposes a Context.Provider value prop',
+        };
+    if (isHardwiredContextProvider(props, usesCreateContext))
+        return {
+            skip: true,
+            reason: 'source uses createContext and component has no props',
+        };
+    if (isSingleDataPropContextWrapper(props, usesCreateContext))
+        return {
+            skip: true,
+            reason: 'source uses createContext and component has a single non-handler prop',
+        };
+    if (hasOnlyEventHandlers(props))
+        return { skip: true, reason: 'every prop is a handler or ref' };
+    return { skip: false };
+}

package/dist/src/extract/services/quality/helpers/inspection/detect-data-wrapper-patterns.d.ts

@@ -0,0 +1,16 @@
+import type { RawComponentDefinition } from '../../../../types/component.js';
+export declare const DATA_WRAPPER_REASON_PREFIX = "data-wrapper:";
+export declare const VISIBLE_UI_TAG_PATTERN: RegExp;
+export declare const GENERATED_IMPORT_PATTERN: RegExp;
+export declare const GENERATED_QUERY_HOOK_PATTERN: RegExp;
+export declare const GQL_FILENAME_PATTERN: RegExp;
+export declare const LOADING_NULL_GUARD_PATTERN: RegExp;
+export declare function escapeRegExp(value: string): string;
+export declare function collectSiblingRendererImports(sourceText: string): string[];
+export declare function hasSiblingForwardRender(sourceText: string, siblingImports: string[]): boolean;
+export declare function hasVisibleUiRender(sourceText: string): boolean;
+/** Returns the prop names when all props are infra-only fetch props; returns empty array otherwise. */
+export declare function collectInfraPropNames(component: RawComponentDefinition): string[];
+/** Maps a raw wrapper evidence score (0–∞) to a 0–5 confidence value. */
+export declare function mapScoreToWrapperConfidence(score: number): 0 | 1 | 2 | 3 | 4 | 5;
+export declare function dedupeStrings(values: string[]): string[];

package/dist/src/extract/services/quality/helpers/inspection/detect-data-wrapper-patterns.js

@@ -0,0 +1,63 @@
+import { parseImportedNames } from '../../../../helpers/evidence/parse-source-imports.js';
+export const DATA_WRAPPER_REASON_PREFIX = 'data-wrapper:';
+const INFRA_PROP_NAMES = new Set(['id', 'locale', 'preview', 'slug', 'topic', 'previousComponent', '__typename']);
+export const VISIBLE_UI_TAG_PATTERN = /<(?:[A-Z][A-Za-z0-9_.]*|div|span|section|main|article|header|footer|nav|aside|img|video|p|h[1-6]|ul|ol|li|button|input|textarea|select|form|label|table|tbody|thead|tr|td|th)\b/;
+export const GENERATED_IMPORT_PATTERN = /from\s+['"][^'"]*__generated[^'"]*['"]/;
+export const GENERATED_QUERY_HOOK_PATTERN = /\buse[A-Z][A-Za-z0-9]*(?:Lazy|Suspense)?Query\s*\(/;
+export const GQL_FILENAME_PATTERN = /(?:-gql|-ggl)\.[cm]?[jt]sx?$/i;
+export const LOADING_NULL_GUARD_PATTERN = /if\s*\([^)]*(?:isLoading|loading|!data|!\w+Collection|!\w+Item|!\w+)\s*[^)]*\)\s*return\s+null\b/;
+const IMPORT_PATTERN = /import\s+(?:type\s+)?(.+?)\s+from\s+['"]([^'"]+)['"]/g;
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function collectSiblingRendererImports(sourceText) {
+    const names = new Set();
+    for (const match of sourceText.matchAll(IMPORT_PATTERN)) {
+        const importClause = match[1]?.trim() ?? '';
+        const importPath = match[2]?.trim() ?? '';
+        if (!importPath.startsWith('./'))
+            continue;
+        if (importPath.includes('__generated'))
+            continue;
+        if (/-g(?:ql|gl)(?:$|\.)/i.test(importPath))
+            continue;
+        for (const name of parseImportedNames(importClause)) {
+            if (name)
+                names.add(name);
+        }
+    }
+    return [...names];
+}
+export function hasSiblingForwardRender(sourceText, siblingImports) {
+    return siblingImports.some((name) => {
+        const renderPattern = new RegExp(`<${escapeRegExp(name)}\\b[\\s\\S]*?(?:/>|</${escapeRegExp(name)}>)`);
+        if (!renderPattern.test(sourceText))
+            return false;
+        const siblingSpreadPattern = new RegExp(`<${escapeRegExp(name)}\\b[^>]*\\{\\.\\.\\.(?!props\\b)[^}]+\\}`);
+        const propsPlusSiblingSpreadPattern = new RegExp(`<${escapeRegExp(name)}\\b[^>]*\\{\\.\\.\\.props\\}[^>]*\\{\\.\\.\\.(?!props\\b)[^}]+\\}`);
+        return siblingSpreadPattern.test(sourceText) || propsPlusSiblingSpreadPattern.test(sourceText);
+    });
+}
+export function hasVisibleUiRender(sourceText) {
+    return /return\s*(?:\(|<)/.test(sourceText) && VISIBLE_UI_TAG_PATTERN.test(sourceText);
+}
+/** Returns the prop names when all props are infra-only fetch props; returns empty array otherwise. */
+export function collectInfraPropNames(component) {
+    const props = component.props.map((prop) => prop.name);
+    return props.length > 0 && props.every((prop) => INFRA_PROP_NAMES.has(prop)) ? props : [];
+}
+/** Maps a raw wrapper evidence score (0–∞) to a 0–5 confidence value. */
+export function mapScoreToWrapperConfidence(score) {
+    if (score <= 0)
+        return 0;
+    if (score <= 2)
+        return 2;
+    if (score <= 4)
+        return 3;
+    if (score <= 6)
+        return 4;
+    return 5;
+}
+export function dedupeStrings(values) {
+    return [...new Set(values)];
+}

package/dist/src/extract/{source-inspection.d.ts → services/quality/helpers/inspection/inspect-component-source.d.ts}

@@ -1,12 +1,9 @@
-import type { RawComponentDefinition } from '../types.js';
+import type { RawComponentDefinition } from '../../../../types/component.js';
+import type { ComponentSourceInspection } from '../../../../types/source-inspection.js';
+export type { ComponentSourceInspection } from '../../../../types/source-inspection.js';
 export declare const HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON = "data-fetch-wrapper";
 export declare const POSSIBLE_DATA_FETCH_WRAPPER_REASON = "possible-data-fetch-wrapper";
 export declare const ZERO_SURFACE_RENDERED_UI_REASON = "zero-surface:rendered-ui";
-export interface ComponentSourceInspection {
-    wrapperConfidence: 0 | 1 | 2 | 3 | 4 | 5;
-    reviewReasons: string[];
-    keepDespiteZeroSurface: boolean;
-}
 export declare function inspectComponentSource(component: RawComponentDefinition): Promise<ComponentSourceInspection>;
 export declare function isDataWrapperReviewReason(reason: string): boolean;
 export declare function describeReviewReason(reason: string): string;

package/dist/src/extract/{source-inspection.js → services/quality/helpers/inspection/inspect-component-source.js}

@@ -1,68 +1,8 @@
 import { readFile } from 'node:fs/promises';
-import { parseImportedNames } from './parse-imported-names.js';
+import { DATA_WRAPPER_REASON_PREFIX, GENERATED_IMPORT_PATTERN, GENERATED_QUERY_HOOK_PATTERN, GQL_FILENAME_PATTERN, LOADING_NULL_GUARD_PATTERN, collectSiblingRendererImports, hasSiblingForwardRender, hasVisibleUiRender, collectInfraPropNames, mapScoreToWrapperConfidence, dedupeStrings, } from './detect-data-wrapper-patterns.js';
 export const HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON = 'data-fetch-wrapper';
 export const POSSIBLE_DATA_FETCH_WRAPPER_REASON = 'possible-data-fetch-wrapper';
 export const ZERO_SURFACE_RENDERED_UI_REASON = 'zero-surface:rendered-ui';
-const DATA_WRAPPER_REASON_PREFIX = 'data-wrapper:';
-const INFRA_PROP_NAMES = new Set(['id', 'locale', 'preview', 'slug', 'topic', 'previousComponent', '__typename']);
-const VISIBLE_UI_TAG_PATTERN = /<(?:[A-Z][A-Za-z0-9_.]*|div|span|section|main|article|header|footer|nav|aside|img|video|p|h[1-6]|ul|ol|li|button|input|textarea|select|form|label|table|tbody|thead|tr|td|th)\b/;
-const GENERATED_IMPORT_PATTERN = /from\s+['"][^'"]*__generated[^'"]*['"]/;
-const GENERATED_QUERY_HOOK_PATTERN = /\buse[A-Z][A-Za-z0-9]*(?:Lazy|Suspense)?Query\s*\(/;
-const GQL_FILENAME_PATTERN = /(?:-gql|-ggl)\.[cm]?[jt]sx?$/i;
-const LOADING_NULL_GUARD_PATTERN = /if\s*\([^)]*(?:isLoading|loading|!data|!\w+Collection|!\w+Item|!\w+)\s*[^)]*\)\s*return\s+null\b/;
-const IMPORT_PATTERN = /import\s+(?:type\s+)?(.+?)\s+from\s+['"]([^'"]+)['"]/g;
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function collectSiblingRendererImports(sourceText) {
-    const names = new Set();
-    for (const match of sourceText.matchAll(IMPORT_PATTERN)) {
-        const importClause = match[1]?.trim() ?? '';
-        const importPath = match[2]?.trim() ?? '';
-        if (!importPath.startsWith('./'))
-            continue;
-        if (importPath.includes('__generated'))
-            continue;
-        if (/-g(?:ql|gl)(?:$|\.)/i.test(importPath))
-            continue;
-        for (const name of parseImportedNames(importClause)) {
-            if (name)
-                names.add(name);
-        }
-    }
-    return [...names];
-}
-function hasSiblingForwardRender(sourceText, siblingImports) {
-    return siblingImports.some((name) => {
-        const renderPattern = new RegExp(`<${escapeRegExp(name)}\\b[\\s\\S]*?(?:/>|</${escapeRegExp(name)}>)`);
-        if (!renderPattern.test(sourceText))
-            return false;
-        const siblingSpreadPattern = new RegExp(`<${escapeRegExp(name)}\\b[^>]*\\{\\.\\.\\.(?!props\\b)[^}]+\\}`);
-        const propsPlusSiblingSpreadPattern = new RegExp(`<${escapeRegExp(name)}\\b[^>]*\\{\\.\\.\\.props\\}[^>]*\\{\\.\\.\\.(?!props\\b)[^}]+\\}`);
-        return siblingSpreadPattern.test(sourceText) || propsPlusSiblingSpreadPattern.test(sourceText);
-    });
-}
-function hasVisibleUiRender(sourceText) {
-    return /return\s*(?:\(|<)/.test(sourceText) && VISIBLE_UI_TAG_PATTERN.test(sourceText);
-}
-function infraPropNames(component) {
-    const props = component.props.map((prop) => prop.name);
-    return props.length > 0 && props.every((prop) => INFRA_PROP_NAMES.has(prop)) ? props : [];
-}
-function scoreToConfidence(score) {
-    if (score <= 0)
-        return 0;
-    if (score <= 2)
-        return 2;
-    if (score <= 4)
-        return 3;
-    if (score <= 6)
-        return 4;
-    return 5;
-}
-function dedupeReasons(reasons) {
-    return [...new Set(reasons)];
-}
 export async function inspectComponentSource(component) {
     let sourceText = '';
     try {
@@ -78,7 +18,7 @@ export async function inspectComponentSource(component) {
     const reviewReasons = [];
     let wrapperScore = 0;
     const hasGeneratedQueryHook = GENERATED_IMPORT_PATTERN.test(sourceText) && GENERATED_QUERY_HOOK_PATTERN.test(sourceText);
-    const infraProps = infraPropNames(component);
+    const infraProps = collectInfraPropNames(component);
     const siblingImports = collectSiblingRendererImports(sourceText);
     if (GQL_FILENAME_PATTERN.test(component.source)) {
         reviewReasons.push('data-wrapper:gql-filename');
@@ -110,7 +50,7 @@ export async function inspectComponentSource(component) {
         reviewReasons.push('data-wrapper:loading-null-guard');
         wrapperScore += 1;
     }
-    const wrapperConfidence = scoreToConfidence(wrapperScore);
+    const wrapperConfidence = mapScoreToWrapperConfidence(wrapperScore);
     if (wrapperConfidence >= 4) {
         reviewReasons.unshift(HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON);
     }
@@ -123,7 +63,7 @@ export async function inspectComponentSource(component) {
     }
     return {
         wrapperConfidence,
-        reviewReasons: dedupeReasons(reviewReasons),
+        reviewReasons: dedupeStrings(reviewReasons),
         keepDespiteZeroSurface,
     };
 }
@@ -159,5 +99,5 @@ export function describeReviewReason(reason) {
     }
 }
 export function describeReviewReasons(reasons) {
-    return dedupeReasons(reasons.map(describeReviewReason));
+    return dedupeStrings(reasons.map(describeReviewReason));
 }

package/dist/src/extract/{validate.d.ts → services/quality/helpers/inspection/validate-extracted-components.d.ts}

@@ -1,4 +1,4 @@
-import type { RawComponentDefinition, ExtractionValidationIssue } from '../types.js';
+import type { RawComponentDefinition, ExtractionValidationIssue } from '../../../../types/component.js';
 export declare function validateExtractedComponents(components: RawComponentDefinition[]): RawComponentDefinition[];
 export declare function shouldExcludeDueToValidation(component: RawComponentDefinition): boolean;
 /**