@mrciphersmith/keryx 0.2.80 → 0.2.82

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.80",
+  "version": "0.2.82",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {
@@ -38,11 +38,13 @@
     "build": "bun build ./src/cli.ts --outdir ./dist --target bun --external @modelcontextprotocol/sdk --external web-tree-sitter --external @opentui/core && bun build ./src/harness/process/sandbox/proxy-worker.ts --outdir ./dist --target bun --external @modelcontextprotocol/sdk --external web-tree-sitter --external @opentui/core",
     "prepare": "bun run build",
     "typecheck": "tsc --noEmit",
+    "typecheck:scripts": "tsc --project tsconfig.scripts.json --noEmit",
     "test": "bun test",
-    "check": "tsc --noEmit && bun test",
+    "check": "bun run lint && bun run typecheck && bun run typecheck:scripts && bun test",
     "check:doc-links": "bun scripts/check-doc-links.ts",
     "baseline:review-precision": "bun scripts/review-precision-baseline.ts",
-    "test:guards": "bun test src/lib/config-dir.ast.test.ts src/lib/config-dir.readers.test.ts src/lib/production-graph.test.ts src/harness/policy/profiles.test.ts src/lib/serve-server.test.ts src/gdskills/agent-catalogue-xref.test.ts src/gdskills/enforcement-claims.test.ts"
+    "test:guards": "bun test src/lib/config-dir.ast.test.ts src/lib/config-dir.readers.test.ts src/lib/production-graph.test.ts src/harness/policy/profiles.test.ts src/lib/serve-server.test.ts src/gdskills/agent-catalogue-xref.test.ts src/gdskills/enforcement-claims.test.ts",
+    "lint": "eslint ."
   },
   "files": [
     "dist",
@@ -55,16 +57,28 @@
     "package.json"
   ],
   "dependencies": {},
+  "overrides": {
+    "fast-uri": "^3.1.6",
+    "ip-address": "^10.3.1",
+    "hono": "^4.12.34",
+    "qs": "^6.16.0",
+    "@hono/node-server": "^1.19.15",
+    "protobufjs": "7.6.6",
+    "sharp": "0.35.4"
+  },
   "optionalDependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@opentui/core": "^0.4.5",
-    "web-tree-sitter": "^0.22.0"
+    "web-tree-sitter": "^0.22.6"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/bun": "latest",
     "@xenova/transformers": "^2.17.2",
     "bun-types": "latest",
-    "typescript": "^5"
+    "eslint": "^10.10.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.69.0"
   },
   "engines": {
     "bun": ">=1.1.0"

package/src/gdgraph/affected.test.ts

@@ -98,3 +98,36 @@ test("AC2.4 — dependencies are the unchanged one-hop forward set", async () =>
     expect(result.dependencies).toEqual(deps);
   }
 });
+
+// ---------------------------------------------------------------------------
+// AFC-11 (flow 234) requirement 3 — a type consumer is visible in impact
+// analysis. `edge.importKind === "type-only"` is erased at runtime and is
+// excluded from `getCycles`' load-order adjacency, but the edge itself is
+// still `kind: "imports"` — a real dependency for "what do I have to
+// re-check" — so `computeAffected` (and `getAffected`) must keep surfacing
+// it. Constructed in-memory rather than through `buildGraph()`: this is a
+// pure-function contract on `GraphData`, unrelated to how the edge's
+// `importKind` was derived.
+// ---------------------------------------------------------------------------
+
+test("AFC-11 req3 — a file that only type-imports the target is still a visible dependent", () => {
+  const graph: GraphData = {
+    nodes: [
+      { id: "src/types.ts", kind: "file", path: "src/types.ts", language: "typescript" },
+      { id: "src/consumer.ts", kind: "file", path: "src/consumer.ts", language: "typescript" },
+    ],
+    edges: [
+      {
+        id: "edge:1",
+        from: "src/consumer.ts",
+        to: "src/types.ts",
+        kind: "imports",
+        specifier: "./types",
+        importKind: "type-only",
+      },
+    ],
+  };
+
+  expect(computeAffected(graph, "src/types.ts").dependents).toEqual(["src/consumer.ts"]);
+  expect(getAffected(graph, "src/types.ts").dependents).toEqual(["src/consumer.ts"]);
+});

package/src/gdgraph/build.ts

@@ -2,7 +2,7 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import type { GraphData, GraphEdge, GraphNode, ImportKind, TranspilerImportKind } from "./types";
-import { UNKNOWN_IMPORT_KIND } from "./types";
+import { TYPE_ONLY_IMPORT_KIND, UNKNOWN_IMPORT_KIND } from "./types";
 
 const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".java", ".py"];
 const SOURCE_RESOLUTION_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".d.ts", ".java", ".py"];
@@ -112,7 +112,7 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
     // dropped), so the resolution metric is honest. TS/JS keeps the exact
     // original guard (relative + tsconfig alias only) ⇒ byte-identical output.
     const isLanguageAware = language === "java" || language === "python";
-    const records = extractImportRecords(content, language);
+    const records = extractImportRecords(content, language, file);
 
     for (const { specifier, kind: importKind } of records) {
       const resolved = resolveImport(projectRoot, file, specifier, fileSet, resolver);
@@ -222,7 +222,7 @@ type ImportRecord = { specifier: string; kind: ImportKind };
 // loop reads `record.kind` straight onto the edge, so cycle detection can
 // later tell a load-order `import-statement` from a call-time `dynamic-import`
 // instead of the previous single "imports" bucket.
-function extractImportRecords(content: string, language: string): ImportRecord[] {
+function extractImportRecords(content: string, language: string, filePath: string): ImportRecord[] {
   // Java/Python are not TS/JS syntax — the tsx transpiler cannot scan them
   // (it throws today, which is why they already reach the fallback). Route them
   // explicitly to the regex fallback that carries the java/python patterns,
@@ -244,7 +244,8 @@ function extractImportRecords(content: string, language: string): ImportRecord[]
   // dependents and showed up as a false orphan. UNION the two extractors: the
   // transpiler contributes the specifiers a regex cannot see (dynamic/`require`,
   // odd formatting), the fallback contributes the type-only ones.
-  const scanned = scanImportsOrEmpty(content);
+  const scanResult = scanImportsOrEmpty(content, filePath);
+  const scanned = scanResult.imports;
   const fallback = extractImportSpecifiersFallback(content);
 
   const kindBySpecifier = new Map<string, ImportKind>();
@@ -259,13 +260,28 @@ function extractImportRecords(content: string, language: string): ImportRecord[]
       kindBySpecifier.set(specifier, kind);
     }
   }
-  // Fallback-only specifiers (not seen by the transpiler at all — e.g.
-  // type-only imports) get the explicit unknown/static marker, never a
-  // guessed kind (AC4). A specifier the transpiler DID see keeps its real
-  // kind; the fallback never overrides it.
+  // Fallback-only specifiers (not seen by the transpiler for THIS statement)
+  // split into two provenances (AFC-11, flow 234):
+  //   * the scan RAN and simply omitted the specifier — that only happens
+  //     because the statement carries no runtime binding (`import type`,
+  //     `export type … from`, or every named specifier is `type`-prefixed).
+  //     That is a KNOWN classification, `TYPE_ONLY_IMPORT_KIND`, never
+  //     "unknown" — it still becomes a real edge for impact analysis
+  //     (getOrphans/getAffected/computeAffected all read `edge.kind`, not
+  //     `importKind`, so they are unaffected), but `getCycles` excludes it
+  //     from load-order adjacency the same way it already excludes
+  //     `dynamic-import`.
+  //   * the scan did not run at all (unparseable source, or a
+  //     transpiler-unsupported language routed here) — genuinely unknown
+  //     provenance, so it keeps the pre-existing conservative default,
+  //     `UNKNOWN_IMPORT_KIND`, which `getCycles` still treats as load-order
+  //     (AC4 of flow 140 — never silently exclude a real cycle when we
+  //     cannot tell).
+  // A specifier the transpiler DID see keeps its real kind; the fallback
+  // never overrides it.
   for (const specifier of fallback) {
     if (!kindBySpecifier.has(specifier)) {
-      kindBySpecifier.set(specifier, UNKNOWN_IMPORT_KIND);
+      kindBySpecifier.set(specifier, scanResult.succeeded ? TYPE_ONLY_IMPORT_KIND : UNKNOWN_IMPORT_KIND);
     }
   }
 
@@ -276,19 +292,40 @@ function extractImportRecords(content: string, language: string): ImportRecord[]
 
 type ScannedImport = { specifier: string; kind: TranspilerImportKind };
 
-function scanImportsOrEmpty(content: string): ScannedImport[] {
+// `succeeded: false` means the transpiler could not even parse the file —
+// distinct from `succeeded: true, imports: []` (a parseable file with no
+// scannable imports, e.g. one containing only type-only imports). The caller
+// needs that distinction to tell "known type-only" apart from "genuinely
+// unknown provenance" (AFC-11, flow 234) when a specifier turns up only in
+// the regex fallback.
+type ScanResult = { succeeded: boolean; imports: ScannedImport[] };
+
+// T19 finding 2 (flow 234 review): the `tsx` loader was hardcoded for every
+// TS/JS file. Under `tsx`, ordinary valid `.ts` syntax that collides with JSX
+// grammar throws — a generic arrow function (`<T>(x: T): T => x`) and an
+// angle-bracket cast (`<string>value`) are both ambiguous with a JSX opening
+// tag. `.ts` (never `.tsx`) is the only extension that can carry that
+// syntax AND can never legally contain real JSX, so it is the only one safe
+// to parse with JSX grammar disabled. `.tsx`/`.jsx` (and plain `.js`, which
+// may itself contain JSX) keep the original `tsx` loader unchanged.
+function loaderForFile(filePath: string): "ts" | "tsx" {
+  return filePath.endsWith(".ts") ? "ts" : "tsx";
+}
+
+function scanImportsOrEmpty(content: string, filePath: string): ScanResult {
   try {
-    const scanner = new Bun.Transpiler({ loader: "tsx" });
-    return scanner
+    const scanner = new Bun.Transpiler({ loader: loaderForFile(filePath) });
+    const imports = scanner
       .scanImports(content)
       .filter(
         (entry): entry is { path: string; kind: TranspilerImportKind } =>
           typeof entry.path === "string" && entry.path.length > 0,
       )
       .map((entry) => ({ specifier: entry.path, kind: entry.kind }));
+    return { succeeded: true, imports };
   } catch {
     // Unparseable source ⇒ the regex fallback alone still yields the imports.
-    return [];
+    return { succeeded: false, imports: [] };
   }
 }
 
@@ -311,7 +348,7 @@ function extractImportSpecifiersFallback(content: string): string[] {
 
   // Java patterns (import com.example.Class;)
   const javaPatterns = [
-    /\bimport\s+(?:static\s+)?([a-zA-Z_][a-zA-Z0-9_\.]*(?:\.\*)?)\s*;/g,
+    /\bimport\s+(?:static\s+)?([a-zA-Z_][a-zA-Z0-9_.]*(?:.*)?)\s*;/g,
   ];
 
   // Python patterns (import module, from module import name).
@@ -321,9 +358,9 @@ function extractImportSpecifiersFallback(content: string): string[] {
   //   before because the module regex required a leading letter; the third
   //   pattern captures the leading-dot forms.
   const pythonPatterns = [
-    /^[ \t]*import\s+([a-zA-Z_][a-zA-Z0-9_\.]*)/gm,
-    /\bfrom\s+([a-zA-Z_][a-zA-Z0-9_\.]*)\s+import/g,
-    /\bfrom\s+(\.+[a-zA-Z0-9_\.]*)\s+import/g,
+    /^[ \t]*import\s+([a-zA-Z_][a-zA-Z0-9_.]*)/gm,
+    /\bfrom\s+([a-zA-Z_][a-zA-Z0-9_.]*)\s+import/g,
+    /\bfrom\s+(\.+[a-zA-Z0-9_.]*)\s+import/g,
   ];
 
   for (const pattern of [...jsPatterns, ...javaPatterns, ...pythonPatterns]) {

package/src/gdgraph/fallback.test.ts

@@ -124,7 +124,7 @@ test("AC4.3 — capability ENABLED but unavailable: exactly one warn, regex path
       return true;
     }) as typeof process.stderr.write;
 
-    let exitCodeBefore = process.exitCode;
+    const exitCodeBefore = process.exitCode;
     try {
       await buildGraph(root);
     } finally {

package/src/gdgraph/import-kind.test.ts

@@ -155,15 +155,66 @@ test("AC3 — the same two-file cycle formed by await import() is NOT reported a
 });
 
 // ---------------------------------------------------------------------------
-// AC4 — an edge found only by the regex fallback (never seen by scanImports)
-// is marked with an explicit unknown/static marker, never inferred dynamic.
-// A type-only import is the real-world case: `Bun.Transpiler#scanImports`
-// erases `import type {...}` entirely, so it reaches the graph only through
-// `extractImportSpecifiersFallback`.
+// AC4 (flow 140) — an edge found only by the regex fallback (never seen by
+// scanImports) is marked with an explicit unknown/static marker, never
+// inferred dynamic.
+//
+// SUPERSEDED for the TS/JS type-only case by AFC-11 (flow 234, below): a
+// fallback-only edge whose file the transpiler DID successfully scan is now
+// known to be type-only, not merely "unknown" — it gets its own
+// `TYPE_ONLY_IMPORT_KIND` so cycle detection can exclude it while impact
+// analysis keeps it. The Java case is untouched: Java is routed straight to
+// the fallback (`extractImportRecords` never calls `scanImports` for it), so
+// its provenance is genuinely unknown and it keeps `unknown-static`.
 // ---------------------------------------------------------------------------
 
-test("AC4 — a fallback-only edge (type-only import) is marked unknown-static, never inferred dynamic", async () => {
-  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-ac4");
+test("AC4 (flow 140, still applies to Java) — a fallback-only Java edge is marked unknown-static, never inferred dynamic", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-java");
+  await reset(root);
+  const javaRoot = path.join(root, "src", "main", "java", "com", "example");
+  await mkdir(javaRoot, { recursive: true });
+  await writeFile(
+    path.join(javaRoot, "Consumer.java"),
+    "package com.example;\nimport com.example.Model;\npublic class Consumer {}\n",
+  );
+  await writeFile(path.join(javaRoot, "Model.java"), "package com.example;\npublic class Model {}\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find(
+    (item) =>
+      item.from === "src/main/java/com/example/Consumer.java" &&
+      item.to === "src/main/java/com/example/Model.java",
+  );
+
+  expect(edge).toBeDefined();
+  expect(edge?.importKind).toBe("unknown-static");
+});
+
+// ---------------------------------------------------------------------------
+// AFC-11 (flow 234, phase 2) — frozen AC4:
+//   "Type-only цикл не попадает в runtime список; mixed import с
+//    runtime-частью попадает; consumer типа виден в impact; цикл сам по себе
+//    не блокирует gate."
+//
+// Reproduced first (see the task report for the exact repro run), then fixed:
+// a type-only cycle (`import type` on both sides) built as `unknown-static`
+// and was reported by `getCycles` as a real runtime cycle, because
+// `unknown-static` was — and for Java/unparseable TS still is — treated as
+// load-order. The fix gives TS/JS type-only edges their own kind,
+// `TYPE_ONLY_IMPORT_KIND` ("type-only"), which `getCycles` (query.ts)
+// excludes from load-order adjacency the same way it already excludes
+// `dynamic-import`, while every impact-analysis consumer (`getOrphans`,
+// `getAffected`, `computeAffected`) is untouched because they read
+// `edge.kind`, not `edge.importKind`.
+// ---------------------------------------------------------------------------
+
+// --- requirement 1 + classification table: the four "is it type-only?"
+// spellings this task must distinguish. Each RED-failed against the
+// pre-fix code with `edge?.importKind === "unknown-static"` (see report).
+
+test("AFC-11 req1 — `import type { X } from './m'` (whole-statement) is classified type-only", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-import-type-whole");
   await reset(root);
   await mkdir(path.join(root, "src"), { recursive: true });
   await writeFile(
@@ -176,30 +227,299 @@ test("AC4 — a fallback-only edge (type-only import) is marked unknown-static,
   const graph = await loadGraph(root);
   const edge = graph.edges.find((item) => item.from === "src/consumer.ts" && item.to === "src/types.ts");
 
-  expect(edge).toBeDefined();
-  expect(edge?.importKind).toBe("unknown-static");
-  expect(edge?.importKind).not.toBe("dynamic-import");
+  expect(edge?.importKind).toBe("type-only");
 });
 
-test("AC4 — Java imports (fallback-only language) are marked unknown-static, never dynamic", async () => {
-  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-java");
+test("AFC-11 req1 — `import { type X } from './m'` (inline, all-type) is classified type-only", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-import-type-inline");
   await reset(root);
-  const javaRoot = path.join(root, "src", "main", "java", "com", "example");
-  await mkdir(javaRoot, { recursive: true });
+  await mkdir(path.join(root, "src"), { recursive: true });
   await writeFile(
-    path.join(javaRoot, "Consumer.java"),
-    "package com.example;\nimport com.example.Model;\npublic class Consumer {}\n",
+    path.join(root, "src", "consumer.ts"),
+    "import { type Shape } from './types';\nexport const consumer: Shape = { ok: true } as Shape;\n",
   );
-  await writeFile(path.join(javaRoot, "Model.java"), "package com.example;\npublic class Model {}\n");
+  await writeFile(path.join(root, "src", "types.ts"), "export interface Shape { ok: boolean }\n");
 
   await buildGraph(root);
   const graph = await loadGraph(root);
-  const edge = graph.edges.find(
-    (item) =>
-      item.from === "src/main/java/com/example/Consumer.java" &&
-      item.to === "src/main/java/com/example/Model.java",
+  const edge = graph.edges.find((item) => item.from === "src/consumer.ts" && item.to === "src/types.ts");
+
+  expect(edge?.importKind).toBe("type-only");
+});
+
+test("AFC-11 req1 — `export type { X } from './m'` (whole-statement re-export) is classified type-only", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-export-type-whole");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(path.join(root, "src", "types.ts"), "export interface Shape { ok: boolean }\n");
+  await writeFile(path.join(root, "src", "reexport.ts"), "export type { Shape } from './types';\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/reexport.ts" && item.to === "src/types.ts");
+
+  expect(edge?.importKind).toBe("type-only");
+});
+
+test("AFC-11 req1 — `export { type X } from './m'` (inline re-export, all-type) is classified type-only", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-export-type-inline");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(path.join(root, "src", "types.ts"), "export interface Shape { ok: boolean }\n");
+  await writeFile(path.join(root, "src", "reexport.ts"), "export { type Shape } from './types';\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/reexport.ts" && item.to === "src/types.ts");
+
+  expect(edge?.importKind).toBe("type-only");
+});
+
+// --- requirement 1: the actual reported symptom — a two-file cycle formed
+// only by type-only edges must not show up in `getCycles`.
+
+test("AFC-11 req1 — a two-file cycle formed only by `import type` on both sides is NOT reported", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-cycle-import-type");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "a.ts"),
+    "import type { BType } from './b';\nexport type AType = { b?: BType };\n",
+  );
+  await writeFile(
+    path.join(root, "src", "b.ts"),
+    "import type { AType } from './a';\nexport type BType = { a?: AType };\n",
   );
 
-  expect(edge).toBeDefined();
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(cycles.some((cycle) => cycle.includes("src/a.ts") && cycle.includes("src/b.ts"))).toBe(false);
+});
+
+test("AFC-11 req1 — a two-file cycle formed only by `export type … from` on both sides is NOT reported", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-cycle-export-type");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(path.join(root, "src", "a.ts"), "export type { BType } from './b';\nexport type AType = {};\n");
+  await writeFile(path.join(root, "src", "b.ts"), "export type { AType } from './a';\nexport type BType = {};\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(cycles.some((cycle) => cycle.includes("src/a.ts") && cycle.includes("src/b.ts"))).toBe(false);
+});
+
+// --- a fifth, non-type-erasing spelling: a plain value import whose binding
+// is used only in a type position at the use site. `import { x } from './m'`
+// carries no `type` keyword anywhere, so the transpiler (this repo's
+// tsconfig sets neither `importsNotUsedAsValues` nor `verbatimModuleSyntax`,
+// so TypeScript's/Bun's default elision applies — see the report) does NOT
+// erase it: erasure here is purely syntactic (was `type` written?), never a
+// usage analysis (is the binding read only as a type elsewhere?). This test
+// guards against a fix that tries to be "smarter" than the transpiler by
+// inferring type-only-ness from usage — it must stay a real runtime edge.
+
+test("`import { x } from './m'` used only in a type position stays import-statement (no usage-based erasure)", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-value-used-as-type");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "consumer.ts"),
+    "import { value } from './lib';\nexport const y: typeof value = value;\n",
+  );
+  await writeFile(path.join(root, "src", "lib.ts"), "export const value = { ok: true };\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/consumer.ts" && item.to === "src/lib.ts");
+
+  expect(edge?.importKind).toBe("import-statement");
+});
+
+// --- requirement 2 (over-correction guard) — a mixed import (one runtime
+// specifier alongside a type specifier) still produces a real load-order
+// edge, and a cycle closed through it IS reported. This is the test that
+// would fail if requirement 1 were implemented too bluntly (e.g. by
+// excluding every edge whose statement merely CONTAINS the word `type`).
+
+test("AFC-11 req2 — `import { x, type Y } from './m'` (mixed) is classified import-statement, a real runtime edge", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-mixed-classification");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "consumer.ts"),
+    "import { value, type Shape } from './lib';\nexport const consumer: Shape = value;\n",
+  );
+  await writeFile(
+    path.join(root, "src", "lib.ts"),
+    "export interface Shape { ok: boolean }\nexport const value = { ok: true };\n",
+  );
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/consumer.ts" && item.to === "src/lib.ts");
+
+  expect(edge?.importKind).toBe("import-statement");
+});
+
+test("AFC-11 req2 (the over-correction guard) — a two-file cycle where both directions are mixed imports IS reported", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-cycle-mixed-both");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "a.ts"),
+    "import { b, type BType } from './b';\nexport type AType = { b?: BType };\nexport const a = () => b();\n",
+  );
+  await writeFile(
+    path.join(root, "src", "b.ts"),
+    "import { a, type AType } from './a';\nexport type BType = { a?: AType };\nexport const b = () => a();\n",
+  );
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(cycles.some((cycle) => cycle.includes("src/a.ts") && cycle.includes("src/b.ts"))).toBe(true);
+});
+
+// --- requirement 4 — a detected cycle is information only; it never throws,
+// never sets a failure flag, and the JSON `getCycles` returns is exactly what
+// a caller (CLI/MCP) renders as a plain list. There is no "gate" primitive in
+// this module's return type to fail: proving that is proving there is no
+// exception and no truthy/falsy "blocked" field mixed into the result.
+
+// ---------------------------------------------------------------------------
+// T19 finding 2 (flow 234 review) — `extractImportRecords` hardcoded the
+// `tsx` transpiler loader for every `.ts` file. Under `tsx`, valid TypeScript
+// syntax that collides with JSX grammar throws: a generic arrow function
+// (`<T>(x: T): T => x`) and an angle-bracket cast (`<string>value`) are both
+// ambiguous with a JSX opening tag. When the scan throws, EVERY specifier in
+// the file falls back to the regex extractor with `scanResult.succeeded ===
+// false`, so a type-only cycle between two such files was still classified
+// `UNKNOWN_IMPORT_KIND` — which `getCycles` treats as load-order — defeating
+// AC4 clause 1 on a real, constructible TypeScript input. Reproduced directly
+// against `src/tui/shell-chrome.ts` / `src/sac/fwk-service.test.ts` (both
+// throw under the `tsx` loader, both parse under `ts`) — see the task report.
+// Fixed by choosing the loader from the file extension (`ts` for `.ts`,
+// `tsx` for `.tsx`/`.jsx`), so a `.ts` file — which can never legally contain
+// JSX — is parsed with JSX grammar disabled.
+// ---------------------------------------------------------------------------
+
+test("T19 finding 2 — a generic arrow function no longer breaks the scan for a .ts file", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-t19-generic-arrow");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "identity.ts"),
+    "import { helper } from './helper';\nexport const identity = <T>(x: T): T => x;\nexport const used = helper();\n",
+  );
+  await writeFile(path.join(root, "src", "helper.ts"), "export const helper = () => 1;\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/identity.ts" && item.to === "src/helper.ts");
+
+  // Before the fix: the `tsx` scan of identity.ts throws on `<T>(x: T)`, the
+  // whole file falls back to the regex extractor, and this edge is
+  // classified `unknown-static`, not the real `import-statement`.
+  expect(edge?.importKind).toBe("import-statement");
+});
+
+test("T19 finding 2 — an angle-bracket cast no longer breaks the scan for a .ts file", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-t19-angle-cast");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "cast.ts"),
+    "import { helper } from './helper';\nexport const cast = (value: unknown) => <string>value;\nexport const used = helper();\n",
+  );
+  await writeFile(path.join(root, "src", "helper.ts"), "export const helper = () => 1;\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/cast.ts" && item.to === "src/helper.ts");
+
+  expect(edge?.importKind).toBe("import-statement");
+});
+
+test("T19 finding 2 — a type-only cycle between two files that also use a generic arrow / angle-bracket cast is NOT reported as a runtime cycle", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-t19-cycle-jsx-collision");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "a.ts"),
+    [
+      "import type { BType } from './b';",
+      "export type AType = { b?: BType };",
+      "export const identity = <T>(x: T): T => x;",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(
+    path.join(root, "src", "b.ts"),
+    [
+      "import type { AType } from './a';",
+      "export type BType = { a?: AType };",
+      "export const cast = (value: unknown) => <string>value;",
+      "",
+    ].join("\n"),
+  );
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+
+  const edgeAB = graph.edges.find((item) => item.from === "src/a.ts" && item.to === "src/b.ts");
+  const edgeBA = graph.edges.find((item) => item.from === "src/b.ts" && item.to === "src/a.ts");
+  // Before the fix, both scans throw (the file collides with JSX grammar
+  // under `tsx`), so both edges fall back to `unknown-static` — which
+  // `getCycles` treats as load-order — instead of the real `type-only`.
+  expect(edgeAB?.importKind).toBe("type-only");
+  expect(edgeBA?.importKind).toBe("type-only");
+
+  const cycles = getCycles(graph);
+  expect(cycles.some((cycle) => cycle.includes("src/a.ts") && cycle.includes("src/b.ts"))).toBe(false);
+});
+
+// A genuinely unparseable `.ts` file must still classify as unknown — the
+// fix must not weaken AC4 (flow 140) by treating every scan failure as
+// type-only. Unbalanced syntax throws under BOTH the `ts` and `tsx` loaders
+// (verified directly against `Bun.Transpiler` — see the task report), so this
+// proves the retry/extension-selection does not paper over a real parse
+// failure.
+test("T19 finding 2 (both directions) — a genuinely unparseable .ts file still classifies its edges as unknown-static", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-t19-unparseable-ts");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "broken.ts"),
+    "import { helper } from './helper';\nexport const broken = {\n",
+  );
+  await writeFile(path.join(root, "src", "helper.ts"), "export const helper = () => 1;\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/broken.ts" && item.to === "src/helper.ts");
+
   expect(edge?.importKind).toBe("unknown-static");
 });
+
+test("AFC-11 req4 — a real runtime cycle is reported without throwing, as plain data (not a gate failure)", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-afc11-gate");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(path.join(root, "src", "a.ts"), "import { b } from './b';\nexport const a = () => b();\n");
+  await writeFile(path.join(root, "src", "b.ts"), "import { a } from './a';\nexport const b = () => a();\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+
+  expect(() => getCycles(graph)).not.toThrow();
+  const cycles = getCycles(graph);
+  expect(Array.isArray(cycles)).toBe(true);
+  expect(cycles.length).toBeGreaterThan(0);
+  // The return type is `string[][]` — there is no boolean/gate field on it to
+  // assert "false" for; the absence of one IS the requirement.
+});