CodePlug

The source of truth for codebase understanding & governance.

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 polyglot codebases. It covers installation, configuration, usage commands, and architecture to help developers integrate CodePlug into their workflows. CodePlug combines signal extraction with on-device ML inference to provide automated convention governance, semantic drift detection, living documentation generation, and structured AI agent context export.

Key Descriptions

CodePlug acts as the source of truth for codebase understanding. It uses signal extractors and on-device ML models (via @huggingface/transformers, with no Python dependency) to identify patterns across naming, structure, frameworks, components, and semantic role/layer behavior. 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.

Key Features

Convention Detection & Governance

• Multi-Dimensional AST Analysis: Six to seven specialized visitors identify naming patterns, component styles, test organization, error handling, and import conventions.
• Baseline Lifecycle: Supports observed → normalized → locked baseline flow to separate inferred behavior from enforced policy.
• Drift & Compliance Scoring: Classifies git diffs against stored conventions, scores compliance with severity-weighted metrics, and tracks trends over time.
• Semantic Drift (ML-first): Uses code embeddings and role centroids to flag role drift, layer leakage, and abstraction mismatch.
• Auto-Fix: Supports automated renaming and provides guided remediation for complex violations.

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.

Feature Matrix

| 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 | | Baseline | Normalize & Lock | codeplug convention baseline normalize/lock | Observed vs enforced convention lifecycle | | Explainability | Finding Evidence | codeplug convention explain <id> | Shows ML confidence and evidence payload | | 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 Validation | codeplug config validate-models | Verifies local HF model-role readiness |

Prerequisites

| 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

npm install -g @dinyangetoh/codeplug-cli

Local Development

git clone <repository-url>
cd codeplug
npm install
npm run build
node dist/cli/index.js --help

Quick Start

# Initialize and detect conventions in your project
cd your-project
codeplug convention init

# Run a compliance audit
codeplug convention audit

# Normalize and lock your baseline policy
codeplug convention baseline normalize
codeplug convention baseline lock

# Launch the interactive wizard
codeplug start

Usage

Interactive Wizard

The codeplug start command provides a guided interface organized into four areas:

| 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 |

Common Commands

# Audit changes from the last 7 days
codeplug convention audit --since 7d

# CI mode — exits non-zero if score is below threshold
codeplug convention audit --ci

# Explain a specific finding with model evidence
codeplug convention explain <violation-id>

# Validate all configured local model roles
codeplug config validate-models

# Generate docs for a junior audience in concise style
codeplug docs generate --audience junior --style concise

# Export rules for Cursor
codeplug export --target cursor

# Export all AI agent context files
codeplug export --all

Configuration

CodePlug stores project-level settings in .codeplug/config.json.

LLM Providers

Convention detection and drift analysis run on-device. Documentation prose generation can optionally be enhanced via a local or cloud LLM provider:

• Local: Ollama (default)
• Cloud: OpenAI, Anthropic, Gemini, OpenRouter, Groq, DeepSeek, Grok

codeplug config set llm.provider openai
codeplug config set llm.apiKey sk-...

Model Tiers

| Tier | RAM | Disk | Use Case | |---|---|---|---| | Default | 8 GB+ | ~1.2 GB | Production quality, CI pipelines | | Lite | 4 GB+ | ~450 MB | Constrained local hardware |

codeplug config set models.tier lite
codeplug config validate-models --tier lite

ML Model Roles (Hugging Face)

CodePlug uses role-based local models and keeps ML as the primary signal interpreter:

• classifier / frameworkClassifier: onnx-community/codebert-base-ONNX
• codeEmbedding: onnx-community/codebert-base-ONNX (fallback to Xenova/all-MiniLM-L6-v2)
• languageIdentifier: Xenova/distilbert-base-uncased-mnli
• zeroShot: Xenova/distilbert-base-uncased-mnli
• sentenceSimilarity: Xenova/all-MiniLM-L6-v2
• extractor: distilbert-base-cased-distilled-squad
• ner: dslim/bert-base-NER (lite: dslim/distilbert-NER)
• summarizer: facebook/bart-large-cnn (lite: sshleifer/distilbart-cnn-6-6)

Custom Rules

Define regex-based rules in .codeplug/rules.json to extend or override detected conventions:

[{
  "id": "no-index-export",
  "pattern": "export \\* from",
  "scope": "content",
  "message": "Prefer named exports",
  "severity": "low"
}]

Project Structure & Architecture

Folder Structure

./                           # 119 files total
src/                         # 88 source files
├── cli/
│   └── commands/            # Command handlers (7 files)
├── config/                  # Zod schemas and provider presets (4 files)
├── core/
│   ├── analyzer/            # AST analysis — specialized visitors (29 files)
│   ├── classifier/          # Drift classification & confidence gating (2 files)
│   ├── convention/          # Convention management (1 file)
│   ├── exporter/            # Formatters — Claude, Cursor, SARIF (9 files)
│   ├── generator/           # ML pipelines (BART, BERT) & LLM client (19 files)
│   ├── git/                 # Diff analysis & hook management (2 files)
│   └── scorer/              # Compliance engine & violation detection (5 files)
├── models/                  # Tier-aware ML model registry (2 files)
├── storage/                 # sql.js (scores) and JSON stores (7 files)
└── templates/               # Export templates for AI agents

tests/                       # 28 test files
├── integration/             # Integration tests (1 file)
├── unit/                    # Unit tests by module (22 files)
│   ├── analyzer/
│   ├── config/
│   ├── cli/
│   ├── exporter/
│   ├── models/
│   ├── scorer/
│   ├── generator/
│   └── storage/
└── fixtures/
    └── sample-react-app/    # Test fixtures (5 files)

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 |

Conventions

These are the conventions CodePlug enforces and itself follows internally.

Naming

| 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() |

Note: Kebab-case filenames are not used anywhere in this project.

API & Async Patterns

• All I/O operations use async/await; callbacks and raw Promise chains are avoided.
• All backend requests should go through a dedicated API layer, not raw fetch() calls scattered in component code.
• Use explicit builder.query<Result, Arg> and builder.mutation<Result, Arg> to prevent incorrect call signatures and unsafe data assumptions.

Architecture

• Keep dependencies one-way: presentation → business → data → models. Models must not depend on UI.
• Page components should remain thin orchestration shells that delegate feature logic to dedicated modules.

State Management

• Server data belongs in RTK Query, not regular slices.
• Prefer typed hooks (useAppDispatch, useAppSelector) over raw react-redux hooks for type safety.

Testing

• 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.

TypeScript

• Maintain strict TypeScript — eliminate explicit any annotations in source code.
• Components typically annotate return types with React.JSX.Element (or Promise variant for server components).

Development

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