@akanjs/devkit 3.0.0 → 3.0.2-rc.0

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-static-in-object-light-model/bad.ts

@@ -0,0 +1,43 @@
+import { enumOf, ID, Int } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class QuizInput extends via((field) => ({
+  userId: field(ID, { ref: "user", immutable: true }),
+})) {}
+
+export class QuizObject extends via(QuizInput, (field) => ({
+  correctNum: field(Int, { default: 0, min: 0 }),
+})) {
+  static maxNum = 4; // @flag
+  static readonly minNum = 1; // @flag
+  private static secretNum = 2; // @flag
+  static { // @flag
+    QuizObject.maxNum = 5;
+  }
+}
+
+export class LightQuiz extends via(
+  QuizObject,
+  ["userId", "correctNum"] as const,
+  (resolve) => ({}),
+) {
+  static choiceNum = 4; // @flag
+  static xpOfCorrect(comboNum: number) { // @flag
+    return comboNum * 10;
+  }
+  static async loadAll() { // @flag
+    return [];
+  }
+  static get defaultNum() { // @flag
+    return 1;
+  }
+  isPerfect() {
+    return this.correctNum === 4;
+  }
+}
+
+export class LightRenamed extends via(QuizObject, ["userId"] as const, (resolve) => ({})) {
+  static sizeNum = 1; // @flag
+}
+
+export class Quiz extends via(QuizObject, LightQuiz, (resolve) => ({})) {}

package/lint/__fixtures__/no-static-in-object-light-model/fixture.json

@@ -0,0 +1 @@
+{ "path": "lib/quiz/quiz.constant.ts" }

package/lint/__fixtures__/no-static-in-object-light-model/good.ts

@@ -0,0 +1,42 @@
+import { ID, Int } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class QuizInput extends via((field) => ({
+  userId: field(ID, { ref: "user", immutable: true }),
+})) {
+  static minSize = 4; // @ok
+}
+
+export class QuizObject extends via(QuizInput, (field) => ({
+  correctNum: field(Int, { default: 0, min: 0 }),
+})) {}
+
+export class LightQuiz extends via(QuizObject, ["userId", "correctNum"] as const, (resolve) => ({})) {
+  isPerfect() { // @ok
+    return this.correctNum === 4;
+  }
+  staticNum = 1; // @ok
+}
+
+export class Quiz extends via(QuizObject, LightQuiz, (resolve) => ({})) {
+  static choiceNum = 4; // @ok
+  static xpOfCorrect(comboNum: number) { // @ok
+    return comboNum * 10;
+  }
+}
+
+export class QuizInsight extends via(Quiz, (field) => ({})) {
+  static emptyNum = 0; // @ok
+}
+
+export class Coordinate extends via((field) => ({
+  lat: field(Int),
+})) {
+  static getDistanceKm(a: Coordinate, b: Coordinate) { // @ok
+    return a.lat - b.lat;
+  }
+}
+
+export class ObjectRegistry {
+  static instance = new ObjectRegistry(); // @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-static-in-object-light-model.grit

@@ -0,0 +1,27 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `via(XObject, LightX, ...)` mixes in only the prototypes of XObject and LightX (applyMixins in
+// akanjs/common), so a static declared on either never reaches the full model `X`. Statics belong on
+// XInput (or a scalar), X, or XInsight. The Object class is recognised by its `*Object` name, because its
+// via() shape is identical to the Insight's; the Light class also by its `[...] as const` field tuple.
+or {
+  JsMethodClassMember(),
+  JsPropertyClassMember(),
+  JsGetterClassMember(),
+  JsSetterClassMember(),
+  JsStaticInitializationBlockClassMember()
+} as $member where {
+  $member <: r"(?:(?:public|protected|private|declare|override|readonly|accessor)\s+)*static\b[\s\S]*",
+  $member <: within JsClassDeclaration() as $model where {
+    $model <: or {
+      r"class\s+(?:Light[A-Za-z0-9_$]*|[A-Za-z0-9_$]*Object)\s+extends\s+via\([\s\S]*",
+      r"class\s+[A-Za-z0-9_$]+\s+extends\s+via\(\s*[A-Za-z0-9_$.]+\s*,\s*\[[\s\S]*"
+    }
+  },
+  register_diagnostic(
+    span = $member,
+    message = "A static on an XObject or LightX class never reaches the full model, because via() mixes in their prototypes only. Declare it on XInput, the full model X, or XInsight instead.",
+    severity = "error"
+  )
+}

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

package/lint/no-unguarded-endpoint.grit

@@ -0,0 +1,73 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `SignalContext` checks `signalOption.guards ?? []`, so an endpoint, a named slice, or a slice's root query declaring
+// none is open to every HTTP and websocket caller. An option the rule cannot read, a variable or a spread, is left alone.
+or {
+  JsCallExpression(callee = $callee, arguments = JsCallArguments(args = $args)) as $call where {
+    or {
+      and {
+        $callee <: r"(?:query|mutation|pubsub|message)",
+        $call <: within JsCallExpression(callee = `endpoint`),
+        or { $args <: [$returns], $args <: [$returns, $option] }
+      },
+      and {
+        $callee <: `init`,
+        $call <: within JsCallExpression(callee = `slice`),
+        or { $args <: [], $args <: [$option] }
+      }
+    },
+    or {
+      $option <: undefined,
+      $option <: JsObjectExpression(members = $members) where {
+        or {
+          $members <: not some or {
+            JsPropertyObjectMember(name = r"(?:guards|\x22guards\x22|'guards')"),
+            JsShorthandPropertyObjectMember(name = r"guards"),
+            JsSpread()
+          },
+          $members <: some JsPropertyObjectMember(name = r"(?:guards|\x22guards\x22|'guards')", value = JsArrayExpression(elements = []))
+        }
+      }
+    },
+    register_diagnostic(
+      span = $callee,
+      message = "No `guards`, so every HTTP and websocket caller reaches this endpoint: a missing or empty `guards` fails open, which is also why MCP refuses it. Name the guards it needs, or write `guards: [Public]` when anonymous access is the intent.",
+      severity = "warn"
+    )
+  },
+  JsCallExpression(callee = `slice`, arguments = JsCallArguments(args = [$srv, $sliceOption, ...])) where {
+    $sliceOption <: JsObjectExpression(members = $sliceMembers),
+    or {
+      and {
+        $sliceMembers <: not some or {
+          JsPropertyObjectMember(name = r"(?:guards|\x22guards\x22|'guards')"),
+          JsShorthandPropertyObjectMember(name = r"guards"),
+          JsSpread()
+        },
+        register_diagnostic(
+          span = $sliceOption,
+          message = "No `guards` on this slice, so every HTTP and websocket caller reaches its root query and generated reads and writes: a missing guard fails open. Pass { guards: { root: Admin, get: …, cru: … } }, naming `Public` where anonymous access is the intent.",
+          severity = "warn"
+        )
+      },
+      and {
+        $sliceMembers <: some JsPropertyObjectMember(name = r"(?:guards|\x22guards\x22|'guards')", value = $guardMap),
+        $guardMap <: JsObjectExpression(members = $guardKeys),
+        or {
+          $guardKeys <: not some or {
+            JsPropertyObjectMember(name = r"(?:root|\x22root\x22|'root')"),
+            JsShorthandPropertyObjectMember(name = r"root"),
+            JsSpread()
+          },
+          $guardKeys <: some JsPropertyObjectMember(name = r"(?:root|\x22root\x22|'root')", value = JsArrayExpression(elements = []))
+        },
+        register_diagnostic(
+          span = $guardMap,
+          message = "No `root` guard on this slice, so its root query lists any filter to every HTTP and websocket caller: a missing or empty `root` fails open. Write `root: Admin`.",
+          severity = "warn"
+        )
+      }
+    }
+  }
+}

package/manifestDependencies.ts

@@ -0,0 +1,65 @@
+import { LibSource } from "./libSource";
+import type { PackageJson } from "./types";
+
+type DependencyMap = Record<string, string>;
+
+export interface ScannedImports {
+  runtime: readonly string[];
+  typeOnly: readonly string[];
+}
+
+export class ManifestDependencies {
+  readonly #root: PackageJson;
+  readonly #runtime: Set<string>;
+  readonly #typeOnly: Set<string>;
+  readonly #isKept: (dep: string) => boolean;
+
+  constructor(root: PackageJson, { runtime, typeOnly }: ScannedImports, isKept: (dep: string) => boolean) {
+    this.#root = root;
+    this.#runtime = new Set(runtime);
+    this.#typeOnly = new Set(typeOnly);
+    this.#isKept = isKept;
+  }
+
+  static keptBy(manifest: PackageJson): string[] {
+    const { keepDependencies } = (manifest[LibSource.manifestKey] ?? {}) as { keepDependencies?: unknown };
+    return Array.isArray(keepDependencies)
+      ? keepDependencies.filter((dep): dep is string => typeof dep === "string")
+      : [];
+  }
+
+  //* The scan recognises only the names the root declares, so only those can be proven unused and pruned.
+  realign(manifest: PackageJson) {
+    const removed: string[] = [];
+    const unverifiable: string[] = [];
+    const dependencies: DependencyMap = {};
+    for (const [dep, version] of Object.entries(manifest.dependencies ?? {})) {
+      if (this.#typeOnly.has(dep)) continue;
+      const rootVersion = this.#rootVersionOf(dep);
+      if (!rootVersion) {
+        unverifiable.push(dep);
+        dependencies[dep] = version;
+      } else if (this.#runtime.has(dep) || this.#isKept(dep)) dependencies[dep] = rootVersion;
+      else removed.push(dep);
+    }
+    const runtimeOfRootDependencies = [...this.#runtime].filter((dep) => this.#root.dependencies?.[dep]);
+    this.#append(dependencies, runtimeOfRootDependencies);
+
+    const devDependencies: DependencyMap = {};
+    for (const [dep, version] of Object.entries(manifest.devDependencies ?? {}))
+      if (!Object.hasOwn(dependencies, dep)) devDependencies[dep] = this.#rootVersionOf(dep) ?? version;
+    this.#append(devDependencies, [...this.#typeOnly]);
+    return { dependencies, devDependencies, removed, unverifiable };
+  }
+
+  #append(map: DependencyMap, deps: string[]) {
+    for (const dep of deps.filter((dep) => !Object.hasOwn(map, dep)).sort((a, b) => (a < b ? -1 : 1))) {
+      const rootVersion = this.#rootVersionOf(dep);
+      if (rootVersion) map[dep] = rootVersion;
+    }
+  }
+
+  #rootVersionOf(dep: string) {
+    return this.#root.dependencies?.[dep] ?? this.#root.devDependencies?.[dep];
+  }
+}

package/mobile/desktopBin.test.ts

@@ -28,7 +28,7 @@ const stage = async (
   bin: AkanBinConfig,
   { libBins = [], libs = [] }: { libBins?: { lib: string; bin: AkanBinConfig }[]; libs?: string[] } = {},
 ) => {
-  const binDir = path.join(root, "apps/portal/.akan/native/default/bin");
+  const binDir = path.join(root, "dist/native/portal/default/bin");
   const config = { app: { name: "portal" }, bin, libBins } as never;
   const carried = await new DesktopBin(fakeApp(path.join(root, "apps/portal"), libs), config).stage(binDir);
   return { carried, binDir };

package/mobile/desktopServerStage.test.ts

@@ -241,10 +241,13 @@ describe("DesktopServerStage", () => {
   });
 
   test("a phone build cannot carry the server", async () => {
-    const app = new NativeApp({ cwdPath: "/repo/apps/portal" } as never, {
-      name: "default",
-      config: { name: "default", appName: "Portal", appId: "com.portal.app", version: "1.0.0", buildNum: 1 },
-    });
+    const app = new NativeApp(
+      { name: "portal", cwdPath: "/repo/apps/portal", workspace: { workspaceRoot: "/repo" } } as never,
+      {
+        name: "default",
+        config: { name: "default", appName: "Portal", appId: "com.portal.app", version: "1.0.0", buildNum: 1 },
+      },
+    );
     const server = { dir: "/tmp/server", entry: "main.js", env: {} };
     await expect(app.build("ios", { server })).rejects.toThrow("Only a desktop app carries its server");
     await expect(app.run("android", { server })).rejects.toThrow("Only a desktop app carries its server");