@fuzdev/fuz_ui 0.175.0 → 0.176.1

package/dist/svelte_helpers.d.ts

@@ -10,28 +10,83 @@
  * Workflow: Transform Svelte to TypeScript via svelte2tsx, parse the transformed
  * TypeScript with the TS Compiler API, extract component-level JSDoc from original source.
  *
+ * **Svelte 5 only**: The svelte2tsx output format changed significantly between versions.
+ * This module requires Svelte 5+ and will throw a clear error if an older version is detected.
+ * There is no Svelte 4 compatibility layer.
+ *
  * All functions are prefixed with `svelte_` for clarity.
+ *
+ * @module
  */
 import ts from 'typescript';
+import { TraceMap } from '@jridgewell/trace-mapping';
 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';
+import type { ModuleAnalysis } from './library_analysis.js';
+/** Result of analyzing a Svelte file. */
+export interface SvelteFileAnalysis {
+    /** The component declaration metadata. */
+    declaration: DeclarationJson;
+    /** Module-level documentation comment, if present. */
+    module_comment?: string;
+}
 /**
- * Analyze a Svelte component from its svelte2tsx transformation.
+ * Analyze a Svelte component file and extract module metadata.
+ *
+ * Wraps `svelte_analyze_file` and adds dependency information
+ * from the source file info if available.
+ *
+ * This is a high-level function suitable for building documentation or library metadata.
+ * For lower-level analysis, use `svelte_analyze_file` directly.
+ *
+ * Returns raw analysis data matching `ModuleAnalysis` structure.
+ * Consumer decides filtering policy (Svelte components are never nodocs).
+ *
+ * @param source_file The source file info (from Gro filer, file system, or other source)
+ * @param module_path The module path (relative to source root)
+ * @param checker TypeScript type checker
+ * @param options Module source options for path extraction
+ * @param ctx Analysis context for collecting diagnostics
+ * @returns Module analysis matching ModuleAnalysis structure
  */
-export declare const svelte_analyze_component: (ts_code: string, source_file: ts.SourceFile, checker: ts.TypeChecker, component_name: string) => DeclarationJson;
+export declare const svelte_analyze_module: (source_file: SourceFileInfo, module_path: string, checker: ts.TypeChecker, options: ModuleSourceOptions, ctx: AnalysisContext) => ModuleAnalysis;
 /**
- * Analyze a Svelte component file from disk.
+ * Analyze a Svelte component file.
  *
  * This is a high-level function that handles the complete workflow:
- * 1. Read the Svelte source from disk
- * 2. Transform to TypeScript via svelte2tsx
- * 3. Extract component metadata (props, documentation)
+ * 1. Transform Svelte source to TypeScript via svelte2tsx
+ * 2. Extract component metadata (props, documentation)
+ * 3. Extract module-level documentation
  *
  * Suitable for use in documentation generators, build tools, and analysis.
  *
- * @param file_path Absolute path to the .svelte file
- * @param module_path Module path relative to src/lib (e.g., 'Alert.svelte')
+ * @param source_file Source file info with path and content
+ * @param module_path Module path relative to source root (e.g., 'Alert.svelte')
  * @param checker TypeScript type checker for type resolution
- * @returns Complete declaration metadata for the component
+ * @param ctx Analysis context for collecting diagnostics
+ * @returns Component declaration and optional module-level comment
+ */
+export declare const svelte_analyze_file: (source_file: SourceFileInfo, module_path: string, checker: ts.TypeChecker, ctx: AnalysisContext) => SvelteFileAnalysis;
+/**
+ * Analyze a Svelte component from its svelte2tsx transformation.
+ */
+export declare const svelte_analyze_component: (ts_code: string, source_file: ts.SourceFile, checker: ts.TypeChecker, component_name: string, file_path: string, source_map: TraceMap | null, ctx: AnalysisContext) => DeclarationJson;
+/**
+ * Extract the content of the main `<script>` tag from Svelte source.
+ *
+ * Matches `<script>` or `<script lang="ts">` but not `<script module>`.
+ * Returns undefined if no matching script tag is found.
+ */
+export declare const svelte_extract_script_content: (svelte_source: string) => string | undefined;
+/**
+ * Extract module-level comment from Svelte script content.
+ *
+ * Requires `@module` tag to identify module comments. The tag line is stripped
+ * from the output.
+ *
+ * @param script_content - The content of the `<script>` tag.
+ * @returns The cleaned module comment text, or undefined if none found.
  */
-export declare const svelte_analyze_file: (file_path: string, module_path: string, checker: ts.TypeChecker) => DeclarationJson;
+export declare const svelte_extract_module_comment: (script_content: string) => string | undefined;
 //# sourceMappingURL=svelte_helpers.d.ts.map

package/dist/svelte_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"svelte_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B,OAAO,KAAK,EAAC,eAAe,EAAoB,MAAM,iCAAiC,CAAC;AAKxF;;GAEG;AACH,eAAO,MAAM,wBAAwB,GACpC,SAAS,MAAM,EACf,aAAa,EAAE,CAAC,UAAU,EAC1B,SAAS,EAAE,CAAC,WAAW,EACvB,gBAAgB,MAAM,KACpB,eAqCF,CAAC;AAkMF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC/B,WAAW,MAAM,EACjB,aAAa,MAAM,EACnB,SAAS,EAAE,CAAC,WAAW,KACrB,eAqBF,CAAC"}
+{"version":3,"file":"svelte_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAC,QAAQ,EAAsB,MAAM,2BAA2B,CAAC;AAExE,OAAO,KAAK,EAAC,eAAe,EAAoB,MAAM,iCAAiC,CAAC;AAIxF,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,mBAAmB,EAGxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,uBAAuB,CAAC;AAqB1D,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IAClC,0CAA0C;IAC1C,WAAW,EAAE,eAAe,CAAC;IAC7B,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,GACjC,aAAa,cAAc,EAC3B,aAAa,MAAM,EACnB,SAAS,EAAE,CAAC,WAAW,EACvB,SAAS,mBAAmB,EAC5B,KAAK,eAAe,KAClB,cAiBF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,GAC/B,aAAa,cAAc,EAC3B,aAAa,MAAM,EACnB,SAAS,EAAE,CAAC,WAAW,EACvB,KAAK,eAAe,KAClB,kBAqDF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB,GACpC,SAAS,MAAM,EACf,aAAa,EAAE,CAAC,UAAU,EAC1B,SAAS,EAAE,CAAC,WAAW,EACvB,gBAAgB,MAAM,EACtB,WAAW,MAAM,EACjB,YAAY,QAAQ,GAAG,IAAI,EAC3B,KAAK,eAAe,KAClB,eA0CF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAI,eAAe,MAAM,KAAG,MAAM,GAAG,SAM9E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GAAI,gBAAgB,MAAM,KAAG,MAAM,GAAG,SAU/E,CAAC"}

package/dist/svelte_helpers.js

@@ -10,17 +10,124 @@
  * Workflow: Transform Svelte to TypeScript via svelte2tsx, parse the transformed
  * TypeScript with the TS Compiler API, extract component-level JSDoc from original source.
  *
+ * **Svelte 5 only**: The svelte2tsx output format changed significantly between versions.
+ * This module requires Svelte 5+ and will throw a clear error if an older version is detected.
+ * There is no Svelte 4 compatibility layer.
+ *
  * All functions are prefixed with `svelte_` for clarity.
+ *
+ * @module
  */
 import ts from 'typescript';
-import { readFileSync } from 'node:fs';
 import { svelte2tsx } from 'svelte2tsx';
+import { TraceMap, originalPositionFor } from '@jridgewell/trace-mapping';
+import { VERSION } from 'svelte/compiler';
 import { tsdoc_parse, tsdoc_apply_to_declaration } from './tsdoc_helpers.js';
-import { module_get_component_name } from './module_helpers.js';
+import { ts_extract_module_comment } from './ts_helpers.js';
+import { module_get_component_name, module_extract_dependencies, } from './module_helpers.js';
+/** Guard to ensure version check runs only once. */
+let svelte_version_checked = false;
+/**
+ * Assert Svelte 5+ is installed (lazy, runs once on first use).
+ * Throws a clear error message if an older version is detected.
+ */
+const svelte_assert_version = () => {
+    if (svelte_version_checked)
+        return;
+    svelte_version_checked = true;
+    const [major] = VERSION.split('.');
+    if (parseInt(major, 10) < 5) {
+        throw new Error(`Svelte ${VERSION} detected but Svelte 5+ is required for source analysis. ` +
+            `The svelte2tsx output format changed significantly between versions.`);
+    }
+};
+/**
+ * Analyze a Svelte component file and extract module metadata.
+ *
+ * Wraps `svelte_analyze_file` and adds dependency information
+ * from the source file info if available.
+ *
+ * This is a high-level function suitable for building documentation or library metadata.
+ * For lower-level analysis, use `svelte_analyze_file` directly.
+ *
+ * Returns raw analysis data matching `ModuleAnalysis` structure.
+ * Consumer decides filtering policy (Svelte components are never nodocs).
+ *
+ * @param source_file The source file info (from Gro filer, file system, or other source)
+ * @param module_path The module path (relative to source root)
+ * @param checker TypeScript type checker
+ * @param options Module source options for path extraction
+ * @param ctx Analysis context for collecting diagnostics
+ * @returns Module analysis matching ModuleAnalysis structure
+ */
+export const svelte_analyze_module = (source_file, module_path, checker, options, ctx) => {
+    // Use the existing helper for core analysis
+    const { declaration, module_comment } = svelte_analyze_file(source_file, module_path, checker, ctx);
+    // Extract dependencies and dependents if provided
+    const { dependencies, dependents } = module_extract_dependencies(source_file, options);
+    return {
+        path: module_path,
+        module_comment,
+        // Wrap declaration in DeclarationAnalysis format (Svelte components are never nodocs)
+        declarations: [{ declaration, nodocs: false }],
+        dependencies,
+        dependents,
+        star_exports: [],
+        re_exports: [],
+    };
+};
+/**
+ * Analyze a Svelte component file.
+ *
+ * This is a high-level function that handles the complete workflow:
+ * 1. Transform Svelte source to TypeScript via svelte2tsx
+ * 2. Extract component metadata (props, documentation)
+ * 3. Extract module-level documentation
+ *
+ * Suitable for use in documentation generators, build tools, and analysis.
+ *
+ * @param source_file Source file info with path and content
+ * @param module_path Module path relative to source root (e.g., 'Alert.svelte')
+ * @param checker TypeScript type checker for type resolution
+ * @param ctx Analysis context for collecting diagnostics
+ * @returns Component declaration and optional module-level comment
+ */
+export const svelte_analyze_file = (source_file, module_path, checker, ctx) => {
+    svelte_assert_version();
+    const svelte_source = source_file.content;
+    // Check if component uses TypeScript
+    const is_ts_file = svelte_source.includes('lang="ts"');
+    // Transform Svelte to TS
+    const ts_result = svelte2tsx(svelte_source, {
+        filename: source_file.id,
+        isTsFile: is_ts_file,
+        emitOnTemplateError: true, // Handle malformed templates gracefully
+    });
+    // Create source map for position mapping back to original .svelte file
+    let source_map = null;
+    try {
+        // svelte2tsx returns a magic-string SourceMap which is compatible with TraceMap
+        // Cast to unknown first since the types don't perfectly align but are compatible
+        source_map = new TraceMap(ts_result.map);
+    }
+    catch (_error) {
+        // If source map parsing fails, diagnostics will use virtual file positions
+    }
+    // Get component name from filename
+    const component_name = module_get_component_name(module_path);
+    // Create a temporary source file from the original Svelte content for JSDoc extraction
+    const temp_source = ts.createSourceFile(source_file.id, svelte_source, ts.ScriptTarget.Latest, true);
+    // Analyze the component using the existing lower-level function
+    const declaration = svelte_analyze_component(ts_result.code, temp_source, checker, component_name, module_path, source_map, ctx);
+    // Extract module-level comment from the script content
+    const script_content = svelte_extract_script_content(svelte_source);
+    const module_comment = script_content ? svelte_extract_module_comment(script_content) : undefined;
+    return { declaration, module_comment };
+};
 /**
  * Analyze a Svelte component from its svelte2tsx transformation.
  */
-export const svelte_analyze_component = (ts_code, source_file, checker, component_name) => {
+export const svelte_analyze_component = (ts_code, source_file, checker, component_name, file_path, source_map, ctx) => {
     const result = {
         name: component_name,
         kind: 'component',
@@ -33,7 +140,7 @@ export const svelte_analyze_component = (ts_code, source_file, checker, componen
         const component_tsdoc = svelte_extract_component_tsdoc(virtual_source);
         tsdoc_apply_to_declaration(result, component_tsdoc);
         // Extract props from svelte2tsx transformed output
-        const props = svelte_extract_props(virtual_source, checker);
+        const props = svelte_extract_props(virtual_source, checker, component_name, file_path, source_map, ctx);
         if (props.length > 0) {
             result.props = props;
         }
@@ -42,12 +149,37 @@ export const svelte_analyze_component = (ts_code, source_file, checker, componen
         result.source_line = start_pos.line + 1;
     }
     catch (error) {
-        // If analysis fails, return basic component info
-        // eslint-disable-next-line no-console
-        console.error(`Error analyzing Svelte component ${component_name}:`, error);
+        throw new Error(`Failed to analyze Svelte component ${component_name}`, { cause: error });
     }
     return result;
 };
+/**
+ * Extract the content of the main `<script>` tag from Svelte source.
+ *
+ * Matches `<script>` or `<script lang="ts">` but not `<script module>`.
+ * Returns undefined if no matching script tag is found.
+ */
+export const svelte_extract_script_content = (svelte_source) => {
+    // Match <script> or <script lang="ts"> but not <script module>
+    // Captures the content between opening and closing tags
+    const script_regex = /<script(?:\s+lang=["']ts["'])?(?:\s*)>([^]*?)<\/script>/i;
+    const match = script_regex.exec(svelte_source);
+    return match?.[1];
+};
+/**
+ * Extract module-level comment from Svelte script content.
+ *
+ * Requires `@module` tag to identify module comments. The tag line is stripped
+ * from the output.
+ *
+ * @param script_content - The content of the `<script>` tag.
+ * @returns The cleaned module comment text, or undefined if none found.
+ */
+export const svelte_extract_module_comment = (script_content) => {
+    // Parse the script content as TypeScript and reuse the shared extraction logic
+    const source_file = ts.createSourceFile('script.ts', script_content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    return ts_extract_module_comment(source_file);
+};
 /**
  * Extract component-level TSDoc comment from svelte2tsx transformed output.
  *
@@ -81,9 +213,9 @@ const svelte_extract_component_tsdoc = (source_file) => {
     return found_tsdoc;
 };
 /**
- * Helper to extract prop info from a property signature member.
+ * Extract prop info from a property signature member.
  */
-const svelte_extract_prop_from_member = (member, source_file, checker) => {
+const svelte_extract_prop_from_member = (member, source_file, checker, component_name, file_path, source_map, ctx) => {
     if (!ts.isIdentifier(member.name))
         return undefined;
     const prop_name = member.name.text;
@@ -99,8 +231,30 @@ const svelte_extract_prop_from_member = (member, source_file, checker) => {
             const prop_type = checker.getTypeAtLocation(member);
             type_string = checker.typeToString(prop_type);
         }
-        catch {
-            // Fallback to 'any'
+        catch (err) {
+            // Fallback to 'any' but report diagnostic with mapped position
+            const { line, character } = source_file.getLineAndCharacterOfPosition(member.getStart());
+            // Map virtual position back to original .svelte file if source map available
+            let final_line = line + 1;
+            let final_column = character + 1;
+            if (source_map) {
+                const original = originalPositionFor(source_map, { line: line + 1, column: character });
+                // When line is found, column is guaranteed to be present (same mapping entry)
+                if (original.line !== null) {
+                    final_line = original.line;
+                    final_column = original.column + 1;
+                }
+            }
+            ctx.add({
+                kind: 'svelte_prop_failed',
+                file: file_path,
+                line: final_line,
+                column: final_column,
+                message: `Failed to resolve type for prop "${prop_name}" in ${component_name}, falling back to 'any': ${err instanceof Error ? err.message : String(err)}`,
+                severity: 'warning',
+                component_name,
+                prop_name,
+            });
         }
     }
     // Extract TSDoc description
@@ -154,12 +308,12 @@ const svelte_extract_bindable_props = (virtual_source) => {
  *
  * @mutates props - adds extracted prop info to the array
  */
-const svelte_extract_props_from_type = (type_node, virtual_source, checker, bindable_props, props) => {
+const svelte_extract_props_from_type = (type_node, virtual_source, checker, bindable_props, props, component_name, file_path, source_map, ctx) => {
     if (ts.isTypeLiteralNode(type_node)) {
         // Handle direct type literal: { prop1: type1, prop2: type2 }
         for (const member of type_node.members) {
             if (ts.isPropertySignature(member)) {
-                const prop_info = svelte_extract_prop_from_member(member, virtual_source, checker);
+                const prop_info = svelte_extract_prop_from_member(member, virtual_source, checker, component_name, file_path, source_map, ctx);
                 if (prop_info) {
                     // Mark as bindable if found in bindings
                     if (bindable_props.has(prop_info.name)) {
@@ -173,7 +327,7 @@ const svelte_extract_props_from_type = (type_node, virtual_source, checker, bind
     else if (ts.isIntersectionTypeNode(type_node)) {
         // Handle intersection type: TypeA & TypeB & { prop: type }
         for (const type_part of type_node.types) {
-            svelte_extract_props_from_type(type_part, virtual_source, checker, bindable_props, props);
+            svelte_extract_props_from_type(type_part, virtual_source, checker, bindable_props, props, component_name, file_path, source_map, ctx);
         }
     }
     // Skip other type references like SvelteHTMLElements['details'] since we can't easily resolve them
@@ -184,20 +338,20 @@ const svelte_extract_props_from_type = (type_node, virtual_source, checker, bind
  * svelte2tsx generates a `$$ComponentProps` type alias containing the component props.
  * This function extracts prop metadata from that type.
  */
-const svelte_extract_props = (virtual_source, checker) => {
+const svelte_extract_props = (virtual_source, checker, component_name, file_path, source_map, ctx) => {
     const props = [];
     const bindable_props = svelte_extract_bindable_props(virtual_source);
     // Look for $$ComponentProps type alias or Props interface
     ts.forEachChild(virtual_source, (node) => {
         // Check for type alias ($$ComponentProps)
         if (ts.isTypeAliasDeclaration(node) && node.name.text === '$$ComponentProps') {
-            svelte_extract_props_from_type(node.type, virtual_source, checker, bindable_props, props);
+            svelte_extract_props_from_type(node.type, virtual_source, checker, bindable_props, props, component_name, file_path, source_map, ctx);
         }
         // Also check for Props interface (fallback/older format)
         else if (ts.isInterfaceDeclaration(node) && node.name.text === 'Props') {
             for (const member of node.members) {
                 if (ts.isPropertySignature(member)) {
-                    const prop_info = svelte_extract_prop_from_member(member, virtual_source, checker);
+                    const prop_info = svelte_extract_prop_from_member(member, virtual_source, checker, component_name, file_path, source_map, ctx);
                     if (prop_info) {
                         // Mark as bindable if found in bindings
                         if (bindable_props.has(prop_info.name)) {
@@ -211,35 +365,3 @@ const svelte_extract_props = (virtual_source, checker) => {
     });
     return props;
 };
-/**
- * Analyze a Svelte component file from disk.
- *
- * This is a high-level function that handles the complete workflow:
- * 1. Read the Svelte source from disk
- * 2. Transform to TypeScript via svelte2tsx
- * 3. Extract component metadata (props, documentation)
- *
- * Suitable for use in documentation generators, build tools, and analysis.
- *
- * @param file_path Absolute path to the .svelte file
- * @param module_path Module path relative to src/lib (e.g., 'Alert.svelte')
- * @param checker TypeScript type checker for type resolution
- * @returns Complete declaration metadata for the component
- */
-export const svelte_analyze_file = (file_path, module_path, checker) => {
-    const svelte_source = readFileSync(file_path, 'utf-8');
-    // Check if component uses TypeScript
-    const is_ts_file = svelte_source.includes('lang="ts"');
-    // Transform Svelte to TS
-    const ts_result = svelte2tsx(svelte_source, {
-        filename: file_path,
-        isTsFile: is_ts_file,
-        emitOnTemplateError: true, // Handle malformed templates gracefully
-    });
-    // Get component name from filename
-    const component_name = module_get_component_name(module_path);
-    // Create a temporary source file from the original Svelte content for JSDoc extraction
-    const temp_source = ts.createSourceFile(file_path, svelte_source, ts.ScriptTarget.Latest, true);
-    // Analyze the component using the existing lower-level function
-    return svelte_analyze_component(ts_result.code, temp_source, checker, component_name);
-};

package/dist/ts_helpers.d.ts

@@ -2,48 +2,94 @@
  * TypeScript compiler API helpers for extracting metadata from source code.
  *
  * All functions are prefixed with `ts_` for clarity.
+ *
+ * @module
  */
 import ts from 'typescript';
 import type { DeclarationJson, DeclarationKind } from '@fuzdev/fuz_util/source_json.js';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
 import { tsdoc_parse } from './tsdoc_helpers.js';
+import { type ModuleSourceOptions, type SourceFileInfo } from './module_helpers.js';
+import type { AnalysisContext } from './analysis_context.js';
+import type { DeclarationAnalysis, ReExportInfo, ModuleAnalysis } from './library_analysis.js';
 /**
- * Infer declaration kind from symbol and node.
+ * Options for creating a TypeScript program.
  */
-export declare const ts_infer_declaration_kind: (symbol: ts.Symbol, node: ts.Node) => DeclarationKind;
+export interface TsProgramOptions {
+    /** Project root directory. @default './' */
+    root?: string;
+    /** Path to tsconfig.json (relative to root). @default 'tsconfig.json' */
+    tsconfig?: string;
+    /** Override compiler options. */
+    compiler_options?: ts.CompilerOptions;
+}
 /**
- * Extract function/method information including parameters
- * with descriptions and default values.
- *
- * @mutates declaration - adds type_signature, return_type, return_description, throws, since, parameters, generic_params
+ * Result of creating a TypeScript program.
  */
-export declare const ts_extract_function_info: (node: ts.Node, symbol: ts.Symbol, checker: ts.TypeChecker, declaration: DeclarationJson, tsdoc: ReturnType<typeof tsdoc_parse>) => void;
+export interface TsProgram {
+    program: ts.Program;
+    checker: ts.TypeChecker;
+}
 /**
- * Extract type/interface information with rich property metadata.
- *
- * @mutates declaration - adds type_signature, generic_params, extends, properties
+ * Result of analyzing a module's exports.
  */
-export declare const ts_extract_type_info: (node: ts.Node, _symbol: ts.Symbol, checker: ts.TypeChecker, declaration: DeclarationJson) => void;
+export interface ModuleExportsAnalysis {
+    /** Module-level documentation comment. */
+    module_comment?: string;
+    /** All exported declarations with nodocs flags - consumer filters based on policy. */
+    declarations: Array<DeclarationAnalysis>;
+    /** Same-name re-exports (for building also_exported_from in post-processing). */
+    re_exports: Array<ReExportInfo>;
+    /** Star exports (`export * from './module'`) - module paths that are fully re-exported. */
+    star_exports: Array<string>;
+}
 /**
- * Extract class information with rich member metadata.
+ * Create TypeScript program for analysis.
  *
- * @mutates declaration - adds extends, implements, generic_params, members
+ * @param options Configuration options for program creation
+ * @param log Optional logger for info messages
+ * @returns The program and type checker
+ * @throws Error if tsconfig.json is not found
  */
-export declare const ts_extract_class_info: (node: ts.Node, _symbol: ts.Symbol, checker: ts.TypeChecker, declaration: DeclarationJson) => void;
+export declare const ts_create_program: (options?: TsProgramOptions, log?: Logger) => TsProgram;
 /**
- * Extract variable information.
+ * Analyze a TypeScript file and extract module metadata.
  *
- * @mutates declaration - adds type_signature
+ * Wraps `ts_analyze_module_exports` and adds dependency information
+ * from the source file info if available.
+ *
+ * This is a high-level function suitable for building documentation or library metadata.
+ * For lower-level analysis, use `ts_analyze_module_exports` directly.
+ *
+ * @param source_file_info The source file info (from Gro filer, file system, or other source)
+ * @param ts_source_file TypeScript source file from the program
+ * @param module_path The module path (relative to source root)
+ * @param checker TypeScript type checker
+ * @param options Module source options for path extraction
+ * @param ctx Analysis context for collecting diagnostics
+ * @returns Module metadata and re-export information
  */
-export declare const ts_extract_variable_info: (node: ts.Node, symbol: ts.Symbol, checker: ts.TypeChecker, declaration: DeclarationJson) => void;
+export declare const ts_analyze_module: (source_file_info: SourceFileInfo, ts_source_file: ts.SourceFile, module_path: string, checker: ts.TypeChecker, options: ModuleSourceOptions, ctx: AnalysisContext) => ModuleAnalysis;
 /**
- * Result of analyzing a single declaration.
+ * Analyze all exports from a TypeScript source file.
+ *
+ * Extracts the module-level comment and all exported declarations with
+ * complete metadata. Handles re-exports by:
+ * - Same-name re-exports: tracked in `re_exports` for `also_exported_from` building
+ * - Renamed re-exports: included as new declarations with `alias_of` metadata
+ * - Star exports (`export * from`): tracked in `star_exports` for namespace-level info
+ *
+ * This is a mid-level function (above `ts_extract_*`, below `library_gen`)
+ * suitable for building documentation, API explorers, or analysis tools.
+ * For standard SvelteKit library layouts, use `module_create_source_options(process.cwd())`.
+ *
+ * @param source_file The TypeScript source file to analyze
+ * @param checker The TypeScript type checker
+ * @param options Module source options for path extraction in re-exports
+ * @param ctx Analysis context for collecting diagnostics
+ * @returns Module comment, declarations, re-exports, and star exports
  */
-export interface TsDeclarationAnalysis {
-    /** The analyzed declaration metadata. */
-    declaration: DeclarationJson;
-    /** Whether the declaration is marked @nodocs (should be excluded from documentation). */
-    nodocs: boolean;
-}
+export declare const ts_analyze_module_exports: (source_file: ts.SourceFile, checker: ts.TypeChecker, options: ModuleSourceOptions, ctx: AnalysisContext) => ModuleExportsAnalysis;
 /**
  * Analyze a TypeScript symbol and extract rich metadata.
  *
@@ -54,57 +100,82 @@ export interface TsDeclarationAnalysis {
  * @param symbol The TypeScript symbol to analyze
  * @param source_file The source file containing the symbol
  * @param checker The TypeScript type checker
+ * @param ctx Optional analysis context for collecting diagnostics
  * @returns Complete declaration metadata including docs, types, and parameters, plus nodocs flag
  */
-export declare const ts_analyze_declaration: (symbol: ts.Symbol, source_file: ts.SourceFile, checker: ts.TypeChecker) => TsDeclarationAnalysis;
+export declare const ts_analyze_declaration: (symbol: ts.Symbol, source_file: ts.SourceFile, checker: ts.TypeChecker, ctx: AnalysisContext) => DeclarationAnalysis;
 /**
- * Information about a same-name re-export.
- * Used for post-processing to build `also_exported_from` arrays.
+ * Extract module-level comment.
+ *
+ * Requires `@module` tag to identify module comments. The tag line is stripped
+ * from the output. Supports optional module renaming: `@module custom-name`.
+ *
+ * @see https://typedoc.org/documents/Tags._module.html
  */
-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;
-}
+export declare const ts_extract_module_comment: (source_file: ts.SourceFile) => string | undefined;
 /**
- * Result of analyzing a module's exports.
+ * Infer declaration kind from symbol and node.
+ *
+ * Maps TypeScript constructs to `DeclarationKind`:
+ * - Classes → `'class'`
+ * - Functions (declarations, expressions, arrows) → `'function'`
+ * - Interfaces, type aliases → `'type'`
+ * - Enums (regular and const) → `'type'`
+ * - Variables → `'variable'` (unless function-valued → `'function'`)
  */
-export interface ModuleExportsAnalysis {
-    /** Module-level documentation comment. */
-    module_comment?: string;
-    /** All exported declarations with their metadata (excludes same-name re-exports). */
-    declarations: Array<DeclarationJson>;
-    /** Same-name re-exports (for building also_exported_from in post-processing). */
-    re_exports: Array<ReExportInfo>;
-}
+export declare const ts_infer_declaration_kind: (symbol: ts.Symbol, node: ts.Node) => DeclarationKind;
 /**
- * Analyze all exports from a TypeScript source file.
+ * Extract parameters from a TypeScript signature with TSDoc descriptions and default values.
  *
- * Extracts the module-level comment and all exported declarations with
- * complete metadata. Handles re-exports by:
- * - Same-name re-exports: tracked in `re_exports` for `also_exported_from` building
- * - Renamed re-exports: included as new declarations with `alias_of` metadata
+ * Shared helper for extracting parameter information from both standalone functions
+ * and class methods/constructors.
  *
- * This is a high-level function suitable for building documentation, API explorers, or analysis tools.
+ * @param sig The TypeScript signature to extract parameters from
+ * @param checker TypeScript type checker for type resolution
+ * @param tsdoc_params Map of parameter names to TSDoc descriptions (from tsdoc.params)
+ * @returns Array of parameter info objects
+ */
+export declare const ts_extract_signature_parameters: (sig: ts.Signature, checker: ts.TypeChecker, tsdoc_params: Map<string, string> | undefined) => Array<{
+    name: string;
+    type: string;
+    optional?: boolean;
+    description?: string;
+    default_value?: string;
+}>;
+/**
+ * Extract function/method information including parameters
+ * with descriptions and default values.
  *
- * @param source_file The TypeScript source file to analyze
- * @param checker The TypeScript type checker
- * @returns Module comment, array of analyzed declarations, and re-export information
+ * @internal Use `ts_analyze_declaration` for high-level analysis.
+ * @mutates declaration - adds type_signature, return_type, return_description, throws, since, parameters, generic_params
  */
-export declare const ts_analyze_module_exports: (source_file: ts.SourceFile, checker: ts.TypeChecker) => ModuleExportsAnalysis;
+export declare const ts_extract_function_info: (node: ts.Node, symbol: ts.Symbol, checker: ts.TypeChecker, declaration: DeclarationJson, tsdoc: ReturnType<typeof tsdoc_parse>, ctx: AnalysisContext) => void;
 /**
- * Extract module-level comment.
+ * Extract type/interface information with rich property metadata.
  *
- * Only accepts JSDoc/TSDoc comments (`/** ... *\/`) followed by a blank line to distinguish
- * them from identifier-level comments. This prevents accidentally treating function/class
- * comments as module comments. Module comments can appear after imports.
+ * @internal Use `ts_analyze_declaration` for high-level analysis.
+ * @mutates declaration - adds type_signature, generic_params, extends, properties
  */
-export declare const ts_extract_module_comment: (source_file: ts.SourceFile) => string | undefined;
+export declare const ts_extract_type_info: (node: ts.Node, _symbol: ts.Symbol, checker: ts.TypeChecker, declaration: DeclarationJson, ctx: AnalysisContext) => void;
 /**
- * Create TypeScript program for analysis.
+ * Extract class information with rich member metadata.
+ *
+ * @internal Use `ts_analyze_declaration` for high-level analysis.
+ * @mutates declaration - adds extends, implements, generic_params, members
+ */
+export declare const ts_extract_class_info: (node: ts.Node, _symbol: ts.Symbol, checker: ts.TypeChecker, declaration: DeclarationJson, ctx: AnalysisContext) => void;
+/**
+ * Extract variable information.
+ *
+ * @internal Use `ts_analyze_declaration` for high-level analysis.
+ * @mutates declaration - adds type_signature
+ */
+export declare const ts_extract_variable_info: (node: ts.Node, symbol: ts.Symbol, checker: ts.TypeChecker, declaration: DeclarationJson, ctx: AnalysisContext) => void;
+/**
+ * TypeScript modifier keywords extracted from declarations.
+ *
+ * These are the access modifiers and other keywords that can appear
+ * on class members, interface properties, etc.
  */
-export declare const ts_create_program: (log: {
-    warn: (message: string) => void;
-}) => ts.Program | null;
+export type TsModifier = 'public' | 'private' | 'protected' | 'readonly' | 'static' | 'abstract';
 //# sourceMappingURL=ts_helpers.d.ts.map