Add a Settings About page, with attribution in a new CreditKit module

[kyleve]

Summary

Adds an About block at the bottom of Settings covering the things the app couldn't previously answer: which build is running, what third-party work it's built with, and where its bundled region boundaries came from.

The app had no build metadata at all — version and build number were Tuist's .extendingDefault values and nothing recorded the commit — so this also adds the plumbing to stamp it.

Credits are vended by the module that owns the thing being credited, and the screen only renders them:

• WhereCore.BuildInfo — the version keys plus the commit stamped into the built Info.plist.
• CreditKit.SoftwareCredit — third-party software and its license notice, in a new Shared module (see below).
• RegionKit.RegionDataSource — the origin, license, and fidelity of the bundled GeoJSON.

Attribution: CreditKit reports, the app ships the report

Attribution started out in WhereCore, which was wrong: WhereCore is just the only module that happens to link an external package today, and the edge pointed the wrong way — Broadway, Periscope and friends are documented as portable and app-agnostic, so none of them could have vended a credit without depending on app code.

The first pass moved it to a Shared module, but that module then was the Where app's credits wearing a library's clothes: a credits.json and five vendored notices in its own resource bundle, a generator hardcoding this repo's paths, and tests asserting ZIPFoundation was linked. A second app could not have used any of it.

Shared/CreditKit now owns the format and the tooling and nothing else. An app declares its own inputs, ./attribution runs the report, and the result lands in that app's resources — for Where, Where/Where/Resources/attribution.json:

{
  "output": "Where/Where/Resources/attribution.json",
  "sources": [
    { "type": "swiftPackageManager", "kind": "library",
      "manifest": "Package.swift", "resolved": "Package.resolved" },
    { "type": "agentSkills", "kind": "developmentTool",
      "manifest": ".agents/external-skills.json" }
  ]
}

Dropping the resource bundle dropped the last dependency too: CreditKit is Foundation-only and throws rather than logs, leaving the caller to decide what a missing report means. Notices are inlined into the report, so one decode yields everything needed and the missing-file path stops existing.

The report is still derived, which is what stops it going stale: credits come from packages a target actually links via .product(name:package:), pinned by Package.resolved, with each notice read at the pinned revision. A new dependency is credited wherever it lands, and a package resolved only for tooling (BumperBowling, swift-syntax) correctly isn't. The generated notices came out byte-identical to the ones previously vendored by hand, and re-running produces no diff.

Kind is derived too, not declared. Linking is not shipping: SnapshotKitTesting links the snapshot-testing engine and the accessibility parser, and crediting those as libraries would tell a reader their binary contains a test harness. The config's shippedFrom names the package targets the app and its extensions link (WhereUI, WhereIntents); the generator walks the manifest's target graph from there, so a package inside that closure is a library and any other linked package is a developmentTool — same bucket as the vendored agent skills, credited because the repo depends on them rather than because they reach a device. shippedFrom is the only value set by hand.

WhereCore.AppAttribution reads the report from Bundle.main beside BuildInfo, and splits the two failures they share: a bundle with no report is legitimate (only the app target ships one), while a report that won't decode is a corrupt resource and faults. AppAttribution.main caches the decode for the process — About takes it as a default argument, and Swift re-evaluates those on every init, so reading eagerly re-read and re-decoded the file on every SwiftUI body pass; current(bundle:) remains for tests and other bundles.

About says something in every empty case, keyed on the section rather than on the report: "no report at all" and "nothing of this kind" describe different builds, and a header and footer over no rows describes neither. The generator also refuses to write a report with duplicate credit names (SoftwareCredit is Identifiable by name, and a library's name is its repo basename, so two orgs can collide) or an unrecognized kind, which would otherwise generate and commit cleanly and then fail to decode inside the app.

The build stamp

A post-build script phase on the Where target writes WhereGitSHA / WhereGitStatus into the built product's plist. Post (not pre) so it edits the plist after "Process Info.plist" writes it and before signing seals the bundle, and basedOnDependencyAnalysis: false so an unchanged source tree can't ship the previous commit's SHA. A checkout without git metadata stamps unknown rather than failing the build, and unstamped bundles (RegionViewer, StuffTestHost, the extensions) report no commit rather than a placeholder.

Content call worth a look

Canada and the EU have no external source and no license — RegionKit/README.md calls them coarse placeholders unfit for a real residency audit. The page says that plainly ("Approximate outline drawn for this app — coarse, and not authoritative") rather than omitting them. Say if you'd rather word it differently or leave them off.

Test plan

• ./swiftformat --lint, ./xcstrings --lint
• swift run bumper config ., swift run bumper test ., swift run bumper lint . — no violations
• tuist test CreditKitTests, WhereCoreTests, WhereTests, RegionKitTests, WhereUITests — all green, including the new AttributionManifestTests, AppAttributionTests, BuildInfoTests, RegionDataSourceTests, AboutSettingsViewTests, LicenseViewTests
• ./attribution is idempotent — a second run rewrites the same bytes
• Built and installed the app: the stamp lands in Where.app/Info.plist (WhereGitSHA 778d7e8523d1, WhereGitStatus dirty) and re-runs on every build
• Rendered both screens in the simulator
• Full Stuff-iOS-Tests scheme — 251 suites green after merging main (the earlier run's four StuffTestHost bundle kills were simulator contention on this machine; Give every checkout a simulator of its own #141's per-checkout simulator cleared it)
• tuist test WhereUISnapshotTests — 31 suites green on a clean re-run after recording

Snapshots

main's snapshot bundle (#101) landed after this branch wrote the About screen, so merging the two invalidated 9 of the 11 SettingsViewSnapshotTests references — the Settings list grew an About row. Those are re-recorded, and AboutSettingsView / LicenseView now have the SnapshotProviding conformance and suite the module convention asks for. The About matrix is built around absence, since the shipping build is the only one both stamped and attributed: a full report, a dirty tree, no report at all, and a report crediting only one kind. That last case pins the empty-section fix as an image, which suits a failure that was purely visual.

Recording caught a stale string: LicenseView's empty-notice case still said "This license text couldn't be loaded from the app bundle", describing the old architecture where notices were separate bundle resources. Nothing is loaded now — the notice is inlined — so it reads "This credit's report entry carries no license text".

Drift guards

• RegionDataSourceTests fails if a catalog region is covered by zero or two sources, so a regenerated catalog can't ship uncredited geometry. Coverage derives from the us- prefix the generator mints plus an explicit id list — deliberately not an "everything else" bucket that would quietly mis-credit a new region.
• ./attribution --check re-derives the expected report from Package.swift, Package.resolved, and the skills manifest and diffs it against the committed one, gated in CI. It makes no network calls — notices are read at the pinned revision, so a matching revision means matching text — and runs in under a second. This replaced a guard that didn't work. AppAttributionTests had compared the report to a hardcoded list of names, which a stale report satisfies exactly as well as a fresh one; it passed on this branch while the committed report was missing two packages the main merge had added. A test bundle can't read Package.swift, so it can't do this job at all. It now asserts only what the shipping bundle can answer: present, decodable, notices inline, unique names, both kinds populated.
• AboutSettingsViewTests.separatesLinkedLibrariesFromDevelopmentTools fails if either section would render empty or lose its heading.

Follow-up filed

Root TODOs.md: a LogSession names only a version and build number, both pinned in the manifest, so every developer build logs as v1.0 (1). PeriscopeCore sits below WhereCore and can't read BuildInfo, so carrying the commit into log sessions needs a seam rather than a direct adoption.

Made with Cursor

[kyleve]

Is placing this in WhereCore correct? Attributions aren't unique to WhereCore, they can come in anywhere, right?

[kyleve]

Posted by an AI agent on $USER's behalf.

You're right, and the doc comment was overstating its case — it said "WhereCore owns this because WhereCore is what pulls the dependencies in," which reads like a principle but was really a coincidence. WhereCore just happens to be the only module linking an external runtime package today (ZIPFoundation; BumperBowling and swift-syntax are dev/CI-only and never reach the binary).

The concrete problem: the dependency edge pointed the wrong way. Broadway, Periscope, LifecycleKit and friends are documented as portable and app-agnostic, so if one of them picked up a package it could not vend a credit without depending on app code.

Fixed in f6fe23b by giving attribution its own Shared leaf module, CreditKit, that anything may depend on.

The other half of your question — "they can come in anywhere" — turned out to be the more interesting one, because placement alone doesn't solve it. Wherever the type lives, a hand-kept list silently goes stale when a different module adds a package. So the manifest is now generated instead: Shared/CreditKit/Tools/generate-credits.rb derives the credits from packages a target actually links via .product(name:package:), pinned by Package.resolved, and fetches each notice at the pinned revision. A new dependency gets credited wherever it lands, and a package resolved only for tooling correctly doesn't.

Worth noting as validation: the generated ZIPFoundation notice came out byte-identical to the one I'd vendored by hand from the pinned checkout.

BuildInfo stays in WhereCore — that's build identity, not attribution.

[kyleve]

Posted by an AI agent on $USER's behalf.

Follow-up in 149c17c, after your point about the shape. You were right that the first pass didn't finish the job: I'd moved attribution into a Shared module, but that module was the Where app's credits wearing a library's clothes — a credits.json and five vendored notices in its own Bundle.module, a generator hardcoding this repo's paths, and tests asserting ZIPFoundation was linked. A library making claims about its consumer's dependency graph. A second app couldn't have used any of it.

CreditKit now owns the format and the tooling and nothing else:

• An app declares its inputs in an attribution-sources.json; ./attribution runs the report; the result lands in that app's resources (Where/Where/Resources/attribution.json). A report describes one app's dependency graph, so it's the app's data.
• Notices are inlined in the report rather than sidecar files, so one decode yields everything and the missing-file failure path stops existing.
• Dropping the resource bundle dropped the last dependency: CreditKit is Foundation-only now, and throws instead of logging, because only the caller knows whether a missing report is a problem.
• WhereCore.AppAttribution makes that call for Where, splitting the two cases the way BuildInfo splits stamped from unstamped: no report is legitimate (only the app target ships one), a report that won't decode is a corrupt resource and faults.
• The app-specific assertions moved to AppAttributionTests in the Where app's own test bundle — the one hosted by Where.app, so Bundle.main is the shipping bundle.

Two checks worth reporting: the generated notices are byte-identical to the ones previously vendored by hand, and re-running the report produces no diff.

[kyleve]

Thinking out loud, we should also integrate with the sync-agents tool to credit the external skills we've added.

[kyleve]

Posted by an AI agent on $USER's behalf.

Done in f6fe23b — and there was a real gap here, not just a nice-to-have. All four external skills are MIT (all from twostraws), and sync-agents clones the repo then copies only the skill subdirectory, so the upstream root LICENSE gets dropped on the floor. We were making copies on every dev machine and cloud agent with none of the notices attached.

Rather than a second mechanism, the same generate-credits.rb reads .agents/external-skills.json and vendors each skill's notice at its pinned ref, alongside the library credits.

One thing I did push back on slightly. I kept them visually distinct rather than folding them into the existing "Open Source" list: SoftwareCredit.Kind is .library (compiled into the binary) or .developmentTool, and About renders a separate "Development Tools" section whose footer says outright that they aren't part of the app on your device. A skill is credited because the repo copies it, not because a user is running it, and one merged list would have credited honestly while describing the app falsely. The Kind distinction is enforced as an invariant in CreditKit/AGENTS.md so a future UI can't quietly collapse it.

Follow-on for whenever you next touch it: ./sync-agents --update changes the pinned refs, so the credits script needs a re-run after it. That's documented in the root AGENTS.md and in the sync-agents section, but it's a manual step — if it proves easy to forget, having sync-agents --update invoke the generator itself would be the obvious next move.