@appchy/jarvis 0.1.36 → 0.1.39

package/dist/data/backends.mjs

@@ -0,0 +1,469 @@
+import {
+  IMPORT_RELATIONS
+} from "./chunk-AKQQC5IT.mjs";
+import "./chunk-7REP35VA.mjs";
+import "./chunk-RRJ6KKYL.mjs";
+import {
+  backend
+} from "./chunk-AYOJSS2F.mjs";
+import {
+  matcher
+} from "./chunk-YWSWQEJN.mjs";
+
+// ../../packages/data/src/backends/graphify.ts
+import { execFile } from "child_process";
+import { access, readFile as readFile2, rename, rm, stat, utimes, writeFile } from "fs/promises";
+import { dirname, resolve as resolve2 } from "path";
+import { promisify } from "util";
+
+// ../../packages/data/src/backends/imports.ts
+import { readFile } from "fs/promises";
+import { posix, resolve } from "path";
+var IMPORT_RELATION_SET = new Set(IMPORT_RELATIONS);
+var asStr = (v) => typeof v === "string" ? v : void 0;
+var toPosix = (p) => p.replace(/\\/g, "/");
+var noExt = (p) => p.replace(/\.[^./]+$/, "");
+var baseNoExt = (p) => noExt(p.split("/").pop() ?? p);
+function lineNumberOf(loc) {
+  if (!loc) return void 0;
+  const m = loc.match(/\d+/);
+  return m ? Number(m[0]) : void 0;
+}
+function specifiersOf(line) {
+  const re = /(?:from|import|require)\s*\(?\s*['"]([^'"]+)['"]/g;
+  const out = [];
+  let m;
+  while ((m = re.exec(line)) !== null) if (m[1]) out.push(m[1]);
+  return out;
+}
+function resolvedNoExt(importer, spec) {
+  return noExt(posix.normalize(posix.join(posix.dirname(importer), spec)));
+}
+var NO_PACKAGE = /* @__PURE__ */ Symbol("no-package");
+async function packageNameOf(cache, root, file) {
+  const pending = [];
+  let dir = posix.dirname(toPosix(file));
+  for (; ; ) {
+    const hit = cache.get(dir);
+    if (hit !== void 0) {
+      for (const d of pending) cache.set(d, hit);
+      return hit === NO_PACKAGE ? void 0 : hit;
+    }
+    pending.push(dir);
+    const name = await readFile(resolve(root, dir, "package.json"), "utf8").then((text) => asStr(JSON.parse(text).name)).catch(() => void 0);
+    if (name !== void 0) {
+      for (const d of pending) cache.set(d, name);
+      return name;
+    }
+    const next = posix.dirname(dir);
+    if (next === dir || dir === "." || dir === "") break;
+    dir = next;
+  }
+  for (const d of pending) cache.set(d, NO_PACKAGE);
+  return void 0;
+}
+async function readLines(cache, absPath) {
+  const hit = cache.get(absPath);
+  if (hit !== void 0) return hit;
+  const lines = await readFile(absPath, "utf8").then((text) => text.split(/\r?\n/)).catch(() => null);
+  cache.set(absPath, lines);
+  return lines;
+}
+async function resolveImportCollisions(raw, root) {
+  const fileById = /* @__PURE__ */ new Map();
+  for (const n of raw.nodes) {
+    const id = asStr(n.id);
+    const f = asStr(n.source_file);
+    if (id && f) fileById.set(id, toPosix(f));
+  }
+  const drop = /* @__PURE__ */ new Set();
+  const lineCache = /* @__PURE__ */ new Map();
+  const pkgCache = /* @__PURE__ */ new Map();
+  const fileSpecCache = /* @__PURE__ */ new Map();
+  const specsInFile = async (file) => {
+    const hit = fileSpecCache.get(file);
+    if (hit !== void 0 || fileSpecCache.has(file)) return hit;
+    const lines = await readLines(lineCache, resolve(root, file));
+    const specs = lines?.flatMap((l) => specifiersOf(l));
+    fileSpecCache.set(file, specs);
+    return specs;
+  };
+  for (const link of raw.links) {
+    const rel = asStr(link.relation);
+    if (!rel || !IMPORT_RELATION_SET.has(rel)) continue;
+    const site = asStr(link.source_file);
+    const node = fileById.get(asStr(link.source) ?? "");
+    if (site === void 0 || node === void 0) continue;
+    if (toPosix(site) !== node) drop.add(link);
+  }
+  for (const link of raw.links) {
+    const rel = asStr(link.relation);
+    if (!rel || !IMPORT_RELATION_SET.has(rel)) continue;
+    const importer = toPosix(asStr(link.source_file) ?? "");
+    const target = fileById.get(asStr(link.target) ?? "");
+    if (!importer || !target) continue;
+    const fromPkg = await packageNameOf(pkgCache, root, importer);
+    const toPkg = await packageNameOf(pkgCache, root, target);
+    if (fromPkg === void 0 || toPkg === void 0 || fromPkg === toPkg) continue;
+    const specs = await specsInFile(importer);
+    if (specs === void 0) continue;
+    if (specs.some((s) => s === toPkg || s.startsWith(`${toPkg}/`))) continue;
+    drop.add(link);
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const l of raw.links) {
+    const rel = asStr(l.relation);
+    const src = asStr(l.source);
+    const loc = asStr(l.source_location);
+    if (!rel || !src || !loc || !IMPORT_RELATION_SET.has(rel)) continue;
+    const key = `${src}\0${loc}\0${rel}`;
+    const g = groups.get(key);
+    if (g) g.push(l);
+    else groups.set(key, [l]);
+  }
+  for (const links of groups.values()) {
+    const importer = toPosix(asStr(links[0]?.source_file) ?? "");
+    const lineNo = lineNumberOf(asStr(links[0]?.source_location));
+    if (!importer || lineNo === void 0) continue;
+    const lines = await readLines(lineCache, resolve(root, importer));
+    const line = lines?.[lineNo - 1];
+    if (!line) continue;
+    const allSpecs = specifiersOf(line);
+    if (!allSpecs.length) continue;
+    const bare = allSpecs.filter((s) => !s.startsWith(".") && !s.startsWith("/"));
+    if (bare.length === allSpecs.length) {
+      for (const link of links) {
+        const file = fileById.get(asStr(link.target) ?? "");
+        if (!file) continue;
+        const pkg = await packageNameOf(pkgCache, root, file);
+        if (pkg === void 0) continue;
+        if (bare.some((s) => s === pkg || s.startsWith(`${pkg}/`))) continue;
+        drop.add(link);
+      }
+      continue;
+    }
+    if (links.length < 2) continue;
+    const byBase = /* @__PURE__ */ new Map();
+    for (const link of links) {
+      const file = fileById.get(asStr(link.target) ?? "");
+      if (!file) continue;
+      const base = baseNoExt(file);
+      let files = byBase.get(base);
+      if (!files) {
+        files = /* @__PURE__ */ new Map();
+        byBase.set(base, files);
+      }
+      const list = files.get(file);
+      if (list) list.push(link);
+      else files.set(file, [link]);
+    }
+    const colliding = [...byBase.values()].filter((files) => files.size >= 2);
+    if (!colliding.length) continue;
+    const specs = allSpecs.filter((s) => s.startsWith("."));
+    if (!specs.length) continue;
+    for (const files of colliding) {
+      const base = baseNoExt([...files.keys()][0] ?? "");
+      const spec = specs.find((s) => baseNoExt(s) === base);
+      if (!spec) continue;
+      const want = resolvedNoExt(importer, spec);
+      const winners = [...files.keys()].filter((f) => noExt(f) === want);
+      if (winners.length !== 1) continue;
+      const keep = winners[0];
+      for (const [file, ls] of files) if (file !== keep) for (const l of ls) drop.add(l);
+    }
+  }
+  if (!drop.size) return raw;
+  return { nodes: raw.nodes, links: raw.links.filter((l) => !drop.has(l)) };
+}
+
+// ../../packages/data/src/backends/prompt.ts
+function communityLine(c) {
+  return `Community ${c.id}: ${c.representatives.join(", ")}`;
+}
+function communityLabelPrompt(communities) {
+  return 'You are naming clusters in a knowledge graph. For each community below, return a concise 2-5 word plain-language name describing what it is about (e.g. "Order Management", "Payment Flow", "Auth Middleware"). Respond ONLY with a JSON object mapping the community id (as a string) to its name - no prose, no markdown fences.\n\n' + communities.map(communityLine).join("\n");
+}
+
+// ../../packages/data/src/backends/graphify.ts
+var run = promisify(execFile);
+var LABEL_TOP_K = 8;
+var LABEL_MAX_LEN = 80;
+var PLACEHOLDER_COMMUNITY = /^Community \d+$/;
+var DEFAULT_GRAPH_JSON = ".data/graphify/graph.json";
+function graphify(options = {}) {
+  const graphRel = options.path ?? DEFAULT_GRAPH_JSON;
+  return backend({
+    name: "graphify",
+    native: () => ({ type: "graphify", graphJson: graphRel }),
+    // Declared, so `jarvis-data lint` can gate on it while presenting the built graph. Still checked
+    // inside `load` too: a build DOES run the backend, and a graph that fell behind mid-build is worth
+    // saying so at the moment it is produced.
+    ...options.staleness ? { staleness: options.staleness } : {},
+    load: async (ctx) => {
+      const root = resolve2(ctx.config.repoRoot, options.root ?? ".");
+      const graphPath = resolve2(ctx.config.repoRoot, graphRel);
+      const bin = options.bin ?? "graphify";
+      const forceExtract = process.env.JARVIS_DATA_REBUILD === "1";
+      const refresh = process.env.JARVIS_DATA_REFRESH === "1" && options.extract !== false;
+      const forceLabel = process.env.JARVIS_DATA_LABEL === "1";
+      const mode = forceExtract ? true : options.extract ?? "auto";
+      const present = await exists(graphPath);
+      const missing = options.missing !== void 0 ? { missing: options.missing } : {};
+      const extracted = forceExtract && present ? await rebuildFresh(graphPath, () => extract(bin, root, ctx, graphRel, { ...missing })) : refresh ? await extract(bin, root, ctx, graphRel, { force: true, ...missing }) : mode === true || mode === "auto" && !present ? await extract(bin, root, ctx, graphRel, { ...missing }) : false;
+      if (extracted) await stampFresh(graphPath);
+      if (!await exists(graphPath)) {
+        ctx.panic(
+          `graphify graph not found at ${graphRel}. Run \`jarvis build graph\`, or set { extract: true } in the backend options.`
+        );
+      }
+      if (options.staleness) await reportIfStale(ctx, graphPath, graphRel, options.staleness);
+      const raw = JSON.parse(await readFile2(graphPath, "utf8"));
+      if (options.labeler && (forceLabel || extracted && !refresh)) {
+        await labelCommunities(ctx, options.labeler, raw, graphPath, extracted);
+      }
+      const labels = await loadCommunityLabels(graphPath);
+      const corrected = await resolveImportCollisions(raw, root);
+      return mapAndFilter(corrected, options, labels);
+    }
+  });
+}
+async function loadCommunityLabels(graphPath) {
+  const labels = /* @__PURE__ */ new Map();
+  const labelPath = resolve2(dirname(graphPath), ".graphify_labels.json");
+  try {
+    const raw = JSON.parse(await readFile2(labelPath, "utf8"));
+    if (!raw || typeof raw !== "object") return labels;
+    for (const [rawId, rawName] of Object.entries(raw)) {
+      const name = asString(rawName);
+      if (name) labels.set(rawId, name);
+    }
+  } catch {
+  }
+  return labels;
+}
+function mapAndFilter(raw, options, labels) {
+  const matchIgnore = options.ignore && options.ignore.length ? matcher(options.ignore) : void 0;
+  const matchInclude = options.include && options.include.length ? matcher(options.include) : void 0;
+  const kept = /* @__PURE__ */ new Set();
+  const nodes = [];
+  for (const n of raw.nodes) {
+    const id = asString(n.id);
+    if (!id) continue;
+    const sourceFile = asString(n.source_file);
+    if (sourceFile) {
+      if (matchInclude && !matchInclude(sourceFile)) continue;
+      if (matchIgnore && matchIgnore(sourceFile)) continue;
+    }
+    kept.add(id);
+    nodes.push({
+      id,
+      type: asString(n.file_type) ?? "code",
+      metadata: {
+        ...asString(n.label) ? { label: asString(n.label) } : {},
+        ...sourceFile ? { sourceFile } : {},
+        // graphify carries the symbol's location as e.g. "L123" — keep it so rendered code
+        // nodes can surface `file:line` (Claude Code jumps/Reads by line). Parsed in lineOf.
+        ...asString(n.source_location) ? { sourceLine: asString(n.source_location) } : {},
+        ...communityOf(n, labels) ? { community: communityOf(n, labels) } : {},
+        origin: "graphify"
+      }
+    });
+  }
+  const edges = [];
+  for (const l of raw.links) {
+    const from = asString(l.source);
+    const to = asString(l.target);
+    if (!from || !to || !kept.has(from) || !kept.has(to)) continue;
+    edges.push({ from, to, relation: asString(l.relation) ?? "related" });
+  }
+  return { nodes, edges };
+}
+function communityOf(n, labels) {
+  const named = asString(n.community_name);
+  if (named && !PLACEHOLDER_COMMUNITY.test(named)) return named;
+  const id = n.community;
+  if (id === void 0 || id === null || id === "") return void 0;
+  const key = String(id);
+  return labels.get(key) ?? `Community ${key}`;
+}
+function graphifyOptions(ctx, graphRel) {
+  return { cwd: ctx.config.repoRoot, env: { ...process.env, GRAPHIFY_OUT: dirname(graphRel) } };
+}
+async function extract(bin, root, ctx, graphRel, options = {}) {
+  try {
+    ctx.logger.info(
+      `graphify: extracting ${root}${options.force ? " (incremental \u2014 prune deletions)" : ""}`
+    );
+    const args = options.force ? ["update", "--force", root] : ["update", root];
+    await run(bin, args, graphifyOptions(ctx, graphRel));
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") {
+      const message = `graphify binary "${bin}" not found \u2014 install it with \`uv tool install graphifyy\`, or set { extract: false } to present the existing graph.`;
+      if (options.missing === "error") ctx.panic(message);
+      ctx.report({
+        severity: options.missing ?? "warn",
+        code: "BACKEND_UNAVAILABLE",
+        message: `${message} Using the existing graph.json if present.`
+      });
+      return false;
+    }
+    ctx.report({
+      severity: "warn",
+      code: "BACKEND_EXTRACT_FAILED",
+      message: `graphify update failed: ${err instanceof Error ? err.message : String(err)}`
+    });
+    return false;
+  }
+}
+async function rebuildFresh(graphPath, extract2) {
+  const backup = `${graphPath}.bak`;
+  await rename(graphPath, backup);
+  let ok = false;
+  try {
+    ok = await extract2() && await parseable(graphPath);
+  } catch {
+    ok = false;
+  }
+  if (ok) {
+    await rm(backup, { force: true });
+    return true;
+  }
+  await rename(backup, graphPath);
+  return false;
+}
+async function parseable(path) {
+  try {
+    JSON.parse(await readFile2(path, "utf8"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function stampFresh(path) {
+  try {
+    const now = /* @__PURE__ */ new Date();
+    await utimes(path, now, now);
+  } catch {
+  }
+}
+async function labelCommunities(ctx, labeler, raw, graphPath, freshExtract) {
+  const sampled = sampleCommunities(raw);
+  if (!sampled.length) return;
+  const relabelAll = freshExtract || process.env.JARVIS_DATA_RELABEL_ALL === "1";
+  const existing = relabelAll ? /* @__PURE__ */ new Map() : await readCommunityLabels(graphPath);
+  const communities = sampled.filter((c) => !existing.has(c.id));
+  if (!communities.length) {
+    ctx.logger.info(
+      "communities already named \u2014 nothing to label (set JARVIS_DATA_RELABEL_ALL=1 to force)"
+    );
+    return;
+  }
+  try {
+    ctx.logger.info(`labeling ${communities.length} communities via ${labeler.name}`);
+    const named = await labeler.label({ communities, prompt: communityLabelPrompt });
+    if (named.size) await writeCommunityLabels(graphPath, named);
+  } catch (err) {
+    ctx.report({
+      severity: "warn",
+      code: "BACKEND_LABEL_FAILED",
+      message: `community labeling (${labeler.name}) failed; communities keep their cluster ids: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+}
+function sampleCommunities(raw) {
+  const degree = /* @__PURE__ */ new Map();
+  for (const l of raw.links) {
+    const s = asString(l.source);
+    const t = asString(l.target);
+    if (s) degree.set(s, (degree.get(s) ?? 0) + 1);
+    if (t) degree.set(t, (degree.get(t) ?? 0) + 1);
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const n of raw.nodes) {
+    const id = asString(n.id);
+    if (!id) continue;
+    const c = n.community;
+    if (c === void 0 || c === null || c === "") continue;
+    const member = { id, label: asString(n.label) ?? id };
+    const arr = groups.get(String(c));
+    if (arr) arr.push(member);
+    else groups.set(String(c), [member]);
+  }
+  const communities = [];
+  for (const [id, members] of [...groups].sort((a, b) => b[1].length - a[1].length)) {
+    members.sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0));
+    const representatives = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const m of members) {
+      const label = m.label.trim().replace(/^\(+|\)+$/g, "").slice(0, LABEL_MAX_LEN);
+      if (label && !seen.has(label.toLowerCase())) {
+        seen.add(label.toLowerCase());
+        representatives.push(label);
+      }
+      if (representatives.length >= LABEL_TOP_K) break;
+    }
+    if (representatives.length) communities.push({ id, representatives });
+  }
+  return communities;
+}
+function communityLabelsPath(graphPath) {
+  return resolve2(dirname(graphPath), ".graphify_labels.json");
+}
+async function readCommunityLabels(graphPath) {
+  const out = /* @__PURE__ */ new Map();
+  try {
+    const existing = JSON.parse(await readFile2(communityLabelsPath(graphPath), "utf8"));
+    for (const [id, value] of Object.entries(existing)) {
+      const name = asString(value);
+      if (name && !PLACEHOLDER_COMMUNITY.test(name)) out.set(id, name);
+    }
+  } catch {
+  }
+  return out;
+}
+async function writeCommunityLabels(graphPath, named) {
+  const merged = {};
+  for (const [id, name] of await readCommunityLabels(graphPath)) merged[id] = name;
+  for (const [id, name] of named) merged[id] = name;
+  await writeFile(communityLabelsPath(graphPath), `${JSON.stringify(merged, null, 2)}
+`, "utf8");
+}
+async function reportIfStale(ctx, graphPath, graphRel, severity) {
+  let graphMs;
+  try {
+    graphMs = (await stat(graphPath)).mtimeMs;
+  } catch {
+    return;
+  }
+  let headMs;
+  try {
+    const { stdout } = await run("git", ["show", "-s", "--format=%ct", "HEAD"], {
+      cwd: ctx.config.repoRoot
+    });
+    const seconds = Number(stdout.trim());
+    headMs = Number.isFinite(seconds) ? seconds * 1e3 : void 0;
+  } catch {
+    return;
+  }
+  if (headMs !== void 0 && graphMs < headMs) {
+    ctx.report({
+      severity,
+      code: "stale-graph",
+      message: `${graphRel} is older than HEAD \u2014 the code graph is stale, so traces and impact analysis can't be trusted. Rebuild it (\`graphify update .\` / \`make graph\`).`
+    });
+  }
+}
+async function exists(path) {
+  return access(path).then(
+    () => true,
+    () => false
+  );
+}
+function asString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+export {
+  graphify
+};