diff --git a/docs/audits/2026-11-15-explorer-audit.md b/docs/audits/2026-11-15-explorer-audit.md new file mode 100644 index 0000000..da18fe1 --- /dev/null +++ b/docs/audits/2026-11-15-explorer-audit.md @@ -0,0 +1,61 @@ +# Audit: structure, data correctness, security (15 Nov 2026) + +Scope: everything the November score audits (`2026-11-berekeningen.md`, `2026-11-site-validatie.md`) did not cover: collectors, size attribution, export, WebView boundary, structure. Baseline: `flutter analyze` clean, 1389 tests pass. + +Status per finding: **reproduced** (shown with a run) or **read** (follows from the code; needs a failing test before it is fixed). + +The plans in `docs/superpowers/plans/2026-11-15-*.md` implement this document. IDs below are used there. + +## D — Data correctness + +| ID | Status | Finding | Where | +|---|---|---|---| +| D1 | reproduced (Node) | `__vsv_collect` calls `skip()`, which only exists inside the bootstrap closure. With one dropped resource the whole `resources` section becomes `{ok:false, error:"ReferenceError: skip is not defined"}`. The drop count is lost too, so the page weight is not marked as a lower bound. | `lib/services/collectors/vsv_collect_js.dart:359` | +| D2 | read | Own size lookups treat every `img` as safe to repeat. A cross-origin tracking pixel without Timing-Allow-Origin has no size, so the app sends its own HEAD/GET with the same query. That can double-count pageviews or conversions. | `lib/services/derive/estimate_targets.dart:16` | +| D3 | read | Size matching tier 4 keys on filename + query only (no host, no path): `a.com/x/logo.png` gets the size of `b.com/y/logo.png`. Tier 5 keys on host + last path segment and is shown as measured. | `lib/services/html_service.dart:4507`, `:4560` | +| D4 | read | The HTML document's weight comes from the app's own fetch (own User-Agent, gzip only) and is counted as measured. `PerformanceNavigationTiming` has `transferSize`, `encodedBodySize`, `decodedBodySize`; the collector does not read them. | `lib/services/derive/page_weight.dart:268`, `vsv_collect_js.dart:375` | +| D5 | read | `categorizeResource` falls back to URL substrings: `/lifestyle/api` → CSS, `/subscriptions` → script, anything with `document` → HTML. Video and audio are counted as images, fonts as other. | `lib/services/probe_service.dart:148` | +| D6 | read | The collector lives in the page's own JavaScript world (`window.__vsv_*`, patched `fetch`/`XHR`). A page can fake the data; anti-bot scripts can see the patch. Possibly related to open item O1 (bol.com block page); that link is a hypothesis. | `vsv_collect_js.dart:200` | +| D7 | read | `source/diff.patch` compares line N with line N. One inserted line marks every later line as changed. | `lib/services/inspection_export_service.dart:752` | +| D8 | read | Three definitions of "same site": detection engine (`_sameSite`), Sovereignty (`registrableDomain` with a short suffix list), site-data cleaner. `www.x.nl` and `static.x.nl` are different sites in the engine. | `lib/services/detection/engine.dart:109`, `sovereignty_service.dart:1511` | +| D9 | read | Detection confidence (92/90/88/82/72/40) reads like a percentage but has no basis. Cookie rules: first match wins, not the longest prefix. | `engine.dart:34`, `:222` | +| D10 | read | Only the first resolved IP of a host is used, and for anycast CDNs the GeoLite country is not where the visitor is served. Nothing marks that. | `sovereignty_service.dart:1408`, `:822` | + +## S — Security and privacy + +| ID | Finding | Where | +|---|---|---| +| S1 | `PRIVACY.md` says URLs never go to third parties. Hostnames and IPs go to RIPEstat, LibreDNS / Google DNS and DuckDuckGo's icon service, and the app makes its own requests to third-party resource hosts. | `PRIVACY.md` | +| S2 | Iframes post their resource URLs to the top frame with `postMessage(…, '*')`. The embedding page can read what a cross-origin frame loaded; any frame can inject fake entries. | `vsv_collect_js.dart:136` | +| S3 | Reader view renders Readability output with JavaScript on and no CSP. Readability removes `']), isNull); + expect(frameRelayScript([{'e': []}]), isNull); +}); +// vsv_collect_js_test.dart +test('__vsv_frameIn records frame entries with their origin', () async { + final out = await runCollector(after: "window.__vsv_frameIn({__vsv_frame: 1," + "fo: 'https://ads.test', to: 1, e: [{n: 'https://ads.test/a.js'," + "it: 'script', st: 1, du: 1, tx: 10, enc: 9, dec: 20}], d: []});"); + if (out == null) return markTestSkipped('node not installed'); + expect(out['resources']['observer'].single, + containsPair('fo', 'https://ads.test')); +}); +``` + +- [ ] **Step 2: Run and see them fail** + +Run: `flutter test test/collectors/` +Expected: FAIL. + +- [ ] **Step 3: Implement `frame_relay.dart`, `__vsv_frameIn`, and the bridge-first `flush`** + +Keep the `message` listener as the receiver of the fallback path; it now calls `__vsv_frameIn(ev.data)` after its `ev.source === window` check. + +- [ ] **Step 4: Register `vsvFrame` next to `vsvResources` in `browser_view.dart` and in the headless measurer** + +- [ ] **Step 5: Run the suite, then the real-browser gate** + +Run: `flutter analyze --no-pub && flutter test`, then `validation/run.sh techcrunch` +Expected: PASS; `network/timeline.json` of techcrunch still has entries with `frameOrigin`. If it has none, the bridge does not reach sub-frames on this platform: set `javaScriptHandlersForMainFrameOnly: false` and `javaScriptBridgeForMainFrameOnly: false` in the WebView settings and rerun; if still none, the `postMessage` fallback is what runs and this is noted in the commit message. + +- [ ] **Step 6: Commit** + +```bash +git commit -am "Security: iframes report resources through the bridge, not postMessage" +``` + +--- + +### Task 6: One definition of "same site", from the Public Suffix List (D8) + +**Files:** +- Create: `tool/gen_public_suffix.dart`, `tool/data/public_suffix_list.dat`, `tool/data/PSL_VERSION` +- Create: `lib/utils/public_suffix.g.dart` (generated), `lib/utils/site.dart` +- Create: `assets/licenses/public-suffix-list-LICENSE.txt` (MPL-2.0 text) +- Modify: `pubspec.yaml` (asset), `THIRD_PARTY_NOTICES.md`, the place that registers `open-cookie-database-LICENSE.txt` with `LicenseRegistry` (grep for that filename) +- Modify: `lib/services/detection/engine.dart` (`_sameSite`), `lib/services/sovereignty_service.dart` (`registrableDomain`, `_publicSuffixes`) +- Test: `test/utils/site_test.dart` + +**Interfaces:** +- Produces: `String registrableDomain(String host)` and `bool sameSite(String hostA, String hostB)` in `lib/utils/site.dart`. Hosts are lower-cased; a trailing dot is ignored. An IP address, a single label, or an empty string is returned unchanged; two such hosts are the same site only when equal. +- Produces: `const Set publicSuffixRules`, `publicSuffixWildcards` (the part after `*.`), `publicSuffixExceptions` (the part after `!`) in `public_suffix.g.dart`. ICANN and PRIVATE sections both included. +- Keeps: `SovereigntyService.registrableDomain` as a one-line forwarder. + +- [ ] **Step 1: Pin the list** + +```bash +curl -fsSL https://publicsuffix.org/list/public_suffix_list.dat -o tool/data/public_suffix_list.dat +``` + +Write the download date and the file's `// VERSION:` / `// COMMIT:` header lines into `tool/data/PSL_VERSION`, in the style of `tool/data/OCD_VERSION`. + +- [ ] **Step 2: Write the failing tests** + +```dart +test('registrable domain', () { + expect(registrableDomain('www.example.co.uk'), 'example.co.uk'); + expect(registrableDomain('a.b.rijksoverheid.nl'), 'rijksoverheid.nl'); + expect(registrableDomain('foo.github.io'), 'foo.github.io'); + expect(registrableDomain('x.y.kawasaki.jp'), 'x.y.kawasaki.jp'); // *.kawasaki.jp + expect(registrableDomain('www.city.kawasaki.jp'), 'city.kawasaki.jp'); // !city.kawasaki.jp + expect(registrableDomain('WWW.Example.COM.'), 'example.com'); +}); +test('hosts that are not domains are returned unchanged', () { + for (final h in ['localhost', '192.168.1.1', '[::1]', '']) { + expect(registrableDomain(h), h); + } +}); +test('same site', () { + expect(sameSite('www.x.nl', 'static.x.nl'), isTrue); + expect(sameSite('a.github.io', 'b.github.io'), isFalse); + expect(sameSite('x.nl', 'x.com'), isFalse); + expect(sameSite('', ''), isFalse); +}); +``` + +- [ ] **Step 3: Run and see them fail** + +Run: `flutter test test/utils/site_test.dart` +Expected: FAIL (`site.dart` missing). + +- [ ] **Step 4: Write the generator (model it on `tool/gen_cookie_db.dart`), generate, implement `site.dart`** + +Run: `dart run tool/gen_public_suffix.dart` +Algorithm (publicsuffix.org "Formal algorithm"): the longest matching rule wins; an exception rule beats everything and its suffix is the rule minus its first label; a host with no matching rule uses `*` (its last label). The registrable domain is the suffix plus one label; a host that is itself a suffix is returned unchanged. + +- [ ] **Step 5: Replace the two other definitions** + +`engine.dart`: delete `_sameSite`, import `sameSite`, keep the `pageHost.isNotEmpty` guard at the call sites. `sovereignty_service.dart`: `registrableDomain` forwards; delete `_publicSuffixes` and its helpers. + +- [ ] **Step 6: Run the suite** + +Run: `flutter test` +Expected: PASS. A detection test that relied on `cdn.example.com` being third party to `www.example.com` is wrong by the new definition: change its expectation. + +- [ ] **Step 7: Add the licence asset and notices, commit** + +```bash +git add -A && git commit -m "Fix: one same-site definition, from a pinned Public Suffix List" +``` + +--- + +### Task 7: Never re-request tracking pixels (D2) + +**Files:** +- Modify: `lib/services/derive/estimate_targets.dart` +- Test: `test/derive/estimate_targets_test.dart` + +**Interfaces:** +- Consumes: `sameSite` (Task 6), `externalServicesForUrl(url, pageUrl)` and `Entity.beacons` from `detection/engine.dart`. +- Changes: `bool isEstimableResourceType(String rawType, String url, {String pageUrl = ''})`. `estimateTargetsOf` passes `browser.value.url.toString()`. + +Rules added (any one makes the URL not estimable): +1. Any type: the URL matches a `beacons` pattern of a catalogue entity. +2. Type `img`/`image`: `externalServicesForUrl(url, pageUrl)` contains an entity with `category.isTracking`. +3. Type `img`/`image`, `pageUrl` not empty, host not `sameSite` with the page, the URL has a query, and `ProbeService.resourceTypeFromExtension(url) != 'image'`. + +- [ ] **Step 1: Write the failing tests** + +```dart +const page = 'https://shop.test/'; +test('tracking pixels are never requested again', () { + expect(isEstimableResourceType('img', + 'https://www.facebook.com/tr?id=1&ev=PageView', pageUrl: page), isFalse); + expect(isEstimableResourceType('img', + 'https://px.ads.test/p?uid=9', pageUrl: page), isFalse); +}); +test('ordinary images still are', () { + expect(isEstimableResourceType('img', + 'https://images.cdn.test/a/photo.jpg?w=200', pageUrl: page), isTrue); + expect(isEstimableResourceType('img', + 'https://shop.test/img?id=4', pageUrl: page), isTrue); + expect(isEstimableResourceType('img', + 'https://images.cdn.test/a/slug', pageUrl: page), isTrue); +}); +test('tracker scripts are static files and stay estimable', () { + expect(isEstimableResourceType('script', + 'https://www.googletagmanager.com/gtag/js?id=G-1', pageUrl: page), isTrue); +}); +test('without a page URL the old rules apply', () { + expect(isEstimableResourceType('img', 'https://px.ads.test/p?uid=9'), isTrue); +}); +``` + +- [ ] **Step 2: Run and see them fail** + +Run: `flutter test test/derive/estimate_targets_test.dart` +Expected: FAIL on the first test. + +- [ ] **Step 3: Implement the three rules; rewrite the doc comment of `_estimableTypes` to state them** + +- [ ] **Step 4: Run and see them pass, commit** + +Run: `flutter test test/derive/` +```bash +git commit -am "Fix: size lookups never re-request tracking pixels" +``` + +--- + +### Task 8: Size matching out of HtmlService, without the cross-host match (D3) + +**Files:** +- Modify: `lib/services/derive/resource_matching.dart` +- Modify: `lib/services/html_service.dart` (`_sizeOf` ~4450, `_enrichMetadataWithSizes` ~4473–4720) +- Test: `test/derive/resource_matching_test.dart` + +**Interfaces:** +- Produces: `Map? sizeOfTimelineEntry(Map entry)`: `HtmlService._sizeOf`, moved unchanged. +- Produces: `class ResourceSizeIndex { ResourceSizeIndex(Iterable> timeline); Map? find(String? src); }`. Tiers in order: data URI / inline SVG (own bytes); exact URL; host + path without trailing slash + query; host + path + query without cache-busters (path longer than 3); same host + same last path segment with a measured transfer. The last tier returns the entry's size plus `'estimated': true` and `'variantOf': `. There is no filename-only tier. + +- [ ] **Step 1: Write the failing tests** + +```dart +Map e(String name, int tx) => + {'name': name, 'transfer': tx, 'decoded': tx * 3, 'initiatorType': 'script'}; + +test('the same filename on another host is not a match', () { + final i = ResourceSizeIndex([e('https://b.test/y/logo.png', 900)]); + expect(i.find('https://a.test/x/logo.png'), isNull); +}); +test('the same filename in another directory is not a match for a script', () { + final i = ResourceSizeIndex([e('https://a.test/b/index.js', 900)]); + expect(i.find('https://a.test/a/index.js'), isNull); +}); +test('a size variant of an image is an estimate that names its source', () { + final i = ResourceSizeIndex([ + {...e('https://img.test/w_400/photo-1.jpg', 700), 'initiatorType': 'img'} + ]); + final s = i.find('https://img.test/w_1200/photo-1.jpg')!; + expect(s['transfer'], 700); + expect(s['estimated'], isTrue); + expect(s['variantOf'], 'https://img.test/w_400/photo-1.jpg'); +}); +test('exact and cache-buster matches are not estimates', () { + final i = ResourceSizeIndex([e('https://a.test/app.js?v=2', 500)]); + expect(i.find('https://a.test/app.js?v=1'), {'transfer': 500, 'decoded': 1500}); +}); +test('data URIs are sized by their own bytes', () { + expect(ResourceSizeIndex(const []).find('data:image/gif;base64,AAAA')!['transfer'], 26); +}); +``` + +The second test changes behaviour on purpose: the variant tier only applies when the matched entry is an image (`initiatorType` `img`/`image`, or an image extension). + +- [ ] **Step 2: Run and see them fail** + +Run: `flutter test test/derive/resource_matching_test.dart` +Expected: FAIL (`ResourceSizeIndex` missing). + +- [ ] **Step 3: Implement `ResourceSizeIndex` and move `_sizeOf`** + +- [ ] **Step 4: Shrink `_enrichMetadataWithSizes`** + +Replace the index maps and the `findSize` closure with `final index = ResourceSizeIndex(timeline);` and `index.find`. Replace the three copies of "merge external list into main list" with one loop over `const [('cssLinks', 'externalCssLinks'), ('jsLinks', 'externalJsLinks'), ('iframeLinks', 'externalIframeLinks')]`. Behaviour of the enrichment itself is unchanged. + +- [ ] **Step 5: Run the suite, commit** + +Run: `flutter test` +Expected: PASS. A test that expected a filename-only match now expects no size. +```bash +git commit -am "Fix: no cross-host size matches; size matching moved to derive" +``` + +--- + +### Task 9: Resource type from what the browser says, not from URL substrings (D5) + +**Files:** +- Modify: `lib/services/probe_service.dart` (`categorizeResource`, new `resourceKindFromExtension`) +- Modify: `lib/services/derive/page_weight.dart` (`resourceCategory`, bucket map) +- Modify: `lib/widgets/page_size_view.dart:491` (bucket labels) +- Test: `test/derive/page_weight_test.dart`, `test/probe_service_test.dart` (create if absent) + +**Interfaces:** +- Produces: `static String? ProbeService.resourceKindFromExtension(String url)`: `script`, `style`, `image`, `media`, `font`, `document` or null. Same extension table as `resourceTypeFromExtension`, with `mp4 webm mov m4v ogv mp3 ogg wav m4a aac` as `media`. +- Changes: `resourceCategory(ResourceEntry r, String pageUrl)` returns one of `script style image media font document other`: + +| initiator type | result | +|---|---| +| `img`, `image` | `image` | +| `video`, `audio`, `media`, `track` | `media` | +| `script` | `script` | +| `iframe`, `frame` | `document` | +| `link` | extension kind, else `style` | +| `css` | extension kind, else `other` | +| anything else (`fetch`, `xmlhttprequest`, `beacon`, `other`, empty) | extension kind, else `document` when the URL equals the page URL (with or without trailing slash), else `other` | + +- Changes: `PageWeight.breakdown` keys: `scripts css images media fonts html other thirdPartyFrames`. +- Changes: `ProbeService.categorizeResource` loses every `contains(...)` rule: extension (font → `other`), then page-URL equality → `document`, else `other`. + +- [ ] **Step 1: Write the failing tests** + +```dart +test('an XHR is not a stylesheet because its URL says lifestyle', () { + expect(resourceCategory(res('https://a.test/lifestyle/api', type: 'xmlhttprequest'), + 'https://a.test/'), 'other'); + expect(resourceCategory(res('https://a.test/subscriptions', type: 'fetch'), + 'https://a.test/'), 'other'); +}); +test('fonts and media have their own kind', () { + expect(resourceCategory(res('https://a.test/f.woff2', type: 'css'), ''), 'font'); + expect(resourceCategory(res('https://a.test/v.mp4', type: 'video'), ''), 'media'); +}); +test('a link without an extension is a stylesheet', () { + expect(resourceCategory( + res('https://fonts.googleapis.com/css2?family=Inter', type: 'link'), ''), 'style'); +}); +test('the breakdown has fonts and media buckets', () { + // snapshot with one woff2 (css, tx 100) and one mp4 (video, tx 900) + // expect w.breakdown['fonts']!.transfer == 100 + // expect w.breakdown['media']!.transfer == 900 + // expect w.breakdown['images']!.count == 0 +}); +``` + +- [ ] **Step 2: Run and see them fail** + +Run: `flutter test test/derive/page_weight_test.dart` +Expected: FAIL. + +- [ ] **Step 3: Implement; in `page_size_view.dart` rename `'Images/Media'` to `'Images'` and add `('media', 'Video & audio')` and `('fonts', 'Fonts')` after it** + +In `derivePageWeightOf`, "is image" for the decoded-size rule stays `category == 'image'`; media has no decoded expectation either (treat like image for `decodedMissingCount`). + +- [ ] **Step 4: Run the suite, commit** + +Run: `flutter test` +Expected: PASS. Tests that listed the six old bucket keys now list eight. +```bash +git commit -am "Fix: resource type from the initiator, fonts and media get their own bucket" +``` + +--- + +### Task 10: Detection engine: labels instead of percentages, longest cookie rule, precompiled regexes (D9, Q4) + +**Files:** +- Modify: `lib/services/detection/engine.dart` +- Modify: `lib/widgets/metadata_view.dart:896` +- Test: `test/detection_engine_test.dart` + +**Interfaces:** +- Produces: `enum DetectionConfidence { high, medium, low }` with `String get label` (`High`, `Medium`, `Low`). +- Changes: `(DetectionConfidence, String) get confidence` on `Detection`. Header, a loaded request, or a version → `high`; cookie or found in source → `medium`; connection hint only → `low`. The reason strings are unchanged. +- Produces: `@visibleForTesting Entity? longestCookieRule(String name, List<(Entity, String)> rules)`: among matching rules the longest rule wins; an exact rule beats a prefix rule (`_ga` beats `_ga*`). +- Changes: `entityForCookie(String name)` is `longestCookieRule(name, _cookieRules)`. + +- [ ] **Step 1: Write the failing tests** + +```dart +test('confidence is a label', () { + final d = Detection(entityNamed('Google Ads')!)..requests = 1; + expect(d.confidence.$1, DetectionConfidence.high); + expect(DetectionConfidence.medium.label, 'Medium'); +}); +test('the longest cookie rule wins', () { + const a = Entity('A', DetectionCategory.analytics); + const b = Entity('B', DetectionCategory.advertising); + expect(longestCookieRule('_gcl_au', [(a, '_g*'), (b, '_gcl_*')]), b); + expect(longestCookieRule('_gcl_au', [(b, '_gcl_*'), (a, '_g*')]), b); + expect(longestCookieRule('_ga', [(a, '_ga*'), (b, '_ga')]), b); // exact beats prefix + expect(longestCookieRule('other', [(a, '_g*')]), isNull); +}); +``` + +- [ ] **Step 2: Run and see them fail** + +Run: `flutter test test/detection_engine_test.dart` +Expected: FAIL. + +- [ ] **Step 3: Implement** + +Top-level finals built once: `_headerRules` (`(Entity, String name, RegExp? regex)`, null regex for the empty pattern) and `_beaconRules` (`(Entity, RegExp)`). `scanSource` and `detect` use them instead of `RegExp(...)` in the loops. `metadata_view.dart` shows `confidence.$1.label` where it showed the number. + +- [ ] **Step 4: Run the suite, commit** + +Run: `flutter test` +```bash +git commit -am "Fix: detection confidence as a label; longest cookie rule; precompiled patterns" +``` + +--- + +### Task 11: Sovereignty: anycast is not a location; RIPEstat etiquette; one HTTP client (D10, S7, Q3) + +**Files:** +- Modify: `lib/services/sovereignty_service.dart` (`HostInfo` ~407, residency check ~822, `_enrichHost` ~1406, `_fetchJson` ~1429, the three RIPEstat URLs) +- Test: `test/services/sovereignty_service_test.dart` + +**Interfaces:** +- Produces: `bool HostInfo.anycast` (default false; true when the matched provider has `edge == true`); `'anycast'` in `HostInfo.toJson()`. +- Produces: `@visibleForTesting static String SovereigntyService.ripeUrl(String call, String resource)` → `https://stat.ripe.net/data//data.json?resource=&sourceapp=viewsourcevibe`. +- Changes: the residency check counts only hosts with a known country that are not anycast, and its evidence text ends with `; N host(s) on an anycast CDN (location depends on the visitor)` when N > 0. +- Changes: all RIPEstat requests share one lazily created `HttpClient` (`idleTimeout` 15 s) that is not closed per request. + +- [ ] **Step 1: Check the etiquette claim** + +Read https://stat.ripe.net/docs/data-api/ (rules of usage). If it does not ask for `sourceapp`, leave the parameter out and drop that expectation from the test below. + +- [ ] **Step 2: Write the failing tests** + +```dart +test('RIPEstat URLs name the app', () { + expect(SovereigntyService.ripeUrl('prefix-overview', '1.2.3.4'), + 'https://stat.ripe.net/data/prefix-overview/data.json' + '?resource=1.2.3.4&sourceapp=viewsourcevibe'); +}); +test('anycast hosts do not count as located', () { + // Build hosts the way the existing residency tests in this file do: + // one host in NL (not anycast), one on a CDN with ipCountry 'US' and anycast = true. + // Expect the residency check to judge only the NL host and its evidence to + // contain '1 host(s) on an anycast CDN'. +}); +``` + +- [ ] **Step 3: Run and see them fail, implement, run the suite** + +Run: `flutter test test/services/sovereignty_service_test.dart` + +- [ ] **Step 4: Commit** + +```bash +git commit -am "Fix: anycast hosts are not located; RIPEstat sourceapp; shared client" +``` + +--- + +### Task 12: Size lookups share one connection pool (Q3) + +**Files:** +- Modify: `lib/services/collectors/transfer_size_lookup.dart` +- Modify: `lib/services/html_service.dart` (`_cachedSizeLookup` ~4762, `_lookupResourceSize` ~5087, `dispose`) +- Test: `test/collectors/transfer_size_lookup_test.dart` + +**Interfaces:** +- Changes: `lookupTransferSize(String url, {required String userAgent, int limit, Duration timeout, HttpClient Function()? client, HttpClient? shared})`. With `shared`, that client is used and left open; `client` and `shared` together is an `ArgumentError`. +- `HtmlService` holds one `HttpClient` per navigation generation for lookups (`autoUncompress = false`, `connectionTimeout` 15 s), closed with `close(force: true)` when the generation changes and in `dispose`. + +- [ ] **Step 1: Write the failing test** + +```dart +test('a shared client is reused and left open', () async { + final ports = []; + final server = await HttpServer.bind('127.0.0.1', 0); + server.listen((r) { + ports.add(r.connectionInfo!.remotePort); + r.response..headers.contentLength = 3..write('abc')..close(); + }); + final client = HttpClient()..autoUncompress = false; + final url = 'http://127.0.0.1:${server.port}/a.png'; + await lookupTransferSize(url, userAgent: 't', shared: client); + await lookupTransferSize(url, userAgent: 't', shared: client); + expect(ports.toSet(), hasLength(1)); + client.close(force: true); + await server.close(force: true); +}); +``` + +- [ ] **Step 2: Run and see it fail, implement, run the suite, commit** + +Run: `flutter test test/collectors/transfer_size_lookup_test.dart` +```bash +git commit -am "Perf: size lookups reuse one HTTP client per navigation" +``` + +--- + +### Task 13: A real diff in the export (D7) + +**Files:** +- Create: `lib/utils/line_diff.dart` +- Modify: `lib/services/inspection_export_service.dart` (`_lineDiff` ~752, manifest, `_pill` for `diff.patch`) +- Test: `test/utils/line_diff_test.dart`, `test/inspection_export_service_test.dart` + +**Interfaces:** +- Produces: `String? unifiedDiff(String before, String after, {String fromName = 'a', String toName = 'b', int context = 3, int maxChanges = 2000})`. Null when the texts are equal or when more than `maxChanges` lines are added plus removed. Output is a unified diff (`--- name`, `+++ name`, `@@ -l,s +l,s @@` hunks) that `patch` accepts. Myers O(ND) on lines, stopping at `maxChanges`. +- Changes: manifest gets `'diff': {'status': 'present'}` or `{'status': 'unavailable', 'reason': 'exceedsLimit', 'detail': 'more than 2000 changed lines'}` or `{'status': 'unavailable', 'reason': 'notApplicable', 'detail': 'no server source and browser DOM to compare'}`. + +- [ ] **Step 1: Write the failing tests** + +```dart +test('one inserted line is one added line', () { + final d = unifiedDiff('a\nb\nc\nd\ne\n', 'a\nb\nX\nc\nd\ne\n', + fromName: 'source/server.html', toName: 'source/browser-dom.html')!; + expect(d, '--- source/server.html\n+++ source/browser-dom.html\n' + '@@ -1,5 +1,6 @@\n a\n b\n+X\n c\n d\n e\n'); +}); +test('equal texts give null', () => expect(unifiedDiff('a\n', 'a\n'), isNull)); +test('too many changes give null', () { + final a = List.generate(3000, (i) => 'a$i').join('\n'); + final b = List.generate(3000, (i) => 'b$i').join('\n'); + expect(unifiedDiff(a, b), isNull); +}); +test('patch accepts the output', () async { + // Skip when `patch` is not installed. Write before/after to a temp dir, + // run `patch before.txt diff.patch`, expect the file to equal `after`. +}); +``` + +- [ ] **Step 2: Run and see them fail, implement, wire into the export, run the suite** + +Run: `flutter test test/utils/line_diff_test.dart test/inspection_export_service_test.dart` + +- [ ] **Step 3: Commit** + +```bash +git commit -am "Fix: source/diff.patch is a real unified diff" +``` + +--- + +### Task 14: Reader view runs no page script (S3) + +**Files:** +- Modify: `lib/services/reader_service.dart` (`wrapInReaderTemplate`) +- Test: `test/reader_service_test.dart` + +- [ ] **Step 1: Write the failing test** + +```dart +test('the reader page forbids scripts', () { + final html = wrapInReaderTemplate(article, dark: false, baseUrl: 'https://a.test/'); + const csp = ''; + expect(html, contains(csp)); + expect(html.indexOf(csp), lessThan(html.indexOf('`, run, commit** + +Run: `flutter test test/reader_service_test.dart` +```bash +git commit -am "Security: reader view forbids scripts with a CSP" +``` + +--- + +### Task 15: Privacy policy matches the app; warning before sharing a package (S1, S5) + +**Files:** +- Modify: `PRIVACY.md` +- Create: `lib/widgets/share_package_dialog.dart` +- Modify: `lib/widgets/toolbar.dart:192` +- Test: `test/widgets/share_package_dialog_test.dart` + +**Interfaces:** +- Produces: `Future confirmSharePackage(BuildContext context)`: an `AlertDialog`; true only when the user taps `Share`. + +- [ ] **Step 1: Rewrite the "Network Access" section of `PRIVACY.md`** + +Set "Last updated" to the commit date. Replace the numbered list and the paragraph after it with: + +```markdown +The application contacts: + +1. **The site you inspect**: the page itself (in the in-app browser and with a separate request by the app), its redirects, `robots.txt`, `sitemap.xml` and `/.well-known/security.txt`. +2. **The hosts that page loads files from**: the in-app browser loads them like any browser. For files whose size the browser does not report, the app requests the file once more to measure it. Tracking pixels are never requested again. +3. **RIPEstat (stat.ripe.net, RIPE NCC, Netherlands)**: the IP addresses of the hosts a page uses, to look up their network and country. Only when you open the Sovereignty tab. +4. **A DNS-over-HTTPS resolver** (doh.libredns.gr, Greece; dns.google, United States, as fallback): the domain name of the site, to read its DNS records. Only when you open the Sovereignty tab. +5. **DuckDuckGo's icon service (icons.duckduckgo.com)**: the domain names of services detected on a page, to show their logos. Logos are cached for 30 days. + +These services see your IP address and the names listed above. They do not receive the page content, your history, cookies or any identifier from the app. + +Your history and the URLs you visit are stored on your device and are never sent to us. +``` + +Check each of the five lines against the code before committing (`rg "https://" lib/services`); correct the list if the code says otherwise. + +- [ ] **Step 2: Write the failing widget test** + +```dart +testWidgets('share only after the user confirms', (tester) async { + bool? result; + await tester.pumpWidget(MaterialApp(home: Builder(builder: (c) => + TextButton(onPressed: () async => result = await confirmSharePackage(c), + child: const Text('go'))))); + await tester.tap(find.text('go')); + await tester.pumpAndSettle(); + expect(find.text('Share inspection package?'), findsOneWidget); + expect(find.textContaining('can include personal data'), findsOneWidget); + await tester.tap(find.text('Cancel')); + await tester.pumpAndSettle(); + expect(result, isFalse); +}); +``` + +Import `MaterialApp` the way the other widget tests do (`package:material_ui/material_ui.dart`). + +- [ ] **Step 3: Implement with this exact copy, call it in `toolbar.dart` before `createShareableInspectionPackage`** + +Title: `Share inspection package?` +Body: `The package contains the page source as the browser showed it and every request URL. If you were signed in, that can include personal data. Cookie and storage values are not included.` +Buttons: `Cancel`, `Share`. + +- [ ] **Step 4: Run the suite, commit** + +```bash +git commit -am "Security: privacy policy lists third parties; confirm before sharing a package" +``` + +--- + +### Task 16: Quiet release logs, English certificate dialog, one version constant (S6, Q6) + +**Files:** +- Modify: `lib/main.dart` (first lines of `main`) +- Modify: `lib/services/certificate_security_service.dart:49–64` +- Create: `lib/utils/app_version.dart` +- Modify: `lib/screens/about_screen.dart:89`, `lib/services/collectors/server_fetcher.dart:13` +- Modify: `analysis_options.yaml`; Create: `test/analysis_options.yaml` +- Test: `test/app_version_test.dart` + +**Interfaces:** +- Produces: `const kAppVersion = '2.0.0';` in `lib/utils/app_version.dart`. `kServerUserAgent` becomes `'ViewSourceVibe/$kAppVersion (+https://github.com/woutervanwijk/viewsourcevibe)'`. + +- [ ] **Step 1: Write the failing test** + +```dart +test('kAppVersion matches pubspec.yaml', () { + final line = File('pubspec.yaml').readAsLinesSync() + .firstWhere((l) => l.startsWith('version:')); + expect(line, startsWith('version: $kAppVersion+')); +}); +``` + +- [ ] **Step 2: Run and see it fail, implement the constant and its two uses** + +- [ ] **Step 3: Silence `debugPrint` in release builds** + +First statement of `main()`: `if (kReleaseMode) debugPrint = (String? message, {int? wrapWidth}) {};` + +- [ ] **Step 4: Certificate dialog copy** + +Title `Untrusted certificate`. Body `The server "$host" presented a certificate this device does not trust.` then the subject line (`Certificate: `) when known, then `Accept this certificate for "$host" for the rest of this session?`. Buttons `Cancel` and `Accept (this session only)`. + +- [ ] **Step 5: Scope the print exemption to tests** + +Remove `errors: avoid_print: ignore` from `analysis_options.yaml`. Create `test/analysis_options.yaml`: + +```yaml +include: ../analysis_options.yaml +analyzer: + errors: + avoid_print: ignore +``` + +Run: `flutter analyze --no-pub` +Expected: `No issues found!` If `integration_test/` or `tool/` report `avoid_print`, give those directories the same file. + +- [ ] **Step 6: Run the suite, commit** + +```bash +git commit -am "Chore: silent release logs, English certificate dialog, one version constant" +``` + +--- + +### Task 17: Remove dead code; move filename generation out of HtmlService (Q6, Q1) + +Runs after every other task is merged. + +**Files:** +- Delete: `lib/utils/page_weight.dart`, `test/utils/page_weight_test.dart` +- Modify: `lib/services/html_service.dart` (remove `loadServerSourceForDiff` ~3557, `cancelPendingHighlight` ~4247, `getLanguageForExtension` ~3616 to the end of its switch; move `generateDescriptiveFilename` ~2586–2945) +- Create: `lib/utils/descriptive_filename.dart` +- Modify: `test/language_support_test.dart`, `test/automatic_detection_ui_test.dart`, `test/enhanced_language_support_test.dart` and any other test that calls `htmlService.getLanguageForExtension` +- Test: `test/utils/descriptive_filename_test.dart` (move the existing cases that cover `generateDescriptiveFilename`) + +**Interfaces:** +- Produces: `String generateDescriptiveFilename(Uri uri, String content, {String? contentType})` as a top-level function with exactly the parameters the method has today (read the method first; keep its signature). `HtmlService` calls it; the method is removed. + +- [ ] **Step 1: Prove each deletion is dead** + +Run: `grep -rn "resourcesBySize\|ResourceSize(\|loadServerSourceForDiff\|cancelPendingHighlight" lib integration_test` +Expected: only the definitions. If anything else shows up, leave that item in place and say so in the commit message. + +- [ ] **Step 2: Point the language tests at the mapping the app uses** + +Replace `htmlService.getLanguageForExtension(x)` with `SourceViewerEditor.getLanguageForExtension(x)` in the tests. +Run: `flutter test test/language_support_test.dart test/enhanced_language_support_test.dart test/automatic_detection_ui_test.dart` +Expected: PASS. Where an expectation fails, `SourceViewerEditor` is what the app shows: list the differing extensions in the commit message and change the expectation. + +- [ ] **Step 3: Delete the dead code; move `generateDescriptiveFilename` and its private helpers verbatim** + +- [ ] **Step 4: Run everything** + +Run: `flutter analyze --no-pub && flutter test` +Expected: PASS; `wc -l lib/services/html_service.dart` is at least 900 lines lower than before this task. + +- [ ] **Step 5: Commit** + +```bash +git add -A && git commit -m "Chore: remove dead code; filename generation out of HtmlService" +``` + +--- + +## Final gate + +- [ ] `flutter analyze --no-pub && flutter test` on the merged branch: clean, all pass. +- [ ] `validation/run.sh` (all ten sites, macOS): compare `summary.json` with the run of 13 Nov. No new ❌. Note whether bol.com (O1) still gets the block page; that tells whether D6 was its cause. +- [ ] Add a "Follow-up 15 Nov" section to `docs/audits/2026-11-15-explorer-audit.md` listing which findings are fixed and what the validation run showed. diff --git a/docs/superpowers/plans/2026-11-15-02-summary-and-batch.md b/docs/superpowers/plans/2026-11-15-02-summary-and-batch.md new file mode 100644 index 0000000..5aedc23 --- /dev/null +++ b/docs/superpowers/plans/2026-11-15-02-summary-and-batch.md @@ -0,0 +1,469 @@ +# Summary and Batch Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** A rule-based summary of the most important findings of an inspection, and a batch mode that visits a list of sites one by one and exports every site's inspection package plus that summary in one zip (F1). + +**Architecture:** `deriveSummary` is a pure function over the models the tabs already use; it feeds the report, a new `analysis/summary.json`, and the batch table. `BatchRunner` drives the live browser through a narrow `BatchTarget` interface (so it is testable without a WebView), the way `integration_test/site_validation_test.dart` already does by hand. No AI, no new dependencies. + +**Tech Stack:** Flutter, `provider`, `archive` (already a dependency), `shared_preferences`. + +**Spec:** `docs/audits/2026-11-15-explorer-audit.md` (F1). Requirements from the owner (14 Nov): fill in a list of sites; they get visited one by one; results exported like the current export, plus a summary with the most important findings per site; no AI. + +**Depends on:** plan 01 Task 6 (`sameSite`) and Task 9 (`PageWeight.breakdown` keys). Start after those are merged. + +## Global Constraints + +- Everything in plan 01's Global Constraints applies. +- Unknown is never `0` or `''` in JSON: a fact that is unknown is `null`. In CSV an unknown fact is an empty cell. +- Text that comes from a site (finding details, tracker names from cookies, block-page text) is escaped in HTML and neutralised in CSV (see Task 3). +- Rules are fixed and deterministic: the same inspection gives the same findings in the same order. +- The thresholds below are product choices without an external norm; they live in one place (`inspection_summary.dart`) as named constants. + +## Review Focus + +1. A site that never settles: after the timeout the package is still exported, the row says `timed out` and names the analyses that were unfinished (Task 4 test `a site that never settles is exported as timed out`). +2. Two URLs with the same slug (`example.com/a`, `example.com/a/`): package names stay unique (Task 4 test `slugs are unique`). +3. Site-controlled text starting with `=`, `+`, `-` or `@` in a CSV cell (formula injection): prefixed with `'` (Task 3 test). +4. Cancel during a site: the runner stops, finished sites and their packages are kept, the zip can still be built (Task 4 test `cancel keeps finished sites`). +5. Pasted input with blank lines, `#` comments, bare domains, duplicates and non-web schemes (`javascript:`, `file:`) (Task 4 test `parseBatchInput`). +6. A block or challenge page: findings about the site's content (trackers, cookies, weight) are not reported for it (Task 1 test `a block page hides content findings`). + +--- + +### Task 1: `deriveSummary`: fixed rules over the existing models + +**Files:** +- Create: `lib/services/derive/inspection_summary.dart` +- Test: `test/derive/inspection_summary_test.dart` + +**Interfaces:** +- Consumes: `PageInspection`, `Observed`, `Observed`, `Observed`, `DetectionsView`, `Observed`, `BlockPage?`, `List`, `derivePageWeight`, `sameSite`. +- Produces: + +```dart +enum FindingSeverity { high, medium, low, info } + +class Finding { + final String id; // rule id from the table below + final FindingSeverity severity; + final String title; // one line, complete on its own + final String? tab; // AppTab.tag of the tab with the detail + const Finding(this.id, this.severity, this.title, {this.tab}); + Map toJson(); +} + +class SummaryInputs { + final PageInspection inspection; + final Observed general; + final Observed security; + final Observed cookies; + final DetectionsView detections; + final Observed sovereignty; + final BlockPage? blockPage; + final List divergences; + const SummaryInputs({required ...all of them}); +} + +class InspectionSummary { + final List findings; // sorted: severity, then rule order + final Map facts; // keys in [summaryFactKeys], null = unknown + List get top => findings.take(5).toList(); + Map toJson(); // {'findings': [...], 'facts': {...}} +} + +const List summaryFactKeys = [ + 'url', 'finalUrl', 'status', 'blocked', 'requests', 'thirdPartyHosts', + 'transferBytes', 'transferIsLowerBound', 'trackers', 'trackerNames', + 'consentTool', 'cookies', 'advertisingCookies', 'analyticsCookies', + 'securityHeadersPct', 'cspScore', 'certValidUntil', + 'sovereigntyScore', 'sovereigntyGrade', 'sovereigntyCoverage', +]; + +InspectionSummary deriveSummary(SummaryInputs i); +``` + +Rules, in rule order. "Trackers" = detections with `category.isTracking` that are not `hintOnly`. A rule whose input is not `Present` produces nothing. + +| id | severity | when | title | tab | +|---|---|---|---|---| +| `block-page` | high | `blockPage != null` | `Not the site: ` | `browser` | +| `invalid-cert-accepted` | high | server snapshot `acceptedInvalidCertificate` | `Loaded with an untrusted certificate (accepted by the user)` | `security` | +| `no-https` | high | final URL scheme is `http` | `No HTTPS: the page is served over plain HTTP` | `security` | +| `cert-expired` | high | `certificate.validityExpired` | `Certificate expired ()` | `security` | +| `cert-host` | high | `!certificate.hostMatches` | `Certificate does not match the host` | `security` | +| `pre-consent` | high | not blocked; a detection with category `consent` exists and ≥ 1 tracker has `requests > 0` or a cookie | `Tracking before consent: N tracker(s) active while is present` | `privacy` | +| `trackers` | high when a tracker has `category.tracking >= 4`, else medium | not blocked; ≥ 1 tracker | `N tracker(s): A, B, C` (first three by the engine's order, then ` (+k)`) | `privacy` | +| `ad-cookies` | medium | not blocked; `cookies.advertisingCount > 0` | `N advertising cookie(s) set without a consent choice` | `cookies` | +| `cert-expiring` | medium | not expired and `validityTone` is `warn` or `bad` | `Certificate: ` | `security` | +| `security-headers` | medium below `kHeadersPoor` (50), low below `kHeadersGood` (80) | `audit.percentage != null` | `Security headers: P% (missing: )` | `security` | +| `page-weight` | medium above `kWeightHeavy` (5 MB), low above `kWeightNotable` (2 MB) | not blocked; `PageWeight.transfer != null` | `Page weight ` plus `, P% in third-party iframes` when that share is ≥ 20% | `page-size` | +| `sovereignty` | medium for grade `Poor`, low for `Fair` | `report.grade != null` | `Sovereignty: S (), coverage C%` | `sovereignty` | +| `csp-weak` | low | `csp.score != null && csp.score < 50` | `Content-Security-Policy is weak (score S)` | `security` | +| `divergence` | low | each divergence with `!lowSeverity` | `` | `probe` | +| `third-parties` | info | not blocked; browser resources Present | `N third-party host(s) contacted` | `request-timeline` | + +Sizes use `FormatUtils` (the same formatter the Size tab uses). Third-party host = host of a resource that is not `sameSite` with the page host; counted once per host. + +- [ ] **Step 1: Write the failing tests** + +Build inputs from the existing fixtures (`test/fixtures/inspection/trackers.dart`, `full_page.dart`, `bot_blocked.dart`) and the derive functions the views use; add a small helper `SummaryInputs inputsFor(PageInspection p, {List detections})` in the test file. + +```dart +test('trackers are reported with names and severity', () { + final s = deriveSummary(inputsFor(trackersPage, detections: [ + Detection(entityNamed('Google Ads')!)..requests = 2, + Detection(entityNamed('Google Analytics')!)..requests = 1, + ])); + final f = s.findings.firstWhere((f) => f.id == 'trackers'); + expect(f.severity, FindingSeverity.high); // advertising has tracking 5 + expect(f.title, '2 tracker(s): Google Ads, Google Analytics'); + expect(s.facts['trackers'], 2); +}); +test('tracking with a consent tool present is pre-consent tracking', () { + // + Detection(entityNamed('Cookiebot')!)..requests = 1 + // expect a finding 'pre-consent' with severity high whose title contains 'Cookiebot' + // expect facts['consentTool'] == 'Cookiebot' +}); +test('a block page hides content findings', () { + final s = deriveSummary(inputsFor(botBlockedPage, detections: [ + Detection(entityNamed('Google Ads')!)..requests = 2])); + expect(s.findings.first.id, 'block-page'); + expect(s.findings.map((f) => f.id), isNot(contains('trackers'))); + expect(s.facts['blocked'], isTrue); + expect(s.facts['trackers'], isNull); +}); +test('unknown facts are null, never 0', () { + final s = deriveSummary(inputsFor(const PageInspection.empty())); + expect(s.findings, isEmpty); + expect(s.facts.keys, summaryFactKeys); + expect(s.facts['requests'], isNull); + expect(s.facts['securityHeadersPct'], isNull); +}); +test('findings are sorted by severity, then rule order', () { + // full page with trackers (high), weak headers (medium), info + // expect severities non-decreasing by index +}); +test('security headers name what is missing', () { + // audit with HSTS and CSP failing out of six applicable checks + // expect title 'Security headers: 67% (missing: HSTS, CSP)' with severity low +}); +``` + +Use the catalogue's real entity names; check them with `grep "Entity('" lib/services/detection/catalog.dart`. + +- [ ] **Step 2: Run and see them fail** + +Run: `flutter test test/derive/inspection_summary_test.dart` +Expected: FAIL (file missing). + +- [ ] **Step 3: Implement `inspection_summary.dart`** + +One private function per rule returning `Finding?` or `List`, called in table order; a stable sort by `severity.index` afterwards. Thresholds as top-level constants `kHeadersPoor = 50`, `kHeadersGood = 80`, `kWeightHeavy = 5 * 1024 * 1024`, `kWeightNotable = 2 * 1024 * 1024`, `kFrameShareNotable = 0.20`. + +- [ ] **Step 4: Run and see them pass, commit** + +```bash +git add lib/services/derive/inspection_summary.dart test/derive/inspection_summary_test.dart +git commit -m "Add a rule-based inspection summary (key findings)" +``` + +--- + +### Task 2: The summary in the single-site export + +**Files:** +- Modify: `lib/services/html_service.dart` (one getter next to `generalView` ~837) +- Modify: `lib/services/inspection_export_service.dart` (`buildPackageBytes`, `_buildHtmlReport`) +- Test: `test/inspection_export_service_test.dart` + +**Interfaces:** +- Produces: `InspectionSummary get summary` on `HtmlService` (builds `SummaryInputs` from its existing getters; no caching). +- Produces: `analysis/summary.json` in the package (`summary.toJson()`); a `Key findings` section directly under the first metric cards in `report.html`: a table with columns `Severity`, `Finding`, or the card `No findings from the checks that ran.` when empty. + +- [ ] **Step 1: Write the failing test** + +```dart +test('the package carries the summary', () { + final archive = ZipDecoder().decodeBytes( + InspectionExportService().buildPackageBytes(service)); + final json = jsonDecode(utf8.decode( + archive.findFile('analysis/summary.json')!.content as List)); + expect(json['facts'].keys, containsAll(summaryFactKeys)); + final report = utf8.decode(archive.findFile('report.html')!.content as List); + expect(report, contains('

Key findings

')); +}); +``` + +`service` is set up the way the other tests in this file do it. + +- [ ] **Step 2: Run, see it fail, implement, run the suite, commit** + +Run: `flutter test test/inspection_export_service_test.dart` +```bash +git commit -am "Export: key findings in report.html and analysis/summary.json" +``` + +--- + +### Task 3: Batch outputs: `summary.json`, `summary.csv`, `summary.html` + +**Files:** +- Create: `lib/services/batch_summary.dart` +- Test: `test/services/batch_summary_test.dart` + +**Interfaces:** +- Produces: + +```dart +class BatchRow { + final Uri url; + final String slug; // also the package name: sites/.zip + final String state; // 'done' | 'timed out' | 'failed' | 'cancelled' + final List pending; // analyses unfinished at export + final String? error; + final InspectionSummary? summary; // null when nothing was exported + const BatchRow({...}); +} + +Map batchSummaryJson(List rows, {required DateTime exportedAt}); +String batchSummaryCsv(List rows); +String batchSummaryHtml(List rows, {required DateTime exportedAt}); +String csvCell(Object? value); +``` + +- `batchSummaryCsv`: header `url,state,pending,error,` + `summaryFactKeys` joined by `,` + `,finding1,finding2,finding3,finding4,finding5`. One row per site, `\r\n` line ends, UTF-8. +- `csvCell`: null → empty; lists joined with `; `; a cell whose first character is `=`, `+`, `-`, `@`, tab or CR gets a leading `'`; cells containing `,`, `"`, CR or LF are quoted with `"` doubled. Numbers and booleans are written as they are (a negative number is a number, not text, and gets no `'`). +- `batchSummaryHtml`: one self-contained page (reuse the CSS string of the report: make `InspectionExportService._reportCss` a library-level `const reportCss` in its own file `lib/services/report_css.dart`). A table with one row per site: site (link to `sites/.zip`), state, and the top five findings as a list with the severity as a word. Everything escaped with `HtmlEscape`. +- `batchSummaryJson`: `{'format': 'view-source-vibe-batch', 'formatVersion': 1, 'exportedAt': ..., 'unknownIs': 'null', 'sites': [{'url', 'slug', 'package', 'state', 'pending', 'error', 'summary'}]}`. + +- [ ] **Step 1: Write the failing tests** + +```dart +test('csv cells from a site cannot become formulas', () { + expect(csvCell('=HYPERLINK("http://x")'), '"\'=HYPERLINK(""http://x"")"'); + expect(csvCell('@cmd'), "'@cmd"); + expect(csvCell(-5), '-5'); + expect(csvCell(null), ''); + expect(csvCell(['a', 'b']), 'a; b'); + expect(csvCell('a,b'), '"a,b"'); +}); +test('csv has one row per site and a stable header', () { + final csv = batchSummaryCsv([rowFor('https://a.test/'), rowFor('https://b.test/')]); + final lines = csv.trimRight().split('\r\n'); + expect(lines, hasLength(3)); + expect(lines.first, startsWith('url,state,pending,error,url,finalUrl,status,')); + expect(lines.first, endsWith('finding1,finding2,finding3,finding4,finding5')); +}); +test('html escapes site text', () { + // a row whose finding title is '' + // expect the page to contain '<script>' and not '