nx-visualizer 1.0.0

package/README.md

@@ -0,0 +1,75 @@
+# nx-visualizer
+
+CLI that reads an Nx project graph and reports **circular dependencies**, **orphan projects** (nothing depends on them), and **layer violations** against a simple apps → features → shared → core model.
+
+## Prerequisites
+
+- **Node.js** (current LTS is fine)
+- An **Nx workspace** where you can export the dependency graph
+
+## Install
+
+From this repository:
+
+```bash
+npm install
+npm run build
+```
+
+Compiled output is written to `dist/`.
+
+## Quick start
+
+Run everything from the **root of your Nx workspace** (the same folder where `nx.json` lives).
+
+### 1. Export the graph
+
+```bash
+npx nx graph --file=graph.json
+```
+
+This creates `graph.json` in the current directory. The analyzer expects that exact filename in the working directory.
+
+### 2. Analyze
+
+Run the built CLI directly:
+
+```bash
+npx nx-visualizer analyze
+```
+
+## What you get
+
+| Check | Meaning |
+|--------|--------|
+| **Circular dependencies** | Projects involved in dependency cycles (first node hit when a cycle is detected). |
+| **Orphan libraries** | Projects that never appear as a dependency target—often unused entry points or mis-wired libs. |
+| **Layer violations** | Edges that go “up” the stack (e.g. a lower layer depending on a higher one). |
+
+### Default layers
+
+Layers are inferred from project names/paths using these prefixes:
+
+| Layer | Path hints |
+|--------|------------|
+| `apps` | `apps/` |
+| `features` | `libs/features/` |
+| `shared` | `libs/shared/` |
+| `core` | `libs/core/` |
+
+Anything else is treated as `unknown` for layer rules.
+
+Allowed direction is **apps → features → shared → core** (higher index must not depend on lower index in that list). Violations are listed as `source → target`.
+
+## Customizing layers
+
+The prefix map lives in `src/cli.ts` as `DEFAULT_LAYERS`. Adjust it to match your repo’s folder layout, then rebuild (`npm run build`).
+
+## Troubleshooting
+
+- **`graph.json not found`** — Run `nx graph --file=graph.json` from the Nx workspace root, or run the analyzer with that file present in the current working directory.
+- **Empty or surprising results** — Confirm `graph.json` is fresh and that you are analyzing the same workspace you exported.
+
+## License
+
+ISC

package/dist/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "fs";
+import chalk from "chalk";
+const program = new Command();
+program
+    .name("nx-visualizer")
+    .description("Nx visualizer")
+    .version("1.0.0");
+const DEFAULT_LAYERS = {
+    apps: ["apps/"],
+    features: ["libs/features/"],
+    shared: ["libs/shared/"],
+    core: ["libs/core/"],
+};
+function detectLayer(projectName) {
+    for (const [layer, prefixes] of Object.entries(DEFAULT_LAYERS)) {
+        for (const prefix of prefixes) {
+            if (projectName.includes(prefix)) {
+                return layer;
+            }
+        }
+    }
+    return "unknown";
+}
+function loadGraph() {
+    const file = "graph.json";
+    if (!fs.existsSync(file)) {
+        console.log(chalk.red("graph.json not found"));
+        console.log("Run: nx graph --file=graph.json");
+        process.exit(1);
+    }
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+}
+function detectCircularDeps(graph) {
+    const visited = new Set();
+    const stack = new Set();
+    const cycles = [];
+    function dfs(node) {
+        if (stack.has(node)) {
+            cycles.push(node);
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        stack.add(node);
+        const deps = graph.dependencies[node] || [];
+        for (const dep of deps) {
+            dfs(dep.target);
+        }
+        stack.delete(node);
+    }
+    Object.keys(graph.nodes).forEach(dfs);
+    return cycles;
+}
+function detectOrphans(graph) {
+    const inbound = new Set();
+    Object.values(graph.dependencies).forEach((deps) => {
+        deps.forEach((dep) => inbound.add(dep.target));
+    });
+    return Object.keys(graph.nodes).filter((node) => !inbound.has(node));
+}
+function detectLayerViolations(graph) {
+    const violations = [];
+    const layerOrder = ["apps", "features", "shared", "core"];
+    Object.entries(graph.dependencies).forEach(([source, deps]) => {
+        const sourceLayer = detectLayer(source);
+        deps.forEach(({ target }) => {
+            const targetLayer = detectLayer(target);
+            if (layerOrder.indexOf(sourceLayer) <
+                layerOrder.indexOf(targetLayer)) {
+                violations.push(`${source} → ${target}`);
+            }
+        });
+    });
+    return violations;
+}
+program.command("analyze").action(() => {
+    const graph = loadGraph();
+    console.log(chalk.blue("\nAnalyzing Nx workspace architecture...\n"));
+    const circular = detectCircularDeps(graph);
+    const orphans = detectOrphans(graph);
+    const violations = detectLayerViolations(graph);
+    console.log(chalk.yellow(`Circular dependencies: ${circular.length}`));
+    circular.forEach((c) => console.log(chalk.gray(` - ${c}`)));
+    console.log(chalk.yellow(`\nOrphan libraries: ${orphans.length}`));
+    orphans.forEach((o) => console.log(chalk.gray(` - ${o}`)));
+    console.log(chalk.red(`\nLayer violations: ${violations.length}`));
+    violations.forEach((v) => console.log(chalk.gray(` - ${v}`)));
+    console.log(chalk.green("\nAnalysis complete.\n"));
+});
+program.parse(process.argv);
+//# sourceMappingURL=cli.js.map

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "nx-visualizer",
+  "version": "1.0.0",
+  "description": "",
+  "main": "src/cli.ts",
+  "type": "module",
+  "bin": {
+    "nx-visualizer": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "fs";
+import chalk from "chalk";
+
+const program = new Command();
+
+program
+  .name("nx-visualizer")
+  .description("Nx visualizer")
+  .version("1.0.0");
+
+type Graph = {
+  nodes: Record<string, any>;
+  dependencies: Record<string, { target: string }[]>;
+};
+
+const DEFAULT_LAYERS = {
+  apps: ["apps/"],
+  features: ["libs/features/"],
+  shared: ["libs/shared/"],
+  core: ["libs/core/"],
+};
+
+function detectLayer(projectName: string) {
+  for (const [layer, prefixes] of Object.entries(DEFAULT_LAYERS)) {
+    for (const prefix of prefixes) {
+      if (projectName.includes(prefix)) {
+        return layer;
+      }
+    }
+  }
+  return "unknown";
+}
+
+function loadGraph(): Graph {
+  const file = "graph.json";
+
+  if (!fs.existsSync(file)) {
+    console.log(chalk.red("graph.json not found"));
+    console.log("Run: nx graph --file=graph.json");
+    process.exit(1);
+  }
+
+  return JSON.parse(fs.readFileSync(file, "utf-8"));
+}
+
+function detectCircularDeps(graph: Graph) {
+  const visited = new Set<string>();
+  const stack = new Set<string>();
+  const cycles: string[] = [];
+
+  function dfs(node: string) {
+    if (stack.has(node)) {
+      cycles.push(node);
+      return;
+    }
+
+    if (visited.has(node)) return;
+
+    visited.add(node);
+    stack.add(node);
+
+    const deps = graph.dependencies[node] || [];
+
+    for (const dep of deps) {
+      dfs(dep.target);
+    }
+
+    stack.delete(node);
+  }
+
+  Object.keys(graph.nodes).forEach(dfs);
+
+  return cycles;
+}
+
+function detectOrphans(graph: Graph) {
+  const inbound = new Set<string>();
+
+  Object.values(graph.dependencies).forEach((deps) => {
+    deps.forEach((dep) => inbound.add(dep.target));
+  });
+
+  return Object.keys(graph.nodes).filter(
+    (node) => !inbound.has(node)
+  );
+}
+
+function detectLayerViolations(graph: Graph) {
+  const violations: string[] = [];
+
+  const layerOrder = ["apps", "features", "shared", "core"];
+
+  Object.entries(graph.dependencies).forEach(
+    ([source, deps]) => {
+      const sourceLayer = detectLayer(source);
+
+      deps.forEach(({ target }) => {
+        const targetLayer = detectLayer(target);
+
+        if (
+          layerOrder.indexOf(sourceLayer) <
+          layerOrder.indexOf(targetLayer)
+        ) {
+          violations.push(
+            `${source} → ${target}`
+          );
+        }
+      });
+    }
+  );
+
+  return violations;
+}
+
+program.command("analyze").action(() => {
+  const graph = loadGraph();
+
+  console.log(
+    chalk.blue("\nAnalyzing Nx workspace architecture...\n")
+  );
+
+  const circular = detectCircularDeps(graph);
+  const orphans = detectOrphans(graph);
+  const violations = detectLayerViolations(graph);
+
+  console.log(
+    chalk.yellow(
+      `Circular dependencies: ${circular.length}`
+    )
+  );
+
+  circular.forEach((c) =>
+    console.log(chalk.gray(` - ${c}`))
+  );
+
+  console.log(
+    chalk.yellow(`\nOrphan libraries: ${orphans.length}`)
+  );
+
+  orphans.forEach((o) =>
+    console.log(chalk.gray(` - ${o}`))
+  );
+
+  console.log(
+    chalk.red(
+      `\nLayer violations: ${violations.length}`
+    )
+  );
+
+  violations.forEach((v) =>
+    console.log(chalk.gray(` - ${v}`))
+  );
+
+  console.log(
+    chalk.green("\nAnalysis complete.\n")
+  );
+});
+
+program.parse(process.argv);

package/tsconfig.json

@@ -0,0 +1,46 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    // "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": ["node"],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "rootDir": "src",
+    "outDir": "./dist",
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}