@akanjs/devkit 3.1.1-rc.15 → 3.1.1-rc.17

package/componentWriteChainScanner.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { ComponentWriteChainScanner } from "./componentWriteChainScanner";
+import type { SourceFileInfo } from "./qualityScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { WritingActionIndex } from "./writingActionIndex";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(
+    file,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  ),
+});
+
+const index = new WritingActionIndex(
+  new SignalMutationIndex([
+    fileOf(
+      "apps/demo/lib/court/court.signal.ts",
+      `export class CourtSlice extends slice(srv.court, { guards: { root: Admin, cru: User } }, () => ({})) {}
+export class CourtEndpoint extends endpoint(srv.court, ({ query, mutation }) => ({
+  skipNvrOnCourt: mutation(cnst.Court, { guards: [User] }).param("courtId", ID).exec(() => null),
+  courtCount: query(Int, { guards: [User] }).exec(() => 0),
+})) {}
+`,
+    ),
+  ]),
+  [
+    fileOf(
+      "apps/demo/lib/court/court.store.ts",
+      `import { fetch, sig } from "../useClient";
+export class CourtStore extends store(sig.court, () => ({})) {
+  async skipNvrOnCourt(courtId: string) {
+    this.setCourt(await fetch.skipNvrOnCourt(courtId));
+  }
+  async loadCourtCount() {
+    this.set({ count: await fetch.courtCount() });
+  }
+}
+`,
+    ),
+  ],
+);
+
+const chainsIn = (body: string) =>
+  new ComponentWriteChainScanner(index).scan(
+    fileOf(
+      "apps/demo/lib/court/Court.Zone.tsx",
+      `"use client";\nimport { st } from "@apps/demo/client";\n\nexport const Install = ({ courtId }: { courtId: string }) => {\n${body}\n};\n`,
+    ).sourceFile,
+  );
+
+describe("ComponentWriteChainScanner", () => {
+  test("reports one handler sending two writing actions at the second", () => {
+    const chains = chainsIn(`  const register = st
+    .tool("registerNvr")
+    .exec(async () => {
+      await st.do.updateCourt(courtId, {});
+      await st.do.loadCourtCount();
+      await st.do.skipNvrOnCourt(courtId);
+    });
+  return <button type="button" onClick={() => void register()} />;`);
+
+    expect(chains).toEqual([
+      { component: "Install", line: 10, writes: ["st.do.updateCourt", "st.do.skipNvrOnCourt"], writeCount: 2 },
+    ]);
+  });
+
+  test("passes two writes in two separate handlers, a render callback included", () => {
+    const chains = chainsIn(`  const courtIds = [courtId];
+  return (
+    <div>
+      {courtIds.map((id) => (
+        <div key={id}>
+          <button type="button" onClick={() => void st.do.removeCourt(id)} />
+          <button type="button" onClick={() => void st.do.skipNvrOnCourt(id)} />
+        </div>
+      ))}
+    </div>
+  );`);
+
+    expect(chains).toEqual([]);
+  });
+
+  test("reads exclusive branches as one and an array or promise callback as part of its handler", () => {
+    const chains = chainsIn(`  const onSave = async (isNew: boolean) => {
+    if (isNew) await st.do.createCourt({});
+    else await st.do.updateCourt(courtId, {});
+  };
+  const onRemoveAll = async (ids: string[]) => {
+    await Promise.all(ids.map((id) => st.do.removeCourt(id)));
+    await st.do.submitCourt().then(() => st.do.mergeCourt(courtId, {}));
+  };
+  return <button type="button" onClick={() => void onSave(true)} />;`);
+
+    expect(chains).toEqual([
+      {
+        component: "Install",
+        line: 11,
+        writes: ["st.do.removeCourt (per item)", "st.do.submitCourt", "st.do.mergeCourt"],
+        writeCount: 4,
+      },
+    ]);
+  });
+
+  test("reads one write per item as a chain, in a loop or a per-element callback, and a hook like a component", () => {
+    const loop = chainsIn(`  const onRemoveAll = async (ids: string[]) => {
+    for (const id of ids) await st.do.removeCourt(id);
+  };
+  return <button type="button" onClick={() => void onRemoveAll([courtId])} />;`);
+    const hook = new ComponentWriteChainScanner(index).scan(
+      fileOf(
+        "apps/demo/webkit/useBulk.tsx",
+        'import { st } from "@apps/demo/client";\n\nexport const useBulk = () => ({\n  run: async (ids: string[]) => {\n    await Promise.all(ids.map((id) => st.do.removeCourt(id)));\n  },\n});\n',
+      ).sourceFile,
+    );
+
+    expect(loop).toEqual([{ component: "Install", line: 6, writes: ["st.do.removeCourt (per item)"], writeCount: 2 }]);
+    expect(hook).toEqual([{ component: "useBulk", line: 5, writes: ["st.do.removeCourt (per item)"], writeCount: 2 }]);
+  });
+
+  test("ignores a component file that does not import st", () => {
+    const chains = new ComponentWriteChainScanner(index).scan(
+      fileOf(
+        "apps/demo/ui/Plain.tsx",
+        "export const Plain = () => {\n  const onClick = async () => {\n    await st.do.createCourt({});\n    await st.do.removeCourt('a');\n  };\n  return null;\n};\n",
+      ).sourceFile,
+    );
+
+    expect(chains).toEqual([]);
+  });
+});

package/componentWriteChainScanner.ts

@@ -0,0 +1,104 @@
+import ts from "typescript";
+import { ComponentSizeScanner } from "./componentSizeScanner";
+import { StoreAccessScanner } from "./storeAccessScanner";
+import { WritePath } from "./writePath";
+import type { WritingActionIndex } from "./writingActionIndex";
+
+export interface ComponentWriteChain {
+  component: string;
+  line: number;
+  writes: string[];
+  writeCount: number;
+}
+
+//? A callback an array method or a promise runs belongs to the handler that started it; any other function is one.
+export class ComponentWriteChainScanner {
+  static readonly #inlineCallers = new Set([
+    "map",
+    "flatMap",
+    "forEach",
+    "filter",
+    "reduce",
+    "some",
+    "every",
+    "find",
+    "findIndex",
+    "then",
+    "catch",
+    "finally",
+  ]);
+  readonly #index: WritingActionIndex;
+
+  constructor(index: WritingActionIndex) {
+    this.#index = index;
+  }
+
+  scan(sourceFile: ts.SourceFile): ComponentWriteChain[] {
+    const stNames = StoreAccessScanner.stNamesOf(sourceFile);
+    if (!stNames.size) return [];
+    const path = new WritePath(
+      (call) => {
+        const action = ComponentWriteChainScanner.#actionOf(call.expression, stNames);
+        return !!action && this.#index.isWritingAction(action);
+      },
+      { enters: ComponentWriteChainScanner.#isInlineCallback },
+    );
+    return ComponentSizeScanner.componentsAndHooksOf(sourceFile).flatMap(({ name, node }) =>
+      ComponentWriteChainScanner.#handlersIn(node).flatMap((handler) => {
+        const writes = path.along(handler);
+        const writeCount = path.countOf(writes);
+        const second = writes[1] ?? writes[0];
+        if (writeCount < 2 || !second) return [];
+        return [
+          {
+            component: name,
+            line: sourceFile.getLineAndCharacterOfPosition(second.getStart(sourceFile)).line + 1,
+            writes: writes.map((call) => path.labelOf(call, sourceFile)),
+            writeCount,
+          },
+        ];
+      }),
+    );
+  }
+
+  static #handlersIn(component: ts.Node) {
+    const bodies: ts.ConciseBody[] = [];
+    const visit = (node: ts.Node) => {
+      if (
+        ComponentWriteChainScanner.#isFunction(node) &&
+        node.body &&
+        !ComponentWriteChainScanner.#isInlineCallback(node)
+      )
+        bodies.push(node.body);
+      ts.forEachChild(node, visit);
+    };
+    visit(component);
+    return bodies;
+  }
+
+  static #isFunction(node: ts.Node): node is ts.FunctionLikeDeclaration {
+    return (
+      ts.isArrowFunction(node) ||
+      ts.isFunctionExpression(node) ||
+      ts.isFunctionDeclaration(node) ||
+      ts.isMethodDeclaration(node)
+    );
+  }
+
+  static #isInlineCallback(fn: ts.Node) {
+    const call = fn.parent;
+    return (
+      !!call &&
+      ts.isCallExpression(call) &&
+      call.arguments.some((arg) => arg === fn) &&
+      ts.isPropertyAccessExpression(call.expression) &&
+      ComponentWriteChainScanner.#inlineCallers.has(call.expression.name.text)
+    );
+  }
+
+  static #actionOf(callee: ts.Expression, stNames: Set<string>) {
+    if (!ts.isPropertyAccessExpression(callee) || !ts.isPropertyAccessExpression(callee.expression)) return null;
+    const { expression: st, name } = callee.expression;
+    return ts.isIdentifier(st) && stNames.has(st.text) && name.text === "do" ? callee.name.text : null;
+  }
+}

package/conventionSet.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import fsPromise from "node:fs/promises";
+import path from "node:path";
+import { ConventionSet } from "./conventionSet";
+import { MaintainabilityContract } from "./maintainabilityContract";
+import { Prompter } from "./prompter";
+
+describe("ConventionSet", () => {
+  test("expands every brace list, so a comma-separated glob field can carry it", () => {
+    expect(ConventionSet.expand("{apps,libs}/**/*.{ts,tsx}")).toEqual([
+      "apps/**/*.ts",
+      "apps/**/*.tsx",
+      "libs/**/*.ts",
+      "libs/**/*.tsx",
+    ]);
+    expect(ConventionSet.expand("**/.env*")).toEqual(["**/.env*"]);
+  });
+
+  test("reads a rule's description and paths from its frontmatter, and refuses one without", () => {
+    const rule = ConventionSet.parseRule(
+      "page",
+      '---\ndescription: Route files.\npaths:\n  - "{apps,libs}/**/page/**"\n---\n\n# Pages\n',
+    );
+    expect(rule).toEqual({
+      name: "page",
+      description: "Route files.",
+      paths: ["{apps,libs}/**/page/**"],
+      body: "# Pages",
+    });
+    expect(() => ConventionSet.parseRule("bare", "# Pages\n")).toThrow("no frontmatter");
+    expect(() => ConventionSet.parseRule("empty", "---\ndescription: x\n---\n")).toThrow("description and paths");
+  });
+
+  test("nests each rule under the core when composed, leaving fenced code alone", () => {
+    const set = new ConventionSet("## Core", [
+      { name: "a", description: "d", paths: ["x"], body: "# A\n\n## Part\n\n```sh\n# a comment\n```" },
+    ]);
+    expect(set.instruction).toBe("## Core\n\n## A\n\n### Part\n\n```sh\n# a comment\n```\n");
+  });
+
+  test("the shipped conventions guideline is the core followed by every rule", async () => {
+    const set = await Prompter.getConventionSet();
+    const instruction = await Prompter.getInstruction("conventions");
+    expect(set.rules.length).toBeGreaterThanOrEqual(10);
+    expect(instruction.startsWith(set.core)).toBe(true);
+    for (const rule of set.rules) {
+      expect(rule.body).toStartWith("# ");
+      expect(instruction).toContain(`\n#${rule.body.split("\n")[0]}\n`);
+    }
+  });
+
+  test("names only checks that exist, and names every lint plugin and maintainability gate somewhere", async () => {
+    const set = await Prompter.getConventionSet();
+    const named = new Set(
+      [set.core, ...set.rules.map((rule) => rule.body)].flatMap((text) =>
+        [...text.matchAll(/`([^`\s]+)`/g)].map((match) => match[1] ?? ""),
+      ),
+    );
+    const plugins = (await fsPromise.readdir(path.join(import.meta.dir, "lint")))
+      .filter((file) => file.endsWith(".grit"))
+      .map((file) => file.slice(0, -".grit".length));
+    const gates: readonly string[] = MaintainabilityContract.ruleIds;
+    const gateAreas = new Set(gates.map((id) => id.split(".").slice(0, 2).join(".")));
+    const isPluginName = (name: string) => /^non?-[a-z]+(-[a-z]+)+$/.test(name);
+    const isGateName = (name: string) =>
+      gateAreas.has(name.split(".").slice(0, 2).join(".")) && !name.endsWith(".json");
+
+    expect([...named].filter((name) => isPluginName(name) && !plugins.includes(name))).toEqual([]);
+    expect([...named].filter((name) => isGateName(name) && !gates.includes(name))).toEqual([]);
+    expect(plugins.filter((plugin) => !named.has(plugin))).toEqual([]);
+    expect(gates.filter((gate) => !named.has(gate))).toEqual([]);
+  });
+});

package/conventionSet.ts

@@ -0,0 +1,67 @@
+import fsPromise from "node:fs/promises";
+import path from "node:path";
+
+export interface ConventionRule {
+  name: string;
+  description: string;
+  paths: string[];
+  body: string;
+}
+
+export class ConventionSet {
+  constructor(
+    readonly core: string,
+    readonly rules: ConventionRule[],
+  ) {}
+
+  static async load(dir: string) {
+    const core = await fsPromise.readFile(path.join(dir, "core.md"), "utf-8");
+    const files = (await fsPromise.readdir(path.join(dir, "rules"))).filter((file) => file.endsWith(".md")).sort();
+    const rules = await Promise.all(
+      files.map(async (file) =>
+        ConventionSet.parseRule(file.slice(0, -3), await fsPromise.readFile(path.join(dir, "rules", file), "utf-8")),
+      ),
+    );
+    return new ConventionSet(core.trim(), rules);
+  }
+
+  static parseRule(name: string, text: string): ConventionRule {
+    const match: RegExpExecArray | null = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (!match) throw new Error(`Convention rule ${name} has no frontmatter`);
+    const front = match[1] ?? "";
+    const described: RegExpExecArray | null = /^description:\s*(.+)$/m.exec(front);
+    const description = described?.[1]?.trim() ?? "";
+    const paths = [...front.matchAll(/^\s+-\s+"([^"]+)"$/gm)].map((entry) => entry[1] ?? "");
+    if (!description || paths.length === 0) throw new Error(`Convention rule ${name} needs a description and paths`);
+    return { name, description, paths, body: text.slice(match[0].length).trim() };
+  }
+
+  //? Cursor splits `globs:` on commas, so a `{a,b}` brace list has to be expanded before it is written there.
+  static expand(glob: string): string[] {
+    const open = glob.indexOf("{");
+    if (open === -1) return [glob];
+    const close = glob.indexOf("}", open);
+    if (close === -1) return [glob];
+    const head = glob.slice(0, open);
+    const tail = glob.slice(close + 1);
+    return glob
+      .slice(open + 1, close)
+      .split(",")
+      .flatMap((choice) => ConventionSet.expand(`${head}${choice}${tail}`));
+  }
+
+  static demote(markdown: string) {
+    let fenced = false;
+    return markdown
+      .split("\n")
+      .map((line) => {
+        if (line.startsWith("```")) fenced = !fenced;
+        return !fenced && /^#{1,5} /.test(line) ? `#${line}` : line;
+      })
+      .join("\n");
+  }
+
+  get instruction() {
+    return `${[this.core, ...this.rules.map((rule) => ConventionSet.demote(rule.body))].join("\n\n")}\n`;
+  }
+}

package/deprecatedCommentScanner.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { DeprecatedCommentScanner } from "./deprecatedCommentScanner";
+import type { SourceFileInfo } from "./qualityScanner";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS),
+});
+
+const scan = (file: string, lines: string[]) =>
+  new DeprecatedCommentScanner().scan([fileOf(file, `${lines.join("\n")}\n`)]);
+
+describe("DeprecatedCommentScanner", () => {
+  test("flags a trailing, a leading and a block deprecated comment", () => {
+    const warnings = scan("apps/demo/lib/court/court.constant.ts", [
+      "export class CourtInput extends via((field) => ({",
+      "  legacyVenue: field(String).optional(), // deprecated",
+      "  // Deprecated: use courtId",
+      "  legacyCourt: field(String).optional(),",
+      "  /* DEPRECATED */ oldName: field(String).optional(),",
+      "  /** deprecated, read venueId */ oldVenue: field(String).optional(),",
+      "})) {}",
+    ]);
+
+    expect(warnings.map((warning) => warning.line)).toEqual([2, 3, 5, 6]);
+    expect(warnings[0]).toMatchObject({ rule: "akan.comment.deprecated-marker", scope: "comment" });
+    expect(warnings[0]?.message).toContain('"// deprecated"');
+  });
+
+  test("leaves a JSDoc @deprecated tag and prose that only mentions deprecation", () => {
+    expect(
+      scan("libs/demo/ui/field.type.ts", [
+        "export interface FieldProps {",
+        "  /** @deprecated Ignored: the field renders `value`. */",
+        "  defaultValue?: string;",
+        "  /**",
+        "   * Old name.",
+        "   * @deprecated use `value`",
+        "   */",
+        "  initial?: string;",
+        "}",
+        "// Replaces the deprecated upstream plugin.",
+        "export const notice = '// deprecated';",
+      ]),
+    ).toEqual([]);
+  });
+
+  test("stays out of tests", () => {
+    expect(scan("apps/demo/lib/court/court.signal.test.ts", ["const venue = 1; // deprecated"])).toEqual([]);
+  });
+});

package/deprecatedCommentScanner.ts

@@ -0,0 +1,30 @@
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+import { type SourceComment, SourceComments } from "./sourceComments";
+
+export class DeprecatedCommentScanner {
+  static readonly rule = "akan.comment.deprecated-marker";
+  static #marker = /^[!?*\s]*(?:(?:TODO|FIXME|XXX|NOTE)\b\s*:?\s*)?@?deprecated\b/i;
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    return sourceFiles
+      .filter(({ file }) => /^(apps|libs)\//.test(file) && !/\.(test|spec)\.tsx?$/.test(file))
+      .flatMap(({ file, sourceFile }) =>
+        SourceComments.of(sourceFile)
+          .filter((comment) => DeprecatedCommentScanner.#isLooseMarker(comment))
+          .map((comment) => ({
+            rule: DeprecatedCommentScanner.rule,
+            scope: "comment" as const,
+            severity: "warning" as const,
+            file,
+            line: comment.line,
+            message: `"${comment.raw.split(/\r?\n/)[0]?.trim().slice(0, 80)}" marks nothing at the use sites; editors strike through only a JSDoc @deprecated tag.`,
+          })),
+      );
+  }
+
+  static #isLooseMarker({ isJsDoc, body }: SourceComment) {
+    const text = body.filter((line) => line !== "").join(" ");
+    if (isJsDoc && /(^|\s)@deprecated\b/.test(text)) return false;
+    return DeprecatedCommentScanner.#marker.test(text);
+  }
+}

package/endpointReach.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { EndpointReach } from "./endpointReach";
+
+const fileOf = (file: string, content: string) => ({
+  file,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true),
+});
+
+describe("EndpointReach", () => {
+  test("follows an endpoint or a slice through its service's own and other services' methods, not a job", () => {
+    const reach = new EndpointReach(
+      [
+        fileOf(
+          "apps/demo/lib/court/court.signal.ts",
+          `export class CourtInternal extends internal(srv.court, ({ cron }) => ({
+  sweep: cron("0 * * * *").exec(function () { return this.courtService.sweep(); }),
+})) {}
+export class CourtSlice extends slice(srv.court, { guards: { root: Admin } }, (init) => ({
+  inOrg: init().exec(function (orgId) { return this.courtService.queryInOrg(orgId); }),
+})) {}
+export class CourtEndpoint extends endpoint(srv.court, ({ mutation }) => ({
+  assign: mutation(Boolean).exec(function (id) { return this.courtService.assign(id); }),
+})) {}
+`,
+        ),
+      ],
+      [
+        fileOf(
+          "apps/demo/lib/court/court.service.ts",
+          `export class CourtService extends serve(db.court, () => ({})) {
+  queryInOrg(orgId: string) { return { orgId }; }
+  async assign(id: string) { return await this.#pick(id); }
+  async #pick(id: string) { return await this.pcService.claim(id); }
+  async sweep() { return await this.#pick("all"); }
+}
+`,
+        ),
+        fileOf(
+          "libs/shared/lib/_pc/pc.service.ts",
+          `export class PcService extends serve("pc", () => ({})) {
+  async claim(id: string) { return id; }
+  async release(id: string) { return id; }
+}
+`,
+        ),
+      ],
+    );
+
+    expect(EndpointReach.serviceOf("libs/shared/lib/_pc/pc.service.ts")).toBe("pc");
+    expect(
+      ["court.queryInOrg", "court.assign", "court.#pick", "pc.claim", "court.sweep", "pc.release"].map((key) => {
+        const [service = "", method = ""] = key.split(".");
+        return reach.reaches(service, method);
+      }),
+    ).toEqual([true, true, true, true, false, false]);
+  });
+});

package/endpointReach.ts

@@ -0,0 +1,80 @@
+import path from "node:path";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+
+type ServiceMethod = [service: string, method: string];
+
+//? Only `endpoint(…)` and `slice(…)` answer a caller who waits; an `internal(…)` job (cron, interval, queue) works
+//? per item on purpose, so that one failing item leaves the rest done.
+export class EndpointReach {
+  static readonly #requestBuilders = new Set(["endpoint", "slice"]);
+  readonly #reached = new Set<string>();
+
+  constructor(
+    signalFiles: Pick<SourceFileInfo, "sourceFile">[],
+    serviceFiles: Pick<SourceFileInfo, "file" | "sourceFile">[],
+  ) {
+    const methodsByService = new Map<string, Map<string, ts.MethodDeclaration>>();
+    for (const { file, sourceFile } of serviceFiles) {
+      const methods = methodsByService.get(EndpointReach.serviceOf(file)) ?? new Map<string, ts.MethodDeclaration>();
+      for (const cls of sourceFile.statements.filter(ts.isClassDeclaration))
+        for (const member of cls.members)
+          if (
+            ts.isMethodDeclaration(member) &&
+            member.body &&
+            (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name))
+          )
+            methods.set(member.name.text, member);
+      methodsByService.set(EndpointReach.serviceOf(file), methods);
+    }
+    const pending: ServiceMethod[] = [];
+    const reach = ([service, method]: ServiceMethod) => {
+      const key = `${service}.${method}`;
+      if (this.#reached.has(key) || !methodsByService.get(service)?.has(method)) return;
+      this.#reached.add(key);
+      pending.push([service, method]);
+    };
+    for (const { sourceFile } of signalFiles)
+      for (const cls of sourceFile.statements.filter(ts.isClassDeclaration)) {
+        const base = cls.heritageClauses?.[0]?.types[0]?.expression;
+        if (
+          base &&
+          ts.isCallExpression(base) &&
+          ts.isIdentifier(base.expression) &&
+          EndpointReach.#requestBuilders.has(base.expression.text)
+        )
+          EndpointReach.#serviceCallsIn(base, null).forEach(reach);
+      }
+    for (let next = pending.pop(); next; next = pending.pop()) {
+      const [service, method] = next;
+      const declaration = methodsByService.get(service)?.get(method);
+      if (declaration) EndpointReach.#serviceCallsIn(declaration, service).forEach(reach);
+    }
+  }
+
+  static serviceOf(file: string) {
+    return path.posix.basename(file).replace(/\.service\.ts$/, "");
+  }
+
+  reaches(service: string, method: string) {
+    return this.#reached.has(`${service}.${method}`);
+  }
+
+  static #serviceCallsIn(node: ts.Node, ownService: string | null) {
+    const calls: ServiceMethod[] = [];
+    const visit = (child: ts.Node) => {
+      if (ts.isCallExpression(child) && ts.isPropertyAccessExpression(child.expression)) {
+        const { expression: owner, name } = child.expression;
+        if (owner.kind === ts.SyntaxKind.ThisKeyword && ownService) calls.push([ownService, name.text]);
+        else if (ts.isPropertyAccessExpression(owner) && owner.expression.kind === ts.SyntaxKind.ThisKeyword) {
+          const field = owner.name.text;
+          if (field.length > "Service".length && field.endsWith("Service"))
+            calls.push([field.slice(0, -"Service".length), name.text]);
+        }
+      }
+      ts.forEachChild(child, visit);
+    };
+    visit(node);
+    return calls;
+  }
+}

package/executors.test.ts

@@ -275,10 +275,6 @@ describe("Executor filesystem helpers", () => {
       "Akan workspace agent guide",
     );
     expect(await readFile(path.join(root, "workspace/AGENTS.md"), "utf8")).toContain("sample Agent Guide");
-    expect(await readFile(path.join(root, "workspace/docs/AI-DEVELOPMENT.md"), "utf8")).toContain(
-      "AI Development Guide",
-    );
-    expect(await readFile(path.join(root, "workspace/docs/GENERATED.md"), "utf8")).toContain("Generated Akan Files");
     // Rules live in the package's base config, so a framework release reaches an existing workspace on `bun update`.
     expect(await readFile(path.join(root, "workspace/biome.json"), "utf8")).toContain(
       '"extends": ["@akanjs/devkit/biome.base.json"]',

package/index.ts

@@ -19,6 +19,7 @@ export type * from "./fileSys";
 export type * from "./frontendBuild";
 export type * from "./getRelatedCnsts";
 export type * from "./incrementalBuilder";
+export type * from "./maintainabilityContract";
 export type * from "./mobile";
 export type * from "./packageExportsMap";
 export type * from "./prompter";