@anirudw/repolens 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Build project
+        run: npm run build
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,42 @@
+# repolens
+
+A CLI tool to visualize repository dependency graphs by parsing ASTs across multiple languages.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+```bash
+# Scan current directory
+repolens
+
+# Scan specific directory
+repolens ./path/to/repo
+
+# With verbose output
+repolens --verbose
+
+# Output formats
+repolens --format json --output graph.json
+repolens --format html --output graph.html
+```
+
+## Supported Languages
+
+- JavaScript/JSX (.js, .jsx)
+- TypeScript/TSX (.ts, .tsx)
+- Python (.py)
+- Java (.java)
+- Markdown (.md)

package/bin/repolens.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { createCommand } from "../dist/cli/commands.js";
+
+const program = createCommand();
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@anirudw/repolens",
+  "version": "0.1.0",
+  "description": "A CLI tool to visualize repository dependency graphs",
+  "type": "module",
+  "bin": {
+    "repolens": "./bin/repolens.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli/index.ts",
+    "test": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "repository",
+    "graph",
+    "dependencies",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ignore": "^5.3.1",
+    "picocolors": "^1.0.1",
+    "remark": "^15.0.1",
+    "remark-parse": "^11.0.0",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-java": "^0.21.0",
+    "tree-sitter-javascript": "^0.21.2",
+    "tree-sitter-python": "^0.21.0",
+    "unist-util-visit": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  }
+}

package/src/cli/commands.ts

@@ -0,0 +1,112 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { scanDirectory } from "../scanner/index.js";
+import { createParser } from "../parser/index.js";
+import { Graph, analyzeGraph } from "../graph/index.js";
+import { exportGraphToJson } from "../renderers/json/exporter.js";
+import type { ParsedFile } from "../parser/types.js";
+import type { ScanResult } from "../scanner/walker.js";
+import { pc } from "../utils/colors.js";
+
+export function createCommand(): Command {
+  const program = new Command();
+
+  program
+    .name("repolens")
+    .description("Visualize repository dependency graphs")
+    .version("0.1.0")
+    .argument("[path]", "Directory to scan", process.cwd())
+    .option("-v, --verbose", "Enable verbose output", false)
+    .option(
+      "-f, --format <format>",
+      "Output format (text, json)",
+      "text"
+    )
+    .option("-o, --output <file>", "Output file path")
+    .action(async (path, options) => {
+      const scanResult = scanDirectory({ rootDir: path, verbose: options.verbose });
+
+      if (options.verbose) {
+        console.log(pc.dim("\nParsing files..."));
+      }
+
+      const parsedFiles: ParsedFile[] = [];
+      for (const file of scanResult.files) {
+        const parser = createParser(file.absolutePath);
+        if (parser) {
+          try {
+            const content = readFileSync(file.absolutePath, "utf-8");
+            const parsed = await parser.parse(file.absolutePath, content);
+            parsedFiles.push(parsed);
+          } catch (err) {
+            if (options.verbose) {
+              console.warn(`Warning: Failed to parse ${file.relativePath}: ${err}`);
+            }
+          }
+        }
+      }
+
+      const graph = new Graph(parsedFiles);
+      const rankedNodes = analyzeGraph(graph);
+
+      if (options.format === "json") {
+        const outputPath = options.output ?? resolve(process.cwd(), "repolens-graph.json");
+        await exportGraphToJson(graph, parsedFiles, outputPath);
+        console.log(`Graph exported to ${outputPath}`);
+      } else {
+        printSummary(scanResult, rankedNodes, options.verbose);
+      }
+    });
+
+  return program;
+}
+
+function printSummary(
+  result: ScanResult,
+  rankedNodes: ReturnType<typeof analyzeGraph>,
+  verbose: boolean
+): void {
+  console.log(pc.bold("\nRepository Scan Summary\n"));
+  console.log(`Total files found: ${pc.cyan(result.totalFiles.toString())}`);
+  console.log(`Files ignored: ${result.ignoredCount}\n`);
+
+  console.log(pc.bold("Files by language:"));
+  const langColors: Record<string, (s: string) => string> = {
+    javascript: pc.yellow,
+    typescript: pc.blue,
+    python: pc.green,
+    java: pc.red,
+    markdown: pc.magenta,
+  };
+
+  for (const [lang, count] of Object.entries(result.filesByLanguage)) {
+    if (count > 0) {
+      const color = langColors[lang] ?? pc.white;
+      console.log(`  ${color(`• ${lang}`)}: ${pc.bold(count.toString())}`);
+    }
+  }
+
+  const topHubs = rankedNodes.filter((n) => n.inboundEdges > 0).slice(0, 3);
+  if (topHubs.length > 0) {
+    console.log(pc.bold("\nTop Hubs (Most Connected):"));
+    for (const hub of topHubs) {
+      const badge = hub.metadata?.heuristics?.isReact ? " [React]" : "";
+      console.log(
+        `  ${pc.cyan(hub.relativePath)}${badge}: ${pc.bold(hub.inboundEdges.toString())} inbound`
+      );
+    }
+  }
+
+  if (verbose && result.files.length > 0) {
+    console.log(pc.bold("\nScanned files:"));
+    for (const file of result.files.slice(0, 50)) {
+      console.log(`  ${pc.dim(file.relativePath)}`);
+    }
+    if (result.files.length > 50) {
+      console.log(`  ${pc.dim(`... and ${result.files.length - 50} more`)}`);
+    }
+  }
+
+  console.log();
+}

package/src/cli/index.ts

@@ -0,0 +1,4 @@
+import { createCommand } from "./commands.js";
+
+const program = createCommand();
+program.parse(process.argv);

package/src/graph/analyzer/pagerank.ts

@@ -0,0 +1,31 @@
+import { Graph, type GraphNode } from "../network.js";
+
+export interface RankedNode extends GraphNode {
+  centrality: number;
+}
+
+export function analyzeGraph(graph: Graph): RankedNode[] {
+  const nodes = graph.getNodes();
+  const ranked: RankedNode[] = [];
+
+  for (const [, node] of nodes) {
+    let centrality = node.inboundEdges;
+
+    if (node.metadata?.heuristics?.isReact) {
+      centrality += 5;
+    }
+
+    if (node.metadata?.heuristics?.hasMainMethod) {
+      centrality += 5;
+    }
+
+    ranked.push({
+      ...node,
+      centrality,
+    });
+  }
+
+  ranked.sort((a, b) => b.centrality - a.centrality);
+
+  return ranked;
+}

package/src/graph/index.ts

@@ -0,0 +1,2 @@
+export { Graph, type GraphNode, type GraphEdge } from "./network.js";
+export { analyzeGraph, type RankedNode } from "./analyzer/pagerank.js";

package/src/graph/network.ts

@@ -0,0 +1,148 @@
+import { resolve, dirname, join } from "node:path";
+import type { ParsedFile, ExtractedDependency } from "../parser/types.js";
+
+export interface GraphNode {
+  id: string;
+  relativePath: string;
+  language: string;
+  metadata: ParsedFile["metadata"];
+  inboundEdges: number;
+  outboundEdges: number;
+}
+
+export interface GraphEdge {
+  source: string;
+  target: string;
+  type: ExtractedDependency["type"];
+}
+
+export class Graph {
+  private nodes: Map<string, GraphNode> = new Map();
+  private edges: GraphEdge[] = [];
+
+  constructor(files: ParsedFile[]) {
+    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.resolveEdges(files);
+  }
+
+  private resolveEdges(files: ParsedFile[]): void {
+    for (const file of files) {
+      const dir = dirname(file.id);
+
+      for (const dep of file.dependencies) {
+        if (!dep.rawSpecifier) continue;
+
+        if (
+          dep.rawSpecifier.startsWith("http") ||
+          dep.rawSpecifier.startsWith("//") ||
+          dep.rawSpecifier.startsWith("#") ||
+          !this.isLocalImport(dep.rawSpecifier)
+        ) {
+          continue;
+        }
+
+        const resolvedPath = this.resolveImportPath(
+          dir,
+          dep.rawSpecifier
+        );
+
+        if (resolvedPath && this.nodes.has(resolvedPath)) {
+          dep.resolvedPath = resolvedPath;
+          this.edges.push({
+            source: file.id,
+            target: resolvedPath,
+            type: dep.type,
+          });
+
+          const targetNode = this.nodes.get(resolvedPath);
+          if (targetNode) {
+            targetNode.inboundEdges++;
+          }
+
+          const sourceNode = this.nodes.get(file.id);
+          if (sourceNode) {
+            sourceNode.outboundEdges++;
+          }
+        }
+      }
+    }
+  }
+
+  private resolveImportPath(
+    fromDir: string,
+    specifier: string
+  ): string | null {
+    const candidatePaths = [
+      specifier,
+      `${specifier}.js`,
+      `${specifier}.ts`,
+      `${specifier}.jsx`,
+      `${specifier}.tsx`,
+      `${specifier}/index.js`,
+      `${specifier}/index.ts`,
+      `${specifier}/index.jsx`,
+      `${specifier}/index.tsx`,
+    ];
+
+    for (const candidate of candidatePaths) {
+      try {
+        const fullPath = resolve(fromDir, candidate);
+        if (this.nodes.has(fullPath)) {
+          return fullPath;
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    return null;
+  }
+
+  private isLocalImport(specifier: string): boolean {
+    return (
+      specifier.startsWith("./") ||
+      specifier.startsWith("../") ||
+      specifier.startsWith("/")
+    );
+  }
+
+  getNodes(): Map<string, GraphNode> {
+    return this.nodes;
+  }
+
+  getEdges(): GraphEdge[] {
+    return this.edges;
+  }
+
+  getNode(id: string): GraphNode | undefined {
+    return this.nodes.get(id);
+  }
+
+  getNeighbors(id: string): { inbound: GraphNode[]; outbound: GraphNode[] } {
+    const inbound: GraphNode[] = [];
+    const outbound: GraphNode[] = [];
+
+    for (const edge of this.edges) {
+      if (edge.target === id) {
+        const node = this.nodes.get(edge.source);
+        if (node) inbound.push(node);
+      }
+      if (edge.source === id) {
+        const node = this.nodes.get(edge.target);
+        if (node) outbound.push(node);
+      }
+    }
+
+    return { inbound, outbound };
+  }
+}

package/src/parser/index.ts

@@ -0,0 +1,32 @@
+import type { ParserStrategy } from "./types.js";
+import { MarkdownParser } from "./strategies/markdown.js";
+import { JavaScriptParser } from "./strategies/javascript.js";
+import { PythonParser } from "./strategies/python.js";
+import { JavaParser } from "./strategies/java.js";
+
+const JAVASCRIPT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"]);
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown"]);
+const PYTHON_EXTENSIONS = new Set([".py"]);
+const JAVA_EXTENSIONS = new Set([".java"]);
+
+export function createParser(filePath: string): ParserStrategy | null {
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+
+  if (JAVASCRIPT_EXTENSIONS.has(ext)) {
+    return new JavaScriptParser();
+  }
+
+  if (MARKDOWN_EXTENSIONS.has(ext)) {
+    return new MarkdownParser();
+  }
+
+  if (PYTHON_EXTENSIONS.has(ext)) {
+    return new PythonParser();
+  }
+
+  if (JAVA_EXTENSIONS.has(ext)) {
+    return new JavaParser();
+  }
+
+  return null;
+}

package/src/parser/strategies/java.ts

@@ -0,0 +1,154 @@
+import type { ParserStrategy, ExtractedDependency, ParsedFile } from "../types.js";
+
+type TreeSitterParser = {
+  parse(content: string): { rootNode: TreeNode };
+  setLanguage(lang: unknown): void;
+};
+
+let TreeSitterParser: new () => TreeSitterParser;
+let Java: unknown;
+
+async function ensureLoaded(): Promise<void> {
+  if (!TreeSitterParser) {
+    const [ts, j] = await Promise.all([
+      import("tree-sitter"),
+      import("tree-sitter-java"),
+    ]);
+    TreeSitterParser = ts.default as new () => TreeSitterParser;
+    Java = j.default;
+  }
+}
+
+type TreeNode = {
+  type: string;
+  text: string;
+  startPosition: { row: number; column: number };
+  endPosition: { row: number; column: number };
+  children: TreeNode[];
+  childForFieldName(name: string): TreeNode | null;
+};
+
+export class JavaParser implements ParserStrategy {
+  private parser: TreeSitterParser | null = null;
+
+  private async ensureParser(): Promise<TreeSitterParser> {
+    if (!this.parser) {
+      await ensureLoaded();
+      this.parser = new TreeSitterParser();
+      this.parser.setLanguage(Java);
+    }
+    return this.parser;
+  }
+
+  async parse(filePath: string, content: string): Promise<ParsedFile> {
+    const parser = await this.ensureParser();
+    const tree = parser.parse(content);
+    const rootNode = tree.rootNode as TreeNode;
+    const dependencies: ExtractedDependency[] = [];
+    const heuristics: Record<string, boolean> = {};
+
+    this.extractImports(rootNode, dependencies);
+    heuristics.hasMainMethod = this.detectMainMethod(rootNode);
+
+    return {
+      id: filePath,
+      relativePath: filePath.split("/").pop() ?? filePath,
+      language: "java",
+      dependencies,
+      metadata: {
+        sizeBytes: Buffer.byteLength(content, "utf-8"),
+        heuristics,
+      },
+    };
+  }
+
+  private extractImports(node: TreeNode, dependencies: ExtractedDependency[]): void {
+    if (node.type === "import_declaration") {
+      const importText = this.getScopedIdentifierText(node);
+      if (importText) {
+        dependencies.push({
+          rawSpecifier: importText,
+          type: "import",
+          location: {
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column + 1,
+          },
+          resolvedPath: importText,
+        });
+      }
+    }
+
+    for (const child of node.children) {
+      this.extractImports(child, dependencies);
+    }
+  }
+
+  private detectMainMethod(node: TreeNode): boolean {
+    if (node.type === "method_declaration") {
+      const nameNode = this.getChildByType(node, "identifier");
+      const modifiersNode = this.getChildByType(node, "modifiers");
+
+      if (nameNode?.text === "main") {
+        if (modifiersNode) {
+          const modifierTexts = this.getModifierTexts(modifiersNode);
+          if (modifierTexts.includes("public") && modifierTexts.includes("static")) {
+            return true;
+          }
+        }
+      }
+    }
+
+    for (const child of node.children) {
+      if (this.detectMainMethod(child)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private getChildByType(node: TreeNode, type: string): TreeNode | null {
+    for (const child of node.children) {
+      if (child.type === type) return child;
+    }
+    return null;
+  }
+
+  private getModifierTexts(node: TreeNode): string[] {
+    const modifiers: string[] = [];
+    for (const child of node.children) {
+      if (child.type === "public" || child.type === "private" || child.type === "protected" ||
+          child.type === "static" || child.type === "final" || child.type === "abstract" ||
+          child.type === "synchronized" || child.type === "volatile" || child.type === "transient" ||
+          child.type === "native" || child.type === "strictfp") {
+        modifiers.push(child.text);
+      } else if (child.type === "annotation" || child.type === "identifier") {
+        modifiers.push(child.text);
+      }
+    }
+    return modifiers;
+  }
+
+  private getScopedIdentifierText(node: TreeNode): string {
+    for (const child of node.children) {
+      if (child.type === "scoped_identifier") {
+        const parts: string[] = [];
+        this.collectIdentifiers(child, parts);
+        return parts.join(".");
+      } else if (child.type === "identifier") {
+        return child.text;
+      }
+    }
+    return "";
+  }
+
+  private collectIdentifiers(node: TreeNode, parts: string[]): void {
+    for (const child of node.children) {
+      if (child.type === "identifier") {
+        parts.push(child.text);
+      } else if (child.type === "scoped_identifier") {
+        this.collectIdentifiers(child, parts);
+      }
+    }
+  }
+}