@tyndall/dynamic-graph 0.0.1

package/README.md

@@ -0,0 +1,27 @@
+# @tyndall/dynamic-graph
+
+## Overview
+Dynamic module graph manager package for lazy entry expansion and impact analysis.
+
+## Responsibilities
+- Maintain global module DAG and entry views
+- Compute impacted entries from file changes
+- Support shared subgraph convergence and graph hygiene
+
+## Public API Highlights
+- createDynamicModuleGraphManager
+- DynamicModuleGraphManager interface
+
+## Development
+- Build: bun run --filter @tyndall/dynamic-graph build
+- Test (from workspace root): bun test
+
+## Documentation
+- Package specification: [spec.md](./spec.md)
+- Package architecture: [architecture.md](./architecture.md)
+- Package changes: [CHANGELOG.md](./CHANGELOG.md)
+
+## Maintenance Rules
+- Keep this document aligned with implemented package behavior.
+- Update spec.md and architecture.md whenever package contracts or design boundaries change.
+- Record user-visible package changes in CHANGELOG.md.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createDynamicModuleGraphManager, DEFAULT_IMPORT_EXTENSIONS, } from "./manager.js";
+export type { DynamicModuleGraphManager, DynamicModuleGraphEntry, DynamicModuleGraphSnapshot, DynamicModuleGraphStats, DynamicModuleGraphManagerOptions, DynamicModuleGraphChangeResult, } from "./manager.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,yBAAyB,EACzB,uBAAuB,EACvB,0BAA0B,EAC1B,uBAAuB,EACvB,gCAAgC,EAChC,8BAA8B,GAC/B,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { createDynamicModuleGraphManager, DEFAULT_IMPORT_EXTENSIONS, } from "./manager.js";

package/dist/manager.d.ts

@@ -0,0 +1,41 @@
+export declare const DEFAULT_IMPORT_EXTENSIONS: string[];
+export interface DynamicModuleGraphEntry {
+    entryId: string;
+    filePath: string;
+}
+export interface DynamicModuleGraphSnapshot {
+    moduleGraph: Record<string, string[]>;
+    entryToModules: Record<string, string[]>;
+    moduleToEntries: Record<string, string[]>;
+}
+export interface DynamicModuleGraphStats {
+    nodeCount: number;
+    entryCount: number;
+    visitGeneration: number;
+}
+export interface DynamicModuleGraphChangeResult {
+    changedModules: string[];
+    impactedEntryIds: string[];
+    unknownModules: string[];
+}
+export interface DynamicModuleGraphManagerOptions {
+    extensions?: string[];
+    now?: () => number;
+    maxEntries?: number;
+    maxNodes?: number;
+    entryTtlMs?: number;
+}
+export interface DynamicModuleGraphManager {
+    registerEntry: (entry: DynamicModuleGraphEntry) => void;
+    removeEntry: (entryId: string) => void;
+    ensureEntryGraph: (entry: DynamicModuleGraphEntry) => string[];
+    rebuildEntry: (entryId: string) => string[];
+    getEntryModules: (entryId: string) => string[];
+    hasEntry: (entryId: string) => boolean;
+    applyFileChanges: (paths: string[]) => DynamicModuleGraphChangeResult;
+    collectGarbage: () => void;
+    snapshot: () => DynamicModuleGraphSnapshot;
+    stats: () => DynamicModuleGraphStats;
+}
+export declare const createDynamicModuleGraphManager: (options?: DynamicModuleGraphManagerOptions) => DynamicModuleGraphManager;
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,yBAAyB,UASrC,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,8BAA8B;IAC7C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,gCAAgC;IAC/C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACxD,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,gBAAgB,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,MAAM,EAAE,CAAC;IAC/D,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IAC5C,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IAC/C,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,8BAA8B,CAAC;IACtE,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,0BAA0B,CAAC;IAC3C,KAAK,EAAE,MAAM,uBAAuB,CAAC;CACtC;AA2gBD,eAAO,MAAM,+BAA+B,GAC1C,UAAS,gCAAqC,KAC7C,yBAAuE,CAAC"}

package/dist/manager.js

@@ -0,0 +1,433 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname, extname, join, resolve } from "node:path";
+import { hash, normalizePath } from "@tyndall/shared";
+export const DEFAULT_IMPORT_EXTENSIONS = [
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".mts",
+    ".cts",
+];
+const normalizeModuleId = (filePath) => normalizePath(resolve(filePath));
+const sortStrings = (values) => Array.from(new Set(values)).sort((left, right) => left.localeCompare(right));
+const extractImportSpecifiers = (source) => {
+    const specifiers = [];
+    const regex = /(?:import|export)\s+[^'"]*?from\s*['"]([^'"]+)['"]|import\s*['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)|require\(\s*['"]([^'"]+)['"]\s*\)/g;
+    let match;
+    while ((match = regex.exec(source)) !== null) {
+        const specifier = match[1] ?? match[2] ?? match[3] ?? match[4];
+        if (specifier) {
+            specifiers.push(specifier);
+        }
+    }
+    return specifiers;
+};
+const resolveModulePath = (baseDir, specifier, extensions) => {
+    const candidate = resolve(baseDir, specifier);
+    const extension = extname(candidate);
+    const tryFile = (filePath) => {
+        try {
+            const stats = statSync(filePath);
+            if (stats.isFile()) {
+                return filePath;
+            }
+            if (stats.isDirectory()) {
+                for (const ext of extensions) {
+                    const indexPath = join(filePath, `index${ext}`);
+                    try {
+                        const indexStats = statSync(indexPath);
+                        if (indexStats.isFile()) {
+                            return indexPath;
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            }
+        }
+        catch {
+            return null;
+        }
+        return null;
+    };
+    if (extension) {
+        return tryFile(candidate);
+    }
+    for (const ext of extensions) {
+        const resolved = tryFile(`${candidate}${ext}`);
+        if (resolved) {
+            return resolved;
+        }
+    }
+    return tryFile(candidate);
+};
+class DynamicModuleGraphManagerImpl {
+    constructor(options) {
+        this.nodes = new Map();
+        this.entries = new Map();
+        this.entryRoots = new Map();
+        this.visitGeneration = 0;
+        this.extensions = options.extensions ?? DEFAULT_IMPORT_EXTENSIONS;
+        this.now = options.now ?? (() => Date.now());
+        this.maxEntries = options.maxEntries ?? Number.POSITIVE_INFINITY;
+        this.maxNodes = options.maxNodes ?? Number.POSITIVE_INFINITY;
+        this.entryTtlMs = options.entryTtlMs ?? Number.POSITIVE_INFINITY;
+    }
+    registerEntry(entry) {
+        const entryId = entry.entryId;
+        const rootModuleId = normalizeModuleId(entry.filePath);
+        const now = this.now();
+        const existing = this.entries.get(entryId);
+        if (!existing) {
+            this.entries.set(entryId, {
+                id: entryId,
+                rootModuleId,
+                reachableModules: new Set(),
+                lastAccessAt: now,
+                version: 0,
+            });
+            this.indexEntryRoot(entryId, rootModuleId);
+            return;
+        }
+        existing.lastAccessAt = now;
+        if (existing.rootModuleId === rootModuleId) {
+            return;
+        }
+        this.unindexEntryRoot(entryId, existing.rootModuleId);
+        const removedModules = sortStrings(existing.reachableModules);
+        this.detachEntryRefs(entryId, existing.reachableModules);
+        existing.rootModuleId = rootModuleId;
+        existing.reachableModules = new Set();
+        existing.version += 1;
+        this.indexEntryRoot(entryId, rootModuleId);
+        this.pruneOrphans(removedModules);
+    }
+    removeEntry(entryId) {
+        const existing = this.entries.get(entryId);
+        if (!existing) {
+            return;
+        }
+        this.unindexEntryRoot(entryId, existing.rootModuleId);
+        const removedModules = sortStrings(existing.reachableModules);
+        this.detachEntryRefs(entryId, existing.reachableModules);
+        this.entries.delete(entryId);
+        this.pruneOrphans(removedModules);
+    }
+    ensureEntryGraph(entry) {
+        this.registerEntry(entry);
+        return this.rebuildEntry(entry.entryId);
+    }
+    rebuildEntry(entryId) {
+        const view = this.entries.get(entryId);
+        if (!view) {
+            return [];
+        }
+        view.lastAccessAt = this.now();
+        const reachableModules = this.collectReachableModules(view.rootModuleId);
+        const previousModules = view.reachableModules;
+        const removedModules = [];
+        let changed = previousModules.size !== reachableModules.size;
+        for (const moduleId of previousModules) {
+            if (reachableModules.has(moduleId)) {
+                continue;
+            }
+            removedModules.push(moduleId);
+            const node = this.nodes.get(moduleId);
+            node?.entryRefs.delete(entryId);
+            changed = true;
+        }
+        for (const moduleId of reachableModules) {
+            const node = this.ensureNode(moduleId);
+            if (!previousModules.has(moduleId)) {
+                changed = true;
+            }
+            node.entryRefs.add(entryId);
+        }
+        view.reachableModules = reachableModules;
+        if (changed) {
+            view.version += 1;
+        }
+        this.pruneOrphans(removedModules);
+        this.collectGarbage();
+        return sortStrings(reachableModules);
+    }
+    getEntryModules(entryId) {
+        const view = this.entries.get(entryId);
+        if (!view) {
+            return [];
+        }
+        return sortStrings(view.reachableModules);
+    }
+    hasEntry(entryId) {
+        return this.entries.has(entryId);
+    }
+    applyFileChanges(paths) {
+        const changedModules = sortStrings(paths.map((path) => normalizeModuleId(path)));
+        const impactedEntryIds = new Set();
+        const unknownModules = [];
+        for (const moduleId of changedModules) {
+            const node = this.nodes.get(moduleId);
+            if (!node) {
+                unknownModules.push(moduleId);
+            }
+            else {
+                this.markDirtyUpstream(moduleId, impactedEntryIds);
+            }
+            const rootedEntries = this.entryRoots.get(moduleId);
+            if (!rootedEntries) {
+                continue;
+            }
+            for (const entryId of rootedEntries) {
+                impactedEntryIds.add(entryId);
+            }
+        }
+        this.collectGarbage();
+        return {
+            changedModules,
+            impactedEntryIds: sortStrings(impactedEntryIds),
+            unknownModules: sortStrings(unknownModules),
+        };
+    }
+    collectGarbage() {
+        const now = this.now();
+        if (Number.isFinite(this.entryTtlMs)) {
+            const staleEntries = Array.from(this.entries.values())
+                .filter((entry) => now - entry.lastAccessAt > this.entryTtlMs)
+                .map((entry) => entry.id);
+            for (const entryId of staleEntries) {
+                this.removeEntry(entryId);
+            }
+        }
+        if (Number.isFinite(this.maxEntries) && this.entries.size > this.maxEntries) {
+            const coldEntries = Array.from(this.entries.values())
+                .sort((left, right) => left.lastAccessAt - right.lastAccessAt)
+                .map((entry) => entry.id);
+            for (const entryId of coldEntries) {
+                if (this.entries.size <= this.maxEntries) {
+                    break;
+                }
+                this.removeEntry(entryId);
+            }
+        }
+        if (Number.isFinite(this.maxNodes) && this.nodes.size > this.maxNodes) {
+            const coldEntries = Array.from(this.entries.values())
+                .sort((left, right) => left.lastAccessAt - right.lastAccessAt)
+                .map((entry) => entry.id);
+            for (const entryId of coldEntries) {
+                if (this.nodes.size <= this.maxNodes) {
+                    break;
+                }
+                this.removeEntry(entryId);
+            }
+        }
+    }
+    snapshot() {
+        const moduleGraph = {};
+        const entryToModules = {};
+        const moduleToEntries = {};
+        const moduleIds = sortStrings(this.nodes.keys());
+        for (const moduleId of moduleIds) {
+            const node = this.nodes.get(moduleId);
+            if (!node) {
+                continue;
+            }
+            moduleGraph[moduleId] = sortStrings(node.deps);
+            moduleToEntries[moduleId] = sortStrings(node.entryRefs);
+        }
+        const entryIds = sortStrings(this.entries.keys());
+        for (const entryId of entryIds) {
+            const view = this.entries.get(entryId);
+            if (!view) {
+                continue;
+            }
+            entryToModules[entryId] = sortStrings(view.reachableModules);
+        }
+        return {
+            moduleGraph,
+            entryToModules,
+            moduleToEntries,
+        };
+    }
+    stats() {
+        return {
+            nodeCount: this.nodes.size,
+            entryCount: this.entries.size,
+            visitGeneration: this.visitGeneration,
+        };
+    }
+    ensureNode(moduleId) {
+        const existing = this.nodes.get(moduleId);
+        if (existing) {
+            return existing;
+        }
+        const created = {
+            id: moduleId,
+            deps: new Set(),
+            parents: new Set(),
+            entryRefs: new Set(),
+            contentHash: null,
+            parsed: false,
+            dirty: true,
+            lastVisitedGeneration: 0,
+            lastAccessAt: this.now(),
+        };
+        this.nodes.set(moduleId, created);
+        return created;
+    }
+    collectReachableModules(rootModuleId) {
+        this.visitGeneration += 1;
+        const generation = this.visitGeneration;
+        const reachable = new Set();
+        const stack = [rootModuleId];
+        while (stack.length > 0) {
+            const moduleId = stack.pop();
+            if (!moduleId) {
+                continue;
+            }
+            const node = this.ensureNode(moduleId);
+            // Deduplicate traversal inside the same rebuild batch without allocating an extra visited set.
+            if (node.lastVisitedGeneration === generation) {
+                continue;
+            }
+            node.lastVisitedGeneration = generation;
+            node.lastAccessAt = this.now();
+            reachable.add(moduleId);
+            this.refreshNode(node);
+            for (const depId of node.deps) {
+                stack.push(depId);
+            }
+        }
+        return reachable;
+    }
+    refreshNode(node) {
+        if (node.parsed && !node.dirty) {
+            return;
+        }
+        const source = this.readSource(node.id);
+        const nextHash = source === null ? null : hash(source);
+        // Keep existing edges when content hash is identical even if the node was marked dirty by upstream propagation.
+        if (node.parsed && node.contentHash === nextHash) {
+            node.dirty = false;
+            return;
+        }
+        const nextDeps = source === null ? [] : this.resolveDependencies(node.id, source);
+        this.reconcileNodeDeps(node, nextDeps);
+        node.contentHash = nextHash;
+        node.parsed = true;
+        node.dirty = false;
+    }
+    resolveDependencies(moduleId, source) {
+        const baseDir = dirname(moduleId);
+        const dependencies = [];
+        for (const specifier of extractImportSpecifiers(source)) {
+            if (!specifier.startsWith(".")) {
+                continue;
+            }
+            const resolved = resolveModulePath(baseDir, specifier, this.extensions);
+            if (!resolved) {
+                continue;
+            }
+            dependencies.push(normalizeModuleId(resolved));
+        }
+        return sortStrings(dependencies);
+    }
+    reconcileNodeDeps(node, nextDeps) {
+        const next = new Set(nextDeps);
+        for (const depId of node.deps) {
+            if (next.has(depId)) {
+                continue;
+            }
+            const depNode = this.nodes.get(depId);
+            depNode?.parents.delete(node.id);
+        }
+        for (const depId of next) {
+            if (node.deps.has(depId)) {
+                continue;
+            }
+            const depNode = this.ensureNode(depId);
+            depNode.parents.add(node.id);
+        }
+        node.deps = next;
+    }
+    readSource(moduleId) {
+        try {
+            return readFileSync(moduleId, "utf-8");
+        }
+        catch {
+            return null;
+        }
+    }
+    markDirtyUpstream(moduleId, impactedEntryIds) {
+        const stack = [moduleId];
+        const visited = new Set();
+        while (stack.length > 0) {
+            const currentId = stack.pop();
+            if (!currentId || visited.has(currentId)) {
+                continue;
+            }
+            visited.add(currentId);
+            const node = this.nodes.get(currentId);
+            if (!node) {
+                continue;
+            }
+            node.dirty = true;
+            for (const entryId of node.entryRefs) {
+                impactedEntryIds.add(entryId);
+            }
+            // Parent propagation lets us conservatively invalidate every entry path that can reach the changed module.
+            for (const parentId of node.parents) {
+                stack.push(parentId);
+            }
+        }
+    }
+    detachEntryRefs(entryId, moduleIds) {
+        for (const moduleId of moduleIds) {
+            const node = this.nodes.get(moduleId);
+            node?.entryRefs.delete(entryId);
+        }
+    }
+    pruneOrphans(seedModuleIds) {
+        const stack = Array.from(seedModuleIds);
+        const visited = new Set();
+        while (stack.length > 0) {
+            const moduleId = stack.pop();
+            if (!moduleId || visited.has(moduleId)) {
+                continue;
+            }
+            visited.add(moduleId);
+            const node = this.nodes.get(moduleId);
+            if (!node) {
+                continue;
+            }
+            if (node.entryRefs.size > 0 || node.parents.size > 0) {
+                continue;
+            }
+            this.nodes.delete(moduleId);
+            for (const depId of node.deps) {
+                const depNode = this.nodes.get(depId);
+                depNode?.parents.delete(moduleId);
+                stack.push(depId);
+            }
+        }
+    }
+    indexEntryRoot(entryId, rootModuleId) {
+        const rootedEntries = this.entryRoots.get(rootModuleId) ?? new Set();
+        rootedEntries.add(entryId);
+        this.entryRoots.set(rootModuleId, rootedEntries);
+    }
+    unindexEntryRoot(entryId, rootModuleId) {
+        const rootedEntries = this.entryRoots.get(rootModuleId);
+        if (!rootedEntries) {
+            return;
+        }
+        rootedEntries.delete(entryId);
+        if (rootedEntries.size === 0) {
+            this.entryRoots.delete(rootModuleId);
+        }
+    }
+}
+export const createDynamicModuleGraphManager = (options = {}) => new DynamicModuleGraphManagerImpl(options);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@tyndall/dynamic-graph",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@tyndall/shared": "workspace:*"
+  }
+}