@akanjs/devkit 2.4.2-rc.1 → 2.4.2-rc.3

package/abstractCompactor.ts

@@ -0,0 +1,112 @@
+import { Logger } from "akanjs/common";
+import chalk from "chalk";
+import { AbstractDoc, type AbstractKind } from "./abstractDoc";
+import { AiSession } from "./aiEditor";
+import type { SysExecutor } from "./executors";
+
+export interface AbstractCompactOptions {
+  module?: string | null;
+  minLines?: number;
+  interactive?: boolean;
+}
+
+export interface AbstractCompactReport {
+  path: string;
+  beforeLines: number;
+  afterLines: number;
+  status: "compacted" | "unchanged" | "failed";
+}
+
+/** Rewrites bloated `*.abstract.md` files down to the invariants their source files cannot show. */
+export class AbstractCompactor {
+  static readonly #reviewRequest = `Review the compacted file you just wrote against the original.
+- Did you drop an invariant, a security reason, or a workflow step that the source files cannot show by themselves? Restore it.
+- Did you keep anything that only restates code, scaffold wording, or history? Remove it.
+- Is it in the same language as the original, within the line budget, and one short line per bullet?
+Respond with exactly one \`\`\`markdown code block holding the corrected file and nothing else. If nothing needs to change, repeat the file unchanged.`;
+
+  #sys: SysExecutor;
+  #minLines: number;
+  #interactive: boolean;
+  constructor(
+    sys: SysExecutor,
+    { minLines = AbstractDoc.compactMinLines, interactive = false }: AbstractCompactOptions = {},
+  ) {
+    this.#sys = sys;
+    this.#minLines = minLines;
+    this.#interactive = interactive;
+  }
+  async compactAll({ module }: { module?: string | null } = {}) {
+    const docs = await AbstractDoc.findAll(this.#sys, { module });
+    const targets = docs.filter((doc) => doc.lineCount > this.#minLines);
+    const reports: AbstractCompactReport[] = [];
+    // One file at a time: each doc gets its own AI session, and parallel runs would interleave the
+    // streamed response with each other and with the interactive confirm prompt.
+    for (const doc of targets) reports.push(await this.compact(doc));
+    return { scanned: docs.length, reports };
+  }
+  async compact(doc: AbstractDoc): Promise<AbstractCompactReport> {
+    const session = new AiSession("compactAbstract", {
+      workspace: this.#sys.workspace,
+      cacheKey: `${this.#sys.name}-${doc.moduleName}`,
+    });
+    const approve = !this.#interactive;
+    const compacted = await session.editMarkdown(this.#request(doc), { approve });
+    const reviewed = await session.editMarkdown(AbstractCompactor.#reviewRequest, { approve });
+    // The review answers in prose when it finds nothing to fix, so the first compaction is the fallback.
+    const next = [reviewed, compacted]
+      .map((candidate) => candidate.trim())
+      .find((candidate) => doc.canReplaceWith(candidate));
+    const beforeLines = doc.lineCount;
+    if (!next) {
+      Logger.rawLog(chalk.yellow(`${doc.path}: the editor returned no shorter abstract, keeping the current file`));
+      return { path: doc.path, beforeLines, afterLines: beforeLines, status: "failed" };
+    }
+    if (next === doc.content.trim())
+      return { path: doc.path, beforeLines, afterLines: beforeLines, status: "unchanged" };
+    const content = `${next}\n`;
+    await this.#sys.writeFile(doc.path, content);
+    return { path: doc.path, beforeLines, afterLines: AbstractDoc.lineCountOf(content), status: "compacted" };
+  }
+  #targetShape(kind: AbstractKind) {
+    if (kind === "other")
+      return "  - keep the headings that still carry information and drop the rest; do not impose a new structure";
+    return [
+      "  - `# <name> Abstract` title line",
+      "  - one declarative sentence naming what this module owns",
+      "  - `## Rules` — two to five bullets, each an invariant the code cannot show by itself",
+      "  - optional `## Workflow` — the lifecycle as an arrow chain (`draft -> signed -> active`) or a few bullets",
+    ].join("\n");
+  }
+  #request(doc: AbstractDoc) {
+    return `You are compacting an Akan.js abstract file.
+
+An abstract is the summary a coding agent reads before changing a module. Repeated edits have made this one
+bloated, and it has to shrink back to what the source files cannot show by themselves.
+
+# Target file
+${this.#sys.type}s/${this.#sys.name}/${doc.path} (${doc.kind} module "${doc.moduleName}", ${doc.lineCount} lines)
+
+# Source files in the same folder
+${doc.siblingFiles.join(", ") || "none"}
+
+# Current content
+\`\`\`markdown
+${doc.content}
+\`\`\`
+
+# Rules for the compacted file
+- Write it in the SAME language as the current content. Never translate.
+- Keep every invariant, constraint, security reason, and workflow step that the source files cannot show by
+  themselves. Merge duplicates instead of dropping either one.
+- Delete what the code already states: field lists, types, labels, signatures, file lists, and imports.
+- Delete scaffold and placeholder wording, changelog or migration history, TODOs, and any instruction about
+  reading or updating this file.
+- Never invent a rule that the current content does not state.
+- Keep every bullet to one short line, and stay under ${AbstractDoc.compactMinLines} lines in total.
+- Shape:
+${this.#targetShape(doc.kind)}
+
+Respond with exactly one \`\`\`markdown code block holding the whole new file and nothing else.`;
+  }
+}

package/abstractDoc.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AbstractDoc } from "./abstractDoc";
+import { AppExecutor, WorkspaceExecutor } from "./executors";
+
+const tempRoots: string[] = [];
+
+const makeApp = async (files: Record<string, string>) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-abstract-doc-"));
+  tempRoots.push(root);
+  const appName = "abstractDemo";
+  for (const [filePath, content] of Object.entries(files)) {
+    const absolutePath = path.join(root, "apps", appName, filePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content);
+  }
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "repo" });
+  return AppExecutor.from(workspace, appName);
+};
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("AbstractDoc.kindOf", () => {
+  test("reads the module kind off the sys-relative path", () => {
+    expect(AbstractDoc.kindOf("lib/user/user.abstract.md")).toBe("domain");
+    expect(AbstractDoc.kindOf("lib/_payment/payment.abstract.md")).toBe("service");
+    expect(AbstractDoc.kindOf("lib/__scalar/money/money.abstract.md")).toBe("scalar");
+    expect(AbstractDoc.kindOf("ui/Editor/editor.abstract.md")).toBe("other");
+    expect(AbstractDoc.kindOf("lib/user/nested/user.abstract.md")).toBe("other");
+    expect(AbstractDoc.kindOf("lib/__scalar/money.abstract.md")).toBe("other");
+  });
+});
+
+describe("AbstractDoc.canReplaceWith", () => {
+  const doc = new AbstractDoc("lib/user/user.abstract.md", ["# user Abstract", "a", "b", "c", "d", ""].join("\n"), []);
+
+  test("accepts a shorter markdown file", () => {
+    expect(doc.canReplaceWith("# user Abstract\nowns users.\n## Rules\n- one rule")).toBe(true);
+  });
+
+  test("rejects prose, a longer file, and a stub", () => {
+    expect(doc.canReplaceWith("The abstract already meets the requirements.")).toBe(false);
+    expect(doc.canReplaceWith(["# user Abstract", "a", "b", "c", "d", "e"].join("\n"))).toBe(false);
+    expect(doc.canReplaceWith("# user Abstract\nowns users.")).toBe(false);
+  });
+});
+
+describe("AbstractDoc.findAll", () => {
+  test("finds abstracts across facet folders and filters by module", async () => {
+    const app = await makeApp({
+      "lib/user/user.abstract.md": "# user Abstract\n",
+      "lib/user/user.constant.ts": "export class User {}\n",
+      "lib/_payment/payment.abstract.md": "# payment Abstract\n",
+      "lib/__scalar/money/money.abstract.md": "# money Abstract\n",
+      "ui/Editor/editor.abstract.md": "# Editor Abstract\n",
+      "lib/user/user.document.ts": "export class UserModel {}\n",
+    });
+
+    const docs = await AbstractDoc.findAll(app);
+    expect(docs.map((doc) => doc.path)).toEqual([
+      "lib/__scalar/money/money.abstract.md",
+      "lib/_payment/payment.abstract.md",
+      "lib/user/user.abstract.md",
+      "ui/Editor/editor.abstract.md",
+    ]);
+    expect(docs.map((doc) => doc.kind)).toEqual(["scalar", "service", "domain", "other"]);
+
+    const [userDoc] = await AbstractDoc.findAll(app, { module: "user" });
+    expect(userDoc?.siblingFiles.sort()).toEqual(["user.constant.ts", "user.document.ts"]);
+
+    const [serviceDoc] = await AbstractDoc.findAll(app, { module: "_payment" });
+    expect(serviceDoc?.path).toBe("lib/_payment/payment.abstract.md");
+  });
+});

package/abstractDoc.ts

@@ -0,0 +1,70 @@
+import type { SysExecutor } from "./executors";
+
+export type AbstractKind = "domain" | "service" | "scalar" | "other";
+
+/** One `*.abstract.md` file: the agent-facing summary a module carries next to its source. */
+export class AbstractDoc {
+  static readonly suffix = ".abstract.md";
+  /** `akan quality` warns above this and points at `akan compact`. */
+  static readonly maxLines = 300;
+  /** `akan compact` floor, and the line budget it compacts down to, so a compacted file is never a candidate again. */
+  static readonly compactMinLines = 40;
+  // Abstracts only live in facet folders; globbing the sys root instead would walk node_modules.
+  static readonly #facetRoots = "{lib,ui,webkit,srvkit,common,plugin}";
+
+  static isAbstractPath(filePath: string) {
+    return filePath.endsWith(AbstractDoc.suffix);
+  }
+  static lineCountOf(content: string) {
+    return content.split(/\r?\n/).length;
+  }
+  /** Module kind read off the sys-relative path; anything outside a `lib/` module folder is "other". */
+  static kindOf(filePath: string): AbstractKind {
+    const [root, folder, ...rest] = filePath.split("/");
+    if (root !== "lib" || !folder) return "other";
+    if (folder === "__scalar") return rest.length === 2 ? "scalar" : "other";
+    if (rest.length !== 1) return "other";
+    return folder.startsWith("_") ? "service" : "domain";
+  }
+  static async findAll(sys: SysExecutor, { module }: { module?: string | null } = {}) {
+    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).sort();
+    const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
+    if (!module) return docs;
+    return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);
+  }
+  static async read(sys: SysExecutor, filePath: string) {
+    const dirPath = filePath.split("/").slice(0, -1).join("/");
+    const [content, folderFiles] = await Promise.all([sys.readFile(filePath), sys.readdir(dirPath)]);
+    return new AbstractDoc(
+      filePath,
+      content,
+      folderFiles.filter((fileName) => !AbstractDoc.isAbstractPath(fileName)),
+    );
+  }
+
+  constructor(
+    readonly path: string,
+    readonly content: string,
+    readonly siblingFiles: string[],
+  ) {}
+  get kind() {
+    return AbstractDoc.kindOf(this.path);
+  }
+  get folderName() {
+    return this.path.split("/").at(-2) ?? "";
+  }
+  get moduleName() {
+    return (this.path.split("/").at(-1) ?? "").slice(0, -AbstractDoc.suffix.length);
+  }
+  get lineCount() {
+    return AbstractDoc.lineCountOf(this.content);
+  }
+  // An AI editor answers in prose when it decides nothing needs changing, and that prose would silently
+  // replace the abstract — so a candidate must look like a markdown file and be shorter than what it replaces.
+  canReplaceWith(candidate: string) {
+    const next = candidate.trim();
+    if (!next.startsWith("#")) return false;
+    const lineCount = AbstractDoc.lineCountOf(next);
+    return lineCount >= 3 && lineCount < this.lineCount;
+  }
+}

package/executors.ts

@@ -1451,7 +1451,7 @@ export class AppExecutor extends SysExecutor {
     if (!devOnlyKeys.size) return pageKeys;
     const isDevOnly = (key: string) => devOnlyKeys.has(key) || devOnlyDirs.some((dir) => key.startsWith(dir));
     const dropped = pageKeys.filter(isDevOnly);
-    this.log(`[route] excluded ${dropped.length} dev-only route file(s) from the build: ${dropped.join(", ")}`);
+    this.verbose(`[route] excluded ${dropped.length} dev-only route file(s) from the build: ${dropped.join(", ")}`);
     return pageKeys.filter((key) => !isDevOnly(key));
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.2-rc.1",
+  "version": "2.4.2-rc.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.2-rc.1",
+    "akanjs": "2.4.2-rc.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/qualityScanner.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AbstractDoc } from "./abstractDoc";
+import { AkanQualityScanner } from "./qualityScanner";
+
+const tempRoots: string[] = [];
+
+const makeWorkspace = async (files: Record<string, string>) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-quality-scanner-"));
+  tempRoots.push(root);
+  for (const [filePath, content] of Object.entries({ ".gitignore": "node_modules\n", ...files })) {
+    const absolutePath = path.join(root, filePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content);
+  }
+  return root;
+};
+
+const abstractOf = (lineNum: number) =>
+  ["# post Abstract", ...Array.from({ length: lineNum - 1 }, (_, idx) => `- rule ${idx}`)].join("\n");
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("AkanQualityScanner abstract rule", () => {
+  test("warns on an abstract over the line limit and points at akan compact", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/post.abstract.md": abstractOf(AbstractDoc.maxLines + 1),
+      "apps/demo/lib/post/post.constant.ts": "export class Post {}\n",
+      "libs/shared/lib/user/user.abstract.md": abstractOf(AbstractDoc.maxLines),
+      "libs/shared/lib/user/user.constant.ts": "export class User {}\n",
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+    const warnings = result.warnings.filter((warning) => warning.rule === "akan.file.abstract-max-lines");
+
+    expect(result.scannedFiles).toBe(4);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/lib/post/post.abstract.md");
+    expect(warnings[0]?.message).toContain(`${AbstractDoc.maxLines + 1} lines`);
+    expect(warnings[0]?.fix).toContain("akan compact");
+  });
+});

package/qualityScanner.ts

@@ -3,6 +3,7 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import ignore from "ignore";
 import ts from "typescript";
+import { AbstractDoc } from "./abstractDoc";
 
 type QualitySeverity = "warning";
 type QualityScope = "global" | "file" | "convention" | "layout";
@@ -32,6 +33,11 @@ interface SourceFileInfo {
   sourceFile: ts.SourceFile;
 }
 
+interface TextFileInfo {
+  file: string;
+  content: string;
+}
+
 interface ExportedFunctionLike {
   name: string;
   kind: "class" | "function" | "function-variable";
@@ -142,6 +148,8 @@ const RULE_FIXES: Record<string, string> = {
   "akan.file.recommended-max-lines":
     "Split the file by responsibility — move Zones, Utils, or subcomponents into sibling files.",
   "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
+  "akan.file.abstract-max-lines":
+    "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.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
@@ -172,18 +180,28 @@ function getRuleFix(rule: string): string | undefined {
 export class AkanQualityScanner {
   async scan(workspaceRoot: string): Promise<QualityScanResult> {
     const targetFiles = await this.#collectTargetFiles(workspaceRoot);
-    const sourceFiles = await Promise.all(targetFiles.map((file) => this.#readSourceFile(workspaceRoot, file)));
+    const sourceFiles = await Promise.all(
+      targetFiles
+        .filter((file) => !AbstractDoc.isAbstractPath(file))
+        .map((file) => this.#readSourceFile(workspaceRoot, file)),
+    );
+    const abstractFiles = await Promise.all(
+      targetFiles
+        .filter((file) => AbstractDoc.isAbstractPath(file))
+        .map((file) => this.#readTextFile(workspaceRoot, file)),
+    );
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile) => this.#scanSingleFileQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanComponentQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
+      ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
     ];
 
     return {
       workspaceRoot,
-      scannedFiles: sourceFiles.length,
+      scannedFiles: sourceFiles.length + abstractFiles.length,
       warnings: warnings
         .map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) }))
         .sort(compareWarnings),
@@ -226,6 +244,8 @@ export class AkanQualityScanner {
       }
       if ((relativePath.endsWith(".ts") || relativePath.endsWith(".tsx")) && !relativePath.endsWith(".d.ts")) {
         files.push(relativePath);
+      } else if (AbstractDoc.isAbstractPath(relativePath)) {
+        files.push(relativePath);
       }
     }
   }
@@ -241,6 +261,10 @@ export class AkanQualityScanner {
     };
   }
 
+  async #readTextFile(workspaceRoot: string, file: string): Promise<TextFileInfo> {
+    return { file, content: await readFile(path.join(workspaceRoot, file), "utf8") };
+  }
+
   #scanGlobalQuality(sourceFiles: SourceFileInfo[]): QualityWarning[] {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
     const warnings: QualityWarning[] = [];
@@ -391,6 +415,20 @@ export class AkanQualityScanner {
     return warnings;
   }
 
+  #scanAbstractQuality({ file, content }: TextFileInfo): QualityWarning[] {
+    const lineCount = AbstractDoc.lineCountOf(content);
+    if (lineCount <= AbstractDoc.maxLines) return [];
+    return [
+      {
+        rule: "akan.file.abstract-max-lines",
+        scope: "file",
+        severity: "warning",
+        file,
+        message: `Abstract has ${lineCount} lines. Keep abstracts under ${AbstractDoc.maxLines} lines and compact them periodically.`,
+      },
+    ];
+  }
+
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
     const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];