@dinyangetoh/codeplug-cli 0.1.3 → 0.1.5

package/README.md

@@ -1,58 +1,65 @@
 # CodePlug
 
-**The source of truth for codebase understanding and governance.**
+> The source of truth for codebase understanding & 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.
+## Overview
+
+This document is the primary technical reference for **CodePlug** (`@dinyangetoh/codeplug-cli`), a professional-grade, local-first CLI tool designed to detect, enforce, and document coding conventions across TypeScript and JavaScript codebases. It covers installation, configuration, usage, and the underlying architecture to help developers integrate CodePlug into their workflows. CodePlug combines AST analysis with on-device ML inference to provide automated convention governance, living documentation generation, and structured AI agent context export — ensuring both human developers and AI assistants adhere to the same project standards.
 
 ---
 
-## Features
+## Key Descriptions
 
-- **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.
+CodePlug acts as the **source of truth for codebase understanding**. It uses AST visitors and on-device ML models (via `@huggingface/transformers`, with no Python dependency) to identify patterns across naming, structure, components, and error handling. It generates "living documentation" and structured rule files for AI agents (Claude, Cursor, Copilot), and provides a compliance scoring engine to prevent architectural drift over time.
 
 ---
 
-## Quick Start
+## Key Features
 
-```bash
-# Install globally
-npm install -g @dinyangetoh/codeplug-cli
+### Convention Detection & Governance
+- **Multi-Dimensional AST Analysis:** Six to seven specialized visitors identify naming patterns, component styles, test organization, error handling, and import conventions.
+- **Drift & Compliance Scoring:** Classifies git diffs against stored conventions, scores compliance with severity-weighted metrics, and tracks trends via an internal `sql.js` time-series database.
+- **Auto-Fix:** Supports automated renaming and provides guided remediation for complex violations.
 
-# Navigate to your project
-cd your-project
+### Documentation & AI Integration
+- **Living Documentation:** Automatically maintains `ARCHITECTURE.md`, `CONVENTIONS.md`, and `ONBOARDING.md` using ML summarization pipelines (BART, BERT).
+- **AI Agent Export:** Generates context files including `CLAUDE.md`, `.cursor/rules`, and `.github/copilot-instructions.md`.
+- **CI/CD Ready:** Exports SARIF-format reports for integration with GitHub Actions and other CI pipelines.
 
-# Detect and confirm conventions
-codeplug convention init
+### Feature Matrix
 
-# Check compliance
-codeplug convention audit
-```
+| Category | Feature | Command | Notes |
+|---|---|---|---|
+| **CLI** | Interactive Wizard | `codeplug start` | Single entry point for all menus |
+| **Audit** | Compliance Score | `codeplug convention score` | Severity-weighted, time-series tracking |
+| **Docs** | ML Generation | `codeplug docs generate` | 5 core docs; optional LLM enhancement |
+| **Export** | AI Context | `codeplug export --all` | Supports Claude, Cursor, Copilot, JSON |
+| **Config** | Model Tiers | `codeplug config set` | Choose between `default` or `lite` models |
 
 ---
 
 ## Prerequisites
 
-- **Node.js 20+** (required)
-- **Git** (required for drift detection and history analysis)
-- **Ollama** (optional, for LLM-enhanced documentation -- any OpenAI-compatible provider works)
+| Requirement | Version | Notes |
+|---|---|---|
+| **Node.js** | `>=20.0.0` | Required for native fetch and modern ESM support |
+| **Git** | Any modern version | Required for drift detection and history analysis |
+| **Ollama** | Optional | For local LLM-enhanced documentation; any OpenAI-compatible provider is also supported |
 
 ---
 
 ## Installation
 
-### Global install
+### Global Install
 
 ```bash
 npm install -g @dinyangetoh/codeplug-cli
 ```
 
-### Local development
+### Local Development
 
 ```bash
-git clone <repo-url>
+git clone <repository-url>
 cd codeplug
 npm install
 npm run build
@@ -61,231 +68,186 @@ node dist/cli/index.js --help
 
 ---
 
-## Usage
-
-### Convention Detection
+## Quick Start
 
 ```bash
-# Detect and interactively confirm conventions
+# Initialize and detect conventions in your project
+cd your-project
 codeplug convention init
 
-# Re-run detection, overwrite existing conventions
-codeplug convention init --force
-```
-
-### Compliance Audit
-
-```bash
-# Full compliance report
+# Run a compliance audit
 codeplug convention audit
 
-# Audit only changes from the last 7 days
-codeplug convention audit --since 7d
-
-# CI mode -- exits non-zero if score drops below threshold
-codeplug convention audit --ci
+# Launch the interactive wizard
+codeplug start
 ```
 
-### Drift Detection
-
-```bash
-# Check recent commits for convention drift
-codeplug convention drift
-```
-
-### Compliance Score
-
-```bash
-# Show current score
-codeplug convention score
+---
 
-# Show score history and trend chart
-codeplug convention score --trend
-```
+## Usage
 
-### Auto-Fix
+### Interactive Wizard
 
-```bash
-# Apply all safe auto-fixes
-codeplug convention fix --auto
+The `codeplug start` command provides a guided interface organized into four areas:
 
-# Fix a specific finding by ID
-codeplug convention fix --id naming-pascal-components
-```
+| Area | Description |
+|---|---|
+| **Config** | Manage LLM providers, API keys, and model tiers |
+| **Convention** | Initialize detection, run audits, and apply auto-fixes |
+| **Docs** | Generate and update stale documentation |
+| **Export** | Refresh AI agent rule files |
 
-### Documentation Generation
+### Common Commands
 
 ```bash
-# Generate all 5 documents
-codeplug docs generate
+# Audit changes from the last 7 days
+codeplug convention audit --since 7d
 
-# Generate a specific document
-codeplug docs generate --doc ARCHITECTURE
+# CI mode — exits non-zero if score is below threshold
+codeplug convention audit --ci
 
-# Tune for audience and style
+# Generate docs for a junior audience in concise style
 codeplug docs generate --audience junior --style concise
 
-# Check which docs are stale
-codeplug docs status
-
-# Regenerate only stale sections
-codeplug docs update
-```
-
-### Export for AI Agents
-
-```bash
-# Export for a specific target
-codeplug export --target claude
+# Export rules for Cursor
 codeplug export --target cursor
-codeplug export --target copilot
 
-# Export all targets at once
+# Export all AI agent context files
 codeplug export --all
-
-# Check if exports are up to date
-codeplug export --check
-```
-
-### Configuration
-
-```bash
-# View all settings
-codeplug config list
-
-# Get a specific value
-codeplug config get llm.provider
-
-# Set values
-codeplug config set llm.provider openai
-codeplug config set llm.model gpt-4o
-codeplug config set llm.apiKey sk-...
 ```
 
 ---
 
 ## Configuration
 
-CodePlug stores project-level configuration in `.codeplug/config.json`. The `config` command manages this file.
-
-### LLM Provider
+CodePlug stores project-level settings in `.codeplug/config.json`.
 
-The default provider is Ollama (local). Setting a provider auto-fills its base URL and default model:
+### LLM Providers
 
-```bash
-codeplug config set llm.provider ollama    # local, no API key needed
-codeplug config set llm.provider openai    # sets baseUrl + model automatically
-codeplug config set llm.provider anthropic
-```
+Convention detection runs entirely on-device. Documentation prose generation can optionally be enhanced via a local or cloud LLM provider:
 
-You can also set individual fields for custom endpoints:
+- **Local:** Ollama (default)
+- **Cloud:** OpenAI, Anthropic, Gemini, OpenRouter, Groq, DeepSeek, Grok
 
 ```bash
-codeplug config set llm.baseUrl https://my-proxy.example.com/v1
-codeplug config set llm.model my-custom-model
-codeplug config set llm.apiKey my-key
+codeplug config set llm.provider openai
+codeplug config set llm.apiKey sk-...
 ```
 
-### Model Tier
+### Model Tiers
 
-```bash
-# Full-size models (default) -- best quality, ~1.1GB disk, 8GB+ RAM recommended
-codeplug config set models.tier default
+| Tier | RAM | Disk | Use Case |
+|---|---|---|---|
+| **Default** | 8 GB+ | ~1.2 GB | Production quality, CI pipelines |
+| **Lite** | 4 GB+ | ~450 MB | Constrained local hardware |
 
-# Lightweight models -- reduced quality, ~420MB disk, 4GB RAM minimum
-codeplug config set models.tier lite
+```bash
+codeplug config set model.tier lite
 ```
 
-Switching to `lite` prints a warning about potential quality degradation.
-
----
-
-## Supported LLM Providers
+### Custom Rules
 
-All providers work through a single unified client via the OpenAI SDK.
+Define regex-based rules in `.codeplug/rules.json` to extend or override detected conventions:
 
-| Provider | Setup |
-|----------|-------|
-| Ollama | `codeplug config set llm.provider ollama` (default, no API key) |
-| OpenAI | `codeplug config set llm.provider openai` then set `llm.apiKey` |
-| Anthropic | `codeplug config set llm.provider anthropic` then set `llm.apiKey` |
-| Gemini | `codeplug config set llm.provider gemini` then set `llm.apiKey` |
-| OpenRouter | `codeplug config set llm.provider openrouter` then set `llm.apiKey` |
-| Groq | `codeplug config set llm.provider groq` then set `llm.apiKey` |
-| DeepSeek | `codeplug config set llm.provider deepseek` then set `llm.apiKey` |
-| Grok | `codeplug config set llm.provider grok` then set `llm.apiKey` |
+```json
+[{
+  "id": "no-index-export",
+  "pattern": "export \\* from",
+  "scope": "content",
+  "message": "Prefer named exports",
+  "severity": "low"
+}]
+```
 
 ---
 
-## Model Tiers
-
-| | Default | Lite |
-|---|---------|------|
-| Target machine | 8GB+ RAM | 4GB+ RAM |
-| Disk usage | ~1.1GB | ~420MB |
-| 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) |
-| When to use | Production quality, CI pipelines | Local development on constrained hardware |
-
-Models are downloaded on first use and cached in `~/.codeplug/models/`.
+## Project Structure & Architecture
+
+### Folder Structure
+
+```text
+src/                          # 66 source files
+├── cli/
+│   └── commands/             # Command handlers (convention, docs, export)
+├── config/                   # Zod schemas and provider presets
+├── core/
+│   ├── analyzer/             # AST analysis — 6–7 specialized visitors
+│   ├── classifier/           # Drift classification & confidence gating
+│   ├── scorer/               # Compliance engine & violation detection
+│   ├── generator/            # ML pipelines (BART, BERT) & LLM client
+│   ├── exporter/             # Formatters (Claude, Cursor, SARIF)
+│   └── git/                  # Diff analysis & hook management
+├── models/                   # Tier-aware ML model registry
+├── storage/                  # sql.js (scores) and JSON stores
+└── templates/                # Export templates for AI agents
+
+tests/                        # 18 test files
+├── unit/
+│   ├── analyzer/
+│   ├── config/
+│   ├── exporter/
+│   ├── generator/
+│   ├── models/
+│   └── scorer/
+└── fixtures/
+    └── sample-react-app/
+```
+
+### Technical Stack
+
+| Layer | Technology |
+|---|---|
+| **ML Inference** | `@huggingface/transformers` — Python-free, Node.js native |
+| **Summarization** | BART (documentation prose) |
+| **Embeddings** | BERT (pattern classification) |
+| **Database** | `sql.js` (compliance time-series) |
+| **Schema Validation** | Zod |
+| **Test Runner** | Vitest |
 
 ---
 
-## Development
+## Conventions
 
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
+These are the conventions CodePlug enforces and itself follows internally.
 
-# Type check without emitting
-npm run typecheck
+### Naming
 
-# Run tests
-npm test
+| Target | Convention | Example |
+|---|---|---|
+| Class / service files | `PascalCase` | `ConfigManager.ts` |
+| Utility files | `camelCase` | `formatDate.ts` |
+| Class names | `PascalCase` | `class ConventionScorer` |
+| Interface names | `PascalCase` | `interface RuleConfig` |
+| Type aliases | `PascalCase` | `type SeverityLevel` |
+| Factory functions | `camelCase` | `createAnalyzer()` |
 
-# Run tests in watch mode
-npm run test:watch
+> **Note:** Kebab-case filenames are not used anywhere in this project.
 
-# Run with coverage
-npm run coverage
+### API & Async Patterns
 
-# Lint
-npm run lint
+- All I/O operations use `async/await`; callbacks and raw Promise chains are avoided.
 
-# Lint with auto-fix
-npm run lint:fix
+### Testing
 
-# Watch build during development
-npm run dev
-```
+- Integration tests live in the root `tests/` directory.
+- Unit tests are co-located in `__tests__/` subdirectories alongside source files.
+- Test files follow the `.test.{ext}` naming convention.
 
 ---
 
-## Project Structure
+## Development
 
-```
-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
+```bash
+npm run build        # Compile TypeScript
+npm run dev          # Watch mode for active development
+npm run test         # Run the full Vitest suite
+npm run coverage     # Generate test coverage report
+npm run lint         # Check code style
+npm run typecheck    # Verify TypeScript types
 ```
 
 ---
 
 ## 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"}