fishfacegit/file-manager
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Turn the project's rules into tests, and generate a map of where everything lives

Browse Source 
The first question about any change is which file it belongs in, and the three documents that
kept being asked to answer it - README (the tour), ROADMAP (what is done) and CHANGELOG (why it is
like that) - were never going to. docs/CODE_MAP.md answers it: all 74 source files with the purpose
taken from the KDoc already sitting next to them, their size, and the tests that cover them,
followed by every test name in the suite. Those names are sentences about behaviour in this project
("a batch rename is a single undo step"), so the index doubles as the specification, and it is the
cheapest way for a reader, human or otherwise, to find out whether something is already covered.

The map is generated by tools/make-code-map.py rather than written, because a hand-maintained
description of 74 files is wrong within a milestone and nobody notices. The script harvests
declarations and comments; --check fails the moment the file stops matching the tree, and it caught
this very change (350 tests to 355); and the file says so about itself in its first line. A file is
described by the KDoc of the declaration that shares its name, which is the convention this
codebase already follows, and where no declaration matches, the first KDoc is used and the file is
listed at the end - so 15 fallbacks out of 74 are visible rather than assumed. Test files are
attached by the class they declare (NameTest -> Name.kt), which is a name-based match and therefore
approximate: the one honest weakness, and worth knowing before trusting a row that says a file has
no tests.

AGENTS.md is the one page that points at the map: what the app is, the two files to read before the
source, the exact commands, the layout with its dependency direction (ui -> domain -> data -> core,
with core free of Android), the rules that have tests behind them, what to read on demand and what
not to read at all, the definition of done, and the traps that have cost real time here - MIUI's two
install gates, assembleDebug racing an adb install, R8 stripping what only a resource names, and adb
input text not delivering a slash.

The same pass made four of the project's stated rules fail instead of merely being stated, in
ProjectInvariantsTest, which reads the source tree: core/ imports no Android (the engine stays
testable without Robolectric), no Text(...) in ui/ is handed a string literal (text comes from
strings.xml, which the pseudo-locale build exercises), the manifest requests exactly the six
permissions the app is built around and never INTERNET, and separator handling lives in core/ alone.
Three of the four were already true. The fourth found a bug: createFolder checked only that the name
was not empty, so "notes/final" was resolved by StoragePath into the notes folder that happened to
exist - the dialog offered one folder in the folder on screen and the app created a different one.
Rename refused the same input, because the rule has exactly one implementation and only one of its
two callers used it.

Both callers now go through isUsableName, and the shared name dialog says why a name is refused -
"A name cannot contain a slash", while it is typed, with its button disabled - rather than appearing
to do nothing when it is pressed. The batch dialog and both single-name dialogs read the same
string, so the rule reads the same wherever a name is entered. Verified on the phone: a slash typed
into New folder shows the note with Create the only disabled node in the dump, and deleting the
slash clears the note and re-enables it.

355 JVM tests (5 added: the four invariants and the folder-name refusal), lint clean, the map
current. The source-level rules state their own limits in their comments - the literal rule catches
a literal as the whole text of a Text(...) and not one concatenated into resource text, because
seeing that would take a Kotlin parser, and a rule that pretends otherwise is worse than one that
says where it stops.
This commit is contained in:
Hadrian Burkhardt
2026-10-17 02:20:01 +02:00
parent 1220aa6679
commit ddae70a8bc
10 changed files with 1277 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/make-code-map.py
+306
View File
@@ -0,0 +1,306 @@
#!/usr/bin/env python3
"""
Builds docs/CODE_MAP.md: the one-file index of what lives where.
python3 tools/make-code-map.py # write docs/CODE_MAP.md
python3 tools/make-code-map.py --check # exit 1 if the file on disk is stale
Why this exists: the source is 12 000 lines across 74 files, which is more than fits in
anyone's head - and the first question about any change is "which file, and what does it
do?". A hand-written overview of that would be out of date within a milestone, so this one
is *derived*: every line comes from a declaration or from the KDoc already next to it, and
`--check` fails the moment the file stops matching the tree.
The rule that makes the map useful rather than merely long: a file is described by the KDoc
of the declaration that shares its name (`BatchRename.kt` -> `BatchRename`), which is the
convention this codebase already follows. When no declaration matches, the first KDoc in the
file is used, and the file is listed at the end so the convention can be checked rather than
assumed.
Test names are sentences about behaviour in this project, so the behaviour index at the end
doubles as the specification: every name is a claim about what the app does.
"""
import argparse
import re
import sys
from pathlib import Path
PACKAGE = "de/softwareapp_hb/filemanager"
# One line per package, because a directory has no comment of its own. Kept here rather than
# in the generated file so there is exactly one place to update it; the README's layout
# section says the same thing more briefly.
PACKAGES = {
"core": "Pure Kotlin, **no Android imports**: paths, file names, kinds, sorting, "
"formatting, matching, the batch-rename planner",
"data": "Storage backends (all-files access and SAF), volumes, incoming shares, the "
"SQLite search index and trash index",
"domain": "Operations over a source: copy/move/delete/rename, archives, search walking, "
"duplicate finding, trash, usage analysis",
"service": "The foreground service that keeps a long operation alive and reports it",
"text": "Domain enum to string-resource mapping",
"ui/browser": "The browser screen: view model, state, list and grid, dialogs, selection bar",
"ui/viewer": "The built-in viewers (text, image, PDF, media, markup, archive contents)",
"ui/usage": "The storage-usage screen",
"ui/trash": "The trash screen",
"ui/duplicates": "The duplicate-finder screen",
"ui/theme": "Compose theme, colours, type",
"ui": "Compose screens and their shared pieces",
"": "Application entry points",
}
DECLARATION = re.compile(
r"^(?:(?:public|internal|private|protected|abstract|open|sealed|data|value|inline|"
r"suspend|operator|override|const|lateinit|external|annotation|enum)\s+)*"
r"(enum class|sealed class|sealed interface|data class|data object|annotation class|"
r"value class|class|object|interface|fun|val|var|typealias)\s+([A-Za-z_][A-Za-z0-9_]*)"
)
DOC_START = re.compile(r"^\s*/\*\*")
TEST_FUN = re.compile(r"^\s*fun\s+`([^`]+)`")
TEST_CLASS = re.compile(r"^(?:class|object)\s+([A-Za-z_][A-Za-z0-9_]*)")
def repo_root() -> Path:
"""The repository root, found from this file rather than from the working directory."""
here = Path(__file__).resolve()
for candidate in (here.parent, *here.parents):
if (candidate / "settings.gradle.kts").is_file():
return candidate
sys.exit("make-code-map.py: no settings.gradle.kts above %s" % here)
def first_sentence(block: str, limit: int = 190) -> str:
"""The first sentence of a KDoc block, as one line and without markdown decoration."""
parts = []
for line in block.splitlines():
line = line.strip().lstrip("/").lstrip("*").strip()
if line.startswith("@") or not line:
continue
parts.append(line)
joined = " ".join(parts)
joined = re.sub(r"\[([^\]]+)]", r"\1", joined)
joined = re.sub(r"`([^`]*)`", r"\1", joined)
joined = re.sub(r"\*+", "", joined)
match = re.search(r"^(.*?[.!?])(\s|$)", joined)
sentence = (match.group(1) if match else joined).strip()
if len(sentence) > limit:
sentence = sentence[:limit].rsplit(" ", 1)[0] + "…"
return sentence
def kdocs(source: str):
"""Every KDoc block: (start line, body, line of the declaration it documents)."""
lines = source.splitlines()
blocks = []
index = 0
while index < len(lines):
if DOC_START.match(lines[index]):
end = index
body = []
while end < len(lines):
body.append(lines[end])
if "*/" in lines[end]:
break
end += 1
after = end + 1
while after < len(lines) and (not lines[after].strip()
or lines[after].lstrip().startswith("@")):
after += 1
blocks.append((index, "\n".join(body), after))
index = end + 1
else:
index += 1
return blocks
def declarations(source: str):
"""Top-level declarations, as (kind, name, doc first sentence, line number)."""
lines = source.splitlines()
blocks = kdocs(source)
doc_of = {after: first_sentence(body) for start, body, after in blocks}
found = []
for index, line in enumerate(lines):
if not line or line[0].isspace():
continue
match = DECLARATION.match(line)
if not match:
continue
found.append((match.group(1), match.group(2), doc_of.get(index), index + 1))
return found
def purpose_of(path: Path, decls):
"""The KDoc of the declaration sharing the file's name, else the first one there is."""
for kind, name, doc, line in decls:
if name == path.stem and doc:
return doc, True
for kind, name, doc, line in decls:
if doc:
return doc, False
return "", False
def scan_source(main_dir: Path):
entries = []
for path in sorted(main_dir.rglob("*.kt")):
source = path.read_text(encoding="utf-8")
decls = declarations(source)
doc, matched = purpose_of(path, decls)
entries.append({
"rel": path.relative_to(main_dir).as_posix(),
"package": path.parent.relative_to(main_dir).as_posix(),
"stem": path.stem,
"lines": len(source.splitlines()),
"decls": decls,
"doc": doc,
"matched": matched,
})
return entries
def scan_tests(test_dir: Path):
entries = []
for path in sorted(test_dir.rglob("*.kt")):
source = path.read_text(encoding="utf-8")
lines = source.splitlines()
names = [TEST_FUN.match(line).group(1) for line in lines if TEST_FUN.match(line)]
if not names:
continue
subjects = [match.group(1)[:-4]
for match in (TEST_CLASS.match(line) for line in lines)
if match and match.group(1).endswith("Test")]
# A test class is the usual way to say what is covered; a test file named after the file
# rather than after a declaration (FileNamesTest -> FileNames.kt) is the other, so both
# are offered and the source tree decides which one lands.
subjects.append(path.stem[:-4] if path.stem.endswith("Test") else path.stem)
entries.append({
"rel": path.relative_to(test_dir).as_posix(),
"stem": path.stem,
"subjects": subjects,
"tests": names,
})
return entries
def render(root: Path) -> str:
main_dir = root / "app/src/main/java" / PACKAGE
test_dir = root / "app/src/test/java" / PACKAGE
sources = scan_source(main_dir)
tests = scan_tests(test_dir)
by_declaration = {}
by_stem = {}
for entry in sources:
for kind, name, doc, line in entry["decls"]:
by_declaration.setdefault(name, entry)
by_stem.setdefault(entry["stem"], entry)
tests_for = {}
unplaced = []
for test in tests:
placed = False
for subject in test["subjects"]:
target = by_declaration.get(subject) or by_stem.get(subject)
if target is None:
continue
bucket = tests_for.setdefault(target["rel"], [])
if test not in bucket:
bucket.append(test)
placed = True
if not placed:
unplaced.append(test)
out = [
"# Code map\n",
"Generated from the source by `tools/make-code-map.py` - do not edit by hand. "
"Regenerate it after a change (`python3 tools/make-code-map.py`); `--check` exits "
"non-zero when this file is stale.\n",
"%d source files, %d lines - %d test files, %d tests. The behaviour index at the end "
"lists every test name, and in this project a test name is a sentence about what the "
"app does, so it doubles as the specification.\n"
% (len(sources), sum(entry["lines"] for entry in sources),
len(tests), sum(len(test["tests"]) for test in tests)),
"Start at `AGENTS.md`. What is done, and why: `docs/ROADMAP.md` and `CHANGELOG.md`. "
"What was verified by hand rather than by a test: `docs/EDGE_CASE_TESTING.md`.\n",
]
packages = list(PACKAGES) + [name for name in sorted({entry["package"] for entry in sources})
if name not in PACKAGES]
for package in packages:
entries = [entry for entry in sources if entry["package"] == package]
if not entries:
continue
out.append("\n## %s\n" % (package + "/" if package else "(root files)"))
if PACKAGES.get(package):
out.append("%s\n" % PACKAGES[package])
out.append("\n| file | lines | what it holds | tests |")
out.append("|---|---|---|---|")
for entry in entries:
declared = ", ".join(name + "()" if kind == "fun" else name
for kind, name, doc, line in entry["decls"])
cell = "%s%s" % ("%s " % entry["doc"] if entry["doc"] else "", declared)
covered = ", ".join("`%s` (%d)" % (test["stem"], len(test["tests"]))
for test in tests_for.get(entry["rel"], [])) or "-"
out.append("| `%s` | %d | %s | %s |"
% (Path(entry["rel"]).name, entry["lines"],
cell.replace("|", "\\|").strip(), covered))
out.append("\n## Behaviour index\n")
out.append("Every test name in the suite, by file: the fastest way to see whether "
"something is already covered, and what the app claims to do.\n")
for test in tests:
out.append("\n### `%s` (%d)\n" % (test["rel"], len(test["tests"])))
out.extend("- %s" % name for name in test["tests"])
if unplaced:
out.append("\n### Test files with no source file of the same name\n")
for test in unplaced:
out.append("- `%s` (%d tests) - %s"
% (test["rel"], len(test["tests"]),
", ".join(test["subjects"]) or "no named subject"))
fallbacks = [entry for entry in sources if not entry["matched"]]
out.append("\n---\n")
out.append("Purpose taken from the first KDoc rather than from a declaration sharing the "
"file's name (%d of %d): %s\n"
% (len(fallbacks), len(sources),
", ".join("`%s`" % Path(entry["rel"]).name for entry in fallbacks) or "none"))
return re.sub(r"\n{3,}", "\n\n", "\n".join(out)).rstrip("\n") + "\n"
def main() -> int:
parser = argparse.ArgumentParser(description="Build or verify docs/CODE_MAP.md")
parser.add_argument("--check", action="store_true",
help="exit non-zero if docs/CODE_MAP.md is out of date")
args = parser.parse_args()
root = repo_root()
target = root / "docs/CODE_MAP.md"
rendered = render(root)
if args.check:
current = target.read_text(encoding="utf-8") if target.is_file() else ""
if current == rendered:
print("docs/CODE_MAP.md is current")
return 0
current_lines = current.splitlines()
rendered_lines = rendered.splitlines()
for number in range(max(len(current_lines), len(rendered_lines))):
old = current_lines[number] if number < len(current_lines) else "<missing>"
new = rendered_lines[number] if number < len(rendered_lines) else "<missing>"
if old != new:
print("docs/CODE_MAP.md is out of date at line %d:" % (number + 1))
print(" on disk: %s" % old)
print(" source: %s" % new)
break
print("run: python3 tools/make-code-map.py")
return 1
target.write_text(rendered, encoding="utf-8")
print("wrote %s (%d lines)" % (target.relative_to(root), rendered.count("\n") + 1))
return 0
if __name__ == "__main__":
raise SystemExit(main())