archlens 0.0.2

package/packages/cli/archlens-report/report.json

@@ -0,0 +1,282 @@
+{
+  "meta": {
+    "projectName": "cli",
+    "analyzedAt": "2026-02-22T18:16:32.518Z",
+    "fileCount": 11
+  },
+  "graph": {
+    "nodes": [
+      "src/engine/fileCollector.ts",
+      "src/engine/graph.ts",
+      "src/engine/importParsers.ts",
+      "src/engine/index.ts",
+      "src/engine/metrics.ts",
+      "src/engine/resolve.ts",
+      "src/engine/score.ts",
+      "src/engine/tarjan.ts",
+      "src/engine/tsconfigAliases.ts",
+      "src/engine/types.ts",
+      "src/main.ts"
+    ],
+    "edges": []
+  },
+  "cycles": [],
+  "metrics": {
+    "perFile": [
+      {
+        "file": "src/engine/fileCollector.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/graph.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/importParsers.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/index.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/metrics.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/resolve.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/score.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/tarjan.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/tsconfigAliases.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/types.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/main.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      }
+    ],
+    "topFanIn": [
+      {
+        "file": "src/engine/fileCollector.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/graph.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/importParsers.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/index.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/metrics.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/resolve.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/score.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/tarjan.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/tsconfigAliases.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/types.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      }
+    ],
+    "topFanOut": [
+      {
+        "file": "src/engine/fileCollector.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/graph.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/importParsers.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/index.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/metrics.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/resolve.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/score.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/tarjan.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/tsconfigAliases.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      },
+      {
+        "file": "src/engine/types.ts",
+        "fanIn": 0,
+        "fanOut": 0,
+        "instability": null,
+        "dangerScore": 0
+      }
+    ],
+    "danger": []
+  },
+  "score": {
+    "value": 100,
+    "grade": "A",
+    "status": "Healthy",
+    "breakdown": [
+      {
+        "key": "cycles",
+        "points": 0,
+        "details": "No dependency cycles detected"
+      },
+      {
+        "key": "danger>=4",
+        "points": 0,
+        "details": "No elevated coupling hotspots (dangerScore ≥ 4)"
+      },
+      {
+        "key": "danger>=9",
+        "points": 0,
+        "details": "No strong coupling hotspots (dangerScore ≥ 9)"
+      },
+      {
+        "key": "fanOut>=10",
+        "points": 0,
+        "details": "No modules with very high fanOut (≥ 10)"
+      },
+      {
+        "key": "fanOut>=20",
+        "points": 0,
+        "details": "No modules with extreme fanOut (≥ 20)"
+      }
+    ]
+  }
+}

package/packages/cli/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "archlens",
+  "version": "0.1.2",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "archlens": "dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.26.0",
+    "fast-glob": "^3.3.3",
+    "commander": "^..."
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}

package/packages/cli/src/engine/fileCollector.ts

@@ -0,0 +1,20 @@
+import fg from "fast-glob";
+
+export async function collectFiles(params: {
+  cwd: string;
+  entryGlobs: string[];
+  excludeGlobs: string[];
+}): Promise<string[]> {
+  const { cwd, entryGlobs, excludeGlobs } = params;
+
+  const files = await fg(entryGlobs, {
+    cwd,
+    ignore: excludeGlobs,
+    onlyFiles: true,
+    dot: false,
+    unique: true,
+    absolute: false
+  });
+
+  return files.map((p) => p.replaceAll("\\", "/")).sort();
+}

package/packages/cli/src/engine/graph.ts

@@ -0,0 +1,66 @@
+import { candidatePaths, isRelative } from "./resolve.js";
+import { loadAliasRules, resolveAliasImport } from "./tsconfigAliases.js";
+import { parseImportsJS, parseImportsTS } from "./importParsers.js";
+
+import type { Edge } from "./types.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function buildGraph(params: {
+  cwd: string;
+  files: string[];
+}): Promise<{ nodes: string[]; edges: Edge[] }> {
+  const { cwd, files } = params;
+
+  const fileSet = new Set(files);
+  const edges: Edge[] = [];
+
+  const aliasRules = await loadAliasRules(cwd);
+
+  for (const file of files) {
+    const abs = path.join(cwd, file);
+
+    let text = "";
+    try {
+      text = await fs.readFile(abs, "utf8");
+    } catch {
+      continue;
+    }
+
+    const isTS = file.endsWith(".ts") || file.endsWith(".tsx");
+    const specs = isTS ? parseImportsTS(text, file) : parseImportsJS(text);
+
+    for (const spec of specs) {
+      // 1) relativo: ./ ../
+      if (isRelative(spec)) {
+        const candidates = candidatePaths(file, spec);
+        const target = candidates.find((c) => fileSet.has(c));
+        if (target) edges.push({ from: file, to: target });
+        continue;
+      }
+
+      // 2) alias: @/...
+      const aliased = resolveAliasImport(spec, aliasRules);
+      if (aliased) {
+        // aqui "aliased" vira algo como "src/app/types/product"
+        const candidates = [
+          aliased,
+          `${aliased}.ts`,
+          `${aliased}.tsx`,
+          `${aliased}.js`,
+          `${aliased}.jsx`,
+          `${aliased}/index.ts`,
+          `${aliased}/index.tsx`,
+          `${aliased}/index.js`,
+          `${aliased}/index.jsx`
+        ].map((p) => p.replaceAll("\\", "/"));
+
+        const target = candidates.find((c) => fileSet.has(c));
+        if (target) edges.push({ from: file, to: target });
+      }
+    }
+  }
+
+  const nodes = Array.from(new Set([...files, ...edges.flatMap((e) => [e.from, e.to])])).sort();
+  return { nodes, edges };
+}

package/packages/cli/src/engine/importParsers.ts

@@ -0,0 +1,72 @@
+import { parse as babelParse } from "@babel/parser";
+import ts from "typescript";
+
+export function parseImportsTS(sourceText: string, filePath: string): string[] {
+  const sf = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true);
+  const imports: string[] = [];
+
+  function visit(node: ts.Node) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      imports.push(node.moduleSpecifier.text);
+    }
+    if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      imports.push(node.moduleSpecifier.text);
+    }
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === "require" &&
+      node.arguments.length === 1 &&
+      ts.isStringLiteral(node.arguments[0])
+    ) {
+      imports.push(node.arguments[0].text);
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return imports;
+}
+
+export function parseImportsJS(sourceText: string): string[] {
+  const ast = babelParse(sourceText, {
+    sourceType: "unambiguous",
+    plugins: ["jsx", "typescript", "decorators-legacy"]
+  });
+
+  const imports: string[] = [];
+  const stack: any[] = [ast];
+
+  while (stack.length) {
+    const node = stack.pop();
+    if (!node || typeof node !== "object") continue;
+
+    if (node.type === "ImportDeclaration" && node.source?.value) {
+      imports.push(String(node.source.value));
+    }
+    if (node.type === "ExportNamedDeclaration" && node.source?.value) {
+      imports.push(String(node.source.value));
+    }
+    if (node.type === "ExportAllDeclaration" && node.source?.value) {
+      imports.push(String(node.source.value));
+    }
+    if (
+      node.type === "CallExpression" &&
+      node.callee?.type === "Identifier" &&
+      node.callee.name === "require" &&
+      node.arguments?.length === 1 &&
+      node.arguments[0]?.type === "StringLiteral"
+    ) {
+      imports.push(String(node.arguments[0].value));
+    }
+
+    for (const k of Object.keys(node)) {
+      const v = (node as any)[k];
+      if (Array.isArray(v)) for (const child of v) stack.push(child);
+      else if (v && typeof v === "object") stack.push(v);
+    }
+  }
+
+  return imports;
+}

package/packages/cli/src/engine/index.ts

@@ -0,0 +1,44 @@
+import type { Report } from "./types.js";
+import { buildGraph } from "./graph.js";
+import { collectFiles } from "./fileCollector.js";
+import { computeNodeMetrics } from "./metrics.js";
+import { computeScore } from "./score.js";
+import { stronglyConnectedComponents } from "./tarjan.js";
+
+export async function analyzeProject(params: {
+  cwd: string;
+  projectName: string;
+  entryGlobs: string[];
+  excludeGlobs: string[];
+}): Promise<Report> {
+
+  const { cwd, projectName, entryGlobs, excludeGlobs } = params;
+
+  const files = await collectFiles({ cwd, entryGlobs, excludeGlobs });
+  const graph = await buildGraph({ cwd, files });
+
+  const sccs = stronglyConnectedComponents(graph.nodes, graph.edges);
+
+  const cycles = sccs
+    .filter(c => c.length > 1)
+    .map((nodes, i) => ({
+      id: `cycle-${i + 1}`,
+      nodes: nodes.sort()
+    }));
+
+    const metrics = computeNodeMetrics(graph.nodes, graph.edges);
+
+    const score = computeScore({ cycles, metrics });
+
+  return {
+    meta: {
+      projectName,
+      analyzedAt: new Date().toISOString(),
+      fileCount: graph.nodes.length
+    },
+    graph,
+    cycles,
+    metrics,
+    score
+  };
+}

package/packages/cli/src/engine/metrics.ts

@@ -0,0 +1,36 @@
+import type { Edge, NodeMetrics } from "./types.js";
+
+export function computeNodeMetrics(nodes: string[], edges: Edge[]) {
+  const fanIn = new Map<string, number>();
+  const fanOut = new Map<string, number>();
+
+  for (const n of nodes) {
+    fanIn.set(n, 0);
+    fanOut.set(n, 0);
+  }
+
+  for (const e of edges) {
+    fanOut.set(e.from, (fanOut.get(e.from) ?? 0) + 1);
+    fanIn.set(e.to, (fanIn.get(e.to) ?? 0) + 1);
+  }
+
+  const perFile: NodeMetrics[] = nodes.map((file) => {
+    const fi = fanIn.get(file) ?? 0;
+    const fo = fanOut.get(file) ?? 0;
+    const denom = fi + fo;
+    const instability = denom === 0 ? null : Number((fo / denom).toFixed(3));
+    const dangerScore = fi * fo;
+    return { file, fanIn: fi, fanOut: fo, instability, dangerScore };
+  });
+
+  const topFanIn = [...perFile].sort((a, b) => b.fanIn - a.fanIn).slice(0, 10);
+  const topFanOut = [...perFile].sort((a, b) => b.fanOut - a.fanOut).slice(0, 10);
+
+  // “perigo” = central + acoplado: alto (fanIn+fanOut) e idealmente ambos > 0
+  const danger = [...perFile]
+    .filter((m) => m.fanIn > 0 && m.fanOut > 0)
+    .sort((a, b) => (b.dangerScore ?? 0) - (a.dangerScore ?? 0))
+    .slice(0, 10);
+
+  return { perFile, topFanIn, topFanOut, danger };
+}

package/packages/cli/src/engine/resolve.ts

@@ -0,0 +1,26 @@
+import path from "node:path";
+
+export function isRelative(spec: string): boolean {
+  return spec.startsWith(".") || spec.startsWith("/");
+}
+
+export function candidatePaths(fromFile: string, spec: string): string[] {
+  const fromDir = path.posix.dirname(fromFile);
+  const base = spec.startsWith("/")
+    ? path.posix.normalize(spec.slice(1))
+    : path.posix.normalize(path.posix.join(fromDir, spec));
+
+  return [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    `${base}.js`,
+    `${base}.jsx`,
+    `${base}.mjs`,
+    `${base}.cjs`,
+    `${base}/index.ts`,
+    `${base}/index.tsx`,
+    `${base}/index.js`,
+    `${base}/index.jsx`
+  ].map((p) => p.replaceAll("\\", "/"));
+}

package/packages/cli/src/engine/score.ts

@@ -0,0 +1,131 @@
+import type { Report, Score, ScoreBreakdownItem } from "./types.js";
+
+function clamp(n: number, min: number, max: number) {
+  return Math.max(min, Math.min(max, n));
+}
+
+function gradeFromScore(v: number): Score["grade"] {
+  if (v >= 90) return "A";
+  if (v >= 80) return "B";
+  if (v >= 70) return "C";
+  if (v >= 60) return "D";
+  return "F";
+}
+
+function statusFromScore(v: number): Score["status"] {
+  if (v >= 80) return "Healthy";
+  if (v >= 60) return "Warning";
+  return "Critical";
+}
+
+export function computeScore(input: {
+  cycles: { id: string; nodes: string[] }[];
+  metrics: Report["metrics"];
+}): Score {
+  const breakdown: ScoreBreakdownItem[] = [];
+  let totalPenalty = 0;
+
+  // 1) Cycles
+  const cycleCount = input.cycles.length;
+  const cycleNodesTotal = input.cycles.reduce((acc, c) => acc + c.nodes.length, 0);
+
+  if (cycleCount > 0) {
+    const penalty = -(cycleCount * 15 + cycleNodesTotal * 2);
+    totalPenalty += penalty;
+    breakdown.push({
+      key: "cycles",
+      points: penalty,
+      details: `Detected ${cycleCount} cycle(s) involving ${cycleNodesTotal} file(s)`
+    });
+  } else {
+    breakdown.push({
+      key: "cycles",
+      points: 0,
+      details: "No dependency cycles detected"
+    });
+  }
+
+  // 2) Danger modules (fanIn * fanOut)
+  const danger4 = input.metrics.perFile.filter((m) => (m.dangerScore ?? (m.fanIn * m.fanOut)) >= 4);
+  const danger9 = input.metrics.perFile.filter((m) => (m.dangerScore ?? (m.fanIn * m.fanOut)) >= 9);
+
+  // Evita penalizar duas vezes o mesmo arquivo no threshold menor
+  const danger4Only = danger4.filter((m) => (m.dangerScore ?? (m.fanIn * m.fanOut)) < 9);
+
+  if (danger4Only.length > 0) {
+    const penalty = -(danger4Only.length * 2);
+    totalPenalty += penalty;
+    breakdown.push({
+      key: "danger>=4",
+      points: penalty,
+      details: `${danger4Only.length} module(s) have elevated coupling (dangerScore ≥ 4)`
+    });
+  } else {
+    breakdown.push({
+      key: "danger>=4",
+      points: 0,
+      details: "No elevated coupling hotspots (dangerScore ≥ 4)"
+    });
+  }
+
+  if (danger9.length > 0) {
+    const penalty = -(danger9.length * 4);
+    totalPenalty += penalty;
+    breakdown.push({
+      key: "danger>=9",
+      points: penalty,
+      details: `${danger9.length} module(s) are strong coupling hotspots (dangerScore ≥ 9)`
+    });
+  } else {
+    breakdown.push({
+      key: "danger>=9",
+      points: 0,
+      details: "No strong coupling hotspots (dangerScore ≥ 9)"
+    });
+  }
+
+  // 3) High fan-out
+  const fanOut10 = input.metrics.perFile.filter((m) => m.fanOut >= 10 && m.fanOut < 20);
+  const fanOut20 = input.metrics.perFile.filter((m) => m.fanOut >= 20);
+
+  if (fanOut10.length > 0) {
+    const penalty = -(fanOut10.length * 2);
+    totalPenalty += penalty;
+    breakdown.push({
+      key: "fanOut>=10",
+      points: penalty,
+      details: `${fanOut10.length} module(s) depend on 10–19 internal modules (fanOut ≥ 10)`
+    });
+  } else {
+    breakdown.push({
+      key: "fanOut>=10",
+      points: 0,
+      details: "No modules with very high fanOut (≥ 10)"
+    });
+  }
+
+  if (fanOut20.length > 0) {
+    const penalty = -(fanOut20.length * 4);
+    totalPenalty += penalty;
+    breakdown.push({
+      key: "fanOut>=20",
+      points: penalty,
+      details: `${fanOut20.length} module(s) depend on 20+ internal modules (fanOut ≥ 20)`
+    });
+  } else {
+    breakdown.push({
+      key: "fanOut>=20",
+      points: 0,
+      details: "No modules with extreme fanOut (≥ 20)"
+    });
+  }
+
+  const value = clamp(100 + totalPenalty, 0, 100);
+
+  return {
+    value,
+    grade: gradeFromScore(value),
+    status: statusFromScore(value),
+    breakdown
+  };
+}