@akanjs/devkit 3.0.0-alpha.9 → 3.0.0-alpha.90

package/lint/gritRules.test.ts

@@ -0,0 +1,178 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { spawn } from "node:child_process";
+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";
+
+/**
+ * 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.
+ */
+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");
+
+interface BiomeDiagnostic {
+  severity: string;
+  message: string;
+  category: string;
+  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 {
+  path?: string;
+  expect?: "lines" | "file";
+}
+
+interface FixtureCase {
+  rule: string;
+  name: string;
+  dir: string;
+  meta: FixtureMeta;
+}
+
+const tempDirs: string[] = [];
+
+afterAll(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+const runBiome = (args: string[], cwd: string) =>
+  new Promise<string>((resolve, reject) => {
+    const proc = spawn(biomeBin, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk: Buffer) => (stdout += chunk.toString()));
+    proc.stderr.on("data", (chunk: Buffer) => (stderr += chunk.toString()));
+    proc.on("error", reject);
+    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) => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    if (entries.some((entry) => entry.isFile() && entry.name.startsWith("bad."))) {
+      const metaPath = path.join(dir, "fixture.json");
+      const meta = existsSync(metaPath) ? (JSON.parse(await readFile(metaPath, "utf-8")) as FixtureMeta) : {};
+      cases.push({ rule, name: name || rule, dir, meta });
+    }
+    for (const entry of entries.filter((entry) => entry.isDirectory()))
+      await walk(path.join(dir, entry.name), rule, `${rule}/${entry.name}`);
+  };
+  for (const entry of (await readdir(fixturesDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()))
+    await walk(path.join(fixturesDir, entry.name), entry.name, "");
+  return cases.sort((left, right) => left.name.localeCompare(right.name));
+};
+
+const sourceName = (fixture: FixtureCase, kind: "bad" | "good") => {
+  const target = fixture.meta.path;
+  if (!target) return { read: `${kind}.tsx`, write: `${kind}.tsx` };
+  const ext = path.extname(target);
+  return { read: `${kind}${ext}`, write: target };
+};
+
+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);
+  // Every built-in rule off and the formatter silent, so the only thing left that can report is the plugin.
+  await writeFile(
+    path.join(dir, "biome.json"),
+    JSON.stringify({
+      linter: { enabled: true, rules: { recommended: false } },
+      formatter: { enabled: false },
+      assist: { enabled: false },
+      plugins: [path.join(lintDir, `${fixture.rule}.grit`)],
+    }),
+  );
+  const source = path.join(dir, sourceName(fixture, kind).write);
+  await mkdir(path.dirname(source), { recursive: true });
+  await writeFile(source, await readFixture(fixture, kind));
+  const output = await runBiome(
+    ["check", "--reporter=json", "--max-diagnostics=none", "--no-errors-on-unmatched", `--config-path=${dir}`, source],
+    dir,
+  );
+  const start = output.indexOf("{");
+  const end = output.lastIndexOf("}");
+  if (start === -1 || end < start)
+    throw new Error(`biome produced no JSON for ${fixture.name}/${kind}: ${output.slice(0, 400)}`);
+  const diagnostics =
+    (JSON.parse(output.slice(start, end + 1)) as { diagnostics?: BiomeDiagnostic[] }).diagnostics ?? [];
+  return {
+    diagnostics,
+    lines: [...new Set(diagnostics.map((diagnostic) => diagnostic.location?.start?.line ?? 0))].sort(
+      (left, right) => left - right,
+    ),
+  };
+};
+
+/** The 1-based line of every line carrying `marker`. One case per line is the fixture contract. */
+const markedLines = async (fixture: FixtureCase, kind: "bad" | "good", marker: string) =>
+  (await readFixture(fixture, kind))
+    .split("\n")
+    .map((line, index) => (line.includes(marker) ? index + 1 : 0))
+    .filter((line) => line > 0);
+
+const fixtures = await collectCases();
+
+describe("grit lint rules", () => {
+  test("the harness found the biome binary and at least one fixture", () => {
+    expect(existsSync(biomeBin)).toBe(true);
+    expect(fixtures.length).toBeGreaterThan(0);
+  });
+
+  test("every fixture folder names a rule that exists", () => {
+    for (const fixture of fixtures) expect(existsSync(path.join(lintDir, `${fixture.rule}.grit`))).toBe(true);
+  });
+
+  test("every rule in this folder has a fixture", async () => {
+    const ruleFiles = (await readdir(lintDir))
+      .filter((name) => name.endsWith(".grit"))
+      .map((name) => name.slice(0, -5));
+    const covered = new Set(fixtures.map((fixture) => fixture.rule));
+    expect(ruleFiles.filter((rule) => !covered.has(rule))).toEqual([]);
+  });
+
+  for (const fixture of fixtures) {
+    test(`${fixture.name} flags exactly the marked lines in bad`, async () => {
+      const { lines, diagnostics } = await lintFixture(fixture, "bad");
+      for (const diagnostic of diagnostics) expect(diagnostic.category).toBe("plugin");
+      if (fixture.meta.expect === "file") {
+        expect(diagnostics.length).toBeGreaterThan(0);
+        return;
+      }
+      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.
+      expect(lines).toEqual(expected);
+    });
+
+    test(`${fixture.name} leaves good clean`, async () => {
+      expect((await markedLines(fixture, "good", "// @ok")).length).toBeGreaterThan(0);
+      const { diagnostics } = await lintFixture(fixture, "good");
+      expect(diagnostics.map((diagnostic) => `${diagnostic.location?.start?.line}: ${diagnostic.message}`)).toEqual([]);
+    });
+  }
+});

package/lint/no-arbitrary-color.grit

@@ -3,7 +3,7 @@ language js(typescript, jsx)
 
 // Arbitrary-value color literals (`bg-[#3b82f6]`, `text-[rgb(0,0,0)]`) bypass the semantic
 // token layer, so they ignore data-theme switching and theme contrast validation. Grit port
-// of styleGuard's `arbitrary-color` rule (frontendBuild/styleGuard.ts) — keep in sync.
+// Cases: lint/__fixtures__/no-arbitrary-color/{bad,good}.tsx
 // Variable references (`bg-[--brand]`, `text-[var(--fg)]`) do not match, by design.
 or {
   JsxString() as $s,

package/lint/no-async-component-in-ui.grit

@@ -0,0 +1,35 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// React has no async client component: an async body is a server-only shape, so a `ui/` component that
+// awaits stops rendering the moment any client parent imports it — and `ui/` is written to be reachable
+// from both sides. It also moves the load below the route, where the framework can no longer start it
+// before the first byte. Awaiting belongs to `page/**`, which passes the resolved data down as props.
+//
+// Component-ness is a PascalCase regex on the binding, the same test `no-model-type-in-util-zone.grit`
+// uses. The declarator regex anchors `async` to the initializer position (`[^=]*` cannot cross an `=`),
+// so an async handler declared inside a synchronous component is not read as the component's own body;
+// `not within JsFunctionBody()` drops every nested declaration for the same reason. Out of scope by
+// construction, since neither is a named binding at statement level: an inline `onClick={async () => …}`
+// and an async member of an object literal.
+JsIdentifierBinding() as $name where {
+  $name <: r"[A-Z][A-Za-z0-9_$]*",
+  not $name <: within JsFunctionBody(),
+  not $name <: within JsFormalParameter(),
+  or {
+    $name <: within JsVariableDeclarator() as $decl where {
+      $decl <: r"[A-Z][A-Za-z0-9_$]*\s*(?::[^=]*)?=\s*async[\s\S]*"
+    },
+    $name <: within JsFunctionDeclaration() as $fn where {
+      $fn <: r"(?:export\s+)?(?:default\s+)?async\s+function[\s\S]*"
+    },
+    $name <: within JsFunctionExportDefaultDeclaration() as $default where {
+      $default <: r"(?:export\s+)?(?:default\s+)?async\s+function[\s\S]*"
+    }
+  },
+  register_diagnostic(
+    span = $name,
+    message = "An async component belongs in page/. React has no async client component, so a ui/ component that awaits breaks as soon as a client parent renders it, and the route can no longer start the load before the first byte. Await in the page — or hand an unawaited fetch.* to a Zone as an init / view prop — and take the resolved data as a prop.",
+    severity = "error"
+  )
+}

package/lint/no-bang-comment-in-client.grit

@@ -2,19 +2,32 @@ engine biome(1.0)
 language js(typescript, jsx)
 
 // Bun's bundler classifies `//!` and `/*!` as legal comments (the `@license` / `@preserve` class) and keeps
-// them through `minify: true`, so a `//!` marker in browser-reachable code ships verbatim to every visitor.
+// them through `minify: true`, so a bang marker in browser-reachable code ships verbatim to every visitor.
 // `legalComments` is not a Bun.build option, so the source is the only place to stop it.
-// The two alternatives anchor the marker to line start or to whitespace after code, which keeps a literal
-// like `'https://host//!path'` from tripping the rule. A marker on the file's very first line is trivia that
-// Biome does not expose to the pattern, so it is the one case this rule cannot see.
-JsModule() as $mod where {
-  or {
-    $mod <: r"(?m)(?s).*^[ \t]*//!.*",
-    $mod <: r"(?s).*[^\s/][ \t]+//!.*"
+//
+// Matched through `file($name, $body)` rather than a node: a comment is trivia, and Biome's GritQL exposes
+// it to no node pattern — `JsModule()` does not even match as a top-level pattern, which is why the earlier
+// node-based spelling of this rule reported nothing at all.
+//
+// Two consequences, both measured (`local/review-2/data/probes/grit-node-probe.sh`):
+//   1. `$body` is the module's *token* span, so interior trivia is visible but the leading and trailing
+//      trivia are not — a marker above the first statement or below the last one is unreachable from
+//      GritQL. Those two positions are the rule's blind spot.
+//   2. `$body` is the whole file, so the diagnostic lands on line 1 whatever line the marker is on, and a
+//      regex capture carries no range to report instead. Search the file for the marker to find it.
+//
+// The alternations anchor the marker to line start or to whitespace after code, which keeps a literal like
+// `'https://host//!path'` from tripping the rule.
+file($name, $body) where {
+  $body <: or {
+    r"(?ms).*^[ \t]*//!.*",
+    r"(?s).*[^\s/][ \t]+//!.*",
+    r"(?ms).*^[ \t]*/\*!.*",
+    r"(?s).*[^\s/][ \t]+/\*!.*"
   },
   register_diagnostic(
-    span = $mod,
-    message = "The `//!` marker survives minification (Bun keeps it as a legal comment) and ships to the browser. Use `// FIXME:` or `// TODO:` in client-reachable code; keep `//!` for server, srvkit, and CLI files.",
+    span = $body,
+    message = "A `//!` or `/*!` marker survives minification (Bun keeps it as a legal comment) and ships to the browser. Use `// FIXME:` or `// TODO:` in client-reachable code; keep the bang form for server, srvkit, and CLI files. This diagnostic is file-level — search the file for the marker.",
     severity = "error"
   )
 }

package/lint/no-daisyui-legacy-class.grit

@@ -2,19 +2,36 @@ engine biome(1.0)
 language js(typescript, jsx)
 
 // daisyUI was removed from the UI system; its component classes (`btn-primary`, `card-body`,
-// `mockup-code`, ...) no longer have any CSS behind them and silently render unstyled. Grit
-// port of styleGuard's `daisyui-legacy` rule (frontendBuild/styleGuard.ts) — keep in sync.
+// `mockup-code`, ...) and its colour slots (`bg-base-100`, `text-base-content`, `bg-error`)
+// no longer have any CSS behind them and silently render unstyled.
+// Cases: lint/__fixtures__/no-daisyui-legacy-class/{bad,good}.tsx
 // Only high-signal compound names are matched; bare ambiguous words that collide with
-// Tailwind or app classes (`card`, `input`, `badge`, `btn`) are deliberately not flagged.
+// Tailwind or app classes (`card`, `input`, `badge`, `btn`, `divider`) are deliberately not
+// flagged, and colour slots that survived into the semantic vocabulary (`primary`, `info`,
+// `success`, `warning`, `neutral`) are not either — only the slots the vocabulary dropped.
+// Biome keeps only the first diagnostic a single plugin registers on a node, so a string
+// carrying both halves reports the component one and surfaces the colour one on the next run.
 or {
   JsxString() as $s,
   JsStringLiteralExpression() as $s,
   JsTemplateChunkElement() as $s
 } where {
-  $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
-  register_diagnostic(
-    span = $s,
-    message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
-    severity = "error"
-  )
+  any {
+    and {
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      register_diagnostic(
+        span = $s,
+        message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
+        severity = "error"
+      )
+    },
+    and {
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)-(?:base-(?:100|200|300|content)|(?:primary|secondary|accent|neutral|info|success|warning|error)-content|error)(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      register_diagnostic(
+        span = $s,
+        message = "daisyUI colour slot - the closed colour vocabulary has no CSS for it, so this renders unstyled. base-100/200/300 -> background/muted/border, base-content -> foreground, <colour>-content -> <colour>-foreground, error -> destructive.",
+        severity = "error"
+      )
+    }
+  }
 }

package/lint/no-deprecated-log-level.grit

@@ -0,0 +1,17 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// The level ladder no longer has a `log` tier: `logger.log()` and `Logger.log()` are kept for compatibility
+// and emit at `info`, so a call reads like a distinct level and is not one. The receiver regex admits the
+// instance field (`this.logger`, `this.#logger`), a local (`logger`) and the static class (`Logger`), and
+// nothing else — `console.log` is biome's own `noConsole` rule.
+//
+// No autofix: Biome does not apply plugin rewrites, and the rename is a one-word edit at each site.
+`$recv.log($arg)` as $call where {
+  $recv <: r"(?:this\.)?#?[lL]ogger",
+  register_diagnostic(
+    span = $call,
+    message = "`.log()` is deprecated and emits at `info`. Call `.info()` instead.",
+    severity = "error"
+  )
+}

package/lint/no-init-fetch-in-client.grit

@@ -0,0 +1,47 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `fetch.init<Model><Suffix>` is not a request, it is a hydration snapshot. `#registerSlice`
+// (pkgs/akanjs/fetch/client/fetchClient.ts) composes it out of the slice's list and insight queries and
+// returns a `ServerInit` whose only consumer is the `init` prop of `Load.Units` / `Load.View`, which
+// writes it into the store before React ever renders. `fetch.get<Model>Init<Suffix>` is the same call
+// returning the payload alone. Run from a route they resolve before the first byte and the markup ships
+// populated; run after hydration they are two extra round-trips for a shell the browser already painted
+// empty, landing in a local variable no store reads — `Load.*` seeds state, so a value held in a client
+// closure reaches nothing.
+//
+// The client is not missing the load, only this spelling of it: every slice also generates
+// `st.do.init<Model><Suffix>` (pkgs/akanjs/store/action.ts), which runs the same two queries and commits
+// them to state.
+//
+// Both names are matched by shape, since a lint rule cannot know which slices exist. The generated one is
+// `init` + `Capitalize<refName>` + `Capitalize<suffix>`, so it always carries two capital-led segments —
+// requiring the second one is what keeps a hand-written `initPayment` / `initSession` endpoint out, while
+// `initializeSomething` was never at risk (`init` is followed by a lowercase letter). What is left over is a
+// custom endpoint that happens to spell the generated shape exactly, `initPaymentSession` or
+// `get<X>Init<Y>`; suppress that one with `// biome-ignore lint/plugin: <reason>`.
+//
+// `view`/`edit` hydrate the same way but are not matched here: `edit<X>` is a plausible custom endpoint
+// name, whereas the two shapes above are not.
+//
+// The gate is the file. `JsDirective` anchors `"use client"` to the real directive — docs pages carry the
+// same text as an ordinary string literal and inside sample code, and neither is one. `*.store.ts` is
+// added by name because a store is client-only by role and carries no directive.
+JsCallExpression() as $call where {
+  $call <: `fetch.$endpoint($...)`,
+  $endpoint <: or {
+    r"init[A-Z][A-Za-z0-9_$]*[A-Z][A-Za-z0-9_$]*",
+    r"get[A-Z][A-Za-z0-9_$]*Init[A-Z][A-Za-z0-9_$]*"
+  },
+  or {
+    $filename <: r".*\.store\.ts",
+    $call <: within JsModule() as $module where {
+      $module <: contains JsDirective() as $directive where { $directive <: r"[\s\S]*use client[\s\S]*" }
+    }
+  },
+  register_diagnostic(
+    span = $call,
+    message = "This is a server-side hydration call. It composes the slice's list and insight queries into a snapshot whose only consumer is the init prop of Load.Units / Load.View, so on the client it costs two extra round-trips for a shell the browser already painted, and the result lands in a value nothing reads. Load it in the route — await fetch.initXInY(...) in page/** and pass the result down as an init prop, or hand the unawaited promise to a Zone and let Load.* resolve it behind a skeleton. To reload from the client, call the generated store action st.do.initXInY() instead, which writes the same data into state.",
+    severity = "error"
+  )
+}

package/lint/no-inline-color.grit

@@ -2,18 +2,20 @@ engine biome(1.0)
 language js(typescript, jsx)
 
 // Color literals inside `style={{ ... }}` bypass the class scanner, the semantic token layer,
-// and theme switching entirely. Grit port of styleGuard's `inline-color` rule
-// (frontendBuild/styleGuard.ts) — keep in sync. `var(--token)` references do not match.
+// and theme switching entirely. `var(--token)` references do not match.
 //
-// Known delta vs the TS guard: color literals inside a `<style>` tag's template body are not
-// matched here (template chunks are not scoped by this pattern); the build-gate styleGuard
-// still covers that case.
-JsStringLiteralExpression() as $s where {
-  $s <: within `style={$obj}`,
+// The `<style>` arm covers the same literal in a tag body, which is the other way a color reaches
+// the page without passing the vocabulary. Both arms are needed because the two sites are different
+// node kinds — a string in an object property, and a chunk of a template literal.
+// Cases: lint/__fixtures__/no-inline-color/{bad,good}.tsx
+or {
+  JsStringLiteralExpression() as $s where { $s <: within `style={$obj}` },
+  JsTemplateChunkElement() as $s where { $s <: within `<style>$body</style>` }
+} where {
   $s <: r"[\s\S]*(?:#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb)\()[\s\S]*",
   register_diagnostic(
     span = $s,
-    message = "Inline color literal in a style object bypasses semantic tokens and theme switching. Use a token class, or style={{ color: 'var(--primary)' }} when a runtime value is unavoidable.",
+    message = "Inline color literal bypasses semantic tokens and theme switching. Use a token class, or style={{ color: 'var(--primary)' }} when a runtime value is unavoidable.",
     severity = "error"
   )
 }

package/lint/no-interpolated-arbitrary-class.grit

@@ -7,9 +7,9 @@ language js(typescript, jsx)
 // literal of the same shape happens to exist elsewhere in the codebase: the default value works by accident
 // while every override dies quietly (that is exactly how `Empty`'s minHeight went unnoticed).
 //
-// Grit port of styleGuard's `interpolated-arbitrary` rule (frontendBuild/styleGuard.ts) — keep the two
-// regexes in sync. Matching template *chunks* is what makes this detectable: the chunk before `${` still
-// carries the unterminated `-[`.
+// Matching template *chunks* is what makes this detectable: the chunk before `${` still carries the
+// unterminated `-[`.
+// Cases: lint/__fixtures__/no-interpolated-arbitrary-class/{bad,good}.tsx
 //
 // The fix is a style prop for the runtime value (`style={{ minHeight }}`) — dimensions are not colors, so
 // no-inline-color does not apply — or a fixed set of literal classes when the value comes from an enum.

package/lint/no-model-type-in-util-zone.grit

@@ -0,0 +1,58 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `Util` and `Zone` are always client components, so a *prop* typed as a `cnst` model is a hydrated
+// class instance the server has to hand across the boundary — the methods are stripped on the way and
+// what arrives is a plain object wearing the model's type.
+//
+// Only prop positions are reported: the component's `*Props` interface / type alias, or the inline
+// object type on its parameter. A `cnst` type anywhere else in the file never crosses the boundary and
+// stays legal — a local annotation, a callback parameter the framework already types with the model
+// (`renderItem`, `renderList`), a module-scope helper, a non-`Props` local shape, and the props of a
+// component nested inside another one. A function-typed prop is client-internal too: a closure cannot
+// cross the RSC boundary at all, so whoever passes it already holds the value it takes.
+//
+// The exempt generics are the framework props types whose model parameter never lands on a prop as
+// data: `ClientInit` / `ClientView` / `ClientEdit` (mapped to plain `GetStateObject`) and `ModelsProps`,
+// whose only use of the model is `onClickItem?: (model: M) => unknown` — a callback, so the caller
+// already holds the value. `ModelProps<"x", cnst.LightX>` is *not* exempt: it spreads the model onto
+// the props themselves.
+TsReferenceType() as $ref where {
+  $ref <: r"cnst\.[A-Za-z_$][A-Za-z0-9_$]*",
+  not $ref <: within TsIndexedAccessType() as $indexed where {
+    $indexed <: r"cnst\.[A-Za-z_$][A-Za-z0-9_$]*\[.value.\][\s\S]*"
+  },
+  not $ref <: within TsReferenceType() as $wrapper where {
+    $wrapper <: r"(?:(?:Client|Server)(?:Init|View|Edit)|ModelsProps)<[\s\S]*"
+  },
+  not $ref <: within TsFunctionType(),
+  or {
+    $ref <: within TsInterfaceDeclaration() as $propsInterface where {
+      $propsInterface <: r"interface\s+[A-Za-z0-9_$]*Props[\s\S]*"
+    },
+    $ref <: within TsTypeAliasDeclaration() as $propsAlias where {
+      $propsAlias <: r"type\s+[A-Za-z0-9_$]*Props[\s\S]*"
+    },
+    and {
+      $ref <: within JsFormalParameter(),
+      // A parameter is a sibling of the body, so this only drops the ones belonging to a function
+      // declared *inside* a component — a nested component or a local callback.
+      not $ref <: within JsFunctionBody(),
+      // Same for a callback handed straight to a call, which an expression-bodied component leaves
+      // outside every function body: `rows.map((row: cnst.LightTicket) => …)`.
+      not $ref <: within JsCallArguments(),
+      or {
+        $ref <: within JsVariableDeclarator() as $component where {
+          $component <: r"[A-Z][A-Za-z0-9_$]*[\s\S]*"
+        },
+        $ref <: within JsFunctionDeclaration() as $componentFn where {
+          $componentFn <: r"(?:async\s+)?function\s+[A-Z][A-Za-z0-9_$]*[\s\S]*"
+        }
+      }
+    }
+  },
+  register_diagnostic(
+    span = $ref,
+    message = "Util and Zone are client components, so a cnst model type on a prop is a class instance crossing the server boundary. Take an id instead (bannerId: string), or hand server data across as ClientInit / ClientView. An enum union such as cnst.AdminRole['value'] is allowed, and so is a cnst type that stays inside the file — a local annotation or a callback parameter."
+  )
+}

package/lint/no-raw-palette-class.grit

@@ -3,9 +3,9 @@ language js(typescript, jsx)
 
 // Vocabulary closure (`@theme { --color-*: initial }` in akanjs/ui/styles.css) strips the raw
 // Tailwind palette, so classes like `bg-blue-500` generate NO css and silently render as
-// currentColor/transparent. This rule surfaces that silent breakage at lint time. It is the
-// grit port of styleGuard's `raw-palette` rule (frontendBuild/styleGuard.ts) — keep the two
-// regexes in sync. Matching string/template nodes (not raw text) skips comments for free.
+// currentColor/transparent. This rule surfaces that silent breakage at lint time. Matching
+// string/template nodes (not raw text) skips comments for free.
+// Cases: lint/__fixtures__/no-raw-palette-class/{bad,good}.tsx
 //
 // Bare `bg-neutral` is a semantic token and allowed; the numeric suffix (`bg-neutral-500`)
 // is what marks a raw palette class. black/white stay in the vocabulary for overlays.

package/lint/no-unpublished-form-setter.grit

@@ -0,0 +1,41 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A form control publishes its own setter by reading the action off the function it was handed
+// (`actionTagOf` in pkgs/akanjs/store/actionTag.ts). A setter passed by reference names the field it
+// writes, so the control emits `data-akan-action` and `useFieldTool` publishes the field to the in-page
+// agent. An arrow that only forwards its argument is a fresh anonymous closure carrying neither, so the
+// field silently becomes unreachable to the agent, to an E2E selector, and to the accessibility tree —
+// while looking identical to a reader. Generated field setters take exactly one value
+// (`makeFormSetter` in pkgs/akanjs/store/action.ts), so the wrapper never changes what runs.
+//
+// Only a pure forwarding body is reported: the argument reaches the setter unchanged, as the sole
+// statement. Each other shape has its own home, so none of them is reported here:
+//
+//   normalize  `(v) => set(formatPhone(v))`      -> the control's own `transform` prop, which every text and
+//                                                   number `Field.*` already takes. Keep `onChange` a reference.
+//   composite  `(v) => { set(v); other(v); }`    -> a `_postSet<Field>` method on the store, with the generated
+//                                                   setter left on the control. A generated action cannot be
+//                                                   overridden: mapped types make them properties (TS2425).
+//   nested     `(v) => writeOnX('a.3.b', v)`     -> unannotatable by design. An agent reaches an embedded row
+//                                                   through `fill<Model>Form`, which waves composites through.
+//
+// A typed parameter (`(v: string) => st.do.setVOnX(v)`) is not matched: the parameter and the argument
+// bind to different text, so the metavariable cannot unify them. Under-reporting, not a false positive.
+//
+JsxAttribute() as $attr where {
+  $attr <: contains JsArrowFunctionExpression() as $arrow,
+  $arrow <: `($p) => $body`,
+  // One bare parameter. A metavariable matches a whole parameter list leniently, so `(a, b)` binds the
+  // text "a, b" and is excluded here rather than by the snippet.
+  $p <: r"[A-Za-z_$][A-Za-z0-9_$]*",
+  $body <: contains `st.do.$action($p)` as $call,
+  $action <: r"set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*",
+  // The body is that call and nothing else — `r"..."` is a full match, so an extra statement fails it.
+  $body <: r"\{?\s*(?:void\s+|await\s+)?st\.do\.[A-Za-z0-9_$]+\([A-Za-z_$][A-Za-z0-9_$]*\)\s*;?\s*\}?",
+  register_diagnostic(
+    span = $arrow,
+    message = "This arrow only forwards its argument, and an anonymous closure names no action — the control publishes no agent tool and emits no data-akan-action for the field. Pass the setter by reference: onChange={st.do.setTypeOnTicket}. A wrapper that does more is not reported: normalization belongs in the control's transform prop, a multi-write belongs in a _postSet<Field> hook on the store, and a nested path through writeOnX is reached by the agent through fill<Model>Form.",
+    severity = "error"
+  )
+}

package/lint/non-scalar-props-restricted.grit

@@ -1,10 +1,19 @@
-`$name={$value}` where {
-  or {
-    $value <: `($$$_) => $_`,
-    $value <: `$_ => $_`,
-    $value <: `function($$$_) { $$$_ }`,
-    $value <: `function $fnName($$$_) { $$$_ }`
-  },
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A function prop cannot cross the RSC boundary: a closure has no serialized form, so a server component
+// handing one down fails at the boundary rather than at the call. `loader`, `render` and `of` are the
+// framework's own slots, which take the function on the client side of the boundary.
+//
+// The attribute is matched by node fields rather than by a `$name={$value}` snippet: Biome's GritQL does
+// not parse a bare snippet in that shape as a JsxAttribute, so the snippet form matches nothing at all.
+// Reading `expression` off the initializer is also what keeps the value anchored to this attribute — a
+// `contains` would reach into nested JSX and report `item={item}` inside `render={(item) => <Row item={item} />}`.
+JsxAttribute(
+  name = $name,
+  initializer = JsxAttributeInitializerClause(value = JsxExpressionAttributeValue(expression = $value))
+) where {
+  $value <: or { JsArrowFunctionExpression(), JsFunctionExpression() },
   not $name <: or { `loader`, `render`, `of` },
   register_diagnostic(
     span = $name,