svelte-docinfo 0.5.4 → 0.6.0

package/dist/analyze.d.ts

@@ -17,7 +17,7 @@
  * @module
  */
 import type { AnalysisLog } from './log.js';
-import { type ModuleSourceOptions, type SourceOptionsDefaults } from './source-config.js';
+import { type ExcludeOption, type ModuleSourceOptions, type SourceOptionsOverrides } from './source-config.js';
 import { type Discovery } from './discovery.js';
 import { type ResolveImport } from './dep-resolver.js';
 import { type AnalyzeResultJson, type OnDuplicates } from './analyze-core.js';
@@ -30,7 +30,13 @@ import type { SourceFileInfo } from './source.js';
  * for incremental use.
  */
 export interface AnalyzeOptions {
-    /** Source files to analyze (must have content loaded). */
+    /**
+     * Source files to analyze (must have content loaded). Files outside
+     * `sourceOptions.sourcePaths` or matching `exclude` emit no module — they
+     * still feed the checker as in-memory content, so passing extra files
+     * (unsaved buffers, virtual-only helpers) shapes type resolution without
+     * polluting the output.
+     */
     sourceFiles: ReadonlyArray<SourceFileInfo>;
     /** Module source options for path extraction and source filtering. */
     sourceOptions: ModuleSourceOptions;
@@ -70,26 +76,45 @@ export interface AnalyzeFromFilesOptions {
     /** Absolute path to project root directory. */
     projectRoot: string;
     /** Partial overrides for default source options (SvelteKit `src/lib` layout). */
-    sourceOptions?: Partial<SourceOptionsDefaults>;
+    sourceOptions?: SourceOptionsOverrides;
     /** Behavior when duplicate declaration names are found across modules. */
     onDuplicates?: OnDuplicates;
     /** Optional logger for status and diagnostic messages. */
     log?: AnalysisLog;
     /**
-     * Glob patterns to include (relative to `projectRoot`).
+     * Glob patterns to include (relative to `projectRoot`; an absolute pattern
+     * inside the root relativizes, an out-of-root one throws — see
+     * `normalizeIncludePatterns`).
      *
      * Filters glob-based discovery. Providing `include` under the default
      * `discovery: 'auto'` collapses the chain to glob immediately; combining
      * with `discovery: 'exports'` throws.
      *
+     * Explicit patterns also widen the source scope: their static bases join
+     * `sourceOptions.sourcePaths` (see `widenSourcePathsForInclude`), so
+     * include-discovered files outside the configured source paths still emit
+     * modules, with paths relative to the widened set's common root. A pattern
+     * with no static base (`'**\/*.ts'`, a literal root file) scopes the whole
+     * project root as source and logs an info line; an out-of-root base
+     * (`'../other/**'`) throws.
+     *
      * When omitted, the glob fallback derives an include from
      * `sourceOptions.sourcePaths` via `deriveIncludePatterns`, so custom
      * `sourcePaths` (e.g., `['packages/foo']`) survive the fallback instead of
      * silently defaulting to `src/lib`.
      */
     include?: Array<string>;
-    /** Glob patterns to exclude — fully replaces `sourceOptions.exclude` (no merge). */
-    exclude?: Array<string>;
+    /**
+     * Glob patterns to exclude — takes precedence over `sourceOptions.exclude`
+     * (no merge between the two). An array replaces the default patterns
+     * wholesale; the callback form extends them without restating them
+     * (`(defaults) => [...defaults, '**\/*.gen.ts']` — see `ExcludeOption`).
+     * The callback always receives the built-in defaults, even when
+     * `sourceOptions.exclude` is also set (that value is superseded whole).
+     * The always-on baseline (`node_modules` + dot-directories below a matched
+     * source path) applies beneath it and is unaffected by overrides.
+     */
+    exclude?: ExcludeOption;
     /**
      * Whether to resolve import dependencies (default `true`).
      *

package/dist/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,UAAU,CAAC;AAE1C,OAAO,EAEN,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAsB,KAAK,SAAS,EAAC,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAiB,KAAK,aAAa,EAAC,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAEN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,aAAa,CAAC;AAIhD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,0DAA0D;IAC1D,WAAW,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC3C,sEAAsE;IACtE,aAAa,EAAE,mBAAmB,CAAC;IACnC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAU,SAAS,cAAc,KAAG,OAAO,CAAC,iBAAiB,CAkBhF,CAAC;AAIF;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,aAAa,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,oFAAoF;IACpF,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,uBAAuB,KAC9B,OAAO,CAAC,iBAAiB,CAqG3B,CAAC"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAEN,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAEN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,WAAW,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC3C,sEAAsE;IACtE,aAAa,EAAE,mBAAmB,CAAC;IACnC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAU,SAAS,cAAc,KAAG,OAAO,CAAC,iBAAiB,CAwBhF,CAAC;AAIF;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,uBAAuB,KAC9B,OAAO,CAAC,iBAAiB,CAwH3B,CAAC"}

package/dist/analyze.js

@@ -18,10 +18,10 @@
  */
 import { errorsOf, formatDiagnostic, warningsOf } from './diagnostics.js';
 import { createAnalysisSession } from './session.js';
-import { createSourceOptions, } from './source-config.js';
+import { createSourceOptionsWithInclude } from './source-config.js';
 import { discoverSourceFiles } from './discovery.js';
 import { noDepsResolver } from './dep-resolver.js';
-import { normalizeDiagnosticPaths, } from './analyze-core.js';
+import { normalizeDiagnosticPaths } from './analyze-core.js';
 /**
  * Analyze library source files and extract metadata (one-shot).
  *
@@ -39,6 +39,12 @@ export const analyze = async (options) => {
         sourceOptions: options.sourceOptions,
         log: options.log,
         resolveImport: options.resolveImport,
+        // One-shot with caller-provided inputs: no watch loop, so TS/JS context
+        // is read exactly once via the LS disk fallback either way — closure
+        // ownership is pure overhead. Gated *Svelte* dependencies are the
+        // exception (the LS can't serve raw `.svelte` from disk); callers pass
+        // them in `sourceFiles` — the query gate keeps them out of output.
+        contextClosure: false
     });
     try {
         const ingest = await session.setFiles(options.sourceFiles);
@@ -47,7 +53,7 @@ export const analyze = async (options) => {
         // session.setFiles; query diagnostics are normalized in analyze-core.
         return {
             modules: query.modules,
-            diagnostics: [...ingest.diagnostics, ...query.diagnostics],
+            diagnostics: [...ingest.diagnostics, ...query.diagnostics]
         };
     }
     finally {
@@ -67,7 +73,7 @@ export const analyze = async (options) => {
  * @throws Error if `sourceOptions` validation fails or `tsconfig.json` is missing
  */
 export const analyzeFromFiles = async (options) => {
-    const { projectRoot, include, exclude, resolveDependencies: shouldResolveDependencies = true, resolveImport, sourceOptions, onDuplicates, log, discovery, distDir, } = options;
+    const { projectRoot, include, exclude, resolveDependencies: shouldResolveDependencies = true, resolveImport, sourceOptions, onDuplicates, log, discovery, distDir } = options;
     // A custom resolver with resolution turned off is a contradiction — the
     // resolver would never be consulted. Fail fast rather than silently dropping
     // it (mirrors the `discovery: 'exports'` + `include` config-error throw).
@@ -81,7 +87,11 @@ export const analyzeFromFiles = async (options) => {
     // `createSourceOptions` so the normalized options carry a single source
     // of truth.
     const mergedSourceOptions = exclude !== undefined ? { ...sourceOptions, exclude } : sourceOptions;
-    const resolvedSourceOptions = createSourceOptions(projectRoot, mergedSourceOptions);
+    // Explicit include patterns widen the source scope — their static bases
+    // join `sourcePaths` so include-discovered files pass the query-time source
+    // gate and get proper relative module paths; a pattern with no base scopes
+    // the whole project root and logs.
+    const resolvedSourceOptions = createSourceOptionsWithInclude(projectRoot, mergedSourceOptions, include, log);
     const normalizedProjectRoot = resolvedSourceOptions.projectRoot;
     // Step 1: discover files.
     const { files: discoveredFiles, diagnostics: discoveryDiagnostics } = await discoverSourceFiles({
@@ -89,7 +99,7 @@ export const analyzeFromFiles = async (options) => {
         include,
         discovery,
         distDir,
-        log,
+        log
     });
     // Step 2: build the session-default resolver. When dep-resolution is
     // disabled, install the shared no-deps resolver so the session's lex+resolve
@@ -104,15 +114,25 @@ export const analyzeFromFiles = async (options) => {
     const session = createAnalysisSession({
         sourceOptions: resolvedSourceOptions,
         log,
-        resolveImport: sessionResolver,
+        resolveImport: sessionResolver
+        // Closure stays on (the session default) despite being one-shot:
+        // discovery excludes gated files, so a gated `.svelte` dependency
+        // (`export {default as X} from './internal/X.svelte'`) exists nowhere
+        // else — the LS can't serve raw `.svelte` from disk, only the closure's
+        // ingest runs svelte2tsx. TS/JS context would be covered by the disk
+        // fallback either way; the closure's extra reads are the price of the
+        // Svelte case resolving.
     });
     let result;
     try {
-        const ingest = await session.setFiles(discoveredFiles);
+        await session.setFiles(discoveredFiles);
         const query = session.query({ onDuplicates, log });
         result = {
             modules: query.modules,
-            diagnostics: [...ingest.diagnostics, ...query.diagnostics],
+            // Cumulative rather than the batch return: context-closure ingest
+            // diagnostics (e.g. a gated Svelte file whose transform failed)
+            // live only on entries.
+            diagnostics: [...session.allIngestDiagnostics(), ...query.diagnostics]
         };
     }
     finally {

package/dist/cli.d.ts

@@ -25,14 +25,23 @@ type OnDuplicatesFlag = (typeof ON_DUPLICATES_VALUES)[number];
  * CLI options parsed from command line arguments.
  */
 export interface CliOptions {
-    /** File patterns to include (undefined = use exports discovery or defaults). */
+    /**
+     * File patterns to include (undefined = use exports discovery or defaults).
+     *
+     * Relative to the project root; an absolute pattern inside it relativizes,
+     * an out-of-root one throws.
+     */
     include?: Array<string>;
     /**
-     * File patterns to exclude (undefined = use defaults — test and spec files).
+     * File patterns to exclude (undefined = use defaults — test/spec files and
+     * `internal/` directories).
      *
      * When provided, **fully replaces** the defaults — no array merge. Passing
-     * a custom `--exclude` pattern drops the default test/spec filters unless
-     * the caller re-includes them explicitly.
+     * a custom `--exclude` pattern drops the default test/spec/`internal/`
+     * filters unless the caller re-includes them explicitly (the API's
+     * exclude-callback form has no CLI equivalent). The always-on baseline
+     * (`node_modules` + dot-directories below a source path) applies beneath
+     * it and is unaffected by overrides.
      */
     exclude?: Array<string>;
     /** Output file path (undefined = stdout). */
@@ -52,7 +61,8 @@ export interface CliOptions {
     /** Dist directory name for exports-based discovery (undefined = 'dist'). */
     distDir?: string;
     /**
-     * Source directories relative to project root (undefined = ['src/lib']).
+     * Source directories, relative to project root or absolute inside it
+     * (undefined = ['src/lib']); an out-of-root entry throws.
      *
      * Repeatable. Drives the implicit include glob in the glob-discovery
      * fallback (via `deriveIncludePatterns` inside `discoverSourceFiles`) so
@@ -60,8 +70,8 @@ export interface CliOptions {
      */
     sourceDir?: Array<string>;
     /**
-     * Source root for module path extraction, relative to project root
-     * (undefined = single sourceDir or longest common prefix).
+     * Source root for module path extraction, relative to project root or
+     * absolute inside it (undefined = single sourceDir or longest common prefix).
      *
      * Module paths in output are stripped of `<projectRoot>/<sourceRoot>/`.
      * Pass `.` (or `""`) to keep module paths project-relative — useful when

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAU9C,4CAA4C;AAC5C,QAAA,MAAM,oBAAoB,4BAA6B,CAAC;AACxD,KAAK,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAS9D;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,gFAAgF;IAChF,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAU,OAAM,KAAK,CAAC,MAAM,CAAgB,KAAG,OAAO,CAAC,MAAM,CA2N/E,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAUhD,4CAA4C;AAC5C,QAAA,MAAM,oBAAoB,4BAA6B,CAAC;AACxD,KAAK,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAS9D;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAU,OAAM,KAAK,CAAC,MAAM,CAAgB,KAAG,OAAO,CAAC,MAAM,CA6N/E,CAAC"}

package/dist/cli.js

@@ -22,6 +22,7 @@ import { writeFile, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import picomatch from 'picomatch';
 import { analyzeFromFiles } from './analyze.js';
+import { DEFAULT_SOURCE_OPTIONS } from './source-config.js';
 import { hasErrors } from './diagnostics.js';
 import { to_error_message } from './error.js';
 import { compactReplacer } from './declaration-helpers.js';
@@ -67,10 +68,12 @@ export const runCli = async (argv = process.argv) => {
         .description('Static analysis for TypeScript and Svelte source code')
         .version(pkg.version)
         .argument('[project-root]', 'Project root directory', process.cwd())
-        .option('-i, --include <pattern>', 'Include pattern (repeatable, replaces exports discovery; ' +
+        .option('-i, --include <pattern>', 'Include pattern, relative to project root — absolute inside it accepted ' +
+        '(repeatable, replaces exports discovery, widens the source scope; ' +
         'incompatible with --discovery exports)', collect)
         .option('-e, --exclude <pattern>', 'Exclude glob (applied at discovery and analysis, repeatable; ' +
-        'fully replaces defaults — does not merge with **/*.test.ts, **/*.spec.ts)', collect)
+        `fully replaces the defaults ${DEFAULT_SOURCE_OPTIONS.exclude.join(', ')} — no merge; ` +
+        'node_modules and dot-directories below a source dir are always excluded regardless)', collect)
         .option('-o, --output <file>', 'Output file (default: stdout; pass `-` for explicit stdout)')
         .option('--no-resolve-dependencies', 'Disable dependency resolution')
         .option('--discovery <mode>', `Source file discovery strategy: ${DISCOVERY_VALUES.join('|')} ` +
@@ -78,9 +81,9 @@ export const runCli = async (argv = process.argv) => {
         '`exports` is strict and fails if package.json exports is missing or empty ' +
         '(also incompatible with --include).')
         .option('--dist-dir <dir>', 'Dist directory for exports discovery (default: dist)')
-        .option('--source-dir <dir>', 'Source directory relative to project root (default: src/lib). ' +
-        'Repeatable for monorepos. Drives the implicit include glob for the ' +
-        'glob-discovery fallback when no --include is provided.', collect)
+        .option('--source-dir <dir>', 'Source directory, relative to project root or absolute inside it ' +
+        '(default: src/lib). Repeatable for monorepos. Drives the implicit include ' +
+        'glob for the glob-discovery fallback when no --include is provided.', collect)
         .option('--source-root <dir>', 'Prefix stripped from module paths in output (default: the source-dir, ' +
         'or longest common prefix when multiple). Pass `.` to keep paths project-relative.')
         .option('--on-duplicates <mode>', `Dispatch on duplicate declaration names across modules: ${ON_DUPLICATES_VALUES.join('|')} ` +
@@ -131,7 +134,7 @@ Examples:
                 onDuplicates: raw.onDuplicates,
                 only: raw.only,
                 quiet: raw.quiet,
-                pretty: raw.pretty,
+                pretty: raw.pretty
             };
             const resolvedRoot = resolve(projectRoot);
             // Stderr logger — `--quiet` only mutes info; warnings and errors always print
@@ -139,7 +142,7 @@ Examples:
             const log = {
                 info: options.quiet ? () => { } : (msg) => console.error(msg),
                 warn: (msg) => console.error(`warning: ${msg}`),
-                error: (msg) => console.error(`error: ${msg}`),
+                error: (msg) => console.error(`error: ${msg}`)
             };
             // Build sourceOptions only when source-dir or source-root is specified,
             // so the default (`['src/lib']`) flows through `createSourceOptions`.
@@ -149,7 +152,7 @@ Examples:
             const sourceOptions = options.sourceDir !== undefined || options.sourceRoot !== undefined
                 ? {
                     ...(options.sourceDir !== undefined ? { sourcePaths: options.sourceDir } : {}),
-                    ...(options.sourceRoot !== undefined ? { sourceRoot: options.sourceRoot } : {}),
+                    ...(options.sourceRoot !== undefined ? { sourceRoot: options.sourceRoot } : {})
                 }
                 : undefined;
             const onDuplicates = options.onDuplicates;
@@ -162,7 +165,7 @@ Examples:
                 distDir: options.distDir,
                 ...(sourceOptions !== undefined ? { sourceOptions } : {}),
                 ...(onDuplicates !== undefined ? { onDuplicates } : {}),
-                log,
+                log
             });
             // `--only` is an output-only filter: analysis ran against the full
             // owned set so re-exports/dependents/`alsoExportedFrom` are correct,

package/dist/declaration-build.d.ts

@@ -13,7 +13,7 @@
  * @module
  */
 import { z } from 'zod';
-import type { DeclarationKind, DeclarationModifier, GenericParamJson, MemberKind, ParameterJson, OverloadJsonInput, ComponentPropJsonInput, Reactivity, ReExportJsonInput, ExternalReExportJsonInput } from './types.js';
+import type { DeclarationKind, DeclarationModifier, GenericParamJson, MemberKind, ParameterJson, OverloadJsonInput, ComponentPropJsonInput, Reactivity, ReExportJsonInput, ExternalReExportJsonInput, TypeJson } from './types.js';
 /**
  * Permissive type for constructing members incrementally before Zod validation.
  *
@@ -35,10 +35,12 @@ export interface MemberJsonBuild {
     genericParams?: Array<GenericParamJson>;
     parameters?: Array<z.input<typeof ParameterJson>>;
     returnType?: string;
+    returnTypeInfo?: TypeJson;
     returnDescription?: string;
     overloads?: Array<OverloadJsonInput>;
     examples?: Array<string>;
     deprecatedMessage?: string;
+    internalMessage?: string;
     seeAlso?: Array<string>;
     throws?: Array<{
         type?: string;
@@ -50,8 +52,10 @@ export interface MemberJsonBuild {
     partial?: boolean;
     /** Whether the member has a `?` token in its declaration. Function and variable members only. */
     optional?: boolean;
-    /** Default value documented via `@default`. Variable members only. */
+    /** Default value documented via `@default`. Variable and function members only. */
     defaultValue?: string;
+    /** Structured type. Variable members only; see `TypeJson`. */
+    typeInfo?: TypeJson;
 }
 /**
  * Permissive type for constructing declarations incrementally before Zod validation.
@@ -69,11 +73,13 @@ export interface DeclarationJsonBuild {
     sourceLine?: number;
     parameters?: Array<z.input<typeof ParameterJson>>;
     returnType?: string;
+    returnTypeInfo?: TypeJson;
     returnDescription?: string;
     genericParams?: Array<GenericParamJson>;
     overloads?: Array<OverloadJsonInput>;
     examples?: Array<string>;
     deprecatedMessage?: string;
+    internalMessage?: string;
     seeAlso?: Array<string>;
     throws?: Array<{
         type?: string;
@@ -81,8 +87,8 @@ export interface DeclarationJsonBuild {
     }>;
     since?: string;
     mutates?: Record<string, string>;
-    extends?: string | Array<string>;
-    intersects?: Array<string>;
+    extends?: Array<string>;
+    externalTypes?: Array<string>;
     implements?: Array<string>;
     members?: Array<MemberJsonBuild>;
     props?: Array<ComponentPropJsonInput>;
@@ -99,6 +105,10 @@ export interface DeclarationJsonBuild {
     module?: string;
     /** Default value documented via `@default`. Variable declarations only. */
     defaultValue?: string;
+    /** The exported name also carries a value meaning. Type/interface declarations only. */
+    mergedValue?: boolean;
+    /** Structured type. Variable and type-alias declarations only; see `TypeJson`. */
+    typeInfo?: TypeJson;
 }
 /**
  * Result of analyzing a single declaration.

package/dist/declaration-build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"declaration-build.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/declaration-build.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"declaration-build.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/declaration-build.ts"],"names":[],"mappings":"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"}

package/dist/declaration-helpers.d.ts

@@ -2,13 +2,13 @@
  * Utility functions for working with declaration and member types.
  *
  * Display formatting, code generation, serialization, type narrowing,
- * and type reference discovery for `DeclarationJson` and `MemberJson`.
+ * and `TypeJson` tokenization for `DeclarationJson` and `MemberJson`.
  *
- * @see `types.ts` for `DeclarationJson`, `MemberJson` Zod schemas
+ * @see `types.ts` for `DeclarationJson`, `MemberJson`, `TypeJson` Zod schemas
  *
  * @module
  */
-import type { DeclarationJson, MemberJson, DeclarationKind, MemberKind } from './types.js';
+import type { DeclarationJson, MemberJson, DeclarationKind, MemberKind, TypeJson } from './types.js';
 /**
  * JSON replacer that strips Zod default values for compact serialization.
  *
@@ -17,6 +17,12 @@ import type { DeclarationJson, MemberJson, DeclarationKind, MemberKind } from '.
  * Assumes all boolean fields in the schema default to `false` — a `true`-defaulted
  * boolean would need its `false` values preserved, breaking the round-trip.
  *
+ * One keyed exemption: `value` is never stripped. `TypeJson`'s literal nodes
+ * carry data there (`{kind: 'literal', value: false}` is the literal type
+ * `false`, required by the schema), not a defaulted flag — no other output
+ * field is named `value`, and any future one must not be a `false`-defaulted
+ * boolean.
+ *
  * **Root-value caveat**: `JSON.stringify([], compactReplacer)` returns the JS
  * `undefined` (not the string `'[]'`), and `JSON.stringify(false, compactReplacer)`
  * returns the JS `undefined` too. Object-rooted callers (`AnalyzeResultJson`
@@ -43,7 +49,7 @@ import type { DeclarationJson, MemberJson, DeclarationKind, MemberKind } from '.
  * const restored = AnalyzeResultJson.parse(JSON.parse(json));
  * ```
  */
-export declare const compactReplacer: (_key: string, value: unknown) => unknown;
+export declare const compactReplacer: (key: string, value: unknown) => unknown;
 /**
  * Format declaration or member name with generic parameters for display.
  *
@@ -69,7 +75,10 @@ export declare const getDisplayName: (declaration: DeclarationJson | MemberJson)
 /**
  * Generate TypeScript import statement for a declaration.
  *
- * Produces `import type` for type/interface declarations, `import` for values.
+ * Produces `import type` for type/interface declarations, `import` for values —
+ * including type/interface declarations marked `mergedValue` (a merged
+ * value+type symbol like a schema/type pair is importable as a runtime value,
+ * so a type-only import would break value use).
  *
  * **Default export handling**: when `declaration.name === 'default'`, emits
  * `import X from '...'` with the binding derived by PascalCasing the module
@@ -96,56 +105,70 @@ export declare const getDisplayName: (declaration: DeclarationJson | MemberJson)
  */
 export declare const generateImport: (declaration: DeclarationJson, modulePath: string, libraryName: string) => string;
 /**
- * Pre-compile identifier-boundary patterns for a set of declaration names.
+ * One rendered piece of a `TypeJson` tree, produced by `typeJsonToTokens`:
+ * `name` tokens are candidate references for a renderer to link (or print
+ * plainly) — reference names, alias names of alias-carrying
+ * unions/intersections — `code` tokens are terminal type text (intrinsics,
+ * literals, anonymous objects/functions, depth-capped nodes) for a renderer
+ * to syntax-highlight, and `text` tokens are structural punctuation
+ * (`<`, ` | `, `[]`, tuple labels). A `name` token carries `module` when its
+ * reference node does (registry-recovered references — the declaring
+ * `ModuleJson.path`), so a renderer can scope the link; alias-name tokens
+ * never carry it.
+ */
+export type TypeJsonToken = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'name';
+    name: string;
+    module?: string;
+} | {
+    kind: 'code';
+    text: string;
+};
+/**
+ * Flatten a `TypeJson` tree into a render-ready token list.
  *
- * When scanning many type strings against the same declaration set,
- * call this once and pass the result to `findTypeReferences`
- * to avoid recompiling regexes on every call.
+ * The semantic linearization for renderers: spacing, separators,
+ * parenthesization (`((x) => void) | null`, `(A | B)[]`), and tuple labels
+ * (`[a: string, b?: number, ...rest: boolean[]]`) are decided here — in
+ * lockstep with the `TypeJson` schema's projection rules — so a renderer
+ * maps tokens to output without re-deriving type syntax. What a token
+ * *looks like* stays the consumer's decision: fuz_ui links `name` tokens to
+ * API docs and syntax-highlights `code` tokens; a CLI might print them all
+ * plainly. Adjacent punctuation merges into single `text` tokens.
  *
- * @param declarationNames - set of known in-project declaration names
- * @returns array of `[name, pattern]` pairs for use with `findTypeReferences`
+ * @param node - the `TypeJson` tree to flatten (a `typeInfo`/`returnTypeInfo` field)
+ * @returns tokens in source order; concatenating their text yields the printed type
  *
  * @example
  * ```ts
- * const names = new Set(modules.flatMap(m => m.declarations.map(d => d.name)));
- * const patterns = buildTypeReferencePatterns(names);
- * for (const decl of declarations) {
- *   const refs = findTypeReferences(decl.typeSignature, patterns);
- * }
+ * typeJsonToTokens({kind: 'reference', name: 'Map', typeArgs: [
+ * 	{kind: 'intrinsic', text: 'string'},
+ * 	{kind: 'reference', name: 'Tome'}
+ * ]})
+ * // => [{kind: 'name', name: 'Map'}, {kind: 'text', text: '<'},
+ * //     {kind: 'code', text: 'string'}, {kind: 'text', text: ', '},
+ * //     {kind: 'name', name: 'Tome'}, {kind: 'text', text: '>'}]
  * ```
  */
-export declare const buildTypeReferencePatterns: (declarationNames: ReadonlySet<string>) => Array<[string, RegExp]>;
+export declare const typeJsonToTokens: (node: TypeJson) => Array<TypeJsonToken>;
 /**
- * Find in-project declaration names referenced in a type string.
- *
- * Uses identifier-boundary matching to find which known declaration names appear
- * in an opaque type string (e.g., `typeSignature`, `returnType`, parameter `type`).
- * Enables consumers to render clickable type links without needing access to
- * the TypeScript type checker.
- *
- * Handles identifiers starting with `$` (e.g., `$state`) which `\b` does not
- * recognize as word boundaries.
- *
- * Accepts either a `ReadonlySet<string>` (convenience) or pre-compiled patterns
- * from `buildTypeReferencePatterns` (performance). Use pre-compiled patterns
- * when scanning many type strings against the same declaration set.
- *
- * **Known limitations**: Identifier-boundary matching can produce false positives
- * when a declaration name appears as a property key in an object literal type
- * (e.g., `{ Foo: string }` when `Foo` is a declaration). This is rare in practice.
- *
- * @param typeString - opaque type string from analysis output
- * @param declarationNames - set of names or pre-compiled patterns from `buildTypeReferencePatterns`
- * @returns array of declaration names found in the type string
+ * The plain-text printed form of a `TypeJson` tree — `typeJsonToTokens`
+ * concatenated. For consumers with no linkification or highlighting surface
+ * (CLI output, markdown code spans, log lines) and for test assertions.
  *
  * @example
  * ```ts
- * const names = new Set(modules.flatMap(m => m.declarations.map(d => d.name)));
- * findTypeReferences('Map<string, ModuleJson[]>', names)
- * // => ['ModuleJson']
+ * typeJsonToText({kind: 'union', members: [
+ * 	{kind: 'reference', name: 'Tome'},
+ * 	{kind: 'intrinsic', text: 'null'}
+ * ]})
+ * // => 'Tome | null'
  * ```
  */
-export declare const findTypeReferences: (typeString: string, declarationNames: ReadonlySet<string> | Array<[string, RegExp]>) => Array<string>;
+export declare const typeJsonToText: (node: TypeJson) => string;
 /**
  * Narrow a declaration by kind for type-safe field access.
  *

package/dist/declaration-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"declaration-helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/declaration-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAC,MAAM,YAAY,CAAC;AAIzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,EAAE,OAAO,OAAO,KAAG,OACqB,CAAC;AAIrF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,eAAe,GAAG,UAAU,KAAG,MAS1E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,cAAc,GAC1B,aAAa,eAAe,EAC5B,YAAY,MAAM,EAClB,aAAa,MAAM,KACjB,MAuBF,CAAC;AA6BF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B,GACtC,kBAAkB,WAAW,CAAC,MAAM,CAAC,KACnC,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,kBAAkB,GAC9B,YAAY,MAAM,EAClB,kBAAkB,WAAW,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAC7D,KAAK,CAAC,MAAM,CAYd,CAAC;AAIF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,eAAe,GAAG,UAAU,EAC5D,aAAa,eAAe,GAAG,UAAU,EACzC,MAAM,CAAC,KACL,WAAW,IAAI,OAAO,CAAC,eAAe,GAAG,UAAU,EAAE;IAAC,IAAI,EAAE,CAAC,CAAA;CAAC,CAA8B,CAAC"}
+{"version":3,"file":"declaration-helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/declaration-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACX,eAAe,EACf,UAAU,EACV,eAAe,EACf,UAAU,EAEV,QAAQ,EACR,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,EAAE,OAAO,OAAO,KAAG,OAGrD,CAAC;AAIV;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,eAAe,GAAG,UAAU,KAAG,MAS1E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,cAAc,GAC1B,aAAa,eAAe,EAC5B,YAAY,MAAM,EAClB,aAAa,MAAM,KACjB,MA2BF,CAAC;AAYF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAmIlC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,QAAQ,KAAG,KAAK,CAAC,aAAa,CAIpE,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,QAAQ,KAAG,MAGrC,CAAC;AAIZ;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,eAAe,GAAG,UAAU,EAC5D,aAAa,eAAe,GAAG,UAAU,EACzC,MAAM,CAAC,KACL,WAAW,IAAI,OAAO,CAAC,eAAe,GAAG,UAAU,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAA8B,CAAC"}