Skip to content

fix(rules): SD022 skips plans and roadmaps, which name paths still to come - #1209

Open
hyperpolymath wants to merge 1 commit into
mainfrom
claude/sd022-planned-paths
Open

hyperpolymath wants to merge 1 commit into
mainfrom
claude/sd022-planned-paths

Conversation

@hyperpolymath

Copy link
Copy Markdown
Owner

What

SD022 (structural_drift) reads a src/<dir>/ reference to a directory that exists nowhere as drift left behind by a rename. A plan or roadmap lists files a work package will create, so every such path is absent by design.

On bactrian#37 it fired three times on docs/status/BACTRIAN-ULTRAPLAN.adoc. The paths were src/driver/, src/ppx/ and src/frontend/, all under a work package's "Files:" line.

Fix

Plans are the mirror of CHANGELOG.md, which SD022 already skips. A changelog records the tree as it was, and a plan records the tree as it will be. Neither describes the current layout, so neither can show rename drift.

planning_doc?/1 recognises a plan by name only. It matches when:

  • a segment of the file name ends in PLAN (PLAN, ULTRAPLAN, IMPLEMENTATION-PLAN), or
  • a segment of the file name equals ROADMAP, or
  • the file sits in a directory named plan, plans or roadmap.

Docs that describe the current state stay in scope.

Evidence

  • New test in test/structural_drift_test.exs:
    • Before the change it fails, because all four plan docs are flagged.
    • After the change it passes.
    • It also checks that EXPLAINME.adoc, which holds the same text, is still flagged.
  • Local test run: test/structural_drift_test.exs, test/rules and test/soundness_test.exs give 1037 tests, 0 failures.
  • Other local checks:
    • scripts/gen-rules-praxis.sh --check: OK.
    • scripts/check-readme-claims.sh: OK.
    • tests/rules-praxis-test.sh: 22 passed.
    • mix format --check-formatted: OK.
  • Not run: I formatted with Elixir 1.17.3 locally. CI's format job runs 1.19.4, and its result is pending.

Generated by Claude Code

… come

SD022 reads a `src/<dir>/` reference to a directory that exists nowhere
as rename drift. A plan or roadmap lists files a work package will
create, so every such path is absent by design. On bactrian#37 it fired
three times on docs/status/BACTRIAN-ULTRAPLAN.adoc (src/driver/,
src/ppx/, src/frontend/ under a work package's "Files:" line).

Plans are the mirror of CHANGELOG.md, which SD022 already skips: one
records the tree as it was, the other the tree as it will be, and
neither describes the current layout. planning_doc?/1 recognises them
by name: a file-name segment ending in PLAN or equal to ROADMAP, or a
plan/plans/roadmap directory. Current-state docs stay in scope; the new
test checks that EXPLAINME.adoc with the same text is still flagged.

The new test fails before the change (all four plan docs flagged) and
passes after; test/structural_drift_test.exs, test/rules and
test/soundness_test.exs: 1037 tests, 0 failures. Formatted with Elixir
1.17.3 locally; the CI format job runs 1.19.4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0136P7ZkGCWGEyedTtdEHAPT
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

  • Bug Fixes
    • Planning and roadmap documents are no longer flagged for references to src/ paths that do not yet exist. This applies when the document name or a parent directory identifies it as a plan or roadmap.
    • References in current-state documents continue to be flagged, while unrelated root-relative references are not reported merely because a nested src/ directory exists.

SD022 now excludes planning documents from stale src/<dir>/ reference checks. A new helper classifies documents by filename or parent directory. A regression test checks planned and current-state references.

Changes: SD022 planning document exclusions

Layer / File(s) Summary
Planning document classification and SD022 exclusion
lib/rules/structural_drift.ex, test/structural_drift_test.exs
A private helper identifies planning documents from filename segments or parent directory names. SD022 excludes those documents from stale-path checks. The regression test verifies that planned references are ignored while a reference in a current-state document remains flagged.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Merge Risk: Minimal · up to d7f36

SD022 now skips plans and roadmaps whose references to not-yet-created paths are intentional, while current-state documents are still checked. The change is small and tested, and no merge-blocking risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: SD022 (structural_drift) now skips plan and roadmap documents, whose paths are not yet created. It matches the raw summary and the PR objectives, and it follows the co…
Description check Passed The description explains the problem (SD022 flags src/ references in plan documents), the fix (skip plans and roadmaps by name, mirroring the existing CHANGELOG.md exclusion), the new test, and the lo…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: SD022 (structural_drift) now skips plan and roadmap documents, whose paths are not yet created. It matches the raw summary and the PR objectives, and it follows the conventional commit format.

Full details: Description check

Explanation

The description explains the problem (SD022 flags src/ references in plan documents), the fix (skip plans and roadmaps by name, mirroring the existing CHANGELOG.md exclusion), the new test, and the local verification results. It relates directly to the changeset.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: c96d7de1-4dd1-4d68-b054-33b4e9d7d91e
Commits

Reviewing files that changed from the base of the PR and between 53ec5b2 and d7f362f.

Files selected for processing: 2

  • lib/rules/structural_drift.ex
  • test/structural_drift_test.exs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Recent review details

Context from checks skipped due to timeout: 60

  • GitHub Check: Escript packaging soundness
  • GitHub Check: Integration Tests
  • GitHub Check: CodeRabbit
  • GitHub Check: Validate Documentation
  • GitHub Check: lint
  • GitHub Check: Build AsciiDoc
  • GitHub Check: docs
  • GitHub Check: governance / Trusted-base reduction policy
  • GitHub Check: governance / JS runtimes — deno
  • GitHub Check: governance / JS runtimes — environment provisions Bun first
  • GitHub Check: governance / JS runtimes — pnpm
  • GitHub Check: governance / Actions lockfile verify
  • GitHub Check: governance / Exemption ratchet
  • GitHub Check: governance / Security policy checks
  • GitHub Check: governance / Licence consistency
  • GitHub Check: governance / JS runtimes — bun
  • GitHub Check: governance / Well-Known (RFC 9116 + RSR)
  • GitHub Check: governance / Language / package anti-pattern policy
  • GitHub Check: governance / Check Workflow Staleness
  • GitHub Check: governance / Guix packaging policy (Nix retired)
  • GitHub Check: governance / UUID v8 conformance
  • GitHub Check: governance / UUID v7 conformance
  • GitHub Check: governance / Code quality + docs
  • GitHub Check: governance / Live Actions policy (credentialed advisory)
  • GitHub Check: governance / Workflow security linter
  • GitHub Check: governance / Debt ratchet
  • GitHub Check: governance / Allowlist Preflight
  • GitHub Check: hypatia / Hypatia Neurosymbolic Analysis
  • GitHub Check: scan / gitleaks
  • GitHub Check: scan / rust-secrets
  • GitHub Check: KYAML conformance (Hypatia.Kyaml against kyq)
  • GitHub Check: k9iser manifest + build
  • GitHub Check: Elixir Compile (dogfood toolchain)
  • GitHub Check: Rust Check & Clippy
  • GitHub Check: Rust Format
  • GitHub Check: Elixir Format (dogfood toolchain)
  • GitHub Check: analyze (actions, none)
  • GitHub Check: E2E — Rust CLI Scan
  • GitHub Check: Aspect — Rule Module Coverage
  • GitHub Check: E2E — Elixir Scanner Pipeline
  • GitHub Check: stress-test
  • GitHub Check: criterion + baseline gate
  • GitHub Check: Estate rules and sweep structure
  • GitHub Check: Validate K9 contracts
  • GitHub Check: Empty-linter (invisible characters)
  • GitHub Check: Validate DEED manifests
  • GitHub Check: Check
  • GitHub Check: Container Security (Trivy) (deploy/Containerfile)
  • GitHub Check: License Compliance Check
  • GitHub Check: Rust License & Ban Check
  • GitHub Check: Generate SBOM
  • GitHub Check: Rust Dependency Audit
  • GitHub Check: Secret Detection (TruffleHog)
  • GitHub Check: Groove manifest check
  • GitHub Check: Cargo check + clippy + fmt
  • GitHub Check: CodeQL Analysis (actions)
  • GitHub Check: Language Policy
  • GitHub Check: Build AsciiDoc
  • GitHub Check: docs
  • GitHub Check: Validate Documentation
Additional comments: 2

lib/rules/structural_drift.ex: 1

1084-1084: LGTM!

Also applies to: 1145-1174

test/structural_drift_test.exs: 1

460-491: LGTM!

Finishing Touches
Fix failing CI checks

  • Commit to this branch
  • Create a new PR

@sonarqubecloud

Copy link
Copy Markdown

@linear-code
linear-code Bot marked this pull request as ready for review November 19, 2026 01:18

Copy link
Copy Markdown
Owner Author

governance / Validate Hypatia Baseline is red because of main, not this PR.

  • The failures are all research_extensions/RE011 (medium). They are in test/ci-health-test.sh, tests/rules-praxis-test.sh, test/standards-integration-test.sh, scripts/standards-integration/check-standards-integration.sh and scripts/security-check.sh.
  • This PR changes only lib/rules/structural_drift.ex (SD022) and its test. Neither file is in that list.
  • The same check fails on the base commit 53ec5b2 (run 44374660011).
  • fix(ci): stop piping into a quiet grep (RE011) #1208 ("stop piping into a quiet grep (RE011)") is the open fix. Once it merges, I'll merge main into this branch so the check reruns.

Generated by Claude Code

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants