Add docs/INVESTIGATING.md for diagnosing baseline entries - #43
Conversation
Capture the procedural knowledge needed to act on `# conflict` and `# override` entries — locating AARs in the Gradle cache, mapping the baseline key back to a path inside the artifact (with a per-scan table including the nine-patch and classes-jar gotchas), diffing bytes, tracing the dependency graph via `dependencyInsight`, mapping to runtime usage, and classifying vendor-intentional layering vs real risk. Also link the guide from README (between Baseline Files and Requirements) and from CLAUDE.md so AI agents acting on baseline output have a canonical playbook instead of re-deriving the workflow each time. Closes #42
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive investigation guide in docs/INVESTIGATING.md to help users diagnose and classify #conflict and #override entries in Highlander baselines, with corresponding updates to README.md and CLAUDE.md. A review comment identifies that the provided Python script for diffing files does not account for nested JARs in the classes scan, which would lead to errors, and suggests a clarification in the code comments.
| "<absolute path to first AAR>", | ||
| "<absolute path to second AAR>", | ||
| ] | ||
| inner = "res/layout/exo_player_view.xml" # adjust per entry |
There was a problem hiding this comment.
The Python script provided below does not handle nested ZIP files. For the classes scan type, the target .class file is located inside classes.jar, which is itself a member of the AAR. Using a class path as the inner variable will result in a KeyError. It is recommended to clarify that for classes, users should either diff the entire classes.jar or use a more complex script to extract from the nested JAR.
| inner = "res/layout/exo_player_view.xml" # adjust per entry | |
| inner = "res/layout/exo_player_view.xml" # adjust per entry (e.g. "classes.jar" for classes) |
1 participant
Summary
Adds
docs/INVESTIGATING.md— a step-by-step playbook for diagnosing each# conflictand# overrideentry that survives in the baseline. WithskipContentIdenticalDuplicates = true(default since 0.0.5), the file only contains entries that genuinely need triage; the missing piece was the procedural knowledge for what to do with each one.The guide implements the 6-step workflow proposed in #42 (read coordinates → locate AARs → extract & diff → trace deps → map runtime usage → classify) and adds:
resources/assets/nativeLibs/classes/valuesResources), including the nine-patch case where the baseline strips.9from the key but the file inside the AAR keeps it.valuesResources— entries cannot be diffed by zip extraction because AAR packagers merge values into combined XML; usesaapt2 dump resourcesinstead.zipfilesnippet to extract and SHA-256 two AARs side-by-side.Pointers added so the doc is discoverable:
README.md— new "Investigating duplicates" section between Baseline Files and Requirements.CLAUDE.md— new "Investigating Baseline Output" section so AI agents acting on baseline diffs reach the playbook directly.Closes #42
Test plan
Docs-only change; nothing to run. Manual verification:
ResourceScanner.kt,AssetScanner.kt,NativeLibScanner.kt,ClassScanner.kt,ValuesResourceScanner.kt— all<key, file>mappings match the scanners' actual key derivation.docs/INVESTIGATING.md→../README.md,../CLAUDE.md,setup-guide.md.txt; README →docs/INVESTIGATING.md) resolve correctly under GitHub's renderer.