From d7f362f24ba366cb601c750b98cf734ada47b394 Mon Sep 17 00:00:00 2001
From: CLAUDE <355856132+HoTT-stuff@users.noreply.github.com>
Date: Thu, 19 Nov 2026 01:15:14 +0000
Subject: [PATCH] fix(rules): SD022 skips plans and roadmaps, which name paths
still to come
SD022 reads a `src/
/` 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
Claude-Session: https://claude.ai/code/session_0136P7ZkGCWGEyedTtdEHAPT
---
lib/rules/structural_drift.ex | 33 ++++++++++++++++++++++++++++++++-
test/structural_drift_test.exs | 33 +++++++++++++++++++++++++++++++++
2 files changed, 65 insertions(+), 1 deletion(-)
diff --git a/lib/rules/structural_drift.ex b/lib/rules/structural_drift.ex
index b9305b02..f97a1525 100644
--- a/lib/rules/structural_drift.ex
+++ b/lib/rules/structural_drift.ex
@@ -1081,7 +1081,7 @@ defmodule Hypatia.Rules.StructuralDrift do
])
|> Enum.reject(fn rel ->
rel == "CHANGELOG.md" or Enum.any?(corpus_prefixes, &String.starts_with?(rel, &1)) or
- nested_project_doc?(repo_path, rel)
+ nested_project_doc?(repo_path, rel) or planning_doc?(rel)
end)
|> Enum.flat_map(fn rel ->
path = Path.join(repo_path, rel)
@@ -1142,6 +1142,37 @@ defmodule Hypatia.Rules.StructuralDrift do
File.dir?(Path.join([repo_path, Path.dirname(rel), "src"]))
end
+ # A plan or roadmap describes the tree as it WILL be: the paths it lists are
+ # files a work package is to create, not paths that survived a rename. It is
+ # the mirror of CHANGELOG.md, which records the tree as it WAS; neither
+ # describes the current layout, so neither can show rename drift.
+ #
+ # Measured 2026-11-15 on bactrian#37: docs/status/BACTRIAN-ULTRAPLAN.adoc
+ # lists `src/driver/`, `src/ppx/` and `src/frontend/` under a work package's
+ # "Files:" line. None exists yet, so SD022 fired three times on a correct plan.
+ #
+ # Recognised by name only: a file-name segment ending in PLAN (PLAN,
+ # ULTRAPLAN, IMPLEMENTATION-PLAN) or equal to ROADMAP, or a directory named
+ # plan/plans/roadmap. EXPLAINME and other current-state docs stay in scope.
+ defp planning_doc?(rel) do
+ segments = fn s -> s |> String.upcase() |> String.split(~r/[-_.\s]+/, trim: true) end
+
+ name_hit =
+ rel
+ |> Path.basename()
+ |> Path.rootname()
+ |> segments.()
+ |> Enum.any?(&(&1 == "ROADMAP" or String.ends_with?(&1, "PLAN")))
+
+ dir_hit =
+ rel
+ |> Path.dirname()
+ |> Path.split()
+ |> Enum.any?(&(String.downcase(&1) in ["plan", "plans", "roadmap"]))
+
+ name_hit or dir_hit
+ end
+
# Drop whole-line comments before matching. A commented-out example is not a
# live claim about the tree.
#
diff --git a/test/structural_drift_test.exs b/test/structural_drift_test.exs
index 02b44fea..0fcd071a 100644
--- a/test/structural_drift_test.exs
+++ b/test/structural_drift_test.exs
@@ -457,6 +457,39 @@ defmodule Hypatia.Rules.StructuralDriftTest do
assert Enum.any?(findings, &(&1.stale_dir == "gone" and &1.file == "tools/x/README.md"))
end
+ test "a plan or roadmap names paths still to be created, not rename drift", %{repo: repo} do
+ # Measured 2026-11-15 on bactrian#37: docs/status/BACTRIAN-ULTRAPLAN.adoc
+ # lists `src/driver/`, `src/ppx/` and `src/frontend/` as files a work
+ # package will create. They exist nowhere yet, so SD022 fired three times.
+ File.mkdir_p!(Path.join([repo, "src", "core"]))
+ File.mkdir_p!(Path.join([repo, "docs", "status"]))
+ File.mkdir_p!(Path.join([repo, "docs", "plans"]))
+ planned = "*Files:* `src/driver/main.ml`; `src/ppx/`, `src/frontend/`."
+ File.write!(Path.join([repo, "docs", "status", "BACTRIAN-ULTRAPLAN.adoc"]), planned)
+ File.write!(Path.join([repo, "docs", "status", "ROADMAP.adoc"]), planned)
+ File.write!(Path.join([repo, "docs", "plans", "w2.md"]), planned)
+ File.write!(Path.join([repo, "IMPLEMENTATION-PLAN.md"]), planned)
+ # A current-state doc with the same text is still checked.
+ File.write!(Path.join(repo, "EXPLAINME.adoc"), "See src/driver/main.ml.")
+ File.write!(Path.join([repo, "src", "core", "a.ml"]), "")
+ System.cmd("git", ["init", "-q"], cd: repo)
+ System.cmd("git", ["add", "."], cd: repo)
+
+ System.cmd("git", ["commit", "-q", "-m", "init", "--no-gpg-sign"],
+ cd: repo,
+ env: [
+ {"GIT_AUTHOR_NAME", "T"},
+ {"GIT_AUTHOR_EMAIL", "t@t"},
+ {"GIT_COMMITTER_NAME", "T"},
+ {"GIT_COMMITTER_EMAIL", "t@t"}
+ ]
+ )
+
+ findings = StructuralDrift.sd022_stale_path_after_rename(repo)
+ assert Enum.map(findings, & &1.file) |> Enum.uniq() == ["EXPLAINME.adoc"]
+ assert Enum.map(findings, & &1.stale_dir) == ["driver"]
+ end
+
test "returns empty when src/ has no subdirs", %{repo: repo} do
File.write!(Path.join(repo, "README.md"), "test")
findings = StructuralDrift.sd022_stale_path_after_rename(repo)