@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

package/serviceLoopCallScanner.ts

@@ -0,0 +1,122 @@
+import ts from "typescript";
+import { WritePath } from "./writePath";
+
+export interface ServiceLoopCall {
+  method: string;
+  line: number;
+  calls: string[];
+}
+
+type NamedMethod = ts.MethodDeclaration & { name: ts.Identifier | ts.PrivateIdentifier };
+
+type PerItem = false | "loop" | "callback";
+
+//? A counted loop (`for (;;)`, `while`) retries or pages through a query, so only a loop over items is per item.
+export class ServiceLoopCallScanner {
+  static readonly #reachingField = /(?:Service|Model)$/;
+  static readonly #generatedQuery =
+    /^_*(?:get|load|list|find|pick|exists|count|insight|create|update|remove|search)[A-Z]/;
+
+  scan(sourceFile: ts.SourceFile, answersCaller: (method: string) => boolean): ServiceLoopCall[] {
+    return sourceFile.statements.filter(ts.isClassDeclaration).flatMap((cls) => {
+      const methods = cls.members.filter(
+        (member): member is NamedMethod =>
+          ts.isMethodDeclaration(member) &&
+          !!member.body &&
+          (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name)),
+      );
+      const declared = new Set(methods.map((method) => method.name.text));
+      const reaching = ServiceLoopCallScanner.#reachingMethodsOf(methods, declared);
+      const reaches = (call: ts.CallExpression) => ServiceLoopCallScanner.#reaches(call, declared, reaching);
+      const ownModel = cls.name?.text.replace(/Service$/, "") ?? "";
+      return methods.flatMap((method) => {
+        if (!answersCaller(method.name.text)) return [];
+        const calls: ts.CallExpression[] = [];
+        const visit = (node: ts.Node, perItem: PerItem) => {
+          if (
+            perItem &&
+            ts.isCallExpression(node) &&
+            reaches(node) &&
+            !(perItem === "callback" && ServiceLoopCallScanner.#isBatchedLoad(node, declared, ownModel))
+          )
+            calls.push(node);
+          if (ts.isForOfStatement(node) || ts.isForInStatement(node)) {
+            visit(node.expression, perItem);
+            visit(node.statement, "loop");
+            return;
+          }
+          ts.forEachChild(node, (child) =>
+            visit(child, perItem === "loop" || !WritePath.isPerElementCallback(child) ? perItem : "callback"),
+          );
+        };
+        visit(method, false);
+        const first = calls[0];
+        if (!first) return [];
+        return [
+          {
+            method: method.name.text,
+            line: sourceFile.getLineAndCharacterOfPosition(first.getStart(sourceFile)).line + 1,
+            calls: calls.map((call) => call.expression.getText(sourceFile)),
+          },
+        ];
+      });
+    });
+  }
+
+  static #reachingMethodsOf(methods: NamedMethod[], declared: Set<string>) {
+    const reaching = new Set<string>();
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const method of methods) {
+        const name = method.name.text;
+        if (reaching.has(name)) continue;
+        let found = false;
+        const visit = (node: ts.Node) => {
+          if (found) return;
+          if (ts.isCallExpression(node) && ServiceLoopCallScanner.#reaches(node, declared, reaching)) found = true;
+          else ts.forEachChild(node, visit);
+        };
+        visit(method);
+        if (found) {
+          reaching.add(name);
+          grew = true;
+        }
+      }
+    }
+    return reaching;
+  }
+
+  //? `get<Model>` / `load<Model>` / `load<Model>Many` go through the model's DataLoader, so the calls a per-element
+  //? callback issues in one tick are one query; a `for…of` awaiting each item issues them a tick apart, one by one.
+  static #isBatchedLoad(call: ts.CallExpression, declared: Set<string>, ownModel: string) {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee)) return false;
+    const model = ServiceLoopCallScanner.#loadedModelOf(callee, declared, ownModel);
+    if (!model) return false;
+    const className = `${model.charAt(0).toUpperCase()}${model.slice(1)}`;
+    return [`get${className}`, `load${className}`, `load${className}Many`].includes(callee.name.text);
+  }
+
+  static #loadedModelOf(callee: ts.PropertyAccessExpression, declared: Set<string>, ownModel: string) {
+    const owner = callee.expression;
+    if (owner.kind === ts.SyntaxKind.ThisKeyword) return declared.has(callee.name.text) ? null : ownModel;
+    if (!ts.isPropertyAccessExpression(owner) || owner.expression.kind !== ts.SyntaxKind.ThisKeyword) return null;
+    return owner.name.text.match(/^(\w+)Model$/)?.[1] ?? null;
+  }
+
+  static #reaches(call: ts.CallExpression, declared: Set<string>, reaching: Set<string>) {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee)) return false;
+    const owner = callee.expression;
+    if (owner.kind === ts.SyntaxKind.ThisKeyword) {
+      const name = callee.name.text;
+      return declared.has(name) ? reaching.has(name) : ServiceLoopCallScanner.#generatedQuery.test(name);
+    }
+    return (
+      ts.isPropertyAccessExpression(owner) &&
+      owner.expression.kind === ts.SyntaxKind.ThisKeyword &&
+      ServiceLoopCallScanner.#reachingField.test(owner.name.text)
+    );
+  }
+}

package/shellOnlyEnv.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { ShellOnlyEnv } from "./shellOnlyEnv";
+
+const key = "AKAN_SHELL_ONLY_TEST_KEY";
+const shellValue = "from-shell";
+
+const inRepo = (files: Record<string, string>, run: (env: ShellOnlyEnv<typeof key>) => void) => {
+  const repo = mkdtempSync(path.join(tmpdir(), "akan-shell-only-env-"));
+  const cwd = process.cwd();
+  try {
+    for (const [name, content] of Object.entries(files)) writeFileSync(path.join(repo, name), content);
+    process.chdir(repo);
+    process.env[key] = shellValue;
+    run(new ShellOnlyEnv([key]));
+  } finally {
+    process.chdir(cwd);
+    delete process.env[key];
+    rmSync(repo, { recursive: true, force: true });
+  }
+};
+
+describe("ShellOnlyEnv", () => {
+  test.each([
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.development.local",
+    ".env.production",
+    ".env.production.local",
+    ".env.test",
+    ".env.test.local",
+  ])("ignores a key that %s names", (file) => {
+    inRepo({ [file]: `${key}=placeholder\n` }, (env) => {
+      expect(env.get(key)).toBeUndefined();
+      expect(env.ignored()).toEqual([
+        `${key} is set in ${file}, which the repository controls, so it is ignored. Export it in your shell instead.`,
+      ]);
+    });
+  });
+
+  test.each([
+    `${key}=placeholder`,
+    `export ${key}=placeholder`,
+    `  ${key} = placeholder`,
+    `${key}: placeholder`,
+    `export ${key}: placeholder`,
+    `${key}\t:\tplaceholder`,
+    `${key}:`,
+    `${key}=placeholder\r`,
+  ])("ignores a key set as %j", (line) => {
+    inRepo({ ".env": `OTHER_KEY=placeholder\n${line}\n` }, (env) => {
+      expect(env.get(key)).toBeUndefined();
+    });
+  });
+
+  test("reads the shell value when no dotenv file names the key", () => {
+    inRepo({ ".env": `OTHER_KEY=placeholder\n# ${key}=placeholder\n${key}_SUFFIX=placeholder\n` }, (env) => {
+      expect(env.get(key)).toBe(shellValue);
+      expect(env.ignored()).toEqual([]);
+    });
+  });
+});

package/shellOnlyEnv.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+// Bun loads the ones NODE_ENV picks from the working directory before code runs, so a cloned repo's file can set them.
+const dotenvFiles = [
+  ".env",
+  ".env.local",
+  ".env.development",
+  ".env.development.local",
+  ".env.production",
+  ".env.production.local",
+  ".env.test",
+  ".env.test.local",
+];
+// Bun also reads `KEY: value` lines.
+const assignedKey = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*[=:]/;
+
+// Judged by presence, not value: a comparison would trust whatever a parser difference with Bun's reader lets through.
+export class ShellOnlyEnv<Key extends string> {
+  readonly #keys: ReadonlySet<string>;
+  #cache: { cwd: string; found: Map<string, string> } | undefined;
+
+  constructor(keys: readonly Key[]) {
+    this.#keys = new Set(keys);
+  }
+
+  get(key: Key): string | undefined {
+    if (this.#found().has(key)) return undefined;
+    return process.env[key];
+  }
+
+  ignored() {
+    return [...this.#found()].map(
+      ([key, file]) =>
+        `${key} is set in ${file}, which the repository controls, so it is ignored. Export it in your shell instead.`,
+    );
+  }
+
+  #found() {
+    const cwd = process.cwd();
+    if (this.#cache?.cwd === cwd) return this.#cache.found;
+    const found = new Map<string, string>();
+    for (const name of dotenvFiles) {
+      const file = path.join(cwd, name);
+      if (!existsSync(file)) continue;
+      for (const line of readFileSync(file, "utf8").split("\n")) {
+        const key = line.match(assignedKey)?.[1];
+        if (key && this.#keys.has(key) && !found.has(key)) found.set(key, name);
+      }
+    }
+    this.#cache = { cwd, found };
+    return found;
+  }
+}

package/signalMutationIndex.test.ts

@@ -110,6 +110,21 @@ export class ItemEndpoint extends endpoint(srv.item, ({ query, mutation }) => ({
     expect(index.isMutation("apps/third/page/x.tsx", "approveTicket")).toBe(false);
   });
 
+  test("reads a lib page's call by its own lib's endpoint before another lib's of that name", () => {
+    const shared = fileOf(
+      "libs/shared/lib/_shared/shared.signal.ts",
+      `export class SharedEndpoint extends endpoint(srv.shared, ({ mutation }) => ({ syncFeed: mutation(Boolean, {}).exec(() => true) })) {}`,
+    );
+    const social = fileOf(
+      "libs/social/lib/_social/social.signal.ts",
+      `export class SocialEndpoint extends endpoint(srv.social, ({ query }) => ({ syncFeed: query(Boolean, {}).exec(() => true) })) {}`,
+    );
+    const index = new SignalMutationIndex([shared, social]);
+    expect(index.isMutation("libs/social/page/x.tsx", "syncFeed")).toBe(false);
+    expect(index.policyIndexOf("libs/social/page/x.tsx", "syncFeed")).toBeNull();
+    expect(index.isMutation("libs/shared/page/x.tsx", "syncFeed")).toBe(true);
+  });
+
   test("ignores signal tests and specs", () => {
     const spec = fileOf(
       "apps/demo/lib/ticket/ticket.signal.spec.ts",

package/signalMutationIndex.ts

@@ -1,3 +1,5 @@
+import { createAst, createFactReader, type FileFacts } from "@akanjs/language";
+import { modelNames } from "akanjs/common";
 import ts from "typescript";
 import type { SourceFileInfo } from "./qualityScanner";
 
@@ -8,8 +10,14 @@ interface EndpointShape {
 
 export class SignalMutationIndex {
   //? As the client generates them: `update<Model>(id, data, option?)`, `add<Model>Files(files, parentId?, option?)`.
-  static #generatedArgCounts = { create: 1, update: 2, remove: 1, merge: 2 } as const;
-  static #argMethods = new Set(["param", "body", "search", "room", "msg"]);
+  static #generatedArgCounts = [
+    ["createModel", 1],
+    ["updateModel", 2],
+    ["removeModel", 1],
+    ["mergeModel", 2],
+    ["addModelFiles", 2],
+  ] as const;
+  static #reader = createFactReader(ts, createAst(ts));
   readonly #shapesByOwner = new Map<string, Map<string, EndpointShape>>();
 
   constructor(sourceFiles: SourceFileInfo[]) {
@@ -17,7 +25,7 @@ export class SignalMutationIndex {
       if (!/^(apps|libs)\/[^/]+\/lib\/.+\.signal\.ts$/.test(file)) continue;
       const owner = file.split("/").slice(0, 2).join("/");
       const shapes = this.#shapesByOwner.get(owner) ?? new Map<string, EndpointShape>();
-      SignalMutationIndex.#collect(sourceFile, shapes);
+      SignalMutationIndex.#collect(SignalMutationIndex.#reader.read(sourceFile, owner), shapes);
       this.#shapesByOwner.set(owner, shapes);
     }
   }
@@ -34,7 +42,7 @@ export class SignalMutationIndex {
 
   #shapeOf(consumerFile: string, name: string) {
     const [root, owner] = consumerFile.split("/");
-    const own = root === "apps" ? this.#shapesByOwner.get(`apps/${owner}`)?.get(name) : undefined;
+    const own = this.#shapesByOwner.get(`${root}/${owner}`)?.get(name);
     if (own) return own;
     for (const [key, shapes] of this.#shapesByOwner) {
       const shape = shapes.get(name);
@@ -43,85 +51,18 @@ export class SignalMutationIndex {
     return undefined;
   }
 
-  static #collect(sourceFile: ts.SourceFile, kinds: Map<string, EndpointShape>) {
-    const visit = (node: ts.Node) => {
-      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
-        if (node.expression.text === "slice") SignalMutationIndex.#collectGenerated(node, kinds);
-        else if (node.expression.text === "endpoint") SignalMutationIndex.#collectEndpoints(node, kinds);
-      }
-      ts.forEachChild(node, visit);
-    };
-    visit(sourceFile);
-  }
-
-  static #collectGenerated(slice: ts.CallExpression, kinds: Map<string, EndpointShape>) {
-    let service: ts.Expression | undefined = slice.arguments[0];
-    while (service && ts.isCallExpression(service) && ts.isPropertyAccessExpression(service.expression))
-      service = service.expression.expression;
-    if (!service || !ts.isPropertyAccessExpression(service) || !SignalMutationIndex.#isNamed(service.expression, "srv"))
-      return;
-    const model = service.name.text;
-    const capModel = `${model.charAt(0).toUpperCase()}${model.slice(1)}`;
-    for (const [verb, argCount] of Object.entries(SignalMutationIndex.#generatedArgCounts))
-      kinds.set(`${verb}${capModel}`, { kind: "mutation", argCount });
-    kinds.set(`add${capModel}Files`, { kind: "mutation", argCount: 2 });
-  }
-
-  static #collectEndpoints(endpoint: ts.CallExpression, kinds: Map<string, EndpointShape>) {
-    const builder = endpoint.arguments[1];
-    if (!builder || (!ts.isArrowFunction(builder) && !ts.isFunctionExpression(builder))) return;
-    const map = SignalMutationIndex.#returnedObjectOf(builder);
-    if (!map) return;
-    const verbOf = SignalMutationIndex.#verbReaderOf(builder.parameters[0]);
-    for (const property of map.properties) {
-      if (!ts.isPropertyAssignment(property)) continue;
-      if (!ts.isIdentifier(property.name) && !ts.isStringLiteral(property.name)) continue;
-      const { root, argCount } = SignalMutationIndex.#chainOf(property.initializer);
-      const verb = verbOf(root);
-      //? A socket message writes with the visitor's credential as a mutation does, and the client refuses it alike.
-      const kind = verb === "message" ? "mutation" : verb;
-      if (kind === "query" || kind === "mutation") kinds.set(property.name.text, { kind, argCount });
+  static #collect(facts: FileFacts, shapes: Map<string, EndpointShape>) {
+    for (const { model } of facts.slices) {
+      if (!model) continue;
+      const names = modelNames(model);
+      for (const [role, argCount] of SignalMutationIndex.#generatedArgCounts)
+        shapes.set(names[role], { kind: "mutation", argCount });
     }
-  }
-
-  static #returnedObjectOf(builder: ts.ArrowFunction | ts.FunctionExpression) {
-    let body: ts.Node | undefined = builder.body;
-    if (ts.isBlock(body)) body = body.statements.find(ts.isReturnStatement)?.expression;
-    while (body && ts.isParenthesizedExpression(body)) body = body.expression;
-    return body && ts.isObjectLiteralExpression(body) ? body : null;
-  }
-
-  static #verbReaderOf(parameter: ts.ParameterDeclaration | undefined) {
-    const verbs = new Map<string, string>();
-    if (parameter && ts.isObjectBindingPattern(parameter.name))
-      for (const element of parameter.name.elements) {
-        const verb = element.propertyName ?? element.name;
-        if (ts.isIdentifier(verb) && ts.isIdentifier(element.name)) verbs.set(element.name.text, verb.text);
+    for (const { keys } of facts.endpoints)
+      for (const { name, verb, argCount } of keys) {
+        //? A socket message writes with the visitor's credential as a mutation does, and the client refuses it alike.
+        const kind = verb === "message" ? "mutation" : verb;
+        if (kind === "query" || kind === "mutation") shapes.set(name, { kind, argCount });
       }
-    const holder = parameter && ts.isIdentifier(parameter.name) ? parameter.name.text : null;
-    return (callee: ts.Expression | undefined) => {
-      if (callee && ts.isIdentifier(callee)) return verbs.get(callee.text);
-      if (callee && ts.isPropertyAccessExpression(callee) && SignalMutationIndex.#isNamed(callee.expression, holder))
-        return callee.name.text;
-      return undefined;
-    };
-  }
-
-  static #isNamed(expression: ts.Expression, name: string | null) {
-    return ts.isIdentifier(expression) && expression.text === name;
-  }
-
-  static #chainOf(initializer: ts.Expression) {
-    let root = initializer;
-    let argCount = 0;
-    while (
-      ts.isCallExpression(root) &&
-      ts.isPropertyAccessExpression(root.expression) &&
-      ts.isCallExpression(root.expression.expression)
-    ) {
-      if (SignalMutationIndex.#argMethods.has(root.expression.name.text)) argCount += 1;
-      root = root.expression.expression;
-    }
-    return { root: ts.isCallExpression(root) ? root.expression : undefined, argCount };
   }
 }

package/sourceComments.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { SourceComments } from "./sourceComments";
+
+const commentsOf = (content: string) =>
+  SourceComments.of(ts.createSourceFile("demo.tsx", content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)).map(
+    ({ line, body, isJsDoc }) => ({ line, body, isJsDoc }),
+  );
+
+describe("SourceComments", () => {
+  test("finds leading, trailing, empty-block and end-of-file comments", () => {
+    expect(
+      commentsOf(
+        ["// leading", "const a = 1; // trailing", "const f = () => {", "  /* inside */", "};", "// last", ""].join(
+          "\n",
+        ),
+      ),
+    ).toEqual([
+      { line: 1, body: ["leading"], isJsDoc: false },
+      { line: 2, body: ["trailing"], isJsDoc: false },
+      { line: 4, body: ["inside"], isJsDoc: false },
+      { line: 6, body: ["last"], isJsDoc: false },
+    ]);
+  });
+
+  test("ignores comment syntax inside strings, templates, regexes and JSX text", () => {
+    expect(
+      commentsOf(
+        [
+          'const url = "https://host//path";',
+          `const tpl = \`a // b \${url} // c\`;`,
+          "const re = /\\/\\/x/;",
+          'export const C = () => <div title="//x">// text {/* real */}</div>;',
+          "",
+        ].join("\n"),
+      ),
+    ).toEqual([{ line: 4, body: ["real"], isJsDoc: false }]);
+  });
+
+  test("strips block delimiters and marks a JSDoc", () => {
+    expect(
+      commentsOf(["/**", " * Summary", " * @deprecated use b", " */", "export const a = 1;", ""].join("\n")),
+    ).toEqual([{ line: 1, body: ["", "Summary", "@deprecated use b", ""], isJsDoc: true }]);
+  });
+});

package/sourceComments.ts

@@ -0,0 +1,70 @@
+import ts from "typescript";
+
+export interface SourceComment {
+  raw: string;
+  line: number;
+  isJsDoc: boolean;
+  body: string[];
+}
+
+export class SourceComments {
+  static #scanner = ts.createScanner(ts.ScriptTarget.Latest, false);
+
+  static of(sourceFile: ts.SourceFile): SourceComment[] {
+    const comments: SourceComment[] = [];
+    const scanGap = (start: number, end: number) => {
+      if (end <= start) return;
+      const scanner = SourceComments.#scanner;
+      scanner.setText(sourceFile.text, start, end - start);
+      for (let kind = scanner.scan(); kind !== ts.SyntaxKind.EndOfFileToken; kind = scanner.scan()) {
+        if (kind !== ts.SyntaxKind.SingleLineCommentTrivia && kind !== ts.SyntaxKind.MultiLineCommentTrivia) continue;
+        comments.push(SourceComments.#commentOf(sourceFile, scanner.getTokenStart(), scanner.getTokenText()));
+      }
+      scanner.setText(undefined);
+    };
+    //? Only the trivia between AST children is scanned: string, template, regex and JSX text tokens can hold `//`.
+    const visit = (node: ts.Node) => {
+      if (node.kind === ts.SyntaxKind.JsxText) return;
+      if (ts.isToken(node)) {
+        scanGap(node.pos, node.getStart(sourceFile));
+        return;
+      }
+      const children: ts.Node[] = [];
+      ts.forEachChild(
+        node,
+        (child) => {
+          children.push(child);
+        },
+        (nodes) => {
+          children.push(...nodes);
+        },
+      );
+      let cursor = node.pos;
+      for (const child of children) {
+        scanGap(cursor, child.pos);
+        visit(child);
+        cursor = Math.max(cursor, child.end);
+      }
+      scanGap(cursor, node.end);
+    };
+    visit(sourceFile);
+    return comments;
+  }
+
+  static #commentOf(sourceFile: ts.SourceFile, pos: number, raw: string): SourceComment {
+    return {
+      raw,
+      line: sourceFile.getLineAndCharacterOfPosition(pos).line + 1,
+      isJsDoc: raw.startsWith("/**") && !raw.startsWith("/**/"),
+      body: SourceComments.#bodyOf(raw),
+    };
+  }
+
+  static #bodyOf(raw: string) {
+    if (raw.startsWith("//")) return [raw.replace(/^\/\/+/, "").trim()];
+    return raw
+      .slice(2, raw.endsWith("*/") ? -2 : undefined)
+      .split(/\r?\n/)
+      .map((line) => line.replace(/^\s*\*+/, "").trim());
+  }
+}

package/sshHostKeys.ts

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ConfigLock } from "./cloud/configLock";
+import { FileSys } from "./fileSys";
+
+type KnownHosts = Record<string, string>;
+
+export interface HostKeyVerdict {
+  trusted: boolean;
+  firstUse: boolean;
+  fingerprint: string;
+}
+
+export class SshHostKeys {
+  static defaultPath() {
+    return path.join(Bun.env.HOME ?? Bun.env.USERPROFILE ?? "", ".akan", "ssh_known_hosts.json");
+  }
+  static fingerprintOf(key: Buffer) {
+    return `SHA256:${createHash("sha256").update(key).digest("base64").replace(/=+$/, "")}`;
+  }
+  static parsePinned(value: string | undefined) {
+    return (value ?? "")
+      .split(",")
+      .map((fingerprint) => fingerprint.trim())
+      .filter(Boolean)
+      .map((fingerprint) => (fingerprint.startsWith("SHA256:") ? fingerprint : `SHA256:${fingerprint}`));
+  }
+  readonly filePath: string;
+  constructor(filePath: string = SshHostKeys.defaultPath()) {
+    this.filePath = filePath;
+  }
+  //? Pinned fingerprints decide alone; without them the first key a host shows is kept and any other is refused.
+  async verify(hostId: string, key: Buffer, pinned: string[] = []): Promise<HostKeyVerdict> {
+    const fingerprint = SshHostKeys.fingerprintOf(key);
+    if (pinned.length) return { trusted: pinned.includes(fingerprint), firstUse: false, fingerprint };
+    return await ConfigLock.run(`${this.filePath}.lock`, async () => {
+      const known = await this.#read();
+      const stored = known[hostId];
+      if (stored) return { trusted: stored === fingerprint, firstUse: false, fingerprint };
+      await this.#write({ ...known, [hostId]: fingerprint });
+      return { trusted: true, firstUse: true, fingerprint };
+    });
+  }
+  async #read(): Promise<KnownHosts> {
+    return (await FileSys.fileExists(this.filePath)) ? await FileSys.readJson<KnownHosts>(this.filePath) : {};
+  }
+  async #write(known: KnownHosts) {
+    await mkdir(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+    const temp = `${this.filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    try {
+      await writeFile(temp, JSON.stringify(known, null, 2), { mode: 0o600 });
+      await FileSys.replace(temp, this.filePath);
+    } catch (error) {
+      await rm(temp, { force: true });
+      throw error;
+    }
+  }
+}

package/storeAccessScanner.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { StoreAccessScanner } from "./storeAccessScanner";
+import { WritingActionIndex } from "./writingActionIndex";
+
+const sourceOf = (file: string, content: string) =>
+  ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+
+const storeFile = "apps/demo/lib/board/board.store.ts";
+const signalFile = "apps/demo/lib/boardPin/boardPin.signal.ts";
+const signal = sourceOf(
+  signalFile,
+  "export class BoardPinSlice extends slice(srv.boardPin, { guards: { root: Admin, cru: User } }, () => ({})) {}\n",
+);
+const index = new WritingActionIndex(
+  new SignalMutationIndex([{ file: signalFile, absolutePath: "", content: "", sourceFile: signal }]),
+  [
+    {
+      file: storeFile,
+      sourceFile: sourceOf(
+        storeFile,
+        `import { fetch, sig } from "../useClient";
+export class BoardStore extends store(sig.board, () => ({})) {
+  async addPinOnCanvas(boardId: string) {
+    await fetch.createBoardPin({ board: boardId });
+  }
+}
+`,
+      ),
+    },
+  ],
+);
+
+const measure = (content: string) =>
+  new StoreAccessScanner(index).measure(sourceOf("apps/demo/lib/board/Board.Zone.tsx", content));
+
+describe("StoreAccessScanner", () => {
+  test("counts every read, action, selector, slice and agent hook a component reaches the store through", () => {
+    const counts = measure(`"use client";
+import { st as store } from "@apps/demo/client";
+
+export const Canvas = () => {
+  const board = store.use.board();
+  const pins = store.slice.boardInSelf.use.boardList();
+  const zoom = store.sel((state) => state.zoom);
+  const latest = store.ref((state) => state.board);
+  const move = store.tool("movePin").exec(() => store.do.setZoom(1));
+  return <div onClick={() => void store.do.addPinOnCanvas(board.id)}>{pins.length}{zoom}{latest.current?.id}{String(move)}</div>;
+};
+
+export const Empty = () => null;
+`);
+
+    expect(counts).toEqual([
+      { component: "Canvas", line: 4, accessCount: 7 },
+      { component: "Empty", line: 13, accessCount: 0 },
+    ]);
+  });
+
+  test("leaves out a generated form setter bound to its control, but not a writing action named like one", () => {
+    const counts = measure(`"use client";
+import { st } from "@apps/demo/client";
+
+export const General = () => {
+  const boardForm = st.use.boardForm();
+  return (
+    <form>
+      <input value={boardForm.name} onChange={(e) => st.do.setNameOnBoard(e.target.value)} />
+      <input onChange={st.do.addTagOnBoard} />
+      <input onChange={(e) => st.do.writeOnBoard("meta.title", e.target.value)} />
+      <button type="button" onClick={() => void st.do.addPinOnCanvas(boardForm.id)} />
+    </form>
+  );
+};
+`);
+
+    expect(counts).toEqual([{ component: "General", line: 4, accessCount: 2 }]);
+  });
+
+  test("measures nothing in a file that does not import st", () => {
+    expect(measure("export const Plain = () => st.use.board();\n")).toEqual([]);
+  });
+});