@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.81

package/lint/__fixtures__/README.md

@@ -0,0 +1,40 @@
+# grit rule fixtures
+
+One folder per `lint/*.grit` rule. `gritRules.test.ts` runs biome with that one plugin enabled and asserts
+`bad` reports **exactly** the marked lines and `good` reports nothing — so a rule that silently stops
+matching after a biome upgrade fails the suite instead of going quiet, and `every rule in this folder has a
+fixture` fails when a rule is added without one.
+
+## Contract
+
+- One case per line. `// @flag` marks a line the rule must report in `bad`; `// @ok` marks a line in `good`.
+- The `bad` assertion is 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.
+- `good` is the half that matters most: an over-matching rule is what makes developers distrust the gate.
+- `fixture.json` is optional:
+  - `path` — where the source is written inside the temp workspace, for a rule that reads `$filename`
+    (`no-deep-internal-import`, `no-redeclare-predefined-endpoint`). Its extension also picks which of
+    `bad.ts` / `bad.tsx` is read.
+  - `expect: "file"` — for a rule whose span is the whole file (`no-bang-comment-in-client`), where there is
+    no per-line diagnostic to match. `bad` must report at least once.
+- A rule with two independent gates gets one subfolder per gate (`no-init-fetch-in-client/{use-client,store-file}`).
+- These files are excluded from the repo's own biome run (root `biome.json` `files.includes`) and from
+  `tsc` (`tsconfig.json` `exclude`), because they reference undeclared identifiers on purpose and the
+  formatter would reorder the class strings the vocabulary fixtures test.
+
+## Biome GritQL constraints these fixtures pinned down
+
+Each of these made a rule silently report nothing, and each was found by adding the fixture:
+
+- A bare snippet in JSX-attribute shape (`` `$name={$value}` ``) matches **no** JsxAttribute. Match the node
+  and read its fields: `JsxAttribute(name = $name, initializer = ...)`.
+- `JsModule()` never matches as a top-level pattern, and no node pattern is given comment trivia. A rule
+  about comments has to go through `file($name, $body)`, whose span is the whole file.
+- `file()`'s `$body` is the module's **token** span: interior trivia is visible, the leading and trailing
+  trivia are not. So a comment above the first statement or below the last one is unreachable from GritQL —
+  that is `no-bang-comment-in-client`'s blind spot, and why its fixture puts the marker between statements.
+- A regex capture (`r"..."($var)`) carries no source range: a diagnostic spanned on one gets no location,
+  and `$var` does not interpolate into a `message`.
+
+The five vocabulary fixtures were ported from `frontendBuild/styleGuard.test.ts`, the pre-grit
+implementation of the same rules, when that scanner was retired.

package/lint/__fixtures__/no-arbitrary-color/bad.tsx

@@ -0,0 +1,3 @@
+export const HexValue = () => <div className="bg-[#3b82f6]" />; // @flag
+export const ColorFunctionValue = () => <div className="text-[rgb(0,0,0)]" />; // @flag
+export const HslValue = () => <div className="border-[hsl(210,100%,50%)]" />; // @flag

package/lint/__fixtures__/no-arbitrary-color/good.tsx

@@ -0,0 +1,4 @@
+export const CssVariableShorthand = () => <div className="bg-[--brand]" />; // @ok
+export const CssVariableFunction = () => <div className="text-[var(--fg)]" />; // @ok
+export const ArbitrarySizeNotColor = () => <div className="min-h-[300px] w-[42ch]" />; // @ok
+export const SemanticToken = () => <div className="bg-primary" />; // @ok

package/lint/__fixtures__/no-async-component-in-ui/bad.tsx

@@ -0,0 +1,4 @@
+export const Card = async () => <div className="flex" />; // @flag
+export const Typed: FC = async () => <div className="flex" />; // @flag
+export async function Panel() { return <div className="flex" />; } // @flag
+export default async function Shell() { return <div className="flex" />; } // @flag

package/lint/__fixtures__/no-async-component-in-ui/good.tsx

@@ -0,0 +1,4 @@
+export const Card = () => <div className="flex" />; // @ok
+export const Handler = () => { const onSave = async () => save(); return <button onClick={onSave} />; }; // @ok
+export const loadThing = async () => await fetchThing(); // @ok
+export function Panel() { return <div className="flex" />; } // @ok

package/lint/__fixtures__/no-bang-comment-in-client/bad.tsx

@@ -0,0 +1,4 @@
+export const a = 1;
+//! FIXME: this marker survives minification and ships to every visitor
+/*! and so does the block form */
+export const b = 2;

package/lint/__fixtures__/no-bang-comment-in-client/fixture.json

@@ -0,0 +1 @@
+{ "expect": "file" }

package/lint/__fixtures__/no-bang-comment-in-client/good.tsx

@@ -0,0 +1,3 @@
+// FIXME: the client-reachable spelling of the same note // @ok
+export const url = "https://host//!path"; // @ok
+export const a = 1; // @ok

package/lint/__fixtures__/no-daisyui-legacy-class/bad.tsx

@@ -0,0 +1,7 @@
+export const CompoundButton = () => <button className="btn-primary" />; // @flag
+export const CompoundBadge = () => <span className="badge-success" />; // @flag
+export const DroppedBaseSurface = () => <div className="bg-base-100" />; // @flag
+export const DroppedBaseContentWithOpacity = () => <div className="text-base-content/70" />; // @flag
+export const DroppedBaseOnABorderSide = () => <div className="border-t-base-300" />; // @flag
+export const DroppedPrimaryContent = () => <div className="text-primary-content" />; // @flag
+export const DroppedErrorSlot = () => <div className="bg-error/5" />; // @flag

package/lint/__fixtures__/no-daisyui-legacy-class/good.tsx

@@ -0,0 +1,5 @@
+export const BareAmbiguousNamesCollideWithTailwind = () => <div className="card input badge btn" />; // @ok
+export const SurvivingSemanticPair = () => <div className="bg-primary text-primary-foreground" />; // @ok
+export const SurvivingStatusTokens = () => <div className="bg-neutral text-info border-warning" />; // @ok
+export const DestructiveReplacesError = () => <div className="bg-destructive/10 text-destructive" />; // @ok
+export const UnrelatedContentUtilities = () => <div className="content-center justify-content" />; // @ok

package/lint/__fixtures__/no-deep-internal-import/bad.tsx

@@ -0,0 +1,3 @@
+import { userConstant } from "@libs/shared/lib/user/user.constant"; // @flag
+import { helper } from "../../common/helper"; // @flag
+import * as cnst from "../cnst"; // @flag

package/lint/__fixtures__/no-deep-internal-import/fixture.json

@@ -0,0 +1 @@
+{ "path": "apps/demo/lib/task/Task.Zone.tsx" }

package/lint/__fixtures__/no-deep-internal-import/good.tsx

@@ -0,0 +1,3 @@
+import { cnst, st } from "@apps/demo/client"; // @ok
+import { Task } from "./task.constant"; // @ok
+import { env } from "@apps/demo/env/env.client"; // @ok

package/lint/__fixtures__/no-deprecated-log-level/bad.tsx

@@ -0,0 +1,4 @@
+export const viaLocal = () => logger.log("x"); // @flag
+export const viaStatic = () => Logger.log("x"); // @flag
+export class ViaField { run() { this.logger.log("x"); } } // @flag
+export class ViaPrivateField { run() { this.#logger.log("x"); } } // @flag

package/lint/__fixtures__/no-deprecated-log-level/good.tsx

@@ -0,0 +1,4 @@
+export const infoIsTheReplacement = () => logger.info("x"); // @ok
+export const otherLevelsAreFine = () => logger.warn("x"); // @ok
+export const anUnrelatedReceiverIsNotTheLadder = () => auditTrail.log("x"); // @ok
+export const consoleIsBiomesOwnRule = () => console.log("x"); // @ok

package/lint/__fixtures__/no-import-client-functions/bad.tsx

@@ -0,0 +1,2 @@
+import { useState } from "react"; // @flag
+import { st } from "../st"; // @flag

package/lint/__fixtures__/no-import-client-functions/good.tsx

@@ -0,0 +1,4 @@
+import type { ReactNode } from "react"; // @ok
+import { cnst } from "@libs/shared/client"; // @ok
+import { usePage } from "akanjs/client"; // @ok
+export const Card = ({ children }: { children: ReactNode }) => <div>{children}</div>; // @ok

package/lint/__fixtures__/no-import-client-in-server/bad.tsx

@@ -0,0 +1,6 @@
+import { TaskStore } from "./task.store"; // @flag
+import { Card } from "./Task.Unit"; // @flag
+import { Button } from "@libs/shared/ui"; // @flag
+import { useSpeech } from "@libs/util/webkit"; // @flag
+import { cn } from "akanjs/client"; // @flag
+import { st } from "../st"; // @flag

package/lint/__fixtures__/no-import-client-in-server/good.tsx

@@ -0,0 +1,5 @@
+import type { TaskStore } from "./task.store"; // @ok
+import * as cnst from "../cnst"; // @ok
+import * as db from "../db"; // @ok
+import { Err } from "../dict"; // @ok
+import { Admin } from "@libs/shared/srvkit"; // @ok

package/lint/__fixtures__/no-import-external-library/bad.tsx

@@ -0,0 +1,4 @@
+import dayjs from "dayjs"; // @flag
+import { z } from "zod"; // @flag
+import fs from "node:fs"; // @flag
+import { clsx } from "clsx"; // @flag

package/lint/__fixtures__/no-import-external-library/good.tsx

@@ -0,0 +1,5 @@
+import { Ticket } from "./ticket.constant"; // @ok
+import { cnst } from "@libs/shared/client"; // @ok
+import { field } from "akanjs/constant"; // @ok
+import { useState } from "react"; // @ok
+import { test } from "bun:test"; // @ok

package/lint/__fixtures__/no-import-server-in-client/bad.tsx

@@ -0,0 +1,6 @@
+import { TaskService } from "./task.service"; // @flag
+import { TaskModel } from "./task.document"; // @flag
+import { Admin } from "@libs/shared/srvkit"; // @flag
+import { AkanServer } from "akanjs/server"; // @flag
+import * as db from "../db"; // @flag
+import { Err } from "../dict"; // @flag

package/lint/__fixtures__/no-import-server-in-client/good.tsx

@@ -0,0 +1,4 @@
+import type { TaskService } from "./task.service"; // @ok
+import * as cnst from "../cnst"; // @ok
+import { st } from "../st"; // @ok
+import { Err, Task } from "@libs/shared/client"; // @ok

package/lint/__fixtures__/no-init-fetch-in-client/store-file/bad.ts

@@ -0,0 +1 @@
+export class TaskStore { async reload(orgId: string) { const snapshot = await fetch.initTaskInOrg(orgId); } } // @flag

package/lint/__fixtures__/no-init-fetch-in-client/store-file/fixture.json

@@ -0,0 +1 @@
+{ "path": "apps/demo/lib/task/task.store.ts" }

package/lint/__fixtures__/no-init-fetch-in-client/store-file/good.ts

@@ -0,0 +1 @@
+export class TaskStore { async reload() { await st.do.initTaskInOrg(); } } // @ok

package/lint/__fixtures__/no-init-fetch-in-client/use-client/bad.tsx

@@ -0,0 +1,4 @@
+"use client";
+
+export const A = () => { void fetch.initTaskInOrg(orgId); }; // @flag
+export const B = () => { void fetch.getTaskInitInOrg(orgId); }; // @flag

package/lint/__fixtures__/no-init-fetch-in-client/use-client/good.tsx

@@ -0,0 +1,5 @@
+"use client";
+
+export const C = () => { void fetch.initPayment(sessionId); }; // @ok
+export const D = () => { void st.do.initTaskInOrg(); }; // @ok
+export const E = () => { void fetch.viewTask(taskId); }; // @ok

package/lint/__fixtures__/no-inline-color/bad.tsx

@@ -0,0 +1,3 @@
+export const HexInStyleObject = () => <div style={{ color: "#fff" }} />; // @flag
+export const RgbInStyleObject = () => <div style={{ background: "rgb(0,0,0)" }} />; // @flag
+export const ColorLiteralInStyleTag = () => <style>{`.x { color: #abcdef; }`}</style>; // @flag

package/lint/__fixtures__/no-inline-color/good.tsx

@@ -0,0 +1,3 @@
+export const VarReferenceInStyleObject = () => <div style={{ color: "var(--primary)" }} />; // @ok
+export const NonColorStyleProperty = () => <div style={{ width: "100%" }} />; // @ok
+export const ComputedNonColorStyle = () => <div style={{ minHeight }} />; // @ok

package/lint/__fixtures__/no-interpolated-arbitrary-class/bad.tsx

@@ -0,0 +1,3 @@
+export const SizeFromRuntimeExpression = () => <div className={`min-h-[${minHeight}px] flex`} />; // @flag
+export const ColorFromRuntimeExpression = () => <div className={`bg-[${color}] w-full`} />; // @flag
+export const BrokenBracketSwallowsNextClass = () => <div className={`min-h-[ w-full${minHeight}px] flex`} />; // @flag

package/lint/__fixtures__/no-interpolated-arbitrary-class/good.tsx

@@ -0,0 +1,3 @@
+export const LiteralArbitraryValue = () => <div className="min-h-[300px] flex" />; // @ok
+export const InterpolationOutsideBrackets = () => <div className={`flex gap-2 ${isOpen ? "opacity-50" : ""}`} />; // @ok
+export const InterpolationInStylePropNotClass = () => <div style={{ minHeight }} className={`flex ${extra}`} />; // @ok

package/lint/__fixtures__/no-js-private-class-method/bad.tsx

@@ -0,0 +1,3 @@
+export class SyncPrivate { #compute() { return 1; } } // @flag
+export class AsyncPrivate { async #load() { return 1; } } // @flag
+export class CallsPrivate { run() { this.#compute(); } } // @flag

package/lint/__fixtures__/no-js-private-class-method/good.tsx

@@ -0,0 +1,3 @@
+export class TypescriptPrivate { private _compute() { return 1; } } // @ok
+export class CallsUnderscore { run() { this._compute(); } } // @ok
+export class PrivateField { #cache = new Map(); } // @ok

package/lint/__fixtures__/no-model-type-in-util-zone/bad.tsx

@@ -0,0 +1,3 @@
+export interface CardProps { task: cnst.Task; } // @flag
+export type RowProps = { banner: cnst.LightBanner }; // @flag
+export const View = ({ task }: { task: cnst.Task }) => <div className="flex" />; // @flag

package/lint/__fixtures__/no-model-type-in-util-zone/good.tsx

@@ -0,0 +1,6 @@
+export interface IdProps { taskId: string; } // @ok
+export interface EnumProps { role: cnst.AdminRole["value"]; } // @ok
+export interface InitProps { init: ClientInit<cnst.Task>; } // @ok
+export interface CallbackProps { onPick: (task: cnst.Task) => void; } // @ok
+export interface ModelsWrapperProps { models: ModelsProps<cnst.Task>; } // @ok
+export const localAnnotationStaysInFile = (raw: unknown) => raw as cnst.Task; // @ok

package/lint/__fixtures__/no-raw-palette-class/bad.tsx

@@ -0,0 +1,6 @@
+export const TwoInOneString = () => <div className="bg-blue-500 text-gray-700" />; // @flag
+export const VariantPrefixAndOpacity = () => <div className="hover:bg-red-500/50" />; // @flag
+export const NumericNeutral = () => <div className="bg-neutral-500" />; // @flag
+export const AlongsideAUrlString = () => <a href="https://x.io" className="bg-blue-500" />; // @flag
+export const BorderSide = () => <div className="border-t-emerald-300" />; // @flag
+export const InsideCn = () => <div className={cn("flex", "text-slate-400")} />; // @flag

package/lint/__fixtures__/no-raw-palette-class/good.tsx

@@ -0,0 +1,8 @@
+export const BareSemanticNeutral = () => <div className="bg-neutral text-neutral-foreground" />; // @ok
+export const SemanticTokens = () => <div className="bg-primary text-muted-foreground border-border" />; // @ok
+export const BlackAndWhiteStayInVocabulary = () => <div className="bg-black text-white bg-white/30 bg-black/50" />; // @ok
+export const NonColorNumericUtilities = () => <div className="gap-4 mt-2 grid-cols-3 w-500" />; // @ok
+export const OpacityOnASemanticToken = () => <div className="text-foreground/70 bg-primary/10" />; // @ok
+// iconClassName="bg-blue-500" — a class name in a line comment is not code
+/** legacy: bg-red-500 */
+export const CommentsAreNotCode = () => <div className="flex" />; // @ok

package/lint/__fixtures__/no-redeclare-predefined-endpoint/bad.ts

@@ -0,0 +1,10 @@
+export class TaskEndpoint extends endpoint(srv.task, ({ query, mutation }) => ({
+  task: query(cnst.Task).exec(() => null), // @flag
+  lightTask: query(cnst.Task).exec(() => null), // @flag
+  createTask: mutation(cnst.Task).exec(() => null), // @flag
+  updateTask: mutation(cnst.Task).exec(() => null), // @flag
+  removeTask: mutation(cnst.Task).exec(() => null), // @flag
+  viewTask: query(cnst.Task).exec(() => null), // @flag
+  editTask: query(cnst.Task).exec(() => null), // @flag
+  mergeTask: mutation(cnst.Task).exec(() => null), // @flag
+})) {}

package/lint/__fixtures__/no-redeclare-predefined-endpoint/fixture.json

@@ -0,0 +1 @@
+{ "path": "apps/demo/lib/task/task.signal.ts" }

package/lint/__fixtures__/no-redeclare-predefined-endpoint/good.ts

@@ -0,0 +1,6 @@
+export class TaskEndpoint extends endpoint(srv.task, ({ query, mutation }) => ({
+  startTask: mutation(cnst.Task).exec(() => null), // @ok
+  taskSummary: query(cnst.Task).exec(() => null), // @ok
+  viewTaskBoard: query(cnst.Task).exec(() => null), // @ok
+  createTaskComment: mutation(cnst.Task).exec(() => null), // @ok
+})) {}

package/lint/__fixtures__/no-return-in-store-action/bad.tsx

@@ -0,0 +1,2 @@
+export class AStore extends store(sig.a, () => ({})) { load() { return 1; } } // @flag
+export class BStore extends store(sig.b, () => ({})) { async save() { return true; } } // @flag

package/lint/__fixtures__/no-return-in-store-action/good.tsx

@@ -0,0 +1,6 @@
+export class CStore extends store(sig.c, () => ({})) { load() { this.set({ n: 1 }); } } // @ok
+export class DStore extends store(sig.d, () => ({})) { load() { if (!this.get()) return; this.set({ n: 1 }); } } // @ok
+export class EStore extends store(sig.e, () => ({})) { static helper() { return 1; } } // @ok
+export class FStore extends store(sig.f, () => ({})) { get total() { return 1; } } // @ok
+export class GStore extends store(sig.g, () => ({})) { load() { items.map((x) => { return x; }); } } // @ok
+export class HPlain { load() { return 1; } } // @ok

package/lint/__fixtures__/no-throw-raw-error/bad.tsx

@@ -0,0 +1,4 @@
+export const throwsNewError = () => { throw new Error("boom"); }; // @flag
+export const throwsBareError = () => { throw Error("boom"); }; // @flag
+export const throwsWithCause = () => { throw new Error("boom", { cause: reason }); }; // @flag
+export const throwsWithNoArgument = () => { throw new Error(); }; // @flag

package/lint/__fixtures__/no-throw-raw-error/good.tsx

@@ -0,0 +1,4 @@
+export const throwsErr = () => { throw new Err("ticket.error.notFound"); }; // @ok
+export const throwsASubclass = () => { throw new HttpError("boom"); }; // @ok
+export const constructsWithoutThrowing = () => new Error("boom"); // @ok
+export const rethrowsACaught = () => { try { run(); } catch (error) { throw error; } }; // @ok

package/lint/__fixtures__/no-unpublished-form-setter/bad.tsx

@@ -0,0 +1,3 @@
+export const A = () => <Field.Text onChange={(v) => st.do.setNameOnTask(v)} />; // @flag
+export const B = () => <Switch onChange={(value) => void st.do.setDoneOnTask(value)} />; // @flag
+export const C = () => <Select onChange={(v) => { st.do.setTypeOnTask(v); }} />; // @flag

package/lint/__fixtures__/no-unpublished-form-setter/good.tsx

@@ -0,0 +1,5 @@
+export const D = () => <Field.Text onChange={st.do.setNameOnTask} />; // @ok
+export const E = () => <Field.Text onChange={(v) => st.do.setNameOnTask(formatPhone(v))} />; // @ok
+export const F = () => <Field.Text onChange={(v) => { st.do.setNameOnTask(v); track(v); }} />; // @ok
+export const G = () => <Field.Text onChange={(v) => st.do.writeOnTask("rows.3.name", v)} />; // @ok
+export const H = () => <Field.Text onChange={(a, b) => st.do.setNameOnTask(a)} />; // @ok

package/lint/__fixtures__/no-use-client-in-server/bad.tsx

@@ -0,0 +1,3 @@
+"use client"; // @flag
+
+export const Card = () => <div className="flex" />;

package/lint/__fixtures__/no-use-client-in-server/good.tsx

@@ -0,0 +1,2 @@
+export const Card = () => <div className="flex" />; // @ok
+export const note = "server only"; // @ok

package/lint/__fixtures__/non-scalar-props-restricted/bad.tsx

@@ -0,0 +1,5 @@
+export const ArrowProp = () => <Button onClick={() => save()} />; // @flag
+export const ArrowWithTwoParams = () => <Button onSelect={(id, kind) => save(id, kind)} />; // @flag
+export const ArrowWithBareParam = () => <Button onChange={value => save(value)} />; // @flag
+export const FunctionExpressionProp = () => <Button onClick={function () { save(); }} />; // @flag
+export const NamedFunctionProp = () => <Button onClick={function handle() { save(); }} />; // @flag

package/lint/__fixtures__/non-scalar-props-restricted/good.tsx

@@ -0,0 +1,4 @@
+export const LoaderIsAllowed = () => <Zone loader={() => fetchThing()} />; // @ok
+export const OfIsAllowed = () => <Load of={() => fetchThing()} />; // @ok
+export const ScalarProps = () => <Button label="Save" count={3} disabled />; // @ok
+export const IdentifierProp = () => <Button onClick={handleSave} />; // @ok

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"
+  )
+}