Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion lib/rules/structural_drift.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
#
Expand Down
33 changes: 33 additions & 0 deletions test/structural_drift_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading