@mrciphersmith/keryx 0.2.80 → 0.2.82

package/src/gdgraph/symbols-capability.ts

@@ -2,6 +2,17 @@
 // `metaproject.json` — the opt-in switch for the symbol layer. Pure manifest
 // transforms (the command layer owns file IO), merge-safe: preserves any other
 // gdgraph capabilities and never rewrites unrelated modules.
+//
+// Also hosts `requireSymbols()` (AFC-13 / AC5, requirements 2 & 3): the typed,
+// actionable error a caller gets when it explicitly demands symbol-level
+// capability and the graph has no symbol layer — instead of `undefined`, an
+// empty result, or a generic `Error` with a string. When given the tree-sitter
+// adapter's per-language `GrammarDiagnosis[]` (see `./treesitter/adapter`),
+// the error additionally distinguishes "grammar not installed" from "grammar
+// installed but incompatible with this runtime" — distinct causes with
+// distinct remedies, rather than one indistinguishable "unavailable".
+
+import type { GrammarDiagnosis } from "./treesitter/adapter";
 
 export const TREESITTER_CAPABILITY = "gdgraph.treesitter";
 
@@ -47,3 +58,97 @@ export function isTreesitterEnabled(manifest: Json): boolean {
     (c) => c && typeof c === "object" && (c as Json).id === TREESITTER_CAPABILITY && (c as Json).enabled === true,
   );
 }
+
+// --- requireSymbols (AFC-13 / AC5, requirements 2 & 3) ---
+
+export type SymbolsUnavailableCode =
+  // The graph has no symbol layer and no diagnoses were supplied to explain
+  // why (capability disabled, or the caller didn't pass the adapter's probe).
+  | "no-symbol-layer"
+  // At least one required language's grammar never resolved: not installed,
+  // or failed the Asset Resolver's checksum.
+  | "grammar-missing"
+  // At least one required language's grammar resolved and verified on disk,
+  // but the installed `web-tree-sitter` runtime refused to load it (ABI /
+  // version mismatch) — distinct from "missing": nothing to install, the
+  // existing install doesn't match the runtime.
+  | "grammar-incompatible";
+
+// Thrown by `requireSymbols()`. A typed, actionable error — never a generic
+// `Error` with a string, never swallowed into `undefined`/an empty result —
+// naming what capability is missing and what would fix it.
+export class SymbolsUnavailableError extends Error {
+  readonly code: SymbolsUnavailableCode;
+  readonly remedy: string;
+  readonly diagnoses: GrammarDiagnosis[];
+
+  constructor(code: SymbolsUnavailableCode, message: string, remedy: string, diagnoses: GrammarDiagnosis[] = []) {
+    super(message);
+    this.name = "SymbolsUnavailableError";
+    this.code = code;
+    this.remedy = remedy;
+    this.diagnoses = diagnoses;
+  }
+}
+
+// The minimal shape `requireSymbols` needs from a graph. Defined locally
+// rather than imported from `./types` (owned by a concurrent task on this
+// flow) so this module depends on nothing but the one field it actually
+// reads; `GraphData` (which has `symbols?: SymbolNode[]`) satisfies this
+// structurally, so callers can pass a real `GraphData` unchanged.
+export interface SymbolsLayerCarrier {
+  symbols?: unknown[];
+}
+
+// Explicit demand for symbol-level capability: returns `graph.symbols` when
+// present, otherwise THROWS `SymbolsUnavailableError` instead of returning
+// `undefined` or an empty array. This is the "requireSymbols" contract in
+// AC-13 — a caller that opts into requiring symbols gets a typed, actionable
+// failure, never a silent downgrade to file-level.
+//
+// `diagnoses` (optional) is normally `TreesitterAdapter#getDiagnoses()`
+// (`./treesitter/adapter`) forwarded by the caller; when supplied, the thrown
+// error's `code` distinguishes "grammar-missing" from "grammar-incompatible"
+// (requirement 3) instead of a single generic "unavailable".
+export function requireSymbols<G extends SymbolsLayerCarrier>(
+  graph: G,
+  diagnoses: GrammarDiagnosis[] = [],
+): NonNullable<G["symbols"]> {
+  if (graph.symbols !== undefined) {
+    return graph.symbols as NonNullable<G["symbols"]>;
+  }
+  throw buildSymbolsUnavailableError(diagnoses);
+}
+
+function buildSymbolsUnavailableError(diagnoses: GrammarDiagnosis[]): SymbolsUnavailableError {
+  const incompatible = diagnoses.filter((d) => d.status === "incompatible");
+  if (incompatible.length > 0) {
+    const languages = incompatible.map((d) => d.language).join(", ");
+    return new SymbolsUnavailableError(
+      "grammar-incompatible",
+      `requireSymbols: the installed grammar for [${languages}] is incompatible with this web-tree-sitter runtime (${incompatible
+        .map((d) => d.reason)
+        .join("; ")})`,
+      `Reinstall a "tree-sitter-<language>" grammar build that matches the installed web-tree-sitter runtime version (run "keryx gdgraph assets pull tree-sitter-<language>" after updating .metaproject/assets.lock.json), then rebuild the graph with "keryx gdgraph build".`,
+      diagnoses,
+    );
+  }
+
+  const missing = diagnoses.filter((d) => d.status === "missing");
+  if (missing.length > 0) {
+    const languages = missing.map((d) => d.language).join(", ");
+    return new SymbolsUnavailableError(
+      "grammar-missing",
+      `requireSymbols: no grammar is installed for [${languages}]`,
+      `Enable the "gdgraph.treesitter" capability in metaproject.json, install the grammar with "keryx gdgraph assets pull tree-sitter-<language>" for each of [${languages}], then rebuild the graph with "keryx gdgraph build".`,
+      diagnoses,
+    );
+  }
+
+  return new SymbolsUnavailableError(
+    "no-symbol-layer",
+    "requireSymbols: the graph has no symbol layer (gdgraph.treesitter is disabled, or the build ran without it)",
+    'Enable the "gdgraph.treesitter" capability in metaproject.json and rebuild the graph with "keryx gdgraph build".',
+    diagnoses,
+  );
+}

package/src/gdgraph/treesitter/adapter.test.ts

@@ -165,6 +165,110 @@ test("availability-false — missing dep ⇒ isAvailable false", async () => {
   }
 });
 
+// --- AFC-13 / AC5 requirement 3: "the grammar is not installed" and "the
+// grammar is installed but its ABI version does not match this runtime" must
+// be distinguishable outcomes, not one collapsed "unavailable". Neither
+// failure mode can be produced on a real machine without either uninstalling
+// `web-tree-sitter` (not available as a seam) or installing an ABI-mismatched
+// grammar build (forbidden by this task). Both are exercised instead through
+// the module's own seam: `spec.load({ dep, asset })` accepts an injected
+// `dep` exactly like the existing tests above, and a `Language.load` that
+// rejects is a faithful simulation of a real ABI/version-mismatch error from
+// `web-tree-sitter` (the real runtime rejects `Language.load` the same way
+// for a grammar built against an incompatible ABI).
+function brokenLanguageParserModule(rejection: Error): unknown {
+  function MockParser(this: unknown) {}
+  (MockParser as unknown as { init: () => Promise<void> }).init = async () => {};
+  (MockParser as unknown as { Language: { load: (p: string) => Promise<unknown> } }).Language = {
+    load: async () => {
+      throw rejection;
+    },
+  };
+  MockParser.prototype.setLanguage = function setLanguage(): void {};
+  MockParser.prototype.parse = function parse(): { rootNode: TsNode } {
+    return { rootNode: bootTree() };
+  };
+  return MockParser;
+}
+
+test("AC5.req3 — grammar asset never resolved ⇒ diagnosis status 'missing', not 'incompatible'", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-ts-diag-missing-"));
+  try {
+    await mkdir(path.join(root, ".metaproject"), { recursive: true });
+    // No assets.lock.json entry at all ⇒ resolveGrammar can never find the asset.
+    const spec = createTreesitterSpec(root, { languages: ["typescript"], grammarsPath: null });
+    const adapter = spec.load({ dep: mockParserModule(), asset: null }) as unknown as {
+      isAvailable(): Promise<boolean>;
+      getDiagnoses(): { language: string; status: string; reason: string }[];
+    };
+
+    expect(await adapter.isAvailable()).toBe(false);
+    const diagnoses = adapter.getDiagnoses();
+    expect(diagnoses).toHaveLength(1);
+    expect(diagnoses[0]?.status).toBe("missing");
+    expect(diagnoses[0]?.reason).not.toContain("ABI");
+    expect(diagnoses[0]?.reason).toContain("not resolved");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("AC5.req3 — grammar asset resolves and verifies, but the runtime refuses to load it ⇒ diagnosis status 'incompatible', not 'missing'", async () => {
+  const { root, grammarsDir } = await makeWorkspaceWithGrammar();
+  try {
+    const spec = createTreesitterSpec(root, { languages: ["typescript"], grammarsPath: grammarsDir });
+    const abiError = new Error("Incompatible language version 13. Expected minimum 14, maximum 15");
+    const adapter = spec.load({ dep: brokenLanguageParserModule(abiError), asset: null }) as unknown as {
+      isAvailable(): Promise<boolean>;
+      getDiagnoses(): { language: string; status: string; reason: string }[];
+    };
+
+    // The grammar resolved (it is on disk with a verified checksum) — this is
+    // the crucial difference from the "missing" case above — but the runtime
+    // could not load it, so overall availability is still false.
+    expect(await adapter.isAvailable()).toBe(false);
+    const diagnoses = adapter.getDiagnoses();
+    expect(diagnoses).toHaveLength(1);
+    expect(diagnoses[0]?.status).toBe("incompatible");
+    expect(diagnoses[0]?.reason).toContain("Incompatible language version 13");
+    expect(diagnoses[0]?.reason).not.toContain("not resolved");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("AC5.req3 — missing and incompatible are genuinely different values end to end (adapter diagnosis -> warn reason -> requireSymbols code), never the same outcome", async () => {
+  const missingRoot = await mkdtemp(path.join(tmpdir(), "keryx-ts-diag-a-"));
+  const incompatibleWorkspace = await makeWorkspaceWithGrammar();
+  try {
+    await mkdir(path.join(missingRoot, ".metaproject"), { recursive: true });
+    const missingSpec = createTreesitterSpec(missingRoot, { languages: ["typescript"], grammarsPath: null });
+    const missingAdapter = missingSpec.load({ dep: mockParserModule(), asset: null }) as unknown as {
+      isAvailable(): Promise<boolean>;
+      getDiagnoses(): { language: string; status: string; reason: string }[];
+    };
+    await missingAdapter.isAvailable();
+
+    const incompatibleSpec = createTreesitterSpec(incompatibleWorkspace.root, {
+      languages: ["typescript"],
+      grammarsPath: incompatibleWorkspace.grammarsDir,
+    });
+    const incompatibleAdapter = incompatibleSpec.load({
+      dep: brokenLanguageParserModule(new Error("bad wasm magic number")),
+      asset: null,
+    }) as unknown as {
+      isAvailable(): Promise<boolean>;
+      getDiagnoses(): { language: string; status: string; reason: string }[];
+    };
+    await incompatibleAdapter.isAvailable();
+
+    expect(missingAdapter.getDiagnoses()[0]?.status).not.toBe(incompatibleAdapter.getDiagnoses()[0]?.status);
+  } finally {
+    await rm(missingRoot, { recursive: true, force: true });
+    await rm(incompatibleWorkspace.root, { recursive: true, force: true });
+  }
+});
+
 test("AC1.1 additive write path — enrich writes symbols.jsonl + calls.jsonl via a mock adapter", async () => {
   const root = await mkdtemp(path.join(tmpdir(), "keryx-enrich-"));
   try {

package/src/gdgraph/treesitter/adapter.ts

@@ -37,6 +37,46 @@ export interface TreesitterAdapterConfig {
   grammarsPath: string | null;
 }
 
+// Per-language probe outcome (AFC-13 / AC5). "missing" and "incompatible" are
+// deliberately distinct: a grammar that never resolved (not installed, or
+// failed the Asset Resolver's checksum) has a different remedy — install it —
+// from one that resolved and verified on disk but the installed
+// `web-tree-sitter` runtime refuses to load it (an ABI/version mismatch
+// between the pinned grammar build and the runtime) — whose remedy is
+// reinstalling a matching build, not installing anything new. Collapsing
+// these into one "unavailable" outcome is the defect class AC5 targets.
+export type GrammarDiagnosisStatus = "ok" | "missing" | "incompatible";
+
+export interface GrammarDiagnosis {
+  language: GrammarLanguage;
+  status: GrammarDiagnosisStatus;
+  // Human-actionable detail; empty for "ok".
+  reason: string;
+}
+
+// Render diagnoses into one warn-once-friendly summary line, grouped by
+// status so a mixed missing+incompatible result stays legible.
+export function describeGrammarDiagnoses(diagnoses: GrammarDiagnosis[]): string {
+  if (diagnoses.length === 0) {
+    return "no grammar languages configured";
+  }
+  const byStatus = (status: GrammarDiagnosisStatus) =>
+    diagnoses.filter((d) => d.status === status).map((d) => d.language);
+  const missing = byStatus("missing");
+  const incompatible = byStatus("incompatible");
+  const parts: string[] = [];
+  if (missing.length > 0) {
+    parts.push(`missing grammar for [${missing.join(", ")}]`);
+  }
+  if (incompatible.length > 0) {
+    parts.push(`incompatible grammar for [${incompatible.join(", ")}]`);
+  }
+  if (parts.length === 0) {
+    return "no configured grammar resolved to a usable parser";
+  }
+  return parts.join("; ");
+}
+
 // Minimal shapes of the `web-tree-sitter` surface we touch (kept local so the
 // dep is never imported for types either — structural typing only).
 interface ParserLike {
@@ -138,7 +178,15 @@ export async function resolveTreesitterCapability(
       return null;
     }
     if (!available) {
-      warnCapabilityDegraded(spec.id, "adapter reported unavailable");
+      // Prefer the per-language diagnoses when the concrete adapter exposes
+      // them (only `TreesitterAdapter` does — this cast is local and narrow,
+      // never leaks into the shared `CapabilityAdapter` interface), so the
+      // one-line warn-once already names missing vs incompatible instead of
+      // a generic "unavailable".
+      const diagnoses = getGrammarDiagnoses(adapter as unknown as { getDiagnoses?: () => GrammarDiagnosis[] });
+      const reason =
+        diagnoses.length > 0 ? describeGrammarDiagnoses(diagnoses) : "adapter reported unavailable";
+      warnCapabilityDegraded(spec.id, reason);
       return null;
     }
 
@@ -149,9 +197,23 @@ export async function resolveTreesitterCapability(
   }
 }
 
+// Read `getDiagnoses()` off a `CapabilityAdapter` when the concrete instance
+// is a `TreesitterAdapter` (the only implementation today). A generic
+// `CapabilityAdapter` from another module simply has no such method, so this
+// is a safe narrow probe rather than an assumption about the seam's shared
+// interface.
+function getGrammarDiagnoses(adapter: { getDiagnoses?: () => GrammarDiagnosis[] }): GrammarDiagnosis[] {
+  return typeof adapter.getDiagnoses === "function" ? adapter.getDiagnoses() : [];
+}
+
 class TreesitterAdapter implements CapabilityAdapter<BuildInput, SymbolLayer> {
   readonly id = "gdgraph.treesitter";
   private grammars: ResolvedGrammar[] = [];
+  private diagnoses: GrammarDiagnosis[] = [];
+  // Populated by `isAvailable()`'s probe so `run()` never re-attempts a
+  // `loadLanguage()` call the probe already made (and, for a language that
+  // probed "incompatible", never attempts it at all).
+  private loadedLanguages = new Map<GrammarLanguage, unknown>();
 
   constructor(
     private readonly cwd: string,
@@ -159,13 +221,88 @@ class TreesitterAdapter implements CapabilityAdapter<BuildInput, SymbolLayer> {
     private readonly dep: unknown,
   ) {}
 
+  // Exposes the per-language missing-vs-incompatible breakdown from the most
+  // recent `isAvailable()` probe (AFC-13 / AC5, requirement 3). Empty before
+  // `isAvailable()` has run.
+  getDiagnoses(): GrammarDiagnosis[] {
+    return this.diagnoses;
+  }
+
   async isAvailable(): Promise<boolean> {
+    const languages = toGrammarLanguages(this.config.languages);
+    this.diagnoses = [];
+    this.loadedLanguages = new Map();
+    this.grammars = [];
+
     if (!this.dep) {
+      this.diagnoses = languages.map((language) => ({
+        language,
+        status: "missing",
+        reason: 'optional dependency "web-tree-sitter" is not installed',
+      }));
       return false;
     }
-    const languages = toGrammarLanguages(this.config.languages);
-    this.grammars = await resolveGrammars(this.cwd, languages, this.config.grammarsPath);
-    return this.grammars.length > 0;
+
+    const resolved = await resolveGrammars(this.cwd, languages, this.config.grammarsPath);
+    const resolvedByLanguage = new Map(resolved.map((grammar) => [grammar.language, grammar]));
+
+    const api = normalizeParserApi(this.dep);
+    if (typeof api?.init === "function") {
+      try {
+        await api.init();
+      } catch {
+        // Runtime init failure ⇒ every resolved grammar is unloadable; each
+        // still gets its own diagnosis below (loadLanguage will also throw).
+      }
+    }
+
+    for (const language of languages) {
+      const grammar = resolvedByLanguage.get(language);
+      if (!grammar) {
+        this.diagnoses.push({
+          language,
+          status: "missing",
+          reason: `grammar asset "tree-sitter-${language}" is not resolved (not installed, or failed checksum verification)`,
+        });
+        continue;
+      }
+      if (!api) {
+        this.diagnoses.push({
+          language,
+          status: "incompatible",
+          reason: 'the "web-tree-sitter" module shape was not recognized (no usable Parser export)',
+        });
+        continue;
+      }
+      try {
+        const loaded = await api.loadLanguage(grammar.path);
+        if (!loaded) {
+          this.diagnoses.push({
+            language,
+            status: "incompatible",
+            reason: `grammar at "${grammar.path}" loaded but produced no Language object`,
+          });
+          continue;
+        }
+        this.loadedLanguages.set(language, loaded);
+        this.grammars.push(grammar);
+        this.diagnoses.push({ language, status: "ok", reason: "" });
+      } catch (error) {
+        // The grammar resolved and verified on disk, but the installed
+        // `web-tree-sitter` runtime refused to load it — an ABI/version
+        // mismatch between the pinned grammar build and the runtime, NOT a
+        // missing asset. Distinct cause, distinct remedy (AFC-13).
+        this.diagnoses.push({
+          language,
+          status: "incompatible",
+          reason: `grammar at "${grammar.path}" failed to load in the installed web-tree-sitter runtime (likely an ABI/version mismatch): ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        });
+      }
+    }
+
+    return this.diagnoses.some((d) => d.status === "ok");
   }
 
   async run(input: BuildInput): Promise<SymbolLayer> {
@@ -178,11 +315,14 @@ class TreesitterAdapter implements CapabilityAdapter<BuildInput, SymbolLayer> {
       await api.init();
     }
 
-    // Load + cache one parser per resolved grammar language.
+    // Load + cache one parser per resolved grammar language. Reuse the
+    // Language object the `isAvailable()` probe already loaded when present
+    // (the common path); fall back to loading directly for a caller that
+    // invokes `run()` without having called `isAvailable()` first.
     const parsers = new Map<GrammarLanguage, ParserLike>();
     for (const grammar of this.grammars) {
       try {
-        const language = await api.loadLanguage(grammar.path);
+        const language = this.loadedLanguages.get(grammar.language) ?? (await api.loadLanguage(grammar.path));
         if (!language) {
           continue;
         }

package/src/gdgraph/treesitter/real-grammar-fixture.test.ts

@@ -0,0 +1,71 @@
+// AFC-13 / AC5 requirement 4: "fixture даёт реальные symbols после явной
+// установки" — a fixture that genuinely yields real symbols after an
+// explicit runtime/grammar installation. This task is forbidden from
+// performing that installation (no dependency installs of any kind).
+//
+// So this file does NOT install anything. It probes whether a working
+// `web-tree-sitter` runtime + a real, verified grammar are ALREADY present in
+// this environment (exactly the state an explicit install would produce) and:
+//   - genuinely present  ⇒ the test RUNS FOR REAL against the real adapter
+//     (`resolveTreesitterCapability`, the actual production entry point —
+//     not a mock) and asserts real, non-empty symbols extracted from a real
+//     TypeScript fixture by the real grammar.
+//   - genuinely absent   ⇒ `test.skipIf` marks the test SKIPPED (visible as
+//     "skip" in `bun test`'s own summary, not a silent pass), with the reason
+//     embedded in the test name.
+//
+// A vacuous pass (the "absent" branch quietly returning without asserting
+// anything) would NOT be evidence for requirement 4 — `test.skipIf` is used
+// specifically so an absent environment shows up as a skip, never as a pass.
+
+import { expect, test } from "bun:test";
+import { resolveTreesitterCapability } from "./adapter";
+
+const FIXTURE_SOURCE = ["export function boot(): void {", "  tick();", "}", "", "function tick(): void {}", ""].join(
+  "\n",
+);
+
+// Probed once at module load (top-level await — this file's only test needs
+// the answer before `test.skipIf` decides whether to run). This calls the
+// REAL `resolveTreesitterCapability` against the real project root, so it
+// reflects whatever runtime + grammar state is genuinely on this machine —
+// no mocking, no injected `dep`.
+const projectRoot = process.cwd();
+const probedAdapter = await resolveTreesitterCapability(projectRoot, {
+  languages: ["typescript"],
+  grammarsPath: null,
+});
+const skipReason = probedAdapter
+  ? ""
+  : "no working web-tree-sitter runtime + verified typescript grammar resolved in this environment " +
+    "(gdgraph.treesitter must be enabled in metaproject.json AND a matching grammar installed via " +
+    '"keryx gdgraph assets pull tree-sitter-typescript" — an install this task must not perform)';
+
+test.skipIf(!probedAdapter)(
+  skipReason ? `AC5.req4 — real fixture yields real symbols [SKIPPED: ${skipReason}]` : "AC5.req4 — real fixture yields real symbols after explicit installation",
+  async () => {
+    const adapter = probedAdapter;
+    if (!adapter) {
+      // Unreachable when the test actually runs (skipIf gates it), kept only
+      // so TypeScript sees the non-null adapter below without a cast.
+      throw new Error("AC5.req4 ran without a resolved adapter — skipIf condition was wrong");
+    }
+
+    const layer = await adapter.run({
+      files: [{ path: "fixtures/treesitter/ac5-req4-fixture.ts", content: FIXTURE_SOURCE }],
+    });
+
+    // Real symbols, not a mock's canned output: names, kinds, and a resolved
+    // call edge all come from the actually-installed tree-sitter grammar
+    // parsing actual TypeScript source.
+    expect(layer.symbols.length).toBeGreaterThan(0);
+    const byName = Object.fromEntries(layer.symbols.map((s) => [s.name, s]));
+    expect(byName.boot).toMatchObject({ kind: "function", language: "typescript" });
+    expect(byName.tick).toMatchObject({ kind: "function", language: "typescript" });
+
+    const callSummaries = layer.calls.map((c) => `${c.kind}:${c.from}=>${c.to}`);
+    expect(callSummaries).toContain(
+      "calls:fixtures/treesitter/ac5-req4-fixture.ts#boot=>fixtures/treesitter/ac5-req4-fixture.ts#tick",
+    );
+  },
+);

package/src/gdgraph/types.ts

@@ -27,10 +27,35 @@ export type TranspilerImportKind =
 // plain regex with no notion of "static" vs "dynamic". Never infer one;
 // `UNKNOWN_IMPORT_KIND` marks it explicitly and cycle detection treats it as
 // load-order (the pre-fix behavior), so fallback-only edges are never
-// silently excluded from a real cycle.
+// silently excluded from a real cycle. This is reserved for the case where
+// `scanImports` could not even run (unparseable source) or the language has
+// no transpiler support at all (Java/Python) — genuinely unknown provenance,
+// where "assume load-order" is the safe default.
 export const UNKNOWN_IMPORT_KIND = "unknown-static" as const;
 
-export type ImportKind = TranspilerImportKind | typeof UNKNOWN_IMPORT_KIND;
+// AFC-11 (flow 234): a specifier the transpiler DID successfully scan the
+// file for, but did not report for THIS statement, because the statement
+// carries no runtime binding — `import type {...}`, `export type {...} from`,
+// or an inline specifier list where every name is `type`-prefixed
+// (`import { type X } from "./m"`). `Bun.Transpiler#scanImports` erases these
+// (verified empirically: this repo's `tsconfig.json` sets neither
+// `importsNotUsedAsValues` nor `verbatimModuleSyntax`, so it runs on
+// TypeScript's defaults, which elide type-only imports/exports at compile
+// time), so they only reach the graph through the regex fallback below.
+// Unlike `UNKNOWN_IMPORT_KIND`, the provenance here is NOT unknown — it is
+// known to be type-only — so it gets its own kind rather than being folded
+// into "unknown-static": `getCycles` (query.ts) excludes it from the
+// load-order adjacency (a type-only cycle cannot deadlock a runtime module
+// graph — it does not exist once compiled away), while every consumer that
+// reads `edge.kind` (getOrphans, getAffected, computeAffected) is untouched
+// and keeps treating it as a real dependency edge for impact analysis, since
+// the edge is genuinely real for "what has to be re-checked".
+export const TYPE_ONLY_IMPORT_KIND = "type-only" as const;
+
+export type ImportKind =
+  | TranspilerImportKind
+  | typeof UNKNOWN_IMPORT_KIND
+  | typeof TYPE_ONLY_IMPORT_KIND;
 
 export type GraphEdge = {
   id: string;

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.codex.md

@@ -10,7 +10,7 @@ triggers:
   - "Implement issue task"
 metadata:
   author: "MrCipherSmith"
-  version: "1.3.0"
+  version: "1.3.1"
   category: "implementation"
   agent_worthy: true
   compatible_harnesses: "claude,cursor,codex,zed,opencode"
@@ -23,7 +23,7 @@ license: "MIT"
 
 Receives a single atomic task (JSON task object from `issue-analyzer`) and implements it end-to-end. Designed to run autonomously as a sub-agent — no user interaction required. Commits its changes to a shared feature branch managed by the orchestrator.
 
-**Input:** JSON task object + workspace context (branch, codebase path, issue number)
+**Input:** JSON task object + workspace context (branch, codebase path, optional real issue number)
 **Output:** JSON result object with implementation status, files modified, verification results
 
 ## When to Use
@@ -86,10 +86,12 @@ TASK: (from JSON object passed by orchestrator)
 WORKSPACE:
   codebase_path:        absolute path to the repository
   branch:               feature branch to work on (already checked out by orchestrator)
-  issue_number:         GitHub issue number (for commit messages)
+  issue_number:         Optional real GitHub issue number; omit for description-based tasks
   issue_title:          issue title (for commit messages)
 ```
 
+For a description-based task, omit `issue_number` and issue references in commit messages. Never substitute a flow ID or fabricate a GitHub issue. A supplied issue number must remain a positive integer.
+
 **1.3 For fix tasks (dispatched from review loop):**
 
 ```
@@ -120,7 +122,7 @@ The refusals are the contract's, not a checklist you run by eye
 | `task_type` outside `ui_component\|store_logic\|service_api\|refactoring\|fix\|mixed` | `task.task_type.enum` |
 | A `task_id` that is not `task-<n>` | `task.task_id.pattern` |
 | Empty `target_files` or empty `acceptance_criteria` | `minItems: 1` on both |
-| Missing `codebase_path` / `branch` / `issue_number` | `workspace.required` |
+| Missing `codebase_path` / `branch` | `workspace.required` |
 | `skip_confirmation` anything but `true` | `automation.skip_confirmation.const` |
 | `max_self_fix_attempts` above 3 | `automation.max_self_fix_attempts.maximum` |
 | Any field the contract does not declare | `additionalProperties: false` |
@@ -315,7 +317,7 @@ Execute the change plan. Write production-quality code.
 
 **4.5 Commit after implementation:**
 
-Create a conventional commit with the changes:
+When auto-commit is enabled, create a conventional commit with the changes. Include the `refs #<issue_number>` line below only when a positive real issue number was supplied; otherwise omit that entire line:
 ```bash
 git add <modified files>
 git commit -m "<type>(<scope>): <description>
@@ -399,6 +401,7 @@ said. Report the block instead, naming what repeated.
 **Never run `git reset --hard`, `git clean`, or any unscoped revert.** You do not own the worktree. `job-orchestrator` dispatches implementers in PARALLEL WAVES sharing a single worktree, so an unscoped reset destroys a wave-mate's uncommitted work — work that is not yours, cannot be recovered, and whose loss is invisible to you because the other agent's failure surfaces somewhere else entirely. If you cannot identify which files are yours, leave the tree exactly as it is and say so in the report: a dirty tree is recoverable, a destroyed one is not.
 
 **5.5 Re-commit fixes if any:**
+When auto-commit is enabled, use the template below. Include `refs #<issue_number>` only for a supplied positive real issue number; otherwise omit that entire line.
 ```bash
 git add <fixed files>
 git commit -m "fix(<scope>): resolve lint/type/test issues
@@ -530,7 +533,7 @@ second copy of a schema is how that happens.
 5. **DO** use project path aliases (`@components`, `@utils`, etc.) for imports.
 6. **DO** wrap React components with `observer()` when they access MobX stores.
 7. **DO** use `runInAction()` after every `await` in MobX actions.
-8. **DO** commit with conventional commit format referencing the issue number.
+8. **DO** use conventional commit format when auto-commit is enabled. Reference only a supplied real issue number; omit the issue reference when absent.
 9. **DO** verify your work before reporting.
 10. **DO** make `STATUS: <TOKEN>` the first line of your final message, and put no
     JSON in the response body. The full JSON result is the file Phase 6.1 writes

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.cursor.md

@@ -10,7 +10,7 @@ triggers:
   - "Implement issue task"
 metadata:
   author: "MrCipherSmith"
-  version: "1.3.0"
+  version: "1.3.1"
   category: "implementation"
   agent_worthy: true
   compatible_harnesses: "claude,cursor,codex,zed,opencode"
@@ -23,7 +23,7 @@ license: "MIT"
 
 Receives a single atomic task (JSON task object from `issue-analyzer`) and implements it end-to-end. Designed to run autonomously as a sub-agent — no user interaction required. Commits its changes to a shared feature branch managed by the orchestrator.
 
-**Input:** JSON task object + workspace context (branch, codebase path, issue number)
+**Input:** JSON task object + workspace context (branch, codebase path, optional real issue number)
 **Output:** JSON result object with implementation status, files modified, verification results
 
 ## When to Use
@@ -86,10 +86,12 @@ TASK: (from JSON object passed by orchestrator)
 WORKSPACE:
   codebase_path:        absolute path to the repository
   branch:               feature branch to work on (already checked out by orchestrator)
-  issue_number:         GitHub issue number (for commit messages)
+  issue_number:         Optional real GitHub issue number; omit for description-based tasks
   issue_title:          issue title (for commit messages)
 ```
 
+For a description-based task, omit `issue_number` and issue references in commit messages. Never substitute a flow ID or fabricate a GitHub issue. A supplied issue number must remain a positive integer.
+
 **1.3 For fix tasks (dispatched from review loop):**
 
 ```
@@ -120,7 +122,7 @@ The refusals are the contract's, not a checklist you run by eye
 | `task_type` outside `ui_component\|store_logic\|service_api\|refactoring\|fix\|mixed` | `task.task_type.enum` |
 | A `task_id` that is not `task-<n>` | `task.task_id.pattern` |
 | Empty `target_files` or empty `acceptance_criteria` | `minItems: 1` on both |
-| Missing `codebase_path` / `branch` / `issue_number` | `workspace.required` |
+| Missing `codebase_path` / `branch` | `workspace.required` |
 | `skip_confirmation` anything but `true` | `automation.skip_confirmation.const` |
 | `max_self_fix_attempts` above 3 | `automation.max_self_fix_attempts.maximum` |
 | Any field the contract does not declare | `additionalProperties: false` |
@@ -315,7 +317,7 @@ Execute the change plan. Write production-quality code.
 
 **4.5 Commit after implementation:**
 
-Create a conventional commit with the changes:
+When auto-commit is enabled, create a conventional commit with the changes. Include the `refs #<issue_number>` line below only when a positive real issue number was supplied; otherwise omit that entire line:
 ```bash
 git add <modified files>
 git commit -m "<type>(<scope>): <description>
@@ -399,6 +401,7 @@ said. Report the block instead, naming what repeated.
 **Never run `git reset --hard`, `git clean`, or any unscoped revert.** You do not own the worktree. `job-orchestrator` dispatches implementers in PARALLEL WAVES sharing a single worktree, so an unscoped reset destroys a wave-mate's uncommitted work — work that is not yours, cannot be recovered, and whose loss is invisible to you because the other agent's failure surfaces somewhere else entirely. If you cannot identify which files are yours, leave the tree exactly as it is and say so in the report: a dirty tree is recoverable, a destroyed one is not.
 
 **5.5 Re-commit fixes if any:**
+When auto-commit is enabled, use the template below. Include `refs #<issue_number>` only for a supplied positive real issue number; otherwise omit that entire line.
 ```bash
 git add <fixed files>
 git commit -m "fix(<scope>): resolve lint/type/test issues
@@ -530,7 +533,7 @@ second copy of a schema is how that happens.
 5. **DO** use project path aliases (`@components`, `@utils`, etc.) for imports.
 6. **DO** wrap React components with `observer()` when they access MobX stores.
 7. **DO** use `runInAction()` after every `await` in MobX actions.
-8. **DO** commit with conventional commit format referencing the issue number.
+8. **DO** use conventional commit format when auto-commit is enabled. Reference only a supplied real issue number; omit the issue reference when absent.
 9. **DO** verify your work before reporting.
 10. **DO** make `STATUS: <TOKEN>` the first line of your final message, and put no
     JSON in the response body. The full JSON result is the file Phase 6.1 writes