@contentful/experience-design-system-cli 2.11.4-dev-build-86a5f6e.0 → 2.11.4-dev-build-7abd382.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.11.4-dev-build-86a5f6e.0",
+  "version": "2.11.4-dev-build-7abd382.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/analyze/command.js

@@ -99,7 +99,16 @@ export function registerAnalyzeCommand(program) {
         .description('Extract component definitions from a project')
         .requiredOption('--project <path>', 'Path to the project root')
         .option('--dir <path>', 'Path to the component source directory relative to the project root')
+        .option('--resolve-unreachable <mode>', "Retry pass for unresolved Svelte Props types: 'auto' (default), 'always', or 'never'", 'auto')
         .action(async (opts) => {
+        const resolveUnreachable = (() => {
+            const v = opts.resolveUnreachable ?? 'auto';
+            if (v !== 'auto' && v !== 'always' && v !== 'never') {
+                process.stderr.write(`Error: --resolve-unreachable must be one of 'auto', 'always', 'never' (got '${v}')\n`);
+                process.exit(1);
+            }
+            return v;
+        })();
         const projectRoot = resolve(opts.project);
         const outDir = join(projectRoot, '.contentful');
         let sourceDirectory;
@@ -123,7 +132,7 @@ export function registerAnalyzeCommand(program) {
             if (!process.stdout.isTTY) {
                 process.stderr.write(`progress=extract:${filesProcessed}/${sourceFiles.length}:${componentsFound}\n`);
             }
-        });
+        }, { resolveUnreachable, projectRoot });
         await mkdir(outDir, { recursive: true });
         const db = openPipelineDb();
         const { sessionId } = getOrCreateSession(db, undefined, undefined, {

package/dist/src/analyze/extract/pipeline.d.ts

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

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

@@ -224,7 +224,7 @@ function choosePreferredComponent(existing, candidate) {
         reason: `kept ${existing.source} over ${candidate.source} by stable first-seen order`,
     };
 }
-export async function extractComponents(filePaths, onProgress) {
+export async function extractComponents(filePaths, onProgress, opts) {
     const filesByExtractor = new Map();
     for (const extractor of extractors) {
         filesByExtractor.set(extractor, []);
@@ -254,7 +254,7 @@ export async function extractComponents(filePaths, onProgress) {
             perExtractorFiles.set(extractor, p.filesProcessed);
             perExtractorComponents.set(extractor, p.componentsFound);
             onProgress?.({ filesProcessed: totalFilesProcessed, componentsFound: totalComponentsFound });
-        });
+        }, opts);
         return result;
     }));
     const allWarnings = [];

package/dist/src/analyze/extract/svelte.d.ts

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

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

@@ -1,17 +1,19 @@
 import { basename, dirname, resolve, join } from 'node:path';
 import { readFile } from 'node:fs/promises';
-import { existsSync, statSync } from 'node:fs';
+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';
 const SVELTE_EXTRACT_CONCURRENCY = Number(process.env['EDS_EXTRACT_CONCURRENCY'] ?? 0) || os.cpus().length;
-export async function extractSvelteComponents(filePaths, onProgress) {
+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];
@@ -22,12 +24,14 @@ export async function extractSvelteComponents(filePaths, onProgress) {
                 break;
             try {
                 const source = await readFile(filePath, 'utf-8');
-                const { component, warnings: fileWarnings } = await extractFromSvelteFile(filePath, source);
+                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)}`);
@@ -37,11 +41,443 @@ export async function extractSvelteComponents(filePaths, onProgress) {
         }
     }
     await Promise.all(Array.from({ length: Math.min(SVELTE_EXTRACT_CONCURRENCY, svelteFiles.length) }, worker));
+    const finalWarnings = await maybeRunResolveUnreachableRetry(components, warnings, retryContexts, opts);
     return {
         components: components.sort((a, b) => a.name.localeCompare(b.name)),
-        warnings,
+        warnings: collapseUnresolvedTypeWarnings(finalWarnings),
     };
 }
+// ---------------------------------------------------------------------------
+// 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 only members are Snippet-typed (the partial-heritage signal that
+    // tripped the original warning), we haven't actually recovered useful props.
+    if (members.every((m) => m.isSnippet))
+        return false;
+    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; recompute confidence.
+    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 so it doesn't muddy the
+    // summary line / TUI grouping after recovery.
+    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),
+ * collapse them into a single summary line at the top + the per-component
+ * details below. Per-component reviewReasons and needsReview stay intact;
+ * this only affects the warnings array's readability.
+ *
+ * Threshold: 3 or more identical-shape warnings. Below that, the literal
+ * per-component lines are clearer than a summary.
+ */
+function collapseUnresolvedTypeWarnings(warnings) {
+    const isUnresolvedWarning = (w) => /declared Props type .* resolved to/.test(w);
+    const unresolved = warnings.filter(isUnresolvedWarning);
+    if (unresolved.length < 3)
+        return warnings;
+    const summary = `Unresolved component types: ${unresolved.length} 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). ` +
+        `See https://github.com/contentful/experience-design-system-sdk-public/pull/44 for context and partner workarounds.`;
+    return [summary, ...warnings];
+}
 async function extractFromSvelteFile(filePath, source) {
     const warnings = [];
     // Derive the component name up front so warning messages can prefix it for
@@ -130,7 +566,25 @@ async function extractFromSvelteFile(filePath, source) {
     // 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
-    return { component, warnings };
+    // 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
@@ -366,7 +820,7 @@ function declarationHasHeritage(decl) {
     }
     return false;
 }
-async function resolveViaTypeChecker(annotation, instance, moduleScript, filePath, source, snippetLocals) {
+async function resolveViaTypeChecker(annotation, instance, moduleScript, filePath, source, snippetLocals, externalProject) {
     const annotationText = sliceSource(source, annotation);
     if (!annotationText)
         return null;
@@ -376,17 +830,21 @@ async function resolveViaTypeChecker(annotation, instance, moduleScript, filePat
     const moduleText = sliceScriptContent(source, moduleScript);
     const instanceText = sliceScriptContent(source, instance);
     const synthetic = [moduleText, instanceText, `type __SveltePropsT__ = ${annotationText};`].filter(Boolean).join('\n');
-    const project = new Project({
-        compilerOptions: {
-            strict: false,
-            target: ScriptTarget.ESNext,
-            module: ModuleKind.ESNext,
-            allowJs: true,
-            jsx: ts.JsxEmit.Preserve,
-        },
-        useInMemoryFileSystem: false,
-        skipAddingFilesFromTsConfig: true,
-    });
+    // 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;
@@ -419,7 +877,18 @@ async function resolveViaTypeChecker(annotation, instance, moduleScript, filePat
         }
         const allowed = extractAllowedValuesFromType(propType);
         const description = readJsDocFromDeclaration(declaration);
-        const isSnippet = isSnippetTypeText(typeText, snippetLocals);
+        // 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,
@@ -468,6 +937,20 @@ function readJsDocFromDeclaration(decl) {
     }
     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) {
@@ -477,6 +960,35 @@ function isSnippetTypeText(typeText, snippetLocals) {
     // 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)

package/dist/src/types.d.ts

@@ -54,10 +54,25 @@ export type ExtractorProgress = {
     filesProcessed: number;
     componentsFound: number;
 };
+/**
+ * Optional extraction-time settings forwarded from the CLI through the
+ * pipeline to each extractor. Only the Svelte extractor currently consumes
+ * any of these; other extractors ignore the value.
+ */
+export interface ExtractorOptions {
+    /**
+     * Whether the Svelte extractor should run a retry pass for components whose
+     * declared Props type couldn't be resolved on the first pass (cross-package
+     * extends, path-alias-only types, etc.). See svelte.ts for the policy.
+     */
+    resolveUnreachable?: 'auto' | 'always' | 'never';
+    /** Absolute project root — used by the retry pass to locate tsconfig.json and node_modules. */
+    projectRoot?: string;
+}
 export interface ComponentExtractor {
     name: string;
     fileFilter: (filePath: string) => boolean;
-    extract(filePaths: string[], onProgress?: (p: ExtractorProgress) => void): Promise<ComponentExtractionResult>;
+    extract(filePaths: string[], onProgress?: (p: ExtractorProgress) => void, opts?: ExtractorOptions): Promise<ComponentExtractionResult>;
 }
 export interface TokenExtractor {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.11.4-dev-build-86a5f6e.0",
+  "version": "2.11.4-dev-build-7abd382.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.11.4-dev-build-86a5f6e.0"
+    "@contentful/experience-design-system-types": "2.11.4-dev-build-7abd382.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",