@fuzdev/fuz_ui 0.175.0 → 0.176.1

package/dist/module_helpers.d.ts

@@ -5,33 +5,228 @@
  * and import relationships in the package generation system.
  *
  * All functions are prefixed with `module_` for clarity.
+ *
+ * @module
+ */
+/**
+ * Analyzer type for source files.
+ *
+ * - `'typescript'` - TypeScript/JavaScript files analyzed via TypeScript Compiler API
+ * - `'svelte'` - Svelte components analyzed via svelte2tsx + TypeScript Compiler API
+ */
+export type AnalyzerType = 'typescript' | 'svelte';
+/**
+ * File information for source analysis.
+ *
+ * Can be constructed from Gro's Disknode or from plain file system access.
+ * This abstraction enables non-Gro usage while keeping Gro support via adapter.
+ *
+ * Note: `content` is required to keep analysis functions pure (no hidden I/O).
+ * Callers are responsible for reading file content before analysis.
  */
+export interface SourceFileInfo {
+    /** Absolute path to the file. */
+    id: string;
+    /** File content (required - analysis functions don't read from disk). */
+    content: string;
+    /**
+     * Absolute file paths of modules this file imports (optional).
+     * Only include resolved local imports, not node_modules.
+     * Order should be declaration order in source for deterministic output.
+     */
+    dependencies?: ReadonlyArray<string>;
+    /**
+     * Absolute file paths of modules that import this file (optional).
+     * Only include resolved local imports, not node_modules.
+     */
+    dependents?: ReadonlyArray<string>;
+}
 /**
- * Configuration for module source detection.
+ * Configuration for module source detection and path extraction.
  *
- * Allows customizing which paths are considered source modules,
- * useful for projects with non-standard directory structures.
+ * Uses proper path semantics with `project_root` as the base for all path operations.
+ * Paths are matched using `startsWith` rather than substring search, which correctly
+ * handles nested directories without special heuristics.
+ *
+ * @example
+ * const options = module_create_source_options(process.cwd(), {
+ *   source_paths: ['src/lib', 'src/routes'],
+ *   source_root: 'src',
+ * });
  */
 export interface ModuleSourceOptions {
-    /** Source directory paths to include. @default ['/src/lib/'] */
-    source_paths?: Array<string>;
-    /** File extensions to analyze. @default ['.ts', '.js', '.svelte'] */
-    extensions?: Array<string>;
-    /** Patterns to exclude (matched against full path). @default [/\.test\.ts$/] */
-    exclude_patterns?: Array<RegExp>;
+    /**
+     * Absolute path to the project root directory.
+     *
+     * All `source_paths` are relative to this. Typically `process.cwd()` when
+     * running from the project root via Gro, Vite, or other build tools.
+     *
+     * @example '/home/user/my-project'
+     */
+    project_root: string;
+    /**
+     * Source directory paths to include, relative to `project_root`.
+     *
+     * Paths should not have leading or trailing slashes - they are added
+     * internally for correct matching.
+     *
+     * @example ['src/lib'] - single source directory
+     * @example ['src/lib', 'src/routes'] - multiple directories
+     */
+    source_paths: Array<string>;
+    /**
+     * Source root for extracting relative module paths, relative to `project_root`.
+     *
+     * When omitted:
+     * - Single `source_path`: defaults to that path
+     * - Multiple `source_paths`: required (no auto-derivation)
+     *
+     * @example 'src/lib' - module paths like 'foo.ts', 'utils/bar.ts'
+     * @example 'src' - module paths like 'lib/foo.ts', 'routes/page.svelte'
+     */
+    source_root?: string;
+    /** Patterns to exclude (matched against full path). */
+    exclude_patterns: Array<RegExp>;
+    /**
+     * Determine which analyzer to use for a file path.
+     *
+     * Called for files in source directories. Return `'typescript'`, `'svelte'`,
+     * or `null` to skip the file. This is the single source of truth for which
+     * files are analyzable and how to analyze them.
+     *
+     * @default Uses file extension: `.svelte` → svelte, `.ts`/`.js` → typescript
+     *
+     * @example
+     * // Add MDsveX support
+     * get_analyzer: (path) => {
+     *   if (path.endsWith('.svelte') || path.endsWith('.svx')) return 'svelte';
+     *   if (path.endsWith('.ts') || path.endsWith('.js')) return 'typescript';
+     *   return null;
+     * }
+     *
+     * @example
+     * // Include .d.ts files
+     * get_analyzer: (path) => {
+     *   if (path.endsWith('.svelte')) return 'svelte';
+     *   if (path.endsWith('.ts') || path.endsWith('.d.ts') || path.endsWith('.js')) return 'typescript';
+     *   return null;
+     * }
+     */
+    get_analyzer: (path: string) => AnalyzerType | null;
 }
 /**
- * Default options for module source detection.
+ * Default analyzer resolver based on file extension.
+ *
+ * - `.svelte` → `'svelte'`
+ * - `.ts`, `.js` → `'typescript'`
+ * - Other extensions → `null` (skip)
+ */
+export declare const module_get_analyzer_default: (path: string) => AnalyzerType | null;
+/**
+ * Partial source options without `project_root`.
+ *
+ * Use with `module_create_source_options` to build complete options.
+ */
+export type ModuleSourcePartial = Omit<ModuleSourceOptions, 'project_root'>;
+/**
+ * Default partial options for standard SvelteKit library structure.
+ *
+ * Does not include `project_root` - use `module_create_source_options()` to create
+ * complete options with your project root.
+ */
+export declare const MODULE_SOURCE_PARTIAL: ModuleSourcePartial;
+/**
+ * Create complete source options from project root and optional overrides.
+ *
+ * @param project_root Absolute path to project root (typically `process.cwd()`)
+ * @param overrides Optional overrides for default options
+ *
+ * @example
+ * // Standard SvelteKit library
+ * const options = module_create_source_options(process.cwd());
+ *
+ * @example
+ * // Multiple source directories
+ * const options = module_create_source_options(process.cwd(), {
+ *   source_paths: ['src/lib', 'src/routes'],
+ *   source_root: 'src',
+ * });
+ *
+ * @example
+ * // Custom exclusions
+ * const options = module_create_source_options(process.cwd(), {
+ *   exclude_patterns: [/\.test\.ts$/, /\.internal\.ts$/],
+ * });
+ */
+export declare const module_create_source_options: (project_root: string, overrides?: Partial<ModuleSourcePartial>) => ModuleSourceOptions;
+/**
+ * Validate `ModuleSourceOptions` format and consistency.
+ *
+ * Checks:
+ * 1. `project_root` is an absolute path (starts with `/`)
+ * 2. `source_paths` entries don't have leading/trailing slashes
+ * 3. `source_root` (if provided) doesn't have leading/trailing slashes
+ * 4. Multiple `source_paths` require explicit `source_root`
+ * 5. `source_root` is a prefix of all `source_paths`
+ *
+ * @throws Error if validation fails
+ *
+ * @example
+ * // Valid - single source path (source_root auto-derived)
+ * module_validate_source_options({
+ *   project_root: '/home/user/project',
+ *   source_paths: ['src/lib'],
+ *   ...
+ * });
+ *
+ * @example
+ * // Valid - multiple source paths with explicit source_root
+ * module_validate_source_options({
+ *   project_root: '/home/user/project',
+ *   source_paths: ['src/lib', 'src/routes'],
+ *   source_root: 'src',
+ *   ...
+ * });
+ *
+ * @example
+ * // Invalid - multiple source paths without source_root
+ * module_validate_source_options({
+ *   project_root: '/home/user/project',
+ *   source_paths: ['src/lib', 'src/routes'],  // throws
+ *   ...
+ * });
+ */
+export declare const module_validate_source_options: (options: ModuleSourceOptions) => void;
+/**
+ * Get the effective source_root from options.
+ *
+ * Returns `source_root` if provided, otherwise returns `source_paths[0]` for single-path configs.
+ *
+ * @throws Error if source_root is required but not provided (multiple source_paths)
  */
-export declare const MODULE_SOURCE_DEFAULTS: Required<ModuleSourceOptions>;
+export declare const module_get_source_root: (options: ModuleSourceOptions) => string;
 /**
- * Extract module path relative to src/lib from absolute source ID.
+ * Extract module path relative to source root from absolute source ID.
+ *
+ * Uses proper path semantics: strips `project_root/source_root/` prefix.
+ *
+ * @param source_id Absolute path to the source file
+ * @param options Module source options for path extraction
+ *
+ * @example
+ * const options = module_create_source_options('/home/user/project');
+ * module_extract_path('/home/user/project/src/lib/foo.ts', options) // => 'foo.ts'
+ * module_extract_path('/home/user/project/src/lib/nested/bar.svelte', options) // => 'nested/bar.svelte'
  *
  * @example
- * module_extract_path('/home/user/project/src/lib/foo.ts') // => 'foo.ts'
- * module_extract_path('/home/user/project/src/lib/nested/bar.svelte') // => 'nested/bar.svelte'
+ * const options = module_create_source_options('/home/user/project', {
+ *   source_paths: ['src/lib', 'src/routes'],
+ *   source_root: 'src',
+ * });
+ * module_extract_path('/home/user/project/src/lib/foo.ts', options) // => 'lib/foo.ts'
+ * module_extract_path('/home/user/project/src/routes/page.svelte', options) // => 'routes/page.svelte'
  */
-export declare const module_extract_path: (source_id: string) => string;
+export declare const module_extract_path: (source_id: string, options: ModuleSourceOptions) => string;
 /**
  * Extract component name from a Svelte module path.
  *
@@ -47,23 +242,50 @@ export declare const module_get_component_name: (module_path: string) => string;
  * module_get_key('foo.ts') // => './foo.ts'
  */
 export declare const module_get_key: (module_path: string) => string;
+/**
+ * Check if a path is a TypeScript or JavaScript file.
+ *
+ * Includes both `.ts` and `.js` files since JS files are valid in TS projects.
+ * Excludes `.d.ts` declaration files - use a custom `get_analyzer` to include them.
+ */
 export declare const module_is_typescript: (path: string) => boolean;
 export declare const module_is_svelte: (path: string) => boolean;
 export declare const module_is_css: (path: string) => boolean;
 export declare const module_is_json: (path: string) => boolean;
 export declare const module_is_test: (path: string) => boolean;
 /**
- * Check if a path matches source criteria.
+ * Check if a path is an analyzable source file.
  *
- * Checks source directory paths, file extensions, and exclusion patterns.
- * Uses defaults if no options provided.
+ * Combines all filtering: exclusion patterns, source directory paths,
+ * and analyzer availability. This is the single check for whether a
+ * file should be included in library analysis.
+ *
+ * Uses proper path semantics with `startsWith` matching against
+ * `project_root/source_path/`. No heuristics needed - nested directories
+ * are correctly excluded by the prefix check.
+ *
+ * @param path Full absolute path to check
+ * @param options Module source options for filtering
+ * @returns True if the path is an analyzable source file
+ *
+ * @example
+ * const options = module_create_source_options('/home/user/project');
+ * module_is_source('/home/user/project/src/lib/foo.ts', options) // => true
+ * module_is_source('/home/user/project/src/lib/foo.test.ts', options) // => false (excluded)
+ * module_is_source('/home/user/project/src/fixtures/mini/src/lib/bar.ts', options) // => false (wrong prefix)
+ */
+export declare const module_is_source: (path: string, options: ModuleSourceOptions) => boolean;
+/**
+ * Extract dependencies and dependents for a module from source file info.
  *
- * Rejects nested repo paths by ensuring the first `/src/` leads to the source directory
- * (e.g. rejects `/src/fixtures/repos/foo/src/lib/index.ts` because `/src/fixtures/` ≠ `/src/lib/`).
+ * Filters to only include source modules (excludes external packages, node_modules, tests).
+ * Returns sorted arrays of module paths (relative to source_root) for deterministic output.
  *
- * @param path Full path to check
- * @param options Configuration options (uses defaults if not provided)
- * @returns True if the path matches all criteria
+ * @param source_file The source file info to extract dependencies from
+ * @param options Module source options for filtering and path extraction
  */
-export declare const module_matches_source: (path: string, options?: ModuleSourceOptions) => boolean;
+export declare const module_extract_dependencies: (source_file: SourceFileInfo, options: ModuleSourceOptions) => {
+    dependencies: Array<string>;
+    dependents: Array<string>;
+};
 //# sourceMappingURL=module_helpers.d.ts.map

package/dist/module_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/module_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,gEAAgE;IAChE,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,qEAAqE;IACrE,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3B,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,mBAAmB,CAIhE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,WAAW,MAAM,KAAG,MAGvD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,aAAa,MAAM,KAAG,MACN,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,KAAG,MAA4B,CAAC;AAElF,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,OACP,CAAC;AAE9C,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,OAAmC,CAAC;AAEpF,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,OAAgC,CAAC;AAE9E,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAAiC,CAAC;AAEhF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAAoC,CAAC;AAEnF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,MAAM,EAAE,UAAU,mBAAmB,KAAG,OAyBnF,CAAC"}
+{"version":3,"file":"module_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/module_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,gBAAgB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,MAAM,KAAG,YAAY,GAAG,IAIzE,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAInC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,4BAA4B,GACxC,cAAc,MAAM,EACpB,YAAY,OAAO,CAAC,mBAAmB,CAAC,KACtC,mBAID,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,8BAA8B,GAAI,SAAS,mBAAmB,KAAG,IAqE7E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,mBAAmB,KAAG,MAWrE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,GAAI,WAAW,MAAM,EAAE,SAAS,mBAAmB,KAAG,MAUrF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,aAAa,MAAM,KAAG,MACN,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,KAAG,MAA4B,CAAC;AAElF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,OACsB,CAAC;AAE3E,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,OAAmC,CAAC;AAEpF,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,OAAgC,CAAC;AAE9E,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAAiC,CAAC;AAEhF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAAoC,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,SAAS,mBAAmB,KAAG,OAe7E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,GACvC,aAAa,cAAc,EAC3B,SAAS,mBAAmB,KAC1B;IAAC,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CA2BzD,CAAC"}

package/dist/module_helpers.js

@@ -5,25 +5,197 @@
  * and import relationships in the package generation system.
  *
  * All functions are prefixed with `module_` for clarity.
+ *
+ * @module
  */
 /**
- * Default options for module source detection.
+ * Default analyzer resolver based on file extension.
+ *
+ * - `.svelte` → `'svelte'`
+ * - `.ts`, `.js` → `'typescript'`
+ * - Other extensions → `null` (skip)
  */
-export const MODULE_SOURCE_DEFAULTS = {
-    source_paths: ['/src/lib/'],
-    extensions: ['.ts', '.js', '.svelte'],
+export const module_get_analyzer_default = (path) => {
+    if (module_is_svelte(path))
+        return 'svelte';
+    if (module_is_typescript(path))
+        return 'typescript';
+    return null;
+};
+/**
+ * Default partial options for standard SvelteKit library structure.
+ *
+ * Does not include `project_root` - use `module_create_source_options()` to create
+ * complete options with your project root.
+ */
+export const MODULE_SOURCE_PARTIAL = {
+    source_paths: ['src/lib'],
     exclude_patterns: [/\.test\.ts$/],
+    get_analyzer: module_get_analyzer_default,
+};
+/**
+ * Create complete source options from project root and optional overrides.
+ *
+ * @param project_root Absolute path to project root (typically `process.cwd()`)
+ * @param overrides Optional overrides for default options
+ *
+ * @example
+ * // Standard SvelteKit library
+ * const options = module_create_source_options(process.cwd());
+ *
+ * @example
+ * // Multiple source directories
+ * const options = module_create_source_options(process.cwd(), {
+ *   source_paths: ['src/lib', 'src/routes'],
+ *   source_root: 'src',
+ * });
+ *
+ * @example
+ * // Custom exclusions
+ * const options = module_create_source_options(process.cwd(), {
+ *   exclude_patterns: [/\.test\.ts$/, /\.internal\.ts$/],
+ * });
+ */
+export const module_create_source_options = (project_root, overrides) => ({
+    project_root,
+    ...MODULE_SOURCE_PARTIAL,
+    ...overrides,
+});
+/**
+ * Validate `ModuleSourceOptions` format and consistency.
+ *
+ * Checks:
+ * 1. `project_root` is an absolute path (starts with `/`)
+ * 2. `source_paths` entries don't have leading/trailing slashes
+ * 3. `source_root` (if provided) doesn't have leading/trailing slashes
+ * 4. Multiple `source_paths` require explicit `source_root`
+ * 5. `source_root` is a prefix of all `source_paths`
+ *
+ * @throws Error if validation fails
+ *
+ * @example
+ * // Valid - single source path (source_root auto-derived)
+ * module_validate_source_options({
+ *   project_root: '/home/user/project',
+ *   source_paths: ['src/lib'],
+ *   ...
+ * });
+ *
+ * @example
+ * // Valid - multiple source paths with explicit source_root
+ * module_validate_source_options({
+ *   project_root: '/home/user/project',
+ *   source_paths: ['src/lib', 'src/routes'],
+ *   source_root: 'src',
+ *   ...
+ * });
+ *
+ * @example
+ * // Invalid - multiple source paths without source_root
+ * module_validate_source_options({
+ *   project_root: '/home/user/project',
+ *   source_paths: ['src/lib', 'src/routes'],  // throws
+ *   ...
+ * });
+ */
+export const module_validate_source_options = (options) => {
+    const { project_root, source_paths, source_root } = options;
+    // Validate project_root is absolute
+    if (!project_root.startsWith('/')) {
+        throw new Error(`project_root must be an absolute path (start with "/"): "${project_root}"`);
+    }
+    // Validate project_root doesn't have trailing slash (we add it internally)
+    if (project_root.endsWith('/')) {
+        throw new Error(`project_root should not have trailing slash: "${project_root}". ` +
+            `Trailing slashes are added internally for correct matching.`);
+    }
+    // Validate source_paths
+    if (source_paths.length === 0) {
+        throw new Error('source_paths must have at least one entry');
+    }
+    for (const source_path of source_paths) {
+        if (source_path.startsWith('/')) {
+            throw new Error(`source_paths entry should not start with "/": "${source_path}". ` +
+                `Paths are relative to project_root.`);
+        }
+        if (source_path.endsWith('/')) {
+            throw new Error(`source_paths entry should not end with "/": "${source_path}". ` +
+                `Trailing slashes are added internally for correct matching.`);
+        }
+    }
+    // Validate source_root if provided
+    if (source_root !== undefined) {
+        if (source_root.startsWith('/')) {
+            throw new Error(`source_root should not start with "/": "${source_root}". ` +
+                `Paths are relative to project_root.`);
+        }
+        if (source_root.endsWith('/')) {
+            throw new Error(`source_root should not end with "/": "${source_root}". ` +
+                `Trailing slashes are added internally for correct matching.`);
+        }
+        // Validate each source_path starts with source_root
+        for (const source_path of source_paths) {
+            // source_path should equal source_root or start with source_root/
+            if (source_path !== source_root && !source_path.startsWith(source_root + '/')) {
+                throw new Error(`source_paths entry "${source_path}" must start with source_root "${source_root}". ` +
+                    `module_extract_path uses source_root to compute module paths.`);
+            }
+        }
+    }
+    else if (source_paths.length > 1) {
+        // Multiple source_paths without source_root - error
+        throw new Error(`source_root is required when source_paths has multiple entries. ` +
+            `Got source_paths: [${source_paths.map((p) => `"${p}"`).join(', ')}]. ` +
+            `Provide source_root to specify the common prefix for module path extraction.`);
+    }
 };
 /**
- * Extract module path relative to src/lib from absolute source ID.
+ * Get the effective source_root from options.
+ *
+ * Returns `source_root` if provided, otherwise returns `source_paths[0]` for single-path configs.
+ *
+ * @throws Error if source_root is required but not provided (multiple source_paths)
+ */
+export const module_get_source_root = (options) => {
+    if (options.source_root !== undefined) {
+        return options.source_root;
+    }
+    if (options.source_paths.length === 1) {
+        return options.source_paths[0];
+    }
+    throw new Error(`source_root is required when source_paths has multiple entries. ` +
+        `Got source_paths: [${options.source_paths.map((p) => `"${p}"`).join(', ')}].`);
+};
+/**
+ * Extract module path relative to source root from absolute source ID.
+ *
+ * Uses proper path semantics: strips `project_root/source_root/` prefix.
+ *
+ * @param source_id Absolute path to the source file
+ * @param options Module source options for path extraction
+ *
+ * @example
+ * const options = module_create_source_options('/home/user/project');
+ * module_extract_path('/home/user/project/src/lib/foo.ts', options) // => 'foo.ts'
+ * module_extract_path('/home/user/project/src/lib/nested/bar.svelte', options) // => 'nested/bar.svelte'
  *
  * @example
- * module_extract_path('/home/user/project/src/lib/foo.ts') // => 'foo.ts'
- * module_extract_path('/home/user/project/src/lib/nested/bar.svelte') // => 'nested/bar.svelte'
+ * const options = module_create_source_options('/home/user/project', {
+ *   source_paths: ['src/lib', 'src/routes'],
+ *   source_root: 'src',
+ * });
+ * module_extract_path('/home/user/project/src/lib/foo.ts', options) // => 'lib/foo.ts'
+ * module_extract_path('/home/user/project/src/routes/page.svelte', options) // => 'routes/page.svelte'
  */
-export const module_extract_path = (source_id) => {
-    const lib_index = source_id.indexOf('/src/lib/');
-    return lib_index !== -1 ? source_id.substring(lib_index + 9) : source_id;
+export const module_extract_path = (source_id, options) => {
+    const effective_root = module_get_source_root(options);
+    // Build the full prefix: project_root + '/' + source_root + '/'
+    const prefix = options.project_root + '/' + effective_root + '/';
+    if (source_id.startsWith(prefix)) {
+        return source_id.slice(prefix.length);
+    }
+    // Fallback: return full path if prefix doesn't match (shouldn't happen with valid inputs)
+    return source_id;
 };
 /**
  * Extract component name from a Svelte module path.
@@ -40,48 +212,84 @@ export const module_get_component_name = (module_path) => module_path.replace(/^
  * module_get_key('foo.ts') // => './foo.ts'
  */
 export const module_get_key = (module_path) => `./${module_path}`;
-export const module_is_typescript = (path) => path.endsWith('.ts') || path.endsWith('.js'); // hackyy but fine?
+/**
+ * Check if a path is a TypeScript or JavaScript file.
+ *
+ * Includes both `.ts` and `.js` files since JS files are valid in TS projects.
+ * Excludes `.d.ts` declaration files - use a custom `get_analyzer` to include them.
+ */
+export const module_is_typescript = (path) => (path.endsWith('.ts') && !path.endsWith('.d.ts')) || path.endsWith('.js');
 export const module_is_svelte = (path) => path.endsWith('.svelte');
 export const module_is_css = (path) => path.endsWith('.css');
 export const module_is_json = (path) => path.endsWith('.json');
 export const module_is_test = (path) => path.endsWith('.test.ts');
 /**
- * Check if a path matches source criteria.
+ * Check if a path is an analyzable source file.
  *
- * Checks source directory paths, file extensions, and exclusion patterns.
- * Uses defaults if no options provided.
+ * Combines all filtering: exclusion patterns, source directory paths,
+ * and analyzer availability. This is the single check for whether a
+ * file should be included in library analysis.
  *
- * Rejects nested repo paths by ensuring the first `/src/` leads to the source directory
- * (e.g. rejects `/src/fixtures/repos/foo/src/lib/index.ts` because `/src/fixtures/` ≠ `/src/lib/`).
+ * Uses proper path semantics with `startsWith` matching against
+ * `project_root/source_path/`. No heuristics needed - nested directories
+ * are correctly excluded by the prefix check.
  *
- * @param path Full path to check
- * @param options Configuration options (uses defaults if not provided)
- * @returns True if the path matches all criteria
+ * @param path Full absolute path to check
+ * @param options Module source options for filtering
+ * @returns True if the path is an analyzable source file
+ *
+ * @example
+ * const options = module_create_source_options('/home/user/project');
+ * module_is_source('/home/user/project/src/lib/foo.ts', options) // => true
+ * module_is_source('/home/user/project/src/lib/foo.test.ts', options) // => false (excluded)
+ * module_is_source('/home/user/project/src/fixtures/mini/src/lib/bar.ts', options) // => false (wrong prefix)
  */
-export const module_matches_source = (path, options) => {
-    const opts = { ...MODULE_SOURCE_DEFAULTS, ...options };
-    // Check if path is in one of the source directories
-    // The first /src/ in the path must lead directly to the source directory
-    // This rejects nested repos like /src/fixtures/repos/foo/src/lib/
-    const in_source_dir = opts.source_paths.some((source_path) => {
-        if (!path.includes(source_path))
-            return false;
-        // Find the first /src/ and verify it's part of the source_path
-        const first_src_index = path.indexOf('/src/');
-        if (first_src_index === -1)
-            return false;
-        // The source_path should start at that position
-        return path.substring(first_src_index).startsWith(source_path);
+export const module_is_source = (path, options) => {
+    // Check exclusion patterns first (fast regex check)
+    const is_excluded = options.exclude_patterns.some((pattern) => pattern.test(path));
+    if (is_excluded)
+        return false;
+    // Check if path starts with project_root/source_path/
+    // Using startsWith with trailing slash ensures correct directory matching
+    const in_source_dir = options.source_paths.some((source_path) => {
+        const full_prefix = options.project_root + '/' + source_path + '/';
+        return path.startsWith(full_prefix);
     });
     if (!in_source_dir)
         return false;
-    // Check if extension matches
-    const has_valid_extension = opts.extensions.some((ext) => path.endsWith(ext));
-    if (!has_valid_extension)
-        return false;
-    // Check exclusion patterns
-    const is_excluded = opts.exclude_patterns.some((pattern) => pattern.test(path));
-    if (is_excluded)
-        return false;
-    return true;
+    // Check if file type is analyzable
+    return options.get_analyzer(path) !== null;
+};
+/**
+ * Extract dependencies and dependents for a module from source file info.
+ *
+ * Filters to only include source modules (excludes external packages, node_modules, tests).
+ * Returns sorted arrays of module paths (relative to source_root) for deterministic output.
+ *
+ * @param source_file The source file info to extract dependencies from
+ * @param options Module source options for filtering and path extraction
+ */
+export const module_extract_dependencies = (source_file, options) => {
+    const dependencies = [];
+    const dependents = [];
+    // Extract dependencies (files this module imports) if provided
+    if (source_file.dependencies) {
+        for (const dep_id of source_file.dependencies) {
+            if (module_is_source(dep_id, options)) {
+                dependencies.push(module_extract_path(dep_id, options));
+            }
+        }
+    }
+    // Extract dependents (files that import this module) if provided
+    if (source_file.dependents) {
+        for (const dependent_id of source_file.dependents) {
+            if (module_is_source(dependent_id, options)) {
+                dependents.push(module_extract_path(dependent_id, options));
+            }
+        }
+    }
+    // Sort for deterministic output
+    dependencies.sort();
+    dependents.sort();
+    return { dependencies, dependents };
 };