SoftwareApp
ddae70a8bc
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.
117 lines
6.9 KiB
Markdown
117 lines
6.9 KiB
Markdown
# Working in this repository
|
|
|
|
**Plain Files** is a file manager for Android: Kotlin and Jetpack Compose, one Gradle module
|
|
(`app`), `minSdk` 26, `targetSdk` 36, and **no `INTERNET` permission** — "nothing leaves the
|
|
device" is a shipping requirement of this app, not a slogan. It is sold once (no ads, no
|
|
subscription, no billing code), and the prose in `docs/` is treated as part of the product.
|
|
|
|
Two habits shape everything here. **The app is driven on a real device** for anything a user can
|
|
see, and what that proved is written down. **A test name is a sentence** about behaviour, so the
|
|
suite doubles as the specification.
|
|
|
|
## Read these two first, and only then the source
|
|
|
|
| file | why |
|
|
|---|---|
|
|
| `docs/CODE_MAP.md` | Generated index of the source tree: what each file holds, and every test name in the suite. Start here for "which file is this in?" |
|
|
| `docs/ROADMAP.md` | Which milestone is done, the key decisions, and the deliberate deferrals |
|
|
|
|
Do **not** read `CHANGELOG.md` front to back — it is long, and it is meant to be grepped by
|
|
feature name once you know what you are changing.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
./gradlew :app:testDebugUnitTest # the gate: 355 JVM tests
|
|
./gradlew :app:lintDebug # the gate: Android Lint
|
|
./gradlew :app:assembleDebug # then: adb install -r app/build/outputs/apk/debug/app-debug.apk
|
|
./gradlew :app:assembleRelease # R8 is on here, and it has hidden real bugs — see Traps
|
|
|
|
python3 tools/make-code-map.py # regenerate docs/CODE_MAP.md after touching source
|
|
python3 tools/make-code-map.py --check # fails when the map is stale
|
|
```
|
|
|
|
There is **no CI**: those two Gradle tasks are the gate, and whoever changes the code runs them.
|
|
Add `--offline` when the network is unavailable — the dependency cache is already warm.
|
|
|
|
## Where things live, and the one rule about direction
|
|
|
|
```
|
|
core/ pure Kotlin, no Android imports: paths, names, kinds, sorting, planning
|
|
data/ storage backends (all-files access, SAF), volumes, shares, SQLite index and trash
|
|
domain/ operations over a source: copy/move/delete/rename, archives, search, duplicates
|
|
service/ the foreground service that keeps a long operation alive
|
|
ui/ Compose: browser/, viewer/, usage/, trash/, duplicates/, theme/
|
|
text/ domain enum to string resource
|
|
```
|
|
|
|
The dependency direction is `ui → domain → data → core`, and `core/` importing `android.*` or
|
|
`androidx.*` is a test failure, not a matter of taste: it is what keeps the trickiest logic
|
|
testable without Robolectric. `docs/CODE_MAP.md` has the per-file detail.
|
|
|
|
## Non-negotiables
|
|
|
|
Each of these is enforced somewhere, so breaking one fails a test, lint, or a reviewer's first
|
|
comment. `app/src/test/java/…/ProjectInvariantsTest.kt` holds the source-level ones.
|
|
|
|
- **No new permission, and never `INTERNET`.** The manifest's permission set is asserted exactly;
|
|
adding one means deciding it, explaining it in the manifest comment and the README, and updating
|
|
that list deliberately.
|
|
- **Every user-visible string comes from `strings.xml`.** The debug build enables a pseudo-locale
|
|
(`values-en-XA`), so untranslated text is visible on screen as unaccented text.
|
|
- **A name is one path segment.** `core/FileNames.isUsableName` is the only implementation; never
|
|
inspect `/` yourself. `StoragePath.child("a/b")` resolves *into a subfolder*, so an unguarded
|
|
call renames or creates something the dialog never offered.
|
|
- **Nothing is overwritten silently.** Operations refuse rather than destroy; deletes go through
|
|
the trash (24-hour window) and offer undo; a batch that cannot succeed is refused as a whole
|
|
rather than performed until it hits the problem.
|
|
- **Comments explain why, not what.** The house style is a KDoc paragraph per file and type that
|
|
says what it is for and what was rejected — decisions and limits, not restatements of the code.
|
|
- **A test name is a sentence about behaviour** (`a batch rename is a single undo step`), because
|
|
the names are read as the spec. Logic gets behaviour tests; rules about the shape of the project
|
|
get source-level tests.
|
|
- **The docs are part of the change.** `CHANGELOG.md` (Added/Changed/Fixed, in the house voice),
|
|
the `ROADMAP.md` milestone table, the README if a claim changed, and `docs/EDGE_CASE_TESTING.md`
|
|
for anything only a device could confirm.
|
|
|
|
## Traps that have cost real time here
|
|
|
|
- **MIUI blocks `adb install` twice over.** Developer options needs *Install via USB*, and each
|
|
install then waits for a confirmation dialog that times out on its own. A bare
|
|
`INSTALL_FAILED_USER_RESTRICTED` means the dialog was answered late, not that the APK is bad.
|
|
- **Never run `assembleDebug` and `adb install` in one parallel batch.** They race, the install
|
|
takes the previous APK, and the feature you just wrote appears to be missing.
|
|
- **R8 has hidden real bugs.** A class reached only by reflection, or named only from a resource,
|
|
is stripped from the release build while debug works perfectly — this happened with `coil-video`,
|
|
where video frames decoded in debug and quietly fell back to icons for real users. When debug and
|
|
release disagree, assume the shrinker removed something.
|
|
- **`adb input text` does not deliver a `/`.** Send `input keyevent 76` instead. The slash is worth
|
|
testing at all because the field *accepts* it and the dialog is what refuses it.
|
|
- **Long-press multi-select via `input swipe x y x y 900` works, but not every time** — it has also
|
|
landed as a plain tap. A flaky gesture is a reason to look at the screen, not to distrust the code.
|
|
- **The debug build is a separate package** (`…filemanager.debug`), so it installs beside a release
|
|
build and the two can be compared directly.
|
|
|
|
## Documentation map — read on demand
|
|
|
|
| file | what it is for |
|
|
|---|---|
|
|
| `README.md` | The tour: features, layout, build, and the honest **known limitations** |
|
|
| `CHANGELOG.md` | The reasoning behind each change. Grep it; do not read it end to end |
|
|
| `docs/ROADMAP.md` | Milestones with their evidence, the key decisions, the deferrals |
|
|
| `docs/EDGE_CASE_TESTING.md` | What was verified, on which device or AVD, and what was not |
|
|
| `docs/PLAY_RELEASE_CHECKLIST.md` | Release only — work it in order |
|
|
| `docs/COMPETITIVE_ANALYSIS.md`, `docs/MONETISATION.md`, `docs/STORE_LISTING.md` | Product context, pricing, and length-checked listing copy |
|
|
| `PRIVACY.md` | The policy text the store listing points at |
|
|
|
|
## Definition of done
|
|
|
|
1. `:app:testDebugUnitTest` and `:app:lintDebug` green.
|
|
2. `python3 tools/make-code-map.py` run, so that `--check` passes.
|
|
3. A `CHANGELOG.md` entry in the house voice: what changed, why, what was rejected, and what was
|
|
verified rather than assumed.
|
|
4. Anything a user can see driven on a device or emulator, with the result written into
|
|
`docs/EDGE_CASE_TESTING.md` — including what was deliberately left untested, and why.
|
|
5. A commit whose subject is a sentence about the change and whose body explains the reasoning.
|
|
The diff already says what changed; the message is there for why it is this way.
|