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
1 change: 1 addition & 0 deletions .claude/agents/reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ Read AGENTS.md and docs/vision.md first. Read any ADR in docs/adr/ and any spec
4. **Architecture rules**, once there is code. Module boundaries, NewPipeExtractor used only in the YouTube layer, logging only through the Logger with constant messages, tags and field names and no user data, as ADR 0007 defines it, MVI with a pure reducer, playback state kept out of screen state, no hardcoded strings or colors, no GlobalScope, committed Room schema files, and, from the first public release on, a migration plus migration test for every Room schema change.
- Dewfall's lint checks in `:lint-rules` enforce ADR 0007's logging rules. Flag any change to their exceptions, in LogWriterClass.kt, and ask the maintainer about it. It is a must-fix unless the same pull request updates ADR 0007 with a dated note. Also flag any lint.xml file, lint baseline, or lint setting that names a Dewfall issue, such as `disable`, a severity, or `checkOnly`, and any change that makes a Dewfall issue suppressible.
- @ConstantText goes only on a String parameter that its function passes on as log text.
- Lint can't read a module's src/screenshotTest folder, so check it by hand. Every .kt file there holds only @PreviewTest wrappers whose body is one call to a preview in src/main, such as `private fun ResultsScreenshot() = ResultsPreview()`, with no logging and no other code. The only other files there are reference images under src/screenshotTest<Variant>/reference/. scripts/scan_screenshot_tests.py checks this shape too. ADR 0007's note of November 21, 2026 explains why.
5. **Kotlin style.** Read every changed Kotlin file, main code and tests, against the Kotlin style rule next to the formatting commands in AGENTS.md.
6. **Tests.** New logic has tests. Unit tests never touch the network. No test was deleted, skipped or weakened.
7. **Workflow.** The work is on a branch, not main. Commit messages follow the conventional format. Before a push, the hand-off shows the pre-push gate's output for HEAD, ending with PASS, as AGENTS.md asks. A behavior change has an OpenSpec change. A hard-to-reverse decision has an ADR. docs/architecture.md is updated if the structure changed. If the work fully finishes a roadmap task, the pull request closes that task's issue on the project board. It never closes the issue of an unfinished task.
Expand Down
6 changes: 6 additions & 0 deletions .coderabbit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,12 @@ reviews:
- path: "**/src/test/**"
instructions: >-
Check tests against AGENTS.md's Testing rules and docs/testing.md.
- path: "**/src/screenshotTest/**"
instructions: >-
Android Lint and Dewfall's lint checks don't read this folder. It holds only @PreviewTest
wrappers whose body is one call to a preview in src/main, with no logging and no other
code, which scripts/scan_screenshot_tests.py checks. See the note of November 21, 2026 in
docs/adr/0007-how-the-app-logs.md and docs/testing.md#screenshot-tests.
- path: ".github/workflows/**"
instructions: >-
Check workflows against the GitHub Actions rule in AGENTS.md's How to work section.
Expand Down
21 changes: 16 additions & 5 deletions .github/workflows/pull-request.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Checks every pull request to main: formatting, detekt, Android Lint with the Android API check,
# unit tests, a debug build, and the Room schema check. It runs the all-checks command from
# AGENTS.md.
# unit tests, screenshot tests, a debug build, the Room schema check, and the scan of the screenshot
# test folders. It runs the all-checks command from AGENTS.md.
name: Pull request

on:
Expand Down Expand Up @@ -66,10 +66,10 @@ jobs:

# --continue reports every failing check in one run. sdkDownload=false makes a missing SDK
# package fail the build instead of downloading silently.
- name: Check formatting, run detekt, lint and unit tests, and build the debug APK
- name: Check formatting, run detekt, lint, unit and screenshot tests, and build the debug APK
run: >-
./gradlew --continue -Pandroid.builder.sdkDownload=false
spotlessCheck detekt lint test assembleDebug
spotlessCheck detekt lint test testDebugScreenshotTestDefaultTestSuite assembleDebug

# Room rewrites the schema files in core/database/schemas/ when the database changes, and the
# build still passes, even when the version number stays the same. This fails when the build
Expand All @@ -85,11 +85,22 @@ jobs:
exit 1
fi

# Lint can't read the src/screenshotTest folders, so this checks that they hold only one-call
# preview wrappers and reference images. See docs/testing.md#screenshot-tests. It runs even
# when a step above failed.
- name: Check the screenshot test folders
if: ${{ !cancelled() }}
run: python3 -I scripts/scan_screenshot_tests.py

# The screenshot tests' report names the images it compared. The new and diff images stay in
# the results folder, so they are uploaded too.
- name: Upload the reports
if: failure()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: reports
path: "**/build/reports/"
path: |
**/build/reports/
**/build/intermediates/*/testDebugScreenshotTestDefaultTestSuite/results/
retention-days: 7
if-no-files-found: ignore
18 changes: 11 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,10 @@ This section is updated whenever a phase's milestone closes.
| core/database/schemas/ | The Room database schemas that the build writes, one JSON file per database version |
| core/youtube/src/test/resources/youtube/ | The saved YouTube responses that the YouTube layer's tests replay, which the recorder writes |
| feature/ | Feature modules, two for each feature. Today the Search YouTube screen, the video screen, and the YouTube layer's debug screen, which only debug builds contain |
| feature/*-ui/src/screenshotTest/ | The screenshot tests: one-call @PreviewTest wrappers of the previews in src/main. The reference images they are compared with are in src/screenshotTestDefaultDebug/reference/ next to it. docs/testing.md#screenshot-tests explains them |
| build-logic/ | Convention plugins with the build settings that every module shares |
| lint-rules/ | Dewfall's own lint checks, which lint runs on every module of the app. They enforce ADR 0007's logging rules, and nothing from them ships |
| scripts/ | The pre-push gate, which checks every commit before a push, its scan of the saved YouTube responses, the maintainer subagent's guard and checkout script, and their tests. docs/testing.md#the-pre-push-gate explains the gate |
| scripts/ | The pre-push gate, which checks every commit before a push, its scan of the saved YouTube responses, the scan of the screenshot test folders, the maintainer subagent's guard and checkout script, and their tests. docs/testing.md#the-pre-push-gate explains the gate |
| gradle/libs.versions.toml | The version of every plugin and library |
| config/detekt/detekt.yml | detekt's settings: the changes to its default rules, and the list of Compose rules |
| .editorconfig | Editor settings, with a Kotlin section that comes close to the formatter |
Expand Down Expand Up @@ -105,19 +106,19 @@ These apply from Phase 2 on. A pull request that refines them updates this secti
- Colors come from MaterialTheme color roles. Never hardcode colors. The one exception is `:app`'s launch window theme, which Android draws before Compose can read MaterialTheme, so it copies Dewfall's surface color from tokens.json, and LaunchThemeTest checks the copy. Every screen must work in light, dark and dynamic color.
- Every screen draws edge to edge and handles window insets. Backgrounds may sit under the system bars, but no text or controls sit under the system bars or the display cutout. Android 16 and later give apps that target them no way to opt out. See ADR 0006.
- Annotation processors for Kotlin code, such as Hilt's and Room's compilers, run through KSP. The kotlin-kapt plugin doesn't work with AGP's built-in Kotlin, and Google recommends KSP over its com.android.legacy-kapt fallback. Ask first before adding kotlin-kapt or com.android.legacy-kapt.
- Log only through the Logger from `:core:logging`, which a class receives in its constructor. Messages, tags and field names are constant text: a string literal, a `const val`, or `+` of those, never a string template. A function that passes its own String parameter on as one of them marks it @ConstantText. Never log user data, as [ADR 0007](docs/adr/0007-how-the-app-logs.md#user-data) defines it. Never call android.util.Log outside LogcatWriter in `:app`, which calls only Log.println. Never write to standard output outside ConsoleLogWriter, which writes the lines of the recorder of saved YouTube responses and of the live YouTube check in `:core:youtube`'s tests, and never write to standard error or call printStackTrace anywhere. Never use NewPipeExtractor's ExtractorLogger, and never use another logging API, such as java.util.logging. Reducers never log. Dewfall's lint checks enforce these rules in main and test sources, and nothing can suppress them. Any change to their two exceptions updates ADR 0007 in the same pull request, with a dated note.
- Log only through the Logger from `:core:logging`, which a class receives in its constructor. Messages, tags and field names are constant text: a string literal, a `const val`, or `+` of those, never a string template. A function that passes its own String parameter on as one of them marks it @ConstantText. Never log user data, as [ADR 0007](docs/adr/0007-how-the-app-logs.md#user-data) defines it. Never call android.util.Log outside LogcatWriter in `:app`, which calls only Log.println. Never write to standard output outside ConsoleLogWriter, which writes the lines of the recorder of saved YouTube responses and of the live YouTube check in `:core:youtube`'s tests, and never write to standard error or call printStackTrace anywhere. Never use NewPipeExtractor's ExtractorLogger, and never use another logging API, such as java.util.logging. Reducers never log. Dewfall's lint checks enforce these rules in main and test sources, and nothing can suppress them. Lint can't read the screenshot test folders, src/screenshotTest, so they hold only one-call wrappers of previews in src/main, and scripts/scan_screenshot_tests.py, which the gate and the pull request workflow run, checks that shape. See ADR 0007's note of November 21, 2026. Any change to the lint checks' two exceptions updates ADR 0007 in the same pull request, with a dated note.
- Use coroutines and Flow. Never use GlobalScope. Inject dispatchers so tests can replace them. The one exception is viewModelScope's Main dispatcher: ViewModels take no dispatcher, and their tests replace Main with Dispatchers.setMain.
- The database uses Room 3, in the androidx.room3 package. Room 2 is deprecated.
- Room schemas are exported into core/database/schemas/. Commit the schema files that the build writes, and never edit them by hand. The first public release is the first GitHub release, including a pre-release, published from a version tag. A tag made only to test the release workflow, with no published release, doesn't count, and nightly APKs don't count. Until then, the database stays at version 1, and a schema change needs no migration. From the first public release on, every schema change raises the version and needs a migration and a migration test. Never use destructive migrations.

## Testing rules

- New logic ships with tests in the same pull request.
- Write tests with kotlin.test's annotations and assertions. They run on JUnit 6 in plain Kotlin/JVM modules and on JUnit 4 in Android modules. docs/testing.md explains how to test reducers and ViewModels.
- Write tests with kotlin.test's annotations and assertions. They run on JUnit 6 in plain Kotlin/JVM modules and on JUnit 4 in Android modules. docs/testing.md explains how to test reducers and ViewModels. Screenshot tests are the exception: they are @PreviewTest wrappers of previews, which the screenshot engine's own test engine runs.
- ViewModel tests replace the Main dispatcher with Dispatchers.setMain before each test and reset it after.
- Unit tests never touch the network. The YouTube layer is tested against saved responses. Live YouTube checks run in the scheduled CI workflow, or by hand with `./gradlew :core:youtube:liveYouTubeCheck`. Recording the saved responses is the one other step that reaches YouTube: a developer runs it by hand, and it never runs in CI. Neither runs in `./gradlew test`. docs/testing.md explains when to run each.
- Emulator tests replace the YouTube layer and the player's media clients with fakes through Hilt, so they never reach YouTube either. docs/testing.md#emulator-tests explains them.
- Screens get screenshot tests in light, dark and large font.
- Screens get screenshot tests in light, dark and large font, and in dynamic color with a fixed wallpaper. docs/testing.md#screenshot-tests explains how to add, record and update them.
- Never delete, skip or weaken a test to make it pass. If a test looks wrong, explain why and ask.

## Commands
Expand All @@ -131,10 +132,13 @@ Run these from the repository root. The build needs JDK 17 installed, because ev
- Check formatting: `./gradlew spotlessCheck`. It checks every Kotlin file and Kotlin build script in the repository, build-logic included, against ktfmt in kotlinlang style.
- Fix formatting: `./gradlew spotlessApply`. It rewrites the same files in place. Run it before you commit.
- Follow the Kotlin style that ktfmt doesn't decide, from [Android's Kotlin style guide](https://developer.android.com/kotlin/style-guide#braces) and [Kotlin's coding conventions](https://kotlinlang.org/docs/coding-conventions.html#loops). Every for, while and do has braces, even on one line. An if, used as a statement or an expression, skips braces only when all of it fits on one line and it has at most one else, such as `if (x) return` or `if (done) finish() else retry()`. A when branch skips them when its arrow and its whole body fit on one line, even when ktfmt wraps its conditions onto the lines above. The guide shows no branch whose conditions span lines, so that part is Dewfall's own reading. In main code, prefer for loops to forEach, unless the receiver is nullable or forEach is part of a longer call chain. Tests may use forEach.
- Run detekt: `./gradlew detekt`. It checks the Kotlin code in src/main, src/test and src/androidTest of every module, and the code in build-logic, without type resolution. Any finding fails the build. Reports go to build/reports/detekt/ in each project.
- Run Android Lint: `./gradlew lint`. It checks every module, with Dewfall's own checks from `:lint-rules` on main and test sources of every module of the app, and writes a report to build/reports/ in each of them. Any warning fails the build. In the app's plain Kotlin/JVM modules it also runs Animal Sniffer, which checks the code against the Android API at minSdk 29, because lint's own API check skips those modules. The lint checks' own tests run with `./gradlew :lint-rules:test`, which `./gradlew test` includes.
- Run detekt: `./gradlew detekt`. It checks the Kotlin code in src/main, src/test and src/androidTest of every module, and in src/screenshotTest of the modules with screenshot tests, and the code in build-logic, without type resolution. Any finding fails the build. Reports go to build/reports/detekt/ in each project.
- Run Android Lint: `./gradlew lint`. It checks every module, with Dewfall's own checks from `:lint-rules` on main and test sources of every module of the app, but not on src/screenshotTest, which it can't read, and writes a report to build/reports/ in each of them. Any warning fails the build. In the app's plain Kotlin/JVM modules it also runs Animal Sniffer, which checks the code against the Android API at minSdk 29, because lint's own API check skips those modules. The lint checks' own tests run with `./gradlew :lint-rules:test`, which `./gradlew test` includes.
- Run the pre-push gate: `python3 scripts/pre_push_gate.py`. It needs Python 3.9 or later, with no packages beyond its standard library. macOS has Python 3.9 with Xcode's Command Line Tools. `--no-build` skips the build for a quick look, and the gate then ends INCOMPLETE or FAIL, never PASS.
- Run every check that the pull request workflow runs: `./gradlew spotlessCheck detekt lint test assembleDebug`. The workflow is .github/workflows/pull-request.yml. It adds `--continue`, so one run reports every failing check, and `-Pandroid.builder.sdkDownload=false`, so a missing SDK package fails the build instead of being downloaded. After the build, the workflow fails if the build changed or added files in core/database/schemas/, so commit the schema files it writes.
- Run the screenshot tests: `./gradlew testDebugScreenshotTestDefaultTestSuite`. They render each screen's previews on the JVM and compare them with the reference images. The report goes to build/reports/tests/testDebugScreenshotTestDefaultTestSuite/ in the module. `./gradlew test` doesn't run them.
- Record the screenshot tests' reference images again: `./gradlew updateDebugScreenshotTestDefaultTestSuite`, after a change to a screen that you meant. Look at every changed image before you commit it, as docs/testing.md#screenshot-tests says.
- Check the screenshot test folders: `python3 scripts/scan_screenshot_tests.py`. It checks that they hold only one-call wrappers and reference images with no text in them.
- Run every check that the pull request workflow runs: `./gradlew spotlessCheck detekt lint test testDebugScreenshotTestDefaultTestSuite assembleDebug`, then `python3 scripts/scan_screenshot_tests.py`. The workflow is .github/workflows/pull-request.yml. It adds `--continue`, so one run reports every failing check, and `-Pandroid.builder.sdkDownload=false`, so a missing SDK package fails the build instead of being downloaded. After the build, the workflow fails if the build changed or added files in core/database/schemas/, so commit the schema files it writes.
- Record the saved YouTube responses again: `./gradlew :core:youtube:recordYouTubeResponses`. It sends requests to YouTube, so run it only when docs/testing.md says to. `-PyoutubeSets=SEARCH_NASA,UPLOADS_NASA` records only the sets it names. If none of them names the machine's address and the network's country, the recorder also makes VIDEO_BIG_BUCK_BUNNY's call to learn them, and writes nothing of it.
- Open the YouTube layer's debug screen: install a debug build with `./gradlew :app:installDebug`, then open "Dewfall debug" in the launcher. docs/testing.md says what to check, and how to check that release builds leave the screen out.
- Run the live YouTube check by hand: `./gradlew :core:youtube:liveYouTubeCheck`. It sends requests to YouTube and googlevideo.com, so run it only when docs/testing.md says to. It logs its results and writes them to core/youtube/build/live-youtube-check/results.txt, and files no issue. To run the daily workflow now instead: `gh workflow run daily-youtube-check.yml`.
Expand Down
Loading