@akanjs/devkit 3.0.1 → 3.0.2

package/frontendBuild/devGeneratedIndexSync.ts

@@ -114,7 +114,8 @@ export class DevGeneratedIndexSync {
 
   async #facetContent(dir: string): Promise<string | null> {
     const nameCasePattern = path.basename(dir) === "ui" ? FACET_PASCAL_CASE_RE : FACET_CAMEL_CASE_RE;
-    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => null);
+    if (!entries) return null;
     const exportNames = entries
       .flatMap((entry) => {
         const name = entry.name;
@@ -125,8 +126,8 @@ export class DevGeneratedIndexSync {
         const exportName = name.replace(FACET_SOURCE_FILE_RE, "");
         return nameCasePattern.test(exportName) ? [exportName] : [];
       })
-      .sort();
-    if (exportNames.length === 0) return null;
+      .sort(compareExportNames);
+    if (exportNames.length === 0) return "export {};\n";
     return `${exportNames.map((name) => `export * from "./${name}";`).join("\n")}\n`;
   }
 
@@ -149,10 +150,26 @@ export class DevGeneratedIndexSync {
       if (await exists(path.join(dir, `${modelName}.${type}.tsx`))) fileTypes.push(type);
     }
     if (fileTypes.length === 0) return null;
-    return `\n${fileTypes.map((type) => `import * as ${type} from "./${modelName}.${type}";`).join("\n")}\n\nexport const ${modelName} = { ${fileTypes.join(", ")} };`;
+    return `${fileTypes.map((type) => `import * as ${type} from "./${modelName}.${type}";`).join("\n")}\n\nexport const ${modelName} = { ${fileTypes.join(", ")} };\n`;
   }
 }
 
+//? Biome's organizeImports order, or `akan lint` reorders the barrel: A < a < B < b, a digit before a letter, and a
+//? run of digits compared by its length first. The facetIndex template sorts the same way.
+const letterRankOf = (char: string) => char.toLowerCase().charCodeAt(0) * 2 + (char === char.toLowerCase() ? 1 : 0);
+const digitRunAt = (name: string, idx: number) => /^\d+/.exec(name.slice(idx))?.[0] ?? "";
+const compareExportNames = (a: string, b: string) => {
+  for (let idx = 0; idx < a.length && idx < b.length; ) {
+    const [runA, runB] = [digitRunAt(a, idx), digitRunAt(b, idx)];
+    if (runA && runB && runA !== runB) return runA.length - runB.length || (runA < runB ? -1 : 1);
+    if (runA && runB) idx += runA.length;
+    else if (runA || runB) return runA ? -1 : 1;
+    else if (a.charAt(idx) !== b.charAt(idx)) return letterRankOf(a.charAt(idx)) - letterRankOf(b.charAt(idx));
+    else idx++;
+  }
+  return a.length - b.length;
+};
+
 const exists = async (file: string) =>
   stat(file)
     .then(() => true)

package/frontendBuild/frontendBuild.test.ts

@@ -354,7 +354,7 @@ describe("DevGeneratedIndexSync", () => {
 
     expect(removed.errors).toEqual([]);
     expect(removed.changedFiles).toEqual([index]);
-    expect(await Bun.file(index).exists()).toBe(false);
+    expect(await readFile(index, "utf8")).toBe("export {};\n");
   });
 
   test("ignores server/client folders as barrel facets", async () => {

package/jsonFormatter.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { JsonFormatter } from "./jsonFormatter";
+import { formatWithBiome, hasBiome } from "./testHelpers";
+
+const pad = (length: number) => "x".repeat(length);
+const thousands = Array.from({ length: 40 }, (_, idx) => idx * 1000);
+
+const fixtures: Record<string, unknown> = {
+  collapsed: { scalars: ["accessToken", "accessLog"], empty: [], none: {}, nested: [["a"], [{}]] },
+  commaAtTheEdge: { a: [pad(108)], b: [pad(109)], c: [pad(109)] },
+  objectsInArray: { routes: [{ path: "/" }, { path: "/a" }] },
+  numbers: { sizes: thousands, words: thousands.map(String) },
+  wide: { a: ["한".repeat(54)], b: ["한".repeat(55)] },
+  rootArray: [pad(60), pad(60)],
+};
+
+describe("JsonFormatter", () => {
+  test("collapses an array that fits the line with its trailing comma, and keeps every object expanded", () => {
+    expect(JsonFormatter.stringify(fixtures.collapsed, "akan.lib.json")).toBe(
+      '{\n  "scalars": ["accessToken", "accessLog"],\n  "empty": [],\n  "none": {},\n  "nested": [["a"], [{}]]\n}\n',
+    );
+    expect(JsonFormatter.stringify(fixtures.commaAtTheEdge, "akan.lib.json").split("\n")).toEqual([
+      "{",
+      `  "a": ["${pad(108)}"],`,
+      '  "b": [',
+      `    "${pad(109)}"`,
+      "  ],",
+      `  "c": ["${pad(109)}"]`,
+      "}",
+      "",
+    ]);
+    expect(JsonFormatter.stringify(fixtures.objectsInArray, "akan.lib.json")).toContain('"routes": [\n    {\n');
+  });
+
+  test("fills an array of numbers that overflows, and keeps any other overflowing array one item a line", () => {
+    const [, sizesOpen, firstRow, secondRow] = JsonFormatter.stringify(fixtures.numbers, "akan.app.json").split("\n");
+    expect(sizesOpen).toBe('  "sizes": [');
+    expect(firstRow).toStartWith("    0, 1000, 2000,");
+    expect(firstRow?.length).toBeLessThanOrEqual(JsonFormatter.lineWidth);
+    expect(secondRow).toStartWith("    18000,");
+    expect(JsonFormatter.stringify(fixtures.numbers, "akan.app.json")).toContain('"words": [\n    "0",\n    "1000",');
+  });
+
+  test("measures a wide character as two columns", () => {
+    const [, fits, overflows] = JsonFormatter.stringify(fixtures.wide, "akan.lib.json").split("\n");
+    expect(fits).toBe(`  "a": ["${"한".repeat(54)}"],`);
+    expect(overflows).toBe('  "b": [');
+  });
+
+  test("keeps a package.json expanded the way JSON.stringify writes it", () => {
+    const manifest = { name: "x", workspaces: ["pkgs/*"], dependencies: {} };
+    expect(JsonFormatter.stringify(manifest, "libs/x/package.json")).toBe(`${JSON.stringify(manifest, null, 2)}\n`);
+  });
+
+  test.skipIf(!hasBiome)("prints what Biome prints", async () => {
+    expect(await formatWithBiome('{"a":[1]}', "libs/fixture/akan.lib.json")).toBe('{ "a": [1] }\n');
+    for (const [name, fixture] of Object.entries(fixtures)) {
+      const printed = JsonFormatter.stringify(fixture, `libs/fixture/${name}.json`);
+      expect(await formatWithBiome(printed, `libs/fixture/${name}.json`)).toBe(printed);
+    }
+    const manifest = JsonFormatter.stringify({ name: "x", workspaces: ["a", "b"] }, "package.json");
+    expect(await formatWithBiome(manifest, "libs/fixture/package.json")).toBe(manifest);
+  });
+});

package/jsonFormatter.ts

@@ -0,0 +1,78 @@
+import path from "node:path";
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+interface Placement {
+  column: number;
+  trailing: number;
+}
+
+//* Prints what `biome format` would, or `akan lint` and `akan sync` flip-flop a generated .json. Biome keeps a
+//* package.json fully expanded (`expand: always`); elsewhere (`auto`) it keeps an object expanded, collapses an array
+//* that fits the 120-column line (a trailing comma included), fills an array of numbers, and ends with a newline.
+export class JsonFormatter {
+  static readonly lineWidth = 120;
+
+  static stringify(value: unknown, filePath: string) {
+    const json = JSON.stringify(value, null, 2);
+    if (path.basename(filePath) === "package.json") return `${json}\n`;
+    return `${JsonFormatter.#print(JSON.parse(json) as JsonValue, 0, { column: 0, trailing: 0 })}\n`;
+  }
+
+  static #print(value: JsonValue, depth: number, placement: Placement): string {
+    if (Array.isArray(value)) return JsonFormatter.#printArray(value, depth, placement);
+    if (value === null || typeof value !== "object") return JSON.stringify(value);
+    const entries = Object.entries(value);
+    if (!entries.length) return "{}";
+    const indent = "  ".repeat(depth + 1);
+    const members = entries.map(([key, member], idx) => {
+      const prefix = `${indent}${JSON.stringify(key)}: `;
+      const trailing = idx < entries.length - 1 ? 1 : 0;
+      return `${prefix}${JsonFormatter.#print(member, depth + 1, { column: Bun.stringWidth(prefix), trailing })}`;
+    });
+    return `{\n${members.join(",\n")}\n${"  ".repeat(depth)}}`;
+  }
+
+  static #printArray(items: JsonValue[], depth: number, { column, trailing }: Placement) {
+    if (!items.length) return "[]";
+    const flat = JsonFormatter.#flat(items);
+    if (flat !== null && column + Bun.stringWidth(flat) + trailing <= JsonFormatter.lineWidth) return flat;
+    const indent = "  ".repeat(depth + 1);
+    const isLast = (idx: number) => idx === items.length - 1;
+    const body = items.every((item) => typeof item === "number")
+      ? JsonFormatter.#fill(
+          items.map((item, idx) => `${JSON.stringify(item)}${isLast(idx) ? "" : ","}`),
+          indent,
+        )
+      : items
+          .map((item, idx) => {
+            const placement = { column: indent.length, trailing: isLast(idx) ? 0 : 1 };
+            return `${indent}${JsonFormatter.#print(item, depth + 1, placement)}`;
+          })
+          .join(",\n");
+    return `[\n${body}\n${"  ".repeat(depth)}]`;
+  }
+
+  static #fill(tokens: string[], indent: string) {
+    const lines: string[] = [];
+    let line = "";
+    for (const token of tokens) {
+      if (line && Bun.stringWidth(line) + 1 + Bun.stringWidth(token) <= JsonFormatter.lineWidth) {
+        line = `${line} ${token}`;
+        continue;
+      }
+      if (line) lines.push(line);
+      line = `${indent}${token}`;
+    }
+    return [...lines, line].join("\n");
+  }
+
+  static #flat(value: JsonValue): string | null {
+    if (Array.isArray(value)) {
+      const items = value.map((item) => JsonFormatter.#flat(item));
+      return items.includes(null) ? null : `[${items.join(", ")}]`;
+    }
+    if (value === null || typeof value !== "object") return JSON.stringify(value);
+    return Object.keys(value).length ? null : "{}";
+  }
+}

package/lint/__fixtures__/README.md

@@ -7,9 +7,12 @@ 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.
+- One case per line. In `bad`, `// @flag` marks a line the rule must report as an error and `// @warn` one it
+  must report as a warning; `// @ok` marks a line in `good`.
+- The `bad` assertion is exact, not containment: every marked line is reported once, at its marker's severity,
+  and nothing else is. A marked line nobody reported is a pattern that stopped matching, a reported line nobody
+  marked is the rule reaching further than the fixture claims, a line reported twice is one site reported
+  twice, and a different severity is a tier that moved.
 - `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`
@@ -35,6 +38,12 @@ Each of these made a rule silently report nothing, and each was found by adding
   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`.
+- A code snippet also matches JSX text that parses as it: `` `new Error` `` reports `<code>new Error</code>` in a
+  docs page. Where a rule meets `.tsx`, match the node kind instead (`JsNewExpression(callee = `Error`)`).
+- A regex is anchored by bare concatenation, so a top-level alternation leaks out of the anchors: `r"fill|stroke"`
+  is `^fill|stroke$` and matches `fillOpacity`. Group it: `r"(?:fill|stroke)"`.
+- A `\"` in a GritQL string is unescaped twice and corrupts it: messages quote with `'`, and a regex spells the
+  character `\x22`.
 
 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-double-brace-placeholder/bad.ts

@@ -0,0 +1,22 @@
+export const dictionary = modelDictionary(["en", "ko"])
+  .of((t) => t(["Video Board", "비디오 보드"]).desc(["A board of cuts", "컷 보드"]))
+  .error({
+    videoBlockedByPolicy: [
+      "The provider refused this video: {{reason}}", // @flag
+      "제공자가 거절했습니다: {{reason}}", // @flag
+    ],
+    invalidValues: [
+      "The device rejects these values: {{fields}} ({{command}}).", // @flag
+      "기기가 받지 않는 값입니다: {{fields}} ({{command}}).", // @flag
+    ],
+  })
+  .translate({
+    greeting: [
+      `Hello {{name}}`, // @flag
+      `안녕하세요 {{name}}`, // @flag
+    ],
+    turnSteps: [
+      `Turn ${"left"} in {{steps}} steps`, // @flag
+      "{{steps}}걸음 뒤 회전", // @flag
+    ],
+  });

package/lint/__fixtures__/no-double-brace-placeholder/fixture.json

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

package/lint/__fixtures__/no-double-brace-placeholder/good.ts

@@ -0,0 +1,15 @@
+export const dictionary = modelDictionary(["en", "ko"])
+  .of((t) => t(["Video Board", "비디오 보드"]).desc(["Cuts name a {{slot}} the user types", "컷에 {{슬롯}}을 적습니다"])) // @ok
+  .model((t) => ({
+    refAssets: t(["Ref Assets", "참고 자산"]).desc(["Each plays a {{slot}} of the plan", "기획안의 {{슬롯}}을 맡습니다"]), // @ok
+  }))
+  .endpoint((fn) => ({
+    bindSlot: fn(["Bind Slot", "슬롯 연결"]).desc(["Bind an asset to a {{slot}}", "{{슬롯}}에 자산을 연결합니다"]), // @ok
+  }))
+  .error({
+    videoBlockedByPolicy: ["The provider refused this video: {reason}", "제공자가 거절했습니다: {reason}"], // @ok
+  })
+  .translate({
+    greeting: [`Hello {name}`, `안녕하세요 {name}`], // @ok
+    bracesExplained: ["Wrap a name in { and }", "이름을 { 와 }로 감쌉니다"], // @ok
+  });

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

@@ -1,3 +1,20 @@
 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
+export const FillInAStyleObject = () => <path style={{ fill: "#2b7fff" }} />; // @flag
+export const FillAttribute = () => <path fill="#2b7fff" />; // @warn
+export const StrokeAttribute = () => <path stroke="#909090" />; // @warn
+export const StopColorAttribute = () => <stop stopColor="rgba(255,72,64,0)" />; // @warn
+export const FloodColorAttribute = () => <feDropShadow floodColor="#000" />; // @warn
+export const LightingColorAttribute = () => <feDiffuseLighting lightingColor="hsl(0 0% 100%)" />; // @warn
+export const ColorAttribute = () => <svg color="#5bbad5" />; // @warn
+export const ComponentFillProp = () => <Icon fill="#ffd700" />; // @warn
+export const ExpressionValue = () => <path fill={isActive ? "#ffffff" : fillColor} />; // @warn
+export const TemplateValue = () => <path stroke={`rgb(${red}, 0, 0)`} />; // @warn
+export const GradientWithFallback = () => <path fill="url(#fade) #2b7fff" />; // @warn
+export const StyleWrite = (path: SVGPathElement) => { path.style.fill = "#2b7fff"; }; // @warn
+export const StyleFilterWrite = (path: SVGPathElement) => { path.style.filter = "drop-shadow(0 0 12px rgba(96, 165, 250, 0.7))"; }; // @warn
+export const NestedStyleWrite = (ref: { current: HTMLElement }) => { ref.current.style.background = "#fff"; }; // @warn
+export const ComputedStyleWrite = (el: HTMLElement) => { el.style["background-color"] = "#fff"; }; // @warn
+export const TemplateStyleWrite = (el: HTMLElement) => { el.style.boxShadow = `0 0 ${blur}px rgba(0, 0, 0, 0.3)`; }; // @warn
+export const SetPropertyWrite = (el: HTMLElement) => { el.style.setProperty("--glow", "#60a5fa"); }; // @warn

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

@@ -1,3 +1,16 @@
 export const VarReferenceInStyleObject = () => <div style={{ color: "var(--primary)" }} />; // @ok
 export const NonColorStyleProperty = () => <div style={{ width: "100%" }} />; // @ok
 export const ComputedNonColorStyle = () => <div style={{ minHeight }} />; // @ok
+export const CurrentColorFill = () => <path fill="currentColor" className="text-primary" />; // @ok
+export const NoneAndTransparent = () => <path fill="none" stroke="transparent" />; // @ok
+export const VarStopColor = () => <stop stopColor="var(--primary)" />; // @ok
+export const RuntimeFill = () => <path fill={fillColor} />; // @ok
+export const GradientReference = () => <path fill="url(#fade)" />; // @ok
+export const QuotedGradientReference = () => <path fill="url('#bead')" />; // @ok
+export const HrefIsNotAColorAttribute = () => <use href="#cafe" />; // @ok
+export const VarStyleWrite = (el: HTMLElement) => { el.style.color = "var(--primary)"; }; // @ok
+export const CurrentColorStyleWrite = (el: HTMLElement) => { el.style.fill = "currentColor"; }; // @ok
+export const NonColorStyleWrite = (el: HTMLElement) => { el.style.display = "none"; }; // @ok
+export const FilterReferenceStyleWrite = (el: HTMLElement) => { el.style.filter = "url(#dead)"; }; // @ok
+// biome-ignore lint/plugin: the Google mark keeps its brand colors
+export const SuppressedBrandMark = () => <path fill="#4285f4" />; // @ok

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

@@ -2,3 +2,11 @@ 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
+export const throwsWithoutParens = () => { throw new Error; }; // @flag
+export const rejectsInAPromise = () => new Promise((_, reject) => reject(new Error(`k8s ${path} failed`))); // @warn
+export const rejectsDirectly = () => Promise.reject(new Error("boom")); // @warn
+export const throwsAStoredError = () => { const error = new Error("boom"); throw error; }; // @warn
+export const returnsAnError = () => { return new Error("boom"); }; // @warn
+export const callsWithoutNew = () => Error("boom"); // @warn
+export const causesAnErr = () => { throw new Err("ticket.error.failed", { cause: new Error("boom") }); }; // @warn
+export const throwsAWrappedError = () => { throw wrapError(new Error("boom")); }; // @warn

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

@@ -1,4 +1,11 @@
 export const throwsErr = () => { throw new Err("ticket.error.notFound"); }; // @ok
+export const rejectsWithErr = () => Promise.reject(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
+export const narrowsAnError = (value: unknown) => value instanceof Error; // @ok
+export const readsAnAttachedField = (error: Error & { stderr: string }) => error.stderr; // @ok
+export const capturesAStack = (target: object) => Error.captureStackTrace(target); // @ok
+export const callsAMethodNamedError = () => logger.Error("boom"); // @ok
+export const quotesTheRule = () => "throw new Error('boom')"; // @ok
+export const DocumentsTheRule = () => <code>new Error</code>; // @ok
+export const DocumentsTheCallForm = () => <code>Error("boom")</code>; // @ok

package/lint/__fixtures__/no-unguarded-endpoint/bad.ts

@@ -0,0 +1,20 @@
+export class TaskSlice extends slice(srv.task, { guards: { root: Admin, get: Public, cru: Admin } }, (init) => ({
+  inProject: init().param("projectId", ID).exec(() => null), // @warn
+  inOrg: init({ mcp: false }).param("orgId", ID).exec(() => null), // @warn
+  inAnyone: init({ guards: [] }).exec(() => null), // @warn
+})) {}
+
+export class TaskEndpoint extends endpoint(srv.task, ({ query, mutation, pubsub, message }) => ({
+  taskCount: query(Int).exec(() => 0), // @warn
+  taskOfSlug: query(cnst.Task, { nullable: true }).param("slug", String).exec(() => null), // @warn
+  startTask: mutation(Boolean).exec(() => true), // @warn
+  archiveTask: mutation(Boolean, { guards: [] }).exec(() => true), // @warn
+  noteTask: mutation(Boolean, { nullable, timeout: 500 }).exec(() => true), // @warn
+  taskEvents: pubsub(cnst.Task).exec(() => null), // @warn
+  pingTask: message(Boolean, { timeout: 1000 }).exec(() => true), // @warn
+})) {}
+
+export class NoteSlice extends slice(srv.note, { guards: { get: Public, cru: Admin } }, () => ({})) {} // @warn
+export class LabelSlice extends slice(srv.label, { guards: { root: [], get: Public, cru: Admin } }, () => ({})) {} // @warn
+export class TagSlice extends slice(srv.tag, { mcp: false }, () => ({})) {} // @warn
+export class StampSlice extends slice(srv.stamp, {}, () => ({}), libStampSlice) {} // @warn

package/lint/__fixtures__/no-unguarded-endpoint/fixture.json

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

package/lint/__fixtures__/no-unguarded-endpoint/good.ts

@@ -0,0 +1,28 @@
+export class TaskSlice extends slice(srv.task, { guards: { root: Admin, get: Public, cru: Admin } }, (init) => ({
+  inProject: init({ guards: [Member] }).param("projectId", ID).exec(() => null), // @ok
+  inPublic: init({ guards: [Public], mcp: false }).exec(() => null), // @ok
+  inShared: init(sharedSliceOption).exec(() => null), // @ok
+})) {}
+
+export class TaskEndpoint extends endpoint(srv.task, ({ query, mutation, pubsub, message }) => ({
+  taskCount: query(Int, { guards: [Public] }).exec(() => 0), // @ok
+  startTask: mutation(Boolean, { guards: [User], mcp: false }).exec(() => true), // @ok
+  addTaskFiles: mutation([cnst.File], { guards: [Every], fileUpload: true }).exec(() => []), // @ok
+  taskFrames: pubsub(Binary, { guards: [Admin], backpressure: "queue" }).exec(() => null), // @ok
+  pingTask: message(Boolean, { guards }).exec(() => true), // @ok
+  taskSummary: query(cnst.Task, { ...adminOption, nullable: true }).exec(() => null), // @ok
+  taskOwner: query(cnst.User, { "guards": [Admin] }).exec(() => null), // @ok
+})) {}
+
+export class TaskInternal extends internal(srv.task, ({ interval, initialize }) => ({
+  sweepTasks: interval(60_000).exec(() => null), // @ok
+  bootTasks: initialize().exec(() => null), // @ok
+})) {}
+
+export const describeTask = () => query(cnst.Task); // @ok
+
+export class NoteSlice extends slice(srv.note, { guards: { root: [Admin, Owner], get: Public } }, () => ({}), libNoteSlice) {} // @ok
+export class LabelSlice extends slice(srv.label, { guards: { root: None, get: None, cru: None } }) {} // @ok
+export class TagSlice extends slice(srv.tag, sharedSliceOption, () => ({})) {} // @ok
+export class StampSlice extends slice(srv.stamp, { guards: { ...adminGuards, get: Public } }, () => ({})) {} // @ok
+export class SealSlice extends slice(srv.seal, { guards: sealGuards, mcp: { cru: false } }, () => ({})) {} // @ok

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

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

package/lint/gritRules.test.ts

@@ -102,23 +102,27 @@ const lintFixture = async (fixture: FixtureCase, kind: "bad" | "good") => {
   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,
-    ),
-  };
+  return (JSON.parse(output.slice(start, end + 1)) as { diagnostics?: BiomeDiagnostic[] }).diagnostics ?? [];
 };
 
-//? One case per line is the fixture contract.
+//? One case per line is the fixture contract, and a `bad` line's marker names the severity it is reported at.
+const severityOfMarker = { "// @flag": "error", "// @warn": "warning" } as const;
+
 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 expectedReports = async (fixture: FixtureCase) =>
+  (await readFixture(fixture, "bad")).split("\n").flatMap((line, index) =>
+    Object.entries(severityOfMarker)
+      .filter(([marker]) => line.includes(marker))
+      .map(([, severity]) => `${index + 1}: ${severity}`),
+  );
+
+const byLine = (left: string, right: string) => Number.parseInt(left, 10) - Number.parseInt(right, 10);
+
 const fixtures = await collectCases();
 
 describe("grit lint rules", () => {
@@ -140,22 +144,26 @@ describe("grit lint rules", () => {
   });
 
   for (const fixture of fixtures) {
-    test(`${fixture.name} flags exactly the marked lines in bad`, async () => {
-      const { lines, diagnostics } = await lintFixture(fixture, "bad");
+    test(`${fixture.name} reports each marked line in bad once, at its marker's severity`, async () => {
+      const 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");
+      const expected = await expectedReports(fixture);
       expect(expected.length).toBeGreaterThan(0);
-      // Set equality: an unreported mark is a pattern that stopped matching, an unmarked report is overreach.
-      expect(lines).toEqual(expected);
+      // An unreported mark stopped matching, an unmarked report is overreach, a line reported twice is one site
+      // reported twice, and a severity that differs is a tier that moved.
+      const reported = diagnostics.map(
+        (diagnostic) => `${diagnostic.location?.start?.line ?? 0}: ${diagnostic.severity}`,
+      );
+      expect(reported.sort(byLine)).toEqual(expected.sort(byLine));
     });
 
     test(`${fixture.name} leaves good clean`, async () => {
       expect((await markedLines(fixture, "good", "// @ok")).length).toBeGreaterThan(0);
-      const { diagnostics } = await lintFixture(fixture, "good");
+      const diagnostics = await lintFixture(fixture, "good");
       expect(diagnostics.map((diagnostic) => `${diagnostic.location?.start?.line}: ${diagnostic.message}`)).toEqual([]);
     });
   }

package/lint/no-double-brace-placeholder.grit

@@ -0,0 +1,15 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `interpolateTranslation` replaces `{name}` only, so a `{{name}}` reaches the reader as typed. Only `.error()` and
+// `.translate()` entries receive data; a `{{` in a label or description is literal text, such as a syntax users type.
+JsCallExpression(callee = JsStaticMemberExpression(member = r"(?:error|translate)"), arguments = $entries) where {
+  $entries <: contains bubble or { JsStringLiteralExpression(), JsTemplateChunkElement() } as $s where {
+    $s <: r"[\s\S]*\{\{[\s\S]*",
+    register_diagnostic(
+      span = $s,
+      message = "`{{name}}` is never interpolated: a translation replaces `{name}` only, so the braces reach the reader as typed. Write `{name}`.",
+      severity = "error"
+    )
+  }
+}

package/lint/no-inline-color.grit

@@ -7,15 +7,31 @@ language js(typescript, jsx)
 // 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.
+// SVG color attributes and `element.style` writes are the same bypass outside a style object. They are
+// warnings, not errors, so code written before the rule reached them is not broken.
+// The hex arm skips `url(#id)`: a paint-server id such as `#fade` is spelled in hex digits.
 // 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>` }
+  or {
+    JsStringLiteralExpression() as $s where { $s <: within `style={$obj}` },
+    JsTemplateChunkElement() as $s where { $s <: within `<style>$body</style>` }
+  } where { $tier = "error" },
+  or {
+    or { JsxString(), JsStringLiteralExpression(), JsTemplateChunkElement() } as $s where {
+      $s <: within JsxAttribute(name = r"(?:fill|stroke|stopColor|floodColor|lightingColor|color|stop-color|flood-color|lighting-color)")
+    },
+    or { JsStringLiteralExpression(), JsTemplateChunkElement() } as $s where {
+      $s <: within or { `$el.style.$prop = $value`, `$el.style[$prop] = $value`, `$el.style.setProperty($prop, $value)` }
+    }
+  } where { $tier = "warn" }
 } where {
-  $s <: r"[\s\S]*(?:#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb)\()[\s\S]*",
+  $s <: or {
+    r"[\s\S]*(?:(?:^|[^(\x22'])#|(?:^|[^lL])\([\x22']?#|(?:^|[^rR])[lL]\([\x22']?#|(?:^|[^uU])[rR][lL]\([\x22']?#|(?:^|[^(])[\x22']#)[0-9a-fA-F]{3,8}(?:$|[^0-9A-Za-z_-])[\s\S]*",
+    r"[\s\S]*(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb)\([\s\S]*"
+  },
   register_diagnostic(
     span = $s,
-    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"
+    message = "Inline color literal bypasses semantic tokens and theme switching. Use a token class, currentColor, or a token variable: style={{ color: 'var(--primary)' }}, fill='currentColor', el.style.color = 'var(--primary)'. A fixed brand or data-viz color takes // biome-ignore lint/plugin: <reason>.",
+    severity = $tier
   )
 }

package/lint/no-throw-raw-error.grit

@@ -1,40 +1,25 @@
 engine biome(1.0)
 language js(typescript, jsx)
 
-// Domain code in apps/ and libs/ must not throw a raw `Error`. Throw the typed
-// `Err` instead, which is generated per app/lib by `makeTrans`
-// (pkgs/akanjs/dictionary/trans.ts) and imported via `import { Err } from "../dict"`
-// (or the app/lib client entrypoint). `Err` carries a translatable error key,
-// a status code, and structured payload, so raw `Error` throws lose i18n and
-// HTTP-status handling.
-//
-// The `$msg` metavariable in the argument position leniently matches any arity,
-// so `throw new Error()`, `throw new Error("x")`, and
-// `throw new Error("x", { cause })` are all caught, as is the `new`-less
-// `throw Error(...)` call form. Only real throw statements match — a
-// `new Error(...)` inside a string literal or one that is not thrown is ignored.
-//
-// No autofix: `Err`'s first argument must be a typed dictionary error key
-// (e.g. throw new Err('model.errorKey')), so a mechanical rewrite of an
-// arbitrary message string would not typecheck. Each site must be migrated to a
-// real error key by hand.
-//
-// NOTE: the diagnostic messages below use single quotes in the example on
-// purpose. Escaped double quotes (\") inside a GritQL string trigger a
-// double-unescape bug in Biome 2.4.4 that corrupts the rendered message.
-or {
-  `throw new Error($msg)` as $throw where {
+// A raw `Error` loses the translatable key and status `Err` carries whether it is thrown, rejected, returned or stored.
+// Thrown, it is an error; built anywhere else, a warning, so code written before the rule reached it is not broken.
+// No rewrite: `Err` takes a dictionary key, which an arbitrary message is not.
+// Node kinds, not snippets: a `new Error` snippet also matches the JSX text of `<code>new Error</code>`.
+// Single quotes in the message: Biome unescapes a `\"` in a GritQL string twice and corrupts the text.
+or { JsNewExpression(callee = `Error`), JsCallExpression(callee = `Error`) } as $error where {
+  or {
+    and {
+      $error <: within JsThrowStatement(argument = $error),
+      register_diagnostic(
+        span = $error,
+        message = "Do not throw a raw `Error`: it carries no translatable key or status. Throw the typed `Err` (import { Err } from the app/lib dict), e.g. throw new Err('<module>.error.<key>'), and register the key in that module's dictionary `.error({})`.",
+        severity = "error"
+      )
+    },
     register_diagnostic(
-      span = $throw,
-      message = "Do not throw a raw `Error`. Throw the typed `Err` instead (import { Err } from the app/lib dict), e.g. throw new Err('model.errorKey').",
-      severity = "error"
-    )
-  },
-  `throw Error($msg)` as $throw where {
-    register_diagnostic(
-      span = $throw,
-      message = "Do not throw a raw `Error`. Throw the typed `Err` instead (import { Err } from the app/lib dict), e.g. throw new Err('model.errorKey').",
-      severity = "error"
+      span = $error,
+      message = "Do not construct a raw `Error`: rejected, returned or stored, it carries no translatable key or status. Use the typed `Err` (import { Err } from the app/lib dict), e.g. new Err('<module>.error.<key>'), and register the key in that module's dictionary `.error({})`.",
+      severity = "warn"
     )
   }
 }