/coverage-explore
Project context
AltTab follows the Humble Object pattern: logic lives in dependency-free decision kernels
(SelectionResolver.swift, SearchModeResolver.swift, the *Testable.swift files) compiled into the
unit-tests target and tested in isolation; the AppKit layer (windows, views, event taps) is kept thin
and is deliberately not unit-tested. So coverage is meaningful per kernel / per feature-source —
those should trend to ~100%, every decision branch exercised — and an aggregate app-wide % is not a
goal.
Coverage is documentation here, not a build artifact. The only stored coverage is:
- the per-feature badge (
> **Line coverage:** …) atop each *Specs.md, and
- the root
src/coverage.md table.
There is intentionally nothing else: no lcov, no HTML, no committed .xcresult, and coverage is
not gathered on routine runs (scripts/run_tests.sh, CI, or Xcode) — only when this skill runs it.
(Coverage isn't usefully viewable in IntelliJ, so there's no IDE-integration artifact to maintain.)
Workflow
Measure into a throwaway bundle (then delete it — store nothing technical):
rm -rf /tmp/altcov.xcresult
set -o pipefail && xcodebuild test \
-project alt-tab-macos.xcodeproj -scheme Test -configuration Release \
-enableCodeCoverage YES -resultBundlePath /tmp/altcov.xcresult | scripts/xcbeautify
If the build is red, stop and report — coverage on a failing suite is meaningless.
Parse xcrun xccov view --report --json /tmp/altcov.xcresult. Each targets[].files[] has
path, lineCoverage, coveredLines, executableLines, functions[]. For line-by-line counts of
one file while investigating a gap: xcrun xccov view --file <abs-path> /tmp/altcov.xcresult.
Refresh src/coverage.md. Rewrite the table with every src/ file (excluding *Tests.swift)
that the test target compiles, sorted worst-coverage-first, as | NN% (cov/exec) | \path` |`.
Keep the header note explaining the Humble-Object scope and that this + the badges are the only
stored coverage. Update the "updated" date.
Offer to refresh the per-spec badges. For each <Base>Specs.md whose <Base>.swift (or kernel)
is in the report, propose updating its > **Line coverage:** … line with the new % + today's date.
Ask first; only apply the ones the user accepts. Keep honest notes where a file is intentionally
partial (e.g. PreferencesMigrations.swift).
Rank gaps & suggest tests. For kernels below 100%, list the uncovered functions/regions, map each
to the behavior it represents (read the source), and write ready-to-paste additions: a
- **testGroupScenario** — … spec line + a short XCTest stub in that suite's builder style. Don't add
tests automatically unless asked.
Clean up: rm -rf /tmp/altcov.xcresult. Leave no technical coverage files in the tree.
Reporting
- Headline: a small ascending table of kernel
lineCoverage, and the delta vs the previous src/coverage.md.
- Ranked gap list: file → uncovered function/branch → the behavior it represents.
- Suggested scenarios (spec lines + test stubs) for the top gaps.
- State exactly what was rewritten (
src/coverage.md, which badges). Flag files that are partial by
design (AppKit glue, excluded migrations) so a low number isn't mistaken for a problem.
1---2name: coverage-explore3description: Measure AltTab test coverage and record it as documentation. Runs the Test scheme with coverage into a throwaway result bundle, parses the per-file/region report, refreshes the per-feature badge atop each `*Specs.md` and the root `src/coverage.md` table, then suggests the highest-value missing tests. These two markdown outputs are the ONLY stored coverage — no lcov/html/xcresult is kept, and routine test runs don't gather coverage. Use to refresh coverage docs, find untested kernel branches, or decide what to test next.4---56# /coverage-explore78## Project context910AltTab follows the **Humble Object** pattern: logic lives in dependency-free **decision kernels**11(`SelectionResolver.swift`, `SearchModeResolver.swift`, the `*Testable.swift` files) compiled into the12`unit-tests` target and tested in isolation; the AppKit layer (windows, views, event taps) is kept thin13and is deliberately *not* unit-tested. So coverage is meaningful **per kernel / per feature-source** —14those should trend to ~100%, every decision branch exercised — and an aggregate app-wide % is not a15goal.1617**Coverage is documentation here, not a build artifact.** The only stored coverage is:181. the per-feature badge (`> **Line coverage:** …`) atop each `*Specs.md`, and192. the root **`src/coverage.md`** table.2021There is intentionally **nothing else**: no lcov, no HTML, no committed `.xcresult`, and coverage is22**not** gathered on routine runs (`scripts/run_tests.sh`, CI, or Xcode) — only when this skill runs it.23(Coverage isn't usefully viewable in IntelliJ, so there's no IDE-integration artifact to maintain.)2425## Workflow26271. **Measure into a throwaway bundle** (then delete it — store nothing technical):28 ```sh29 rm -rf /tmp/altcov.xcresult30 set -o pipefail && xcodebuild test \31 -project alt-tab-macos.xcodeproj -scheme Test -configuration Release \32 -enableCodeCoverage YES -resultBundlePath /tmp/altcov.xcresult | scripts/xcbeautify33 ```34 If the build is red, stop and report — coverage on a failing suite is meaningless.35362. **Parse** `xcrun xccov view --report --json /tmp/altcov.xcresult`. Each `targets[].files[]` has37 `path`, `lineCoverage`, `coveredLines`, `executableLines`, `functions[]`. For line-by-line counts of38 one file while investigating a gap: `xcrun xccov view --file <abs-path> /tmp/altcov.xcresult`.39403. **Refresh `src/coverage.md`.** Rewrite the table with every `src/` file (excluding `*Tests.swift`)41 that the test target compiles, sorted worst-coverage-first, as `| NN% (cov/exec) | \`path\` |`.42 Keep the header note explaining the Humble-Object scope and that this + the badges are the only43 stored coverage. Update the "updated" date.44454. **Offer to refresh the per-spec badges.** For each `<Base>Specs.md` whose `<Base>.swift` (or kernel)46 is in the report, propose updating its `> **Line coverage:** …` line with the new % + today's date.47 Ask first; only apply the ones the user accepts. Keep honest notes where a file is intentionally48 partial (e.g. `PreferencesMigrations.swift`).49505. **Rank gaps & suggest tests.** For kernels below 100%, list the uncovered functions/regions, map each51 to the behavior it represents (read the source), and write ready-to-paste additions: a52 `- **testGroupScenario** — …` spec line + a short XCTest stub in that suite's builder style. Don't add53 tests automatically unless asked.54556. **Clean up:** `rm -rf /tmp/altcov.xcresult`. Leave no technical coverage files in the tree.5657## Reporting5859- Headline: a small ascending table of kernel `lineCoverage`, and the delta vs the previous `src/coverage.md`.60- Ranked gap list: file → uncovered function/branch → the behavior it represents.61- Suggested scenarios (spec lines + test stubs) for the top gaps.62- State exactly what was rewritten (`src/coverage.md`, which badges). Flag files that are partial *by63 design* (AppKit glue, excluded migrations) so a low number isn't mistaken for a problem.
lwouis