@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/integration/ssrMemoryProbe.ts

@@ -1,17 +1,11 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { DevResourceProbe, type DevResourceProc } from "./devResourceProbe";
 
 export type SsrProcRole = "gateway" | "replica" | "rsc" | "other";
 
-export interface SsrProc {
-  pid: number;
-  ppid: number;
-  rssMb: number;
-  cpuSec: number;
-  role: SsrProcRole;
-  command: string;
-}
+export type SsrProc = DevResourceProc<SsrProcRole>;
 
 export interface SsrCgroupSample {
   currentMb: number;
@@ -35,12 +29,7 @@ export interface SsrCacheSample {
   heap: SsrHeapSample;
 }
 
-/**
- * RSS minus JS heap is what a module graph costs beyond its objects — compiled code, module
- * records, native allocator retention — so the split is what separates "the app retains objects"
- * from "the runtime retains code". `jscExtra` is JSC's off-heap attribution, which is where
- * typed-array backing stores (cached Flight chunks) land.
- */
+// `jscExtra` is JSC's off-heap attribution, where typed-array backing stores (cached Flight chunks) land.
 export interface SsrHeapSample {
   replicaHeapUsedMb: number;
   replicaJscHeapMb: number;
@@ -52,63 +41,30 @@ export interface SsrHeapSample {
 
 export interface SsrMemoryProbeOptions {
   appName: string;
-  /** Built app directory — `dist/apps/<app>` unless the build was relocated. */
   distDir: string;
   port: number;
   basePaths: string;
   repoName: string;
   serveDomain: string;
   scenarios: number[];
-  /** Repeat count for scenario 1 (same route) and per-route passes in scenario 6. */
   repeats: number;
   concurrencies: number[];
   idleSeconds: number;
-  /** Report cadence forced on the children; also bounds how long a sample waits for a fresh one. */
   metricsIntervalMs: number;
-  /** Disables both result caches at boot — the second half of scenario 3. */
   cacheOff: boolean;
-  /**
-   * Forces `Bun.gc(true)` before every metrics sample. Required for the s7 ratchet test: without
-   * it, growth across passes cannot be told apart from garbage that has not been collected yet.
-   */
   gcOnReport: boolean;
-  /** s7: how many times to walk the whole route list. */
   passes: number;
-  /** s8: cumulative distinct-route counts to sample the per-route slope at. */
   sweep: number[];
   logPath: string;
 }
 
-/**
- * Production process-tree RSS and cache occupancy — probe §0.3 of
- * `local/reduce-ssr-ram/01-measurement-harness.md`, and the source of the phase 0 results table.
- *
- *   bun pkgs/@akanjs/devkit/integration/ssrMemoryProbe.ts <app> [--scenarios=1,2,5] [--cache=off]
- *
- * The production tree is gateway → replica × N → rsc worker × N, with no builder; `DevResourceProbe`
- * measures the dev tree instead and the two are not interchangeable.
- *
- * Two things this exists to get right:
- *
- * - **Replica and worker RSS are reported separately.** They are separate processes and the worker
- *   holds a private copy of the pages bundle, so one summed number hides which of the two grows.
- * - **On Linux it samples the cgroup's `anon` / `file` split, not just RSS.** Whether a cache is
- *   anonymous heap (an OOM contributor) or page cache (evictable) is the entire question phase 2
- *   asks; RSS cannot answer it, and neither can macOS, where the file half does not exist in the
- *   same form. Read a macOS run as directional only.
- */
+// Usage: bun pkgs/@akanjs/devkit/integration/ssrMemoryProbe.ts <app> [--scenarios=1,2,5] [--cache=off]
+// The cgroup `anon`/`file` split exists only on Linux; read a macOS run as directional.
 export class SsrMemoryProbe {
   static readonly #columns: SsrProcRole[] = ["gateway", "replica", "rsc"];
 
   static parseArgs(argv: string[]): SsrMemoryProbeOptions {
-    const args = new Map(
-      argv.slice(1).map((arg) => {
-        const [key, value] = arg.replace(/^--/, "").split("=");
-        return [key ?? "", value ?? "1"];
-      }),
-    );
-    const appName = argv[0] ?? "akan";
-    const num = (key: string, fallback: number) => Number(args.get(key) ?? fallback);
+    const { appName, args, num } = DevResourceProbe.parseArgMap(argv);
     const list = (key: string, fallback: number[]) =>
       args.has(key)
         ? (args.get(key) ?? "")
@@ -155,10 +111,7 @@ export class SsrMemoryProbe {
         NODE_ENV: "production",
         USE_AKANJS_PKGS: "true",
         AKAN_PUBLIC_APP_NAME: appName,
-        // `getEnv()` requires these one at a time, and a missing one fails the *replica* while the
-        // gateway stays up: the process tree still looks like a healthy three, and only the child's
-        // `ready` flag and the 503s give it away. Both are why `#waitForReady` checks child
-        // readiness rather than the gateway's own 200.
+        // A missing one fails the replica while the gateway stays up and keeps answering.
         AKAN_PUBLIC_REPO_NAME: process.env.AKAN_PUBLIC_REPO_NAME ?? repoName,
         AKAN_PUBLIC_SERVE_DOMAIN: process.env.AKAN_PUBLIC_SERVE_DOMAIN ?? serveDomain,
         AKAN_PUBLIC_ENV: "local",
@@ -181,7 +134,7 @@ export class SsrMemoryProbe {
     try {
       await this.#measure();
     } finally {
-      await this.#cleanup(gateway);
+      await DevResourceProbe.killTree(gateway, () => this.#sampleTree());
     }
   }
 
@@ -221,11 +174,7 @@ export class SsrMemoryProbe {
       for (const concurrency of concurrencies) await this.#run(`s6 concurrency=${concurrency}`, routes, concurrency);
     }
 
-    // s7 — ratchet vs working set. Every pass renders the same routes, so pass 1 pays for module
-    // evaluation and later passes pay for nothing new. Flat later passes mean the memory is a
-    // working set and only a smaller bundle or fewer replicas reduces it; continued growth means
-    // per-render retention, which is a bug worth more than any ceiling. Run with `--cache=off --gc`
-    // or it measures cache hits and uncollected garbage instead.
+    // s7: flat passes after the first mean a working set; continued growth means per-render retention.
     if (scenarios.includes(7)) {
       if (!this.#options.cacheOff)
         console.info("[probe] WARNING s7 without --cache=off measures cache hits from pass 2 on");
@@ -235,8 +184,7 @@ export class SsrMemoryProbe {
         await this.#run(`s7 pass ${pass}/${this.#options.passes}`, routes, 1);
     }
 
-    // s8 — per-route slope vs fixed intercept. Cumulative: each step adds routes the process has
-    // not seen, so the RSS series against distinct-route count separates the two.
+    // s8: cumulative, so RSS against distinct-route count separates the per-route slope from the intercept.
     if (scenarios.includes(8)) {
       for (const count of this.#options.sweep) {
         const subset = routes.slice(0, Math.min(count, routes.length));
@@ -255,11 +203,7 @@ export class SsrMemoryProbe {
     }
   }
 
-  /**
-   * A scenario is only a measurement if its requests succeeded. A gateway whose replica died still
-   * answers — with 503s, instantly — and the resulting RSS row looks like a legitimately cheap one.
-   * Fail loudly rather than publish that number.
-   */
+  // A dead replica still answers instant 503s, which would read as a legitimately cheap row.
   async #run(label: string, urls: string[], concurrency: number): Promise<void> {
     const started = Date.now();
     const { ok, failed, statuses } = await this.#browse(urls, concurrency);
@@ -307,11 +251,7 @@ export class SsrMemoryProbe {
     return `${(bytes / 1024 / 1024).toFixed(1)}MiB`;
   }
 
-  /**
-   * Reads the container's own accounting. `memory.current` counts page cache, so a disk-backed
-   * cache still shows up here — but under `file`, which the kernel reclaims under pressure instead
-   * of OOM-killing. That split is what phase 2 has to move. Returns null off cgroup v2.
-   */
+  // cgroup v2 only. `file` is page cache the kernel reclaims under pressure; `anon` is what gets OOM-killed.
   static readCgroupSample(): SsrCgroupSample | null {
     try {
       const current = Number.parseInt(fs.readFileSync("/sys/fs/cgroup/memory.current", "utf8").trim(), 10);
@@ -328,22 +268,14 @@ export class SsrMemoryProbe {
     }
   }
 
-  /**
-   * Waits for a metrics report sampled *after* `since` before reading the cache columns.
-   *
-   * The counters ride a periodic IPC report, so reading immediately after a browse returns the
-   * state from before it — and the two-hop path (worker → replica → gateway) means the `rsc*` and
-   * `rscWorker*` fields can be a further interval behind. Without this wait every row silently
-   * attributes one scenario's cache growth to the previous scenario.
-   */
+  // Counters ride a periodic two-hop IPC report (worker → replica → gateway), so wait until both hops have
+  // re-reported after `since`, or one scenario's growth lands in the next row.
   async #sampleCaches(since: number): Promise<SsrCacheSample | null> {
     const deadline = Date.now() + this.#options.metricsIntervalMs * 3 + 5_000;
     let children: Array<Record<string, number>> = [];
     let fresh = false;
     while (Date.now() < deadline) {
       children = await this.#fetchChildMetrics();
-      // Both hops must have re-reported: `reportedAt` is the replica's own sample time, and
-      // `rscWorkerReportedAt` the worker's as of the replica's last read of it.
       fresh =
         children.length > 0 &&
         children.every(
@@ -354,32 +286,30 @@ export class SsrMemoryProbe {
     }
     if (children.length === 0) return null;
     if (!fresh) console.info(`${"".padEnd(24)} WARNING cache columns are stale — no fresh report within the wait`);
-    {
-      const sum = (key: string) => children.reduce((total, metrics) => total + Number(metrics[key] ?? 0), 0);
-      const mb = (key: string) => sum(key) / 1024 / 1024;
-      return {
-        replicaRssMb: sum("rssBytes") / 1024 / 1024,
-        rscWorkerRssMb: sum("rscWorkerRssBytes") / 1024 / 1024,
-        htmlEntries: sum("httpHtmlCacheEntries"),
-        htmlBytes: sum("httpHtmlCacheBytes"),
-        rscEntries: sum("rscResultCacheEntries"),
-        rscBytes: sum("rscResultCacheBytes"),
-        patchEntries: sum("rscPatchResultCacheEntries"),
-        patchBytes: sum("rscPatchResultCacheBytes"),
-        ssrChunkKeys: sum("ssrChunkRegistrySize"),
-        loadedRouteModules: sum("rscLoadedRouteModuleCount"),
-        fullSsr: sum("httpFullSsrCount"),
-        rscNavigation: sum("httpRscNavigationCount"),
-        heap: {
-          replicaHeapUsedMb: mb("heapUsedBytes"),
-          replicaJscHeapMb: mb("jscHeapSizeBytes"),
-          replicaJscExtraMb: mb("jscExtraMemorySizeBytes"),
-          workerHeapUsedMb: mb("rscWorkerHeapUsedBytes"),
-          workerJscHeapMb: mb("rscWorkerJscHeapSizeBytes"),
-          workerJscExtraMb: mb("rscWorkerJscExtraMemorySizeBytes"),
-        },
-      };
-    }
+    const sum = (key: string) => children.reduce((total, metrics) => total + Number(metrics[key] ?? 0), 0);
+    const mb = (key: string) => sum(key) / 1024 / 1024;
+    return {
+      replicaRssMb: mb("rssBytes"),
+      rscWorkerRssMb: mb("rscWorkerRssBytes"),
+      htmlEntries: sum("httpHtmlCacheEntries"),
+      htmlBytes: sum("httpHtmlCacheBytes"),
+      rscEntries: sum("rscResultCacheEntries"),
+      rscBytes: sum("rscResultCacheBytes"),
+      patchEntries: sum("rscPatchResultCacheEntries"),
+      patchBytes: sum("rscPatchResultCacheBytes"),
+      ssrChunkKeys: sum("ssrChunkRegistrySize"),
+      loadedRouteModules: sum("rscLoadedRouteModuleCount"),
+      fullSsr: sum("httpFullSsrCount"),
+      rscNavigation: sum("httpRscNavigationCount"),
+      heap: {
+        replicaHeapUsedMb: mb("heapUsedBytes"),
+        replicaJscHeapMb: mb("jscHeapSizeBytes"),
+        replicaJscExtraMb: mb("jscExtraMemorySizeBytes"),
+        workerHeapUsedMb: mb("rscWorkerHeapUsedBytes"),
+        workerJscHeapMb: mb("rscWorkerJscHeapSizeBytes"),
+        workerJscExtraMb: mb("rscWorkerJscExtraMemorySizeBytes"),
+      },
+    };
   }
 
   async #fetchChildMetrics(): Promise<Array<Record<string, number>>> {
@@ -402,49 +332,10 @@ export class SsrMemoryProbe {
     return "other";
   }
 
-  /** One `ps`, then walk from the gateway pid to a fixpoint. */
-  async #sampleTree(): Promise<SsrProc[]> {
-    const proc = Bun.spawn(["ps", "-eo", "pid=,ppid=,rss=,time=,command="], { stdout: "pipe" });
-    const text = await new Response(proc.stdout).text();
-    await proc.exited;
-    const all = text
-      .split("\n")
-      .map((line) => line.trim())
-      .filter(Boolean)
-      .map((line) => {
-        const match = /^(\d+)\s+(\d+)\s+(\d+)\s+([\d:.]+)\s+(.*)$/.exec(line);
-        if (!match) return null;
-        const [, pid, ppid, rss, time, command] = match;
-        const parts = (time ?? "0:0").split(":");
-        const cpuSec =
-          parts.length === 3
-            ? Number(parts[0]) * 3600 + Number(parts[1]) * 60 + Number(parts[2])
-            : Number(parts[0] ?? 0) * 60 + Number(parts[1] ?? 0);
-        return {
-          pid: Number(pid),
-          ppid: Number(ppid),
-          rssMb: Number(rss) / 1024,
-          cpuSec,
-          role: this.#roleOf(command ?? ""),
-          command: command ?? "",
-        } satisfies SsrProc;
-      })
-      .filter((proc): proc is SsrProc => proc !== null);
-    const kept = new Map<number, SsrProc>();
-    const root = all.find((proc) => proc.pid === this.#gatewayPid);
-    if (root) kept.set(this.#gatewayPid, root);
-    for (let pass = 0; pass < 12; pass++) {
-      const before = kept.size;
-      for (const proc of all) if (kept.has(proc.ppid) && !kept.has(proc.pid)) kept.set(proc.pid, proc);
-      if (kept.size === before) break;
-    }
-    return [...kept.values()].filter((proc) => proc.role !== "other" || proc.pid === this.#gatewayPid);
+  #sampleTree(): Promise<SsrProc[]> {
+    return DevResourceProbe.sampleTree(this.#gatewayPid, (command) => this.#roleOf(command));
   }
 
-  /**
-   * Concrete urls from the built route seed index. `:lang` takes the default locale; any route with
-   * another `:param` is skipped because it needs a real id to render.
-   */
   async #staticRoutes(): Promise<string[]> {
     const artifactDir = path.join(this.#options.distDir, ".akan", "artifact");
     const seed = (await Bun.file(path.join(artifactDir, "route-seed-index.json")).json()) as {
@@ -495,11 +386,7 @@ export class SsrMemoryProbe {
     return { ok, failed, statuses };
   }
 
-  /**
-   * Waits for a **child** to report ready, not for the gateway to answer. The gateway binds and
-   * serves `/health` happily while every replica is in a crash-restart loop, so a 200 here proves
-   * nothing about whether anything can render.
-   */
+  // The gateway answers `/health` while every replica crash-loops, so wait for a ready child instead.
   async #waitForReady(timeoutMs: number): Promise<boolean> {
     const deadline = Date.now() + timeoutMs;
     let lastError = "";
@@ -524,19 +411,6 @@ export class SsrMemoryProbe {
     if (lastError) console.info(`[probe] no child became ready; last child error: ${lastError}`);
     return false;
   }
-
-  async #cleanup(gateway: { kill: (signal: NodeJS.Signals) => void }): Promise<void> {
-    for (const proc of (await this.#sampleTree()).reverse()) {
-      try {
-        process.kill(proc.pid, "SIGKILL");
-      } catch {}
-    }
-    try {
-      gateway.kill("SIGKILL");
-    } catch {}
-    await Bun.sleep(1_000);
-    console.info(`[probe] survivors after kill: ${(await this.#sampleTree()).length}`);
-  }
 }
 
 if (import.meta.main) await new SsrMemoryProbe(SsrMemoryProbe.parseArgs(process.argv.slice(2))).run();

package/libSource.test.ts

@@ -1,25 +1,14 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { Executor, LibExecutor, WorkspaceExecutor } from "./executors";
 import { formatLibStatuses, LibSource } from "./libSource";
+import { tempDirs, writeText as write } from "./testHelpers";
 
-const tempRoots: string[] = [];
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
+const makeTempRoot = tempDirs("akan-libsource-");
 
 // `LibExecutor.from` memoises by name, so each fixture needs a name no other test has used.
 const makeLib = async (libName: string) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-libsource-"));
-  tempRoots.push(root);
+  const root = await makeTempRoot();
   await write(
     path.join(root, "package.json"),
     '{ "name": "workspace", "version": "0.0.1", "description": "workspace" }\n',

package/libSource.ts

@@ -20,20 +20,10 @@ export interface LibStatus {
   hash: string;
 }
 
-/**
- * A library's origin, recorded in its own `package.json` under an `akan.source` key.
- *
- * The key rides `package.json` rather than a file of its own because every akan write to a library's
- * manifest is a spread of the existing object (`LibExecutor.syncPackageJson`), so an unknown top-level
- * key survives — while a new root file would have to be added to `libRootAllowedFiles` before
- * `akan sync` stopped rejecting it.
- */
+// In package.json, not a file of its own: every akan manifest write spreads the existing object, so the key survives.
 export class LibSource {
   static readonly manifestKey = "akan";
-  /**
-   * Left out of the hash. `env/` holds per-deployment values that belong to the workspace the library
-   * was installed into, not to the origin, so an env edit is not drift.
-   */
+  // `env/` holds the installing workspace's per-deployment values, so an env edit is not drift.
   static readonly unhashedDirs = ["env"];
 
   #lib: LibExecutor;
@@ -50,33 +40,35 @@ export class LibSource {
     return !LibSource.unhashedDirs.includes(relative.split("/")[0] ?? "");
   }
 
-  /** `package.json` cannot hash the stamp it carries, so the key comes off before hashing. */
-  async #hashableContent(file: string) {
-    const content = await this.#lib.workspace.readFile(file);
-    if (file !== `${this.#prefix}package.json`) return content;
-    const manifest = JSON.parse(content) as PackageJson;
+  static unstamped(manifestContent: string) {
+    const manifest = JSON.parse(manifestContent) as PackageJson;
     delete manifest[LibSource.manifestKey];
     return JSON.stringify(manifest);
   }
 
-  /**
-   * Hash over the library's own files. Untracked files count: a freshly copied library is not committed
-   * yet, and its hash has to be the same one a later `status` recomputes.
-   */
-  async computeHash() {
-    const files = (await this.#lib.workspace.listGitFiles([`libs/${this.#lib.name}`], { untracked: true })).filter(
-      (file) => this.#isHashed(file),
-    );
+  //* `package.json` cannot hash the stamp it carries, so the key comes off before hashing.
+  static async hashFiles(files: string[], manifestFile: string, read: (file: string) => Promise<string>) {
     const hasher = new Bun.CryptoHasher("sha256");
     for (const file of files) {
+      const content = await read(file);
       hasher.update(file);
       hasher.update("\0");
-      hasher.update(await this.#hashableContent(file));
+      hasher.update(file === manifestFile ? LibSource.unstamped(content) : content);
       hasher.update("\0");
     }
     return hasher.digest("hex").slice(0, 32);
   }
 
+  // Untracked files count: a freshly copied library is not committed yet.
+  async computeHash() {
+    const files = (await this.#lib.workspace.listGitFiles([`libs/${this.#lib.name}`], { untracked: true })).filter(
+      (file) => this.#isHashed(file),
+    );
+    return await LibSource.hashFiles(files, `${this.#prefix}package.json`, (file) =>
+      this.#lib.workspace.readFile(file),
+    );
+  }
+
   async read(): Promise<LibSourceStamp | null> {
     const manifest = await this.#lib.getPackageJson();
     const akan = manifest[LibSource.manifestKey] as { source?: LibSourceStamp } | undefined;
@@ -91,11 +83,7 @@ export class LibSource {
     return stamp;
   }
 
-  /**
-   * Writes the stamp only when it would change. `syncedAt` moves on every write, so an unconditional
-   * write leaves the manifest dirty and defeats an idempotent caller — the hash is computed with the
-   * stamp removed, so comparing it first is sound.
-   */
+  // `syncedAt` moves on every write, so an unchanged stamp is left alone (the hash excludes the stamp itself).
   async syncStamp({ origin, sha }: Pick<LibSourceStamp, "origin" | "sha">) {
     const [current, hash] = await Promise.all([this.read(), this.computeHash()]);
     if (current?.origin === origin && current.sha === sha && current.hash === hash)

package/lint/__fixtures__/no-document-cookie/bad.tsx

@@ -0,0 +1,4 @@
+export const readTheme = () => document.cookie; // @flag
+export const writeTheme = (value: string) => { document.cookie = `theme=${value}`; }; // @flag
+export const throughWindow = () => window.document.cookie; // @flag
+export const throughGlobalThis = () => globalThis.document.cookie; // @flag

package/lint/__fixtures__/no-document-cookie/good.tsx

@@ -0,0 +1,7 @@
+import { getCookie, setCookie } from "akanjs/client";
+export const readTheme = () => getCookie("theme"); // @ok
+export const writeTheme = (value: string) => setCookie("theme", value); // @ok
+export const otherDocumentFields = () => document.title; // @ok
+export const aFieldNamedCookie = (req: { cookie: string }) => req.cookie; // @ok
+export const aLiteral = "document.cookie is empty on app://"; // @ok
+export const Docs = () => <p>getCookie reads the request, document.cookie the browser.</p>; // @ok

package/lint/__fixtures__/no-web-only-api-outside-webkit/bad.tsx

@@ -0,0 +1,7 @@
+export const share = (url: string) => navigator.share({ url }); // @flag
+export const canShare = () => typeof navigator.canShare === "function"; // @flag
+export const worker = () => navigator.serviceWorker.register("/sw.js"); // @flag
+export const ask = () => Notification.requestPermission(); // @flag
+export const permission = () => Notification.permission; // @flag
+export const locate = () => navigator.geolocation.getCurrentPosition(() => undefined); // @flag
+export const buzz = () => navigator.vibrate(50); // @flag

package/lint/__fixtures__/no-web-only-api-outside-webkit/good.tsx

@@ -0,0 +1,11 @@
+import { haptics } from "akanjs/client/native";
+import { useGeoLocation } from "akanjs/webkit";
+export const buzz = () => haptics.impact(); // @ok
+export const locate = () => useGeoLocation(); // @ok
+export const languages = () => navigator.languages; // @ok
+export const clipboard = (text: string) => navigator.clipboard.writeText(text); // @ok
+export const aField = (payload: { share: boolean }) => payload.share; // @ok
+export const aLiteral = "navigator.share is missing on Android"; // @ok
+export const Docs = () => <p>navigator.share is missing on Android.</p>; // @ok
+export const ModelZone = () => <Notification.Zone.Initialize />; // @ok
+export const model = (cnst: { Notification: unknown }) => cnst.Notification; // @ok

package/lint/__fixtures__/no-web-storage/bad.tsx

@@ -0,0 +1,6 @@
+export const readDraft = () => localStorage.getItem("draft"); // @flag
+export const writeDraft = (value: string) => localStorage.setItem("draft", value); // @flag
+export const readTab = () => sessionStorage.getItem("tab"); // @flag
+export const throughWindow = () => window.localStorage.getItem("draft"); // @flag
+export const throughGlobalThis = () => globalThis.sessionStorage.clear(); // @flag
+export const guarded = () => (typeof localStorage === "undefined" ? null : 1); // @flag

package/lint/__fixtures__/no-web-storage/good.tsx

@@ -0,0 +1,7 @@
+import { secretStorage, storage } from "akanjs/client";
+export const readDraft = () => storage.getItem("draft"); // @ok
+export const keepToken = (jwt: string) => secretStorage.setItem("jwt", jwt); // @ok
+export const aFieldWithTheName = (cache: { localStorage: string }) => cache.localStorage; // @ok
+export const anObjectKey = { sessionStorage: false }; // @ok
+export const aLiteral = "localStorage works in the shells"; // @ok
+export const Docs = () => <p>window.localStorage and sessionStorage work in the shells.</p>; // @ok

package/lint/gritRules.test.ts

@@ -4,24 +4,14 @@ import { existsSync } from "node:fs";
 import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { Linter } from "../linter";
 
-/**
- * Fixture tests for the GritQL plugins in this folder.
- *
- * These rules break the apps/libs build, and a rule that stops matching reports **zero diagnostics** rather
- * than an error — so a biome upgrade can retire one silently. GritQL has known sharp edges here (escaped
- * quotes, argument-position matching), which is what makes the quiet failure plausible rather than
- * theoretical.
- *
- * Each rule runs alone, against a config this test writes, so a diagnostic can only have come from that
- * plugin. The path scoping in `biome.base.json` is deliberately not exercised — what is under test is
- * whether the pattern still matches. A rule that reads `$filename` needs a real path anyway, which is what
- * a case's `fixture.json` supplies.
- */
+//? A rule that stops matching reports zero diagnostics, not an error, so a biome upgrade can retire one silently.
+//? Each rule runs alone against a config written here; the path scoping in biome.base.json is deliberately not tested.
 const lintDir = import.meta.dir;
 const fixturesDir = path.join(lintDir, "__fixtures__");
 const workspaceRoot = path.resolve(lintDir, "../../../..");
-const biomeBin = path.join(workspaceRoot, "node_modules/.bin/biome");
+const biomeBin = path.join(workspaceRoot, "node_modules", ".bin", Linter.biomeBinName);
 
 interface BiomeDiagnostic {
   severity: string;
@@ -30,13 +20,10 @@ interface BiomeDiagnostic {
   location?: { start?: { line?: number } };
 }
 
-/**
- * `path` is where the source is written inside the temp workspace, for a rule that gates on `$filename`;
- * its extension also decides whether the file may hold JSX. `expect: "file"` is for a rule whose span is
- * the whole module (`JsModule()`), where there is no per-line diagnostic to match.
- */
 interface FixtureMeta {
+  /** Where the source is written, for a rule that gates on `$filename`; its extension decides whether JSX parses. */
   path?: string;
+  /** `"file"`: the rule's span is the whole module (`JsModule()`), so there is no per-line diagnostic to match. */
   expect?: "lines" | "file";
 }
 
@@ -64,7 +51,6 @@ const runBiome = (args: string[], cwd: string) =>
     proc.on("close", () => resolve(stdout || stderr));
   });
 
-/** Every directory holding a `bad.*`, named `<rule>` or `<rule>/<case>`. */
 const collectCases = async (): Promise<FixtureCase[]> => {
   const cases: FixtureCase[] = [];
   const walk = async (dir: string, rule: string, name: string) => {
@@ -92,7 +78,6 @@ const sourceName = (fixture: FixtureCase, kind: "bad" | "good") => {
 const readFixture = async (fixture: FixtureCase, kind: "bad" | "good") =>
   await readFile(path.join(fixture.dir, sourceName(fixture, kind).read), "utf-8");
 
-/** Diagnostics from one plugin against one fixture, keyed by the 1-based line each was reported on. */
 const lintFixture = async (fixture: FixtureCase, kind: "bad" | "good") => {
   const dir = await mkdtemp(path.join(os.tmpdir(), `grit-${fixture.rule}-`));
   tempDirs.push(dir);
@@ -127,7 +112,7 @@ const lintFixture = async (fixture: FixtureCase, kind: "bad" | "good") => {
   };
 };
 
-/** The 1-based line of every line carrying `marker`. One case per line is the fixture contract. */
+//? One case per line is the fixture contract.
 const markedLines = async (fixture: FixtureCase, kind: "bad" | "good", marker: string) =>
   (await readFixture(fixture, kind))
     .split("\n")
@@ -164,8 +149,7 @@ describe("grit lint rules", () => {
       }
       const expected = await markedLines(fixture, "bad", "// @flag");
       expect(expected.length).toBeGreaterThan(0);
-      // Set equality, not containment: a marked line nobody reported is a pattern that stopped matching,
-      // and a reported line nobody marked is the rule reaching further than the fixture claims.
+      // Set equality: an unreported mark is a pattern that stopped matching, an unmarked report is overreach.
       expect(lines).toEqual(expected);
     });
 

package/lint/no-deep-internal-import.grit

@@ -15,7 +15,7 @@ or {
   JsModuleSource() as $source where {
     $source <: within JsImport(),
     not $filename <: r".*\.(?:test|spec)\.tsx?",
-    $filename <: r".*(?:apps|libs)/[^/]+/lib/[^/]+/[^/]+\.(?:ts|tsx)",
+    $filename <: r".*(?:apps|libs)[/\\][^/\\]+[/\\]lib[/\\][^/\\]+[/\\][^/\\]+\.(?:ts|tsx)",
     $source <: r"\"\.\./\.\./.*\"",
     register_diagnostic(
       span = $source,
@@ -25,7 +25,7 @@ or {
   JsModuleSource() as $source where {
     $source <: within JsImport(),
     not $filename <: r".*\.(?:test|spec)\.tsx?",
-    $filename <: r".*/lib/.+\.tsx",
+    $filename <: r".*[/\\]lib[/\\].+\.tsx",
     $source <: r"\"\.\./.*\"",
     register_diagnostic(
       span = $source,

package/lint/no-document-cookie.grit

@@ -0,0 +1,29 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A native shell serves the page from app://localhost on iOS, macOS and Linux, a custom scheme WebKit keeps no
+// cookie jar for: `document.cookie` reads "" and a write is dropped without an error, so the value exists in the
+// browser and silently vanishes in the app. akanjs/client's cookie helpers keep an app:// page's cookies in a
+// storage-backed jar, which is the only spelling that works in every shell.
+//
+// Pinned to the member nodes: a bare snippet also matches JSX text that spells the same words (a docs page), and a
+// write is its own node (JsStaticMemberAssignment) that the expression form does not match.
+or {
+  JsStaticMemberExpression() as $access where {
+    $access <: or { `document.cookie`, `window.document.cookie`, `globalThis.document.cookie`, `self.document.cookie` },
+    register_diagnostic(
+      span = $access,
+      message = "`document.cookie` is always empty on a native app page (app://localhost keeps no cookies), so this value vanishes in the app. Use `getCookie` / `setCookie` / `removeCookie` from `akanjs/client`.",
+      severity = "error"
+    )
+  },
+  JsStaticMemberAssignment(object = $object, member = $member) as $access where {
+    $member <: `cookie`,
+    $object <: or { `document`, `window.document`, `globalThis.document`, `self.document` },
+    register_diagnostic(
+      span = $access,
+      message = "`document.cookie` is always empty on a native app page (app://localhost keeps no cookies), so this value vanishes in the app. Use `getCookie` / `setCookie` / `removeCookie` from `akanjs/client`.",
+      severity = "error"
+    )
+  }
+}

package/lint/no-redeclare-predefined-endpoint.grit

@@ -14,7 +14,8 @@ language js(typescript, jsx)
     $base <: contains `endpoint`,
     $className <: r"([A-Z][a-zA-Z0-9]*)Endpoint"($Cap)
   },
-  $filename <: r".*/([a-z][a-zA-Z0-9]*)\.signal\.ts"($model),
+  // `$filename` carries backslashes on Windows, so a separator here must accept both.
+  $filename <: r".*[/\\]([a-z][a-zA-Z0-9]*)\.signal\.ts"($model),
   or {
     $key <: $model,
     $key <: r"(?:light|create|update|remove|view|edit|merge)([A-Z][a-zA-Z0-9]*)"($keyCap) where {