@eduardbar/drift 1.3.0 → 1.4.0

package/README.md

@@ -51,12 +51,61 @@ npm install --save-dev @eduardbar/drift
 
 - Product requirements and roadmap: [`docs/PRD.md`](./docs/PRD.md)
 - Trust core release checklist: [`docs/trust-core-release-checklist.md`](./docs/trust-core-release-checklist.md)
+- Rules catalog (source-of-truth snapshot): [`docs/rules-catalog.md`](./docs/rules-catalog.md)
 - Contributor/agent workflow guide: [`docs/AGENTS.md`](./docs/AGENTS.md)
 
 ---
 
 ## Commands
 
+### `drift init`
+
+Scaffold first-run setup for drift in an existing repository.
+
+```bash
+drift init
+drift init --preset node-backend
+drift init --preset react-app --ci --baseline
+```
+
+| Flag | Description |
+|------|-------------|
+| `--preset <type>` | Generate `drift.config.ts` using one of: `node-backend`, `react-app`, `hexagonal`, `monorepo` |
+| `--ci` | Generate `.github/workflows/drift-review.yml` |
+| `--baseline` | Generate `drift-baseline.json` from the current scan |
+
+`drift init` is non-destructive for pre-existing targets: drift skips generation when an output file already exists and prints a warning.
+
+---
+
+### `drift doctor`
+
+Run environment diagnostics for Node/runtime and project readiness.
+
+```bash
+drift doctor
+drift doctor --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output structured doctor report JSON |
+
+Checks include Node major version support (`>=18`), `package.json`, ESM mode, `tsconfig.json`, source file count, optional `--low-memory` recommendation, and `drift.config.*` detection.
+
+---
+
+### Repository smoke (local source CLI)
+
+Run a non-destructive end-to-end smoke suite against any repository path using local source commands (`node --import tsx ./src/cli.ts ...`).
+
+```bash
+npm run smoke:repo -- ../target-repo --base origin/main
+npm run smoke:repo -- ../target-repo --dry-run
+```
+
+The script writes JSON + Markdown summaries and command logs under `.drift-smoke/<repo>-<timestamp>/`.
+
 ### `drift scan [path]`
 
 Scan a directory and print a scored report to stdout.
@@ -77,16 +126,19 @@ drift scan ./src --low-memory --max-file-size-kb 1024
 | Flag | Description |
 |------|-------------|
 | `--output <file>` | Write Markdown report to a file instead of stdout |
+| `--format <type>` | Output format: `console\|json\|markdown\|ai\|sarif` |
 | `--json` | Output raw `DriftReport` JSON |
 | `--ai` | Output structured JSON optimized for LLM consumption (Claude, GPT, etc.) |
 | `--fix` | Print inline fix suggestions for each detected issue |
-| `--min-score <n>` | Exit with code 1 if the overall score meets or exceeds this threshold |
+| `--min-score <n>` | Exit with code 1 if the overall score strictly exceeds this threshold |
 | `--low-memory` | Analyze files in bounded chunks to reduce peak RAM |
 | `--chunk-size <n>` | Files per chunk in low-memory mode (default: 40) |
 | `--max-files <n>` | Soft cap on analyzed files; extra files are skipped with diagnostics |
 | `--max-file-size-kb <n>` | Skip oversized files with diagnostics to avoid OOM |
 | `--with-semantic-duplication` | Keep semantic duplication rule enabled in low-memory mode |
 
+`--min-score` currently fails when `totalScore > n` (strictly greater than), matching CLI behavior.
+
 **Example output:**
 
 ```
@@ -113,6 +165,33 @@ drift scan ./src --low-memory --max-file-size-kb 1024
 
 ---
 
+### `drift guard [path]`
+
+Evaluate drift regression guardrails against a git diff (`--base`) or a baseline file/object.
+
+```bash
+drift guard ./src --base origin/main
+drift guard ./src --baseline drift-baseline.json
+drift guard ./src --base origin/main --budget 3 --by-severity error=0,warning=2,info=5
+drift guard ./src --base origin/main --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--base <ref>` | Diff mode: compare current state vs git ref |
+| `--baseline <file>` | Baseline mode: compare against baseline JSON (default file name: `drift-baseline.json`) |
+| `--budget <n>` | Maximum allowed score delta |
+| `--by-severity <spec>` | Severity thresholds as CSV `key=value` pairs (`error`, `warning`, `info`) |
+| `--json` | Output full `GuardResult` JSON |
+| `--low-memory` / `--chunk-size <n>` / `--max-files <n>` / `--max-file-size-kb <n>` / `--with-semantic-duplication` | Analysis resource controls shared with scan/diff/report/badge/ci/trust |
+
+Behavior:
+- With `--base`, guard enforces no-regression checks for score and total issues, then applies optional budget/severity thresholds.
+- Without `--base`, guard requires a baseline (inline or file) and compares only against available baseline anchors.
+- Exit code is `1` when any guard check fails.
+
+---
+
 ### `drift diff [ref]`
 
 Compare the current project state against any git ref. Defaults to `HEAD~1`.
@@ -122,6 +201,7 @@ drift diff                # HEAD vs HEAD~1
 drift diff HEAD~3         # HEAD vs 3 commits ago
 drift diff main           # HEAD vs branch main
 drift diff abc1234        # HEAD vs a specific commit
+drift diff --format sarif # Output SARIF for code scanning
 drift diff --json         # Output raw JSON diff
 ```
 
@@ -129,6 +209,7 @@ drift diff --json         # Output raw JSON diff
 
 | Flag | Description |
 |------|-------------|
+| `--format <type>` | Output format: `console\|json\|sarif` |
 | `--json` | Output raw JSON diff |
 
 Shows score delta, issues introduced, and issues resolved since the given ref.
@@ -143,12 +224,14 @@ Review drift against a git base ref and output a PR-ready markdown comment.
 drift review --base origin/main
 drift review --base main --comment
 drift review --base HEAD~3 --json
+drift review --base origin/main --format sarif
 drift review --base origin/main --fail-on 5
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--base <ref>` | Git base ref to compare against (default: `origin/main`) |
+| `--format <type>` | Output format: `console\|json\|markdown\|sarif` |
 | `--json` | Output structured review JSON |
 | `--comment` | Print only the markdown body for PR comments |
 | `--fail-on <n>` | Exit code 1 when score delta is greater than or equal to `n` |
@@ -167,6 +250,7 @@ drift trust ./src
 drift trust ./src --json
 drift trust ./src --base origin/main
 drift trust ./src --base origin/main --markdown
+drift trust ./src --format sarif
 drift trust ./src --markdown --output trust.md
 drift trust ./src --min-trust 45
 drift trust ./src --max-risk HIGH
@@ -180,6 +264,7 @@ drift trust ./src --advanced-trust --history-file ./drift-history.json --markdow
 | Flag | Description |
 |------|-------------|
 | `--base <ref>` | Compare against a git base ref and include deterministic diff-aware penalties/bonuses |
+| `--format <type>` | Output format: `console\|json\|markdown\|sarif` |
 | `--json` | Output structured trust JSON (`trust_score`, `merge_risk`, `top_reasons`, `fix_priorities`, optional `diff_context`) |
 | `--markdown` | Output PR-ready markdown trust summary |
 | `--output <file>` | Write selected trust output format to file |
@@ -308,6 +393,7 @@ Emit GitHub Actions annotations and a step summary. Designed to run inside a CI
 ```bash
 drift ci                  # scan current directory
 drift ci ./src
+drift ci ./src --format sarif
 drift ci ./src --min-score 60
 ```
 
@@ -315,7 +401,8 @@ drift ci ./src --min-score 60
 
 | Flag | Description |
 |------|-------------|
-| `--min-score <n>` | Exit with code 1 if the overall score meets or exceeds this threshold |
+| `--format <type>` | Output format: `console\|json\|sarif` |
+| `--min-score <n>` | Exit with code 1 if the overall score strictly exceeds this threshold |
 
 Outputs `::error` and `::warning` annotations visible in the PR diff. Writes a markdown summary to `$GITHUB_STEP_SUMMARY`.
 
@@ -427,36 +514,28 @@ export default {
 
 ## Rules
 
-26 rules across three severity levels. All run automatically unless marked as requiring configuration.
+drift currently defines **35 rule IDs** in `RULE_WEIGHTS` (`src/analyzer.ts`): core detections, configurable architecture checks, AI/meta aggregation, plugin diagnostics, and analysis guardrail diagnostics.
+
+For the complete up-to-date catalog (id, severity, weight, phase/origin, note), see [`docs/rules-catalog.md`](./docs/rules-catalog.md).
+
+Highlights:
 
 | Rule | Severity | Weight | What it detects |
 |------|----------|--------|-----------------|
-| `large-file` | error | 20 | Files exceeding 300 lines — AI generates monolithic files instead of splitting responsibility |
-| `large-function` | error | 15 | Functions exceeding 50 lines — AI avoids decomposing logic into smaller units |
-| `duplicate-function-name` | error | 18 | Function names that appear more than once (case-insensitive) — AI regenerates helpers instead of reusing them |
-| `high-complexity` | error | 15 | Cyclomatic complexity above 10 — AI produces correct code, not necessarily simple code |
-| `circular-dependency` | error | 14 | Circular import chains between modules — AI doesn't reason about module topology |
-| `layer-violation` | error | 16 | Imports that cross architectural layers in the wrong direction (e.g., domain importing from infra) — requires `drift.config.ts` |
-| `debug-leftover` | warning | 10 | `console.log`, `console.warn`, `console.error`, and `TODO` / `FIXME` / `HACK` comments — AI leaves scaffolding in place |
-| `dead-code` | warning | 8 | Named imports that are never used in the file — AI imports broadly |
-| `any-abuse` | warning | 8 | Explicit `any` type annotations — AI defaults to `any` when type inference is unclear |
-| `catch-swallow` | warning | 10 | Empty `catch` blocks — AI makes code not throw without handling the error |
-| `comment-contradiction` | warning | 12 | Comments that restate what the surrounding code already expresses — AI over-documents the obvious |
-| `deep-nesting` | warning | 12 | Control flow nested more than 3 levels deep — results in code that is difficult to follow |
-| `too-many-params` | warning | 8 | Functions with more than 4 parameters — AI avoids grouping related arguments into objects |
-| `high-coupling` | warning | 10 | Files importing from more than 10 distinct modules — AI imports broadly without encapsulation |
-| `promise-style-mix` | warning | 7 | `async/await` and `.then()` / `.catch()` used together in the same file — AI combines styles inconsistently |
-| `unused-export` | warning | 8 | Named exports that are never imported anywhere in the project — cross-file dead code ESLint cannot detect |
-| `dead-file` | warning | 10 | Files never imported by any other file in the project — invisible dead code |
-| `unused-dependency` | warning | 6 | Packages listed in `package.json` with no corresponding import in source files |
-| `cross-boundary-import` | warning | 10 | Imports that cross module boundaries outside the allowed list — requires `drift.config.ts` |
-| `hardcoded-config` | warning | 10 | Hardcoded URLs, IP addresses, secrets, or connection strings — AI skips environment variable abstraction |
-| `inconsistent-error-handling` | warning | 8 | Mixed `try/catch` and `.catch()` patterns in the same file — AI combines approaches without a consistent strategy |
-| `unnecessary-abstraction` | warning | 7 | Wrapper functions or helpers that add no logic over what they wrap — AI over-engineers simple calls |
-| `naming-inconsistency` | warning | 6 | Mixed `camelCase` and `snake_case` in the same module — AI forgets project conventions mid-generation |
-| `semantic-duplication` | warning | 12 | Functions with structurally identical logic despite different names — detected via AST fingerprinting, not text comparison |
-| `no-return-type` | info | 5 | Functions missing an explicit return type annotation |
-| `magic-number` | info | 3 | Numeric literals used directly in logic without a named constant |
+| `large-file` | error | 20 | Files exceeding 300 lines |
+| `duplicate-function-name` | error | 18 | Same function name repeated across a file |
+| `high-complexity` | error | 15 | Cyclomatic complexity above threshold |
+| `layer-violation` | error | 16 | Invalid layer import direction (requires `layers` config) |
+| `cross-boundary-import` | warning | 10 | Invalid module boundary import (requires `modules`/legacy boundaries config) |
+| `controller-no-db` | warning | 11 | Controller touching DB directly (configurable architecture rule) |
+| `service-no-http` | warning | 11 | Service layer coupled to HTTP concerns (configurable architecture rule) |
+| `max-function-lines` | warning | 9 | Function line cap enforced by `architectureRules.maxFunctionLines` |
+| `semantic-duplication` | warning | 12 | AST-level semantic function duplication |
+| `ai-code-smell` | warning | 12 | Aggregated AI-smell signal from multiple heuristics in a file |
+| `plugin-error` | warning | 4 | Plugin load/contract/runtime failure surfaced as issue |
+| `plugin-warning` | info | 0 | Non-fatal plugin validation warning |
+| `analysis-skip-max-files` | info | 0 | File skipped by `maxFiles` guardrail |
+| `analysis-skip-file-size` | info | 0 | File skipped by `maxFileSizeKb` guardrail |
 
 ---
 
@@ -476,7 +555,7 @@ export default {
 
 ## Configuration
 
-drift runs with zero configuration. Architectural rules (`layer-violation`, `cross-boundary-import`) require a `drift.config.ts` (or `.js` / `.json`) at your project root:
+drift runs with zero configuration. Architectural rules (`layer-violation`, `cross-boundary-import`) and configurable architecture checks use `drift.config.ts` (or `.js` / `.json`) at project root:
 
 ```typescript
 import type { DriftConfig } from '@eduardbar/drift'
@@ -509,22 +588,16 @@ export default {
     { name: 'app',     patterns: ['src/app/**'],     canImportFrom: ['domain'] },
     { name: 'infra',   patterns: ['src/infra/**'],   canImportFrom: ['domain', 'app'] },
   ],
-  boundaries: [
+  modules: [
     { name: 'auth',    root: 'src/modules/auth',    allowedExternalImports: ['src/shared'] },
     { name: 'billing', root: 'src/modules/billing', allowedExternalImports: ['src/shared'] },
   ],
-  exclude: [
-    'src/generated/**',
-    '**/*.spec.ts',
-  ],
-  rules: {
-    'large-file': { threshold: 400 },   // override default 300
-    'magic-number': 'off',              // disable a rule
-  },
 } satisfies DriftConfig
 ```
 
-Without a config file, `layer-violation` and `cross-boundary-import` are silently skipped. All other rules run with their defaults.
+For backwards compatibility, `moduleBoundaries` and `boundaries` are normalized to `modules`.
+
+Without a config file, `layer-violation`, `cross-boundary-import`, and configurable architecture checks (`controller-no-db`, `service-no-http`, `max-function-lines`) are skipped. All other rules run with defaults.
 
 ### Memory guardrails (recommended for large repos)
 
@@ -563,7 +636,7 @@ jobs:
         run: npx @eduardbar/drift scan ./src --min-score 60
 ```
 
-Exit code is `1` if the score meets or exceeds `--min-score`. Exit code `0` otherwise.
+Exit code is `1` if the score is strictly greater than `--min-score`. Exit code `0` otherwise.
 
 ### Annotations and step summary with `drift ci`
 
@@ -595,11 +668,45 @@ The repository includes `.github/workflows/review-pr.yml`, which:
 - enforces a trust baseline gate with `drift trust-gate drift-trust.json --min-trust 45 --max-risk HIGH`
 - uploads `drift trust --json` as `drift-trust-json-pr-<PR_NUMBER>-run-<RUN_ATTEMPT>` for manual KPI tracking
 - publishes a compact trust KPI summary in `$GITHUB_STEP_SUMMARY` (score, merge risk, new/resolved issues when diff context is available)
+- generates `drift.sarif` via `drift scan --format sarif`, uploads it to GitHub Code Scanning on non-fork PRs, and stores the SARIF file as workflow artifact for traceability
+
+Quick local SARIF export:
+
+```bash
+drift scan ./src --format sarif > drift.sarif
+```
+
+Example GitHub Code Scanning upload with SARIF:
+
+```yaml
+- name: Generate drift SARIF
+  run: npx @eduardbar/drift scan ./src --format sarif > drift.sarif
+
+- name: Upload SARIF to Code Scanning
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: drift.sarif
+```
 
 Default gate behavior in this repo:
 - fail when trust is below 45
 - fail when merge risk is above `HIGH` (that means `CRITICAL` is blocked)
 
+### GitHub Action contract (v2)
+
+This repo also ships reusable local composite actions:
+
+- `./.github/actions/drift-scan`: score-focused scan gate using `npx @eduardbar/drift@<version>` (no global install).
+- `./.github/actions/drift-review`: trust/review/gate flow for PRs, aligned with `.github/workflows/review-pr.yml`.
+
+`drift-scan` exposes machine-friendly outputs for CI composition:
+- `score`, `grade`, `errors`, `warnings`, `infos`, `total-issues`, `files-affected`, `top-rules`
+
+`drift-review` exposes:
+- `trust-score`, `merge-risk`, `new-issues`, `resolved-issues`, `trust-json`, `trust-markdown`, `review-markdown`
+
+See `.github/actions/drift-scan/README.md` and `.github/actions/drift-review/README.md` for usage details.
+
 ---
 
 ## drift-ignore

package/dist/benchmark.d.ts

@@ -1,2 +1,2 @@
-export {};
+export declare function runBenchmarkCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=benchmark.d.ts.map

package/dist/benchmark.js

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { analyzeProject } from './analyzer.js';
 import { loadConfig } from './config.js';
 import { buildReport } from './reporter.js';
@@ -7,6 +8,30 @@ import { generateReview } from './review.js';
 import { buildTrustReport } from './trust.js';
 import { cleanupTempDir, extractFilesAtRef } from './git.js';
 import { computeDiff } from './diff.js';
+const DEFAULT_SCAN_PATH = '.';
+const DEFAULT_REVIEW_PATH = '.';
+const DEFAULT_TRUST_PATH = '.';
+const DEFAULT_BASE_REF = 'HEAD~1';
+const DEFAULT_WARMUP_RUNS = 1;
+const DEFAULT_MEASURED_RUNS = 5;
+const TABLE_WIDTHS = {
+    task: 10,
+    warmup: 8,
+    runs: 6,
+    median: 13,
+    mean: 11,
+    min: 10,
+    max: 10,
+};
+const TABLE_COLUMNS = [
+    { key: 'task', header: 'task' },
+    { key: 'warmup', header: 'warmup' },
+    { key: 'runs', header: 'runs' },
+    { key: 'median', header: 'median(ms)' },
+    { key: 'mean', header: 'mean(ms)' },
+    { key: 'min', header: 'min(ms)' },
+    { key: 'max', header: 'max(ms)' },
+];
 function parseNumberFlag(value, flagName) {
     const parsed = Number(value);
     if (!Number.isFinite(parsed) || parsed < 0) {
@@ -16,52 +41,29 @@ function parseNumberFlag(value, flagName) {
 }
 function parseOptions(argv) {
     const options = {
-        scanPath: '.',
-        reviewPath: '.',
-        trustPath: '.',
-        baseRef: 'HEAD~1',
-        warmupRuns: 1,
-        measuredRuns: 5,
+        scanPath: DEFAULT_SCAN_PATH,
+        reviewPath: DEFAULT_REVIEW_PATH,
+        trustPath: DEFAULT_TRUST_PATH,
+        baseRef: DEFAULT_BASE_REF,
+        warmupRuns: DEFAULT_WARMUP_RUNS,
+        measuredRuns: DEFAULT_MEASURED_RUNS,
     };
-    for (let i = 0; i < argv.length; i += 1) {
+    const handlers = {
+        '--scan-path': (value) => { options.scanPath = value; },
+        '--review-path': (value) => { options.reviewPath = value; },
+        '--trust-path': (value) => { options.trustPath = value; },
+        '--base': (value) => { options.baseRef = value; },
+        '--warmup': (value) => { options.warmupRuns = parseNumberFlag(value, '--warmup'); },
+        '--runs': (value) => { options.measuredRuns = parseNumberFlag(value, '--runs'); },
+        '--json-out': (value) => { options.jsonOut = value; },
+    };
+    for (let i = 0; i < argv.length; i += 2) {
         const arg = argv[i];
         const next = argv[i + 1];
-        if (arg === '--scan-path' && next) {
-            options.scanPath = next;
-            i += 1;
-            continue;
-        }
-        if (arg === '--review-path' && next) {
-            options.reviewPath = next;
-            i += 1;
-            continue;
-        }
-        if (arg === '--trust-path' && next) {
-            options.trustPath = next;
-            i += 1;
-            continue;
-        }
-        if (arg === '--base' && next) {
-            options.baseRef = next;
-            i += 1;
-            continue;
-        }
-        if (arg === '--warmup' && next) {
-            options.warmupRuns = parseNumberFlag(next, '--warmup');
-            i += 1;
-            continue;
-        }
-        if (arg === '--runs' && next) {
-            options.measuredRuns = parseNumberFlag(next, '--runs');
-            i += 1;
-            continue;
-        }
-        if (arg === '--json-out' && next) {
-            options.jsonOut = next;
-            i += 1;
-            continue;
-        }
-        throw new Error(`Unknown or incomplete argument: ${arg}`);
+        const handler = handlers[arg];
+        if (!handler || !next)
+            throw new Error(`Unknown or incomplete argument: ${arg}`);
+        handler(next);
     }
     if (options.measuredRuns < 1) {
         throw new Error('--runs must be at least 1');
@@ -107,8 +109,8 @@ async function runTask(name, warmupRuns, measuredRuns, task) {
     };
 }
 function printTable(results) {
-    const headers = ['task', 'warmup', 'runs', 'median(ms)', 'mean(ms)', 'min(ms)', 'max(ms)'];
-    const widths = [10, 8, 6, 13, 11, 10, 10];
+    const headers = TABLE_COLUMNS.map((column) => column.header);
+    const widths = TABLE_COLUMNS.map((column) => TABLE_WIDTHS[column.key]);
     const row = (values) => values
         .map((value, index) => value.padEnd(widths[index], ' '))
         .join(' ');
@@ -153,11 +155,14 @@ async function runTrust(trustPath, baseRef) {
     }
     buildTrustReport(report, { diff });
 }
-async function main() {
-    const options = parseOptions(process.argv.slice(2));
+async function runReview(reviewPath, baseRef) {
+    await generateReview(reviewPath, baseRef);
+}
+async function main(argv) {
+    const options = parseOptions(argv);
     const results = [
         await runTask('scan', options.warmupRuns, options.measuredRuns, () => runScan(options.scanPath)),
-        await runTask('review', options.warmupRuns, options.measuredRuns, () => generateReview(options.reviewPath, options.baseRef).then(() => undefined)),
+        await runTask('review', options.warmupRuns, options.measuredRuns, () => runReview(options.reviewPath, options.baseRef)),
         await runTask('trust', options.warmupRuns, options.measuredRuns, () => runTrust(options.trustPath, options.baseRef)),
     ];
     const output = {
@@ -178,8 +183,22 @@ async function main() {
         process.stdout.write(`\nSaved benchmark JSON to ${options.jsonOut}\n`);
     }
 }
-main().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    process.exit(1);
-});
+function isExecutedAsEntryPoint() {
+    const entryArg = process.argv[1];
+    if (!entryArg)
+        return false;
+    return import.meta.url === pathToFileURL(path.resolve(entryArg)).href;
+}
+export async function runBenchmarkCli(argv = process.argv.slice(2)) {
+    try {
+        await main(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    }
+}
+if (isExecutedAsEntryPoint()) {
+    void runBenchmarkCli();
+}
 //# sourceMappingURL=benchmark.js.map