svelte-docinfo 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,102 @@
+/**
+ * CLI for svelte-docinfo.
+ *
+ * Static analysis for TypeScript and Svelte source code.
+ *
+ * @example
+ * ```bash
+ * # Analyze current project
+ * svelte-docinfo
+ *
+ * # Analyze specific directory
+ * svelte-docinfo ./packages/my-lib
+ *
+ * # Write to file
+ * svelte-docinfo --output docs/library.json
+ * ```
+ *
+ * @module
+ */
+import type { Discovery } from './discovery.js';
+/** Allowed values for `--on-duplicates`. */
+declare const ON_DUPLICATES_VALUES: readonly ["throw", "warn"];
+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). */
+    include?: Array<string>;
+    /**
+     * File patterns to exclude (undefined = use defaults — test and spec files).
+     *
+     * 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.
+     */
+    exclude?: Array<string>;
+    /** Output file path (undefined = stdout). */
+    output?: string;
+    /**
+     * Whether to resolve dependencies. Mapped from the `--no-resolve-dependencies`
+     * flag (commander populates `true` by default; `false` when the flag is passed).
+     * Optional here so external callers can omit it; treated as `true` when undefined.
+     */
+    resolveDependencies?: boolean;
+    /**
+     * Discovery strategy (undefined = 'auto').
+     *
+     * Mapped from `--discovery <auto|exports|glob>`.
+     */
+    discovery?: Discovery;
+    /** Dist directory name for exports-based discovery (undefined = 'dist'). */
+    distDir?: string;
+    /**
+     * Source directories relative to project root (undefined = ['src/lib']).
+     *
+     * Repeatable. Drives the implicit include glob in the glob-discovery
+     * fallback (via `deriveIncludePatterns` inside `discoverSourceFiles`) so
+     * custom source directories survive without needing an explicit `--include`.
+     */
+    sourceDir?: Array<string>;
+    /**
+     * Source root for module path extraction, relative to project root
+     * (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
+     * `sourceDir` entries share no common prefix. The `.` form is normalized
+     * to `""` inside `normalizeSourceOptions`.
+     */
+    sourceRoot?: string;
+    /**
+     * Behavior when duplicate declaration names are found across modules
+     * (undefined = emit `duplicate_declaration` diagnostic, no dispatch).
+     *
+     * Duplicate detection always runs regardless of this option — the diagnostic
+     * is the data, this option is the dispatch action.
+     */
+    onDuplicates?: OnDuplicatesFlag;
+    /**
+     * Glob patterns to filter the emitted `modules` array against `ModuleJson.path`
+     * (undefined = emit all analyzed modules).
+     *
+     * Repeatable. Output-only filter: full-project analysis still runs so re-exports,
+     * dependents, and `alsoExportedFrom` stay correct against the complete owned set.
+     * Diagnostics aren't filtered — they may reference modules dropped from output.
+     */
+    only?: Array<string>;
+    /** Whether to suppress info messages to stderr. Treated as `false` when undefined. */
+    quiet?: boolean;
+    /** Whether to pretty-print JSON output. Treated as `false` when undefined. */
+    pretty?: boolean;
+}
+/**
+ * Run the CLI with the given arguments.
+ *
+ * @param argv - command line arguments (defaults to `process.argv`)
+ * @returns exit code: 0 for success, 1 if errors in diagnostics, 2 for CLI errors
+ */
+export declare const runCli: (argv?: Array<string>) => Promise<number>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +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;AAS9C,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"}

package/dist/cli.js

@@ -0,0 +1,206 @@
+/**
+ * CLI for svelte-docinfo.
+ *
+ * Static analysis for TypeScript and Svelte source code.
+ *
+ * @example
+ * ```bash
+ * # Analyze current project
+ * svelte-docinfo
+ *
+ * # Analyze specific directory
+ * svelte-docinfo ./packages/my-lib
+ *
+ * # Write to file
+ * svelte-docinfo --output docs/library.json
+ * ```
+ *
+ * @module
+ */
+import { Command } from 'commander';
+import { writeFile, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import picomatch from 'picomatch';
+import { analyzeFromFiles } from './analyze.js';
+import { hasErrors } from './diagnostics.js';
+import { compactReplacer } from './declaration-helpers.js';
+/** Collect repeatable option values into an array. */
+const collect = (value, previous) => previous ? [...previous, value] : [value];
+/** Allowed values for `--on-duplicates`. */
+const ON_DUPLICATES_VALUES = ['throw', 'warn'];
+const isOnDuplicatesFlag = (value) => ON_DUPLICATES_VALUES.includes(value);
+/** Allowed values for `--discovery`. */
+const DISCOVERY_VALUES = ['auto', 'exports', 'glob'];
+const isDiscoveryFlag = (value) => DISCOVERY_VALUES.includes(value);
+/**
+ * Run the CLI with the given arguments.
+ *
+ * @param argv - command line arguments (defaults to `process.argv`)
+ * @returns exit code: 0 for success, 1 if errors in diagnostics, 2 for CLI errors
+ */
+export const runCli = async (argv = process.argv) => {
+    // Track exit code from action (commander actions don't return values)
+    let exitCode = 0;
+    const program = new Command();
+    // Read version from package.json using URL resolution (works in both source and dist).
+    // Loud throw on lookup failure — silent fallback would let a broken install
+    // report `0.0.0` for `--version` indefinitely.
+    const pkg = await (async () => {
+        // Try dist path first, then source path
+        const attempted = [];
+        for (const relativePath of ['../package.json', '../../package.json']) {
+            const pkgUrl = new URL(relativePath, import.meta.url);
+            attempted.push(pkgUrl.href);
+            try {
+                const content = await readFile(pkgUrl, 'utf-8');
+                return JSON.parse(content);
+            }
+            catch {
+                continue;
+            }
+        }
+        throw new Error(`svelte-docinfo: failed to load package.json for version. Attempted: ${attempted.join(', ')}`);
+    })();
+    program
+        .name('svelte-docinfo')
+        .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; ' +
+        '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)
+        .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('|')} ` +
+        '(default: auto — exports first, glob fallback). ' +
+        '`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-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('|')} ` +
+        '(default: emit duplicate_declaration diagnostic, no dispatch)')
+        .option('--only <pattern>', 'Glob filter applied to module paths in output (repeatable). ' +
+        'Full project is still analyzed — re-exports/dependents stay correct — ' +
+        'but only matching modules are emitted. Diagnostics are not filtered ' +
+        'and may reference modules dropped from output.', collect)
+        .option('--pretty', 'Pretty-print JSON output', false)
+        .option('-q, --quiet', 'Suppress info messages on stderr (warnings and errors still print)', false)
+        .addHelpText('after', `
+Examples:
+  $ svelte-docinfo                                Analyze current project
+  $ svelte-docinfo ./packages/my-lib              Analyze specific directory
+  $ svelte-docinfo -o docs.json                   Write to file
+  $ svelte-docinfo --source-dir src               Non-SvelteKit project (src/ root)
+  $ svelte-docinfo --source-dir src/lib --source-dir src/routes
+                                                  Multiple source dirs (source-root auto-derived as 'src')
+  $ svelte-docinfo --source-dir src/lib --source-dir lib/utils --source-root .
+                                                  No common prefix — module paths stay project-relative
+  $ svelte-docinfo --discovery glob               Skip package.json exports
+  $ svelte-docinfo --discovery exports            Strict — fail if exports missing
+  $ svelte-docinfo --on-duplicates throw          Enforce flat namespace
+  $ svelte-docinfo --only 'components/**'         Emit only modules under components/
+  $ svelte-docinfo --only '*.svelte'              Emit only Svelte modules (top-level)
+  $ svelte-docinfo | jq .                         Pipe to jq for readable output`)
+        .action(async (projectRoot, raw) => {
+        try {
+            // Validate enum-shaped options before constructing the rest of the options.
+            // Commander accepts arbitrary strings; we narrow to the allowed sets.
+            if (raw.onDuplicates !== undefined && !isOnDuplicatesFlag(raw.onDuplicates)) {
+                throw new Error(`Invalid --on-duplicates value: "${raw.onDuplicates}". ` +
+                    `Expected one of: ${ON_DUPLICATES_VALUES.join(', ')}`);
+            }
+            if (raw.discovery !== undefined && !isDiscoveryFlag(raw.discovery)) {
+                throw new Error(`Invalid --discovery value: "${raw.discovery}". ` +
+                    `Expected one of: ${DISCOVERY_VALUES.join(', ')}`);
+            }
+            const options = {
+                include: raw.include,
+                exclude: raw.exclude,
+                output: raw.output,
+                resolveDependencies: raw.resolveDependencies,
+                discovery: raw.discovery,
+                distDir: raw.distDir,
+                sourceDir: raw.sourceDir,
+                sourceRoot: raw.sourceRoot,
+                onDuplicates: raw.onDuplicates,
+                only: raw.only,
+                quiet: raw.quiet,
+                pretty: raw.pretty,
+            };
+            const resolvedRoot = resolve(projectRoot);
+            // Stderr logger — `--quiet` only mutes info; warnings and errors always print
+            // so silent CI runs still surface actionable signal.
+            const log = {
+                info: options.quiet ? () => { } : (msg) => console.error(msg),
+                warn: (msg) => console.error(`warning: ${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`.
+            // `!== undefined` rather than truthy: `--source-root ''` (or `--source-root .`,
+            // aliased internally) is a valid opt-in for project-relative module paths
+            // when sourcePaths share no common prefix.
+            const sourceOptions = options.sourceDir !== undefined || options.sourceRoot !== undefined
+                ? {
+                    ...(options.sourceDir !== undefined ? { sourcePaths: options.sourceDir } : {}),
+                    ...(options.sourceRoot !== undefined ? { sourceRoot: options.sourceRoot } : {}),
+                }
+                : undefined;
+            const onDuplicates = options.onDuplicates;
+            const { modules, diagnostics } = await analyzeFromFiles({
+                projectRoot: resolvedRoot,
+                include: options.include,
+                exclude: options.exclude,
+                resolveDependencies: options.resolveDependencies,
+                discovery: options.discovery,
+                distDir: options.distDir,
+                ...(sourceOptions !== undefined ? { sourceOptions } : {}),
+                ...(onDuplicates !== undefined ? { onDuplicates } : {}),
+                log,
+            });
+            // `--only` is an output-only filter: analysis ran against the full
+            // owned set so re-exports/dependents/`alsoExportedFrom` are correct,
+            // then matching modules are kept for emission. Diagnostics pass
+            // through untouched — filtering them by the same patterns would
+            // silently drop warnings about modules the user excluded from output.
+            const matchOnly = options.only && picomatch(options.only);
+            const emittedModules = matchOnly ? modules.filter((m) => matchOnly(m.path)) : modules;
+            // `AnalyzeResultJson` is the wire-format contract — both `modules`
+            // and `diagnostics` default to `[]` on `.parse()`, so empty arrays
+            // stripped here round-trip losslessly through the schema. Consumers
+            // programmatically ingesting analysis JSON should parse through
+            // `AnalyzeResultJson` to restore defaults; raw-JSON consumers
+            // (`jq '.diagnostics | length'` returns `0` on `{}` since jq treats
+            // null length as 0) don't need the parse step.
+            const jsonOutput = JSON.stringify({ modules: emittedModules, diagnostics }, compactReplacer, options.pretty ? 2 : undefined);
+            // Write output. `-o -` is the conventional stdout sentinel
+            // (matches gzip, curl, cat); accept it as an explicit form so
+            // `svelte-docinfo -o "$OUT"` works when $OUT=-.
+            if (options.output && options.output !== '-') {
+                await writeFile(options.output, jsonOutput + '\n');
+                log.info(`Wrote output to ${options.output}`);
+            }
+            else {
+                console.log(jsonOutput);
+            }
+            exitCode = hasErrors(diagnostics) ? 1 : 0;
+        }
+        catch (error) {
+            // Friendly one-line error for users; full stack only on DEBUG=1
+            // so CI logs and bug reports can still capture it on demand.
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`error: ${message}`);
+            if (process.env.DEBUG) {
+                console.error(error);
+            }
+            exitCode = 2;
+        }
+    });
+    await program.parseAsync(argv);
+    return exitCode;
+};

package/dist/concurrency.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Internal concurrency helpers — bounded `Promise.all` for the few sites
+ * where unbounded fan-out would risk resource exhaustion.
+ *
+ * - `MAX_FILE_CONCURRENCY` — parallel `readFile` cap. Bounds FD pressure so
+ *   projects with thousands of source files don't trip `EMFILE` against the
+ *   typical 1024-FD ulimit. Used by `files.globFiles` and `exports.discoverFromExports`.
+ * - `MAX_RESOLVE_CONCURRENCY` — parallel resolver-call cap for session phase 2.
+ *   Async resolvers (Vite/Rollup `resolveId`, user-supplied) get backpressure
+ *   instead of a 20k+ task fan-out at once. Sync resolvers (TS default,
+ *   no-deps stub) settle in microtasks regardless of the bound.
+ *
+ * Same numerical value today, separately named so a future tuning pass can
+ * move them independently (FD pressure and resolver backpressure are unrelated
+ * limits that happen to coincide at this cap).
+ *
+ * @module
+ */
+export declare const MAX_FILE_CONCURRENCY = 100;
+export declare const MAX_RESOLVE_CONCURRENCY = 100;
+/**
+ * Maps over `items` with a bounded number of in-flight promises, preserving
+ * input order.
+ *
+ * Fail-fast: when `fn` rejects, the outer promise rejects with that error and
+ * idle workers stop pulling from the queue (already-in-flight `fn` calls run
+ * to completion — there's no `AbortSignal` plumbing). Subsequent rejections
+ * from in-flight calls are swallowed by `Promise.all` (only the first wins),
+ * so a misbehaving `fn` can't surface a second error after the function
+ * returns.
+ *
+ * @param items - input array
+ * @param concurrency - maximum number of concurrent operations
+ * @param fn - mapping function (receives item and index)
+ * @returns array of results in input order
+ */
+export declare const map_concurrent: <T, R>(items: ReadonlyArray<T>, concurrency: number, fn: (item: T, index: number) => Promise<R>) => Promise<Array<R>>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,aAAa,MAAM,EACnB,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,KACxC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAkBlB,CAAC"}

package/dist/concurrency.js

@@ -0,0 +1,57 @@
+/**
+ * Internal concurrency helpers — bounded `Promise.all` for the few sites
+ * where unbounded fan-out would risk resource exhaustion.
+ *
+ * - `MAX_FILE_CONCURRENCY` — parallel `readFile` cap. Bounds FD pressure so
+ *   projects with thousands of source files don't trip `EMFILE` against the
+ *   typical 1024-FD ulimit. Used by `files.globFiles` and `exports.discoverFromExports`.
+ * - `MAX_RESOLVE_CONCURRENCY` — parallel resolver-call cap for session phase 2.
+ *   Async resolvers (Vite/Rollup `resolveId`, user-supplied) get backpressure
+ *   instead of a 20k+ task fan-out at once. Sync resolvers (TS default,
+ *   no-deps stub) settle in microtasks regardless of the bound.
+ *
+ * Same numerical value today, separately named so a future tuning pass can
+ * move them independently (FD pressure and resolver backpressure are unrelated
+ * limits that happen to coincide at this cap).
+ *
+ * @module
+ */
+export const MAX_FILE_CONCURRENCY = 100;
+export const MAX_RESOLVE_CONCURRENCY = 100;
+/**
+ * Maps over `items` with a bounded number of in-flight promises, preserving
+ * input order.
+ *
+ * Fail-fast: when `fn` rejects, the outer promise rejects with that error and
+ * idle workers stop pulling from the queue (already-in-flight `fn` calls run
+ * to completion — there's no `AbortSignal` plumbing). Subsequent rejections
+ * from in-flight calls are swallowed by `Promise.all` (only the first wins),
+ * so a misbehaving `fn` can't surface a second error after the function
+ * returns.
+ *
+ * @param items - input array
+ * @param concurrency - maximum number of concurrent operations
+ * @param fn - mapping function (receives item and index)
+ * @returns array of results in input order
+ */
+export const map_concurrent = async (items, concurrency, fn) => {
+    const results = new Array(items.length);
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            try {
+                results[i] = await fn(items[i], i);
+            }
+            catch (err) {
+                failed = true;
+                throw err;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+    return results;
+};

package/dist/declaration-build.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Types for incremental declaration construction during analysis.
+ *
+ * These types are used by the analysis layer (`typescript-extract-*.ts`,
+ * `typescript-exports.ts`, `svelte.ts`, `tsdoc.ts`) to build declarations before
+ * Zod validation. Most consumers work with the validated types from `types.ts`,
+ * but these are available for advanced use cases.
+ *
+ * @see `types.ts` for consumer-facing Zod schemas (`DeclarationJson`, `ModuleJson`)
+ * @see `typescript-exports.ts` and `typescript-extract-*.ts` for TypeScript declaration analysis
+ * @see `svelte.ts` for Svelte component analysis
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { DeclarationKind, DeclarationModifier, GenericParamJson, MemberKind, ParameterJson, OverloadJsonInput, ComponentPropJsonInput, Reactivity } from './types.js';
+/**
+ * Information about a same-name re-export.
+ *
+ * Collected during phase 1 of analysis and passed to `mergeReExports`
+ * in phase 2 to build `alsoExportedFrom` arrays on canonical declarations.
+ */
+export interface ReExportInfo {
+    /**
+     * Name of the re-exported declaration. `'default'` for default-slot
+     * re-exports (`export {default} from './x'`) — that's the canonical's
+     * actual symbol name in the original module.
+     */
+    name: string;
+    /** Module path (relative to `sourceRoot`) where the declaration is originally declared. */
+    originalModule: string;
+}
+/**
+ * Permissive type for constructing members incrementally before Zod validation.
+ *
+ * Used by internal analysis functions in `typescript-extract-*.ts` that build members
+ * by mutating a plain object. The discriminated union schema (`MemberJson`)
+ * validates the final shape at the `ModuleJson.parse()` boundary.
+ *
+ * Mirrors `DeclarationJsonBuild` for the same reason: construction sites
+ * determine `kind` at runtime, so TypeScript can't narrow the union during
+ * incremental field assignment.
+ */
+export interface MemberJsonBuild {
+    name?: string;
+    kind: MemberKind;
+    docComment?: string;
+    typeSignature?: string;
+    modifiers?: Array<DeclarationModifier>;
+    sourceLine?: number;
+    genericParams?: Array<GenericParamJson>;
+    parameters?: Array<z.input<typeof ParameterJson>>;
+    returnType?: string;
+    returnDescription?: string;
+    overloads?: Array<OverloadJsonInput>;
+    examples?: Array<string>;
+    deprecatedMessage?: string;
+    seeAlso?: Array<string>;
+    throws?: Array<{
+        type?: string;
+        description: string;
+    }>;
+    since?: string;
+    mutates?: Record<string, string>;
+    reactivity?: Reactivity;
+    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. */
+    defaultValue?: string;
+}
+/**
+ * Permissive type for constructing declarations incrementally before Zod validation.
+ *
+ * Used by internal analysis functions (`analyzeDeclaration`, `extractFunctionInfo`, etc.)
+ * that build declarations by mutating a plain object. The discriminated union schema
+ * validates the final shape at the `ModuleJson.parse()` boundary.
+ */
+export interface DeclarationJsonBuild {
+    name?: string;
+    kind: DeclarationKind;
+    docComment?: string;
+    typeSignature?: string;
+    modifiers?: Array<DeclarationModifier>;
+    sourceLine?: number;
+    parameters?: Array<z.input<typeof ParameterJson>>;
+    returnType?: string;
+    returnDescription?: string;
+    genericParams?: Array<GenericParamJson>;
+    overloads?: Array<OverloadJsonInput>;
+    examples?: Array<string>;
+    deprecatedMessage?: string;
+    seeAlso?: Array<string>;
+    throws?: Array<{
+        type?: string;
+        description: string;
+    }>;
+    since?: string;
+    mutates?: Record<string, string>;
+    extends?: string | Array<string>;
+    intersects?: Array<string>;
+    implements?: Array<string>;
+    members?: Array<MemberJsonBuild>;
+    props?: Array<ComponentPropJsonInput>;
+    acceptsChildren?: boolean;
+    lang?: 'js';
+    alsoExportedFrom?: Array<string>;
+    aliasOf?: {
+        module: string;
+        name: string;
+    };
+    reactivity?: Reactivity;
+    partial?: boolean;
+    /** Source module path for `kind: 'namespace'` declarations (`export * as ns from './x'`). */
+    module?: string;
+    /** Default value documented via `@default`. Variable declarations only. */
+    defaultValue?: string;
+}
+/**
+ * Result of analyzing a single declaration.
+ *
+ * Produced by `analyzeDeclaration` (in `typescript-exports.ts`) and Svelte component analysis.
+ * Used by `analyzeModule` to filter `@nodocs` declarations before output.
+ *
+ * Uses `DeclarationJsonBuild` (not `DeclarationJsonInput`) because declarations
+ * are constructed incrementally — Zod validation happens at the `ModuleJson.parse()` boundary.
+ */
+export interface DeclarationAnalysis {
+    /** The analyzed declaration metadata (pre-validation). */
+    declaration: DeclarationJsonBuild;
+    /** Whether the declaration is marked `@nodocs` (should be excluded from documentation). */
+    nodocs: boolean;
+}
+/**
+ * Result of analyzing a module's exports.
+ *
+ * Produced by `analyzeExports` in `typescript-exports.ts`.
+ */
+export interface ModuleExportsAnalysis {
+    /** Module-level documentation comment. */
+    moduleComment?: string;
+    /** All exported declarations with `@nodocs` flags — consumer filters based on policy. */
+    declarations: Array<DeclarationAnalysis>;
+    /** Same-name re-exports (for building `alsoExportedFrom` in post-processing). */
+    reExports: Array<ReExportInfo>;
+    /** Star exports (`export * from './module'`) — module paths that are fully re-exported. */
+    starExports: Array<string>;
+}
+/**
+ * Result of analyzing a module (TypeScript or Svelte).
+ *
+ * Produced by `analyzeTypescriptModule` and `analyzeSvelteModule`.
+ * Both analyzers return this same structure for uniform handling
+ * by `analyzeModule` in `analyze-core.ts`.
+ */
+export interface ModuleAnalysis extends ModuleExportsAnalysis {
+    /** Module path relative to source root. */
+    path: string;
+    /** Dependencies (other source modules this module imports). Empty if none. */
+    dependencies: Array<string>;
+    /** Dependents (other source modules that import this module). Empty if none. */
+    dependents: Array<string>;
+}
+//# sourceMappingURL=declaration-build.d.ts.map

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

@@ -0,0 +1 @@
+{"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-build.js

@@ -0,0 +1,15 @@
+/**
+ * Types for incremental declaration construction during analysis.
+ *
+ * These types are used by the analysis layer (`typescript-extract-*.ts`,
+ * `typescript-exports.ts`, `svelte.ts`, `tsdoc.ts`) to build declarations before
+ * Zod validation. Most consumers work with the validated types from `types.ts`,
+ * but these are available for advanced use cases.
+ *
+ * @see `types.ts` for consumer-facing Zod schemas (`DeclarationJson`, `ModuleJson`)
+ * @see `typescript-exports.ts` and `typescript-extract-*.ts` for TypeScript declaration analysis
+ * @see `svelte.ts` for Svelte component analysis
+ *
+ * @module
+ */
+import { z } from 'zod';