Generate FjordIcons from the union of per-app usage lists (GRD-490) #2

Merged
stephen merged 1 commit from stephen/grd-490-icon-union into main 2026-11-19 02:21:03 +00:00
Owner

GRD-490. The kit's FjordIcons was the subset of upstream fjord-icons that fjord-ios uses. It is now generated from the union of the per-app usage lists, so a second app adds its list instead of vendoring its own icons.

  • Inputs. Config/icons-usage/<app>.json per consuming app (fjord-ios.json moved here from fjord-ios's Config/fjord-icons.json, unchanged) and Config/fjord-icons-revision (the pinned upstream commit, moved from fjord-ios).
  • Generator. Scripts/update-icons.sh ../fjord-icons merges the lists (Scripts/icons_union.py: sorted, deduplicated, a concept key such as utility/gear covers its sized keys), runs the upstream scripts/package_usage.py at the pinned commit, and writes Sources/FjordIcons and manifest.json. Upstream fails on an unknown key, which catches a typo in a list.
  • Reproduction. Run against upstream f3c80edf with only the fjord-ios list, the generated Sources/FjordIcons is byte for byte what 0.1.0 shipped. manifest.json changes in one field: app is now fjord-apple-kit instead of fjord-ios. This also settles the layout the fjord-ios script only guessed at: dist/<app>/swiftui/Sources/FjordIcons plus dist/<app>/manifest.json.
  • CI. A Linux job (Icon usage lists, no Mac queued) runs the union tests and Scripts/check_icons_usage.py: every listed icon is carried, the kit carries nothing unlisted, and manifest.json, FjordIconKey.swift and the asset catalog agree.
  • Grid. gridios-cl uses SF Symbols only for now, so there is no Grid list yet. Adding one is Config/icons-usage/<slug>.json plus a regenerate (README, Icons section).
  • Next. A small fjord-ios PR deletes its now-unused Config/fjord-icons.json, Config/fjord-icons-revision and Scripts/update-fjord-icons.sh and updates the docs.

Known edge cases (follow-up): CI proves the list, manifest, sources and assets agree with each other, not that they match the pinned upstream byte for byte, so a hand-edited SVG with consistent names passes; recording the upstream revision in the manifest would close that. Not added here.

GRD-490. The kit's `FjordIcons` was the subset of upstream `fjord-icons` that fjord-ios uses. It is now generated from the union of the per-app usage lists, so a second app adds its list instead of vendoring its own icons. - **Inputs.** `Config/icons-usage/<app>.json` per consuming app (`fjord-ios.json` moved here from fjord-ios's `Config/fjord-icons.json`, unchanged) and `Config/fjord-icons-revision` (the pinned upstream commit, moved from fjord-ios). - **Generator.** `Scripts/update-icons.sh ../fjord-icons` merges the lists (`Scripts/icons_union.py`: sorted, deduplicated, a concept key such as `utility/gear` covers its sized keys), runs the upstream `scripts/package_usage.py` at the pinned commit, and writes `Sources/FjordIcons` and `manifest.json`. Upstream fails on an unknown key, which catches a typo in a list. - **Reproduction.** Run against upstream `f3c80edf` with only the fjord-ios list, the generated `Sources/FjordIcons` is byte for byte what 0.1.0 shipped. `manifest.json` changes in one field: `app` is now `fjord-apple-kit` instead of `fjord-ios`. This also settles the layout the fjord-ios script only guessed at: `dist/<app>/swiftui/Sources/FjordIcons` plus `dist/<app>/manifest.json`. - **CI.** A Linux job (`Icon usage lists`, no Mac queued) runs the union tests and `Scripts/check_icons_usage.py`: every listed icon is carried, the kit carries nothing unlisted, and `manifest.json`, `FjordIconKey.swift` and the asset catalog agree. - **Grid.** gridios-cl uses SF Symbols only for now, so there is no Grid list yet. Adding one is `Config/icons-usage/<slug>.json` plus a regenerate (README, Icons section). - **Next.** A small fjord-ios PR deletes its now-unused `Config/fjord-icons.json`, `Config/fjord-icons-revision` and `Scripts/update-fjord-icons.sh` and updates the docs. Known edge cases (follow-up): CI proves the list, manifest, sources and assets agree with each other, not that they match the pinned upstream byte for byte, so a hand-edited SVG with consistent names passes; recording the upstream revision in the manifest would close that. Not added here.
Generate FjordIcons from the union of per-app usage lists (GRD-490)
All checks were successful
CI / Icon usage lists (pull_request) Successful in 16s
CI / Build and test (iOS Simulator) (pull_request) Successful in 1m27s
3ecee05f22
Each consuming app owns Config/icons-usage/<app>.json. Scripts/update-icons.sh
merges them (Scripts/icons_union.py), runs fjord-icons' package_usage.py at the
commit in Config/fjord-icons-revision, and writes Sources/FjordIcons and
manifest.json. Regenerating with only the fjord-ios list reproduces the
committed sources byte for byte; manifest.json changes only its app field.

CI gains a Linux job that runs the union tests and fails when a list names an
icon the kit does not carry or the kit carries one no list names.
gerri approved these changes 2026-11-19 02:20:29 +00:00
gerri left a comment

Automated Codex review (read-only) of head 3ecee05f22.

  • Low .swiftformat:1, Scripts/update-icons.sh:39. Invariant: copy and behavior match (standards 11), and generation is reproducible. The PR adds a repo-wide .swiftformat that the body never mentions. The generated Swift is only byte-identical to 0.1.0 if swiftformat ran.

    • Failure: update-icons.sh only warns and exits 0 when swiftformat is missing. A contributor without it commits unformatted FjordIconKey.swift and similar files. check_icons_usage.py only regex-matches the case lines, so CI stays green and formatting drift lands in the kit.
    • Fix: mention .swiftformat in the body. Fail the script, or add a flag to opt out, when swiftformat is absent. Alternatively have the CI check ignore formatting explicitly.
  • Low (process) PR body. The body has no "Failure paths" or "Fix scope" section (standards header, items 14 and 18). Two failure paths are worth stating:

    • update-icons.sh can stop partway: rsync --delete succeeds and cp manifest.json then fails. CI catches the resulting disagreement.
    • The pinned-revision check is not run in CI.
  • Low (deferral, unchanged) The body already defers that CI proves only internal agreement and not a byte match with upstream. This diff gives no new evidence, so I am not re-raising it as blocking.

I did not run check_icons_usage.py or the union tests, because the sandbox denied Python execution. I read the code instead. The manifest uses <concept>/16 and <concept>/24 keys (for example ci/passed/16), which matches expand(). update-icons.sh checks the pinned revision and a clean upstream tree before generating. I found no correctness, security or data-loss problem on the normal path.

BLOCKING: 0


Reviewed head 3ecee05f22 at 2026-11-19T02:20:28Z by claude -p, read-only tools (Codex unavailable).

Automated Codex review (read-only) of head 3ecee05f22dbbb135fc55e866712acf9c57709cd. - **Low** `.swiftformat:1`, `Scripts/update-icons.sh:39`. Invariant: copy and behavior match (standards 11), and generation is reproducible. The PR adds a repo-wide `.swiftformat` that the body never mentions. The generated Swift is only byte-identical to 0.1.0 if `swiftformat` ran. - Failure: `update-icons.sh` only warns and exits 0 when `swiftformat` is missing. A contributor without it commits unformatted `FjordIconKey.swift` and similar files. `check_icons_usage.py` only regex-matches the `case` lines, so CI stays green and formatting drift lands in the kit. - Fix: mention `.swiftformat` in the body. Fail the script, or add a flag to opt out, when `swiftformat` is absent. Alternatively have the CI check ignore formatting explicitly. - **Low** (process) PR body. The body has no "Failure paths" or "Fix scope" section (standards header, items 14 and 18). Two failure paths are worth stating: - `update-icons.sh` can stop partway: `rsync --delete` succeeds and `cp manifest.json` then fails. CI catches the resulting disagreement. - The pinned-revision check is not run in CI. - **Low** (deferral, unchanged) The body already defers that CI proves only internal agreement and not a byte match with upstream. This diff gives no new evidence, so I am not re-raising it as blocking. I did not run `check_icons_usage.py` or the union tests, because the sandbox denied Python execution. I read the code instead. The manifest uses `<concept>/16` and `<concept>/24` keys (for example `ci/passed/16`), which matches `expand()`. `update-icons.sh` checks the pinned revision and a clean upstream tree before generating. I found no correctness, security or data-loss problem on the normal path. BLOCKING: 0 --- Reviewed head 3ecee05f22dbbb135fc55e866712acf9c57709cd at 2026-11-19T02:20:28Z by claude -p, read-only tools (Codex unavailable).
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
rasterstate/fjord-apple-kit!2
No description provided.