@akanjs/devkit 3.0.0-alpha.1 → 3.0.0-alpha.100

package/lint/no-import-client-in-server.grit

@@ -0,0 +1,48 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Server files (*.document.ts, *.dictionary.ts, *.service.ts, *.signal.ts, srvkit/) and shared files
+// (common/, *.constant.ts) run in Bun with no DOM and no bundler, and every CLI command, worker, and
+// migration that loads a service loads whatever the service imports. Reaching into the client graph
+// pulls React, the store, and the browser globals they touch into that process, and it runs the
+// dependency backwards: the client entrypoint is built on top of cnst and sig, not the other way round.
+//
+// `import type` is erased before bundling and stays legal. A mixed value-and-type import is not exempt.
+or {
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\".*\.store\"",
+      r"\".*\.(?:Template|Unit|Util|View|Zone)\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Client module. A server or shared file must not import a *.store or a module component (*.Template, *.Unit, *.Util, *.View, *.Zone) — server code reaches the model through cnst and db, never through client state or JSX.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\"(?:.*/)?(?:ui|webkit)(?:/.*)?\"",
+      r"\".*/client(?:/.*)?\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Client entrypoint. A server or shared file must not import ui/, webkit/, or a package client entrypoint such as '@libs/<lib>/client' or 'akanjs/client' — import the server entrypoint or a common/ helper instead.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\"(?:.*/)?(?:st|store|useClient)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Client barrel. A server or shared file must not import st, store, or useClient — server code holds no client state, and Err comes from dict on the server.",
+      severity = "error"
+    )
+  }
+}

package/lint/no-import-server-in-client.grit

@@ -0,0 +1,45 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Client files (ui/, webkit/, page/, *.store.ts, every .tsx) and shared files (common/, *.constant.ts)
+// are compiled into the browser bundle, so a single value import of a server module drags its whole
+// graph along — the database driver, node:crypto, a secret resolved from process.env. The boundary has
+// to hold at the import statement, because by the call site the module is already bundled.
+//
+// `import type` is erased before bundling and stays legal, so a shared file may still name a server-side
+// type. A mixed value-and-type import is not exempt: it emits a real edge.
+or {
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\".*\.(?:document|dictionary|service|signal)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Server module. A client or shared file must not import a *.document, *.dictionary, *.service, or *.signal file — take the model from the package client entrypoint ('@libs/<lib>/client') or from its *.constant instead. Write 'import type' if only the type is needed.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\"(?:.*/)?srvkit(?:/.*)?\"",
+      r"\".*/server(?:/.*)?\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Server entrypoint. A client or shared file must not import srvkit/ or a package server entrypoint such as '@apps/<app>/server' or 'akanjs/server' — import the matching client entrypoint instead.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\"(?:.*/)?(?:db|srv|sig|dict|option|useServer)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Server barrel. A client or shared file must not import db, srv, sig, dict, option, or useServer — read models from cnst, state from st, and Err from the package client entrypoint.",
+      severity = "error"
+    )
+  }
+}

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

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

package/lint/no-inline-color.grit

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

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

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

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

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

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

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

package/lint/no-return-in-store-action.grit

@@ -0,0 +1,35 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Every prototype method of a `store(...)` class is registered as an action
+// (StoreRegistry.register) and reaches callers only as `st.do.<action>`, which re-wraps it
+// (StoreInstance.#extendAccessors) and is typed void by `VoidActions` in
+// pkgs/akanjs/store/types.ts. A returned value is therefore unreachable from every call
+// site — it reads like a contract while being dead code. Write the result into state with
+// `this.set({ ... })` instead.
+//
+// Deliberately not flagged, because none of these are actions: a bare `return;` guard, a
+// `return` belonging to a nested callback, a getter, a `static` helper, and a class-property
+// arrow (an instance field, so `register` never sees it).
+`return $value;` as $return where {
+  not $value <: r"",
+  $return <: within JsClassDeclaration() as $storeClass where {
+    $storeClass <: contains JsExtendsClause() as $extends where {
+      $extends <: r"extends\s+store\([\s\S]*"
+    }
+  },
+  $return <: within JsMethodClassMember() as $action where {
+    not $action <: r"static[\s\S]*"
+  },
+  not $return <: within JsArrowFunctionExpression(),
+  not $return <: within JsFunctionExpression(),
+  not $return <: within JsFunctionDeclaration(),
+  not $return <: within JsMethodObjectMember(),
+  not $return <: within JsGetterObjectMember(),
+  not $return <: within JsSetterObjectMember(),
+  register_diagnostic(
+    span = $return,
+    message = "Store actions dispatch as void — st.do.<action>() never exposes this value. Write the result into state with this.set({ ... }) and drop the returned value; a bare 'return;' guard clause is fine.",
+    severity = "error"
+  )
+}

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

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

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

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

package/linter.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import { type BiomeReport, parseBiomeReport } from "./linter";
+
+const reportOf = (diagnostics: BiomeReport["diagnostics"]): string =>
+  JSON.stringify({ summary: { errors: diagnostics?.length ?? 0, warnings: 0 }, diagnostics });
+
+const oneDiagnostic: BiomeReport["diagnostics"] = [
+  {
+    severity: "error",
+    message: "Unexpected any",
+    category: "lint/suspicious/noExplicitAny",
+    location: { path: "apps/demo/ui/Card.tsx", start: { line: 3, column: 10 } },
+  },
+];
+
+describe("parseBiomeReport", () => {
+  test("reads a report that is the whole output", () => {
+    const report = parseBiomeReport(reportOf(oneDiagnostic));
+    expect(report.diagnostics).toHaveLength(1);
+    expect(report.diagnostics?.[0]?.category).toBe("lint/suspicious/noExplicitAny");
+    expect(report.summary?.errors).toBe(1);
+  });
+
+  test("reads a report behind leading text", () => {
+    const output = `Skipped 3 files.\n${reportOf(oneDiagnostic)}`;
+    expect(parseBiomeReport(output).diagnostics).toHaveLength(1);
+  });
+
+  test("reads a report behind leading text that carries a brace", () => {
+    // The whole reason the first-brace-to-last-brace slice was wrong: Biome prints configuration and IO
+    // diagnostics onto the same stream as the report, and those messages quote source and config.
+    const output = [
+      "configuration/deserialize: unknown key `overrides[0].includes { }`",
+      "  the file `biome.jsonc` cannot be read",
+      reportOf(oneDiagnostic),
+    ].join("\n");
+    expect(parseBiomeReport(output).diagnostics).toHaveLength(1);
+  });
+
+  test("skips a complete JSON object in leading text that is not a report", () => {
+    const output = `hint: try {"linter":{"enabled":true}} in your config\n${reportOf(oneDiagnostic)}`;
+    const report = parseBiomeReport(output);
+    expect(report.diagnostics).toHaveLength(1);
+    expect(report.summary?.errors).toBe(1);
+  });
+
+  test("reads a report followed by trailing text", () => {
+    const output = `${reportOf(oneDiagnostic)}\nChecked 12 files in 40ms. Found 1 error.`;
+    expect(parseBiomeReport(output).diagnostics).toHaveLength(1);
+  });
+
+  test("keeps a diagnostic whose message contains braces and quotes", () => {
+    const message = 'Replace {" a "} with { " a " } — the `{}` object syntax is not allowed';
+    const report = parseBiomeReport(reportOf([{ severity: "error", message }]));
+    expect(report.diagnostics?.[0]?.message).toBe(message);
+  });
+
+  test("keeps a diagnostic whose message ends in an escaped backslash before the closing quote", () => {
+    const message = "path separator is \\\\";
+    const report = parseBiomeReport(reportOf([{ severity: "warning", message }]));
+    expect(report.diagnostics?.[0]?.message).toBe(message);
+    expect(report.diagnostics).toHaveLength(1);
+  });
+
+  test("accepts a report carrying only a summary", () => {
+    expect(parseBiomeReport('{"summary":{"errors":0,"warnings":0}}').summary?.errors).toBe(0);
+  });
+
+  test("throws the output when it holds no JSON at all", () => {
+    expect(() => parseBiomeReport("biome: command not found\n")).toThrow("biome: command not found");
+  });
+
+  test("throws the output when the only brace never closes", () => {
+    expect(() => parseBiomeReport('internal error: {"diagnostics":[')).toThrow("internal error");
+  });
+
+  test("throws a named error for empty output", () => {
+    expect(() => parseBiomeReport("   \n")).toThrow("No Biome JSON output");
+  });
+});

package/linter.ts

@@ -3,14 +3,14 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
 
-type BiomeSeverity = "error" | "warning" | "information" | "hint";
+export type BiomeSeverity = "error" | "warning" | "information" | "hint";
 
-interface BiomePosition {
+export interface BiomePosition {
   line: number;
   column: number;
 }
 
-interface BiomeDiagnostic {
+export interface BiomeDiagnostic {
   severity: BiomeSeverity;
   message: string;
   category?: string;
@@ -21,7 +21,7 @@ interface BiomeDiagnostic {
   };
 }
 
-interface BiomeReport {
+export interface BiomeReport {
   summary?: {
     changed?: number;
     errors?: number;
@@ -58,19 +58,81 @@ interface LintResponse {
   warnings: LintMessage[];
 }
 
+/**
+ * Extracts the `--reporter=json` report from Biome's output.
+ *
+ * Biome mixes configuration and IO diagnostics into the same stream as the report, so the output is not
+ * always JSON alone. Slicing from the first `{` to the last `}` mis-parses as soon as that leading text
+ * carries a brace of its own, which is not hypothetical: a config error printed ahead of the report made
+ * one unchanged command alternate between 2 and 10 diagnostics. So every `{` is tried as a start, its
+ * match is found by depth while string literals are skipped, and the first candidate that both parses and
+ * carries a report field wins — a brace in prose parses as nothing, and `{"a":1}` in prose is not a report.
+ */
+export const parseBiomeReport = (output: string): BiomeReport => {
+  for (let start = output.indexOf("{"); start !== -1; start = output.indexOf("{", start + 1)) {
+    const end = objectEndAt(output, start);
+    if (end === -1) break;
+    const report = asBiomeReport(output.slice(start, end + 1));
+    if (report) return report;
+  }
+  throw new Error(output.trim() || "No Biome JSON output");
+};
+
+const objectEndAt = (output: string, start: number): number => {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let idx = start; idx < output.length; idx += 1) {
+    const char = output[idx];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') inString = true;
+    else if (char === "{") depth += 1;
+    else if (char === "}" && --depth === 0) return idx;
+  }
+  return -1;
+};
+
+const asBiomeReport = (candidate: string): BiomeReport | null => {
+  try {
+    const parsed = JSON.parse(candidate) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    if (!("diagnostics" in parsed) && !("summary" in parsed)) return null;
+    return parsed as BiomeReport;
+  } catch {
+    return null;
+  }
+};
+
+/** Biome reads `biome.json` first and `biome.jsonc` second; only the latter may carry comments. */
+const BIOME_CONFIG_FILES = ["biome.json", "biome.jsonc"] as const;
+
 export class Linter {
   lintRoot: string;
+  configPath: string;
   #biomeBin: string;
 
   constructor(cwdPath: string) {
     this.lintRoot = this.#findBiomeRootPath(cwdPath);
+    this.configPath = Linter.#configPathIn(this.lintRoot) ?? path.join(this.lintRoot, "biome.json");
     const localBiomeBin = path.join(this.lintRoot, "node_modules/.bin/biome");
     this.#biomeBin = existsSync(localBiomeBin) ? localBiomeBin : "biome";
   }
 
+  static #configPathIn(dir: string): string | null {
+    for (const fileName of BIOME_CONFIG_FILES) {
+      const configPath = path.join(dir, fileName);
+      if (existsSync(configPath)) return configPath;
+    }
+    return null;
+  }
+
   #findBiomeRootPath(dir: string): string {
-    const configPath = path.join(dir, "biome.json");
-    if (existsSync(configPath)) return dir;
+    if (Linter.#configPathIn(dir)) return dir;
     const parentDir = path.dirname(dir);
     if (parentDir === dir) throw new Error(`biome.json not found from ${dir}`);
     return this.#findBiomeRootPath(parentDir);
@@ -111,14 +173,6 @@ export class Linter {
     });
   }
 
-  #parseBiomeReport(output: string): BiomeReport {
-    const jsonStart = output.indexOf("{");
-    const jsonEnd = output.lastIndexOf("}");
-    if (jsonStart === -1 || jsonEnd === -1 || jsonEnd < jsonStart)
-      throw new Error(output.trim() || "No Biome JSON output");
-    return JSON.parse(output.slice(jsonStart, jsonEnd + 1)) as BiomeReport;
-  }
-
   #diagnosticFilePath(diagnostic: BiomeDiagnostic, fallbackFilePath: string) {
     const diagnosticPath = diagnostic.location?.path;
     if (!diagnosticPath) return fallbackFilePath;
@@ -193,10 +247,10 @@ export class Linter {
       "--max-diagnostics=none",
       "--no-errors-on-unmatched",
       "--config-path",
-      path.join(this.lintRoot, "biome.json"),
+      this.configPath,
       this.#toBiomePath(filePath),
     ]);
-    const report = this.#parseBiomeReport(stdout || stderr);
+    const report = parseBiomeReport(stdout || stderr);
     const results = this.#toLintResults(report, filePath);
     const { errors, warnings } = this.#splitMessages(results);
     const output = write && existsSync(filePath) ? readFileSync(filePath, "utf8") : undefined;
@@ -390,14 +444,7 @@ export class Linter {
 
     const source = readFileSync(resolvedFilePath, "utf8");
     const { stdout } = await this.#runBiome(
-      [
-        "check",
-        "--write",
-        "--config-path",
-        path.join(this.lintRoot, "biome.json"),
-        "--stdin-file-path",
-        this.#toBiomePath(resolvedFilePath),
-      ],
+      ["check", "--write", "--config-path", this.configPath, "--stdin-file-path", this.#toBiomePath(resolvedFilePath)],
       source,
     );
     const lintResult = await this.lintFile(resolvedFilePath);
@@ -409,10 +456,37 @@ export class Linter {
    * @param filePath - Path to the file
    * @returns Biome configuration object
    */
+  /**
+   * Applies Biome's safe fixes to many files in one process.
+   *
+   * One spawn, not one per file: Biome's startup dominates a small file, so the per-file path turns a
+   * fifteen-file scaffold into three seconds of process launches. Paths that do not exist are dropped
+   * rather than thrown on, because the caller is usually reporting what a template just wrote and a
+   * template is allowed to decline a file.
+   */
+  async fixFiles(filePaths: string[]): Promise<{ fixed: string[] }> {
+    const resolved = filePaths.map((filePath) => this.#resolveFilePath(filePath)).filter(existsSync);
+    if (resolved.length === 0) return { fixed: [] };
+    const before = new Map(resolved.map((filePath) => [filePath, readFileSync(filePath, "utf8")]));
+    await this.#runBiome([
+      "check",
+      "--write",
+      "--reporter=json",
+      "--max-diagnostics=none",
+      "--no-errors-on-unmatched",
+      "--config-path",
+      this.configPath,
+      ...resolved.map((filePath) => this.#toBiomePath(filePath)),
+    ]);
+    return {
+      fixed: resolved.filter((filePath) => readFileSync(filePath, "utf8") !== before.get(filePath)),
+    };
+  }
+
   async getConfigForFile(filePath: string): Promise<unknown> {
     const resolvedFilePath = this.#resolveFilePath(filePath);
     if (!existsSync(resolvedFilePath)) throw new Error(`File not found: ${filePath}`);
-    return JSON.parse(readFileSync(path.join(this.lintRoot, "biome.json"), "utf8")) as unknown;
+    return JSON.parse(readFileSync(this.configPath, "utf8")) as unknown;
   }
 
   /**