modviz 0.1.2

package/dist/shared/modviz-compare.js

@@ -0,0 +1,120 @@
+const sortStrings = (values) => Array.from(values).sort((left, right) => left.localeCompare(right));
+const getEdgeSet = (graph) => new Set(graph.nodes.flatMap((node) => node.importees.map((importee) => `${node.path} -> ${importee}`)));
+const getExternalPackageName = (nodePath, packageName) => {
+    if (!nodePath.includes("node_modules")) {
+        return packageName ?? "external";
+    }
+    if (packageName && packageName !== "node_modules") {
+        return packageName;
+    }
+    const segments = nodePath.split(/[\\/]/).filter(Boolean);
+    const nodeModulesIndex = segments.lastIndexOf("node_modules");
+    if (nodeModulesIndex === -1) {
+        return "node_modules";
+    }
+    const scopeOrName = segments[nodeModulesIndex + 1];
+    const maybeName = segments[nodeModulesIndex + 2];
+    if (!scopeOrName) {
+        return "node_modules";
+    }
+    return scopeOrName.startsWith("@") && maybeName ? `${scopeOrName}/${maybeName}` : scopeOrName;
+};
+const getExternalPackageSet = (graph) => new Set(graph.nodes
+    .filter((node) => node.path.includes("node_modules"))
+    .map((node) => getExternalPackageName(node.path, node.package?.name))
+    .filter(Boolean));
+const getNodeMap = (graph) => new Map(graph.nodes.map((node) => [node.path, node]));
+const setDifference = (left, right) => {
+    const values = new Set();
+    for (const value of left) {
+        if (!right.has(value)) {
+            values.add(value);
+        }
+    }
+    return values;
+};
+export const buildModvizGraphComparison = (baseline, current) => {
+    const baselineNodes = getNodeMap(baseline);
+    const currentNodes = getNodeMap(current);
+    const baselineNodePaths = new Set(baselineNodes.keys());
+    const currentNodePaths = new Set(currentNodes.keys());
+    const baselineEdges = getEdgeSet(baseline);
+    const currentEdges = getEdgeSet(current);
+    const baselineWorkspacePackages = new Set(baseline.metadata.packages.map((pkg) => pkg.name));
+    const currentWorkspacePackages = new Set(current.metadata.packages.map((pkg) => pkg.name));
+    const baselineExternalPackages = getExternalPackageSet(baseline);
+    const currentExternalPackages = getExternalPackageSet(current);
+    const changedNodes = [];
+    for (const [nodePath, baselineNode] of baselineNodes.entries()) {
+        const currentNode = currentNodes.get(nodePath);
+        if (!currentNode) {
+            continue;
+        }
+        const deltaMagnitude = Math.abs(currentNode.importedBy.length - baselineNode.importedBy.length) +
+            Math.abs(currentNode.importees.length - baselineNode.importees.length) +
+            Math.abs(currentNode.imports.length - baselineNode.imports.length);
+        if (deltaMagnitude === 0) {
+            continue;
+        }
+        changedNodes.push({
+            path: nodePath,
+            baselineIncoming: baselineNode.importedBy.length,
+            currentIncoming: currentNode.importedBy.length,
+            baselineOutgoing: baselineNode.importees.length,
+            currentOutgoing: currentNode.importees.length,
+            baselineImports: baselineNode.imports.length,
+            currentImports: currentNode.imports.length,
+            deltaMagnitude,
+        });
+    }
+    changedNodes.sort((left, right) => right.deltaMagnitude - left.deltaMagnitude || left.path.localeCompare(right.path));
+    return {
+        baselineGeneratedAt: baseline.metadata.generatedAt ?? null,
+        currentGeneratedAt: current.metadata.generatedAt ?? null,
+        summary: {
+            baselineEdges: baselineEdges.size,
+            baselineExternalPackages: baselineExternalPackages.size,
+            baselineImportStatements: baseline.nodes.reduce((sum, node) => sum + node.imports.length, 0),
+            baselineNodes: baseline.nodes.length,
+            baselineWorkspacePackages: baselineWorkspacePackages.size,
+            currentEdges: currentEdges.size,
+            currentExternalPackages: currentExternalPackages.size,
+            currentImportStatements: current.nodes.reduce((sum, node) => sum + node.imports.length, 0),
+            currentNodes: current.nodes.length,
+            currentWorkspacePackages: currentWorkspacePackages.size,
+        },
+        addedEdges: sortStrings(setDifference(currentEdges, baselineEdges)),
+        addedExternalPackages: sortStrings(setDifference(currentExternalPackages, baselineExternalPackages)),
+        addedNodes: sortStrings(setDifference(currentNodePaths, baselineNodePaths)),
+        addedWorkspacePackages: sortStrings(setDifference(currentWorkspacePackages, baselineWorkspacePackages)),
+        changedNodes,
+        removedEdges: sortStrings(setDifference(baselineEdges, currentEdges)),
+        removedExternalPackages: sortStrings(setDifference(baselineExternalPackages, currentExternalPackages)),
+        removedNodes: sortStrings(setDifference(baselineNodePaths, currentNodePaths)),
+        removedWorkspacePackages: sortStrings(setDifference(baselineWorkspacePackages, currentWorkspacePackages)),
+    };
+};
+export const renderModvizGraphComparison = (comparison, options = {}) => {
+    const limit = Number.isFinite(options.limit) ? Math.max(1, Math.trunc(options.limit ?? 10)) : 10;
+    const changedNodes = comparison.changedNodes.slice(0, limit);
+    return [
+        "",
+        "Graph diff",
+        `- Nodes: ${comparison.summary.baselineNodes} -> ${comparison.summary.currentNodes} (${comparison.summary.currentNodes - comparison.summary.baselineNodes >= 0 ? "+" : ""}${comparison.summary.currentNodes - comparison.summary.baselineNodes})`,
+        `- Edges: ${comparison.summary.baselineEdges} -> ${comparison.summary.currentEdges} (${comparison.summary.currentEdges - comparison.summary.baselineEdges >= 0 ? "+" : ""}${comparison.summary.currentEdges - comparison.summary.baselineEdges})`,
+        `- Import statements: ${comparison.summary.baselineImportStatements} -> ${comparison.summary.currentImportStatements} (${comparison.summary.currentImportStatements - comparison.summary.baselineImportStatements >= 0 ? "+" : ""}${comparison.summary.currentImportStatements - comparison.summary.baselineImportStatements})`,
+        `- Workspace packages: ${comparison.summary.baselineWorkspacePackages} -> ${comparison.summary.currentWorkspacePackages}`,
+        `- External packages: ${comparison.summary.baselineExternalPackages} -> ${comparison.summary.currentExternalPackages}`,
+        `- Added modules: ${comparison.addedNodes.length}`,
+        `- Removed modules: ${comparison.removedNodes.length}`,
+        `- Added edges: ${comparison.addedEdges.length}`,
+        `- Removed edges: ${comparison.removedEdges.length}`,
+        changedNodes.length > 0
+            ? [
+                "",
+                "Largest direct node deltas",
+                ...changedNodes.map((node) => `- ${node.path}: inbound ${node.baselineIncoming}->${node.currentIncoming}, outbound ${node.baselineOutgoing}->${node.currentOutgoing}, imports ${node.baselineImports}->${node.currentImports}`),
+            ].join("\n")
+            : "",
+    ].filter(Boolean).join("\n");
+};

package/dist/shared/modviz-trace.js

@@ -0,0 +1,244 @@
+const chainCache = new WeakMap();
+const packageReportCache = new WeakMap();
+const nodeReportCache = new WeakMap();
+const normalizeForSearch = (value) => value.trim().toLowerCase();
+const isExternalPath = (value) => value.includes("node_modules");
+const uniqueSorted = (values) => Array.from(new Set(values))
+    .filter(Boolean)
+    .sort((left, right) => left.localeCompare(right));
+export const getTracePackageName = (node) => {
+    if (!node.path.includes("node_modules")) {
+        return node.package?.name ?? null;
+    }
+    if (node.package?.name && node.package.name !== "node_modules") {
+        return node.package.name;
+    }
+    const segments = node.path.split(/[\\/]/).filter(Boolean);
+    const nodeModulesIndex = segments.lastIndexOf("node_modules");
+    if (nodeModulesIndex === -1) {
+        return null;
+    }
+    const scopeOrName = segments[nodeModulesIndex + 1];
+    const maybeName = segments[nodeModulesIndex + 2];
+    if (!scopeOrName) {
+        return null;
+    }
+    return scopeOrName.startsWith("@") && maybeName ? `${scopeOrName}/${maybeName}` : scopeOrName;
+};
+const uniqueChains = (chains) => {
+    const seen = new Set();
+    const nextChains = [];
+    for (const chain of chains) {
+        const key = chain.join(" -> ");
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        nextChains.push(chain);
+    }
+    return nextChains.sort((left, right) => {
+        const byLength = left.length - right.length;
+        return byLength !== 0 ? byLength : left.join("/").localeCompare(right.join("/"));
+    });
+};
+const buildUpstreamChains = (graph, targetPath, maxChains = 40, maxDepth = 28) => {
+    const cacheKey = `${targetPath}::${maxChains}::${maxDepth}`;
+    const cachedGraphChains = chainCache.get(graph);
+    if (cachedGraphChains?.has(cacheKey)) {
+        return cachedGraphChains.get(cacheKey);
+    }
+    const nodeByPath = new Map(graph.nodes.map((node) => [node.path, node]));
+    const entrypoints = new Set(graph.metadata.entrypoints);
+    const results = [];
+    const queue = [[targetPath]];
+    let queueIndex = 0;
+    while (queueIndex < queue.length && results.length < maxChains) {
+        const reverseChain = queue[queueIndex];
+        queueIndex += 1;
+        if (!reverseChain) {
+            continue;
+        }
+        const currentPath = reverseChain[0];
+        const currentNode = nodeByPath.get(currentPath);
+        const importers = uniqueSorted((currentNode?.importedBy ?? []).filter((importerPath) => !reverseChain.includes(importerPath) && nodeByPath.has(importerPath)));
+        if (!currentNode ||
+            importers.length === 0 ||
+            entrypoints.has(currentPath) ||
+            reverseChain.length >= maxDepth) {
+            results.push([...reverseChain].reverse());
+            continue;
+        }
+        importers
+            .sort((left, right) => {
+            const leftExternal = isExternalPath(left);
+            const rightExternal = isExternalPath(right);
+            if (leftExternal !== rightExternal) {
+                return leftExternal ? 1 : -1;
+            }
+            return left.localeCompare(right);
+        })
+            .forEach((importerPath) => {
+            queue.push([importerPath, ...reverseChain]);
+        });
+    }
+    const resolvedChains = uniqueChains(results);
+    const nextCache = cachedGraphChains ?? new Map();
+    nextCache.set(cacheKey, resolvedChains);
+    if (!cachedGraphChains) {
+        chainCache.set(graph, nextCache);
+    }
+    return resolvedChains;
+};
+const getWorkspaceOrigin = (chain) => chain.find((segment) => !isExternalPath(segment)) ?? chain[0] ?? null;
+const getIntroducedThrough = (chain) => {
+    for (let index = 0; index < chain.length; index += 1) {
+        if (!isExternalPath(chain[index])) {
+            continue;
+        }
+        return chain[index - 1] ?? chain[index] ?? null;
+    }
+    return chain.at(-1) ?? null;
+};
+const createTraceMatch = (node, chains) => ({
+    path: node.path,
+    label: node.name,
+    packageName: getTracePackageName(node),
+    type: node.type,
+    targetPaths: [node.path],
+    directImporters: uniqueSorted(node.importedBy),
+    chains,
+    workspaceOrigins: uniqueSorted(chains.map((chain) => getWorkspaceOrigin(chain)).filter(Boolean)),
+    introducedThrough: uniqueSorted(chains.map((chain) => getIntroducedThrough(chain)).filter(Boolean)),
+});
+export const buildPackageTraceReport = (graph, packageQuery, options = {}) => {
+    const { maxChainsPerTarget = 40, maxDepth = 28, maxNodesPerPackage = Number.POSITIVE_INFINITY, } = options;
+    const cacheSuffix = `::${maxChainsPerTarget}::${maxDepth}::${maxNodesPerPackage}`;
+    const normalizedQuery = normalizeForSearch(packageQuery);
+    const cacheKey = `${normalizedQuery}${cacheSuffix}`;
+    const cachedReports = packageReportCache.get(graph);
+    if (cachedReports?.has(cacheKey)) {
+        return cachedReports.get(cacheKey);
+    }
+    const groupedMatches = new Map();
+    const tracedNodeCountByPackage = new Map();
+    graph.nodes
+        .filter((node) => node.path.includes("node_modules"))
+        .filter((node) => {
+        const packageName = getTracePackageName(node);
+        return packageName ? normalizeForSearch(packageName).includes(normalizedQuery) : false;
+    })
+        .forEach((node) => {
+        const packageName = getTracePackageName(node) ?? node.path;
+        const tracedCount = tracedNodeCountByPackage.get(packageName) ?? 0;
+        const canTraceNode = tracedCount < maxNodesPerPackage;
+        const chains = canTraceNode
+            ? buildUpstreamChains(graph, node.path, maxChainsPerTarget, maxDepth)
+            : [];
+        if (canTraceNode) {
+            tracedNodeCountByPackage.set(packageName, tracedCount + 1);
+        }
+        const existing = groupedMatches.get(packageName);
+        if (!existing) {
+            groupedMatches.set(packageName, {
+                path: packageName,
+                label: packageName,
+                packageName,
+                type: "package",
+                targetPaths: [node.path],
+                directImporters: uniqueSorted(node.importedBy),
+                chains,
+                workspaceOrigins: uniqueSorted(chains.map((chain) => getWorkspaceOrigin(chain)).filter(Boolean)),
+                introducedThrough: uniqueSorted(chains.map((chain) => getIntroducedThrough(chain)).filter(Boolean)),
+            });
+            return;
+        }
+        existing.targetPaths = uniqueSorted([...existing.targetPaths, node.path]);
+        existing.directImporters = uniqueSorted([...existing.directImporters, ...node.importedBy]);
+        existing.chains = uniqueChains([...existing.chains, ...chains]);
+        existing.workspaceOrigins = uniqueSorted([
+            ...existing.workspaceOrigins,
+            ...chains.map((chain) => getWorkspaceOrigin(chain)).filter(Boolean),
+        ]);
+        existing.introducedThrough = uniqueSorted([
+            ...existing.introducedThrough,
+            ...chains.map((chain) => getIntroducedThrough(chain)).filter(Boolean),
+        ]);
+    });
+    const matches = Array.from(groupedMatches.values()).sort((left, right) => left.label.localeCompare(right.label));
+    const report = {
+        kind: "package",
+        query: packageQuery,
+        matchedLabels: Array.from(new Set(matches.map((match) => match.packageName).filter(Boolean))).sort((left, right) => left.localeCompare(right)),
+        matches,
+        totalChains: matches.reduce((sum, match) => sum + match.chains.length, 0),
+    };
+    const nextCache = cachedReports ?? new Map();
+    nextCache.set(cacheKey, report);
+    if (!cachedReports) {
+        packageReportCache.set(graph, nextCache);
+    }
+    return report;
+};
+export const buildNodeTraceReport = (graph, nodeQuery, options = {}) => {
+    const { maxChainsPerTarget = 40, maxDepth = 28, maxNodeMatches = Number.POSITIVE_INFINITY, } = options;
+    const cacheSuffix = `::${maxChainsPerTarget}::${maxDepth}::${maxNodeMatches}`;
+    const normalizedQuery = normalizeForSearch(nodeQuery);
+    const cacheKey = `${normalizedQuery}${cacheSuffix}`;
+    const cachedReports = nodeReportCache.get(graph);
+    if (cachedReports?.has(cacheKey)) {
+        return cachedReports.get(cacheKey);
+    }
+    const matches = graph.nodes
+        .filter((node) => {
+        return [node.path, node.name, node.package?.name, node.cluster]
+            .filter(Boolean)
+            .some((value) => normalizeForSearch(String(value)).includes(normalizedQuery));
+    })
+        .slice(0, maxNodeMatches)
+        .map((node) => createTraceMatch(node, buildUpstreamChains(graph, node.path, maxChainsPerTarget, maxDepth)));
+    const report = {
+        kind: "node",
+        query: nodeQuery,
+        matchedLabels: matches.map((match) => match.path),
+        matches,
+        totalChains: matches.reduce((sum, match) => sum + match.chains.length, 0),
+    };
+    const nextCache = cachedReports ?? new Map();
+    nextCache.set(cacheKey, report);
+    if (!cachedReports) {
+        nodeReportCache.set(graph, nextCache);
+    }
+    return report;
+};
+export const renderTraceReport = (report, limit = 10) => {
+    const lines = [
+        `${report.kind === "package" ? "Package" : "Node"} trace for: ${report.query}`,
+        `Matched ${report.matches.length} node(s) across ${report.totalChains} origin chain(s).`,
+        "",
+    ];
+    if (report.matches.length === 0) {
+        lines.push("No matching nodes were found.");
+        return `${lines.join("\n")}\n`;
+    }
+    for (const match of report.matches.slice(0, limit)) {
+        lines.push(`- ${match.path} (${match.type})`);
+        if (match.packageName) {
+            lines.push(`  Package: ${match.packageName}`);
+        }
+        lines.push(`  Matching files: ${match.targetPaths.length}`);
+        lines.push(`  Workspace origins: ${match.workspaceOrigins.join(", ") || "none"}`);
+        lines.push(`  Introduced through: ${match.introducedThrough.join(", ") || "none"}`);
+        lines.push(`  Direct importers: ${match.directImporters.join(", ") || "none"}`);
+        for (const chain of match.chains.slice(0, limit)) {
+            lines.push(`  Chain: ${chain.join(" -> ")}`);
+        }
+        if (match.chains.length > limit) {
+            lines.push(`  +${match.chains.length - limit} more chain(s)`);
+        }
+        lines.push("");
+    }
+    if (report.matches.length > limit) {
+        lines.push(`+${report.matches.length - limit} more matching node(s)`);
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+};

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "modviz",
+  "type": "module",
+  "version": "0.1.2",
+  "description": "CLI and web UI for analyzing and visualizing TypeScript and JavaScript module dependency graphs.",
+  "keywords": [
+    "module",
+    "graph",
+    "cli",
+    "transitive",
+    "import",
+    "export",
+    "dependency-graph",
+    "import-analysis",
+    "javascript",
+    "module-graph",
+    "typescript",
+    "visualization"
+  ],
+  "license": "ISC",
+  "author": "Alexandre Stahmer",
+  "homepage": "https://github.com/astahmer/modviz#readme",
+  "bugs": {
+    "url": "https://github.com/astahmer/modviz/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astahmer/modviz.git"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "engines": {
+    "node": ">=22.12.0",
+    "pnpm": ">=10.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/mod/index.js",
+  "exports": {
+    ".": "./dist/mod/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "modviz": "./dist/mod/cli.js"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "cli": "node mod/cli.ts",
+    "cli:build": "tsgo --ignoreConfig --skipLibCheck mod/cli.ts mod/index.ts --types node --outDir dist --target es2022 --module nodenext --moduleResolution nodenext --allowImportingTsExtensions --rewriteRelativeImportExtensions",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "fmt": "oxfmt --write .",
+    "fmt:check": "oxfmt --check .",
+    "lint": "oxlint --import-plugin --react-plugin --vitest-plugin --jsx-a11y-plugin --node-plugin .",
+    "lint:fix": "pnpm run lint -- --fix",
+    "dev": "vite dev",
+    "test": "vitest run",
+    "typecheck": "tsgo -p tsconfig.json --noEmit",
+    "typecheck:tsgo": "tsgo -p tsconfig.json --noEmit",
+    "check": "pnpm run lint && pnpm run typecheck",
+    "build": "pnpm run clean && pnpm vite build && pnpm run cli:build && pnpm run typecheck",
+    "prepublishOnly": "pnpm run check && pnpm run test",
+    "prepack": "pnpm run build",
+    "release": "release-it",
+    "release:dry-run": "release-it --dry-run --no-npm.publish --git.requireCleanWorkingDir=false --git.requireUpstream=false --git.push=false",
+    "start": "node dist/mod/runtime-host.js"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "3.0.52",
+    "@ark-ui/react": "5.36.0",
+    "@astahmer/module-graph": "0.14.2",
+    "@chenglou/pretext": "0.0.5",
+    "@radix-ui/react-dialog": "1.1.15",
+    "@radix-ui/react-popover": "1.1.15",
+    "@radix-ui/react-slot": "1.2.4",
+    "@react-sigma/core": "5.0.6",
+    "@react-sigma/graph-search": "5.0.6",
+    "@react-sigma/layout-circlepack": "5.0.6",
+    "@react-sigma/layout-circular": "5.0.6",
+    "@react-sigma/layout-core": "5.0.6",
+    "@react-sigma/layout-force": "5.0.6",
+    "@react-sigma/layout-forceatlas2": "5.0.6",
+    "@react-sigma/layout-noverlap": "5.0.6",
+    "@react-sigma/layout-random": "5.0.6",
+    "@react-sigma/minimap": "5.0.6",
+    "@sigma/utils": "3.0.0",
+    "@tanstack/react-router": "1.168.19",
+    "@tanstack/react-router-devtools": "1.166.13",
+    "@tanstack/react-start": "1.167.35",
+    "@tanstack/react-virtual": "3.13.23",
+    "@xstate/store": "3.17.1",
+    "ai": "6.0.159",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "cmdk": "1.1.1",
+    "find-workspaces": "0.3.1",
+    "graphology": "0.26.0",
+    "graphology-communities-louvain": "2.0.2",
+    "graphology-types": "0.24.8",
+    "iwanthue": "2.0.0",
+    "leva": "0.10.1",
+    "lucide-react": "1.8.0",
+    "magic-string": "0.30.21",
+    "nanovis": "1.0.0",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "react-icons": "5.6.0",
+    "resolve-pkg-maps": "1.0.0",
+    "sigma": "3.0.2",
+    "tailwind-merge": "3.5.0",
+    "vite": "8.0.8",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "4.2.2",
+    "@types/node": "25.6.0",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@typescript/native-preview": "7.0.0-dev.20260413.1",
+    "@vitejs/plugin-react": "6.0.1",
+    "autoprefixer": "10.4.27",
+    "oxfmt": "0.45.0",
+    "oxlint": "1.60.0",
+    "postcss": "8.5.9",
+    "release-it": "19.2.4",
+    "shadcn": "4.2.0",
+    "tailwindcss": "4.2.2",
+    "tw-animate-css": "1.4.0",
+    "typescript": "6.0.2",
+    "vitest": "4.1.4"
+  }
+}