@fuzdev/fuz_ui 0.193.1 → 0.195.0

package/src/lib/module.svelte.ts

@@ -1,4 +1,4 @@
-import type {ModuleJson} from '@fuzdev/fuz_util/source_json.js';
+import type {ModuleJsonInput} from 'svelte-docinfo/types.js';
 
 import {Declaration} from './declaration.svelte.js';
 import type {Library} from './library.svelte.js';
@@ -6,13 +6,30 @@ import {url_github_file} from './package_helpers.js';
 
 /**
  * Rich runtime representation of a module with computed properties.
+ *
+ * Wraps svelte-docinfo's `ModuleJson` with reactive derivations,
+ * URL generation, and `Declaration` instances.
+ *
+ * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
+ * @see `declaration.svelte.ts` for the `Declaration` wrapper class
  */
 export class Module {
 	readonly library: Library = $state.raw()!;
-	readonly module_json: ModuleJson = $state.raw()!;
+	// `library.json` is compacted (svelte-docinfo's `compactReplacer` strips empty
+	// default arrays), so the on-disk data is the `*Input` shape. Typing it as
+	// input makes TypeScript force guards on defaulted-array reads.
+	readonly module_json: ModuleJsonInput = $state.raw()!;
 
 	/**
-	 * Canonical module path (e.g., 'Alert.ts', 'helpers/foo.ts').
+	 * Canonical module path — `src/lib/`-relative, with source extension
+	 * (`.ts`, `.svelte`, etc.). Examples: `'Alert.ts'`, `'helpers/foo.ts'`,
+	 * `'actions/composables.ts'`.
+	 *
+	 * This is the key `Library.module_by_path` indexes, so it's also the
+	 * exact string TSDoc backtick references must use to auto-link to a
+	 * module via `DocsLink.svelte` (e.g., `` `actions/composables.ts` ``).
+	 * A leading `./` or a `.js` runtime extension will not match. Top-level
+	 * files match by bare filename; nested files require the full sub-path.
 	 */
 	path = $derived(this.module_json.path);
 
@@ -21,17 +38,15 @@ export class Module {
 	 */
 	path_import = $derived('./' + this.path);
 
-	module_comment = $derived(this.module_json.module_comment);
+	module_comment = $derived(this.module_json.moduleComment);
 
 	/**
 	 * Array of `Declaration` instances. Filters out default exports.
 	 */
 	declarations = $derived(
-		this.module_json.declarations
-			? this.module_json.declarations
-					.filter((declaration_json) => declaration_json.name !== 'default')
-					.map((declaration_json) => new Declaration(this, declaration_json))
-			: [],
+		(this.module_json.declarations ?? [])
+			.filter((declaration_json) => declaration_json.name !== 'default')
+			.map((declaration_json) => new Declaration(this, declaration_json)),
 	);
 
 	/**
@@ -48,23 +63,21 @@ export class Module {
 			: undefined,
 	);
 
-	has_declarations: boolean = $derived(
-		!!(this.module_json.declarations && this.module_json.declarations.length > 0),
-	);
+	has_declarations: boolean = $derived((this.module_json.declarations?.length ?? 0) > 0);
 
-	has_module_comment: boolean = $derived(!!this.module_json.module_comment);
+	has_module_comment: boolean = $derived(!!this.module_comment);
 
 	/**
 	 * Modules this imports (paths relative to src/lib).
 	 */
-	dependencies = $derived(this.module_json.dependencies);
+	dependencies = $derived(this.module_json.dependencies ?? []);
 
 	/**
 	 * Modules that import this (paths relative to src/lib).
 	 */
-	dependents = $derived(this.module_json.dependents);
+	dependents = $derived(this.module_json.dependents ?? []);
 
-	constructor(library: Library, module_json: ModuleJson) {
+	constructor(library: Library, module_json: ModuleJsonInput) {
 		this.library = library;
 		this.module_json = module_json;
 	}

package/src/lib/style_variable_helpers.svelte.ts

@@ -2,6 +2,8 @@ import type {StyleVariable} from '@fuzdev/fuz_css/variable.js';
 
 import {create_context} from './context_helpers.js';
 
+export const selected_variable_context = create_context(() => new SelectedStyleVariable(null));
+
 // TODO maybe change this to a generic wrapper class for any value?
 export class SelectedStyleVariable {
 	value: StyleVariable | null = $state.raw()!;
@@ -10,5 +12,3 @@ export class SelectedStyleVariable {
 		this.value = initial;
 	}
 }
-
-export const selected_variable_context = create_context(() => new SelectedStyleVariable(null));

package/src/lib/tome.ts

@@ -6,6 +6,10 @@ import {ensure_start} from '@fuzdev/fuz_util/string.js';
 import {create_context} from './context_helpers.js';
 import {DOCS_PATH_DEFAULT} from './docs_helpers.svelte.js';
 
+export const tomes_context = create_context<() => Map<string, Tome>>();
+
+export const tome_context = create_context<() => Tome>();
+
 export const Tome = z.object({
 	/**
 	 * Stable identifier and URL path segment — must be a URL-safe slug
@@ -47,13 +51,9 @@ export const tome_to_pathname = (
  */
 export const tome_to_title = (tome: Tome): string => tome.title ?? tome.slug;
 
-export const tomes_context = create_context<() => Map<string, Tome>>();
-
 export const tome_get_by_slug = (slug: string): Tome => {
 	const get_tomes = tomes_context.get();
 	const tome = get_tomes().get(slug);
 	if (!tome) throw Error(`unable to find tome "${slug}"`);
 	return tome;
 };
-
-export const tome_context = create_context<() => Tome>();

package/src/lib/tsdoc_mdz.ts

@@ -17,10 +17,12 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  * Convert raw TSDoc `@see` content to mdz format for rendering.
  *
  * Handles TSDoc link syntax:
- * - `{@link url|text}` → `[text](url)` (markdown link)
+ * - `{@link url|text}` → `[text](url)` (markdown link, TSDoc canonical form)
+ * - `{@link url text}` → `[text](url)` (TS-lenient space-separated form)
  * - `{@link https://...}` → `https://...` (bare URL, auto-linked by mdz)
  * - `{@link identifier}` → `` `identifier` `` (code formatting)
  * - Bare URLs → returned as-is
+ * - Bare markdown links (`[text](url)` ...) → returned as-is
  * - Bare identifiers → wrapped in backticks
  * - `identifier description text` → `` `identifier` description text `` (first token is the reference)
  *
@@ -38,6 +40,9 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  * tsdoc_see_to_mdz('https://example.com')
  * // → 'https://example.com'
  *
+ * tsdoc_see_to_mdz('[svelte-docinfo](https://github.com/ryanatkn/svelte-docinfo) for the analysis library')
+ * // → '[svelte-docinfo](https://github.com/ryanatkn/svelte-docinfo) for the analysis library'
+ *
  * tsdoc_see_to_mdz('library_gen.ts for Gro-specific integration')
  * // → '`library_gen.ts` for Gro-specific integration'
  * ```
@@ -51,7 +56,7 @@ export const tsdoc_see_to_mdz = (content: string): string => {
 	if (link_match) {
 		const inner = link_match[1]!.trim();
 
-		// Check for pipe separator (custom display text)
+		// Pipe separator takes precedence (TSDoc canonical form)
 		const pipe_index = inner.indexOf('|');
 		if (pipe_index !== -1) {
 			const reference = inner.slice(0, pipe_index).trim();
@@ -59,9 +64,27 @@ export const tsdoc_see_to_mdz = (content: string): string => {
 			return `[${display_text}](${reference})`;
 		}
 
+		// Space-separated form: TS accepts `{@link url text}` as equivalent to `{@link url|text}`.
+		// Only treat space as a separator when the first token looks like a link target (URL),
+		// so identifier-style references like `module.function` aren't split.
+		const space_index = inner.indexOf(' ');
+		if (space_index !== -1) {
+			const reference = inner.slice(0, space_index);
+			if (mdz_is_url(reference)) {
+				const display_text = inner.slice(space_index + 1).trim();
+				return `[${display_text}](${reference})`;
+			}
+		}
+
 		return format_reference(inner);
 	}
 
+	// Pass through bare markdown links (`[text](url)` optionally followed by description)
+	// so authors can write `@see [text](url) for context` directly.
+	if (trimmed.charCodeAt(0) === 91 /* [ */ && /^\[[^\]]+\]\([^)\s]+\)/.test(trimmed)) {
+		return trimmed;
+	}
+
 	// Split at first whitespace: first token is the reference, rest is description
 	const space_index = trimmed.indexOf(' ');
 	if (space_index === -1) {

package/dist/analysis_context.d.ts

@@ -1,199 +0,0 @@
-/**
- * Diagnostic collection for source analysis.
- *
- * Provides structured error/warning collection during TypeScript and Svelte
- * analysis, replacing silent catch blocks with actionable diagnostics.
- *
- * ## Error Handling Contract
- *
- * Analysis functions follow a two-tier error model:
- *
- * **Accumulated (non-fatal)** - Collected in `AnalysisContext`, analysis continues:
- * - Type resolution failures (complex generics, circular refs)
- * - Missing or unparseable JSDoc
- * - Individual member/prop extraction failures
- * - The return value is still valid but may have partial data
- *
- * **Thrown (fatal)** - Analysis cannot continue for this file:
- * - File not found or unreadable
- * - Syntax errors preventing parsing
- * - svelte2tsx transformation failures
- * - Svelte version incompatibility
- *
- * ## Usage Pattern
- *
- * ```ts
- * const ctx = new AnalysisContext();
- * const results = files.map(f => {
- *   try {
- *     return library_analyze_module(f, program, options, ctx);
- *   } catch (e) {
- *     // Fatal error - log and skip this file
- *     console.error(`Failed to analyze ${f.id}: ${e}`);
- *     return null;
- *   }
- * });
- *
- * // Results are valid even with accumulated errors
- * // Check ctx for diagnostics to display to user
- * if (ctx.has_errors()) {
- *   for (const err of ctx.errors()) {
- *     console.error(format_diagnostic(err));
- *   }
- * }
- * ```
- *
- * @example
- * ```ts
- * const ctx = new AnalysisContext();
- * // ... analysis functions add diagnostics via ctx.add(...)
- * if (ctx.has_errors()) {
- *   for (const err of ctx.errors()) {
- *     console.error(`${err.file}:${err.line}: ${err.message}`);
- *   }
- * }
- * ```
- *
- * @module
- */
-/**
- * Diagnostic severity levels.
- *
- * - `error`: Analysis failed, declaration may be incomplete or missing data
- * - `warning`: Partial success, something seems off but analysis continued
- */
-export type DiagnosticSeverity = 'error' | 'warning';
-/**
- * Discriminant for diagnostic types.
- */
-export type DiagnosticKind = 'type_extraction_failed' | 'signature_analysis_failed' | 'class_member_failed' | 'svelte_prop_failed' | 'module_skipped';
-/**
- * Base diagnostic fields shared by all diagnostic types.
- */
-export interface BaseDiagnostic {
-    kind: DiagnosticKind;
-    /** File path relative to project root (display with './' prefix). */
-    file: string;
-    /** Line number (1-based), or null if location unavailable. */
-    line: number | null;
-    /** Column number (1-based), or null if location unavailable. */
-    column: number | null;
-    /** Human-readable description of the issue. */
-    message: string;
-    severity: DiagnosticSeverity;
-}
-/**
- * Type extraction failed (e.g., complex or recursive types).
- */
-export interface TypeExtractionDiagnostic extends BaseDiagnostic {
-    kind: 'type_extraction_failed';
-    /** Name of the symbol whose type couldn't be extracted. */
-    symbol_name: string;
-}
-/**
- * Function/method signature analysis failed.
- */
-export interface SignatureAnalysisDiagnostic extends BaseDiagnostic {
-    kind: 'signature_analysis_failed';
-    /** Name of the function or method. */
-    function_name: string;
-}
-/**
- * Class member analysis failed.
- */
-export interface ClassMemberDiagnostic extends BaseDiagnostic {
-    kind: 'class_member_failed';
-    /** Name of the class. */
-    class_name: string;
-    /** Name of the member that failed. */
-    member_name: string;
-}
-/**
- * Svelte prop type resolution failed.
- */
-export interface SveltePropDiagnostic extends BaseDiagnostic {
-    kind: 'svelte_prop_failed';
-    /** Name of the component. */
-    component_name: string;
-    /** Name of the prop. */
-    prop_name: string;
-}
-/**
- * Module was skipped during analysis.
- * Could be due to missing source file in program or no analyzer available.
- */
-export interface ModuleSkippedDiagnostic extends BaseDiagnostic {
-    kind: 'module_skipped';
-    /** Reason the module was skipped. */
-    reason: 'not_in_program' | 'no_analyzer';
-}
-/**
- * Union of all diagnostic types.
- */
-export type Diagnostic = TypeExtractionDiagnostic | SignatureAnalysisDiagnostic | ClassMemberDiagnostic | SveltePropDiagnostic | ModuleSkippedDiagnostic;
-/**
- * Context for collecting diagnostics during source analysis.
- *
- * Thread an instance through analysis functions to collect errors and warnings
- * without halting analysis. After analysis completes, check `has_errors()` and
- * report collected diagnostics.
- *
- * @example
- * ```ts
- * const ctx = new AnalysisContext();
- * ts_analyze_module_exports(source_file, checker, options, ctx);
- * if (ctx.has_errors()) {
- *   console.error('Analysis completed with errors:');
- *   for (const d of ctx.errors()) {
- *     console.error(format_diagnostic(d));
- *   }
- * }
- * ```
- */
-export declare class AnalysisContext {
-    readonly diagnostics: Array<Diagnostic>;
-    /**
-     * Add a `Diagnostic` to the collection.
-     */
-    add(diagnostic: Diagnostic): void;
-    /**
-     * Check if any errors were collected.
-     */
-    has_errors(): boolean;
-    /**
-     * Check if any warnings were collected.
-     */
-    has_warnings(): boolean;
-    /**
-     * Get all error diagnostics.
-     */
-    errors(): Array<Diagnostic>;
-    /**
-     * Get all warning diagnostics.
-     */
-    warnings(): Array<Diagnostic>;
-    /**
-     * Get diagnostics of a specific `DiagnosticKind`.
-     */
-    by_kind<K extends DiagnosticKind>(kind: K): Array<Extract<Diagnostic, {
-        kind: K;
-    }>>;
-}
-/**
- * Options for formatting diagnostics.
- */
-export interface FormatDiagnosticOptions {
-    /** Prefix for file path (default: './'). */
-    prefix?: string;
-    /** Base path to strip from absolute file paths (e.g., process.cwd()). */
-    strip_base?: string;
-}
-/**
- * Format a diagnostic for display.
- *
- * @param diagnostic - the diagnostic to format
- * @param options - formatting options
- * @returns formatted string like './file.ts:10:5: error: message'
- */
-export declare const format_diagnostic: (diagnostic: Diagnostic, options?: FormatDiagnosticOptions) => string;
-//# sourceMappingURL=analysis_context.d.ts.map

package/dist/analysis_context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"analysis_context.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/analysis_context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,cAAc,GACvB,wBAAwB,GACxB,2BAA2B,GAC3B,qBAAqB,GACrB,oBAAoB,GACpB,gBAAgB,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,cAAc,CAAC;IACrB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,cAAc;IAC/D,IAAI,EAAE,wBAAwB,CAAC;IAC/B,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,cAAc;IAClE,IAAI,EAAE,2BAA2B,CAAC;IAClC,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC5D,IAAI,EAAE,qBAAqB,CAAC;IAC5B,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC3D,IAAI,EAAE,oBAAoB,CAAC;IAC3B,6BAA6B;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC9D,IAAI,EAAE,gBAAgB,CAAC;IACvB,qCAAqC;IACrC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GACnB,wBAAwB,GACxB,2BAA2B,GAC3B,qBAAqB,GACrB,oBAAoB,GACpB,uBAAuB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAe;IAC3B,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAM;IAE7C;;OAEG;IACH,GAAG,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAIjC;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAI3B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC;IAI7B;;OAEG;IACH,OAAO,CAAC,CAAC,SAAS,cAAc,EAAE,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE;QAAC,IAAI,EAAE,CAAC,CAAA;KAAC,CAAC,CAAC;CAGjF;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC7B,YAAY,UAAU,EACtB,UAAU,uBAAuB,KAC/B,MAeF,CAAC"}

package/dist/analysis_context.js

@@ -1,138 +0,0 @@
-/**
- * Diagnostic collection for source analysis.
- *
- * Provides structured error/warning collection during TypeScript and Svelte
- * analysis, replacing silent catch blocks with actionable diagnostics.
- *
- * ## Error Handling Contract
- *
- * Analysis functions follow a two-tier error model:
- *
- * **Accumulated (non-fatal)** - Collected in `AnalysisContext`, analysis continues:
- * - Type resolution failures (complex generics, circular refs)
- * - Missing or unparseable JSDoc
- * - Individual member/prop extraction failures
- * - The return value is still valid but may have partial data
- *
- * **Thrown (fatal)** - Analysis cannot continue for this file:
- * - File not found or unreadable
- * - Syntax errors preventing parsing
- * - svelte2tsx transformation failures
- * - Svelte version incompatibility
- *
- * ## Usage Pattern
- *
- * ```ts
- * const ctx = new AnalysisContext();
- * const results = files.map(f => {
- *   try {
- *     return library_analyze_module(f, program, options, ctx);
- *   } catch (e) {
- *     // Fatal error - log and skip this file
- *     console.error(`Failed to analyze ${f.id}: ${e}`);
- *     return null;
- *   }
- * });
- *
- * // Results are valid even with accumulated errors
- * // Check ctx for diagnostics to display to user
- * if (ctx.has_errors()) {
- *   for (const err of ctx.errors()) {
- *     console.error(format_diagnostic(err));
- *   }
- * }
- * ```
- *
- * @example
- * ```ts
- * const ctx = new AnalysisContext();
- * // ... analysis functions add diagnostics via ctx.add(...)
- * if (ctx.has_errors()) {
- *   for (const err of ctx.errors()) {
- *     console.error(`${err.file}:${err.line}: ${err.message}`);
- *   }
- * }
- * ```
- *
- * @module
- */
-/**
- * Context for collecting diagnostics during source analysis.
- *
- * Thread an instance through analysis functions to collect errors and warnings
- * without halting analysis. After analysis completes, check `has_errors()` and
- * report collected diagnostics.
- *
- * @example
- * ```ts
- * const ctx = new AnalysisContext();
- * ts_analyze_module_exports(source_file, checker, options, ctx);
- * if (ctx.has_errors()) {
- *   console.error('Analysis completed with errors:');
- *   for (const d of ctx.errors()) {
- *     console.error(format_diagnostic(d));
- *   }
- * }
- * ```
- */
-export class AnalysisContext {
-    diagnostics = [];
-    /**
-     * Add a `Diagnostic` to the collection.
-     */
-    add(diagnostic) {
-        this.diagnostics.push(diagnostic);
-    }
-    /**
-     * Check if any errors were collected.
-     */
-    has_errors() {
-        return this.diagnostics.some((d) => d.severity === 'error');
-    }
-    /**
-     * Check if any warnings were collected.
-     */
-    has_warnings() {
-        return this.diagnostics.some((d) => d.severity === 'warning');
-    }
-    /**
-     * Get all error diagnostics.
-     */
-    errors() {
-        return this.diagnostics.filter((d) => d.severity === 'error');
-    }
-    /**
-     * Get all warning diagnostics.
-     */
-    warnings() {
-        return this.diagnostics.filter((d) => d.severity === 'warning');
-    }
-    /**
-     * Get diagnostics of a specific `DiagnosticKind`.
-     */
-    by_kind(kind) {
-        return this.diagnostics.filter((d) => d.kind === kind);
-    }
-}
-/**
- * Format a diagnostic for display.
- *
- * @param diagnostic - the diagnostic to format
- * @param options - formatting options
- * @returns formatted string like './file.ts:10:5: error: message'
- */
-export const format_diagnostic = (diagnostic, options) => {
-    const prefix = options?.prefix ?? './';
-    const strip_base = options?.strip_base;
-    let file = diagnostic.file;
-    if (strip_base && file.startsWith(strip_base)) {
-        file = file.slice(strip_base.length);
-        // Remove leading slash if present
-        if (file.startsWith('/'))
-            file = file.slice(1);
-    }
-    const { line, column, severity, message } = diagnostic;
-    const location = line !== null ? (column !== null ? `${line}:${column}` : `${line}`) : '';
-    const file_part = location ? `${prefix}${file}:${location}` : `${prefix}${file}`;
-    return `${file_part}: ${severity}: ${message}`;
-};

package/dist/library_analysis.d.ts

@@ -1,112 +0,0 @@
-/**
- * Library source analysis - unified entry point and shared types.
- *
- * Provides a single function for analyzing TypeScript and Svelte source files,
- * dispatching to the appropriate domain-specific analyzer.
- *
- * This module also exports shared types used by both analyzers:
- * - `DeclarationAnalysis` - A declaration with its nodocs flag
- * - `ReExportInfo` - Information about a same-name re-export
- * - `ModuleAnalysis` - Result of analyzing a module (unified structure)
- *
- * @example
- * ```ts
- * import {library_analyze_module} from './library_analysis.js';
- * import {ts_create_program} from './ts_helpers.js';
- * import {module_create_source_options} from './module_helpers.js';
- * import {AnalysisContext} from './analysis_context.js';
- *
- * const {program} = ts_create_program({root: './my-project'});
- * const ctx = new AnalysisContext();
- * const options = module_create_source_options('/my-project');
- *
- * const result = library_analyze_module(
- *   {id: '/my-project/src/lib/file.ts', content: '...'},
- *   program,
- *   options,
- *   ctx,
- * );
- *
- * if (result) {
- *   // Filter out @nodocs declarations
- *   const declarations = result.declarations
- *     .filter(d => !d.nodocs)
- *     .map(d => d.declaration);
- *   console.log('Declarations:', declarations);
- * }
- * ```
- *
- * @see `ts_helpers.ts` for TypeScript-specific analysis
- * @see `svelte_helpers.ts` for Svelte component analysis
- * @see `module_helpers.ts` for path utilities and `SourceFileInfo`
- *
- * @module
- */
-import ts from 'typescript';
-import type { Logger } from '@fuzdev/fuz_util/log.js';
-import type { DeclarationJson } from '@fuzdev/fuz_util/source_json.js';
-import { type SourceFileInfo, type ModuleSourceOptions } from './module_helpers.js';
-import type { AnalysisContext } from './analysis_context.js';
-/**
- * Result of analyzing a single declaration.
- * Used by both TypeScript and Svelte analyzers for uniform handling.
- */
-export interface DeclarationAnalysis {
-    /** The analyzed declaration metadata. */
-    declaration: DeclarationJson;
-    /** Whether the declaration is marked `@nodocs` (should be excluded from documentation). */
-    nodocs: boolean;
-}
-/**
- * Information about a same-name re-export.
- * Used for post-processing to build `also_exported_from` arrays.
- */
-export interface ReExportInfo {
-    /** Name of the re-exported declaration. */
-    name: string;
-    /** Module path (relative to src/lib) where the declaration is originally declared. */
-    original_module: string;
-}
-/**
- * Result of analyzing a module (TypeScript or Svelte).
- * Both analyzers return this same structure for uniform handling.
- */
-export interface ModuleAnalysis {
-    /** Module path relative to source root. */
-    path: string;
-    /** Module-level documentation comment. */
-    module_comment?: string;
-    /** All declarations with nodocs flags - consumer filters based on policy. */
-    declarations: Array<DeclarationAnalysis>;
-    /** 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>;
-    /** Star exports (`export * from './module'`). Empty for Svelte components. */
-    star_exports: Array<string>;
-    /** Re-exports discovered during analysis. Empty for Svelte components. */
-    re_exports: Array<ReExportInfo>;
-}
-/**
- * Analyze a source file and extract module metadata.
- *
- * Unified entry point that dispatches to the appropriate analyzer based on file type:
- * - TypeScript/JS files → `ts_analyze_module`
- * - Svelte components → `svelte_analyze_module`
- *
- * Returns raw analysis data including `nodocs` flags on declarations.
- * Consumer is responsible for filtering based on their policy.
- *
- * This function can be called incrementally - consumers may cache results and
- * only re-analyze changed files. The TypeScript program should include all files
- * for accurate type resolution, but only changed files need re-analysis.
- *
- * @param source_file - the source file info with content and optional dependency data
- * @param program - TypeScript program (used for type checking and source file lookup)
- * @param options - module source options for path extraction
- * @param ctx - analysis context for collecting diagnostics
- * @param log - optional logger for warnings
- * @returns module metadata and re-exports, or undefined if source file not found in program
- */
-export declare const library_analyze_module: (source_file: SourceFileInfo, program: ts.Program, options: ModuleSourceOptions, ctx: AnalysisContext, log?: Logger) => ModuleAnalysis | undefined;
-//# sourceMappingURL=library_analysis.d.ts.map

package/dist/library_analysis.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"library_analysis.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAIrE,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,mBAAmB,EAExB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,yCAAyC;IACzC,WAAW,EAAE,eAAe,CAAC;IAC7B,2FAA2F;IAC3F,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,eAAe,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,YAAY,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACzC,8EAA8E;IAC9E,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,gFAAgF;IAChF,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,8EAA8E;IAC9E,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,UAAU,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,GAClC,aAAa,cAAc,EAC3B,SAAS,EAAE,CAAC,OAAO,EACnB,SAAS,mBAAmB,EAC5B,KAAK,eAAe,EACpB,MAAM,MAAM,KACV,cAAc,GAAG,SAuCnB,CAAC"}