@mrciphersmith/keryx 0.2.76 → 0.2.78

package/dist/proxy-worker.js

@@ -124,23 +124,23 @@ async function createAllowlistProxy(opts) {
   };
   const mitmServers = new Map;
   const mitmPortFor = async (hostname, targetPort, ca) => {
-    const host2 = normalizeHost(hostname);
-    const key = `${host2}:${targetPort}`;
+    const host = normalizeHost(hostname);
+    const key = `${host}:${targetPort}`;
     const hit = mitmServers.get(key);
     if (hit)
       return hit.port;
-    const leaf = await ca.issueLeaf(host2);
-    const server2 = https.createServer({ key: leaf.keyPem, cert: leaf.certPem }, makeMitmHandler(host2, targetPort));
-    await new Promise((resolve) => server2.listen(0, "127.0.0.1", () => resolve()));
-    const addr2 = server2.address();
-    const port2 = addr2 && typeof addr2 === "object" ? addr2.port : 0;
-    mitmServers.set(key, { server: server2, port: port2 });
-    return port2;
+    const leaf = await ca.issueLeaf(host);
+    const server = https.createServer({ key: leaf.keyPem, cert: leaf.certPem }, makeMitmHandler(host, targetPort));
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+    const addr = server.address();
+    const port = addr && typeof addr === "object" ? addr.port : 0;
+    mitmServers.set(key, { server, port });
+    return port;
   };
   server.on("connect", (req, clientSocket, head) => {
     const [reqHost, reqPort] = (req.url ?? "").split(":");
     const hostname = reqHost ?? "";
-    const port2 = Number(reqPort) || 443;
+    const port = Number(reqPort) || 443;
     if (!decide({ host: hostname, allowed: matchesAllowlist(hostname, allowed), kind: "connect" })) {
       clientSocket.write(`HTTP/1.1 403 Forbidden\r
 \r
@@ -152,7 +152,7 @@ async function createAllowlistProxy(opts) {
     if (ca) {
       (async () => {
         try {
-          const terminatorPort = await mitmPortFor(hostname, port2, ca);
+          const terminatorPort = await mitmPortFor(hostname, port, ca);
           clientSocket.write(`HTTP/1.1 200 Connection Established\r
 \r
 `);
@@ -173,7 +173,7 @@ async function createAllowlistProxy(opts) {
       })();
       return;
     }
-    const upstream = net.connect(port2, hostname, () => {
+    const upstream = net.connect(port, hostname, () => {
       clientSocket.write(`HTTP/1.1 200 Connection Established\r
 \r
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.76",
+  "version": "0.2.78",
   "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": {

package/src/gdgraph/build.ts

@@ -159,6 +159,18 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
     // Enrichment module or seam unavailable ⇒ file-level graph only.
   }
 
+  // LWG wiki layer (flow 223): the same additive shape as the symbol layer
+  // above — after the unchanged file-level build, into its OWN storage files,
+  // dynamically imported and defensively wrapped so a failure degrades to
+  // "no wiki layer" rather than a failed graph build. `nodes.jsonl` and
+  // `edges.jsonl` written above are never revisited (AC13).
+  try {
+    const { enrichBuildWithWikiLayer } = await import("./wiki-layer");
+    await enrichBuildWithWikiLayer({ projectRoot, graph, fileRecords });
+  } catch {
+    // Wiki absent, unreadable, or the layer module unavailable ⇒ no layer.
+  }
+
   return {
     nodes: nodes.length,
     edges: edges.length,

package/src/gdgraph/query.ts

@@ -1,6 +1,14 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import type { CallEdge, GraphData, GraphEdge, GraphNode, SymbolNode } from "./types";
+import type {
+  CallEdge,
+  DescribesEdge,
+  GraphData,
+  GraphEdge,
+  GraphNode,
+  SymbolNode,
+  WikiPageNode,
+} from "./types";
 import { resolveGraphTarget } from "./target";
 
 export async function loadGraph(projectRoot: string): Promise<GraphData> {
@@ -11,6 +19,11 @@ export async function loadGraph(projectRoot: string): Promise<GraphData> {
   // (never an error — mirrors `readJsonl` tolerance). File-level graph unchanged.
   const symbols = await readJsonl<SymbolNode>(path.join(storageDir, "symbols.jsonl"));
   const calls = await readJsonl<CallEdge>(path.join(storageDir, "calls.jsonl"));
+  // LWG wiki layer (flow 223): same contract as the symbol layer above —
+  // loaded only if present, absent ⇒ omitted, never an error. A graph built
+  // before this layer existed therefore loads byte-for-byte as it always did.
+  const wikiPages = await readJsonl<WikiPageNode>(path.join(storageDir, "wiki-pages.jsonl"));
+  const describes = await readJsonl<DescribesEdge>(path.join(storageDir, "describes.jsonl"));
   const graph: GraphData = { nodes, edges };
   if (symbols.length > 0) {
     graph.symbols = symbols;
@@ -18,9 +31,46 @@ export async function loadGraph(projectRoot: string): Promise<GraphData> {
   if (calls.length > 0) {
     graph.calls = calls;
   }
+  if (wikiPages.length > 0) {
+    graph.wikiPages = wikiPages;
+  }
+  if (describes.length > 0) {
+    graph.describes = describes;
+  }
   return graph;
 }
 
+/**
+ * Reverse the `describes` layer: which wiki pages document this file?
+ * (LWG-1, flow 223 AC3.)
+ *
+ * The layer stores only page → file, so this is the index every caller would
+ * otherwise rebuild. An absent layer yields an empty array — the honest
+ * answer is "no information", and a caller must not read that as "this file
+ * is undocumented"; only a layer that IS present can support that claim.
+ */
+export function getPagesDescribing(graph: GraphData, filePath: string): string[] {
+  const target = filePath.replace(/^\.\//, "");
+  const pages = new Set<string>();
+  for (const edge of graph.describes ?? []) {
+    if (edge.to === target) {
+      pages.add(edge.from);
+    }
+  }
+  return [...pages].sort();
+}
+
+/** Every file the given page documents (LWG-1). Empty when undecidable. */
+export function getFilesDescribedBy(graph: GraphData, pageId: string): string[] {
+  const files = new Set<string>();
+  for (const edge of graph.describes ?? []) {
+    if (edge.from === pageId) {
+      files.add(edge.to);
+    }
+  }
+  return [...files].sort();
+}
+
 export function getOrphans(graph: GraphData): string[] {
   const inbound = new Set(
     graph.edges.filter((edge) => edge.kind !== "unresolved").map((edge) => edge.to),

package/src/gdgraph/types.ts

@@ -56,6 +56,12 @@ export type GraphData = {
   // these fields, keeping the legacy graph shape backward-compatible.
   symbols?: SymbolNode[];
   calls?: CallEdge[];
+  // LWG wiki layer (flow 223) — present only when `storage/wiki-pages.jsonl` /
+  // `storage/describes.jsonl` exist. Same additive contract as the symbol
+  // layer: missing ⇒ omitted, never an error, and file-level consumers that
+  // ignore these fields keep the legacy graph shape.
+  wikiPages?: WikiPageNode[];
+  describes?: DescribesEdge[];
 };
 
 // --- B1 symbol layer types (additive; only materialized in symbols.jsonl /
@@ -95,3 +101,74 @@ export type SymbolLayer = {
   symbols: SymbolNode[];
   calls: CallEdge[];
 };
+
+// --- LWG wiki layer (flow 223, phase 0; additive, materialized only in
+// `storage/wiki-pages.jsonl` / `storage/describes.jsonl`). ---
+//
+// WHY A SEPARATE LAYER rather than new `kind`s inside `nodes.jsonl` /
+// `edges.jsonl`, which the package specification originally called for:
+// five production call sites treat "every node that is not `asset`" as a
+// source file — `validModuleNames` and `collectGraphWikiCandidates`
+// (`src/wiki/service.ts:365,412`), `computeModuleKeyFiles`
+// (`src/wiki/collect.ts:97`) and `src/commands/update.ts:869`. A page node
+// in `nodes.jsonl` would be grouped by `moduleNameFromProjectPath` into a
+// fabricated module (`.metaproject/wiki/components`) and would corrupt the
+// very module set `wikiPruneOrphans` and `src/sac/lifecycle-flag.ts` use to
+// decide what is orphaned. Keeping the layer separate also preserves the
+// build's existing rule that additive layers never rewrite the legacy
+// artifacts (see `build.ts`'s symbol-layer enrichment).
+
+/**
+ * Where a `describes` relation came from, highest precedence first
+ * (specification §3.3). An explicit `Describes:` frontmatter list REPLACES
+ * the derived set rather than adding to it — a human who names the files a
+ * page covers is correcting the derivation, not supplementing it.
+ */
+export type DescribesOrigin = "frontmatter" | "related-code" | "key-files";
+
+export type WikiPageNode = {
+  /** "wiki:<wiki-relative path>", e.g. "wiki:components/src-ctx.md". */
+  id: string;
+  /** Wiki-relative path, e.g. "components/src-ctx.md". */
+  path: string;
+  title: string;
+  /** `WikiPageType` as a plain string; the wiki owns that union. */
+  pageType: string;
+  status: string | null;
+  version: string | null;
+  /**
+   * True when no describe pattern resolved to a known file. Such a page
+   * cannot be scored for freshness — which is NOT the same as being fresh,
+   * and NOT the same as being orphaned (specification §4.4.1).
+   */
+  undecidable: boolean;
+};
+
+export type DescribesEdge = {
+  id: string;
+  /** `WikiPageNode.id`. */
+  from: string;
+  /** A file `GraphNode.path` — the layer only ever points at known files. */
+  to: string;
+  /** The pattern that produced this edge, as written or derived. */
+  pattern: string;
+  origin: DescribesOrigin;
+};
+
+export type WikiLayer = {
+  pages: WikiPageNode[];
+  describes: DescribesEdge[];
+};
+
+/**
+ * Per-file content fingerprint (LWG-2), written to
+ * `storage/build-manifest.json`. Kept out of `GraphNode` so `nodes.jsonl`
+ * stays byte-stable for its existing consumers; the incremental rebuild
+ * (LWG-3, phase 4) is the intended reader.
+ */
+export type FileFingerprint = {
+  path: string;
+  /** sha256 of the file's content at build time. */
+  contentHash: string;
+  mtimeMs: number;
+};

package/src/gdgraph/wiki-layer-no-git.test.ts

@@ -0,0 +1,73 @@
+// Flow 223 AC11: nothing phase 0 adds may depend on git.
+//
+// Different projects treat `.metaproject/` differently, and
+// `src/commands/init.no-git.test.ts` already pins "no git at all" as a
+// supported state. The describe edge, the wiki layer, the build manifest and
+// page provenance must therefore all work on a bare directory — this suite is
+// the guard that keeps a future `git` call from creeping into that path.
+
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { computeVerifiedScope, parseProvenance, writeProvenance } from "../wiki/provenance";
+import { buildGraph } from "./build";
+import { getFilesDescribedBy, loadGraph } from "./query";
+
+async function bareProject(): Promise<string> {
+  const root = await mkdtemp(path.join(tmpdir(), "lwg-nogit-"));
+  await mkdir(path.join(root, "src", "ctx"), { recursive: true });
+  await writeFile(path.join(root, "src", "ctx", "index.ts"), 'export * from "./run";\n');
+  await writeFile(path.join(root, "src", "ctx", "run.ts"), "export const run = () => 1;\n");
+  await mkdir(path.join(root, ".metaproject", "wiki", "components"), { recursive: true });
+  await writeFile(
+    path.join(root, ".metaproject", "wiki", "components", "src-ctx.md"),
+    "# src/ctx\nVersion: 1.0.0\nType: component\nStatus: accepted\nDescribes:\n  - src/ctx/**\n",
+  );
+  return root;
+}
+
+test("the whole phase-0 path works with no .git directory anywhere", async () => {
+  const root = await bareProject();
+
+  // Two builds: the first writes nodes.jsonl, the second sees a module set.
+  await buildGraph(root);
+  await buildGraph(root);
+
+  const graph = await loadGraph(root);
+  expect(graph.wikiPages?.[0]?.id).toBe("wiki:components/src-ctx.md");
+  expect(getFilesDescribedBy(graph, "wiki:components/src-ctx.md")).toEqual([
+    "src/ctx/index.ts",
+    "src/ctx/run.ts",
+  ]);
+
+  // VerifiedScope is the git-free freshness path; it must compute here.
+  const scope = await computeVerifiedScope(root, ["src/ctx/index.ts", "src/ctx/run.ts"], graph);
+  expect(scope).toMatch(/^sha256:[0-9a-f]{64}$/);
+
+  const pagePath = path.join(root, ".metaproject", "wiki", "components", "src-ctx.md");
+  const stamped = writeProvenance(await readFile(pagePath, "utf8"), { verifiedScope: scope });
+  await writeFile(pagePath, stamped);
+  expect(parseProvenance(await readFile(pagePath, "utf8")).verifiedScope).toBe(scope);
+
+  // And no `.git` was created along the way.
+  expect(await readdir(root)).not.toContain(".git");
+});
+
+test("a page carrying VerifiedAt but no reachable git history still resolves", async () => {
+  const root = await bareProject();
+  const pagePath = path.join(root, ".metaproject", "wiki", "components", "src-ctx.md");
+  await writeFile(
+    pagePath,
+    writeProvenance(await readFile(pagePath, "utf8"), { verifiedAt: "a".repeat(40) }),
+  );
+
+  await buildGraph(root);
+  await buildGraph(root);
+
+  // The sha is parsed and kept; deciding it is unreachable is phase 1's job,
+  // and must not become a build-time failure here (specification §4.1 path 2).
+  expect(parseProvenance(await readFile(pagePath, "utf8")).verifiedAt).toBe("a".repeat(40));
+  const graph = await loadGraph(root);
+  expect(graph.wikiPages?.[0]?.undecidable).toBe(false);
+});

package/src/gdgraph/wiki-layer.test.ts

@@ -0,0 +1,211 @@
+// LWG wiki layer (flow 223, phase 0): AC1, AC5, AC6, AC7, AC10, AC13.
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { buildGraph } from "./build";
+import { getFilesDescribedBy, getPagesDescribing, loadGraph } from "./query";
+import type { GraphData } from "./types";
+import { buildWikiLayer, computeFingerprints, wikiPageId } from "./wiki-layer";
+
+const GRAPH: GraphData = {
+  nodes: [
+    { id: "src/ctx/index.ts", kind: "file", path: "src/ctx/index.ts", language: "typescript" },
+    { id: "src/ctx/run.ts", kind: "file", path: "src/ctx/run.ts", language: "typescript" },
+    { id: "logo.png", kind: "asset", path: "logo.png", language: "asset" },
+  ],
+  edges: [],
+};
+
+function page(relativePath: string, overrides: Partial<{ title: string; pageType: string }> = {}) {
+  return {
+    relativePath,
+    title: overrides.title ?? relativePath,
+    pageType: overrides.pageType ?? "component",
+    status: "accepted" as string | null,
+    version: "1.0.0" as string | null,
+  };
+}
+
+describe("buildWikiLayer", () => {
+  test("AC1: emits a page node per page and describes edges for resolved paths", () => {
+    const layer = buildWikiLayer({
+      projectRoot: "/x",
+      graph: GRAPH,
+      validModules: new Set(["src/ctx"]),
+      pages: [page("components/src-ctx.md")],
+      pageContents: new Map([
+        ["components/src-ctx.md", "Describes:\n  - src/ctx/index.ts\n  - src/ctx/run.ts\n"],
+      ]),
+    });
+
+    expect(layer.pages).toHaveLength(1);
+    expect(layer.pages[0]?.id).toBe("wiki:components/src-ctx.md");
+    expect(layer.pages[0]?.undecidable).toBe(false);
+    expect(layer.describes.map((edge) => edge.to)).toEqual(["src/ctx/index.ts", "src/ctx/run.ts"]);
+    expect(layer.describes.every((edge) => edge.origin === "frontmatter")).toBe(true);
+  });
+
+  test("AC6: an unbuilt graph yields an EMPTY layer, not a layer of orphans", () => {
+    const layer = buildWikiLayer({
+      projectRoot: "/x",
+      graph: GRAPH,
+      validModules: undefined,
+      pages: [page("components/src-ctx.md")],
+      pageContents: new Map([["components/src-ctx.md", "Describes:\n  - src/ctx/index.ts\n"]]),
+    });
+
+    // The dangerous alternative is one page node per page marked undecidable:
+    // that reads downstream as "every page describes nothing", i.e. everything
+    // is orphaned. Absent information must stay absent.
+    expect(layer).toEqual({ pages: [], describes: [] });
+  });
+
+  test("AC5: the module set drives the layer — a stubbed set changes the output", () => {
+    const withModules = buildWikiLayer({
+      projectRoot: "/x",
+      graph: GRAPH,
+      validModules: new Set(["src/ctx"]),
+      pages: [page("components/src-ctx.md")],
+      pageContents: new Map([["components/src-ctx.md", "# Page\n"]]),
+    });
+    const withoutModules = buildWikiLayer({
+      projectRoot: "/x",
+      graph: GRAPH,
+      validModules: undefined,
+      pages: [page("components/src-ctx.md")],
+      pageContents: new Map([["components/src-ctx.md", "# Page\n"]]),
+    });
+    expect(withModules.pages.length).not.toBe(withoutModules.pages.length);
+  });
+
+  test("AC10: a page describing nothing is undecidable and emits no edges", () => {
+    const layer = buildWikiLayer({
+      projectRoot: "/x",
+      graph: GRAPH,
+      validModules: new Set(["src/ctx"]),
+      pages: [page("architecture/overview.md", { pageType: "architecture" })],
+      pageContents: new Map([["architecture/overview.md", "# Overview\nStatus: accepted\n"]]),
+    });
+
+    expect(layer.pages[0]?.undecidable).toBe(true);
+    expect(layer.describes).toEqual([]);
+  });
+
+  test("asset nodes are never describable targets", () => {
+    const layer = buildWikiLayer({
+      projectRoot: "/x",
+      graph: GRAPH,
+      validModules: new Set(["src/ctx"]),
+      pages: [page("components/x.md")],
+      pageContents: new Map([["components/x.md", "Describes:\n  - logo.png\n"]]),
+    });
+    expect(layer.describes).toEqual([]);
+    expect(layer.pages[0]?.undecidable).toBe(true);
+  });
+});
+
+describe("computeFingerprints (AC7)", () => {
+  test("hashes are content-derived, stable and sorted by path", () => {
+    const records = [
+      { path: "b.ts", content: "export const b = 1;\n" },
+      { path: "a.ts", content: "export const a = 1;\n" },
+    ];
+    const first = computeFingerprints(records, new Map([["a.ts", 5]]));
+    const second = computeFingerprints(records, new Map([["a.ts", 5]]));
+
+    expect(first.map((f) => f.path)).toEqual(["a.ts", "b.ts"]);
+    expect(first).toEqual(second);
+    expect(first[0]?.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(first[0]?.contentHash).not.toBe(first[1]?.contentHash);
+    // A file whose mtime could not be read is recorded as 0, not dropped.
+    expect(first[1]?.mtimeMs).toBe(0);
+  });
+});
+
+describe("reverse queries (AC3)", () => {
+  const graph: GraphData = {
+    ...GRAPH,
+    describes: [
+      { id: "d1", from: wikiPageId("components/a.md"), to: "src/ctx/index.ts", pattern: "src/ctx", origin: "key-files" },
+      { id: "d2", from: wikiPageId("components/b.md"), to: "src/ctx/index.ts", pattern: "src/ctx/index.ts", origin: "frontmatter" },
+      { id: "d3", from: wikiPageId("components/b.md"), to: "src/ctx/run.ts", pattern: "src/ctx/run.ts", origin: "frontmatter" },
+    ],
+  };
+
+  test("a file covered by two pages returns both, and nothing else", () => {
+    expect(getPagesDescribing(graph, "src/ctx/index.ts")).toEqual([
+      "wiki:components/a.md",
+      "wiki:components/b.md",
+    ]);
+    expect(getPagesDescribing(graph, "src/ctx/run.ts")).toEqual(["wiki:components/b.md"]);
+  });
+
+  test("the forward direction is available from the same layer", () => {
+    expect(getFilesDescribedBy(graph, wikiPageId("components/b.md"))).toEqual([
+      "src/ctx/index.ts",
+      "src/ctx/run.ts",
+    ]);
+  });
+
+  test("no layer means no information, and an empty answer says so honestly", () => {
+    expect(getPagesDescribing({ nodes: [], edges: [] }, "src/ctx/index.ts")).toEqual([]);
+  });
+});
+
+describe("end-to-end build (AC1, AC7, AC13)", () => {
+  async function fixture(): Promise<string> {
+    const root = await mkdtemp(path.join(tmpdir(), "lwg-build-"));
+    await mkdir(path.join(root, "src", "ctx"), { recursive: true });
+    await writeFile(path.join(root, "src", "ctx", "index.ts"), 'export * from "./run";\n');
+    await writeFile(path.join(root, "src", "ctx", "run.ts"), "export const run = () => 1;\n");
+    return root;
+  }
+
+  test("layer files appear, and nodes.jsonl/edges.jsonl stay byte-identical (AC13)", async () => {
+    const root = await fixture();
+    const storage = path.join(root, ".metaproject", "data", "gdgraph", "storage");
+
+    // Build with no wiki at all: the layer cannot run.
+    await buildGraph(root);
+    const nodesBefore = await readFile(path.join(storage, "nodes.jsonl"), "utf8");
+    const edgesBefore = await readFile(path.join(storage, "edges.jsonl"), "utf8");
+
+    // Now add a wiki page and rebuild: the layer runs.
+    await mkdir(path.join(root, ".metaproject", "wiki", "components"), { recursive: true });
+    await writeFile(
+      path.join(root, ".metaproject", "wiki", "components", "src-ctx.md"),
+      "# src/ctx\nVersion: 1.0.0\nType: component\nStatus: accepted\nDescribes:\n  - src/ctx/run.ts\n",
+    );
+    await buildGraph(root);
+
+    const nodesAfter = await readFile(path.join(storage, "nodes.jsonl"), "utf8");
+    const edgesAfter = await readFile(path.join(storage, "edges.jsonl"), "utf8");
+    // The whole reason the layer is separate: legacy artifacts unchanged.
+    expect(nodesAfter).toBe(nodesBefore);
+    expect(edgesAfter).toBe(edgesBefore);
+
+    const graph = await loadGraph(root);
+    expect(graph.wikiPages?.map((p) => p.id)).toEqual(["wiki:components/src-ctx.md"]);
+    expect(getFilesDescribedBy(graph, "wiki:components/src-ctx.md")).toEqual(["src/ctx/run.ts"]);
+
+    const manifest = JSON.parse(await readFile(path.join(storage, "build-manifest.json"), "utf8"));
+    expect(manifest.files.map((f: { path: string }) => f.path)).toEqual([
+      "src/ctx/index.ts",
+      "src/ctx/run.ts",
+    ]);
+    expect(manifest.files[0].contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(manifest.files[0].mtimeMs).toBeGreaterThan(0);
+  });
+
+  test("AC2: a graph with no layer files loads with the fields simply absent", async () => {
+    const root = await fixture();
+    await buildGraph(root);
+    // No wiki directory was ever created, so no layer files exist.
+    const graph = await loadGraph(root);
+    expect(graph.wikiPages).toBeUndefined();
+    expect(graph.describes).toBeUndefined();
+    expect(graph.nodes.length).toBeGreaterThan(0);
+  });
+});