@eduardbar/drift 1.0.0 → 1.2.0

package/.github/actions/drift-scan/README.md

@@ -0,0 +1,61 @@
+# drift-scan Action
+
+Scan your TypeScript project for AI-generated technical debt in CI.
+
+## Usage
+
+```yaml
+- name: Check drift score
+  uses: eduardbar/drift@v1
+  with:
+    path: ./src
+    min-score: 60
+```
+
+## Inputs
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `path` | Path to scan | `.` |
+| `min-score` | Fail if score exceeds this | `80` |
+| `fail-on-threshold` | Whether to fail on threshold | `true` |
+| `version` | drift version to use | `latest` |
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `score` | Project drift score (0-100) |
+| `grade` | Grade: CLEAN / LOW / MODERATE / HIGH / CRITICAL |
+
+## Example: PR gate
+
+```yaml
+name: Drift Check
+on: [pull_request]
+
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: eduardbar/drift@v1
+        with:
+          path: ./src
+          min-score: 60
+          fail-on-threshold: true
+```
+
+## Example: capture outputs
+
+```yaml
+- name: Scan drift
+  id: drift
+  uses: eduardbar/drift@v1
+  with:
+    path: ./src
+    fail-on-threshold: false
+
+- name: Print results
+  run: echo "Score ${{ steps.drift.outputs.score }}/100 — ${{ steps.drift.outputs.grade }}"
+```

package/.github/actions/drift-scan/action.yml

@@ -0,0 +1,65 @@
+name: 'Drift — Technical Debt Scanner'
+description: 'Scan TypeScript projects for AI-generated technical debt and enforce score thresholds'
+author: 'eduardbar'
+
+branding:
+  icon: 'activity'
+  color: 'purple'
+
+inputs:
+  path:
+    description: 'Path to scan'
+    required: false
+    default: '.'
+  min-score:
+    description: 'Fail if project score exceeds this threshold (0-100)'
+    required: false
+    default: '80'
+  fail-on-threshold:
+    description: 'Whether to fail the action if threshold is exceeded'
+    required: false
+    default: 'true'
+  version:
+    description: 'Version of @eduardbar/drift to use'
+    required: false
+    default: 'latest'
+
+outputs:
+  score:
+    description: 'The overall drift score (0-100)'
+    value: ${{ steps.scan.outputs.score }}
+  grade:
+    description: 'The drift grade (CLEAN / LOW / MODERATE / HIGH / CRITICAL)'
+    value: ${{ steps.scan.outputs.grade }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install drift
+      shell: bash
+      run: npm install -g @eduardbar/drift@${{ inputs.version }}
+
+    - name: Run drift scan
+      id: scan
+      shell: bash
+      run: |
+        TMPFILE=$(mktemp)
+
+        # Run scan — write JSON to tmp, progress to stderr (already separate)
+        drift scan ${{ inputs.path }} --ai > "$TMPFILE" 2>/dev/null || true
+
+        # Extract score and grade from AIOutput JSON
+        SCORE=$(node -e "const d=JSON.parse(require('fs').readFileSync('$TMPFILE','utf8')); console.log(d.summary.score)")
+        GRADE=$(node -e "const d=JSON.parse(require('fs').readFileSync('$TMPFILE','utf8')); console.log(d.summary.grade)")
+
+        rm "$TMPFILE"
+
+        echo "score=$SCORE" >> "$GITHUB_OUTPUT"
+        echo "grade=$GRADE" >> "$GITHUB_OUTPUT"
+
+        echo "Drift Score: $SCORE/100 ($GRADE)"
+
+        if [ "${{ inputs.fail-on-threshold }}" = "true" ] && [ "$SCORE" -gt "${{ inputs.min-score }}" ]; then
+          echo "::error::Drift score $SCORE/100 exceeds threshold of ${{ inputs.min-score }}"
+          exit 1
+        fi

package/.github/workflows/publish-vscode.yml

@@ -3,6 +3,8 @@ name: Publish VS Code Extension
 on:
   release:
     types: [published]
+    tags:
+      - 'vscode-v*'
   workflow_dispatch:
     inputs:
       version:
@@ -39,7 +41,7 @@ jobs:
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
             TAG_VERSION="${{ inputs.version }}"
           else
-            TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+            TAG_VERSION="${GITHUB_REF#refs/tags/vscode-v}"
           fi
           PKG_VERSION=$(node -p "require('./package.json').version")
           if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then

package/.github/workflows/review-pr.yml

@@ -0,0 +1,61 @@
+name: Drift PR Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  drift-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate drift review markdown
+        run: npx @eduardbar/drift review --base "origin/${{ github.base_ref }}" --comment > drift-review.md
+
+      - name: Post or update PR comment (non-fork only)
+        if: github.event.pull_request.head.repo.fork == false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          COMMENT_BODY="<!-- drift-review -->"
+          COMMENT_BODY+=$'\n'
+          COMMENT_BODY+="$(cat drift-review.md)"
+
+          EXISTING_ID=$(gh api "repos/$REPO/issues/$PR_NUMBER/comments" --jq '.[] | select(.user.login == "github-actions[bot]") | select(.body | contains("<!-- drift-review -->")) | .id' | sed -n '1p')
+
+          if [ -n "$EXISTING_ID" ]; then
+            gh api -X PATCH "repos/$REPO/issues/comments/$EXISTING_ID" -f "body=$COMMENT_BODY"
+          else
+            gh api -X POST "repos/$REPO/issues/$PR_NUMBER/comments" -f "body=$COMMENT_BODY"
+          fi
+
+      - name: Fallback summary for fork PRs
+        if: github.event.pull_request.head.repo.fork == true
+        run: |
+          {
+            echo "## drift review"
+            echo
+            cat drift-review.md
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Enforce drift threshold
+        run: npx @eduardbar/drift review --base "origin/${{ github.base_ref }}" --fail-on 5 --comment > /dev/null

package/AGENTS.md

@@ -20,6 +20,7 @@ Publicado en npm como `@eduardbar/drift`. MIT.
 | `kleur ^4` | Colores en consola (sin dependencias) |
 | `typescript ^5.9` | Dev — compilación |
 | `@types/node ^25` | Dev — tipos Node.js |
+| `vitest ^4` | Testing |
 
 **Runtime:** Node.js 18+, ES Modules (`"type": "module"`).
 
@@ -32,18 +33,47 @@ drift/
 ├── bin/
 │   └── drift.js          ← wrapper cross-platform (Windows npx fix)
 ├── src/
-│   ├── types.ts          ← interfaces: DriftIssue, FileReport, DriftReport, AIOutput
-│   ├── analyzer.ts       ← motor AST + 10 reglas de detección + drift-ignore
-│   ├── reporter.ts       ← buildReport(), formatMarkdown(), formatAIOutput()
-│   ├── printer.ts        ← salida consola con colores y score bar ASCII
-│   ├── utils.ts          ← scoreToGrade, severityIcon, scoreBar
-│   ├── index.ts          ← re-exports públicos (librería)
-│   └── cli.ts            ← entry point Commander.js
-├── assets/
-│   ├── og.svg / og.png           ← imagen OG original
-│   ├── og-v030-linkedin.svg/png  ← imagen post LinkedIn v0.3.0
-│   └── og-v030-x.svg/png         ← imagen hilo X v0.3.0
+│   ├── analyzer.ts       ← motor AST + 26 reglas + drift-ignore
+│   ├── types.ts         ← interfaces: DriftIssue, FileReport, DriftReport, AIOutput
+│   ├── reporter.ts      ← buildReport(), formatMarkdown(), formatAIOutput()
+│   ├── printer.ts       ← salida consola con colores y score bar ASCII
+│   ├── utils.ts         ← scoreToGrade, severityIcon, scoreBar
+│   ├── index.ts         ← re-exports públicos (librería)
+│   ├── cli.ts           ← entry point Commander.js
+│   ├── config.ts        ← drift.config.ts support
+│   ├── fix.ts           ← drift fix command
+│   ├── ci.ts            ← drift ci command
+│   ├── diff.ts          ← drift diff command
+│   ├── report.ts        ← drift report command
+│   ├── badge.ts         ← drift badge command
+│   ├── snapshot.ts      ← drift snapshot command
+│   ├── git.ts           ← re-exports git analyzers
+│   ├── git/
+│   │   ├── trend.ts     ← drift trend (historial de scores)
+│   │   ├── blame.ts     ← drift blame (atribución de deuda)
+│   │   └── helpers.ts
+│   └── rules/           ← reglas modularizadas por fase
+│       ├── phase0-basic.ts
+│       ├── phase1-complexity.ts
+│       ├── phase2-crossfile.ts    ← dead-file, unused-export, unused-dependency
+│       ├── phase3-arch.ts          ← circular-dependency, layer-violation
+│       ├── phase5-ai.ts
+│       ├── phase8-semantic.ts     ← semantic-duplication
+│       ├── complexity.ts
+│       ├── coupling.ts
+│       ├── nesting.ts
+│       ├── promise.ts
+│       ├── magic.ts
+│       ├── comments.ts
+│       └── shared.ts
+├── packages/
+│   ├── eslint-plugin-drift/       ← ESLint plugin oficial
+│   └── vscode-drift/              ← VS Code extension
 ├── dist/                 ← output tsc (no editar a mano)
+├── assets/
+│   ├── og.svg / og.png
+│   ├── og-v030-linkedin.svg/png
+│   └── og-v030-x.svg/png
 ├── .github/workflows/publish.yml
 ├── package.json
 ├── tsconfig.json
@@ -58,6 +88,8 @@ drift/
 npm run build       # tsc — compila src/ → dist/
 npm run dev         # tsc --watch
 npm start           # node dist/cli.js (desarrollo local)
+npm test            # vitest run
+npm run test:watch # vitest (watch mode)
 ```
 
 **Pre-publicación:** `prepublishOnly` corre `build` automáticamente.
@@ -226,6 +258,16 @@ Sin esto, Windows no ejecuta el shebang correctamente con ES modules.
 
 ---
 
+## Estado actual (feb 2026)
+
+- **Versión publicada:** `1.0.0`
+- **Branch:** `master`, sincronizado con `origin`
+- **Self-scan score:** 5/100 (LOW)
+- **Top issues:** 51× magic-number, 2× deep-nesting, 2× catch-swallow
+- **26 reglas activas** organizadas en fases
+
+---
+
 ## Convenciones de código
 
 - Todo en TypeScript — sin `any` explícito (drift se corre sobre sí mismo)

package/README.md

@@ -10,7 +10,7 @@ Detect technical debt in AI-generated TypeScript code. One command. Zero config.
 ![ts-morph](https://img.shields.io/badge/powered%20by-ts--morph-6366f1.svg)
 ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)
 
-[Why](#why) · [Installation](#installation) · [Commands](#commands) · [Rules](#rules) · [Score](#score) · [Configuration](#configuration) · [CI Integration](#ci-integration) · [drift-ignore](#drift-ignore) · [Contributing](#contributing)
+[Why](#why) · [Installation](#installation) · [Product Docs](#product-docs) · [Commands](#commands) · [Rules](#rules) · [Score](#score) · [Configuration](#configuration) · [CI Integration](#ci-integration) · [drift-ignore](#drift-ignore) · [Contributing](#contributing)
 
 ---
 
@@ -47,6 +47,13 @@ npm install --save-dev @eduardbar/drift
 
 ---
 
+## Product Docs
+
+- Product requirements and roadmap: [`docs/PRD.md`](./docs/PRD.md)
+- Contributor/agent workflow guide: [`docs/AGENTS.md`](./docs/AGENTS.md)
+
+---
+
 ## Commands
 
 ### `drift scan [path]`
@@ -121,6 +128,47 @@ Shows score delta, issues introduced, and issues resolved since the given ref.
 
 ---
 
+### `drift review`
+
+Review drift against a git base ref and output a PR-ready markdown comment.
+
+```bash
+drift review --base origin/main
+drift review --base main --comment
+drift review --base HEAD~3 --json
+drift review --base origin/main --fail-on 5
+```
+
+| Flag | Description |
+|------|-------------|
+| `--base <ref>` | Git base ref to compare against (default: `origin/main`) |
+| `--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` |
+
+---
+
+### `drift map [path]`
+
+Generate an `architecture.svg` map with inferred layer dependencies. When layer config is present, the SVG also highlights cycle edges and layer violations.
+
+```bash
+drift map
+drift map ./src
+drift map ./src --output docs/architecture.svg
+```
+
+| Flag | Description |
+|------|-------------|
+| `--output <file>` | Output path for the SVG file (default: `architecture.svg`) |
+
+Edge legend in SVG:
+- Gray: normal dependency
+- Orange: cycle edge
+- Red: layer violation edge
+
+---
+
 ### `drift report [path]`
 
 Generate a self-contained HTML report. No server required — open in any browser.
@@ -220,6 +268,49 @@ drift blame file --top 10
 
 ---
 
+### `drift fix [path]`
+
+Auto-fix safe issues with explicit preview/write modes.
+
+```bash
+drift fix ./src --preview
+drift fix ./src --write
+drift fix ./src --write --yes
+drift fix ./src --dry-run   # alias of --preview
+```
+
+| Flag | Description |
+|------|-------------|
+| `--preview` | Preview before/after without writing files |
+| `--write` | Apply fixes to disk |
+| `--dry-run` | Backward-compatible alias for preview mode |
+| `--yes` | Skip interactive confirmation for write mode |
+
+---
+
+### `drift cloud`
+
+Local SaaS foundations backed by `.drift-cloud/store.json`.
+
+```bash
+drift cloud ingest ./src --workspace acme --user u-123 --repo webapp
+drift cloud summary
+drift cloud summary --json
+drift cloud dashboard --output drift-cloud-dashboard.html
+```
+
+**Subcommands:**
+
+| Command | Description |
+|---------|-------------|
+| `drift cloud ingest [path] --workspace <id> --user <id> [--repo <name>] [--store <file>]` | Scans the path and stores one SaaS snapshot |
+| `drift cloud summary [--json] [--store <file>]` | Shows users/workspaces/repos usage and runs per month |
+| `drift cloud dashboard [--output <file>] [--store <file>]` | Generates an HTML dashboard with trends and hotspots |
+
+`drift cloud` ships with a free-until-7,500 strategy and configurable guardrails for the free phase: max runs per workspace per month, max repos per workspace, and retention window.
+
+---
+
 ## Rules
 
 26 rules across three severity levels. All run automatically unless marked as requiring configuration.
@@ -277,6 +368,12 @@ drift runs with zero configuration. Architectural rules (`layer-violation`, `cro
 import type { DriftConfig } from '@eduardbar/drift'
 
 export default {
+  plugins: ['drift-plugin-example'],
+  architectureRules: {
+    controllerNoDb: true,
+    serviceNoHttp: true,
+    maxFunctionLines: 80,
+  },
   layers: [
     { name: 'domain',  patterns: ['src/domain/**'],  canImportFrom: [] },
     { name: 'app',     patterns: ['src/app/**'],     canImportFrom: ['domain'] },
@@ -345,6 +442,14 @@ jobs:
 
 `drift ci` emits `::error` and `::warning` annotations that appear inline in the PR diff and writes a formatted summary to `$GITHUB_STEP_SUMMARY`. Use this when you want visibility beyond a pass/fail exit code.
 
+### Auto PR comment with `drift review`
+
+The repository includes `.github/workflows/review-pr.yml`, which:
+- generates a PR-ready markdown comment from `drift review --comment`
+- updates a single sticky comment (`<!-- drift-review -->`) on non-fork PRs
+- falls back to `$GITHUB_STEP_SUMMARY` for fork PRs
+- enforces a score delta threshold with `--fail-on`
+
 ---
 
 ## drift-ignore

package/dist/analyzer.d.ts

@@ -1,10 +1,14 @@
-import type { DriftIssue, FileReport, DriftConfig } from './types.js';
+import type { DriftIssue, FileReport, DriftConfig, LoadedPlugin } from './types.js';
 export { TrendAnalyzer } from './git/trend.js';
 export { BlameAnalyzer } from './git/blame.js';
 export declare const RULE_WEIGHTS: Record<string, {
     severity: DriftIssue['severity'];
     weight: number;
 }>;
-export declare function analyzeFile(file: import('ts-morph').SourceFile): FileReport;
+export declare function analyzeFile(file: import('ts-morph').SourceFile, options?: DriftConfig | {
+    config?: DriftConfig;
+    loadedPlugins?: LoadedPlugin[];
+    projectRoot?: string;
+}): FileReport;
 export declare function analyzeProject(targetPath: string, config?: DriftConfig): FileReport[];
 //# sourceMappingURL=analyzer.d.ts.map

package/dist/analyzer.js

@@ -4,11 +4,18 @@ import { Project } from 'ts-morph';
 // Rules
 import { isFileIgnored } from './rules/shared.js';
 import { detectLargeFile, detectLargeFunctions, detectDebugLeftovers, detectDeadCode, detectDuplicateFunctionNames, detectAnyAbuse, detectCatchSwallow, detectMissingReturnTypes, } from './rules/phase0-basic.js';
-import { detectHighComplexity, detectDeepNesting, detectTooManyParams, detectHighCoupling, detectPromiseStyleMix, detectMagicNumbers, detectCommentContradiction, } from './rules/phase1-complexity.js';
+import { detectHighComplexity } from './rules/complexity.js';
+import { detectDeepNesting, detectTooManyParams } from './rules/nesting.js';
+import { detectHighCoupling } from './rules/coupling.js';
+import { detectPromiseStyleMix } from './rules/promise.js';
+import { detectMagicNumbers } from './rules/magic.js';
+import { detectCommentContradiction } from './rules/comments.js';
 import { detectDeadFiles, detectUnusedExports, detectUnusedDependencies, } from './rules/phase2-crossfile.js';
 import { detectCircularDependencies, detectLayerViolations, detectCrossBoundaryImports, } from './rules/phase3-arch.js';
+import { detectControllerNoDb, detectServiceNoHttp, detectMaxFunctionLines, } from './rules/phase3-configurable.js';
 import { detectOverCommented, detectHardcodedConfig, detectInconsistentErrorHandling, detectUnnecessaryAbstraction, detectNamingInconsistency, } from './rules/phase5-ai.js';
 import { collectFunctions, fingerprintFunction, calculateScore, } from './rules/phase8-semantic.js';
+import { loadPlugins } from './plugins.js';
 // Git analyzers (re-exported as part of the public API)
 export { TrendAnalyzer } from './git/trend.js';
 export { BlameAnalyzer } from './git/blame.js';
@@ -41,19 +48,95 @@ export const RULE_WEIGHTS = {
     // Phase 3b/c: layer and module boundary enforcement (require drift.config.ts)
     'layer-violation': { severity: 'error', weight: 16 },
     'cross-boundary-import': { severity: 'warning', weight: 10 },
+    'controller-no-db': { severity: 'warning', weight: 11 },
+    'service-no-http': { severity: 'warning', weight: 11 },
+    'max-function-lines': { severity: 'warning', weight: 9 },
     // Phase 5: AI authorship heuristics
     'over-commented': { severity: 'info', weight: 4 },
     'hardcoded-config': { severity: 'warning', weight: 10 },
     'inconsistent-error-handling': { severity: 'warning', weight: 8 },
     'unnecessary-abstraction': { severity: 'warning', weight: 7 },
     'naming-inconsistency': { severity: 'warning', weight: 6 },
+    'ai-code-smell': { severity: 'warning', weight: 12 },
     // Phase 8: semantic duplication
     'semantic-duplication': { severity: 'warning', weight: 12 },
+    'plugin-error': { severity: 'warning', weight: 4 },
 };
+const AI_SMELL_SIGNALS = new Set([
+    'over-commented',
+    'hardcoded-config',
+    'inconsistent-error-handling',
+    'unnecessary-abstraction',
+    'naming-inconsistency',
+    'comment-contradiction',
+    'promise-style-mix',
+    'any-abuse',
+]);
+function detectAICodeSmell(issues, filePath) {
+    const signalCounts = new Map();
+    for (const issue of issues) {
+        if (!AI_SMELL_SIGNALS.has(issue.rule))
+            continue;
+        signalCounts.set(issue.rule, (signalCounts.get(issue.rule) ?? 0) + 1);
+    }
+    const totalSignals = [...signalCounts.values()].reduce((sum, count) => sum + count, 0);
+    if (totalSignals < 3)
+        return [];
+    const triggers = [...signalCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([rule, count]) => `${rule} x${count}`);
+    return [{
+            rule: 'ai-code-smell',
+            severity: 'warning',
+            message: `Aggregated AI smell signals detected (${totalSignals}): ${triggers.join(', ')}`,
+            line: 1,
+            column: 1,
+            snippet: path.basename(filePath),
+        }];
+}
+function runPluginRules(file, loadedPlugins, config, projectRoot) {
+    if (loadedPlugins.length === 0)
+        return [];
+    const context = {
+        projectRoot,
+        filePath: file.getFilePath(),
+        config,
+    };
+    const issues = [];
+    for (const loaded of loadedPlugins) {
+        for (const rule of loaded.plugin.rules) {
+            try {
+                const detected = rule.detect(file, context) ?? [];
+                for (const issue of detected) {
+                    issues.push({
+                        ...issue,
+                        rule: issue.rule || `${loaded.plugin.name}/${rule.name}`,
+                        severity: issue.severity ?? (rule.severity ?? 'warning'),
+                    });
+                }
+            }
+            catch (error) {
+                issues.push({
+                    rule: 'plugin-error',
+                    severity: 'warning',
+                    message: `Plugin '${loaded.id}' rule '${rule.name}' failed: ${error instanceof Error ? error.message : String(error)}`,
+                    line: 1,
+                    column: 1,
+                    snippet: file.getBaseName(),
+                });
+            }
+        }
+    }
+    return issues;
+}
 // ---------------------------------------------------------------------------
 // Per-file analysis
 // ---------------------------------------------------------------------------
-export function analyzeFile(file) {
+export function analyzeFile(file, options) {
+    const normalizedOptions = (options && typeof options === 'object' && ('config' in options || 'loadedPlugins' in options || 'projectRoot' in options))
+        ? options
+        : { config: (options && typeof options === 'object' ? options : undefined) };
     if (isFileIgnored(file)) {
         return {
             path: file.getFilePath(),
@@ -84,7 +167,14 @@ export function analyzeFile(file) {
         ...detectInconsistentErrorHandling(file),
         ...detectUnnecessaryAbstraction(file),
         ...detectNamingInconsistency(file),
+        // Configurable architecture rules
+        ...detectControllerNoDb(file, normalizedOptions?.config),
+        ...detectServiceNoHttp(file, normalizedOptions?.config),
+        ...detectMaxFunctionLines(file, normalizedOptions?.config),
+        // Plugin rules
+        ...runPluginRules(file, normalizedOptions?.loadedPlugins ?? [], normalizedOptions?.config, normalizedOptions?.projectRoot ?? path.dirname(file.getFilePath())),
     ];
+    issues.push(...detectAICodeSmell(issues, file.getFilePath()));
     return {
         path: file.getFilePath(),
         issues,
@@ -113,8 +203,13 @@ export function analyzeProject(targetPath, config) {
         `!${targetPath}/**/*.spec.*`,
     ]);
     const sourceFiles = project.getSourceFiles();
+    const pluginRuntime = loadPlugins(targetPath, config?.plugins);
     // Phase 1: per-file analysis
-    const reports = sourceFiles.map(analyzeFile);
+    const reports = sourceFiles.map((file) => analyzeFile(file, {
+        config,
+        loadedPlugins: pluginRuntime.plugins,
+        projectRoot: targetPath,
+    }));
     const reportByPath = new Map();
     for (const r of reports)
         reportByPath.set(r.path, r);
@@ -172,6 +267,24 @@ export function analyzeProject(targetPath, config) {
             }
         }
     }
+    // Plugin load failures are surfaced as synthetic report entries.
+    if (pluginRuntime.errors.length > 0) {
+        for (const err of pluginRuntime.errors) {
+            const pluginIssue = {
+                rule: 'plugin-error',
+                severity: 'warning',
+                message: `Failed to load plugin '${err.pluginId}': ${err.message}`,
+                line: 1,
+                column: 1,
+                snippet: err.pluginId,
+            };
+            reports.push({
+                path: path.join(targetPath, '.drift-plugin-errors', `${err.pluginId}.plugin`),
+                issues: [pluginIssue],
+                score: calculateScore([pluginIssue], RULE_WEIGHTS),
+            });
+        }
+    }
     // ── Phase 2: dead-file + unused-export + unused-dependency ─────────────────
     const deadFiles = detectDeadFiles(sourceFiles, allImportedPaths, RULE_WEIGHTS);
     for (const [sfPath, issue] of deadFiles) {