@dinyangetoh/codeplug-cli 0.1.3 → 0.1.4

package/README.md

@@ -1,55 +1,75 @@
 # CodePlug
 
+## Executive Summary
+
+This document provides comprehensive technical documentation for CodePlug, a local-first CLI tool designed to detect, enforce, and document coding conventions across TypeScript/JavaScript codebases. The guide covers installation, configuration, usage commands, project architecture, and development workflows for teams seeking automated codebase governance with AI agent integration capabilities.
+
+---
+
+## Overview
+
 **The source of truth for codebase understanding and governance.**
 
 CodePlug is a local-first CLI tool that detects your codebase's coding conventions, enforces them with drift detection and compliance scoring, generates living documentation, and exports convention context for AI coding agents.
 
+The tool operates entirely on-device using ML models for pattern detection, ensuring your codebase data never leaves your machine unless you explicitly configure cloud LLM providers for enhanced documentation generation.
+
 ---
 
-## Features
+## Key Features
 
-- **Convention Detection** -- AST analysis with on-device ML identifies naming patterns, folder structure, component styles, test organization, error handling, and import conventions across your TypeScript/JavaScript codebase.
-- **Drift & Compliance** -- Classifies git diffs against stored conventions, scores compliance with severity-weighted metrics, tracks trends over time, and auto-fixes what it can.
-- **Living Documentation** -- Generates and maintains README, ARCHITECTURE, CONVENTIONS, CONTRIBUTING, and ONBOARDING docs using ML summarization and optional LLM enhancement.
-- **AI Agent Export** -- Exports your conventions as `CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md`, structured JSON, and SARIF-format CI reports.
+### Convention Detection
 
----
+AST analysis with on-device ML identifies naming patterns, folder structure, component styles, test organization, error handling, and import conventions across your TypeScript/JavaScript codebase.
 
-## Quick Start
+### Drift & Compliance
 
-```bash
-# Install globally
-npm install -g @dinyangetoh/codeplug-cli
+Classifies git diffs against stored conventions, scores compliance with severity-weighted metrics, tracks trends over time, and auto-fixes what it can.
 
-# Navigate to your project
-cd your-project
+### Living Documentation
 
-# Detect and confirm conventions
-codeplug convention init
+Generates and maintains README, ARCHITECTURE, CONVENTIONS, CONTRIBUTING, and ONBOARDING docs using ML summarization and optional LLM enhancement.
 
-# Check compliance
-codeplug convention audit
-```
+### AI Agent Export
+
+Exports your conventions as `CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md`, structured JSON, and SARIF-format CI reports.
+
+### All Features
+
+| Category | Feature | Command / Config | Notes |
+|----------|---------|------------------|-------|
+| CLI | Interactive wizard | `codeplug start` | Config, Convention, Docs, Export menus; see [COMMAND.md](COMMAND.md) |
+| Convention | Detection (6 dimensions) | `convention init` | Naming, Component, Test, ErrorHandling, Import, Schema visitors |
+| Convention | Structure (7th dimension) | `convention audit` | StructureVisitor in ViolationDetector |
+| Convention | Drift | `convention drift` | Rule-based diff classification |
+| Convention | Compliance | `convention audit`, `score` | Severity-weighted, sql.js time-series |
+| Convention | Auto-fix | `convention fix` | Rename + manual guidance |
+| Convention | Semantic coherence | `convention.enableSemanticCoherence` | Opt-in; zero-shot + sentenceSimilarity |
+| Convention | Custom rules | `.codeplug/rules.json` | Regex rules (filename, path, content) |
+| Docs | Generate / Status / Update | `docs generate/status/update` | 5 docs, ML pipeline + optional LLM; template fallback |
+| Export | Claude / Cursor / Copilot | `export --target` | CLAUDE.md, .cursor/rules, .github/copilot-instructions |
+| Export | JSON / CI (SARIF) | `export --target json/ci` | .codeplug/exports/, .codeplug/ci-report.json |
+| Config | Model tier, LLM provider | `config set` | default / lite; 8 providers |
 
 ---
 
 ## Prerequisites
 
-- **Node.js 20+** (required)
-- **Git** (required for drift detection and history analysis)
-- **Ollama** (optional, for LLM-enhanced documentation -- any OpenAI-compatible provider works)
+- **Node.js 20+** (required) — CodePlug is built with TypeScript and requires Node.js 20 or higher for native fetch and modern ESM support.
+- **Git** (required for drift detection and history analysis) — CodePlug integrates with Git for diff analysis, commit history inspection, and pre-commit hook management.
+- **Ollama** (optional) — For LLM-enhanced documentation. Any OpenAI-compatible provider works as an alternative.
 
 ---
 
 ## Installation
 
-### Global install
+### Global Install
 
 ```bash
 npm install -g @dinyangetoh/codeplug-cli
 ```
 
-### Local development
+### Local Development
 
 ```bash
 git clone <repo-url>
@@ -61,8 +81,50 @@ node dist/cli/index.js --help
 
 ---
 
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @dinyangetoh/codeplug-cli
+
+# Navigate to your project
+cd your-project
+
+# Interactive wizard — single entry point for new users
+codeplug start
+```
+
+Or run commands directly:
+
+```bash
+# Detect and confirm conventions
+codeplug convention init
+
+# Check compliance
+codeplug convention audit
+```
+
+---
+
 ## Usage
 
+### Interactive Wizard
+
+```bash
+codeplug start
+```
+
+Launches an interactive menu with four core areas:
+
+| Menu     | Options                                                                 |
+| -------- | ----------------------------------------------------------------------- |
+| Config   | View full config, Set provider/model/API key/tier, Back                  |
+| Convention | Initialize, Run audit, Check drift, Show score, Auto-fix, Back        |
+| Docs     | Generate docs, Check status, Update stale, Back                          |
+| Export   | Export all targets, Check freshness, Back                                |
+
+Use arrow keys to navigate and Enter to select. Each sub-menu has a Back option to return.
+
 ### Convention Detection
 
 ```bash
@@ -162,6 +224,12 @@ codeplug config set llm.model gpt-4o
 codeplug config set llm.apiKey sk-...
 ```
 
+### Planned / Partial Features
+
+- **`convention show <commit>`**: Listed in help; returns "Not yet implemented. Coming in Phase 2."
+- **Pre-commit hook**: PreCommitHook class exists; `codeplug hook install/uninstall` commands are not yet exposed (programmatic API; coming soon).
+- **Export `--target ci`**: Produces SARIF 2.1.0 at `.codeplug/ci-report.json` for CI integration.
+
 ---
 
 ## Configuration
@@ -198,6 +266,56 @@ codeplug config set models.tier lite
 
 Switching to `lite` prints a warning about potential quality degradation.
 
+### Configurable Sections
+
+CodePlug supports optional sections in `.codeplug/config.json`. Each section merges with built-in defaults (shallow merge). Omit a section to keep defaults.
+
+```mermaid
+flowchart TB
+  subgraph sources [Config Sources]
+    Defaults[DEFAULT_CONFIG]
+    User[config.json]
+  end
+  Defaults --> Merge[ConfigManager.load]
+  User --> Merge
+  Merge --> Config[CodePlugConfig]
+  Config --> Structure[structure]
+  Config --> Analysis[analysis]
+  Config --> Scoring[scoring]
+  Config --> Convention[convention]
+  Config --> Drift[drift]
+  Config --> Docs[docs]
+  Config --> Naming[naming]
+```
+
+| Section | Purpose |
+|---------|---------|
+| `structure` | Architecture patterns (feature-based, MVC, layered) and directory placement rules (e.g. *Helper in helpers/) |
+| `analysis` | Glob `include` and `ignore` for file discovery |
+| `scoring` | Severity weights, compliance threshold, trend window |
+| `convention` | Confidence threshold and dimension → severity map |
+| `drift` | Confidence threshold and naming pattern regexes |
+| `docs` | Tracked doc names, export targets, dev scripts |
+| `naming` | Stem stopwords for file-responsibility extraction |
+
+### Custom Rules
+
+Add regex-based rules via `.codeplug/rules.json`. Schema: `id`, `pattern`, `scope` (filename | path | content), `message`, `severity` (optional).
+
+```json
+[{ "id": "no-index-export", "pattern": "export \\* from", "scope": "content", "message": "Prefer named exports", "severity": "low" }]
+```
+
+### Data Files
+
+| File | Purpose |
+|------|---------|
+| `.codeplug/config.json` | Project config (LLM, models, analysis, etc.) |
+| `.codeplug/conventions.json` | Stored conventions from `convention init` |
+| `.codeplug/rules.json` | Custom regex rules for audit |
+| `.codeplug/scores.json` | Compliance score history (sql.js) |
+| `.codeplug/violations.json` | Recent violation records |
+
 ---
 
 ## Supported LLM Providers
@@ -222,14 +340,158 @@ All providers work through a single unified client via the OpenAI SDK.
 | | Default | Lite |
 |---|---------|------|
 | Target machine | 8GB+ RAM | 4GB+ RAM |
-| Disk usage | ~1.1GB | ~420MB |
+| Disk usage | ~1.2GB | ~450MB |
 | Classification | CodeBERT-base (125M params) | CodeBERTa-small (84M params) |
 | Summarization | BART-large-CNN (406M params) | DistilBART (230M params) |
 | NER | BERT-base-NER (110M params) | DistilBERT-NER (66M params) |
+| Zero-shot | DistilBERT-MNLI (68MB) | DistilBERT-MNLI (68MB) |
+| Sentence similarity | all-MiniLM-L6-v2 (23MB) | all-MiniLM-L6-v2 (23MB) |
 | When to use | Production quality, CI pipelines | Local development on constrained hardware |
 
+**Model usage (all 6 roles used):**
+
+| Role | Default | Lite | Used By |
+|------|---------|------|---------|
+| classifier | CodeBERT-base | CodeBERTa-small | ConventionMlResolver (convention init) |
+| zeroShot | DistilBERT-MNLI | same | SemanticCoherenceService (opt-in) |
+| sentenceSimilarity | all-MiniLM-L6-v2 | same | SemanticCoherenceService (fallback) |
+| summarizer | BART-large-CNN | DistilBART | DocGenerator (docs generate) |
+| extractor | DistilBERT-SQuAD | same | DocGenerator |
+| ner | BERT-base-NER | DistilBERT-NER | DocGenerator |
+
+Convention detection: AST visitors + CodeBERT (ConventionMlResolver) + zero-shot/sentenceSimilarity when semantic coherence enabled. Doc generation: summarizer, extractor, ner via PipelineOrchestrator (default); falls back to template-only on model load failure.
+
 Models are downloaded on first use and cached in `~/.codeplug/models/`.
 
+### Tradeoffs
+
+- **Default vs Lite**: Quality vs resource usage (8GB vs 4GB RAM; ~1.2GB vs ~450MB disk).
+- **Semantic coherence**: Enable for stricter "export fits context" checks; adds ~68MB model load and inference time per audit.
+- **LLM for docs**: Optional; template-only fallback when LLM unavailable.
+- **Performance targets**: CLI startup <1s; init ~500 files <15s; drift <3s; audit <30s; docs (all 5) <2min.
+
+### Hugging Face Transformers
+
+Convention detection, drift, and compliance use **on-device ML only** via `@huggingface/transformers`. No API keys or network calls for convention features.
+
+**Why Transformers / Local-First ML**
+
+```mermaid
+flowchart LR
+    subgraph design [Design Rationale]
+        A[Privacy: no data leaves machine]
+        B[Zero cost for convention features]
+        C[Python-free Node.js inference]
+        D[Deterministic logic first ML fallback]
+    end
+```
+
+- **Privacy**: Convention detection, drift, compliance run entirely on-device — no API keys, no network calls.
+- **Cost**: Zero runtime cost; models cached in `~/.codeplug/models/`.
+- **Portability**: `@huggingface/transformers` runs in Node.js — no Python, no separate ML server.
+- **Explainability**: Rule-based detection first; ML used for ambiguous cases (e.g., semantic coherence) to keep outputs explainable.
+
+**Feature → Model usage:**
+
+```mermaid
+flowchart TB
+    subgraph convention [Convention Features]
+        Init[convention init]
+        Audit[convention audit]
+    end
+    subgraph conventionML [Convention ML]
+        CodeBERT[classifier: CodeBERT]
+        ZeroShot[zeroShot: DistilBERT-MNLI]
+        SentSim[sentenceSimilarity: all-MiniLM]
+    end
+    subgraph docsML [Docs ML]
+        BART[summarizer]
+        Extractor[extractor]
+        NER[ner]
+    end
+    Init --> CodeBERT
+    Init --> ZeroShot
+    Init --> SentSim
+    Audit --> conventionML
+    DocsGenerate[docs generate] --> BART
+    DocsGenerate --> Extractor
+    DocsGenerate --> NER
+```
+
+**Pipelines by feature:**
+
+| Feature | Pipeline | Use |
+|---------|----------|-----|
+| Convention discovery | Feature extraction (CodeBERT embedding via ConventionMlResolver) | Pattern similarity during init |
+| Convention (opt-in) | Zero-shot, sentence similarity (all-MiniLM) | Semantic coherence: "export fits file context" |
+| Doc generation | Summarization (BART), Q&A (DistilBERT-SQuAD), NER (BERT-NER) | Living documentation; template fallback on load failure |
+
+**LLM scope:** The LLM is **optional** and used only for prose generation in docs. Convention detection, drift, and compliance do not use an LLM.
+
+**Cost:** Zero runtime cost for convention features; models are cached locally.
+
+---
+
+## Project Structure
+
+```
+src/
+├── cli/
+│   └── commands/           # Command handlers (convention, docs, export, config)
+├── config/                 # ConfigManager, Zod schemas, types, provider presets
+├── core/
+│   ├── analyzer/           # AST analysis: 6 visitors (init), 7 for audit (adds StructureVisitor), PatternAggregator
+│   ├── classifier/         # Drift classification + confidence gating
+│   ├── scorer/             # Compliance scoring, violation detection, auto-fix, trends
+│   ├── generator/          # Doc generation, ML pipelines, LLM client, staleness tracking
+│   ├── exporter/           # Export engine + 5 formatters (Claude, Cursor, Copilot, JSON, CI)
+│   └── git/                # Git integration + pre-commit hook management
+├── models/                 # ML model manager + tier-aware registry
+├── storage/                # ConventionStore, ScoreStore (sql.js), ViolationStore, CustomRuleStore
+├── templates/              # Export templates (Claude, Cursor, Copilot)
+└── tests/                  # Unit tests, integration tests, fixture repos
+```
+
+### Directory Details
+
+| Directory | Purpose |
+|-----------|---------|
+| `cli/commands/` | Command handlers for the CLI interface |
+| `config/` | Configuration management with Zod validation |
+| `core/analyzer/` | AST-based code analysis with pattern aggregation |
+| `core/classifier/` | Drift detection and severity classification |
+| `core/scorer/` | Compliance scoring engine with trend analysis |
+| `core/generator/` | Doc generation; PipelineOrchestrator (summarizer, extractor, ner) + LLM; template fallback on failure |
+| `core/exporter/` | Multi-format export for AI coding agents |
+| `core/git/` | Git integration, diff analysis, PreCommitHook (CLI not yet exposed) |
+| `models/` | ML model lifecycle management |
+| `storage/` | ConventionStore, ScoreStore (sql.js), ViolationStore, CustomRuleStore (rules.json) |
+
+---
+
+## Conventions
+
+CodePlug follows these conventions throughout the codebase:
+
+### Naming Conventions
+
+- **Utility files** — Use camelCase (e.g., `formatDate.ts`, `parseConfig.ts`)
+- **Class/service files** — Use PascalCase (e.g., `ConfigManager.ts`, `ConventionStore.ts`)
+- **React components** — Use PascalCase file names (e.g., `Button.tsx`, `UserProfile.tsx`)
+- **Hooks** — Use "use" prefix with camelCase (e.g., `useAuth.ts`, `useTheme.ts`)
+
+### Testing Conventions
+
+- **Separate tests/** directory — Integration and e2e tests live outside `src/`
+- **Test file naming** — Use `.test.ts` or `.spec.ts` suffix
+- **Co-located tests** — Use `__tests__/` directories for unit tests near source files
+
+### Project Structure Conventions
+
+- **Source root** — All source code resides in `src/`
+- **Entry points** — CLI entry at `src/cli/index.ts`
+- **Core modules** — Domain logic in `src/core/` subdirectories by responsibility
+
 ---
 
 ## Development
@@ -265,27 +527,6 @@ npm run dev
 
 ---
 
-## Project Structure
-
-```
-src/
-  cli/commands/        Command handlers (convention, docs, export, config)
-  config/              ConfigManager, Zod schemas, types, provider presets
-  core/
-    analyzer/          AST analysis engine + 6 visitors + PatternAggregator
-    classifier/        Drift classification + confidence gating
-    scorer/            Compliance scoring, violation detection, auto-fix, trends
-    generator/         Doc generation, ML pipelines, LLM client, staleness tracking
-    exporter/          Export engine + 5 formatters (Claude, Cursor, Copilot, JSON, CI)
-    git/               Git integration + pre-commit hook management
-  models/              ML model manager + tier-aware registry
-  storage/             ConventionStore, ScoreStore (sql.js), ViolationStore
-templates/             Export templates (Claude, Cursor, Copilot)
-tests/                 Unit tests, integration tests, fixture repos
-```
-
----
-
 ## License
 
-MIT
+MIT

package/dist/cli/commands/convention.d.ts

@@ -1,4 +1,4 @@
-import type { ConventionInitOptions, ConventionAuditOptions, ConventionScoreOptions, ConventionFixOptions } from '../../config/types.js';
+import type { ConventionAuditOptions, ConventionFixOptions, ConventionInitOptions, ConventionScoreOptions } from "../../config/types.js";
 export declare function handleConventionInit(options: ConventionInitOptions): Promise<void>;
 export declare function handleConventionAudit(options: ConventionAuditOptions): Promise<void>;
 export declare function handleConventionDrift(): Promise<void>;

package/dist/cli/commands/convention.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convention.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/convention.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEzI,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BxF;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB1F;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAc3D;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYtF;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxE"}
+{"version":3,"file":"convention.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/convention.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,uBAAuB,CAAC;AAE/B,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAuFf;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAsDf;AAID,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CA6H3D;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxE"}

package/dist/cli/commands/convention.js

@@ -1,62 +1,205 @@
 export async function handleConventionInit(options) {
-    const chalk = (await import('chalk')).default;
-    const ora = (await import('ora')).default;
-    const { AstAnalyzer } = await import('../../core/analyzer/AstAnalyzer.js');
-    const { ConventionDetector } = await import('../../core/analyzer/ConventionDetector.js');
-    const { ConventionStore } = await import('../../storage/ConventionStore.js');
+    const chalk = (await import("chalk")).default;
+    const ora = (await import("ora")).default;
+    const { ConfigManager } = await import("../../config/ConfigManager.js");
+    const { AstAnalyzer } = await import("../../core/analyzer/AstAnalyzer.js");
+    const { ConventionDetector } = await import("../../core/analyzer/ConventionDetector.js");
+    const { ConventionStore } = await import("../../storage/ConventionStore.js");
     const store = new ConventionStore(process.cwd());
-    if (!options.force && await store.exists()) {
-        console.log(chalk.yellow('Conventions already exist. Use --force to re-detect.'));
+    if (!options.force && (await store.exists())) {
+        console.log(chalk.yellow("Conventions already exist. Use -f/--force to re-detect (e.g. npm run convention:init:force)."));
         return;
     }
-    const spinner = ora('Analysing codebase...').start();
-    const analyzer = new AstAnalyzer(process.cwd());
+    const config = new ConfigManager(process.cwd());
+    await config.load();
+    const spinner = ora("Analysing codebase...").start();
+    const analyzer = new AstAnalyzer(process.cwd(), {
+        analysisConfig: config.getAnalysisConfig(),
+        structureConfig: config.getStructureConfig(),
+        namingConfig: config.getNamingConfig(),
+        conventionConfig: config.getConventionConfig(),
+    });
     const analysisResult = await analyzer.analyze();
     spinner.succeed(`Analysed ${analysisResult.fileCount} files in ${analysisResult.durationMs}ms`);
-    const detector = new ConventionDetector();
+    if (analysisResult.filePaths && analysisResult.filePaths.length >= 3) {
+        const spinner2 = ora("Running semantic coherence (HF)...").start();
+        try {
+            const { detectSemanticPattern } = await import("../../core/analyzer/SemanticCoherencePhase.js");
+            const conventionConfig = config.getConventionConfig();
+            const semanticPattern = await detectSemanticPattern(process.cwd(), analysisResult.filePaths, config.getModelTier(), {
+                useSentenceSimilarityFallback: conventionConfig.useSentenceSimilarityFallback,
+            });
+            if (semanticPattern) {
+                analysisResult.patterns.push(semanticPattern);
+                spinner2.succeed(`Semantic coherence: detected (${semanticPattern.confidence}% confidence)`);
+            }
+            else {
+                spinner2.warn("Semantic coherence: skipped (low confidence or few exports)");
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            spinner2.fail(`Semantic coherence: model load failed (${msg})`);
+        }
+    }
+    const detector = new ConventionDetector({
+        conventionConfig: config.getConventionConfig(),
+        structureConfig: config.getStructureConfig(),
+        modelTier: config.getModelTier(),
+    });
     const candidates = await detector.detect(analysisResult);
-    const { confirmConventions } = await import('./conventionPrompts.js');
+    const { confirmConventions } = await import("./conventionPrompts.js");
     const confirmed = await confirmConventions(candidates);
     await store.save(confirmed);
     console.log(chalk.green(`\n✅ Conventions saved to .codeplug/conventions.json`));
     console.log(chalk.dim(`   Run 'codeplug convention audit' to check current compliance.`));
 }
 export async function handleConventionAudit(options) {
-    const chalk = (await import('chalk')).default;
-    const { ConventionStore } = await import('../../storage/ConventionStore.js');
-    const { ViolationDetector } = await import('../../core/scorer/ViolationDetector.js');
-    const { ComplianceScorer } = await import('../../core/scorer/ComplianceScorer.js');
+    const chalk = (await import("chalk")).default;
+    const ora = (await import("ora")).default;
+    const { ConfigManager } = await import("../../config/ConfigManager.js");
+    const { ConventionStore } = await import("../../storage/ConventionStore.js");
+    const { ViolationDetector } = await import("../../core/scorer/ViolationDetector.js");
+    const { ComplianceScorer } = await import("../../core/scorer/ComplianceScorer.js");
     const store = new ConventionStore(process.cwd());
-    if (!await store.exists()) {
+    if (!(await store.exists())) {
         console.log(chalk.yellow('No conventions found. Run "codeplug convention init" first.'));
         return;
     }
     const conventions = await store.load();
-    const detector = new ViolationDetector(process.cwd());
+    const config = new ConfigManager(process.cwd());
+    await config.load();
+    const oraSpinner = ora("Auditing conventions...").start();
+    const detector = new ViolationDetector(process.cwd(), {
+        analysisConfig: config.getAnalysisConfig(),
+        structureConfig: config.getStructureConfig(),
+        namingConfig: config.getNamingConfig(),
+        modelTier: config.getModelTier(),
+        conventionConfig: config.getConventionConfig(),
+        spinner: {
+            text: (msg) => {
+                oraSpinner.text = msg;
+            },
+            succeed: (msg) => oraSpinner.succeed(msg),
+        },
+    });
     const violations = await detector.detect(conventions, options);
-    const scorer = new ComplianceScorer();
-    const score = scorer.calculate(violations);
+    oraSpinner.succeed(`Audit complete (${violations.length} violation${violations.length === 1 ? "" : "s"})`);
+    const scorer = new ComplianceScorer({
+        scoringConfig: config.getScoringConfig(),
+    });
+    const score = await scorer.scoreAndPersist(violations, process.cwd());
     scorer.printReport(score, violations);
     if (options.ci && score.total < (score.threshold ?? 70)) {
         process.exit(1);
     }
 }
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
 export async function handleConventionDrift() {
-    const chalk = (await import('chalk')).default;
-    const { ConventionStore } = await import('../../storage/ConventionStore.js');
-    const { DriftClassifier } = await import('../../core/classifier/DriftClassifier.js');
+    const chalk = (await import("chalk")).default;
+    const ora = (await import("ora")).default;
+    const { ConfigManager } = await import("../../config/ConfigManager.js");
+    const { ConventionStore } = await import("../../storage/ConventionStore.js");
+    const { ViolationDetector } = await import("../../core/scorer/ViolationDetector.js");
+    const { GitIntegration } = await import("../../core/git/GitIntegration.js");
     const store = new ConventionStore(process.cwd());
-    if (!await store.exists()) {
+    if (!(await store.exists())) {
         console.log(chalk.yellow('No conventions found. Run "codeplug convention init" first.'));
         return;
     }
+    const git = new GitIntegration(process.cwd());
+    if (!(await git.isGitRepo())) {
+        console.log(chalk.red("Not inside a git repository."));
+        return;
+    }
+    const config = new ConfigManager(process.cwd());
+    await config.load();
     const conventions = await store.load();
-    const classifier = new DriftClassifier();
-    await classifier.checkRecentCommits(conventions);
+    let commitDiffs;
+    try {
+        commitDiffs = await git.getRecentCommitDiffs(5);
+    }
+    catch {
+        console.log(chalk.red("Failed to read git history."));
+        return;
+    }
+    if (commitDiffs.length === 0) {
+        console.log(chalk.dim("No recent commits found."));
+        return;
+    }
+    const changedPaths = new Set();
+    const fileToCommit = new Map();
+    for (const cd of commitDiffs) {
+        for (const f of cd.files) {
+            if (!f.binary && CODE_EXTENSIONS.test(f.file)) {
+                changedPaths.add(f.file);
+                if (!fileToCommit.has(f.file)) {
+                    fileToCommit.set(f.file, cd.commit.hash.slice(0, 7));
+                }
+            }
+        }
+    }
+    const filePaths = Array.from(changedPaths);
+    if (filePaths.length === 0) {
+        console.log(chalk.dim("No code files changed in recent commits."));
+        return;
+    }
+    const spinner = ora("Auditing changed files for drift...").start();
+    const detector = new ViolationDetector(process.cwd(), {
+        analysisConfig: config.getAnalysisConfig(),
+        structureConfig: config.getStructureConfig(),
+        namingConfig: config.getNamingConfig(),
+        modelTier: config.getModelTier(),
+        conventionConfig: config.getConventionConfig(),
+        spinner: {
+            text: (msg) => {
+                spinner.text = msg;
+            },
+            succeed: (msg) => spinner.succeed(msg),
+        },
+    });
+    const violations = await detector.detect(conventions, { filePaths });
+    const conventionById = new Map(conventions.map((c) => [c.id, c]));
+    const byCommit = new Map();
+    for (const v of violations) {
+        const commitHash = fileToCommit.get(v.file);
+        if (!commitHash)
+            continue;
+        if (!byCommit.has(commitHash))
+            byCommit.set(commitHash, []);
+        const convention = conventionById.get(v.conventionId);
+        const commitItems = byCommit.get(commitHash);
+        if (commitItems) {
+            commitItems.push({
+                file: v.file,
+                rule: convention?.rule ?? v.conventionId,
+                message: v.message,
+            });
+        }
+    }
+    spinner.stop();
+    console.log("");
+    console.log(chalk.bold(`Drift Report — ${commitDiffs.length} recent commits scanned`));
+    console.log(chalk.dim("─".repeat(50)));
+    if (violations.length === 0) {
+        console.log(chalk.green("No drift detected. All changes follow conventions."));
+        console.log("");
+        return;
+    }
+    const drifting = violations.length;
+    console.log(chalk.red.bold(`\n  Drifting (${drifting}):`));
+    for (const [hash, items] of byCommit) {
+        for (const { file, rule, message } of items) {
+            console.log(chalk.red(`    [${hash}] ${file}`));
+            console.log(chalk.dim(`      Rule: ${rule}`));
+            console.log(chalk.dim(`      ${message}`));
+        }
+    }
+    console.log("");
 }
 export async function handleConventionScore(options) {
-    const chalk = (await import('chalk')).default;
-    const { ScoreStore } = await import('../../storage/ScoreStore.js');
+    const chalk = (await import("chalk")).default;
+    const { ScoreStore } = await import("../../storage/ScoreStore.js");
     const scoreStore = new ScoreStore(process.cwd());
     if (options.trend) {
         await scoreStore.printTrend();
@@ -71,8 +214,8 @@ export async function handleConventionScore(options) {
     }
 }
 export async function handleConventionFix(options) {
-    const chalk = (await import('chalk')).default;
-    const { AutoFixer } = await import('../../core/scorer/AutoFixer.js');
+    const chalk = (await import("chalk")).default;
+    const { AutoFixer } = await import("../../core/scorer/AutoFixer.js");
     const fixer = new AutoFixer(process.cwd());
     if (options.id) {
         await fixer.fixById(options.id);
@@ -85,8 +228,8 @@ export async function handleConventionFix(options) {
     }
 }
 export async function handleConventionShow(commit) {
-    const chalk = (await import('chalk')).default;
+    const chalk = (await import("chalk")).default;
     console.log(chalk.dim(`Showing findings for commit ${commit}...`));
-    console.log(chalk.yellow('Not yet implemented. Coming in Phase 2.'));
+    console.log(chalk.yellow("Not yet implemented. Coming in Phase 2."));
 }
 //# sourceMappingURL=convention.js.map