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)