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

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:
2026-10-17 02:20:01 +02:00
parent 1220aa6679
commit ddae70a8bc
10 changed files with 1277 additions and 7 deletions
+36
View File
@@ -55,6 +55,42 @@ upload needs a **higher `versionCode`** than every previous upload.
snackbar's **Undo** put the later batch of three back in one step. The collision and the slash were
checked the same way, both landing with the action disabled and the reason named.
- **The rules the project states in prose are now checked against the source, and the source has a
generated map.** The first question about any change is *which file is this in*, and the three
documents that kept being asked to answer it — `README` (the tour), `ROADMAP` (what is done) and
`CHANGELOG` (why) — never could. `docs/CODE_MAP.md` does: every one of the 74 source files with
the purpose taken from the KDoc already sitting next to it, its size, and the tests that cover it,
followed by **every test name in the suite**, which in this project is a sentence about behaviour
and therefore the specification itself. It is *generated* by `tools/make-code-map.py` from
declarations and comments rather than written by hand, because a hand-written map of 74 files is
wrong within a milestone; `--check` fails the moment the file stops matching the tree, and the
file says so about itself at the top. `AGENTS.md` is the one page that points at it: the commands,
the layout with its dependency direction, the rules that have tests behind them, and the traps
that have actually cost time here — MIUI's install dialog, an `assembleDebug` racing an
`adb install`, R8 stripping what only a resource names, and that `adb input text` cannot type a
`/`.
The same pass turned four of those stated rules into **failures rather than intentions**.
`ProjectInvariantsTest` reads the tree and asserts that `core/` imports no Android, that no
Compose `Text(...)` in `ui/` is handed a string literal, that the manifest requests exactly the
six permissions the app is built around and never `INTERNET`, and that separator handling lives in
`core/` alone. Three of the four were already true and can no longer quietly stop being true. The
fourth caught a bug: **"New folder" accepted a name that was a path.** `createFolder` checked only
for empty, so `notes/final` was resolved by `StoragePath` into the `notes` folder that happened to
exist — the dialog offered one folder and the app made a different one — while Rename refused the
same input, because the rule had exactly one implementation and only one of the two callers used
it.
Both now go through `core/FileNames.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 —
instead of appearing to do nothing when it is pressed. The batch dialog and the two single-name
dialogs share that one string, so the rule reads the same wherever a name is entered. Verified on
the phone: with `a/b` in the field the note appears and Create is the only disabled node in the
dump; deleting the slash clears the note and re-enables it. **355 JVM tests** (5 added), lint
clean — and the map's own convention is visible inside it: 15 of the 74 files take their purpose
from the first KDoc rather than from a declaration sharing the file's name, and the generated file
lists those at the end instead of pretending otherwise.
### Changed
- **File thumbnails are bigger.** The leading visual in a list row went from 28 dp to 48 dp and