archlens 0.1.0

package/dist/engine/fileCollector.js

@@ -0,0 +1,13 @@
+import fg from "fast-glob";
+export async function collectFiles(params) {
+    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/dist/engine/graph.js

@@ -0,0 +1,54 @@
+import { candidatePaths, isRelative } from "./resolve.js";
+import { loadAliasRules, resolveAliasImport } from "./tsconfigAliases.js";
+import { parseImportsJS, parseImportsTS } from "./importParsers.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function buildGraph(params) {
+    const { cwd, files } = params;
+    const fileSet = new Set(files);
+    const edges = [];
+    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/dist/engine/importParsers.js

@@ -0,0 +1,62 @@
+import { parse as babelParse } from "@babel/parser";
+import ts from "typescript";
+export function parseImportsTS(sourceText, filePath) {
+    const sf = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true);
+    const imports = [];
+    function visit(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) {
+    const ast = babelParse(sourceText, {
+        sourceType: "unambiguous",
+        plugins: ["jsx", "typescript", "decorators-legacy"]
+    });
+    const imports = [];
+    const stack = [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[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/dist/engine/index.js

@@ -0,0 +1,30 @@
+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) {
+    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/dist/engine/metrics.js

@@ -0,0 +1,28 @@
+export function computeNodeMetrics(nodes, edges) {
+    const fanIn = new Map();
+    const fanOut = new Map();
+    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 = 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/dist/engine/resolve.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+export function isRelative(spec) {
+    return spec.startsWith(".") || spec.startsWith("/");
+}
+export function candidatePaths(fromFile, spec) {
+    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/dist/engine/score.js

@@ -0,0 +1,123 @@
+function clamp(n, min, max) {
+    return Math.max(min, Math.min(max, n));
+}
+function gradeFromScore(v) {
+    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) {
+    if (v >= 80)
+        return "Healthy";
+    if (v >= 60)
+        return "Warning";
+    return "Critical";
+}
+export function computeScore(input) {
+    const breakdown = [];
+    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
+    };
+}

package/dist/engine/tarjan.js

@@ -0,0 +1,46 @@
+export function stronglyConnectedComponents(nodes, edges) {
+    const adjacency = new Map();
+    for (const n of nodes)
+        adjacency.set(n, []);
+    for (const e of edges) {
+        adjacency.get(e.from)?.push(e.to);
+    }
+    let index = 0;
+    const stack = [];
+    const onStack = new Set();
+    const indices = new Map();
+    const lowlink = new Map();
+    const sccs = [];
+    function strongConnect(v) {
+        indices.set(v, index);
+        lowlink.set(v, index);
+        index++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of adjacency.get(v) ?? []) {
+            if (!indices.has(w)) {
+                strongConnect(w);
+                lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
+            }
+            else if (onStack.has(w)) {
+                lowlink.set(v, Math.min(lowlink.get(v), indices.get(w)));
+            }
+        }
+        if (lowlink.get(v) === indices.get(v)) {
+            const component = [];
+            while (true) {
+                const w = stack.pop();
+                onStack.delete(w);
+                component.push(w);
+                if (w === v)
+                    break;
+            }
+            sccs.push(component);
+        }
+    }
+    for (const v of nodes) {
+        if (!indices.has(v))
+            strongConnect(v);
+    }
+    return sccs;
+}

package/dist/engine/tsconfigAliases.js

@@ -0,0 +1,68 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+async function readJsonIfExists(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeStarPattern(p) {
+    // "@/*" => {prefix:"@/", hasStar:true}
+    // "src/*" => {targetPrefix:"src/", hasStar:true}
+    const hasStar = p.includes("*");
+    const prefix = p.replaceAll("*", "");
+    return { prefix, hasStar };
+}
+export async function loadAliasRules(cwd) {
+    const tsconfigPath = path.join(cwd, "tsconfig.json");
+    const jsconfigPath = path.join(cwd, "jsconfig.json");
+    const tsconfig = (await readJsonIfExists(tsconfigPath)) ?? (await readJsonIfExists(jsconfigPath));
+    if (!tsconfig)
+        return [];
+    const cfg = tsconfig;
+    const pathsMap = cfg.compilerOptions?.paths ?? {};
+    // baseUrl pode existir (e você já adicionou), mas pro nosso caso de @/* não é obrigatório.
+    // Mesmo assim, mantemos para futuro.
+    const baseUrl = cfg.compilerOptions?.baseUrl ?? ".";
+    const rules = [];
+    for (const [fromPattern, toPatterns] of Object.entries(pathsMap)) {
+        if (!Array.isArray(toPatterns) || toPatterns.length === 0)
+            continue;
+        // Pegamos o primeiro target (MVP). Depois suportamos múltiplos.
+        const toPattern = toPatterns[0];
+        const from = normalizeStarPattern(fromPattern);
+        const to = normalizeStarPattern(toPattern);
+        // MVP: suportar só padrões com "*" do tipo "@/*": ["src/*"]
+        // Se não tiver *, ainda dá pra suportar como prefixo direto, mas vamos aceitar os dois.
+        const fromPrefix = from.prefix;
+        const targetPrefix = to.prefix;
+        // baseUrl: resolve "src/" relativo ao baseUrl (normalmente ".")
+        // Ex: baseUrl="." e targetPrefix="src/" => "src/"
+        // Ex: baseUrl="src" e targetPrefix="" => "src/"
+        const resolvedTargetPrefix = path.posix
+            .normalize(path.posix.join(baseUrl.replaceAll("\\", "/"), targetPrefix.replaceAll("\\", "/")))
+            .replaceAll("\\", "/");
+        rules.push({
+            prefix: fromPrefix,
+            targetPrefix: resolvedTargetPrefix.endsWith("/") ? resolvedTargetPrefix : `${resolvedTargetPrefix}/`
+        });
+    }
+    // Ordena por prefixo mais longo primeiro (evita conflito entre "@/" e "@shared/")
+    rules.sort((a, b) => b.prefix.length - a.prefix.length);
+    return rules;
+}
+export function resolveAliasImport(spec, rules) {
+    for (const r of rules) {
+        if (spec.startsWith(r.prefix)) {
+            const rest = spec.slice(r.prefix.length); // o que vem depois do prefixo
+            // Ex: "@/app/types/product" => "src/app/types/product"
+            const candidateBase = (r.targetPrefix + rest).replaceAll("\\", "/");
+            // removendo "//" acidentais
+            return candidateBase.replaceAll("//", "/");
+        }
+    }
+    return null;
+}

package/dist/engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/main.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { analyzeProject } from "./engine/index.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+const program = new Command();
+program
+    .name("archlens")
+    .description("Architecture health analyzer for JS/TS projects")
+    .version("0.1.0");
+program
+    .command("analyze")
+    .argument("<targetPath>", "Path do projeto (ex: .)")
+    .option("--config <file>", "Arquivo de config", "archlens.config.json")
+    .option("--out <dir>", "Pasta de saída", "./archlens-report")
+    .action(async (targetPath, opts) => {
+    const cwd = path.resolve(process.cwd(), targetPath);
+    const outDir = path.resolve(process.cwd(), opts.out);
+    const configPath = path.resolve(cwd, opts.config);
+    const defaults = {
+        entryGlobs: ["src/**/*.{ts,tsx,js,jsx}"],
+        excludeGlobs: [
+            "**/node_modules/**",
+            "**/dist/**",
+            "**/build/**",
+            "**/coverage/**",
+        ],
+    };
+    let cfg = {};
+    try {
+        // config é opcional: se não existir, usa defaults
+        cfg = JSON.parse(await fs.readFile(configPath, "utf8"));
+    }
+    catch {
+        cfg = {};
+    }
+    const projectName = cfg.projectName ?? path.basename(cwd);
+    const entryGlobs = cfg.entryGlobs ?? defaults.entryGlobs;
+    const excludeGlobs = cfg.excludeGlobs ?? defaults.excludeGlobs;
+    const report = await analyzeProject({
+        cwd,
+        projectName,
+        entryGlobs,
+        excludeGlobs,
+    });
+    await fs.mkdir(outDir, { recursive: true });
+    const jsonPath = path.join(outDir, "report.json");
+    await fs.writeFile(jsonPath, JSON.stringify(report, null, 2), "utf8");
+    console.log(`\n✅ ArchLens analysis complete`);
+    console.log(`Project: ${report.meta.projectName}`);
+    console.log(`Files analyzed: ${report.meta.fileCount}`);
+    console.log(`Edges: ${report.graph.edges.length}`);
+    console.log(`Architecture Health Score: ${report.score.value}/100 (${report.score.grade})`);
+    console.log(`Status: ${report.score.status}`);
+    const penalties = report.score.breakdown.filter((b) => b.points < 0);
+    if (penalties.length) {
+        console.log("\nScore breakdown (penalties):");
+        for (const p of penalties) {
+            console.log(`  ${p.points}  ${p.details}`);
+        }
+    }
+    const topIn = report.metrics.topFanIn.slice(0, 3);
+    const topOut = report.metrics.topFanOut.slice(0, 3);
+    const danger = report.metrics.danger.slice(0, 3);
+    console.log("Top Fan-in (críticos):");
+    for (const m of topIn)
+        console.log(`  - ${m.fanIn} in  | ${m.fanOut} out | ${m.file}`);
+    console.log("Top Fan-out (instáveis):");
+    for (const m of topOut)
+        console.log(`  - ${m.fanIn} in  | ${m.fanOut} out | ${m.file}`);
+    console.log("Danger (acoplados):");
+    for (const m of danger)
+        console.log(`  - ${m.fanIn} in  | ${m.fanOut} out | ${m.file}`);
+    if (report.cycles.length) {
+        console.log(`Cycles detected: ${report.cycles.length}`);
+        console.log(`  - ${report.cycles[0].id}: ${report.cycles[0].nodes.join(" -> ")}`);
+    }
+    console.log(`Report: ${jsonPath}\n`);
+});
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "archlens",
+  "version": "0.1.0",
+  "type": "module",
+  "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"
+  }
+}