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

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/createTunnel.test.ts

@@ -1,8 +1,76 @@
-import { describe, expect, spyOn, test } from "bun:test";
-import { Client } from "ssh2";
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import type { AddressInfo } from "node:net";
+import path from "node:path";
+import { Client, type Connection, Server, utils } from "ssh2";
 import { createTunnel } from "./createTunnel";
+import { SshHostKeys } from "./sshHostKeys";
 import { createTempApp, isolateEnv, tempRoots } from "./testHelpers";
 
+const freePort = () => {
+  const listener = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+  const { port } = listener;
+  listener.stop(true);
+  return port;
+};
+
+const publicBlobOf = (publicKey: string) => {
+  const parsed = utils.parseKey(publicKey);
+  if (parsed instanceof Error) throw parsed;
+  return parsed.getPublicSSH();
+};
+
+const sshServers: { server: Server; clients: Set<Connection> }[] = [];
+
+const startSshServer = async () => {
+  const hostKey = utils.generateKeyPairSync("ed25519");
+  const methods: string[] = [];
+  const clients = new Set<Connection>();
+  const server = new Server({ hostKeys: [hostKey.private] }, (client) => {
+    clients.add(client);
+    client.on("error", () => clients.delete(client));
+    client.on("authentication", (context) => {
+      methods.push(context.method);
+      if (context.method === "password" || context.method === "publickey") context.accept();
+      else context.reject(["publickey", "password"]);
+    });
+    client.on("ready", () => {
+      client.on("tcpip", (accept) => {
+        const channel = accept();
+        channel.on("data", (chunk: Buffer) => channel.write(chunk));
+      });
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+  sshServers.push({ server, clients });
+  const { port } = server.address() as AddressInfo;
+  return { port, methods, fingerprint: SshHostKeys.fingerprintOf(publicBlobOf(hostKey.public)) };
+};
+
+const echoThrough = async (port: number) =>
+  await new Promise<string>((resolve, reject) => {
+    void Bun.connect({
+      hostname: "127.0.0.1",
+      port,
+      socket: {
+        open: (socket) => void socket.write("ping"),
+        data: (socket, chunk) => {
+          resolve(Buffer.from(chunk).toString());
+          socket.end();
+        },
+        error: (_socket, error) => reject(error),
+        connectError: (_socket, error) => reject(error),
+      },
+    });
+  });
+
+afterEach(() => {
+  for (const { server, clients } of sshServers.splice(0)) {
+    for (const client of clients) client.end();
+    server.close();
+  }
+});
+
 describe("createTunnel", () => {
   isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "testing" });
   const track = tempRoots();
@@ -62,4 +130,134 @@ describe("createTunnel", () => {
       connect.mockRestore();
     }
   });
+
+  test("forwards on loopback, signs in with the configured key and keeps the host key it first sees", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    const knownHosts = path.join(root, "known_hosts.json");
+    const keyPath = path.join(root, "id_tunnel");
+    await writeFile(keyPath, utils.generateKeyPairSync("ed25519").private);
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: knownHosts,
+      SSH_TUNNEL_PRIVATE_KEY_PATH: keyPath,
+    });
+    const localPort = freePort();
+    const listen = spyOn(Bun, "listen");
+    try {
+      expect(await createTunnel("redis", { app, environment: "testing", port: localPort })).toBe(
+        `localhost:${localPort}`,
+      );
+      expect(listen.mock.calls[0]?.[0]).toMatchObject({ hostname: "127.0.0.1", port: localPort });
+    } finally {
+      listen.mockRestore();
+    }
+
+    expect(await echoThrough(localPort)).toBe("ping");
+    expect(ssh.methods).toContain("publickey");
+    expect(ssh.methods).not.toContain("password");
+    expect(JSON.parse(await readFile(knownHosts, "utf8"))).toEqual({ [`localhost:${ssh.port}`]: ssh.fingerprint });
+    if (process.platform !== "win32") expect((await stat(knownHosts)).mode & 0o777).toBe(0o600);
+  });
+
+  test("refuses a host whose key differs from the kept or the pinned one", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    const knownHosts = path.join(root, "known_hosts.json");
+    const other = `SHA256:${Buffer.alloc(32, 1).toString("base64").replace(/=+$/, "")}`;
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: knownHosts,
+      SSH_TUNNEL_PASSWORD: "test-password",
+    });
+    const open = async () => await createTunnel("redis", { app, environment: "testing", port: freePort() });
+
+    await writeFile(knownHosts, JSON.stringify({ [`localhost:${ssh.port}`]: other }));
+    await expect(open()).rejects.toThrow(`differs from the one ${knownHosts} keeps`);
+    expect(JSON.parse(await readFile(knownHosts, "utf8"))).toEqual({ [`localhost:${ssh.port}`]: other });
+
+    process.env.SSH_TUNNEL_HOST_FINGERPRINT = other;
+    await expect(open()).rejects.toThrow("is not one SSH_TUNNEL_HOST_FINGERPRINT pins");
+    process.env.SSH_TUNNEL_HOST_FINGERPRINT = ssh.fingerprint;
+    await expect(open()).resolves.toStartWith("localhost:");
+    expect(ssh.methods.filter((method) => method !== "none")).toEqual(["password"]);
+  });
+
+  test("warns when it signs in with the default shared credential", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: path.join(root, "known_hosts.json"),
+    });
+    //? `akan test` runs from the workspace root, whose dotenv may name a password; this case is the one with none.
+    delete process.env.SSH_TUNNEL_PASSWORD;
+    delete process.env.SSH_TUNNEL_PRIVATE_KEY_PATH;
+    const warn = spyOn(app.logger, "warn");
+
+    await createTunnel("redis", { app, environment: "testing", port: freePort() });
+
+    expect(warn.mock.calls.map(([message]) => String(message)).join("\n")).toContain(
+      "uses the default shared credential",
+    );
+  });
+
+  test("listens where SSH_TUNNEL_BIND_HOST says and warns when that is not loopback", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: path.join(root, "known_hosts.json"),
+      SSH_TUNNEL_PASSWORD: "test-password",
+      SSH_TUNNEL_BIND_HOST: "0.0.0.0",
+    });
+    const warn = spyOn(app.logger, "warn");
+    const localPort = freePort();
+    const listen = spyOn(Bun, "listen");
+    try {
+      await createTunnel("redis", { app, environment: "testing", port: localPort });
+      expect(listen.mock.calls[0]?.[0]).toMatchObject({ hostname: "0.0.0.0", port: localPort });
+    } finally {
+      listen.mockRestore();
+    }
+
+    expect(warn.mock.calls.map(([message]) => String(message)).join("\n")).toContain(
+      "The redis tunnel listens on 0.0.0.0 (SSH_TUNNEL_BIND_HOST)",
+    );
+  });
+
+  test("takes no host check or listener the repo's dotenv file names, and says it ignored them", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    const knownHosts = path.join(root, "known_hosts.json");
+    const other = `SHA256:${Buffer.alloc(32, 1).toString("base64").replace(/=+$/, "")}`;
+    await writeFile(path.join(root, ".env"), "SSH_TUNNEL_HOST_FINGERPRINT=*\nexport SSH_TUNNEL_BIND_HOST=0.0.0.0\n");
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: knownHosts,
+      SSH_TUNNEL_PASSWORD: "test-password",
+      SSH_TUNNEL_HOST_FINGERPRINT: "*",
+      SSH_TUNNEL_BIND_HOST: "0.0.0.0",
+    });
+    const warn = spyOn(app.logger, "warn");
+    const listen = spyOn(Bun, "listen");
+    const cwd = process.cwd();
+    process.chdir(root);
+    try {
+      const open = async () => await createTunnel("redis", { app, environment: "testing", port: freePort() });
+      await writeFile(knownHosts, JSON.stringify({ [`localhost:${ssh.port}`]: other }));
+      await expect(open()).rejects.toThrow(`differs from the one ${knownHosts} keeps`);
+      await writeFile(knownHosts, JSON.stringify({ [`localhost:${ssh.port}`]: ssh.fingerprint }));
+      await expect(open()).resolves.toStartWith("localhost:");
+      expect(listen.mock.calls.at(-1)?.[0]).toMatchObject({ hostname: "127.0.0.1" });
+    } finally {
+      process.chdir(cwd);
+      listen.mockRestore();
+    }
+
+    const warnings = warn.mock.calls.map(([message]) => String(message)).join("\n");
+    expect(warnings).toContain("SSH_TUNNEL_HOST_FINGERPRINT is set in .env, which the repository controls");
+    expect(warnings).toContain("SSH_TUNNEL_BIND_HOST is set in .env");
+    expect(warnings).not.toContain("accepts any host key");
+  });
 });

package/createTunnel.ts

@@ -1,36 +1,110 @@
+import { readFileSync } from "node:fs";
+import type { ConnectConfig } from "ssh2";
 import { type AppExecutor, WorkspaceExecutor } from "./executors";
+import { ShellOnlyEnv } from "./shellOnlyEnv";
+import { SshHostKeys } from "./sshHostKeys";
 import { createSshTunnel } from "./sshTunnel";
 
+//? Loosening the host check or the listener, or picking a key, is the person's call; a repo's dotenv cannot set it.
+const tunnelEnv = new ShellOnlyEnv([
+  "SSH_TUNNEL_PRIVATE_KEY_PATH",
+  "SSH_TUNNEL_PASSPHRASE",
+  "SSH_TUNNEL_HOST_FINGERPRINT",
+  "SSH_TUNNEL_KNOWN_HOSTS",
+  "SSH_TUNNEL_BIND_HOST",
+]);
+
 interface TunnelOption {
   app: AppExecutor;
   environment: string;
   port?: number;
 }
+
+const tunnelAuth = (
+  app: AppExecutor,
+  repoName: string,
+): Pick<ConnectConfig, "privateKey" | "passphrase" | "password"> => {
+  const keyPath = tunnelEnv.get("SSH_TUNNEL_PRIVATE_KEY_PATH");
+  const passphrase = tunnelEnv.get("SSH_TUNNEL_PASSPHRASE");
+  if (keyPath) return { privateKey: readFileSync(keyPath), ...(passphrase ? { passphrase } : {}) };
+  if (process.env.SSH_TUNNEL_PASSWORD) return { password: process.env.SSH_TUNNEL_PASSWORD };
+  app.logger.warn(
+    "The SSH tunnel uses the default shared credential. " +
+      "Set SSH_TUNNEL_PRIVATE_KEY_PATH to a key (or SSH_TUNNEL_PASSWORD) once the cluster's tunnel endpoint accepts it.",
+  );
+  return { password: repoName };
+};
+
+const tunnelHostVerifier = (app: AppExecutor, hostId: string, onRefusal: (reason: string) => void) => {
+  const pinned = SshHostKeys.parsePinned(tunnelEnv.get("SSH_TUNNEL_HOST_FINGERPRINT"));
+  const hostKeys = new SshHostKeys(tunnelEnv.get("SSH_TUNNEL_KNOWN_HOSTS") || undefined);
+  return (key: Buffer, verify: (valid: boolean) => void) => {
+    if (pinned.includes("SHA256:*")) {
+      app.logger.warn(`SSH_TUNNEL_HOST_FINGERPRINT=* accepts any host key ${hostId} shows.`);
+      verify(true);
+      return;
+    }
+    hostKeys.verify(hostId, key, pinned).then(
+      ({ trusted, firstUse, fingerprint }) => {
+        if (firstUse)
+          app.logger.warn(
+            `Trusting the SSH host key ${fingerprint} of ${hostId} on first use; kept in ${hostKeys.filePath}.`,
+          );
+        if (!trusted)
+          onRefusal(
+            pinned.length
+              ? `the host key ${fingerprint} of ${hostId} is not one SSH_TUNNEL_HOST_FINGERPRINT pins`
+              : `the host key ${fingerprint} of ${hostId} differs from the one ${hostKeys.filePath} keeps; if the host was rebuilt, remove its entry or pin the new key with SSH_TUNNEL_HOST_FINGERPRINT`,
+          );
+        verify(trusted);
+      },
+      (error: unknown) => {
+        onRefusal(
+          `the host key store ${hostKeys.filePath} could not be read (${error instanceof Error ? error.message : String(error)})`,
+        );
+        verify(false);
+      },
+    );
+  };
+};
+
 export const createTunnel = async (
   service: "redis" | "postgres",
   { app, environment, port = service === "postgres" ? 5432 : 6379 }: TunnelOption,
 ) => {
   const baseDevEnv = WorkspaceExecutor.getBaseDevEnv();
   WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, `The ${service} tunnel`);
+  for (const line of tunnelEnv.ignored()) app.logger.warn(line);
   const { serveDomain, repoName } = baseDevEnv;
   const host = `${app.name}-${environment}.${serveDomain}`;
+  //? RFC 6761 makes *.localhost loopback, but only macOS resolves it; glibc without systemd-resolved and Windows answer ENOTFOUND
+  const sshHost = host.endsWith(".localhost") ? "localhost" : host;
   const sshPort = process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767;
   const dstHost = `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`;
   const dstPort = service === "postgres" ? 5432 : 6379;
+  //? The forward reaches a cluster database, so it listens on loopback unless SSH_TUNNEL_BIND_HOST widens it.
+  const bindHost = tunnelEnv.get("SSH_TUNNEL_BIND_HOST") || "127.0.0.1";
+  if (!["127.0.0.1", "localhost", "::1"].includes(bindHost))
+    app.logger.warn(
+      `The ${service} tunnel listens on ${bindHost} (SSH_TUNNEL_BIND_HOST), so other machines that reach it reach ${dstHost}.`,
+    );
+  let refusal: string | null = null;
   try {
     await createSshTunnel({
-      localHost: "0.0.0.0",
+      localHost: bindHost,
       localPort: port,
-      srcHost: "0.0.0.0",
+      srcHost: "127.0.0.1",
       srcPort: port,
       dstHost,
       dstPort,
       sshOptions: {
-        //? RFC 6761 makes *.localhost loopback, but only macOS resolves it; glibc without systemd-resolved and Windows answer ENOTFOUND
-        host: host.endsWith(".localhost") ? "localhost" : host,
+        host: sshHost,
         port: sshPort,
         username: process.env.SSH_TUNNEL_USERNAME ?? "root",
-        password: process.env.SSH_TUNNEL_PASSWORD ?? repoName,
+        ...tunnelAuth(app, repoName),
+        hostVerifier: tunnelHostVerifier(app, `${sshHost}:${sshPort}`, (reason) => {
+          refusal = reason;
+        }),
       },
     });
   } catch (error) {
@@ -41,7 +115,7 @@ export const createTunnel = async (
           ? error.message
           : String(error);
     throw new Error(
-      `Could not open the ${service} tunnel for ${app.name}-${environment}: SSH ${host}:${sshPort} -> ${dstHost}:${dstPort} failed (${reasons})`,
+      `Could not open the ${service} tunnel for ${app.name}-${environment}: SSH ${host}:${sshPort} -> ${dstHost}:${dstPort} failed (${refusal ?? reasons})`,
       { cause: error },
     );
   }

package/csrE2e/ssrRegistry.e2e.test.ts

@@ -61,7 +61,12 @@ describe.skipIf(!CsrE2eHarness.enabled)("SSR dev registry (minimal)", () => {
   let ssr: CsrE2eHarness;
 
   beforeAll(async () => {
-    ssr = await CsrE2eHarness.start({ app: "minimal", port, env: { AKAN_DEV_SSR_ARM_DELAY_MS: "3000" } });
+    ssr = await CsrE2eHarness.start({
+      app: "minimal",
+      port,
+      // The server-log assertions match verbose-level lines, which a workspace `.env` may or may not turn on.
+      env: { AKAN_DEV_SSR_ARM_DELAY_MS: "3000", AKAN_PUBLIC_LOG_LEVEL: "verbose" },
+    });
   }, 240_000);
 
   afterAll(async () => {

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;
+  }
+}