@contentful/experience-design-system-cli 2.12.4-dev-build-ff57340.0 → 2.13.1-dev-build-fa478b3.0

package/dist/src/analyze/extract/svelte.js

@@ -1,1626 +0,0 @@
-import { basename, dirname, resolve, join } from 'node:path';
-import { readFile } from 'node:fs/promises';
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import os from 'node:os';
-import { parse as parseSvelte } from 'svelte/compiler';
-import { Project, Node, ScriptTarget, ModuleKind, ts } from 'ts-morph';
-import { computeExtractionScore, deriveNeedsReview } from './scoring.js';
-import { extractAllowedComponentsFromTypeText } from './slot-allowed-components.js';
-const SVELTE_EXTRACT_CONCURRENCY = Number(process.env['EDS_EXTRACT_CONCURRENCY'] ?? 0) || os.cpus().length;
-export async function extractSvelteComponents(filePaths, onProgress, opts) {
-    const svelteFiles = filePaths.filter((f) => f.endsWith('.svelte'));
-    if (svelteFiles.length === 0)
-        return { components: [], warnings: [] };
-    const warnings = [];
-    const components = [];
-    const retryContexts = new Map();
-    let filesProcessed = 0;
-    let componentsFound = 0;
-    const queue = [...svelteFiles];
-    async function worker() {
-        while (queue.length > 0) {
-            const filePath = queue.shift();
-            if (!filePath)
-                break;
-            try {
-                const source = await readFile(filePath, 'utf-8');
-                const { component, warnings: fileWarnings, retryContext } = await extractFromSvelteFile(filePath, source);
-                warnings.push(...fileWarnings);
-                if (component) {
-                    components.push(component);
-                    componentsFound++;
-                }
-                if (retryContext)
-                    retryContexts.set(filePath, retryContext);
-            }
-            catch (e) {
-                warnings.push(`${getSvelteComponentName(filePath)}: failed to extract from ${filePath} — ${e instanceof Error ? e.message : String(e)}`);
-            }
-            filesProcessed++;
-            onProgress?.({ filesProcessed, componentsFound });
-        }
-    }
-    await Promise.all(Array.from({ length: Math.min(SVELTE_EXTRACT_CONCURRENCY, svelteFiles.length) }, worker));
-    const finalWarnings = await maybeRunResolveUnreachableRetry(components, warnings, retryContexts, opts);
-    // Post-pass: resolve $allowedComponents for snippet slots whose type text
-    // referenced Snippet<[XProps]>. Build a props-type-name → component-name map
-    // from the full run first so cross-file references resolve.
-    resolveAllowedComponents(components);
-    return {
-        components: components.sort((a, b) => a.name.localeCompare(b.name)),
-        warnings: collapseUnresolvedTypeWarnings(finalWarnings),
-    };
-}
-function resolveAllowedComponents(components) {
-    const propsToComponent = new Map();
-    const componentNames = new Set();
-    for (const c of components) {
-        componentNames.add(c.name);
-        if (c._propsTypeName)
-            propsToComponent.set(c._propsTypeName, c.name);
-    }
-    for (const c of components) {
-        for (const slot of c.slots) {
-            const raw = slot._rawTypeText;
-            if (raw) {
-                const found = extractAllowedComponentsFromTypeText(raw, { propsToComponent, componentNames });
-                if (found.length > 0)
-                    slot.allowedComponents = found;
-            }
-            delete slot._rawTypeText;
-        }
-        delete c._propsTypeName;
-    }
-}
-// ---------------------------------------------------------------------------
-// Resolve-unreachable retry pass (Approach B)
-//
-// After the normal pass, components flagged `props-type-unresolved` get a
-// second look:
-//
-//   Step 1 — tsconfig pass: walk up from projectRoot to the nearest
-//   tsconfig.json and build ONE shared ts-morph Project loaded with that
-//   tsconfig. Re-run resolution per-component. Recovers cases where the type
-//   resolver needed path aliases / baseUrl / a real TS program.
-//
-//   Step 2 — node_modules pass: for components that still won't resolve,
-//   locate the imported package via Node's resolver, find its .d.ts entry,
-//   add it to the shared Project, and retry. Recovers cross-package extends
-//   like skeleton-svelte's `extends Omit<ZagProps, 'id'>` from @zag-js/*.
-//
-// Auto mode triggers only when ≥20% of svelte components in the run share
-// the unresolved-type pattern, so the cost of loading a full TS program is
-// paid only when it's likely to help.
-// ---------------------------------------------------------------------------
-async function maybeRunResolveUnreachableRetry(components, warnings, retryContexts, opts) {
-    const mode = opts?.resolveUnreachable ?? 'auto';
-    if (mode === 'never')
-        return warnings;
-    const isUnresolved = (c) => (c.reviewReasons ?? []).includes('props-type-unresolved') && !!retryContexts.get(c.source);
-    const unresolvedCount = components.filter(isUnresolved).length;
-    if (unresolvedCount === 0)
-        return warnings;
-    if (mode === 'auto') {
-        // Threshold: ≥20% of svelte components in the run.
-        const ratio = unresolvedCount / components.length;
-        if (ratio < 0.2)
-            return warnings;
-    }
-    // Step 1 — tsconfig pass.
-    const projectRoot = opts?.projectRoot;
-    let project = null;
-    let tsconfigPath = null;
-    if (projectRoot) {
-        tsconfigPath = findNearestTsconfig(projectRoot);
-    }
-    if (tsconfigPath) {
-        try {
-            project = new Project({
-                tsConfigFilePath: tsconfigPath,
-                skipAddingFilesFromTsConfig: false,
-                compilerOptions: {
-                    // Allow declaration-only resolution and JS sources.
-                    allowJs: true,
-                    jsx: ts.JsxEmit.Preserve,
-                },
-            });
-        }
-        catch {
-            project = null;
-        }
-    }
-    let recoveredViaTsconfig = 0;
-    if (project) {
-        for (const component of components) {
-            if (!isUnresolved(component))
-                continue;
-            const ctx = retryContexts.get(component.source);
-            if (!ctx)
-                continue;
-            const recovered = await retryComponentWithProject(component, ctx, project, warnings);
-            if (recovered)
-                recoveredViaTsconfig++;
-        }
-    }
-    // Step 2 — node_modules pass for whatever's still unresolved.
-    let recoveredViaNodeModules = 0;
-    const stillUnresolved = components.filter(isUnresolved);
-    if (stillUnresolved.length > 0) {
-        if (!project) {
-            // No tsconfig available — fall back to a lightweight project so we still
-            // get the node_modules pass. Force Node module resolution so that
-            // bare-specifier imports (e.g. `fake-svelte-pkg`) inside the synthetic
-            // file find their .d.ts entry on disk.
-            project = new Project({
-                compilerOptions: {
-                    strict: false,
-                    target: ScriptTarget.ESNext,
-                    module: ModuleKind.ESNext,
-                    moduleResolution: ts.ModuleResolutionKind.NodeJs,
-                    allowJs: true,
-                    jsx: ts.JsxEmit.Preserve,
-                },
-                useInMemoryFileSystem: false,
-                skipAddingFilesFromTsConfig: true,
-            });
-        }
-        for (const component of stillUnresolved) {
-            const ctx = retryContexts.get(component.source);
-            if (!ctx)
-                continue;
-            // Locate the imported types referenced by the user's Props annotation
-            // and add their .d.ts files to the shared project.
-            const added = addImportedDeclarationsToProject(project, ctx);
-            if (added === 0)
-                continue;
-            const recovered = await retryComponentWithProject(component, ctx, project, warnings);
-            if (recovered)
-                recoveredViaNodeModules++;
-        }
-    }
-    // Only surface the informational summary when the retry actually had
-    // something to work with — i.e. a tsconfig was loaded OR we managed to
-    // recover at least one component via node_modules. Otherwise we'd be
-    // adding a top-level warning that says "we did nothing", which clutters
-    // the output (and breaks the per-component-prefix convention the TUI
-    // relies on for grouping).
-    const didMeaningfulWork = !!tsconfigPath || recoveredViaNodeModules > 0;
-    if (didMeaningfulWork) {
-        const remaining = components.filter(isUnresolved).length;
-        const parts = [];
-        if (tsconfigPath) {
-            parts.push(`tsconfig at ${tsconfigPath} recovered ${recoveredViaTsconfig} component(s)`);
-        }
-        parts.push(`node_modules pass recovered ${recoveredViaNodeModules} more`);
-        parts.push(`${remaining} component(s) remain unresolved`);
-        warnings.push(`Unresolved-type retry pass (mode=${mode}): ${parts.join('; ')}.`);
-    }
-    return warnings;
-}
-function findNearestTsconfig(startDir) {
-    let dir = startDir;
-    // Cap at a reasonable depth to avoid scanning into / on weird inputs.
-    for (let i = 0; i < 16; i++) {
-        const candidate = join(dir, 'tsconfig.json');
-        if (existsSync(candidate))
-            return candidate;
-        const parent = dirname(dir);
-        if (!parent || parent === dir)
-            return null;
-        dir = parent;
-    }
-    return null;
-}
-/**
- * Re-run resolution for a single component against a shared Project.
- * On success, mutate the component to replace props/slots/reviewReasons and
- * remove the per-component "declared Props type ... resolved to ..." warning.
- */
-async function retryComponentWithProject(component, ctx, project, warnings) {
-    const snippetLocals = mergeSets(collectSnippetImportLocals(ctx.instance), ctx.moduleScript ? collectSnippetImportLocals(ctx.moduleScript) : new Set());
-    let members = null;
-    try {
-        members = await resolveViaTypeChecker(ctx.annotation, ctx.instance, ctx.moduleScript, ctx.filePath, ctx.source, snippetLocals, project);
-    }
-    catch {
-        members = null;
-    }
-    if (!members || members.length === 0)
-        return false;
-    // If the resolver returned a complete member list — even when it's
-    // Snippet-only — that's a real answer, not a partial one. Apply it and
-    // drop `props-type-unresolved`. Whether the resulting component still
-    // needs review will be decided by the standard heuristics
-    // (no-props-or-slots, infra-fetch, etc.) downstream.
-    const { props, snippetSlots } = extractFromTypeMembersOnly(members);
-    // Merge any template <slot> entries that survived the original pass — we
-    // can't easily re-derive those without re-parsing the fragment, but the
-    // existing component already has them.
-    const templateSlots = component.slots.filter((s) => !snippetSlots.some((ss) => ss.name === s.name));
-    const finalSlots = mergeSlots(snippetSlots, templateSlots).slots;
-    // Defensive dedupe: if a name somehow ended up in both buckets (e.g. when ts-morph
-    // returned `any` for a Snippet member and the Snippet detector failed downstream),
-    // the slot wins — slot semantics aren't recoverable from a duplicated prop.
-    const slotNames = new Set(finalSlots.map((s) => s.name));
-    component.props = props.filter((p) => !slotNames.has(p.name));
-    component.slots = finalSlots;
-    // Drop `props-type-unresolved` from reasons: the type DID resolve. Other
-    // heuristics (no-props-or-slots, infra-fetch, etc.) decide whether the
-    // recovered component still needs review.
-    const remainingReasons = (component.reviewReasons ?? []).filter((r) => r !== 'props-type-unresolved');
-    const score = computeExtractionScore(component, {
-        additionalIssueCount: remainingReasons.length,
-        additionalReasons: remainingReasons,
-    });
-    component.extractionConfidence = score.confidence;
-    component.reviewReasons = score.reasons;
-    component.needsReview = deriveNeedsReview(score.confidence);
-    // Remove the per-component unresolved-type warning — recovery is complete.
-    const componentName = component.name;
-    const idx = warnings.findIndex((w) => w.startsWith(`${componentName}: declared Props type `) && /resolved to /.test(w));
-    if (idx >= 0)
-        warnings.splice(idx, 1);
-    return true;
-}
-/**
- * Walk every type reference inside the user's Props annotation, find the
- * matching ImportDeclaration in instance/module scripts, resolve the
- * specifier via Node's resolver, locate sibling .d.ts files, and add them to
- * the shared Project. Returns the number of newly-added files.
- */
-function addImportedDeclarationsToProject(project, ctx) {
-    // Start with names referenced directly in the annotation (e.g. `Props`).
-    const importedNames = collectReferencedTypeNames(ctx.annotation);
-    // Also pull in names referenced from any LOCAL type/interface declaration the
-    // annotation points at — that's where heritage clauses (`extends FakeProps`)
-    // and intersections live, and they're the ones that name the imported type
-    // we actually need to add to the project.
-    for (const name of [...importedNames]) {
-        const localDecl = findLocalTypeDeclaration(ctx.instance, name, ctx.moduleScript) ??
-            (ctx.moduleScript ? findLocalTypeDeclaration(ctx.moduleScript, name, ctx.instance) : null);
-        if (localDecl) {
-            for (const referenced of collectReferencedTypeNames(localDecl))
-                importedNames.add(referenced);
-        }
-    }
-    if (importedNames.size === 0)
-        return 0;
-    const imports = collectImportSpecifiersForNames(ctx.instance, importedNames);
-    if (ctx.moduleScript) {
-        for (const [k, v] of collectImportSpecifiersForNames(ctx.moduleScript, importedNames))
-            imports.set(k, v);
-    }
-    if (imports.size === 0)
-        return 0;
-    const req = createRequire(ctx.filePath);
-    let added = 0;
-    for (const specifier of imports.values()) {
-        if (specifier.startsWith('.'))
-            continue; // already attempted by relative resolver path
-        const dtsPath = locateDtsForSpecifier(req, specifier, ctx.filePath);
-        if (!dtsPath)
-            continue;
-        try {
-            const sf = project.addSourceFileAtPathIfExists(dtsPath);
-            if (sf)
-                added++;
-        }
-        catch {
-            // Ignore — best-effort.
-        }
-    }
-    return added;
-}
-/**
- * Walk a TS type-annotation AST (or interface declaration) and gather every
- * referenced type name. Handles:
- *   - TSTypeReference (`Foo`, `Foo<Bar>`)
- *   - TSExpressionWithTypeArguments (the `extends Foo` form on interfaces)
- * That second case is critical: it's how `interface Props extends FakeProps {}`
- * surfaces the imported `FakeProps` name we need to add to the project.
- */
-function collectReferencedTypeNames(node) {
-    const names = new Set();
-    walk(node);
-    return names;
-    function walk(n) {
-        if (!n || typeof n !== 'object')
-            return;
-        if (n.type === 'TSTypeReference') {
-            const tn = n['typeName']?.['name'];
-            if (tn)
-                names.add(tn);
-        }
-        if (n.type === 'TSExpressionWithTypeArguments') {
-            const exprName = n['expression']?.['name'];
-            if (exprName)
-                names.add(exprName);
-        }
-        for (const value of Object.values(n)) {
-            if (Array.isArray(value)) {
-                for (const v of value) {
-                    if (v && typeof v === 'object')
-                        walk(v);
-                }
-            }
-            else if (value && typeof value === 'object' && value.type) {
-                walk(value);
-            }
-        }
-    }
-}
-/**
- * For each named identifier in `names`, find the import declaration that
- * brought it into scope and return a map of `localName -> moduleSpecifier`.
- */
-function collectImportSpecifiersForNames(script, names) {
-    const out = new Map();
-    const body = script['content']?.['body'];
-    if (!body)
-        return out;
-    for (const stmt of body) {
-        if (stmt.type !== 'ImportDeclaration')
-            continue;
-        const specifierValue = stmt['source']?.['value'];
-        if (!specifierValue)
-            continue;
-        const specifiers = stmt['specifiers'] ?? [];
-        for (const spec of specifiers) {
-            if (spec.type !== 'ImportSpecifier' && spec.type !== 'ImportDefaultSpecifier')
-                continue;
-            const localName = spec['local']?.['name'];
-            if (localName && names.has(localName))
-                out.set(localName, specifierValue);
-        }
-    }
-    return out;
-}
-/**
- * Locate a `.d.ts` file for `specifier` resolved relative to `parentFile`.
- * Tries a few strategies in priority order:
- *   1. `package.json#types` / `package.json#exports.types`
- *   2. sibling `.d.ts` / `.d.mts` next to the resolved JS entry
- *   3. `index.d.ts` / `index.d.mts` in the package root
- * Returns null if nothing resolves (no node_modules, dynamic import, etc.).
- */
-function locateDtsForSpecifier(req, specifier, parentFile) {
-    let resolvedJs = null;
-    try {
-        resolvedJs = req.resolve(specifier);
-    }
-    catch {
-        resolvedJs = null;
-    }
-    // Find the package root (nearest package.json above the resolved file or above the parentFile).
-    const seedDir = resolvedJs ? dirname(resolvedJs) : dirname(parentFile);
-    const pkgRoot = findPackageRootForSpecifier(seedDir, specifier);
-    if (pkgRoot) {
-        const pkgJsonPath = join(pkgRoot, 'package.json');
-        if (existsSync(pkgJsonPath)) {
-            try {
-                const pkgRaw = readFileSync(pkgJsonPath, 'utf-8');
-                const pkg = JSON.parse(pkgRaw);
-                const typesField = pkg.types ?? pkg.typings;
-                if (typeof typesField === 'string') {
-                    const candidate = resolve(pkgRoot, typesField);
-                    if (existsSync(candidate))
-                        return candidate;
-                }
-                const exportsTypes = extractTypesFromExports(pkg.exports);
-                if (exportsTypes) {
-                    const candidate = resolve(pkgRoot, exportsTypes);
-                    if (existsSync(candidate))
-                        return candidate;
-                }
-            }
-            catch {
-                // Fall through to sibling probing.
-            }
-        }
-        // index.d.ts at the package root.
-        for (const entry of ['index.d.ts', 'index.d.mts']) {
-            const candidate = join(pkgRoot, entry);
-            if (existsSync(candidate))
-                return candidate;
-        }
-    }
-    // Sibling probing next to the resolved JS file.
-    if (resolvedJs) {
-        const noExt = resolvedJs.replace(/\.(m?js|cjs)$/, '');
-        for (const ext of ['.d.ts', '.d.mts']) {
-            const candidate = `${noExt}${ext}`;
-            if (existsSync(candidate))
-                return candidate;
-        }
-    }
-    return null;
-}
-function findPackageRootForSpecifier(seedDir, specifier) {
-    // For scoped (@x/y) and bare specifiers, the package root is the directory
-    // whose path ends with the specifier under a node_modules tree. Walk up.
-    let dir = seedDir;
-    for (let i = 0; i < 32; i++) {
-        if (existsSync(join(dir, 'package.json'))) {
-            // Check this is the package matching the specifier (best-effort: name field).
-            try {
-                const pkgRaw = readFileSync(join(dir, 'package.json'), 'utf-8');
-                const pkg = JSON.parse(pkgRaw);
-                // Either exact match or a sub-path import (foo/sub) where pkg.name === 'foo'.
-                if (pkg.name === specifier)
-                    return dir;
-                if (pkg.name && specifier.startsWith(`${pkg.name}/`))
-                    return dir;
-            }
-            catch {
-                // Ignore and continue walking.
-            }
-        }
-        const parent = dirname(dir);
-        if (!parent || parent === dir)
-            return null;
-        dir = parent;
-    }
-    return null;
-}
-function extractTypesFromExports(exportsField) {
-    if (!exportsField || typeof exportsField !== 'object')
-        return null;
-    const exp = exportsField;
-    // Look for the "." entry first; fall back to top-level types if shape is conditional.
-    const root = (exp['.'] ?? exp);
-    if (!root || typeof root !== 'object')
-        return null;
-    const r = root;
-    if (typeof r['types'] === 'string')
-        return r['types'];
-    // Conditional exports: try import → types, default → types.
-    for (const key of ['import', 'default', 'node']) {
-        const sub = r[key];
-        if (sub && typeof sub === 'object') {
-            const t = sub['types'];
-            if (typeof t === 'string')
-                return t;
-        }
-    }
-    return null;
-}
-/**
- * When a large fraction of components emit the same `declared Props type ...
- * resolved to ... properties` warning (typical of headless libraries like
- * skeleton-svelte that extend types from external packages we can't reach),
- * replace ALL of them with a single summary line. Per-component
- * reviewReasons + needsReview flags stay intact, so the user can still
- * drill into any individual component to see the issue — we just don't
- * flood the top-level warnings panel with N near-identical lines.
- *
- * Threshold: 3 or more identical-shape warnings. Below that, the literal
- * per-component lines are short enough to keep as-is.
- */
-function collapseUnresolvedTypeWarnings(warnings) {
-    const isUnresolvedWarning = (w) => /declared Props type .* resolved to/.test(w);
-    const unresolvedCount = warnings.filter(isUnresolvedWarning).length;
-    if (unresolvedCount < 3)
-        return warnings;
-    const others = warnings.filter((w) => !isUnresolvedWarning(w));
-    const summary = `Unresolved component types: ${unresolvedCount} components have a declared Props type the parser couldn't fully resolve — ` +
-        `most often a cross-package extends pattern (e.g. an interface that extends a type from a node_modules package). ` +
-        `Each affected component is flagged with reviewReasons: ['props-type-unresolved'] and needsReview = true; ` +
-        `select one in the TUI to drill in. ` +
-        `See https://github.com/contentful/experience-design-system-sdk-public/pull/44 for context and partner workarounds.`;
-    return [summary, ...others];
-}
-async function extractFromSvelteFile(filePath, source) {
-    const warnings = [];
-    // Derive the component name up front so warning messages can prefix it for
-    // TUI grouping, even when parsing fails.
-    const name = getSvelteComponentName(filePath);
-    let ast;
-    try {
-        ast = parseSvelte(source, { modern: true });
-    }
-    catch (e) {
-        return {
-            component: null,
-            warnings: [`${name}: parse error in ${filePath}: ${e instanceof Error ? e.message : String(e)}`],
-        };
-    }
-    const instance = ast['instance'];
-    const moduleScript = ast['module'];
-    const fragment = ast['fragment'];
-    // Detect Svelte 4 export-let syntax — currently unsupported.
-    if (instance && hasV4ExportLetProps(instance)) {
-        warnings.push(`${name}: Svelte 4 export let syntax not yet supported (${filePath}); see INTEG-4267 for v5-only scope and follow-up`);
-        return { component: null, warnings };
-    }
-    // Find the $props() call (Svelte 5 runes).
-    const propsCall = instance ? findPropsCall(instance) : null;
-    // Snippet import map: localName -> true if it refers to `Snippet` from 'svelte'.
-    const snippetLocals = instance ? collectSnippetImportLocals(instance) : new Set();
-    // --- Props extraction ---
-    let props = [];
-    let propNamesTreatedAsSnippet = new Set();
-    let snippetSlotsFromProps = [];
-    const extractionReasons = [];
-    if (propsCall) {
-        const result = await extractPropsFromCall({
-            propsCall,
-            instance: instance,
-            moduleScript,
-            filePath,
-            componentName: name,
-            source,
-            snippetLocals,
-        });
-        props = result.props;
-        propNamesTreatedAsSnippet = result.snippetNames;
-        snippetSlotsFromProps = result.snippetSlots;
-        warnings.push(...result.warnings);
-        if (result.additionalReasons)
-            extractionReasons.push(...result.additionalReasons);
-    }
-    else if (instance) {
-        // No $props() call. We've already ruled out v4 above; this means $props was used
-        // but couldn't be located, or the script has no rune-style props at all.
-        // Component still extracted (slots from template may exist).
-    }
-    else {
-        // No script block at all — nothing to extract on the props side.
-        warnings.push(`${name}: no instance script block (${filePath}); no props extracted`);
-    }
-    // --- Slot extraction ---
-    const templateSlots = fragment ? extractTemplateSlots(fragment) : [];
-    const { slots, mixedWarning } = mergeSlots(snippetSlotsFromProps, templateSlots);
-    if (mixedWarning) {
-        warnings.push(`${name}: mixed Snippet and <slot> usage detected (${filePath}); preferring Snippet entries`);
-    }
-    // Capture the props-type-name (if any) so the run-level post-pass can build
-    // a props-type → component-name map for $allowedComponents resolution
-    // (mirrors the React extractor's `_propsTypeName` mechanism).
-    let propsTypeNameCapture;
-    if (propsCall) {
-        const id = propsCall['id'];
-        const annotation = id?.['typeAnnotation']?.['typeAnnotation'];
-        if (annotation?.type === 'TSTypeReference') {
-            const tn = annotation['typeName']?.['name'];
-            if (tn && /^[A-Za-z_$][\w$]*$/.test(tn))
-                propsTypeNameCapture = tn;
-        }
-    }
-    const component = {
-        name,
-        source: filePath,
-        framework: 'svelte',
-        props,
-        slots,
-        ...(propsTypeNameCapture ? { _propsTypeName: propsTypeNameCapture } : {}),
-    };
-    // Score & flag review. Forward extraction-time reasons (e.g. props-type-unresolved)
-    // so they count toward the confidence score AND surface in reviewReasons.
-    const score = computeExtractionScore(component, {
-        additionalIssueCount: extractionReasons.length,
-        additionalReasons: extractionReasons,
-    });
-    component.extractionConfidence = score.confidence;
-    component.reviewReasons = score.reasons;
-    // A type-resolution failure is a strong signal something is wrong; force
-    // human review even when other heuristics keep confidence above the threshold.
-    component.needsReview = deriveNeedsReview(score.confidence) || extractionReasons.includes('props-type-unresolved');
-    // Validation issues (EMPTY_COMPONENT_NAME / EMPTY_PROP_NAME / PROP_SLOT_NAME_COLLISION /
-    // DUPLICATE_COMPONENT_NAME / EMPTY_COMPONENT / EMPTY_SLOT_NAME) are populated
-    // centrally by validateExtractedComponents() in analyze/command.ts after all
-    // extractors return — same convention as React, Vue, Astro, Stencil, and
-    // web-components. No per-extractor work needed here.
-    void propNamesTreatedAsSnippet; // currently informational; reserved for future validation
-    // Capture context for the resolve-unreachable retry pass. Only meaningful
-    // when extraction actually got back the props-type-unresolved signal AND
-    // we have the annotation node needed to re-run resolution.
-    let retryContext;
-    if (extractionReasons.includes('props-type-unresolved') && propsCall && instance) {
-        const id = propsCall['id'];
-        const annotation = id?.['typeAnnotation']?.['typeAnnotation'];
-        if (annotation) {
-            retryContext = {
-                filePath,
-                source,
-                instance,
-                moduleScript,
-                annotation,
-                componentName: name,
-            };
-        }
-    }
-    return { component, warnings, ...(retryContext ? { retryContext } : {}) };
-}
-// ---------------------------------------------------------------------------
-// Component name
-// ---------------------------------------------------------------------------
-// Folder names that are pure scaffolding (anatomy / parts conventions popularized
-// by Ark UI, Zag, Skeleton). When a component file sits directly inside one of
-// these, the meaningful namespace is the grandparent directory.
-const ANATOMY_FOLDERS = new Set(['anatomy', 'parts']);
-function getSvelteComponentName(filePath) {
-    const file = basename(filePath, '.svelte');
-    const parentDir = basename(dirname(filePath));
-    // index.svelte → use parent directory name (mirrors index.vue behavior).
-    if (file === 'index')
-        return toPascalCase(parentDir);
-    // accordion/anatomy/root.svelte → AccordionRoot (avoids massive collisions
-    // when a single library has dozens of components named Root/Item/Trigger).
-    if (ANATOMY_FOLDERS.has(parentDir)) {
-        const grandparent = basename(dirname(dirname(filePath)));
-        if (grandparent && grandparent !== '.' && grandparent !== '/') {
-            return `${toPascalCase(grandparent)}${toPascalCase(file)}`;
-        }
-    }
-    return toPascalCase(file);
-}
-function toPascalCase(s) {
-    if (!s)
-        return s;
-    // Already PascalCase? leave it.
-    if (/^[A-Z]/.test(s) && !s.includes('-') && !s.includes('_'))
-        return s;
-    return s
-        .split(/[-_]+/)
-        .filter(Boolean)
-        .map((part) => part[0].toUpperCase() + part.slice(1))
-        .join('');
-}
-// ---------------------------------------------------------------------------
-// Detection helpers
-// ---------------------------------------------------------------------------
-function hasV4ExportLetProps(instance) {
-    const body = instance['content']?.['body'];
-    if (!body)
-        return false;
-    return body.some((stmt) => {
-        if (stmt.type !== 'ExportNamedDeclaration')
-            return false;
-        const decl = stmt['declaration'];
-        return decl?.type === 'VariableDeclaration' && decl['kind'] === 'let';
-    });
-}
-function findPropsCall(instance) {
-    const body = instance['content']?.['body'];
-    if (!body)
-        return null;
-    let found = null;
-    for (const stmt of body) {
-        if (stmt.type !== 'VariableDeclaration')
-            continue;
-        const decls = stmt['declarations'];
-        if (!decls)
-            continue;
-        for (const d of decls) {
-            const init = d['init'];
-            if (!init || init.type !== 'CallExpression')
-                continue;
-            const callee = init['callee'];
-            if (callee?.type === 'Identifier' && callee['name'] === '$props') {
-                if (found === null)
-                    found = d;
-                // Multiple $props() calls — first wins; we'll warn from the caller.
-            }
-        }
-    }
-    return found;
-}
-function collectSnippetImportLocals(instance) {
-    const locals = new Set();
-    const body = instance['content']?.['body'];
-    if (!body)
-        return locals;
-    for (const stmt of body) {
-        if (stmt.type !== 'ImportDeclaration')
-            continue;
-        const sourceNode = stmt['source'];
-        if (sourceNode?.['value'] !== 'svelte')
-            continue;
-        const specs = stmt['specifiers'];
-        if (!specs)
-            continue;
-        for (const spec of specs) {
-            if (spec.type !== 'ImportSpecifier')
-                continue;
-            const imported = spec['imported'];
-            const local = spec['local'];
-            if (imported?.['name'] === 'Snippet' && typeof local?.['name'] === 'string') {
-                locals.add(local['name']);
-            }
-        }
-    }
-    return locals;
-}
-async function extractPropsFromCall(ctx) {
-    const warnings = [];
-    const propsCall = ctx.propsCall;
-    const id = propsCall['id'];
-    const idType = id?.type;
-    // Decode the type annotation (the right side of `: Props` / `: { ... }`).
-    const annotation = id?.['typeAnnotation']?.['typeAnnotation'];
-    // Resolve the type members once (works for both ObjectPattern and Identifier id forms).
-    const typeMembers = annotation
-        ? await resolveTypeMembers(annotation, ctx.instance, ctx.moduleScript, ctx.filePath, ctx.source)
-        : null;
-    // Detect "we tried to resolve a real type and got nothing back" — distinct from
-    // the user genuinely typing an empty literal. Surface as both a warning (CLI
-    // stderr / analyze report) and a review reason (TUI / downstream gating).
-    const unresolved = classifyUnresolved(annotation, typeMembers, ctx.instance, ctx.moduleScript);
-    const additionalReasons = [];
-    if (unresolved) {
-        const refLabel = describeAnnotationForUser(annotation);
-        const heritageNote = unresolved === 'partial-heritage' ? ' (heritage clauses extending unreachable types)' : '';
-        warnings.push(`${ctx.componentName}: declared Props type ${refLabel} resolved to ${unresolved === 'empty' ? '0' : 'only Snippet-typed'} properties${heritageNote} (${ctx.filePath}) — possible cross-package extends or unreachable type. ` +
-            `See https://github.com/contentful/experience-design-system-sdk-public/pull/44 for context and partner workarounds.`);
-        additionalReasons.push('props-type-unresolved');
-    }
-    if (idType === 'ObjectPattern') {
-        return extractFromDestructure(ctx.propsCall, ctx, typeMembers, warnings, additionalReasons);
-    }
-    if (idType === 'Identifier') {
-        // const props: Props = $props(); — no destructure, no defaults, no per-name binding.
-        if (typeMembers && typeMembers.length > 0) {
-            return { ...extractFromTypeMembersOnly(typeMembers), warnings, additionalReasons };
-        }
-        if (!unresolved) {
-            warnings.push(`${ctx.componentName}: $props() called without destructuring (${ctx.filePath}); cannot extract individual props`);
-        }
-        return { props: [], snippetNames: new Set(), snippetSlots: [], warnings, additionalReasons };
-    }
-    warnings.push(`${ctx.componentName}: unrecognized $props() binding pattern '${idType}' (${ctx.filePath})`);
-    return { props: [], snippetNames: new Set(), snippetSlots: [], warnings, additionalReasons };
-}
-/**
- * Classify whether the user's declared Props type failed to resolve usefully.
- *
- * - `'empty'`: the resolver returned no members for a non-trivial annotation.
- * - `'partial-heritage'`: the source declaration has heritage clauses (extends /
- *   intersection in module-script) but the resolver only surfaced Snippet-typed
- *   members — strong signal that one or more parents pointed at unreachable
- *   types (e.g. cross-package node_modules) and were silently dropped.
- * - `null`: nothing to surface — either the user genuinely typed an empty
- *   literal, omitted the annotation, or the resolver returned regular props.
- */
-function classifyUnresolved(annotation, members, instance, moduleScript) {
-    if (!annotation)
-        return null;
-    if (annotation.type === 'TSTypeLiteral') {
-        const litMembers = annotation['members'] ?? [];
-        if (litMembers.length === 0)
-            return null; // user genuinely typed `{}`
-    }
-    if (members === null || members.length === 0)
-        return 'empty';
-    // Partial-heritage signal: declaration has extends and every surviving member
-    // is Snippet-typed. Real prop interfaces almost never declare every prop as a
-    // Snippet, so this is a strong "something fell off the resolution edge" hint.
-    if (annotation.type === 'TSTypeReference') {
-        const refName = annotation['typeName']?.['name'] ?? null;
-        if (refName) {
-            const decl = findLocalTypeDeclaration(instance, refName, moduleScript);
-            if (decl && declarationHasHeritage(decl) && members.every((m) => m.isSnippet)) {
-                return 'partial-heritage';
-            }
-        }
-    }
-    return null;
-}
-function describeAnnotationForUser(annotation) {
-    if (!annotation)
-        return '<unknown>';
-    if (annotation.type === 'TSTypeReference') {
-        const name = annotation['typeName']?.['name'] ?? null;
-        return name ? `'${name}'` : '<unnamed reference>';
-    }
-    if (annotation.type === 'TSIntersectionType')
-        return '<intersection>';
-    if (annotation.type === 'TSUnionType')
-        return '<union>';
-    if (annotation.type === 'TSTypeLiteral')
-        return '<inline literal>';
-    return `<${annotation.type}>`;
-}
-async function resolveTypeMembers(annotation, instance, moduleScript, filePath, source) {
-    // Snippet imports may live in either script block; collect from both.
-    const snippetLocals = mergeSets(collectSnippetImportLocals(instance), moduleScript ? collectSnippetImportLocals(moduleScript) : new Set());
-    // Fast path 1: inline type literal with no extends/intersection. The AST already
-    // gives us member-level optional/type/JSDoc; no ts-morph needed.
-    if (annotation.type === 'TSTypeLiteral') {
-        return readMembersFromTypeLiteral(annotation, snippetLocals);
-    }
-    // For named refs: try the AST fast path first (inline interface or type literal alias
-    // with no heritage clauses). If that returns >0 members AND the source declaration has
-    // no extends, we trust it. Otherwise fall back to ts-morph type-checker resolution to
-    // pick up extends / Omit / intersection / Partial / generics.
-    if (annotation.type === 'TSTypeReference') {
-        const refName = annotation['typeName']?.['name'] ?? null;
-        if (refName) {
-            const local = findLocalTypeDeclaration(instance, refName, moduleScript);
-            if (local) {
-                const fastPathMembers = readMembersFromInterfaceOrAlias(local, snippetLocals);
-                if (fastPathMembers.length > 0 && !declarationHasHeritage(local)) {
-                    return fastPathMembers;
-                }
-                // Heritage or empty body — fall through to ts-morph resolution.
-            }
-            else {
-                // No local declaration — try import resolution via ts-morph.
-                const imported = (await resolveImportedTypeMembers(refName, instance, filePath)) ??
-                    (moduleScript ? await resolveImportedTypeMembers(refName, moduleScript, filePath) : null);
-                if (imported)
-                    return imported;
-            }
-        }
-    }
-    // Slow path: ts-morph type-checker resolution. Materializes the annotation text as
-    // `type __SveltePropsT__ = <annotation>;` inside an in-memory file containing the
-    // combined script bodies, then reads .getType().getProperties(). The TS checker
-    // resolves extends, &, Omit, Pick, Partial, generics — anything TS itself resolves.
-    return resolveViaTypeChecker(annotation, instance, moduleScript, filePath, source, snippetLocals);
-}
-function declarationHasHeritage(decl) {
-    if (decl.type === 'TSInterfaceDeclaration') {
-        const ext = decl['extends'];
-        return Array.isArray(ext) && ext.length > 0;
-    }
-    return false;
-}
-async function resolveViaTypeChecker(annotation, instance, moduleScript, filePath, source, snippetLocals, externalProject) {
-    const annotationText = sliceSource(source, annotation);
-    if (!annotationText)
-        return null;
-    // Reconstruct the combined script content: module-script first, then instance.
-    // Both bodies share scope in the synthetic file, which is enough for TS to resolve
-    // local interfaces, type aliases, imports, and heritage clauses across them.
-    const moduleText = sliceScriptContent(source, moduleScript);
-    const instanceText = sliceScriptContent(source, instance);
-    const synthetic = [moduleText, instanceText, `type __SveltePropsT__ = ${annotationText};`].filter(Boolean).join('\n');
-    // Reuse the caller-supplied Project if provided (the resolve-unreachable
-    // retry pass shares one Project across all components in the run); otherwise
-    // build a one-off project for this single call.
-    const project = externalProject ??
-        new Project({
-            compilerOptions: {
-                strict: false,
-                target: ScriptTarget.ESNext,
-                module: ModuleKind.ESNext,
-                allowJs: true,
-                jsx: ts.JsxEmit.Preserve,
-            },
-            useInMemoryFileSystem: false,
-            skipAddingFilesFromTsConfig: true,
-        });
-    // Place the synthetic file alongside the .svelte so relative imports resolve.
-    const syntheticPath = `${filePath}.__svelte-props__.ts`;
-    let sf;
-    try {
-        sf = project.createSourceFile(syntheticPath, synthetic, { overwrite: true });
-    }
-    catch {
-        return null;
-    }
-    const alias = sf.getTypeAlias('__SveltePropsT__');
-    if (!alias)
-        return null;
-    const type = alias.getType();
-    const apparent = type.getApparentType();
-    const properties = apparent.getProperties();
-    if (properties.length === 0)
-        return null;
-    const members = [];
-    for (const symbol of properties) {
-        const name = symbol.getName();
-        const declaration = symbol.getValueDeclaration() ?? symbol.getDeclarations()[0];
-        if (!declaration)
-            continue;
-        const propType = symbol.getTypeAtLocation(declaration);
-        let typeText = propType.getText(declaration);
-        // Strip ` | undefined` for clean output on optional props.
-        const optional = symbol.isOptional();
-        if (optional) {
-            typeText = typeText.replace(/\s*\|\s*undefined$/, '').replace(/^undefined\s*\|\s*/, '');
-        }
-        const allowed = extractAllowedValuesFromType(propType);
-        const description = readJsDocFromDeclaration(declaration);
-        // Snippet detection — try three signals in order of reliability:
-        //   1. The author's declared type-node text on the property's source declaration.
-        //      This survives even when ts-morph fails to fully resolve a generic
-        //      instantiation and falls back to `any`/`unknown` (intermittent under
-        //      partial type-checker state).
-        //   2. The resolved type's alias-symbol chain — works when ts-morph DID fully
-        //      resolve the type (`Snippet<[T]>` expanded to its call signature).
-        //   3. Text-match on the rendered type. Last-resort fallback.
-        const declaredTypeText = readDeclaredTypeNodeText(declaration);
-        const isSnippet = (declaredTypeText !== null && isSnippetTypeText(declaredTypeText, snippetLocals)) ||
-            typeRefersToSnippet(propType) ||
-            isSnippetTypeText(typeText, snippetLocals);
-        members.push({
-            name,
-            optional,
-            typeText,
-            ...(declaredTypeText ? { declaredTypeText } : {}),
-            isSnippet,
-            ...(allowed ? { allowedValues: allowed } : {}),
-            ...(description ? { description } : {}),
-            // line/endLine: prefer AST-derived location when the source declaration is in our
-            // svelte file. ts-morph's synthetic location refers to the synthetic file and
-            // isn't useful for the user.
-        });
-    }
-    return members;
-}
-function sliceSource(source, node) {
-    const start = node['start'] ?? null;
-    const end = node['end'] ?? null;
-    if (start == null || end == null)
-        return null;
-    return source.slice(start, end);
-}
-function sliceScriptContent(source, script) {
-    if (!script)
-        return null;
-    const content = script['content'];
-    if (!content)
-        return null;
-    return sliceSource(source, content);
-}
-function extractAllowedValuesFromType(type) {
-    if (!type.isUnion())
-        return undefined;
-    const out = [];
-    for (const t of type.getUnionTypes()) {
-        if (!t.isStringLiteral())
-            return undefined;
-        out.push(t.getLiteralValueOrThrow());
-    }
-    return out.length > 0 ? out : undefined;
-}
-function readJsDocFromDeclaration(decl) {
-    if (Node.isPropertySignature(decl) || Node.isInterfaceDeclaration(decl) || Node.isTypeAliasDeclaration(decl)) {
-        const jsdocs = decl.getJsDocs();
-        if (jsdocs.length > 0)
-            return jsdocs[0].getDescription().trim() || undefined;
-    }
-    return undefined;
-}
-/**
- * Read the literal text of the property's declared type annotation as the
- * AUTHOR wrote it (e.g. `Snippet<[Attrs]>`), independent of what the TS
- * checker resolved it to. This is critical because ts-morph's checker can
- * intermittently fall back to `any`/`unknown` for cross-package generic
- * instantiations, in which case the symbol-/alias-based detector has nothing
- * to follow. The author's syntactic annotation is stable in either case.
- */
-function readDeclaredTypeNodeText(decl) {
-    if (Node.isPropertySignature(decl)) {
-        return decl.getTypeNode()?.getText() ?? null;
-    }
-    return null;
-}
-function isSnippetTypeText(typeText, snippetLocals) {
-    // Direct match against the local Snippet name (handles aliasing).
-    for (const local of snippetLocals) {
-        if (typeText === local || typeText.startsWith(`${local}<`))
-            return true;
-    }
-    // Defensive fallback: TS may surface the canonical `Snippet` from the import.
-    return typeText === 'Snippet' || typeText.startsWith('Snippet<');
-}
-function typeRefersToSnippet(propType) {
-    const seen = new Set();
-    let cursor = propType;
-    while (cursor && !seen.has(cursor)) {
-        seen.add(cursor);
-        const aliasName = cursor.getAliasSymbol()?.getName();
-        const symName = cursor.getSymbol()?.getName();
-        if (aliasName === 'Snippet' || symName === 'Snippet') {
-            const decl = cursor.getAliasSymbol()?.getDeclarations()[0] ?? cursor.getSymbol()?.getDeclarations()[0];
-            const file = decl?.getSourceFile().getFilePath() ?? '';
-            // Accept Snippet from anywhere named "svelte" in the path; users almost
-            // never name an unrelated type "Snippet" in their own code, but the
-            // path check guards against the rare false positive.
-            if (file.includes('/svelte/') || file.includes('\\svelte\\') || file === '')
-                return true;
-        }
-        // Strip optional `| undefined` and recurse into single-element unions
-        // (covers `Snippet | undefined` etc.).
-        if (cursor.isUnion()) {
-            const nonUndef = cursor.getUnionTypes().filter((t) => !t.isUndefined() && !t.isNull());
-            if (nonUndef.length === 1) {
-                cursor = nonUndef[0];
-                continue;
-            }
-        }
-        break;
-    }
-    return false;
-}
-function mergeSets(a, b) {
-    const out = new Set(a);
-    for (const v of b)
-        out.add(v);
-    return out;
-}
-function findLocalTypeDeclaration(instance, name, module) {
-    // Skeleton-svelte and similar libraries declare the Props interface in
-    // <script lang="ts" module> and consume it in the regular <script>. Look
-    // in both bodies. Type declarations may also be wrapped in
-    // `export { ... }` statements (ExportNamedDeclaration with .declaration).
-    for (const script of [instance, module]) {
-        const body = script?.['content']?.['body'];
-        if (!body)
-            continue;
-        for (const stmt of body) {
-            const decl = stmt.type === 'ExportNamedDeclaration' ? (stmt['declaration'] ?? stmt) : stmt;
-            if (decl.type === 'TSInterfaceDeclaration' || decl.type === 'TSTypeAliasDeclaration') {
-                const id = decl['id'];
-                if (id?.['name'] === name)
-                    return decl;
-            }
-        }
-    }
-    return null;
-}
-function readMembersFromInterfaceOrAlias(decl, snippetLocals) {
-    if (decl.type === 'TSInterfaceDeclaration') {
-        const body = decl['body']?.['body'];
-        if (!body)
-            return [];
-        return body.map((m) => readPropertySignature(m, snippetLocals)).filter((m) => !!m);
-    }
-    if (decl.type === 'TSTypeAliasDeclaration') {
-        const ann = decl['typeAnnotation'];
-        if (ann?.type === 'TSTypeLiteral')
-            return readMembersFromTypeLiteral(ann, snippetLocals);
-    }
-    return [];
-}
-function readMembersFromTypeLiteral(literal, snippetLocals) {
-    const members = literal['members'];
-    if (!members)
-        return [];
-    return members.map((m) => readPropertySignature(m, snippetLocals)).filter((m) => !!m);
-}
-function readPropertySignature(member, snippetLocals) {
-    if (member.type !== 'TSPropertySignature')
-        return null;
-    const key = member['key'];
-    const name = key?.['name'] ?? null;
-    if (!name)
-        return null;
-    const optional = !!member['optional'];
-    const typeNode = member['typeAnnotation']?.['typeAnnotation'];
-    const typeText = renderType(typeNode);
-    const isSnippet = isSnippetType(typeNode, snippetLocals);
-    const allowedValues = collectStringLiteralUnion(typeNode);
-    // JSDoc / comments — `leadingComments` may be on the member or on the parent.
-    const leading = member['leadingComments'] ?? [];
-    const description = extractJsdocText(leading);
-    return {
-        name,
-        optional,
-        typeText,
-        isSnippet,
-        allowedValues,
-        description,
-        line: member.loc?.start?.line,
-        endLine: member.loc?.end?.line,
-    };
-}
-function isSnippetType(typeNode, snippetLocals) {
-    if (!typeNode)
-        return false;
-    if (typeNode.type !== 'TSTypeReference')
-        return false;
-    const tn = typeNode['typeName']?.['name'];
-    if (!tn)
-        return false;
-    return snippetLocals.has(tn);
-}
-function collectStringLiteralUnion(typeNode) {
-    if (!typeNode)
-        return undefined;
-    if (typeNode.type !== 'TSUnionType')
-        return undefined;
-    const members = typeNode['types'];
-    if (!members)
-        return undefined;
-    const out = [];
-    for (const m of members) {
-        if (m.type !== 'TSLiteralType')
-            return undefined; // not a pure literal union
-        const lit = m['literal'];
-        const v = lit?.['value'];
-        if (typeof v !== 'string')
-            return undefined;
-        out.push(v);
-    }
-    return out.length > 0 ? out : undefined;
-}
-function renderType(typeNode) {
-    if (!typeNode)
-        return 'unknown';
-    switch (typeNode.type) {
-        case 'TSStringKeyword':
-            return 'string';
-        case 'TSNumberKeyword':
-            return 'number';
-        case 'TSBooleanKeyword':
-            return 'boolean';
-        case 'TSAnyKeyword':
-            return 'any';
-        case 'TSUnknownKeyword':
-            return 'unknown';
-        case 'TSNullKeyword':
-            return 'null';
-        case 'TSUndefinedKeyword':
-            return 'undefined';
-        case 'TSVoidKeyword':
-            return 'void';
-        case 'TSArrayType': {
-            return `${renderType(typeNode['elementType'])}[]`;
-        }
-        case 'TSTupleType': {
-            // Tuple element types can be plain (`T`) or labeled (`name: T` →
-            // TSNamedTupleMember). Render each element by drilling to the type.
-            const elements = typeNode['elementTypes'] ?? [];
-            const rendered = elements.map((el) => {
-                if (el.type === 'TSNamedTupleMember') {
-                    const inner = el['elementType'];
-                    return renderType(inner);
-                }
-                return renderType(el);
-            });
-            return `[${rendered.join(', ')}]`;
-        }
-        case 'TSUnionType': {
-            const members = typeNode['types'] ?? [];
-            return members.map(renderType).join(' | ');
-        }
-        case 'TSLiteralType': {
-            const lit = typeNode['literal'];
-            const v = lit?.['value'];
-            if (typeof v === 'string')
-                return `'${v}'`;
-            if (typeof v === 'number' || typeof v === 'boolean')
-                return String(v);
-            return 'unknown';
-        }
-        case 'TSTypeReference': {
-            const tn = typeNode['typeName']?.['name'];
-            const args = typeNode['typeArguments'];
-            const base = tn ?? 'unknown';
-            const params = args?.['params'] ?? null;
-            if (params && params.length > 0) {
-                return `${base}<${params.map(renderType).join(', ')}>`;
-            }
-            return base;
-        }
-        case 'TSFunctionType': {
-            const params = (typeNode['params'] ?? []).map((p) => {
-                const ann = p['typeAnnotation']?.['typeAnnotation'];
-                const pname = p['name'] ?? 'arg';
-                return `${pname}: ${renderType(ann)}`;
-            });
-            const ret = typeNode['returnType']?.['typeAnnotation'];
-            return `(${params.join(', ')}) => ${renderType(ret)}`;
-        }
-        default:
-            return 'unknown';
-    }
-}
-function extractJsdocText(comments) {
-    if (!comments.length)
-        return undefined;
-    const last = comments[comments.length - 1];
-    if (last.type !== 'Block')
-        return undefined;
-    // Strip leading * on each line, trim, join.
-    const text = last.value
-        .split('\n')
-        .map((l) => l.replace(/^\s*\*\s?/, '').trim())
-        .filter(Boolean)
-        .join(' ')
-        .trim();
-    return text || undefined;
-}
-// ---------------------------------------------------------------------------
-// Extraction: ObjectPattern destructure + type-members
-// ---------------------------------------------------------------------------
-function extractFromDestructure(propsCall, _ctx, typeMembers, warnings, additionalReasons) {
-    const id = propsCall['id'];
-    const properties = id['properties'] ?? [];
-    const typeByName = new Map();
-    if (typeMembers)
-        for (const m of typeMembers)
-            typeByName.set(m.name, m);
-    const props = [];
-    const snippetNames = new Set();
-    const snippetSlots = [];
-    const seenInDestructure = new Set();
-    let dropsRest = false;
-    for (const p of properties) {
-        if (p.type === 'RestElement') {
-            dropsRest = true;
-            continue;
-        }
-        if (p.type !== 'Property')
-            continue;
-        const key = p['key'];
-        const name = key?.['name'] ?? null;
-        if (!name)
-            continue;
-        seenInDestructure.add(name);
-        const value = p['value'];
-        const hasDefault = value?.type === 'AssignmentPattern';
-        const defaultValueRaw = hasDefault ? renderLiteral(value['right']) : undefined;
-        const typeMember = typeByName.get(name);
-        if (typeMember?.isSnippet) {
-            snippetNames.add(name);
-            const slot = {
-                name,
-                isDefault: name === 'children',
-                ...(typeMember.description ? { description: typeMember.description } : {}),
-            };
-            // Stash the author-facing type text so the run-level post-pass can
-            // resolve $allowedComponents from `Snippet<[XProps]>`.
-            // Prefer the author-facing `Snippet<[XProps]>` shape; the resolved
-            // typeText may be an expanded call signature that loses the tuple form.
-            const authorText = typeMember.declaredTypeText ?? typeMember.typeText;
-            if (authorText)
-                slot._rawTypeText = authorText;
-            snippetSlots.push(slot);
-            continue;
-        }
-        const required = typeMember ? !typeMember.optional && !hasDefault : !hasDefault;
-        const propDef = {
-            name,
-            type: typeMember?.typeText ?? 'unknown',
-            required,
-        };
-        if (defaultValueRaw !== undefined)
-            propDef.defaultValue = defaultValueRaw;
-        if (typeMember?.allowedValues)
-            propDef.allowedValues = typeMember.allowedValues;
-        if (typeMember?.description)
-            propDef.description = typeMember.description;
-        props.push(propDef);
-    }
-    // Note: members declared in the type but not destructured are intentionally NOT surfaced
-    // here. With `let { foo, ...rest } = $props()`, only `foo` is bound by name; the rest
-    // are collected into the rest binding and are not individually addressable. Authoring
-    // contract = the destructure list. (Type-members-only path runs separately for the
-    // `const props: Props = $props()` no-destructure case.)
-    // Note: a `...rest` element in the destructure is intentionally NOT warned on.
-    // Nearly every Svelte 5 component in real libraries uses rest-spread to pass
-    // arbitrary HTML attributes through to the underlying element, so this would
-    // fire on most components. The downstream pipeline already strips DOM/a11y
-    // pass-through attributes globally (see `project_dsi-dom-prop-exclusion-decision`),
-    // and the named props we DID extract from the destructure are the meaningful
-    // authoring API. Tracking the rest spread isn't useful signal.
-    void dropsRest;
-    return {
-        props: props.sort((a, b) => sortStable(a.name, b.name, propertyOrder(properties))),
-        snippetNames,
-        snippetSlots,
-        warnings,
-        ...(additionalReasons && additionalReasons.length > 0 ? { additionalReasons } : {}),
-    };
-}
-function extractFromTypeMembersOnly(typeMembers) {
-    const props = [];
-    const snippetNames = new Set();
-    const snippetSlots = [];
-    for (const m of typeMembers) {
-        if (m.isSnippet) {
-            snippetNames.add(m.name);
-            const slot = {
-                name: m.name,
-                isDefault: m.name === 'children',
-                ...(m.description ? { description: m.description } : {}),
-            };
-            const authorText = m.declaredTypeText ?? m.typeText;
-            if (authorText)
-                slot._rawTypeText = authorText;
-            snippetSlots.push(slot);
-            continue;
-        }
-        const propDef = {
-            name: m.name,
-            type: m.typeText,
-            required: !m.optional,
-        };
-        if (m.allowedValues)
-            propDef.allowedValues = m.allowedValues;
-        if (m.description)
-            propDef.description = m.description;
-        props.push(propDef);
-    }
-    return { props, snippetNames, snippetSlots, warnings: [] };
-}
-function propertyOrder(properties) {
-    const m = new Map();
-    let i = 0;
-    for (const p of properties) {
-        if (p.type !== 'Property')
-            continue;
-        const name = p['key']?.['name'] ?? null;
-        if (name)
-            m.set(name, i++);
-    }
-    return m;
-}
-function sortStable(a, b, order) {
-    const ai = order.get(a) ?? Infinity;
-    const bi = order.get(b) ?? Infinity;
-    if (ai !== bi)
-        return ai - bi;
-    return a.localeCompare(b);
-}
-function renderLiteral(node) {
-    if (!node)
-        return undefined;
-    if (node.type === 'Literal') {
-        const v = node['value'];
-        const raw = node['raw'];
-        if (typeof v === 'string')
-            return `'${v}'`;
-        if (typeof raw === 'string')
-            return raw;
-        if (v === null)
-            return 'null';
-        return String(v);
-    }
-    if (node.type === 'Identifier')
-        return node['name'] ?? undefined;
-    if (node.type === 'ArrayExpression') {
-        const els = node['elements'] ?? [];
-        return `[${els.map((e) => renderLiteral(e) ?? '').join(', ')}]`;
-    }
-    if (node.type === 'ObjectExpression')
-        return '{}';
-    return undefined;
-}
-// ---------------------------------------------------------------------------
-// Imported Props resolution via ts-morph (cross-file)
-// ---------------------------------------------------------------------------
-async function resolveImportedTypeMembers(typeName, instance, filePath) {
-    const body = instance['content']?.['body'];
-    if (!body)
-        return null;
-    for (const stmt of body) {
-        if (stmt.type !== 'ImportDeclaration')
-            continue;
-        const specifierValue = stmt['source']?.['value'];
-        if (!specifierValue || !specifierValue.startsWith('.'))
-            continue;
-        const specifiers = stmt['specifiers'] ?? [];
-        let importedExport = null;
-        for (const spec of specifiers) {
-            if (spec.type !== 'ImportSpecifier')
-                continue;
-            const localName = spec['local']?.['name'];
-            if (localName === typeName) {
-                importedExport = spec['imported']?.['name'] ?? null;
-                break;
-            }
-        }
-        if (!importedExport)
-            continue;
-        const resolvedFile = resolveLocalScriptModule(filePath, specifierValue);
-        if (!resolvedFile)
-            continue;
-        return readMembersFromExternalFile(resolvedFile, importedExport);
-    }
-    return null;
-}
-function resolveLocalScriptModule(importingFilePath, specifier) {
-    const basePath = resolve(dirname(importingFilePath), specifier);
-    const candidates = [
-        basePath,
-        `${basePath}.js`,
-        `${basePath}.ts`,
-        `${basePath}.mjs`,
-        `${basePath}.cjs`,
-        join(basePath, 'index.js'),
-        join(basePath, 'index.ts'),
-        join(basePath, 'index.mjs'),
-        join(basePath, 'index.cjs'),
-    ];
-    for (const c of candidates) {
-        if (existsSync(c) && statSync(c).isFile())
-            return c;
-    }
-    // Fallback: handle `.js` import that maps to a `.ts` source on disk (NodeNext convention)
-    if (basePath.endsWith('.js')) {
-        const tsPath = `${basePath.slice(0, -'.js'.length)}.ts`;
-        if (existsSync(tsPath) && statSync(tsPath).isFile())
-            return tsPath;
-    }
-    return null;
-}
-function readMembersFromExternalFile(filePath, exportName) {
-    const project = new Project({
-        compilerOptions: {
-            strict: false,
-            target: ScriptTarget.ESNext,
-            module: ModuleKind.ESNext,
-            allowJs: true,
-        },
-        useInMemoryFileSystem: false,
-        skipAddingFilesFromTsConfig: true,
-    });
-    const sf = project.addSourceFileAtPathIfExists(filePath);
-    if (!sf)
-        return null;
-    // Collect Snippet locals from the resolved file's own imports so that
-    // aliased imports (`import { Snippet as LocalSnippet } from 'svelte'`) are
-    // honored. Mirrors collectSnippetImportLocals() but adapted to ts-morph.
-    const snippetLocals = collectSnippetLocalsFromSourceFile(sf);
-    // Use getExportedDeclarations() so re-export chains (`export { ... } from './x'`,
-    // `export * from './x'`, named or namespace) resolve transparently. ts-morph
-    // follows them recursively and returns the underlying declaration.
-    const exportedDeclarations = sf.getExportedDeclarations();
-    const decls = exportedDeclarations.get(exportName);
-    if (!decls || decls.length === 0)
-        return null;
-    for (const decl of decls) {
-        if (Node.isInterfaceDeclaration(decl)) {
-            // The declaration may live in a different source file than `sf` if the
-            // export chain walked across files; pull snippet locals from that file
-            // so aliased imports are recognized.
-            const declSf = decl.getSourceFile();
-            const declLocals = declSf === sf ? snippetLocals : collectSnippetLocalsFromSourceFile(declSf);
-            return readInterfaceMembers(decl, declLocals);
-        }
-        if (Node.isTypeAliasDeclaration(decl)) {
-            const typeNode = decl.getTypeNode();
-            if (typeNode && Node.isTypeLiteral(typeNode)) {
-                const declSf = decl.getSourceFile();
-                const declLocals = declSf === sf ? snippetLocals : collectSnippetLocalsFromSourceFile(declSf);
-                return readTypeLiteralMembers(typeNode, declLocals);
-            }
-        }
-    }
-    return null;
-}
-function collectSnippetLocalsFromSourceFile(sf) {
-    const locals = new Set();
-    for (const importDecl of sf.getImportDeclarations()) {
-        if (importDecl.getModuleSpecifierValue() !== 'svelte')
-            continue;
-        for (const named of importDecl.getNamedImports()) {
-            if (named.getName() === 'Snippet') {
-                const aliasNode = named.getAliasNode();
-                locals.add(aliasNode ? aliasNode.getText() : named.getName());
-            }
-        }
-    }
-    return locals;
-}
-function readInterfaceMembers(iface, snippetLocals) {
-    return iface.getProperties().map((prop) => {
-        const typeNode = prop.getTypeNode();
-        const typeText = typeNode ? typeNode.getText() : prop.getType().getText(prop);
-        const allowed = extractAllowedValuesFromText(typeText);
-        const jsdocs = prop.getJsDocs();
-        const description = jsdocs.length > 0 ? jsdocs[0].getDescription().trim() : undefined;
-        return {
-            name: prop.getName(),
-            optional: prop.hasQuestionToken(),
-            typeText,
-            isSnippet: isSnippetTypeText(typeText, snippetLocals),
-            ...(allowed ? { allowedValues: allowed } : {}),
-            ...(description ? { description } : {}),
-            line: prop.getStartLineNumber(),
-            endLine: prop.getEndLineNumber(),
-        };
-    });
-}
-function readTypeLiteralMembers(typeNode, snippetLocals) {
-    return typeNode.getMembers().flatMap((m) => {
-        if (!Node.isPropertySignature(m))
-            return [];
-        const tn = m.getTypeNode();
-        const typeText = tn ? tn.getText() : 'unknown';
-        const allowed = extractAllowedValuesFromText(typeText);
-        const jsdocs = m.getJsDocs();
-        const description = jsdocs.length > 0 ? jsdocs[0].getDescription().trim() : undefined;
-        return [
-            {
-                name: m.getName(),
-                optional: m.hasQuestionToken(),
-                typeText,
-                isSnippet: isSnippetTypeText(typeText, snippetLocals),
-                ...(allowed ? { allowedValues: allowed } : {}),
-                ...(description ? { description } : {}),
-                line: m.getStartLineNumber(),
-                endLine: m.getEndLineNumber(),
-            },
-        ];
-    });
-}
-function extractAllowedValuesFromText(typeText) {
-    // Quick parse of `'a' | 'b' | 'c'`.
-    const parts = typeText
-        .split('|')
-        .map((p) => p.trim())
-        .filter(Boolean);
-    if (parts.length < 2)
-        return undefined;
-    const out = [];
-    for (const p of parts) {
-        const m = p.match(/^'([^']*)'$/) ?? p.match(/^"([^"]*)"$/);
-        if (!m)
-            return undefined;
-        out.push(m[1]);
-    }
-    return out.length > 0 ? out : undefined;
-}
-// ---------------------------------------------------------------------------
-// Slot extraction (template <slot> + Snippet props merge)
-// ---------------------------------------------------------------------------
-function extractTemplateSlots(fragment) {
-    const slots = [];
-    const seen = new Set();
-    walk(fragment);
-    return slots;
-    function walk(node) {
-        if (!node)
-            return;
-        if (node.type === 'SlotElement') {
-            const name = readSlotName(node);
-            if (!seen.has(name)) {
-                seen.add(name);
-                slots.push({ name, isDefault: name === 'default' });
-            }
-        }
-        const children = node['nodes'] ?? node['children'] ?? [];
-        for (const c of children)
-            walk(c);
-        const fragChild = node['fragment'];
-        if (fragChild)
-            walk(fragChild);
-    }
-}
-function readSlotName(slotEl) {
-    const attrs = slotEl['attributes'] ?? [];
-    for (const attr of attrs) {
-        if (attr['name'] !== 'name')
-            continue;
-        const value = attr['value'];
-        if (Array.isArray(value)) {
-            for (const v of value) {
-                if (v.type === 'Text' && typeof v['data'] === 'string')
-                    return v['data'];
-            }
-        }
-    }
-    return 'default';
-}
-function mergeSlots(fromSnippetProps, fromTemplate) {
-    if (fromSnippetProps.length === 0)
-        return { slots: fromTemplate, mixedWarning: false };
-    if (fromTemplate.length === 0)
-        return { slots: fromSnippetProps, mixedWarning: false };
-    const byName = new Map();
-    for (const s of fromSnippetProps)
-        byName.set(s.name, s);
-    const snippetHasDefault = fromSnippetProps.some((s) => s.isDefault);
-    let mixed = false;
-    for (const s of fromTemplate) {
-        // Default <slot/> in template is the same surface as a `children: Snippet` prop.
-        // Prefer the Snippet entry when both are present.
-        if (s.isDefault && snippetHasDefault) {
-            mixed = true;
-            continue;
-        }
-        if (byName.has(s.name)) {
-            mixed = true;
-            continue;
-        }
-        byName.set(s.name, s);
-    }
-    return { slots: [...byName.values()], mixedWarning: mixed };
-}