architecture-linter 0.1.4 → 0.1.6

package/README.md

@@ -309,6 +309,180 @@ architecture-linter ci
 
 Fails safely if the workflow file already exists.
 
+### `score`
+
+```
+architecture-linter score [options]
+
+Options:
+  -c, --context <path>   Path to the .context.yml config file (auto-detected)
+  -p, --project <path>   Root directory of the project to scan  (default: .)
+  -f, --format <format>  Output format: text or json              (default: text)
+```
+
+Calculates an **architecture health score from 0 to 100** based on three weighted components:
+
+| Component | Max pts | What it measures |
+|---|---|---|
+| Violation density | 60 | How few import violations exist relative to total imports |
+| Layer coverage | 25 | What fraction of files belong to a declared layer |
+| Rule completeness | 15 | What fraction of layers have at least one rule defined |
+
+**Grades:** A (90–100) · B (75–89) · C (60–74) · D (40–59) · F (0–39)
+
+```bash
+npx architecture-linter score
+```
+
+Example output:
+
+```
+Architecture Health Score
+
+  87/100  Grade: B  █████████████████░░░
+
+  Breakdown:
+    Violation density    52/60  pts
+    Layer coverage       25/25  pts
+    Rule completeness    10/15  pts
+
+  Stats:
+    Files scanned:       24
+    Total imports:       87
+    Violations:          4
+    Classified files:    24/24
+    Layers with rules:   2/3
+```
+
+The score is also included in `scan --format json` output under the `score` key.
+
+---
+
+### `badge`
+
+Generates a [shields.io](https://shields.io) badge URL for the architecture health score. Drop it in your README to show the current grade at a glance.
+
+```
+architecture-linter badge [options]
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `-c, --context <path>` | Path to `.context.yml` | auto-detect |
+| `-p, --project <path>` | Project root directory | `.` |
+| `-f, --format <format>` | Output format: `url` or `markdown` | `url` |
+| `-o, --output <path>` | Write badge to a file instead of stdout | — |
+
+```bash
+# Print a shields.io URL
+npx architecture-linter badge
+
+# Print a Markdown image tag ready to paste into your README
+npx architecture-linter badge --format markdown
+
+# Write the badge URL to a file (useful in CI)
+npx architecture-linter badge --output .badge-url.txt
+```
+
+Badge colours: **A** = bright green, **B** = green, **C** = yellow, **D** = orange, **F** = red.
+
+---
+
+### `scan --format sarif`
+
+Outputs a [SARIF 2.1.0](https://sarifweb.azurewebsites.net/) document — the standard format for GitHub Code Scanning. Upload it with the `github/codeql-action/upload-sarif` action to get violations as native PR annotations.
+
+```bash
+npx architecture-linter scan --format sarif > results.sarif
+```
+
+Example GitHub Actions step:
+
+```yaml
+- name: Run architecture linter (SARIF)
+  run: npx architecture-linter scan --format sarif > arch.sarif
+
+- name: Upload SARIF to GitHub Code Scanning
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: arch.sarif
+```
+
+---
+
+### `scan --baseline` — ratchet mode
+
+Saves the current violation count and fails only when violations **increase**. Perfect for adopting the linter on an existing codebase without having to fix everything at once.
+
+```bash
+# First run: creates .arch-baseline.json and exits 0
+npx architecture-linter scan --baseline
+
+# Subsequent runs: fails only if violations exceeded the saved baseline
+npx architecture-linter scan --baseline
+
+# Explicitly update the baseline after cleaning up violations
+npx architecture-linter scan --baseline --update-baseline
+
+# Use a custom baseline file path
+npx architecture-linter scan --baseline baselines/prod.json
+```
+
+The baseline file (default `.arch-baseline.json`) records the violation count, timestamp, and tool version. Commit it to track regression over time.
+
+---
+
+### `scan --detect-circular`
+
+Detects **circular dependencies between architectural layers** using Tarjan's SCC algorithm. A cycle exists when layer A (transitively) imports layer B which imports back into layer A.
+
+```bash
+npx architecture-linter scan --detect-circular
+```
+
+Text output example:
+
+```
+↻  Circular dependencies detected between layers:
+
+   controller → service → controller
+```
+
+Circular dependencies are also included in `--format json` output under the `circularDeps` key:
+
+```json
+{
+  "circularDeps": [
+    { "cycle": ["controller", "service", "controller"] }
+  ]
+}
+```
+
+---
+
+### `scan --monorepo`
+
+Scans **all workspace packages** defined in the root `package.json` `workspaces` field. Each package uses its own `.context.yml` if one is present; otherwise falls back to the root config.
+
+```bash
+npx architecture-linter scan --monorepo
+```
+
+Each package is scanned independently and prefixed in the output:
+
+```
+Scanning @myorg/api-gateway...
+✅ No architecture violations found. (12 file(s) scanned)
+
+Scanning @myorg/user-service...
+❌ Architecture violation detected
+   ...
+```
+
+The command exits `1` if any package has violations.
+
+---
+
 ### Exit codes
 
 | Code | Meaning |

package/dist/baseline.d.ts

@@ -0,0 +1,29 @@
+export interface BaselineData {
+    /** Number of violations recorded when the baseline was saved. */
+    violationCount: number;
+    /** ISO timestamp of when the baseline was last written. */
+    timestamp: string;
+    /** Tool version that produced this baseline. */
+    version: string;
+}
+/**
+ * Resolves the baseline file path.
+ * `basePath` may be absolute or project-relative; defaults to `.arch-baseline.json`.
+ */
+export declare function resolveBaselinePath(basePath: string | undefined, projectDir: string): string;
+/**
+ * Reads and parses an existing baseline file.
+ * Returns `null` if the file does not exist or cannot be parsed.
+ */
+export declare function loadBaseline(baselinePath: string): BaselineData | null;
+/**
+ * Writes a baseline file with the current violation count.
+ */
+export declare function saveBaseline(baselinePath: string, violationCount: number, toolVersion: string): void;
+/**
+ * Returns `true` when the ratchet should fail — i.e. the current violation
+ * count has INCREASED beyond the saved baseline.
+ * Returns `false` when violations stayed the same or decreased.
+ */
+export declare function hasRatchetFailed(currentCount: number, baseline: BaselineData): boolean;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAG5F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAOtE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,IAAI,CAON;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAEtF"}

package/dist/baseline.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBaselinePath = resolveBaselinePath;
+exports.loadBaseline = loadBaseline;
+exports.saveBaseline = saveBaseline;
+exports.hasRatchetFailed = hasRatchetFailed;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const DEFAULT_BASELINE_FILE = '.arch-baseline.json';
+/**
+ * Resolves the baseline file path.
+ * `basePath` may be absolute or project-relative; defaults to `.arch-baseline.json`.
+ */
+function resolveBaselinePath(basePath, projectDir) {
+    const p = basePath ?? DEFAULT_BASELINE_FILE;
+    return path_1.default.isAbsolute(p) ? p : path_1.default.join(projectDir, p);
+}
+/**
+ * Reads and parses an existing baseline file.
+ * Returns `null` if the file does not exist or cannot be parsed.
+ */
+function loadBaseline(baselinePath) {
+    if (!fs_1.default.existsSync(baselinePath))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(baselinePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Writes a baseline file with the current violation count.
+ */
+function saveBaseline(baselinePath, violationCount, toolVersion) {
+    const data = {
+        violationCount,
+        timestamp: new Date().toISOString(),
+        version: toolVersion,
+    };
+    fs_1.default.writeFileSync(baselinePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Returns `true` when the ratchet should fail — i.e. the current violation
+ * count has INCREASED beyond the saved baseline.
+ * Returns `false` when violations stayed the same or decreased.
+ */
+function hasRatchetFailed(currentCount, baseline) {
+    return currentCount > baseline.violationCount;
+}
+//# sourceMappingURL=baseline.js.map

package/dist/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":";;;;;AAkBA,kDAGC;AAMD,oCAOC;AAKD,oCAWC;AAOD,4CAEC;AA3DD,4CAAoB;AACpB,gDAAwB;AAWxB,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAEpD;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,QAA4B,EAAE,UAAkB;IAClF,MAAM,CAAC,GAAG,QAAQ,IAAI,qBAAqB,CAAC;IAC5C,OAAO,cAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,YAAoB;IAC/C,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAiB,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAC1B,YAAoB,EACpB,cAAsB,EACtB,WAAmB;IAEnB,MAAM,IAAI,GAAiB;QACzB,cAAc;QACd,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO,EAAE,WAAW;KACrB,CAAC;IACF,YAAE,CAAC,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,YAAoB,EAAE,QAAsB;IAC3E,OAAO,YAAY,GAAG,QAAQ,CAAC,cAAc,CAAC;AAChD,CAAC"}

package/dist/circularDetector.d.ts

@@ -0,0 +1,16 @@
+import { CircularDep, FileScan } from './types';
+/**
+ * Detects circular dependencies between architectural layers using Tarjan's
+ * Strongly Connected Components (SCC) algorithm.
+ *
+ * A cycle exists when layer A (transitively) imports layer B which imports
+ * back into layer A — e.g. controller → service → controller.
+ *
+ * Each SCC with more than one node is reported as a circular dependency.
+ * Self-loops (a file importing its own layer) are intentionally ignored.
+ *
+ * @param scans   File scan results produced by `scanProject`.
+ * @param layers  Declared layer names from the architecture config.
+ */
+export declare function detectCircularDependencies(scans: FileScan[], layers: string[]): CircularDep[];
+//# sourceMappingURL=circularDetector.d.ts.map

package/dist/circularDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circularDetector.d.ts","sourceRoot":"","sources":["../src/circularDetector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,QAAQ,EAAE,EACjB,MAAM,EAAE,MAAM,EAAE,GACf,WAAW,EAAE,CA+Df"}

package/dist/circularDetector.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectCircularDependencies = detectCircularDependencies;
+const ruleEngine_1 = require("./ruleEngine");
+/**
+ * Detects circular dependencies between architectural layers using Tarjan's
+ * Strongly Connected Components (SCC) algorithm.
+ *
+ * A cycle exists when layer A (transitively) imports layer B which imports
+ * back into layer A — e.g. controller → service → controller.
+ *
+ * Each SCC with more than one node is reported as a circular dependency.
+ * Self-loops (a file importing its own layer) are intentionally ignored.
+ *
+ * @param scans   File scan results produced by `scanProject`.
+ * @param layers  Declared layer names from the architecture config.
+ */
+function detectCircularDependencies(scans, layers) {
+    // Build directed adjacency list: layer → set of layers it imports.
+    const adj = new Map();
+    for (const layer of layers)
+        adj.set(layer, new Set());
+    for (const scan of scans) {
+        const src = (0, ruleEngine_1.detectLayer)(scan.file, layers);
+        if (!src)
+            continue;
+        for (const imp of scan.imports) {
+            const tgt = (0, ruleEngine_1.detectLayer)(imp.importPath, layers);
+            if (tgt && tgt !== src) {
+                adj.get(src).add(tgt);
+            }
+        }
+    }
+    // ── Tarjan's SCC ────────────────────────────────────────────────────────────
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const cycles = [];
+    let counter = 0;
+    const strongconnect = (v) => {
+        index.set(v, counter);
+        lowlink.set(v, counter);
+        counter++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of adj.get(v)) {
+            if (!index.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), index.get(w)));
+            }
+        }
+        // Root of an SCC
+        if (lowlink.get(v) === index.get(v)) {
+            const scc = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                scc.push(w);
+            } while (w !== v);
+            if (scc.length > 1) {
+                // Reverse to restore natural discovery order, then close the cycle.
+                const ordered = scc.reverse();
+                cycles.push({ cycle: [...ordered, ordered[0]] });
+            }
+        }
+    };
+    for (const layer of layers) {
+        if (!index.has(layer))
+            strongconnect(layer);
+    }
+    return cycles;
+}
+//# sourceMappingURL=circularDetector.js.map

package/dist/circularDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circularDetector.js","sourceRoot":"","sources":["../src/circularDetector.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -6,6 +6,8 @@
  *   scan   Scan the project for architecture violations
  *   init   Generate a starter .context.yml from the project's folder structure
  *   ci     Generate a CI workflow file for architecture linting
+ *   score  Calculate architecture health score
+ *   badge  Generate a shields.io badge for the health score
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}