@akanjs/devkit 3.0.0-alpha.71 → 3.0.0-alpha.72

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,6 +58,56 @@ 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;
 
@@ -123,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;
@@ -208,7 +250,7 @@ export class Linter {
       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;
@@ -414,6 +456,33 @@ 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}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.71",
+  "version": "3.0.0-alpha.72",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.71",
+    "akanjs": "3.0.0-alpha.72",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",
@@ -62,7 +62,7 @@
   },
   "peerDependencies": {
     "@capacitor/cli": "^8.3.4",
-    "react": "19.2.6"
+    "react": "19.2.7"
   },
   "peerDependenciesMeta": {
     "@capacitor/cli": {

package/prompter.ts

@@ -24,7 +24,6 @@ export class Prompter {
   }
 
   static async selectGuideline() {
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
     const guideNames = await Prompter.listGuidelines();
     return await select({
       message: "Select a guideline",
@@ -41,11 +40,17 @@ export class Prompter {
     const guideJson = await fsPromise.readFile(filePath, "utf-8");
     return JSON.parse(guideJson) as GuideGenerateJson;
   }
+  /**
+   * The name is checked against the directory listing rather than interpolated straight into a path:
+   * it arrives from an MCP tool argument, and an unknown one has to name the valid set instead of
+   * surfacing an ENOENT that carries the host's own paths.
+   */
   static async getInstruction(guideName: string): Promise<string> {
+    const guideNames = await Prompter.listGuidelines();
+    if (!guideNames.includes(guideName))
+      throw new Error(`Unknown guideline "${guideName}". Available: ${guideNames.join(", ")}`);
     const guidelineRoot = await Prompter.#getGuidelineRoot();
-    const filePath = `${guidelineRoot}/${guideName}/${guideName}.instruction.md`;
-    const content = await fsPromise.readFile(filePath, "utf-8");
-    return content;
+    return await fsPromise.readFile(`${guidelineRoot}/${guideName}/${guideName}.instruction.md`, "utf-8");
   }
   static async getUpdateRequest(guideName: string) {
     return await input({

package/qualityScanner.test.ts

@@ -249,3 +249,67 @@ describe("AkanQualityScanner layout rules", () => {
     expect(warnings[0]?.file).toBe("libs/demo/lib/helper.ts");
   });
 });
+
+describe("bang comments in browser-reachable files", () => {
+  const bangWarningsIn = async (files: Record<string, string>) => {
+    const result = await new AkanQualityScanner().scan(await makeWorkspace(files));
+    return rulesOf(result, "akan.file.bang-comment-in-client");
+  };
+
+  test("flags the first and last line, which the grit rule cannot reach", async () => {
+    const warnings = await bangWarningsIn({
+      "apps/demo/ui/First.tsx": "//! FIXME: broken\nexport const First = () => null;\n",
+      "apps/demo/ui/Last.tsx": "export const Last = () => null;\n//! left behind\n",
+    });
+
+    expect(warnings.map((warning) => `${warning.file}:${warning.line}`).sort()).toEqual([
+      "apps/demo/ui/First.tsx:1",
+      "apps/demo/ui/Last.tsx:2",
+    ]);
+    expect(warnings[0]?.fix).toContain("// FIXME:");
+  });
+
+  test("flags the block form and a marker trailing code", async () => {
+    const warnings = await bangWarningsIn({
+      "apps/demo/lib/task/Task.Zone.tsx": ["/*! keep me */", "export const Zone = () => null; //! and me", ""].join(
+        "\n",
+      ),
+    });
+
+    expect(warnings.map((warning) => warning.line)).toEqual([1, 2]);
+  });
+
+  test("ignores a double slash inside a string literal", async () => {
+    expect(
+      await bangWarningsIn({ "apps/demo/ui/Url.tsx": 'export const url = "https://host//!path";\n' }),
+    ).toHaveLength(0);
+  });
+
+  test("stays out of server files and tests", async () => {
+    const body = "//! server-only marker\nexport const value = 1;\n";
+    expect(
+      await bangWarningsIn({
+        "apps/demo/srvkit/storage.ts": body,
+        "apps/demo/lib/task/task.service.ts": body,
+        "apps/demo/ui/Card.test.tsx": body,
+        "apps/demo/lib/task/task.signal.spec.ts": body,
+      }),
+    ).toHaveLength(0);
+  });
+
+  test("covers every path role the grit rule is scoped to", async () => {
+    const body = "//! marker\nexport const value = 1;\n";
+    const files = [
+      "apps/demo/ui/Card.tsx",
+      "apps/demo/webkit/useThing.tsx",
+      "apps/demo/common/format.ts",
+      "apps/demo/page/task/_index.tsx",
+      "apps/demo/lib/task/task.constant.ts",
+      "apps/demo/lib/task/task.store.ts",
+      "apps/demo/lib/task/Task.Unit.tsx",
+    ];
+    const warnings = await bangWarningsIn(Object.fromEntries(files.map((file) => [file, body])));
+
+    expect(warnings.map((warning) => warning.file).sort()).toEqual([...files].sort());
+  });
+});

package/qualityScanner.ts

@@ -117,6 +117,8 @@ const RULE_FIXES: Record<string, string> = {
     "Run `akan compact <app-or-lib>` to rewrite the abstract with the AI editor, keeping only the invariants and workflows the source files cannot show.",
   "akan.file.placeholder-export":
     "Remove the placeholder export; generated indexes should only re-export real modules.",
+  "akan.file.bang-comment-in-client":
+    "Rewrite the marker as `// FIXME:` or `// TODO:`. Keep the bang form for server, srvkit, and CLI files.",
   "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
   "akan.file.global-declaration":
     "Move the global declaration into an approved low-level integration file (e.g. webkit) and keep it isolated.",
@@ -314,6 +316,7 @@ export class AkanQualityScanner {
       });
     }
 
+    warnings.push(...getBangCommentWarnings(sourceFile));
     warnings.push(...getPlaceholderExportWarnings(sourceFile));
     warnings.push(...getDictionaryTextWarnings(sourceFile));
     warnings.push(...getGlobalMutationWarnings(sourceFile));
@@ -596,9 +599,10 @@ function isEnumClassStatement(sourceFile: ts.SourceFile, statement: ts.Statement
 
 function getExportedClassNames(sourceFile: ts.SourceFile) {
   return sourceFile.statements
-    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement) && !!statement.name)
+    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement))
     .filter((statement) => isExported(statement))
-    .map((statement) => statement.name!.text);
+    .map((statement) => statement.name?.text)
+    .filter((name): name is string => !!name);
 }
 
 function isComponentDeclarationFile(file: string) {
@@ -678,7 +682,43 @@ function isPascalCaseName(name: string) {
 
 function isDefaultExportStatement(statement: ts.Statement) {
   if (ts.isExportAssignment(statement)) return !statement.isExportEquals;
-  return !!(ts.getCombinedModifierFlags(statement as ts.Declaration) & ts.ModifierFlags.Default);
+  if (!ts.canHaveModifiers(statement)) return false;
+  return !!ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+}
+
+/**
+ * Bun's bundler keeps `//!` and `/*!` through minification (it reads them as the `@license` class), so a
+ * bang marker in browser-reachable code ships verbatim to every visitor. `no-bang-comment-in-client.grit`
+ * is the build gate; this exists because that rule cannot see the whole file.
+ *
+ * A comment is trivia, which Biome's GritQL exposes to no node pattern, so the rule matches through
+ * `file($name, $body)` — and `$body` is the module's *token* span. A marker above the first statement or
+ * below the last one sits in leading or trailing trivia and is unreachable from GritQL at all. Reading the
+ * raw text here covers both, and re-reporting the markers grit already catches costs nothing: the two run
+ * from different commands, and a file with one is failing lint either way.
+ */
+function getBangCommentWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
+  if (!isClientReachableFile(sourceFile.file)) return [];
+  // Anchored to line start or to whitespace after code, so a literal like `"https://host//!path"` is not a hit.
+  return findPatternLines(sourceFile.content, /(?:^|[^\s/][ \t]+)\/[*/]!/).map((line) => ({
+    rule: "akan.file.bang-comment-in-client",
+    scope: "file" as const,
+    severity: "warning" as const,
+    file: sourceFile.file,
+    line,
+    message: "A `//!` or `/*!` marker survives minification and ships to the browser.",
+  }));
+}
+
+/** Mirrors the path scope of `no-bang-comment-in-client.grit` in `biome.base.json`. */
+function isClientReachableFile(file: string) {
+  if (/\.(test|spec)\.tsx?$/.test(file)) return false;
+  if (/\.(constant|store)\.ts$/.test(file)) return true;
+  if (/\.(Template|Unit|Util|View|Zone)\.tsx$/.test(file)) return true;
+  const segments = file.split("/");
+  if (segments.includes("ui") || segments.includes("webkit")) return /\.tsx?$/.test(file);
+  if (segments.includes("common")) return file.endsWith(".ts");
+  return segments.includes("page") && file.endsWith(".tsx");
 }
 
 function getPlaceholderExportWarnings(sourceFile: SourceFileInfo): QualityWarning[] {

package/recipeScanner.ts

@@ -118,7 +118,10 @@ const extractVariants = (config: ts.ObjectLiteralExpression) => {
         if (!ts.isPropertyAssignment(variant) || !isNamed(variant.name)) continue;
         if (!ts.isObjectLiteralExpression(variant.initializer)) continue;
         variants[propName(variant.name)] = variant.initializer.properties
-          .filter((option): option is ts.PropertyAssignment => ts.isPropertyAssignment(option) && isNamed(option.name))
+          .filter(
+            (option): option is ts.PropertyAssignment & { name: ts.Identifier | ts.StringLiteral } =>
+              ts.isPropertyAssignment(option) && isNamed(option.name),
+          )
           .map((option) => propName(option.name));
       }
     } else if (key === "defaultVariants" && ts.isObjectLiteralExpression(property.initializer)) {

package/scanInfo.ts

@@ -518,7 +518,7 @@ export class LibInfo extends ScanInfo {
 export class PkgInfo {
   readonly exec: PkgExecutor;
   readonly name: string;
-  private scanResult: PkgScanResult;
+  #scanResult: PkgScanResult;
 
   static async scanExecutor(exec: PkgExecutor) {
     const [tsconfig, rootPackageJson] = await Promise.all([exec.getTsConfig(), exec.workspace.getPackageJson()]);
@@ -560,10 +560,10 @@ export class PkgInfo {
   constructor(exec: PkgExecutor, scanResult: PkgScanResult) {
     this.exec = exec;
     this.name = exec.name;
-    this.scanResult = scanResult;
+    this.#scanResult = scanResult;
   }
   getScanResult() {
-    return this.scanResult;
+    return this.#scanResult;
   }
 }