desloppify

Desloppify is organized into a layered architecture where each layer can only import from lower-numbered layers. This prevents circular dependencies and maintains a clear separation between foundational infrastructure and language-specific logic.

• Layer 0: base/: Foundational infrastructure (path resolution, config, enums, output).
• Layer 1: engine/detectors/: Generic analysis algorithms with zero language imports.
• Layer 2: languages/_framework/: Shared contracts and helpers for normalizing results into tiered findings.
• Layer 3: languages/<name>/: Language-specific configuration, phases, extractors, detectors, and fixers.
• Layer 4: app/: CLI commands serving as thin entry points.

Desloppify computes a health score from 0 to 100. A score of 100 indicates no known issues. The score is a blend of two independent pools:

• Mechanical (25% weight): Derived from automated detectors (e.g., code smells, duplication, security).
• Subjective (75% weight): Derived from AI code review assessments (e.g., architecture, elegance, contracts).

Note: If no subjective reviews have been run, the score is 100% mechanical. Once subjective dimensions are present, the 25/75 split is applied. Within each pool, dimensions are averaged using their own configured weights.

Desloppify uses a two-tier plugin system for language support:

1. Generic Plugins: Lightweight, single-file plugins (~20-40 lines) that wrap external linters (e.g., rubocop, eslint, shellcheck). When tree-sitter-language-pack is installed, they gain AST-powered analysis (complexity, dependency graphs, unused imports, etc.).
2. Full Plugins: Comprehensive, multi-module packages with hand-written detectors, language-specific smell analysis, auto-fixers, and deep scoring. These are used for languages requiring deep idiomatic understanding (e.g., Python, TypeScript, Rust).

Common capabilities for all plugins:

• Security scanning
• LLM-powered subjective design review
• Boilerplate and duplicate detection
• Zone classification (test/vendor/config/generated)
• Automatic scoring integration

The desloppify queue operates through a single explicit cycle of phases. Understanding this sequence is essential for managing how work moves from detection to execution:

scan -> review -> workflow -> triage -> execute -> scan

Desloppify provides framework-aware code quality detection for Next.js projects. It uses a combination of fast heuristic scanners (regex/file-structure based) and a slower next lint integration to catch smells that generic detectors miss.

Key capabilities include detecting:

• App Router vs. Pages Router misuse and migration signals.
• Client/Server boundary violations (e.g., missing or misplaced "use client" or "use server" directives).
• Server-only imports (like next/headers or server-only) appearing in client modules.
• Environment variable leakage (using non-NEXT_PUBLIC_* variables in client modules).
• Misuse of Next.js APIs in the wrong router context (e.g., using getServerSideProps in the App Router).
• next lint integration for deep ESLint-based analysis.

Desloppify automatically detects Ruby projects if they contain any of the following files:

• Gemfile
• Rakefile
• .ruby-version
• Any *.gemspec file

To achieve the deepest and most accurate C/C++ analysis, Desloppify requires specific build metadata and external analyzers. A 'full' scan is achieved when the following four components are present:

1. compile_commands.json: The primary input for dependency and include resolution. It should be placed at the repository root passed to the scan command.
2. clang-tidy: Must be available on your PATH for security and CERT-style findings.
3. cppcheck: Must be available on your PATH to power the cppcheck_issue phase.
4. Python extras: The desloppify[full] package must be installed in your Python environment.

If any of these are missing, the scan will degrade gracefully (e.g., falling back to regex-based heuristics or local include scanning) rather than failing, but the results will be less complete.

The Python plugin requires Python 3.11+ and specific tools on your PATH for certain analysis phases.

• Unused phase (unused imports/variables): Requires ruff.
• Security phase: Requires bandit (optional).

Install the optional tools using pip:

pip install ruff bandit

To avoid MCP cold-start overhead during parallel runs, you can start a persistent OpenCode server and attach Desloppify to it using the DESLOPPIFY_OPENCODE_ATTACH environment variable. When this variable is set, batch subprocesses will attach to the running server via --attach <url> instead of spawning fresh instances.

opencode serve --port 4096 &
export DESLOPPIFY_OPENCODE_ATTACH=http://localhost:4096
desloppify review --run-batches --runner opencode --parallel --scan-after-import

If you need to control the review process manually, follow these two steps:

1. Prepare: Generate the necessary review files (query.json and .desloppify/review_packet_blind.json) using the --prepare flag.
2. Run batches: Execute the batch review process using the OpenCode runner.

The runner automatically handles batch splitting, prompt generation, parallel execution, retry/stall detection, result extraction, merging, and trusted import.

desloppify review --prepare
desloppify review --run-batches --runner opencode --parallel --scan-after-import