@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.21

package/workflow/sourceAst.ts

@@ -0,0 +1,50 @@
+import ts from "typescript";
+
+export const sourceFileFor = (fileName: string, content: string) =>
+  ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+
+export const nodeName = (node: ts.PropertyName | ts.BindingName | undefined) => {
+  if (!node) return null;
+  if (ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node)) return node.text;
+  return null;
+};
+
+export const propertyName = (node: ts.ObjectLiteralElementLike) =>
+  ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node) || ts.isMethodDeclaration(node)
+    ? nodeName(node.name)
+    : null;
+
+export const expressionName = (expression: ts.Expression): string | null => {
+  if (ts.isIdentifier(expression)) return expression.text;
+  if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
+  if (ts.isCallExpression(expression)) return expressionName(expression.expression);
+  if (ts.isAsExpression(expression)) return expressionName(expression.expression);
+  return null;
+};
+
+export const callExpressionName = (node: ts.CallExpression) =>
+  ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : expressionName(node.expression);
+
+export const firstObjectReturnedByArrow = (node: ts.Node): ts.ObjectLiteralExpression | null => {
+  if (!ts.isArrowFunction(node) && !ts.isFunctionExpression(node)) return null;
+  if (ts.isObjectLiteralExpression(node.body)) return node.body;
+  if (ts.isParenthesizedExpression(node.body) && ts.isObjectLiteralExpression(node.body.expression)) {
+    return node.body.expression;
+  }
+  if (!ts.isBlock(node.body)) return null;
+  for (const statement of node.body.statements) {
+    if (ts.isReturnStatement(statement) && statement.expression && ts.isObjectLiteralExpression(statement.expression)) {
+      return statement.expression;
+    }
+  }
+  return null;
+};
+
+const isViaCall = (expression: ts.Expression) =>
+  ts.isCallExpression(expression) && expressionName(expression.expression) === "via";
+
+export const heritageCall = (node: ts.ClassDeclaration) => {
+  const heritage = node.heritageClauses?.flatMap((clause) => [...clause.types]) ?? [];
+  const expression = heritage.find((clause) => isViaCall(clause.expression))?.expression;
+  return expression && ts.isCallExpression(expression) ? expression : null;
+};

package/workspaceLayout.test.ts

@@ -6,6 +6,7 @@ import {
   isScannedRootEntry,
   libRootAllowedDirs,
   libRootAllowedFiles,
+  rootEntryHintOf,
 } from "./workspaceLayout";
 
 describe("app root layout allowlist", () => {
@@ -15,7 +16,7 @@ describe("app root layout allowlist", () => {
   });
 
   test("admits every documented app root folder", () => {
-    for (const dirname of ["mobile", "plugin", "secrets", "srvkit", "webkit"]) {
+    for (const dirname of [".akan", "plugin", "script", "secrets", "srvkit", "webkit"]) {
       expect(appRootAllowedDirs.has(dirname)).toBe(true);
     }
   });
@@ -25,6 +26,15 @@ describe("app root layout allowlist", () => {
     expect(appRootAllowedDirs.has("base")).toBe(false);
   });
 
+  test("names what a Capacitor app kept in its root as a leftover, not an unknown entry", () => {
+    for (const name of ["android", "ios", "mobile", "capacitor.config.ts", "capacitor.config.json"]) {
+      expect(appRootAllowedFiles.has(name) || appRootAllowedDirs.has(name)).toBe(false);
+      expect(rootEntryHintOf("app", name)).toContain(".akan/mobile/<target>");
+    }
+    expect(rootEntryHintOf("app", "base")).toBeNull();
+    expect(rootEntryHintOf("lib", "ios")).toBeNull();
+  });
+
   test("skips dotfile artifacts the sync glob never sees, but keeps .akan", () => {
     expect(isScannedRootEntry("app", ".DS_Store")).toBe(false);
     expect(isScannedRootEntry("app", ".akan")).toBe(true);
@@ -48,10 +58,10 @@ describe("lib root layout allowlist", () => {
   });
 
   test("rejects the app-only run and mobile entries", () => {
-    for (const filename of ["main.ts", "capacitor.config.ts", "akan.app.json"]) {
+    for (const filename of ["main.ts", "akan.app.json"]) {
       expect(libRootAllowedFiles.has(filename)).toBe(false);
     }
-    for (const dirname of [".akan", "android", "ios", "mobile", "script", "secrets"]) {
+    for (const dirname of [".akan", "script", "secrets"]) {
       expect(libRootAllowedDirs.has(dirname)).toBe(false);
     }
   });

package/workspaceLayout.ts

@@ -1,21 +1,13 @@
-/**
- * App/lib 루트 레이아웃 허용 목록 — 단일 소스.
- *
- * 같은 규칙을 scanInfo(`akan sync`, hard error) · akanContext(`akan doctor`, diagnostic) ·
- * qualityScanner(`akan quality scan`, warning) 세 곳이 각자 복사해 두면서 실제로 어긋났다
- * (스코프 AGENTS.md/CLAUDE.md 는 sync 만 허용, `plugin` 은 문서에만, `secrets` 는 doctor 만 거부).
- * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 의 목록도 같이 갱신한다.
- */
+// The one source of the app/lib root allowlists (sync, doctor and quality scan read it); mirror a change into the
+// root AGENTS.md list.
 
 export type SysType = "app" | "lib";
 
 export const appRootAllowedFiles = new Set([
-  // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
   "AGENTS.md",
   "CLAUDE.md",
   "akan.app.json",
   "akan.config.ts",
-  "capacitor.config.ts",
   "client.ts",
   "main.ts",
   "package.json",
@@ -26,12 +18,9 @@ export const appRootAllowedFiles = new Set([
 
 export const appRootAllowedDirs = new Set([
   ".akan",
-  "android",
   "common",
   "env",
-  "ios",
   "lib",
-  "mobile",
   "page",
   "plugin",
   "private",
@@ -43,12 +32,7 @@ export const appRootAllowedDirs = new Set([
   "webkit",
 ]);
 
-/**
- * 라이브러리 루트는 앱 루트에서 실행/모바일 전용 항목(`main.ts`, `capacitor.config.ts`, `.akan`,
- * `android`, `ios`, `mobile`, `script`, `secrets`)을 뺀 집합이다 — 라이브러리는 부팅되지도, 패키징되지도
- * 않는다. `index.ts` 는 lib 에만 생성되고, `README.md` / `tsconfig.spec.json` 은 라이브러리가 패키지로
- * 배포되기 때문에 남는다. `public` / `private` 은 syncAssets 가 앱으로 심링크하므로 라이브러리도 가진다.
- */
+// A library is never booted or packaged as an app, so the run/mobile entries are out; it is published, so README stays.
 export const libRootAllowedFiles = new Set([
   "AGENTS.md",
   "CLAUDE.md",
@@ -98,9 +82,22 @@ const libFacetRootTestPattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(
 export const isAllowedLibFacetRootFile = (filename: string) =>
   libFacetRootAllowedFiles.has(filename) || libFacetRootTestPattern.test(filename);
 
-/**
- * scanSync 는 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
- * doctor 가 그 차이만큼 `.DS_Store` 같은 툴 산출물을 에러로 올리므로 같은 기준으로 걸러낸다.
- */
+//* What a Capacitor app kept in its root. The native runtime generates its projects under `.akan/mobile/<target>`, so
+//* these are named as leftovers instead of as unknown entries.
+const retiredAppRootEntries = new Set([
+  "android",
+  "ios",
+  "mobile",
+  "capacitor.config.ts",
+  "capacitor.config.js",
+  "capacitor.config.json",
+]);
+
+export const rootEntryHintOf = (type: SysType, name: string) =>
+  type === "app" && retiredAppRootEntries.has(name)
+    ? "a Capacitor-era entry; the native runtime generates its projects under .akan/mobile/<target>, so delete it"
+    : null;
+
+// scanSync reads roots through `Bun.Glob("*")`, which skips dotfiles, so doctor skips them the same way.
 export const isScannedRootEntry = (type: SysType, name: string) =>
   !name.startsWith(".") || rootAllowedDirs[type].has(name);

package/abstractCompactor.ts

@@ -1,112 +0,0 @@
-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/aiEditor.test.ts

@@ -1,60 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { parseTypescriptFileBlocks, preserveTypescriptResponseContent } from "./aiEditor";
-
-describe("parseTypescriptFileBlocks", () => {
-  test("parses TypeScript file blocks with common fence variants", () => {
-    const writes = parseTypescriptFileBlocks(`
-\`\`\`ts
-
-// File: lib/car/car.constant.ts
-
-export const car = "car";
-\`\`\`
-
-\`\`\`tsx
-  // File: lib/car/Car.Unit.tsx
-export const CarUnit = () => null;
-\`\`\`
-`);
-
-    expect(writes).toEqual([
-      {
-        filePath: "lib/car/car.constant.ts",
-        content: 'export const car = "car";',
-      },
-      {
-        filePath: "lib/car/Car.Unit.tsx",
-        content: "export const CarUnit = () => null;",
-      },
-    ]);
-  });
-
-  test("keeps previous code response when validation responds with prose only", () => {
-    const previousContent = `
-\`\`\`typescript
-// File: lib/car/car.constant.ts
-export const car = "car";
-\`\`\`
-`;
-    const nextContent = "The generated file meets all specified requirements. No rewrite is necessary.";
-
-    expect(preserveTypescriptResponseContent(previousContent, nextContent)).toBe(previousContent);
-  });
-
-  test("uses next code response when validation rewrites with parseable files", () => {
-    const previousContent = `
-\`\`\`typescript
-// File: lib/car/car.constant.ts
-export const car = "car";
-\`\`\`
-`;
-    const nextContent = `
-\`\`\`typescript
-// File: lib/car/car.constant.ts
-export const car = "updated";
-\`\`\`
-`;
-
-    expect(preserveTypescriptResponseContent(previousContent, nextContent)).toBe(nextContent);
-  });
-});