/**
* 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,
ReExportJsonInput,
ExternalReExportJsonInput,
} from './types.js';
/**
* 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. Published as `ModuleJson.reExports` and consumed
* by `mergeReExports` in phase 2 to build `alsoExportedFrom` arrays on
* canonical declarations. Unsorted here and may contain exact duplicates
* (Svelte default-slot re-keying) — ordering and dedup are applied at
* publication in `analyze-core.ts`.
*/
reExports: Array<ReExportJsonInput>;
/** Star exports (`export * from './module'`) — module paths that are fully re-exported. */
starExports: Array<string>;
/**
* Direct re-exports from external packages. Published as
* `ModuleJson.externalReExports`; unsorted here, sorted at publication.
*/
externalReExports: Array<ExternalReExportJsonInput>;
/** External star exports (`export * from 'pkg'`) — specifiers as written. */
externalStarExports: 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>;
}
{
"path": "declaration-build.ts",
"declarations": [
{
"name": "MemberJsonBuild",
"kind": "interface",
"docComment": "Permissive type for constructing members incrementally before Zod validation.\n\nUsed by internal analysis functions in `typescript-extract-*.ts` that build members\nby mutating a plain object. The discriminated union schema (`MemberJson`)\nvalidates the final shape at the `ModuleJson.parse()` boundary.\n\nMirrors `DeclarationJsonBuild` for the same reason: construction sites\ndetermine `kind` at runtime, so TypeScript can't narrow the union during\nincremental field assignment.",
"typeSignature": "MemberJsonBuild",
"sourceLine": 42,
"members": [
{
"name": "name",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "kind",
"kind": "variable",
"typeSignature": "MemberKind"
},
{
"name": "docComment",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "typeSignature",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "modifiers",
"kind": "variable",
"typeSignature": "Array<DeclarationModifier>",
"optional": true
},
{
"name": "sourceLine",
"kind": "variable",
"typeSignature": "number",
"optional": true
},
{
"name": "genericParams",
"kind": "variable",
"typeSignature": "Array<GenericParamJson>",
"optional": true
},
{
"name": "parameters",
"kind": "variable",
"typeSignature": "Array<z.input<typeof ParameterJson>>",
"optional": true
},
{
"name": "returnType",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "returnDescription",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "overloads",
"kind": "variable",
"typeSignature": "Array<OverloadJsonInput>",
"optional": true
},
{
"name": "examples",
"kind": "variable",
"typeSignature": "Array<string>",
"optional": true
},
{
"name": "deprecatedMessage",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "seeAlso",
"kind": "variable",
"typeSignature": "Array<string>",
"optional": true
},
{
"name": "throws",
"kind": "variable",
"typeSignature": "Array<{type?: string; description: string}>",
"optional": true
},
{
"name": "since",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "mutates",
"kind": "variable",
"typeSignature": "Record<string, string>",
"optional": true
},
{
"name": "reactivity",
"kind": "variable",
"typeSignature": "Reactivity",
"optional": true
},
{
"name": "partial",
"kind": "variable",
"typeSignature": "boolean",
"optional": true
},
{
"name": "optional",
"kind": "variable",
"docComment": "Whether the member has a `?` token in its declaration. Function and variable members only.",
"typeSignature": "boolean",
"optional": true
},
{
"name": "defaultValue",
"kind": "variable",
"docComment": "Default value documented via `@default`. Variable members only.",
"typeSignature": "string",
"optional": true
}
]
},
{
"name": "DeclarationJsonBuild",
"kind": "interface",
"docComment": "Permissive type for constructing declarations incrementally before Zod validation.\n\nUsed by internal analysis functions (`analyzeDeclaration`, `extractFunctionInfo`, etc.)\nthat build declarations by mutating a plain object. The discriminated union schema\nvalidates the final shape at the `ModuleJson.parse()` boundary.",
"typeSignature": "DeclarationJsonBuild",
"sourceLine": 75,
"members": [
{
"name": "name",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "kind",
"kind": "variable",
"typeSignature": "DeclarationKind"
},
{
"name": "docComment",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "typeSignature",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "modifiers",
"kind": "variable",
"typeSignature": "Array<DeclarationModifier>",
"optional": true
},
{
"name": "sourceLine",
"kind": "variable",
"typeSignature": "number",
"optional": true
},
{
"name": "parameters",
"kind": "variable",
"typeSignature": "Array<z.input<typeof ParameterJson>>",
"optional": true
},
{
"name": "returnType",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "returnDescription",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "genericParams",
"kind": "variable",
"typeSignature": "Array<GenericParamJson>",
"optional": true
},
{
"name": "overloads",
"kind": "variable",
"typeSignature": "Array<OverloadJsonInput>",
"optional": true
},
{
"name": "examples",
"kind": "variable",
"typeSignature": "Array<string>",
"optional": true
},
{
"name": "deprecatedMessage",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "seeAlso",
"kind": "variable",
"typeSignature": "Array<string>",
"optional": true
},
{
"name": "throws",
"kind": "variable",
"typeSignature": "Array<{type?: string; description: string}>",
"optional": true
},
{
"name": "since",
"kind": "variable",
"typeSignature": "string",
"optional": true
},
{
"name": "mutates",
"kind": "variable",
"typeSignature": "Record<string, string>",
"optional": true
},
{
"name": "extends",
"kind": "variable",
"typeSignature": "string | Array<string>",
"optional": true
},
{
"name": "intersects",
"kind": "variable",
"typeSignature": "Array<string>",
"optional": true
},
{
"name": "implements",
"kind": "variable",
"typeSignature": "Array<string>",
"optional": true
},
{
"name": "members",
"kind": "variable",
"typeSignature": "Array<MemberJsonBuild>",
"optional": true
},
{
"name": "props",
"kind": "variable",
"typeSignature": "Array<ComponentPropJsonInput>",
"optional": true
},
{
"name": "acceptsChildren",
"kind": "variable",
"typeSignature": "boolean",
"optional": true
},
{
"name": "lang",
"kind": "variable",
"typeSignature": "'js'",
"optional": true
},
{
"name": "alsoExportedFrom",
"kind": "variable",
"typeSignature": "Array<string>",
"optional": true
},
{
"name": "aliasOf",
"kind": "variable",
"typeSignature": "{module: string; name: string}",
"optional": true
},
{
"name": "reactivity",
"kind": "variable",
"typeSignature": "Reactivity",
"optional": true
},
{
"name": "partial",
"kind": "variable",
"typeSignature": "boolean",
"optional": true
},
{
"name": "module",
"kind": "variable",
"docComment": "Source module path for `kind: 'namespace'` declarations (`export * as ns from './x'`).",
"typeSignature": "string",
"optional": true
},
{
"name": "defaultValue",
"kind": "variable",
"docComment": "Default value documented via `@default`. Variable declarations only.",
"typeSignature": "string",
"optional": true
}
]
},
{
"name": "DeclarationAnalysis",
"kind": "interface",
"docComment": "Result of analyzing a single declaration.\n\nProduced by `analyzeDeclaration` (in `typescript-exports.ts`) and Svelte component analysis.\nUsed by `analyzeModule` to filter `@nodocs` declarations before output.\n\nUses `DeclarationJsonBuild` (not `DeclarationJsonInput`) because declarations\nare constructed incrementally — Zod validation happens at the `ModuleJson.parse()` boundary.",
"typeSignature": "DeclarationAnalysis",
"sourceLine": 119,
"members": [
{
"name": "declaration",
"kind": "variable",
"docComment": "The analyzed declaration metadata (pre-validation).",
"typeSignature": "DeclarationJsonBuild"
},
{
"name": "nodocs",
"kind": "variable",
"docComment": "Whether the declaration is marked `@nodocs` (should be excluded from documentation).",
"typeSignature": "boolean"
}
]
},
{
"name": "ModuleExportsAnalysis",
"kind": "interface",
"docComment": "Result of analyzing a module's exports.\n\nProduced by `analyzeExports` in `typescript-exports.ts`.",
"typeSignature": "ModuleExportsAnalysis",
"sourceLine": 131,
"members": [
{
"name": "moduleComment",
"kind": "variable",
"docComment": "Module-level documentation comment.",
"typeSignature": "string",
"optional": true
},
{
"name": "declarations",
"kind": "variable",
"docComment": "All exported declarations with `@nodocs` flags — consumer filters based on policy.",
"typeSignature": "Array<DeclarationAnalysis>"
},
{
"name": "reExports",
"kind": "variable",
"docComment": "Same-name re-exports. Published as `ModuleJson.reExports` and consumed\nby `mergeReExports` in phase 2 to build `alsoExportedFrom` arrays on\ncanonical declarations. Unsorted here and may contain exact duplicates\n(Svelte default-slot re-keying) — ordering and dedup are applied at\npublication in `analyze-core.ts`.",
"typeSignature": "Array<ReExportJsonInput>"
},
{
"name": "starExports",
"kind": "variable",
"docComment": "Star exports (`export * from './module'`) — module paths that are fully re-exported.",
"typeSignature": "Array<string>"
},
{
"name": "externalReExports",
"kind": "variable",
"docComment": "Direct re-exports from external packages. Published as\n`ModuleJson.externalReExports`; unsorted here, sorted at publication.",
"typeSignature": "Array<ExternalReExportJsonInput>"
},
{
"name": "externalStarExports",
"kind": "variable",
"docComment": "External star exports (`export * from 'pkg'`) — specifiers as written.",
"typeSignature": "Array<string>"
}
]
},
{
"name": "ModuleAnalysis",
"kind": "interface",
"docComment": "Result of analyzing a module (TypeScript or Svelte).\n\nProduced by `analyzeTypescriptModule` and `analyzeSvelteModule`.\nBoth analyzers return this same structure for uniform handling\nby `analyzeModule` in `analyze-core.ts`.",
"typeSignature": "ModuleAnalysis",
"sourceLine": 162,
"extends": [
"ModuleExportsAnalysis"
],
"members": [
{
"name": "path",
"kind": "variable",
"docComment": "Module path relative to source root.",
"typeSignature": "string"
},
{
"name": "dependencies",
"kind": "variable",
"docComment": "Dependencies (other source modules this module imports). Empty if none.",
"typeSignature": "Array<string>"
},
{
"name": "dependents",
"kind": "variable",
"docComment": "Dependents (other source modules that import this module). Empty if none.",
"typeSignature": "Array<string>"
}
]
}
],
"moduleComment": "Types for incremental declaration construction during analysis.\n\nThese types are used by the analysis layer (`typescript-extract-*.ts`,\n`typescript-exports.ts`, `svelte.ts`, `tsdoc.ts`) to build declarations before\nZod validation. Most consumers work with the validated types from `types.ts`,\nbut these are available for advanced use cases.\n\n@see `types.ts` for consumer-facing Zod schemas (`DeclarationJson`, `ModuleJson`)\n@see `typescript-exports.ts` and `typescript-extract-*.ts` for TypeScript declaration analysis\n@see `svelte.ts` for Svelte component analysis",
"dependencies": [
"types.ts"
],
"dependents": [
"analyze-core.ts",
"svelte.ts",
"tsdoc.ts",
"typescript-exports.ts",
"typescript-extract-class.ts",
"typescript-extract-function.ts",
"typescript-extract-shared.ts",
"typescript-extract-type-properties.ts",
"typescript-extract-type.ts"
]
}