svelte-docinfo 0.1.0

package/dist/log.js

@@ -0,0 +1,11 @@
+/**
+ * Minimal logger interface threaded through analysis functions.
+ *
+ * Separate from `diagnostics.ts` because logging and diagnostics are not the
+ * same concern: diagnostics are structured, schema-validated records of
+ * analysis-time failures; logs are unstructured progress/info messages the
+ * caller chooses how to display.
+ *
+ * @module
+ */
+export {};

package/dist/logo.d.ts

@@ -0,0 +1,8 @@
+export declare const logo_svelte_docinfo: {
+    label: string;
+    fill: string;
+    paths: {
+        d: string;
+    }[];
+};
+//# sourceMappingURL=logo.d.ts.map

package/dist/logo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logo.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/logo.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB;;;;;;CAQb,CAAC"}

package/dist/logo.js

@@ -0,0 +1,9 @@
+export const logo_svelte_docinfo = {
+    label: 'a cyan scroll with curling ends',
+    fill: '#1ec3d2',
+    paths: [
+        {
+            d: 'M 83,80.28 c -9.75,-34.41 2.18,-52.33 -3.76,-70 -2.31,-7.66 -48.25,-12 -70.25,-6 -12,6 -10,24 4,24 6,0 5.51,-13.67 6,-18 0,0 -1.43,59.52 5.13,80.21 1.2,3.8 2.91,5.28 4,5.92 3.93,2.31 63.48,3.74 68.01,0.54 1.18,-0.84 3.11,-5.38 2.63,-8.75 -0.42,-2.94 -3.27,-5.78 -5.28,-6.26 -1.74,-0.41 -0.62,-0.79 -5.37,-0.59 C 77.2,81.96 71.49,85.44 47.57,84.25 41.58,84.09 11.04,79.77 64.12,56.73 51.2,46.21 46.99,49.36 37.77,43.13 37.39,42.87 55,45.85 66.37,56.98 -10.84,93.94 82.99,80.29 82.99,80.29 Z',
+        },
+    ],
+};

package/dist/main.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for svelte-docinfo.
+ *
+ * This file is the bin script entry point. The actual CLI implementation
+ * is in `cli.ts` which exports `runCli()` for testing.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/main.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}

package/dist/main.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for svelte-docinfo.
+ *
+ * This file is the bin script entry point. The actual CLI implementation
+ * is in `cli.ts` which exports `runCli()` for testing.
+ *
+ * @module
+ */
+import { runCli } from './cli.js';
+try {
+    const exitCode = await runCli();
+    process.exit(exitCode);
+}
+catch (error) {
+    console.error('Fatal error:', error);
+    process.exit(2);
+}

package/dist/paths.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Path normalization chokepoint.
+ *
+ * Internal contract: every path stored, compared, or used as a Map/Set key
+ * inside this library is in POSIX form (forward slashes). The library accepts
+ * native paths (backslash on Windows, forward slash elsewhere) at every public
+ * API boundary and at every `node:path` call site whose result flows into
+ * storage or comparison.
+ *
+ * `toPosixPath` is the only normalization primitive — anything that needs to
+ * convert a native path to the internal form goes through it. The function is
+ * idempotent: forward-slash inputs round-trip unchanged, so calls outside
+ * Windows are effectively a no-op.
+ *
+ * Drive-letter case (`C:` vs `c:`) and Windows long-path prefixes (`\\?\`) are
+ * deliberately out of scope — they don't arise from the path sources this
+ * library consumes (tsconfig roots, glob results, caller-supplied ids).
+ *
+ * @module
+ */
+/**
+ * Normalize a path to POSIX form (forward slashes).
+ *
+ * Replaces every backslash with a forward slash. Idempotent: forward-slash
+ * input returns unchanged. Empty string returns empty string.
+ *
+ * @example
+ * ```ts
+ * toPosixPath('C:\\proj\\src\\lib\\foo.ts') // => 'C:/proj/src/lib/foo.ts'
+ * toPosixPath('/home/user/proj/foo.ts')     // => '/home/user/proj/foo.ts' (unchanged)
+ * toPosixPath('')                            // => ''
+ * ```
+ */
+export declare const toPosixPath: (p: string) => string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,KAAG,MAAwD,CAAC"}

package/dist/paths.js

@@ -0,0 +1,34 @@
+/**
+ * Path normalization chokepoint.
+ *
+ * Internal contract: every path stored, compared, or used as a Map/Set key
+ * inside this library is in POSIX form (forward slashes). The library accepts
+ * native paths (backslash on Windows, forward slash elsewhere) at every public
+ * API boundary and at every `node:path` call site whose result flows into
+ * storage or comparison.
+ *
+ * `toPosixPath` is the only normalization primitive — anything that needs to
+ * convert a native path to the internal form goes through it. The function is
+ * idempotent: forward-slash inputs round-trip unchanged, so calls outside
+ * Windows are effectively a no-op.
+ *
+ * Drive-letter case (`C:` vs `c:`) and Windows long-path prefixes (`\\?\`) are
+ * deliberately out of scope — they don't arise from the path sources this
+ * library consumes (tsconfig roots, glob results, caller-supplied ids).
+ *
+ * @module
+ */
+/**
+ * Normalize a path to POSIX form (forward slashes).
+ *
+ * Replaces every backslash with a forward slash. Idempotent: forward-slash
+ * input returns unchanged. Empty string returns empty string.
+ *
+ * @example
+ * ```ts
+ * toPosixPath('C:\\proj\\src\\lib\\foo.ts') // => 'C:/proj/src/lib/foo.ts'
+ * toPosixPath('/home/user/proj/foo.ts')     // => '/home/user/proj/foo.ts' (unchanged)
+ * toPosixPath('')                            // => ''
+ * ```
+ */
+export const toPosixPath = (p) => (p.includes('\\') ? p.replace(/\\/g, '/') : p);

package/dist/postprocess.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Post-processing for analyzed library metadata.
+ *
+ * These functions transform analysis results after module-level analysis is complete:
+ *
+ * 1. **Validation** — `findDuplicates` checks flat namespace constraints
+ * 2. **Transformation** — `mergeReExports` resolves re-export relationships,
+ *    `computeDependents` builds bidirectional dependency graphs
+ * 3. **Output** — `sortModules` prepares deterministic output
+ *
+ * @see `analyze.ts` for the main analysis entry point
+ *
+ * @module
+ */
+import type { DeclarationJson, ModuleJson } from './types.js';
+import type { ReExportInfo } from './declaration-build.js';
+import type { SourceFileInfo } from './source.js';
+/**
+ * A duplicate declaration with its full metadata and module path.
+ */
+export interface DuplicateDeclaration {
+    /** The full declaration metadata. */
+    declaration: DeclarationJson;
+    /** Module path where this declaration is defined. */
+    module: string;
+}
+/**
+ * Find duplicate declaration names across modules.
+ *
+ * Callers can decide how to handle duplicates (throw, warn, ignore).
+ *
+ * @returns `Map` of declaration names to their `DuplicateDeclaration` occurrences (only includes duplicates)
+ *
+ * @example
+ * ```ts
+ * const duplicates = findDuplicates(modules);
+ * if (duplicates.size > 0) {
+ *   for (const [name, occurrences] of duplicates) {
+ *     console.error(`"${name}" found in:`);
+ *     for (const {declaration, module} of occurrences) {
+ *       console.error(`  - ${module}:${declaration.sourceLine} (${declaration.kind})`);
+ *     }
+ *   }
+ *   throw new Error(`Found ${duplicates.size} duplicate declaration names`);
+ * }
+ * ```
+ */
+export declare const findDuplicates: (modules: Array<ModuleJson>) => Map<string, Array<DuplicateDeclaration>>;
+/**
+ * Sort modules alphabetically by path for deterministic output and cleaner diffs.
+ *
+ * @param modules - the modules to sort
+ * @returns a new sorted array (does not mutate input)
+ */
+export declare const sortModules: (modules: Array<ModuleJson>) => Array<ModuleJson>;
+/**
+ * A collected re-export with its source module context.
+ *
+ * Used during the two-phase re-export resolution:
+ * 1. Phase 1: Collect re-exports from each module during analysis
+ * 2. Phase 2: Group by original module and merge into `alsoExportedFrom`
+ */
+export interface ReExportEntry {
+    /** The module that re-exports the declaration. */
+    reExportingModule: string;
+    /** The re-export info (name and original module). */
+    reExport: ReExportInfo;
+}
+/**
+ * Build `alsoExportedFrom` arrays from collected re-export data.
+ *
+ * This function resolves the two-phase re-export problem:
+ *
+ * **Problem**: When module A re-exports from module B, we discover this while
+ * analyzing A, but need to update B's declarations. However, B may already be
+ * processed or may be processed later.
+ *
+ * **Solution**: Collect all re-exports in phase 1, then merge them in phase 2
+ * after all modules are analyzed.
+ *
+ * Component-only fields on renamed component aliases (`props`,
+ * `acceptsChildren`, etc.) are populated separately by `resolveComponentAliases`
+ * — call it after this function. They split because they touch disjoint fields
+ * and have different inputs.
+ *
+ * @param modules - the modules array with all modules (will be mutated)
+ * @param collectedReExports - array of re-exports collected during phase 1
+ * @mutates modules - unions new re-exporters into `declaration.alsoExportedFrom`
+ *   (deduped + sorted), so a second call with the same inputs is a no-op
+ *
+ * @example
+ * ```ts
+ * // helpers.ts exports: foo, bar
+ * // index.ts does: export {foo, bar} from './files.js'
+ * //
+ * // After processing:
+ * // - helpers.ts foo declaration gets: alsoExportedFrom: ['index.ts']
+ * // - helpers.ts bar declaration gets: alsoExportedFrom: ['index.ts']
+ * ```
+ */
+export declare const mergeReExports: (modules: Array<ModuleJson>, collectedReExports: Array<ReExportEntry>) => void;
+/**
+ * Copy props/acceptsChildren/lang/etc. from canonical component declarations
+ * onto synthesized component-aliased declarations.
+ *
+ * Renamed Svelte component re-exports (`export {default as Foo} from './X.svelte'`)
+ * are emitted as `kind: 'component'` placeholders by `analyzeExports`, with `aliasOf`
+ * pointing at the canonical. The canonical's component-specific fields are only
+ * available after `analyzeSvelteModule` synthesizes the canonical declaration, so
+ * the copy happens here in phase 2 once all modules are analyzed.
+ *
+ * Call this *after* `mergeReExports` — both walk the same modules array but
+ * read/write disjoint fields, so order between them only matters for clarity.
+ *
+ * @mutates modules - fills component-only fields on aliased component declarations
+ */
+export declare const resolveComponentAliases: (modules: Array<ModuleJson>) => void;
+/**
+ * Compute bidirectional dependencies from source files.
+ *
+ * This function ensures that if file A has file B in its `dependencies`,
+ * then file B will have file A in its `dependents`. This provides consistent
+ * output regardless of whether callers provide one-directional or bidirectional
+ * dependency information.
+ *
+ * Returns new `SourceFileInfo` objects when computed dependents exist or when
+ * paths needed posixification; otherwise the original input objects flow
+ * through `===`-equal (fast path for session callers, who already pass POSIX
+ * paths and may have no inferable dependents for a given file).
+ *
+ * @param files - source files with optional dependency information
+ * @returns new array with bidirectional dependencies computed
+ *
+ * @example
+ * ```ts
+ * // Input: Calculator.svelte has dependencies: [math.ts]
+ * // Output: Calculator.svelte has dependencies: [math.ts]
+ * //         math.ts has dependents: [Calculator.svelte]
+ * const filesWithBidirectional = computeDependents(files);
+ * ```
+ */
+export declare const computeDependents: (files: ReadonlyArray<SourceFileInfo>) => Array<SourceFileInfo & {
+    dependents?: ReadonlyArray<string>;
+}>;
+//# sourceMappingURL=postprocess.d.ts.map

package/dist/postprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postprocess.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/postprocess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAA2B,eAAe,EAAE,UAAU,EAAC,MAAM,YAAY,CAAC;AACtF,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,aAAa,CAAC;AAuBhD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,qCAAqC;IACrC,WAAW,EAAE,eAAe,CAAC;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,GAC1B,SAAS,KAAK,CAAC,UAAU,CAAC,KACxB,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,oBAAoB,CAAC,CA4BzC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,KAAK,CAAC,UAAU,CAAC,KAAG,KAAK,CAAC,UAAU,CAExE,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,cAAc,GAC1B,SAAS,KAAK,CAAC,UAAU,CAAC,EAC1B,oBAAoB,KAAK,CAAC,aAAa,CAAC,KACtC,IAkCF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,KAAK,CAAC,UAAU,CAAC,KAAG,IAoDpE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,OAAO,aAAa,CAAC,cAAc,CAAC,KAClC,KAAK,CAAC,cAAc,GAAG;IAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAC,CAwD7D,CAAC"}

package/dist/postprocess.js

@@ -0,0 +1,305 @@
+/**
+ * Post-processing for analyzed library metadata.
+ *
+ * These functions transform analysis results after module-level analysis is complete:
+ *
+ * 1. **Validation** — `findDuplicates` checks flat namespace constraints
+ * 2. **Transformation** — `mergeReExports` resolves re-export relationships,
+ *    `computeDependents` builds bidirectional dependency graphs
+ * 3. **Output** — `sortModules` prepares deterministic output
+ *
+ * @see `analyze.ts` for the main analysis entry point
+ *
+ * @module
+ */
+import { toPosixPath } from './paths.js';
+/**
+ * Posixify every entry in `arr`. Returns the same array reference when no
+ * entry needed normalization, so identity-equality short-circuits in
+ * `computeDependents`'s no-rewrite branch.
+ */
+const posixifyArray = (arr) => {
+    if (!arr)
+        return arr;
+    let changed = null;
+    for (let i = 0; i < arr.length; i++) {
+        const p = toPosixPath(arr[i]);
+        if (p !== arr[i]) {
+            if (!changed)
+                changed = arr.slice();
+            changed[i] = p;
+        }
+    }
+    return changed ?? arr;
+};
+/**
+ * Find duplicate declaration names across modules.
+ *
+ * Callers can decide how to handle duplicates (throw, warn, ignore).
+ *
+ * @returns `Map` of declaration names to their `DuplicateDeclaration` occurrences (only includes duplicates)
+ *
+ * @example
+ * ```ts
+ * const duplicates = findDuplicates(modules);
+ * if (duplicates.size > 0) {
+ *   for (const [name, occurrences] of duplicates) {
+ *     console.error(`"${name}" found in:`);
+ *     for (const {declaration, module} of occurrences) {
+ *       console.error(`  - ${module}:${declaration.sourceLine} (${declaration.kind})`);
+ *     }
+ *   }
+ *   throw new Error(`Found ${duplicates.size} duplicate declaration names`);
+ * }
+ * ```
+ */
+export const findDuplicates = (modules) => {
+    const allOccurrences = new Map();
+    // Collect declaration names. The default slot is module-scoped per the JS
+    // spec — every module can have its own `'default'` and they don't collide
+    // — so skip `name === 'default'` entries from this flat-namespace check.
+    for (const mod of modules) {
+        for (const declaration of mod.declarations) {
+            if (declaration.name === 'default')
+                continue;
+            if (!allOccurrences.has(declaration.name)) {
+                allOccurrences.set(declaration.name, []);
+            }
+            allOccurrences.get(declaration.name).push({
+                declaration,
+                module: mod.path,
+            });
+        }
+    }
+    // Filter to only duplicates
+    const duplicates = new Map();
+    for (const [name, occurrences] of allOccurrences) {
+        if (occurrences.length > 1) {
+            duplicates.set(name, occurrences);
+        }
+    }
+    return duplicates;
+};
+/**
+ * Sort modules alphabetically by path for deterministic output and cleaner diffs.
+ *
+ * @param modules - the modules to sort
+ * @returns a new sorted array (does not mutate input)
+ */
+export const sortModules = (modules) => {
+    return modules.slice().sort((a, b) => a.path.localeCompare(b.path));
+};
+/**
+ * Build `alsoExportedFrom` arrays from collected re-export data.
+ *
+ * This function resolves the two-phase re-export problem:
+ *
+ * **Problem**: When module A re-exports from module B, we discover this while
+ * analyzing A, but need to update B's declarations. However, B may already be
+ * processed or may be processed later.
+ *
+ * **Solution**: Collect all re-exports in phase 1, then merge them in phase 2
+ * after all modules are analyzed.
+ *
+ * Component-only fields on renamed component aliases (`props`,
+ * `acceptsChildren`, etc.) are populated separately by `resolveComponentAliases`
+ * — call it after this function. They split because they touch disjoint fields
+ * and have different inputs.
+ *
+ * @param modules - the modules array with all modules (will be mutated)
+ * @param collectedReExports - array of re-exports collected during phase 1
+ * @mutates modules - unions new re-exporters into `declaration.alsoExportedFrom`
+ *   (deduped + sorted), so a second call with the same inputs is a no-op
+ *
+ * @example
+ * ```ts
+ * // helpers.ts exports: foo, bar
+ * // index.ts does: export {foo, bar} from './files.js'
+ * //
+ * // After processing:
+ * // - helpers.ts foo declaration gets: alsoExportedFrom: ['index.ts']
+ * // - helpers.ts bar declaration gets: alsoExportedFrom: ['index.ts']
+ * ```
+ */
+export const mergeReExports = (modules, collectedReExports) => {
+    // Group re-exports by `(originalModule, name)`. The default slot keys as
+    // `'default'` like any other name — each module owns its own default slot,
+    // so the per-module map prevents cross-module collisions naturally.
+    const reExportMap = new Map();
+    for (const { reExportingModule, reExport } of collectedReExports) {
+        const { name, originalModule } = reExport;
+        if (!reExportMap.has(originalModule)) {
+            reExportMap.set(originalModule, new Map());
+        }
+        const moduleMap = reExportMap.get(originalModule);
+        if (!moduleMap.has(name)) {
+            moduleMap.set(name, []);
+        }
+        moduleMap.get(name).push(reExportingModule);
+    }
+    // Merge into original declarations
+    for (const mod of modules) {
+        const moduleReExports = reExportMap.get(mod.path);
+        if (!moduleReExports)
+            continue;
+        for (const declaration of mod.declarations) {
+            const reExporters = moduleReExports.get(declaration.name);
+            if (reExporters?.length) {
+                // Union with existing entries, dedupe, sort — keeps the function idempotent
+                // when re-run on already-merged modules
+                const merged = new Set(declaration.alsoExportedFrom);
+                for (const reExporter of reExporters)
+                    merged.add(reExporter);
+                declaration.alsoExportedFrom = Array.from(merged).sort();
+            }
+        }
+    }
+};
+/**
+ * Copy props/acceptsChildren/lang/etc. from canonical component declarations
+ * onto synthesized component-aliased declarations.
+ *
+ * Renamed Svelte component re-exports (`export {default as Foo} from './X.svelte'`)
+ * are emitted as `kind: 'component'` placeholders by `analyzeExports`, with `aliasOf`
+ * pointing at the canonical. The canonical's component-specific fields are only
+ * available after `analyzeSvelteModule` synthesizes the canonical declaration, so
+ * the copy happens here in phase 2 once all modules are analyzed.
+ *
+ * Call this *after* `mergeReExports` — both walk the same modules array but
+ * read/write disjoint fields, so order between them only matters for clarity.
+ *
+ * @mutates modules - fills component-only fields on aliased component declarations
+ */
+export const resolveComponentAliases = (modules) => {
+    // Build {modulePath → {componentName → ComponentDeclarationJson}} for canonical lookups
+    const canonicalByModule = new Map();
+    for (const mod of modules) {
+        for (const decl of mod.declarations) {
+            if (decl.kind !== 'component' || decl.aliasOf)
+                continue;
+            let perModule = canonicalByModule.get(mod.path);
+            if (!perModule) {
+                perModule = new Map();
+                canonicalByModule.set(mod.path, perModule);
+            }
+            perModule.set(decl.name, decl);
+        }
+    }
+    for (const mod of modules) {
+        for (const decl of mod.declarations) {
+            if (decl.kind !== 'component' || !decl.aliasOf)
+                continue;
+            const canonical = canonicalByModule.get(decl.aliasOf.module)?.get(decl.aliasOf.name);
+            if (!canonical)
+                continue;
+            decl.props = canonical.props;
+            decl.acceptsChildren = canonical.acceptsChildren;
+            decl.intersects = canonical.intersects;
+            decl.genericParams = canonical.genericParams;
+            if (canonical.lang !== undefined)
+                decl.lang = canonical.lang;
+            if (canonical.docComment !== undefined && decl.docComment === undefined) {
+                decl.docComment = canonical.docComment;
+            }
+            if (canonical.typeSignature !== undefined && decl.typeSignature === undefined) {
+                decl.typeSignature = canonical.typeSignature;
+            }
+            if (canonical.examples.length > 0 && decl.examples.length === 0) {
+                decl.examples = canonical.examples;
+            }
+            if (canonical.seeAlso.length > 0 && decl.seeAlso.length === 0) {
+                decl.seeAlso = canonical.seeAlso;
+            }
+            if (canonical.throws.length > 0 && decl.throws.length === 0) {
+                decl.throws = canonical.throws;
+            }
+            if (canonical.deprecatedMessage !== undefined && decl.deprecatedMessage === undefined) {
+                decl.deprecatedMessage = canonical.deprecatedMessage;
+            }
+            if (canonical.since !== undefined && decl.since === undefined) {
+                decl.since = canonical.since;
+            }
+            if (canonical.mutates !== undefined && decl.mutates === undefined) {
+                decl.mutates = canonical.mutates;
+            }
+            if (canonical.partial)
+                decl.partial = true;
+        }
+    }
+};
+/**
+ * Compute bidirectional dependencies from source files.
+ *
+ * This function ensures that if file A has file B in its `dependencies`,
+ * then file B will have file A in its `dependents`. This provides consistent
+ * output regardless of whether callers provide one-directional or bidirectional
+ * dependency information.
+ *
+ * Returns new `SourceFileInfo` objects when computed dependents exist or when
+ * paths needed posixification; otherwise the original input objects flow
+ * through `===`-equal (fast path for session callers, who already pass POSIX
+ * paths and may have no inferable dependents for a given file).
+ *
+ * @param files - source files with optional dependency information
+ * @returns new array with bidirectional dependencies computed
+ *
+ * @example
+ * ```ts
+ * // Input: Calculator.svelte has dependencies: [math.ts]
+ * // Output: Calculator.svelte has dependencies: [math.ts]
+ * //         math.ts has dependents: [Calculator.svelte]
+ * const filesWithBidirectional = computeDependents(files);
+ * ```
+ */
+export const computeDependents = (files) => {
+    // Posixify ids and dependency lists at the boundary so a power user
+    // supplying a hand-built `SourceFileInfo[]` with mixed-shape paths still
+    // gets correct lookup behavior. Identity-preserving when no normalization
+    // is needed (session callers, who already pass POSIX): both arrays and the
+    // outer `SourceFileInfo` flow through `===`-equal.
+    const posixFiles = files.map((file) => {
+        const posixId = toPosixPath(file.id);
+        const posixDeps = posixifyArray(file.dependencies);
+        if (posixId === file.id && posixDeps === file.dependencies) {
+            return file;
+        }
+        return {
+            ...file,
+            id: posixId,
+            dependencies: posixDeps,
+        };
+    });
+    // Build a map of file id -> dependents (computed from dependencies)
+    const computedDependents = new Map();
+    // Initialize all files in the map
+    for (const file of posixFiles) {
+        computedDependents.set(file.id, new Set());
+    }
+    // Compute dependents from dependencies
+    for (const file of posixFiles) {
+        if (!file.dependencies)
+            continue;
+        for (const depId of file.dependencies) {
+            // Only add if the dependency is in our file set
+            if (computedDependents.has(depId)) {
+                computedDependents.get(depId).add(file.id);
+            }
+        }
+    }
+    // Attach computed dependents to each file. Dependents are derived from
+    // forward edges in the owned set, not from caller input — the public
+    // `SourceFileInfo` carries no `dependents` field.
+    return posixFiles.map((file) => {
+        const computed = computedDependents.get(file.id);
+        if (!computed || computed.size === 0) {
+            // No computed dependents, return as-is
+            return file;
+        }
+        // Sort for deterministic output
+        const dependents = Array.from(computed).sort();
+        return {
+            ...file,
+            dependents,
+        };
+    });
+};