@anirudw/repolens 0.1.3 → 0.2.0

package/README.md

@@ -1,42 +1,66 @@
-# repolens
+# Repolens
 
-A CLI tool to visualize repository dependency graphs by parsing ASTs across multiple languages.
+**A cross-platform, multi-lingual repository intelligence CLI.**
 
-## Features
+Repolens analyzes your codebase using tree-sitter ASTs to map dependency networks, identify architectural pillars, and calculate coupling metrics.
 
-- **Multi-language support**: JavaScript, TypeScript, Python, Java, and Markdown
-- **Smart scanning**: Respects `.gitignore` rules and common build directories
-- **Dependency analysis**: Builds a graph of imports and references
-- **Multiple outputs**: Terminal summaries, JSON export, and interactive HTML visualization
+[![NPM Version](https://img.shields.io/npm/v/@anirudw/repolens)](https://www.npmjs.com/package/@anirudw/repolens)
+[![License](https://img.shields.io/npm/l/@anirudw/repolens)](LICENSE)
 
-## Installation
+## Install
 
 ```bash
-npm install
-npm run build
+npm install -g @anirudw/repolens
 ```
 
-## Usage
+## Quick Start
 
 ```bash
-# Scan current directory
-repolens
+# Analyze a repository
+repolens ./my-project
 
-# Scan specific directory
-repolens ./path/to/repo
+# Export dependency graph
+repolens ./my-project --format json --output graph.json
 
-# With verbose output
-repolens --verbose
+# Find implementations of an interface
+repolens ./my-project --implements ILogger
 
-# Output formats
-repolens --format json --output graph.json
-repolens --format html --output graph.html
+# View architectural health metrics
+repolens ./my-project --health
 ```
 
-## Supported Languages
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-v, --verbose` | Enable verbose output |
+| `-f, --format` | Output format: `text` (default) or `json` |
+| `-o, --output <file>` | Output file path |
+| `-i, --implements <name>` | Find files implementing an interface |
+| `--health` | Display architectural health metrics |
+
+## Features
+
+- **Multi-lingual AST parsing** — JavaScript, TypeScript, Python, Java, Markdown
+- **Path resolution** — Automatically resolves local imports
+- **PageRank centrality** — Identifies the most relied-upon files
+- **Entry-point detection** — Flags critical entry points
+- **Interface registry** — Track class/interface relationships
+- **Health metrics** — Coupling (Ca, Ce) and instability (I)
+
+## Health Metrics
+
+The `--health` flag calculates coupling metrics:
+
+- **Ca (Afferent Coupling)** — Files that depend on this file
+- **Ce (Efferent Coupling)** — Files this file depends on
+- **Instability** — `I = Ce / (Ca + Ce)`
+
+| Value | Meaning |
+|-------|---------|
+| ~0 | Stable core dependency |
+| ~1 | Highly unstable (fragile) |
+
+## License
 
-- JavaScript/JSX (.js, .jsx)
-- TypeScript/TSX (.ts, .tsx)
-- Python (.py)
-- Java (.java)
-- Markdown (.md)
+MIT

package/dist/chunk-PE6PHNN5.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __glob = (map) => (path) => {
+  var fn = map[path];
+  if (fn) return fn();
+  throw new Error("Module not found in bundle: " + path);
+};
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+export {
+  __require,
+  __glob,
+  __esm,
+  __commonJS
+};

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import "./chunk-PE6PHNN5.js";
 
 // src/cli/commands.ts
 import { Command } from "commander";
@@ -237,34 +238,52 @@ var MarkdownParser = class {
 // src/parser/strategies/javascript.ts
 var TreeSitterParser;
 var JavaScript;
+var TypeScript;
 async function ensureLoaded() {
   if (!TreeSitterParser) {
-    const [ts, js] = await Promise.all([
+    const [ts, js, tst] = await Promise.all([
       import("tree-sitter"),
-      import("tree-sitter-javascript")
+      import("tree-sitter-javascript"),
+      import("./node-EEBHCXXR.js")
     ]);
     TreeSitterParser = ts.default;
     JavaScript = js.default;
+    TypeScript = tst.default.typescript;
   }
 }
 var JavaScriptParser = class {
-  parser = null;
-  async ensureParser() {
-    if (!this.parser) {
-      await ensureLoaded();
-      this.parser = new TreeSitterParser();
-      this.parser.setLanguage(JavaScript);
+  jsParser = null;
+  tsParser = null;
+  async ensureParser(filePath) {
+    await ensureLoaded();
+    const isTsFile = filePath.endsWith(".ts") || filePath.endsWith(".tsx");
+    if (isTsFile) {
+      if (!this.tsParser) {
+        this.tsParser = new TreeSitterParser();
+        this.tsParser.setLanguage(TypeScript);
+      }
+      return this.tsParser;
+    } else {
+      if (!this.jsParser) {
+        this.jsParser = new TreeSitterParser();
+        this.jsParser.setLanguage(JavaScript);
+      }
+      return this.jsParser;
     }
-    return this.parser;
   }
   async parse(filePath, content) {
-    const parser = await this.ensureParser();
+    const parser = await this.ensureParser(filePath);
     const tree = parser.parse(content);
     const rootNode = tree.rootNode;
     const dependencies = [];
     const imports = /* @__PURE__ */ new Set();
     const sourceModules = [];
+    const definedClasses = [];
+    const definedInterfaces = [];
+    const implementsInterfaces = [];
     this.extractImports(rootNode, dependencies, imports, sourceModules);
+    this.extractClassData(rootNode, definedClasses, implementsInterfaces);
+    this.extractInterfaceData(rootNode, definedInterfaces);
     const heuristics = {};
     const allImports = [...imports, ...sourceModules].map((s) => s.toLowerCase());
     heuristics.isReact = allImports.some((i) => i === "react" || i === "@types/react");
@@ -279,7 +298,10 @@ var JavaScriptParser = class {
       dependencies,
       metadata: {
         sizeBytes: Buffer.byteLength(content, "utf-8"),
-        heuristics
+        heuristics,
+        definedClasses,
+        definedInterfaces,
+        implementsInterfaces
       }
     };
   }
@@ -293,6 +315,45 @@ var JavaScriptParser = class {
       this.extractImports(child, dependencies, imports, sourceModules);
     }
   }
+  extractClassData(node, definedClasses, implementsInterfaces) {
+    if (node.type === "class_declaration") {
+      const nameNode = node.childForFieldName("name") || this.getChildByType(node, "type_identifier");
+      if (nameNode) {
+        definedClasses.push(nameNode.text);
+      }
+      const classHeritage = node.childForFieldName("heritage") || this.getChildByType(node, "class_heritage");
+      if (classHeritage) {
+        const implementsClause = classHeritage.childForFieldName("interfaces") || this.getChildByType(classHeritage, "implements_clause");
+        if (implementsClause) {
+          for (const child of implementsClause.children) {
+            if (child.type === "type_identifier" || child.type === "identifier") {
+              implementsInterfaces.push(child.text);
+            }
+          }
+        }
+      }
+    }
+    for (const child of node.children) {
+      this.extractClassData(child, definedClasses, implementsInterfaces);
+    }
+  }
+  extractInterfaceData(node, definedInterfaces) {
+    if (node.type === "interface_declaration") {
+      const nameNode = node.childForFieldName("name") || this.getChildByType(node, "type_identifier");
+      if (nameNode) {
+        definedInterfaces.push(nameNode.text);
+      }
+    }
+    for (const child of node.children) {
+      this.extractInterfaceData(child, definedInterfaces);
+    }
+  }
+  getChildByType(node, type) {
+    for (const child of node.children) {
+      if (child.type === type) return child;
+    }
+    return null;
+  }
   extractImportStatement(node, dependencies, imports, sourceModules) {
     const sourceNode = node.childForFieldName("source");
     if (sourceNode && sourceNode.type === "string") {
@@ -569,7 +630,12 @@ var JavaParser = class {
     const rootNode = tree.rootNode;
     const dependencies = [];
     const heuristics = {};
+    const definedClasses = [];
+    const definedInterfaces = [];
+    const implementsInterfaces = [];
     this.extractImports(rootNode, dependencies);
+    this.extractClassData(rootNode, definedClasses, implementsInterfaces);
+    this.extractInterfaceData(rootNode, definedInterfaces);
     heuristics.hasMainMethod = this.detectMainMethod(rootNode);
     return {
       id: filePath,
@@ -578,7 +644,10 @@ var JavaParser = class {
       dependencies,
       metadata: {
         sizeBytes: Buffer.byteLength(content, "utf-8"),
-        heuristics
+        heuristics,
+        definedClasses,
+        definedInterfaces,
+        implementsInterfaces
       }
     };
   }
@@ -601,6 +670,41 @@ var JavaParser = class {
       this.extractImports(child, dependencies);
     }
   }
+  extractClassData(node, definedClasses, implementsInterfaces) {
+    if (node.type === "class_declaration") {
+      const nameNode = this.getChildByType(node, "identifier");
+      if (nameNode) {
+        definedClasses.push(nameNode.text);
+      }
+      const interfaces = node.childForFieldName("interfaces");
+      if (interfaces) {
+        const typeList = this.getChildByType(interfaces, "type_list");
+        if (typeList) {
+          for (const child of typeList.children) {
+            if (child.type === "type_identifier" || child.type === "identifier") {
+              implementsInterfaces.push(child.text);
+            } else if (child.type === "scoped_identifier") {
+              implementsInterfaces.push(this.getScopedIdentifierText(child));
+            }
+          }
+        }
+      }
+    }
+    for (const child of node.children) {
+      this.extractClassData(child, definedClasses, implementsInterfaces);
+    }
+  }
+  extractInterfaceData(node, definedInterfaces) {
+    if (node.type === "interface_declaration") {
+      const nameNode = this.getChildByType(node, "identifier");
+      if (nameNode) {
+        definedInterfaces.push(nameNode.text);
+      }
+    }
+    for (const child of node.children) {
+      this.extractInterfaceData(child, definedInterfaces);
+    }
+  }
   detectMainMethod(node) {
     if (node.type === "method_declaration") {
       const nameNode = this.getChildByType(node, "identifier");
@@ -688,19 +792,45 @@ import { resolve as resolve2, dirname } from "path";
 var Graph = class {
   nodes = /* @__PURE__ */ new Map();
   edges = [];
+  implementationRegistry = /* @__PURE__ */ new Map();
   constructor(files) {
     for (const file of files) {
-      this.nodes.set(file.id, {
-        id: file.id,
-        relativePath: file.relativePath,
-        language: file.language,
-        metadata: file.metadata,
-        inboundEdges: 0,
-        outboundEdges: 0
-      });
+      this.addNode(file);
     }
     this.resolveEdges(files);
   }
+  addNode(file) {
+    this.nodes.set(file.id, {
+      id: file.id,
+      relativePath: file.relativePath,
+      language: file.language,
+      metadata: file.metadata,
+      inboundEdges: 0,
+      outboundEdges: 0,
+      ca: 0,
+      ce: 0,
+      instability: 0
+    });
+    if (file.metadata.implementsInterfaces) {
+      for (const interfaceName of file.metadata.implementsInterfaces) {
+        if (!this.implementationRegistry.has(interfaceName)) {
+          this.implementationRegistry.set(interfaceName, []);
+        }
+        this.implementationRegistry.get(interfaceName).push(file.id);
+      }
+    }
+  }
+  calculateHealthMetrics() {
+    for (const node of this.nodes.values()) {
+      node.ca = node.inboundEdges;
+      node.ce = node.outboundEdges;
+      const denominator = node.ca + node.ce;
+      node.instability = denominator === 0 ? 0 : node.ce / denominator;
+    }
+  }
+  getImplementationRegistry() {
+    return Object.fromEntries(this.implementationRegistry);
+  }
   resolveEdges(files) {
     for (const file of files) {
       const dir = dirname(file.id);
@@ -831,7 +961,8 @@ async function exportGraphToJson(graph, parsedFiles, outputPath) {
     target: edge.target,
     type: edge.type
   }));
-  const output = { nodes, edges };
+  const implementations = graph.getImplementationRegistry();
+  const output = { nodes, edges, implementations };
   await writeFile(outputPath, JSON.stringify(output, null, 2));
 }
 
@@ -856,7 +987,7 @@ function createCommand() {
     "-f, --format <format>",
     "Output format (text, json)",
     "text"
-  ).option("-o, --output <file>", "Output file path").action(async (path, options) => {
+  ).option("-o, --output <file>", "Output file path").option("-i, --implements <interfaceName>", "Find all files implementing a specific interface or base class").option("--health", "Display architectural health metrics and identify unstable files").action(async (path, options) => {
     const scanResult = scanDirectory({ rootDir: path, verbose: options.verbose });
     if (options.verbose) {
       console.log(pc.dim("\nParsing files..."));
@@ -878,6 +1009,45 @@ function createCommand() {
     }
     const graph = new Graph(parsedFiles);
     const rankedNodes = analyzeGraph(graph);
+    graph.calculateHealthMetrics();
+    if (options.health) {
+      const nodes = Array.from(graph.getNodes().values());
+      const topCoreDeps = nodes.sort((a, b) => b.ca - a.ca).slice(0, 5).filter((n) => n.ca > 0);
+      const topUnstable = nodes.sort((a, b) => b.instability - a.instability).slice(0, 5).filter((n) => n.instability > 0);
+      console.log(pc.bold("\n=== Architectural Health Metrics ===\n"));
+      if (topCoreDeps.length > 0) {
+        console.log(pc.bold("Top 5 Core Dependencies (Highest Ca - will break most things if changed):"));
+        for (const node of topCoreDeps) {
+          console.log(`  ${pc.red(node.relativePath)}: ${pc.bold(node.ca.toString())} dependents`);
+        }
+        console.log();
+      }
+      if (topUnstable.length > 0) {
+        console.log(pc.bold("Top 5 Most Unstable Files (Highest I = Ce/(Ca+Ce)):"));
+        for (const node of topUnstable) {
+          console.log(`  ${pc.yellow(node.relativePath)}: ${pc.bold(node.instability.toFixed(3))} instability`);
+        }
+        console.log();
+      }
+      process.exit(0);
+    }
+    if (options.implements) {
+      const registry = graph.getImplementationRegistry();
+      const implementations = registry[options.implements] || [];
+      console.log(pc.bold(`
+Searching for implementations of: ${pc.cyan(options.implements)}`));
+      if (implementations.length === 0) {
+        console.log(pc.yellow(`
+No implementations found for ${options.implements} in this repository.`));
+      } else {
+        console.log(pc.green(`
+Found ${implementations.length} implementation(s):`));
+        for (const file of implementations) {
+          console.log(`  ${pc.dim(file)}`);
+        }
+      }
+      process.exit(0);
+    }
     if (options.format === "json") {
       const outputPath = options.output ?? resolve3(process.cwd(), "repolens-graph.json");
       await exportGraphToJson(graph, parsedFiles, outputPath);