cosmix/loom

loom-dead-code-check

Generate dead code detection configuration for loom plan verification across Rust, TypeScript, Python, Go, and JavaScript.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/cosmix/loom --skill loom-dead-code-check

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Dead Code Detection

Overview

Dead code — written but never called, imported, or used — is a direct signal of incomplete integration: a function nothing calls means the feature isn't wired up. In loom it serves two roles: wiring verification (catch implemented-but-unintegrated code) and code quality (cleanup). Most valuable in integration-verify stages as a final gate over all implementation stages.

⚠️ `truths` is GONE as a standalone field. Put dead-code checks in the first-class `dead_code_check` field (a goal-backward layer, run by loom check) or in `acceptance` (a build/lint command that exits non-zero on findings). A top-level truths: block is rejected as an unknown field.

If dead code survives implementation it usually means: feature not wired (command unregistered, route unmounted), test code never run, refactor leftovers, or an incomplete implementation.

The dead_code_check field (preferred, first-class)

dead_code_check is a goal-backward check evaluated by loom check <stage-id>. Schema:

yaml
dead_code_check:
  command: "cargo build --message-format=short 2>&1"
  fail_patterns: ["warning: unused", "is never read", "never constructed"]
  ignore_patterns: ["generated.rs", "#[allow(dead_code)]"]

Exactly how loom evaluates it (verify/goal_backward/dead_code.rs):

  1. Runs command in working_dir, 120 s timeout, capturing stdout and stderr.
  2. Scans the combined output line by line.
  3. A line is a violation if it contains any fail_pattern (plain substring, not regex) AND contains no ignore_pattern.
  4. Each violating line becomes one gap. A nonzero exit, missing executable, or timeout also records an unavailable-analysis gap.

The analyzer must exit successfully. A successful cargo build with warnings still produces gaps when a warning matches; -D warnings is unnecessary for pattern detection. A nonzero exit or timeout reports unavailable analysis, even if no pattern matches.

⚠ ignore_patterns match the whole output line, so you can suppress by symbol name, file path, or an #[allow(...)] echo — whatever appears on the tool's line. Substring, so old_helper also ignores old_helper_2.

⚠ Choose fail_patterns that appear on the SAME line as the offending item. Tools that split a finding across lines (a header line + an indented location line) may put the symbol name on a different line than the keyword — test the real output first.

dead_code_check vs acceptance

dead_code_checkacceptance
Counts as goal-backward check✅ (satisfies has_any_goal_checks)❌ (separate requirement)
Pass/fail driversuccessful execution and output pattern matchcommand exit code
Surfaced by loom check --suggest✅❌
Needs -D warnings to failno (warnings can match on exit 0)yes

Use dead_code_check when you want dead code counted as goal-backward proof; use acceptance when a tool already exits non-zero on findings and you want it in the build gate.

Per-language tools and patterns

LangTool / commandfail_patterns (substrings)Notes
Rustcargo build --message-format=short 2>&1 (or cargo clippy)warning: unused, is never read, never constructed, never usedcompiler is built in; no install. -D dead_code only needed for the acceptance (exit-code) form
TypeScriptbunx ts-prune (finds unused exports)used in module, module-path lines--error flag → non-zero exit (for acceptance). bun add --dev ts-prune
Pythonvulture src/ --min-confidence 80unused function, unused class, unused import, unused variable, unreachable code--min-confidence (0-100): higher = fewer false positives. uv add --dev vulture
Gostaticcheck ./...is unused, U1000, U1001go install honnef.co/go/tools/cmd/staticcheck@latest. U1000=unused code, U1001=unused field
JSbunx unimported (unused files + unresolved imports)unused file, unresolved importbun add --dev unimported

⚠ Tools ship NO deps in a fresh loom worktree (node_modules, cargo tool binaries, staticcheck). Install or vendor them in knowledge-bootstrap, or require them as preinstalled prerequisites; never bypass the host sandbox with excluded_commands. Otherwise the command reports unavailable analysis. Rust's compiler-based check has no such dependency; prefer it.

Rust example — both forms

yaml
# Goal-backward form (successful execution and pattern-driven findings):
dead_code_check:
  command: "cargo build --message-format=short 2>&1"
  fail_patterns: ["warning: unused", "is never read", "never constructed"]
  ignore_patterns: []

# OR acceptance form (exit-code driven — needs -D):
acceptance:
  - "cargo clippy -- -D warnings"        # dead_code is a subset of clippy warnings

Tool config keys (suppress false positives at the source)

text
ts-prune   .tsprunerc          {"ignore": "index.ts|types.d.ts"}
vulture    pyproject.toml       [tool.vulture] min_confidence=80  paths=["src"]  ignore_names=["setUp","tearDown","test_*"]
staticcheck .staticcheck.conf   checks = ["all", "-ST1000"]
unimported .unimportedrc.json   {"entry":["src/index.js"], "extensions":[".js",".jsx"], "ignorePatterns":["**/*.config.js"]}

Working directory

Dead-code commands run in working_dir, where the build manifest lives (Cargo.toml, package.json, go.mod, pyproject.toml). If Cargo.toml is at loom/, set working_dir: "loom" — otherwise could not find Cargo.toml. All paths in every field are relative to working_dir; never ../.

False positives — what each tool excludes and how to suppress

Real code that looks unused. Handle via the tool's own mechanism first, ignore_patterns second.

| Cause | Rust | TS/JS | Python | Go | | ----- | ---- | ----- | ------ | -- | | Entry points | fn main() auto-excluded | configure entry in tool config | mark __all__ | exported main-pkg funcs excluded | | Test code | #[cfg(test)] auto-excluded | exclude test dirs in config | ignore test_*/setUp/tearDown | *_test.go handled | | Framework magic (derives/decorators) | #[allow(dead_code)] on the item | tool ignore for decorators | vulture respects __all__ | — | | Public API in a lib | pub items excluded by default | ignore lib entry in .tsprunerc | __all__ | exported (capitalized) excluded | | Feature-gated / build-tagged | run with --all-features | enable during check | enable during check | build tags to include variants | | Reflection / dynamic load | document + integration test | — | — | assigned-to-var for reflection |

Golden rule: prefer a language-native suppression (#[allow(dead_code)], __all__, tool config) that lives WITH the code over a broad ignore_patterns entry that can mask real regressions later.

Combine with wiring for a reliable signal

Dead-code detection is a strong signal, not proof. The triple check catches integration holes reliably:

yaml
stages:
  - id: integration-verify
    stage_type: integration-verify
    working_dir: "loom"
    acceptance:
      - "cargo test"
      - 'loom new-command --help'                 # functional: feature reachable
    dead_code_check:
      command: "cargo build --message-format=short 2>&1"
      fail_patterns: ["warning: unused", "never constructed"]
    wiring:
      - source: "src/cli/dispatch.rs"
        pattern: "Commands::NewCommand"           # CONSUMER: dispatch arm, not `mod new_command`
        description: "New command dispatched in CLI"

Dead-code says "code is used somewhere"; wiring says "used at the RIGHT place"; the functional command says "reachable by a user." A stub that's referenced only by its own unit test passes dead-code but fails the functional check.

YAML gotchas

  • ⛔ Never put triple backticks inside a YAML `description` — breaks parsing.
  • Quote every command; default to YAML single quotes so nothing inside is special.
  • For an acceptance negation, ! cmd | rg -q 'warning:' passes when the pattern is absent (! inverts exit code). This is shell !, valid in acceptance — but wiring patterns treat ! as a literal, not negation.
  • Prefer rg over grep (cross-platform, no BSD/GNU -P differences).

Placement

  • integration-verify — primary home; catches orphans from every implementation stage.
  • Per implementation stage — optional, for fast feedback; scope to the package touched (cargo clippy -p auth -- -D warnings).
  • knowledge-bootstrap — install any external tool the plan's checks depend on.

Checklist

  • [ ] Dead-code checks use dead_code_check (goal-backward) or acceptance (exit-code) — NOT a removed truths: block
  • [ ] fail_patterns are substrings that appear on the SAME output line as the finding (verified against real tool output)
  • [ ] dead_code_check command exits successfully; matching warnings still fail, while nonzero exits, missing executables and timeouts report unavailable analysis. The acceptance form uses -D/--error so findings exit non-zero
  • [ ] Any external tool (ts-prune, vulture, staticcheck, unimported) is installed in the worktree or bootstrap stage
  • [ ] working_dir points at the build manifest; all paths relative to it, no ../
  • [ ] False positives suppressed with a language-native mechanism where possible, ignore_patterns only as fallback
  • [ ] Paired with wiring (consumer site) + a functional command for reliable integration proof
  • [ ] No triple backticks in any description
aus demselben Repository

Weitere Skills

Alle Skills