desloppify 0.7.0__tar.gz

desloppify-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter O'Malley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

desloppify-0.7.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: desloppify
+Version: 0.7.0
+Summary: Multi-language codebase health scanner and technical debt tracker
+Author-email: Peter O'Malley <pete@banodoco.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/peteromallet/desloppify
+Project-URL: Repository, https://github.com/peteromallet/desloppify
+Project-URL: Issues, https://github.com/peteromallet/desloppify/issues
+Keywords: code-quality,technical-debt,linter,static-analysis,refactoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=9.0.0
+Provides-Extra: treesitter
+Requires-Dist: tree-sitter-language-pack>=0.3; extra == "treesitter"
+Dynamic: license-file
+
+# Desloppify - an agent harness to make your codebase 🤌
+
+Desloppify gives your AI coding agent the tools to identify, understand, and systematically improve codebase quality. It finds issues in two ways:
+
+1. **Subjective** — Examines the codebase from multiple subjective perspectives: abstraction quality, naming consistency, module boundaries, error handling patterns, convention drift, and language-specific questions. LLM evaluation scores these and tracks them as findings.
+
+2. **Mechanical** — Detects common mechanical issues like unused imports, dead code, overly long functions, duplication, and dependency cycles. Questionable issues are also flagged to the subjective agent for review.
+
+Your agent works through a prioritized list — auto-fixing what it can, presenting the rest for your judgment. State persists across scans so it chips away over multiple sessions, and the scoring is designed to resist gaming: attestation requirements, strict scoring that penalizes dismissed issues, and cross-checked subjective assessments.
+
+This produces a combined health score — our goal is that a score above 98 correlates with a codebase a seasoned engineer would call beautiful. That score generates a scorecard badge for your GitHub profile or README:
+
+<img src="assets/scorecard.png" width="100%">
+
+Currently supports 28 languages — full plugin depth for TypeScript, Python, C#, Dart, and GDScript; generic linter + tree-sitter support for Go, Rust, Ruby, Java, Kotlin, and 18 more.
+
+## For your agent's consideration...
+
+Paste this prompt into your agent:
+
+```
+Install or update desloppify, then scan this codebase for code quality issues (dead code,
+duplication, complexity, smells). It tracks findings persistently across sessions and reports
+a health score — state is cumulative, so each scan builds on previous progress.
+
+pip install --upgrade git+https://github.com/peteromallet/desloppify.git
+desloppify update-skill claude    # pick yours: claude, cursor, codex, copilot, windsurf, gemini
+desloppify scan --path .
+desloppify status
+desloppify next
+
+--path is the directory to scan (use "." for the whole project, or "src/" etc).
+Language is auto-detected. To override: desloppify --lang python scan --path .
+(note: --lang goes BEFORE the subcommand)
+
+Fix what it finds, then "desloppify resolve fixed <id> --note 'what changed' --attest 'I have actually [DESCRIBE THE CONCRETE CHANGE YOU MADE] and I am not gaming the score by resolving without fixing.'" and rescan.
+For false positives: "desloppify resolve wontfix <id> --note 'reason' --attest 'I have actually verified this is intentional/false-positive and I am not gaming the score by resolving without fixing.'" (note is required — don't skip work; attestation must include the keywords "I have actually" and "not gaming").
+Keep going until all issues are resolved.
+
+If subjective scores feel stale or inflated, force a clean baseline:
+desloppify scan --path . --reset-subjective
+
+Because state persists, desloppify works best when run regularly. Ask the user if they'd
+like to add a desloppify scan to their workflow — for example, adding "run desloppify scan
+before each git push" to their CLAUDE.md, AGENTS.md, or equivalent agent instructions file,
+so code health is checked at a natural interval.
+
+If you notice anything wrong or confusing about
+desloppify itself, tell me and ask if I want you to log an issue. If you need to understand
+how desloppify works or debug an issue: git clone https://github.com/peteromallet/desloppify.git /tmp/desloppify
+```
+
+## From Vibe Coding to Vibe Engineering
+
+Vibe coding gets things built fast. But the codebases it produces tend to rot in ways that are hard to see and harder to fix — not just the mechanical stuff like dead imports, but the structural kind. Abstractions that made sense at first stop making sense. Naming drifts. Error handling is done three different ways. The codebase works, but working in it gets worse over time.
+
+LLMs are actually good at spotting this now, if you ask them the right questions. That's the core bet here — that an agent with the right framework can hold a codebase to a real standard, the kind that used to require a senior engineer paying close attention over months.
+
+So we're trying to define what "good" looks like as a score that's actually worth optimizing. Not a lint score you game to 100 by suppressing warnings. Something where improving the number means the codebase genuinely got better. That's hard, and we're not done, but the anti-gaming stuff matters to us a lot — it's the difference between a useful signal and a vanity metric.
+
+The hope is that anyone can use this to build something a seasoned engineer would look at and respect. That's the bar we're aiming for.
+
+If you'd like to join a community of vibe engineers who want to build beautiful things, [come hang out](https://discord.gg/aZdzbZrHaY).
+
+<img src="docs/engineering.png" width="100%">
+
+---
+
+<details>
+<summary><strong>Stuff you probably won't need to know</strong></summary>
+
+#### Commands
+
+| Command | Description |
+|---------|-------------|
+| `scan [--reset-subjective]` | Run all detectors, update state (optional: reset subjective baseline to 0 first) |
+| `status` | Score + per-tier progress |
+| `show <pattern>` | Findings by file, directory, detector, or ID |
+| `next [--tier N] [--explain]` | Highest-priority open finding (--explain: with score context) |
+| `resolve <status> <patterns>` | Mark fixed / wontfix / false_positive / ignore |
+| `fix <fixer> [--dry-run]` | Auto-fix mechanical issues |
+| `review --prepare` | Generate subjective review packet (`query.json`) |
+| `review --import <file>` | Import subjective review findings |
+| `issues` | Review findings queue (list/show/update) |
+| `zone` | Show/set/clear zone classifications |
+| `config` | Show/set/unset project configuration |
+| `move <src> <dst>` | Move file/directory, update all imports |
+| `detect <name>` | Run a single detector raw |
+| `plan` | Prioritized markdown plan |
+| `tree` | Annotated codebase tree |
+| `viz` | Interactive HTML treemap |
+| `dev scaffold-lang` | Generate a standardized language plugin scaffold |
+
+#### Detectors
+
+**TypeScript/React**: logs, unused, exports, deprecated, large, complexity, gods, single_use, props, passthrough, concerns, deps, dupes, smells, coupling, patterns, naming, cycles, orphaned, react
+
+**Python**: unused, large, complexity, gods, props, smells, dupes, deps, cycles, orphaned, single_use, naming
+
+**C#/.NET**: deps, cycles, orphaned, dupes, large, complexity
+
+#### Tiers & scoring
+
+| Tier | Fix type | Examples |
+|------|----------|----------|
+| T1 | Auto-fixable | Unused imports, debug logs |
+| T2 | Quick manual | Unused vars, dead exports |
+| T3 | Needs judgment | Near-dupes, single_use abstractions |
+| T4 | Major refactor | God components, mixed concerns |
+
+Score is weighted (T4 = 4x T1). Strict score penalizes both open and wontfix.
+
+#### Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DESLOPPIFY_ROOT` | cwd | Project root |
+| `DESLOPPIFY_SRC` | `src` | Source directory (TS alias resolution) |
+| `--lang <name>` | auto-detected | Language selection (each has own state) |
+| `--exclude <pattern>` | none | Path patterns to skip (repeatable: `--exclude migrations --exclude tests`) |
+| `--no-badge` | false | Skip scorecard image generation |
+| `--badge-path <path>` | `scorecard.png` | Output path for scorecard image |
+| `DESLOPPIFY_NO_BADGE` | — | Set to `true` to disable badge via env |
+| `DESLOPPIFY_BADGE_PATH` | `scorecard.png` | Badge output path via env |
+
+Project config values (stored in `.desloppify/config.json`) are managed via:
+- `desloppify config show`
+- `desloppify config set target_strict_score 95` (default: `95`, valid range: `0-100`)
+- `desloppify config set badge_path scorecard.png` (or nested path like `assets/health.png`)
+
+#### Adding or augmenting a language
+
+Use the scaffold workflow documented in `desloppify/languages/README.md`:
+
+```bash
+desloppify dev scaffold-lang <name> --extension .ext --marker <root-marker>
+```
+
+Detect command keys are standardized to snake_case. CLI compatibility aliases
+like `single-use` and legacy `passthrough` are still accepted.
+Standard plugin shape: `__init__.py`, `commands.py`, `extractors.py`, `phases.py`,
+`move.py`, `review.py`, `test_coverage.py`, plus `detectors/`, `fixers/`, and `tests/`.
+Validated at registration. Zero shared code changes.
+
+#### Architecture
+
+```
+engine/detectors/            ← Generic algorithms (zero language knowledge)
+hook_registry.py             ← Detector-safe access to optional language hooks
+languages/_framework/runtime.py    ← LangRun (per-run mutable scan state)
+languages/_framework/base/         ← Shared framework contracts + phase helpers
+languages/_framework/generic.py    ← generic_lang() factory for tool-based plugins
+languages/_framework/treesitter/   ← Tree-sitter integration (optional)
+languages/<name>/            ← Language config + phases + extractors + detectors + fixers
+```
+
+Import direction: `languages/` → `engine/detectors/`. Never the reverse.
+`LangConfig` stays static; runtime state lives on `LangRun`.
+
+#### Command-Layer Boundaries
+
+Command entry modules are intentionally thin orchestrators:
+
+- `desloppify/app/commands/review/cmd.py` delegates to
+  `desloppify/app/commands/review/prepare.py`, `desloppify/app/commands/review/batches.py`, `desloppify/app/commands/review/import_cmd.py`, and `desloppify/app/commands/review/runtime.py`
+- `desloppify/app/commands/scan/scan_reporting_dimensions.py` delegates to
+  `desloppify/app/commands/scan/scan_reporting_presentation.py` and `desloppify/app/commands/scan/scan_reporting_subjective.py`
+- `desloppify/app/cli_support/parser.py` delegates subcommand construction to `desloppify/app/cli_support/parser_groups.py`
+
+Public CLI behavior should be preserved when refactoring these orchestrators.
+
+#### Allowed Dynamic Import Zones
+
+Dynamic/optional loading is allowed only in explicit extension points:
+
+- `desloppify/languages/__init__.py` for plugin discovery and registration
+- `desloppify/hook_registry.py` for detector-safe optional hooks
+
+Outside these zones, use static imports.
+
+#### State Ownership
+
+- `desloppify/state.py` and `desloppify/engine/_state/` own persisted schema and merge rules
+- `desloppify/languages/_framework/runtime.py` (`LangRun`) owns per-run mutable execution state
+- command modules may read/write state through state APIs, but should not define ad-hoc persisted fields
+
+</details>

desloppify-0.7.0/README.md

@@ -0,0 +1,187 @@
+# Desloppify - an agent harness to make your codebase 🤌
+
+Desloppify gives your AI coding agent the tools to identify, understand, and systematically improve codebase quality. It finds issues in two ways:
+
+1. **Subjective** — Examines the codebase from multiple subjective perspectives: abstraction quality, naming consistency, module boundaries, error handling patterns, convention drift, and language-specific questions. LLM evaluation scores these and tracks them as findings.
+
+2. **Mechanical** — Detects common mechanical issues like unused imports, dead code, overly long functions, duplication, and dependency cycles. Questionable issues are also flagged to the subjective agent for review.
+
+Your agent works through a prioritized list — auto-fixing what it can, presenting the rest for your judgment. State persists across scans so it chips away over multiple sessions, and the scoring is designed to resist gaming: attestation requirements, strict scoring that penalizes dismissed issues, and cross-checked subjective assessments.
+
+This produces a combined health score — our goal is that a score above 98 correlates with a codebase a seasoned engineer would call beautiful. That score generates a scorecard badge for your GitHub profile or README:
+
+<img src="assets/scorecard.png" width="100%">
+
+Currently supports 28 languages — full plugin depth for TypeScript, Python, C#, Dart, and GDScript; generic linter + tree-sitter support for Go, Rust, Ruby, Java, Kotlin, and 18 more.
+
+## For your agent's consideration...
+
+Paste this prompt into your agent:
+
+```
+Install or update desloppify, then scan this codebase for code quality issues (dead code,
+duplication, complexity, smells). It tracks findings persistently across sessions and reports
+a health score — state is cumulative, so each scan builds on previous progress.
+
+pip install --upgrade git+https://github.com/peteromallet/desloppify.git
+desloppify update-skill claude    # pick yours: claude, cursor, codex, copilot, windsurf, gemini
+desloppify scan --path .
+desloppify status
+desloppify next
+
+--path is the directory to scan (use "." for the whole project, or "src/" etc).
+Language is auto-detected. To override: desloppify --lang python scan --path .
+(note: --lang goes BEFORE the subcommand)
+
+Fix what it finds, then "desloppify resolve fixed <id> --note 'what changed' --attest 'I have actually [DESCRIBE THE CONCRETE CHANGE YOU MADE] and I am not gaming the score by resolving without fixing.'" and rescan.
+For false positives: "desloppify resolve wontfix <id> --note 'reason' --attest 'I have actually verified this is intentional/false-positive and I am not gaming the score by resolving without fixing.'" (note is required — don't skip work; attestation must include the keywords "I have actually" and "not gaming").
+Keep going until all issues are resolved.
+
+If subjective scores feel stale or inflated, force a clean baseline:
+desloppify scan --path . --reset-subjective
+
+Because state persists, desloppify works best when run regularly. Ask the user if they'd
+like to add a desloppify scan to their workflow — for example, adding "run desloppify scan
+before each git push" to their CLAUDE.md, AGENTS.md, or equivalent agent instructions file,
+so code health is checked at a natural interval.
+
+If you notice anything wrong or confusing about
+desloppify itself, tell me and ask if I want you to log an issue. If you need to understand
+how desloppify works or debug an issue: git clone https://github.com/peteromallet/desloppify.git /tmp/desloppify
+```
+
+## From Vibe Coding to Vibe Engineering
+
+Vibe coding gets things built fast. But the codebases it produces tend to rot in ways that are hard to see and harder to fix — not just the mechanical stuff like dead imports, but the structural kind. Abstractions that made sense at first stop making sense. Naming drifts. Error handling is done three different ways. The codebase works, but working in it gets worse over time.
+
+LLMs are actually good at spotting this now, if you ask them the right questions. That's the core bet here — that an agent with the right framework can hold a codebase to a real standard, the kind that used to require a senior engineer paying close attention over months.
+
+So we're trying to define what "good" looks like as a score that's actually worth optimizing. Not a lint score you game to 100 by suppressing warnings. Something where improving the number means the codebase genuinely got better. That's hard, and we're not done, but the anti-gaming stuff matters to us a lot — it's the difference between a useful signal and a vanity metric.
+
+The hope is that anyone can use this to build something a seasoned engineer would look at and respect. That's the bar we're aiming for.
+
+If you'd like to join a community of vibe engineers who want to build beautiful things, [come hang out](https://discord.gg/aZdzbZrHaY).
+
+<img src="docs/engineering.png" width="100%">
+
+---
+
+<details>
+<summary><strong>Stuff you probably won't need to know</strong></summary>
+
+#### Commands
+
+| Command | Description |
+|---------|-------------|
+| `scan [--reset-subjective]` | Run all detectors, update state (optional: reset subjective baseline to 0 first) |
+| `status` | Score + per-tier progress |
+| `show <pattern>` | Findings by file, directory, detector, or ID |
+| `next [--tier N] [--explain]` | Highest-priority open finding (--explain: with score context) |
+| `resolve <status> <patterns>` | Mark fixed / wontfix / false_positive / ignore |
+| `fix <fixer> [--dry-run]` | Auto-fix mechanical issues |
+| `review --prepare` | Generate subjective review packet (`query.json`) |
+| `review --import <file>` | Import subjective review findings |
+| `issues` | Review findings queue (list/show/update) |
+| `zone` | Show/set/clear zone classifications |
+| `config` | Show/set/unset project configuration |
+| `move <src> <dst>` | Move file/directory, update all imports |
+| `detect <name>` | Run a single detector raw |
+| `plan` | Prioritized markdown plan |
+| `tree` | Annotated codebase tree |
+| `viz` | Interactive HTML treemap |
+| `dev scaffold-lang` | Generate a standardized language plugin scaffold |
+
+#### Detectors
+
+**TypeScript/React**: logs, unused, exports, deprecated, large, complexity, gods, single_use, props, passthrough, concerns, deps, dupes, smells, coupling, patterns, naming, cycles, orphaned, react
+
+**Python**: unused, large, complexity, gods, props, smells, dupes, deps, cycles, orphaned, single_use, naming
+
+**C#/.NET**: deps, cycles, orphaned, dupes, large, complexity
+
+#### Tiers & scoring
+
+| Tier | Fix type | Examples |
+|------|----------|----------|
+| T1 | Auto-fixable | Unused imports, debug logs |
+| T2 | Quick manual | Unused vars, dead exports |
+| T3 | Needs judgment | Near-dupes, single_use abstractions |
+| T4 | Major refactor | God components, mixed concerns |
+
+Score is weighted (T4 = 4x T1). Strict score penalizes both open and wontfix.
+
+#### Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DESLOPPIFY_ROOT` | cwd | Project root |
+| `DESLOPPIFY_SRC` | `src` | Source directory (TS alias resolution) |
+| `--lang <name>` | auto-detected | Language selection (each has own state) |
+| `--exclude <pattern>` | none | Path patterns to skip (repeatable: `--exclude migrations --exclude tests`) |
+| `--no-badge` | false | Skip scorecard image generation |
+| `--badge-path <path>` | `scorecard.png` | Output path for scorecard image |
+| `DESLOPPIFY_NO_BADGE` | — | Set to `true` to disable badge via env |
+| `DESLOPPIFY_BADGE_PATH` | `scorecard.png` | Badge output path via env |
+
+Project config values (stored in `.desloppify/config.json`) are managed via:
+- `desloppify config show`
+- `desloppify config set target_strict_score 95` (default: `95`, valid range: `0-100`)
+- `desloppify config set badge_path scorecard.png` (or nested path like `assets/health.png`)
+
+#### Adding or augmenting a language
+
+Use the scaffold workflow documented in `desloppify/languages/README.md`:
+
+```bash
+desloppify dev scaffold-lang <name> --extension .ext --marker <root-marker>
+```
+
+Detect command keys are standardized to snake_case. CLI compatibility aliases
+like `single-use` and legacy `passthrough` are still accepted.
+Standard plugin shape: `__init__.py`, `commands.py`, `extractors.py`, `phases.py`,
+`move.py`, `review.py`, `test_coverage.py`, plus `detectors/`, `fixers/`, and `tests/`.
+Validated at registration. Zero shared code changes.
+
+#### Architecture
+
+```
+engine/detectors/            ← Generic algorithms (zero language knowledge)
+hook_registry.py             ← Detector-safe access to optional language hooks
+languages/_framework/runtime.py    ← LangRun (per-run mutable scan state)
+languages/_framework/base/         ← Shared framework contracts + phase helpers
+languages/_framework/generic.py    ← generic_lang() factory for tool-based plugins
+languages/_framework/treesitter/   ← Tree-sitter integration (optional)
+languages/<name>/            ← Language config + phases + extractors + detectors + fixers
+```
+
+Import direction: `languages/` → `engine/detectors/`. Never the reverse.
+`LangConfig` stays static; runtime state lives on `LangRun`.
+
+#### Command-Layer Boundaries
+
+Command entry modules are intentionally thin orchestrators:
+
+- `desloppify/app/commands/review/cmd.py` delegates to
+  `desloppify/app/commands/review/prepare.py`, `desloppify/app/commands/review/batches.py`, `desloppify/app/commands/review/import_cmd.py`, and `desloppify/app/commands/review/runtime.py`
+- `desloppify/app/commands/scan/scan_reporting_dimensions.py` delegates to
+  `desloppify/app/commands/scan/scan_reporting_presentation.py` and `desloppify/app/commands/scan/scan_reporting_subjective.py`
+- `desloppify/app/cli_support/parser.py` delegates subcommand construction to `desloppify/app/cli_support/parser_groups.py`
+
+Public CLI behavior should be preserved when refactoring these orchestrators.
+
+#### Allowed Dynamic Import Zones
+
+Dynamic/optional loading is allowed only in explicit extension points:
+
+- `desloppify/languages/__init__.py` for plugin discovery and registration
+- `desloppify/hook_registry.py` for detector-safe optional hooks
+
+Outside these zones, use static imports.
+
+#### State Ownership
+
+- `desloppify/state.py` and `desloppify/engine/_state/` own persisted schema and merge rules
+- `desloppify/languages/_framework/runtime.py` (`LangRun`) owns per-run mutable execution state
+- command modules may read/write state through state APIs, but should not define ad-hoc persisted fields
+
+</details>

desloppify-0.7.0/desloppify/__init__.py

@@ -0,0 +1,3 @@
+"""Desloppify — Automated cruft detection + LLM-ready analysis."""
+
+from __future__ import annotations

desloppify-0.7.0/desloppify/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m desloppify"""
+
+from desloppify.cli import main
+
+main()

desloppify-0.7.0/desloppify/app/__init__.py

@@ -0,0 +1 @@
+"""Application-layer packages: CLI, commands, and output surfaces."""

desloppify-0.7.0/desloppify/app/cli_support/__init__.py

@@ -0,0 +1,2 @@
+"""CLI parser support modules."""
+

desloppify-0.7.0/desloppify/app/cli_support/parser.py

@@ -0,0 +1,122 @@
+"""CLI parser construction helpers."""
+
+from __future__ import annotations
+
+import argparse
+
+from desloppify.app.cli_support.parser_groups import (
+    _add_config_parser,
+    _add_detect_parser,
+    _add_dev_parser,
+    _add_fix_parser,
+    _add_ignore_parser,
+    _add_issues_parser,
+    _add_langs_parser,
+    _add_move_parser,
+    _add_next_parser,
+    _add_plan_parser,
+    _add_resolve_parser,
+    _add_review_parser,
+    _add_scan_parser,
+    _add_show_parser,
+    _add_status_parser,
+    _add_tree_parser,
+    _add_update_skill_parser,
+    _add_viz_parser,
+    _add_zone_parser,
+)
+
+USAGE_EXAMPLES = """
+workflow:
+  scan                          Run all detectors, update state, show diff
+  status                        Score dashboard with per-tier progress
+  tree                          Annotated codebase tree (zoom with --focus)
+  show <pattern>                Dig into findings by file/dir/detector/ID
+  resolve <pattern> <status>    Mark findings as fixed/wontfix/false_positive
+  ignore <pattern>              Suppress findings matching a pattern
+  zone show                     Show zone classifications for all files
+  zone set <file> <zone>        Override zone for a file
+  review --prepare              Prepare holistic codebase review data
+  review --import FILE          Import review findings from JSON
+  issues                        Review findings work queue
+  plan                          Generate prioritized markdown plan
+
+examples:
+  desloppify scan --skip-slow
+  desloppify --lang python scan --path scripts/desloppify
+  desloppify tree --focus shared/components --sort findings --depth 3
+  desloppify tree --detail --focus shared/components/MediaLightbox --min-loc 300
+  desloppify show src/shared/components/PromptEditorModal.tsx
+  desloppify show gods
+  desloppify show "src/shared/components/MediaLightbox"
+  desloppify resolve fixed "unused::src/foo.tsx::React" --note "removed unused React import" --attest "I have actually removed the unused React import from foo.tsx and I am not gaming the score by resolving without fixing."
+  desloppify resolve fixed "logs::src/foo.tsx::*" --note "removed debug logs" --attest "I have actually removed all console.log calls from foo.tsx and I am not gaming the score by resolving without fixing."
+  desloppify resolve wontfix deprecated --note "migration in progress" --attest "I have actually verified these are tracked in the migration plan and I am not gaming the score by resolving without fixing."
+  desloppify ignore "smells::*::async_no_await" --attest "I have actually verified these are intentional fire-and-forget patterns and I am not gaming the score by resolving without fixing."
+  desloppify detect logs --top 10
+  desloppify detect dupes --threshold 0.9
+  desloppify dev scaffold-lang go --extension .go --marker go.mod --default-src .
+  desloppify move src/shared/hooks/useFoo.ts src/shared/hooks/video/useFoo.ts --dry-run
+  desloppify move scripts/foo/bar.py scripts/foo/baz/bar.py
+"""
+
+
+class _NoAbbrevArgumentParser(argparse.ArgumentParser):
+    """Argparse parser variant that disables long-option abbreviation."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("allow_abbrev", False)
+        super().__init__(*args, **kwargs)
+
+
+def create_parser(*, langs: list[str], detector_names: list[str]) -> argparse.ArgumentParser:
+    """Build top-level CLI parser with all subcommands."""
+    lang_help = ", ".join(langs) if langs else "registered languages"
+
+    parser = _NoAbbrevArgumentParser(
+        prog="desloppify",
+        description="Desloppify — codebase health tracker",
+        epilog=USAGE_EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--lang",
+        type=str,
+        default=None,
+        help=f"Language to scan ({lang_help}). Auto-detected if omitted.",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        metavar="PATTERN",
+        help="Path pattern to exclude (component/prefix match; repeatable)",
+    )
+    sub = parser.add_subparsers(
+        dest="command",
+        required=True,
+        parser_class=_NoAbbrevArgumentParser,
+    )
+    _add_scan_parser(sub)
+    _add_status_parser(sub)
+    _add_tree_parser(sub)
+    _add_show_parser(sub)
+    _add_next_parser(sub)
+    _add_resolve_parser(sub)
+    _add_ignore_parser(sub)
+    _add_fix_parser(sub, langs)
+    _add_plan_parser(sub)
+    _add_viz_parser(sub)
+    _add_detect_parser(sub, detector_names)
+    _add_move_parser(sub)
+    _add_review_parser(sub)
+    _add_issues_parser(sub)
+    _add_zone_parser(sub)
+    _add_config_parser(sub)
+    _add_dev_parser(sub)
+    _add_langs_parser(sub)
+    _add_update_skill_parser(sub)
+    return parser
+
+
+__all__ = ["USAGE_EXAMPLES", "create_parser"]