mason-context 0.3.7 → 0.7.0

package/dist/mason-drift.js

@@ -0,0 +1,541 @@
+#!/usr/bin/env node
+
+// src/drift/cli.ts
+import path8 from "path";
+
+// src/drift/drift.ts
+import fs3 from "fs/promises";
+import path4 from "path";
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
+
+// src/snapshot/snapshot.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+import fg3 from "fast-glob";
+
+// src/mcp/sampler.ts
+import fs from "fs/promises";
+import path from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import fg from "fast-glob";
+var exec = promisify(execFile);
+
+// src/test-map.ts
+import path2 from "path";
+import fg2 from "fast-glob";
+
+// src/snapshot/snapshot.ts
+var exec2 = promisify2(execFile2);
+function snapshotDir(rootDir) {
+  return path3.join(rootDir, ".mason");
+}
+function snapshotPath(rootDir) {
+  return path3.join(snapshotDir(rootDir), "snapshot.json");
+}
+async function loadSnapshot(rootDir) {
+  try {
+    const raw = await fs2.readFile(snapshotPath(rootDir), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 2) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function getCurrentGitHash(rootDir) {
+  try {
+    const { stdout } = await exec2("git", ["rev-parse", "HEAD"], {
+      cwd: rootDir
+    });
+    return stdout.trim();
+  } catch {
+    return "unknown";
+  }
+}
+var SOURCE_GLOB = "**/*.{ts,tsx,js,jsx,kt,kts,java,py,go,rs,swift,rb,cs,cpp,c,dart}";
+var SOURCE_IGNORE = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.gradle/**",
+  "**/target/**",
+  "**/.git/**",
+  "**/vendor/**",
+  "**/__pycache__/**",
+  "**/venv/**",
+  "**/.venv/**",
+  "**/*.min.*",
+  "**/*.map",
+  "**/generated/**",
+  "**/R.java",
+  "**/BuildConfig.java"
+];
+async function listSourceFiles(resolvedRoot) {
+  const all = await fg3(SOURCE_GLOB, {
+    cwd: resolvedRoot,
+    ignore: SOURCE_IGNORE
+  });
+  return [...all].sort();
+}
+
+// src/drift/drift.ts
+var exec3 = promisify3(execFile3);
+var FULL_REBUILD_FRACTION = 0.4;
+var FULL_REBUILD_MIN_CHANGED_MAPPED_FILES = 10;
+async function getChangesWithStatus(resolvedRoot, fromHash) {
+  if (!fromHash || fromHash === "unknown") return null;
+  try {
+    const { stdout } = await exec3(
+      "git",
+      ["diff", "--name-status", "-M", fromHash, "HEAD"],
+      { cwd: resolvedRoot, maxBuffer: 10 * 1024 * 1024 }
+    );
+    const changes = [];
+    for (const line of stdout.split("\n")) {
+      if (!line.trim()) continue;
+      const parts = line.split("	");
+      if (parts.some((p) => p.startsWith(".mason/"))) continue;
+      const code = parts[0];
+      if (code.startsWith("R") && parts.length >= 3) {
+        changes.push({
+          status: "renamed",
+          path: parts[2],
+          previousPath: parts[1]
+        });
+      } else if (code.startsWith("C") && parts.length >= 3) {
+        changes.push({ status: "added", path: parts[2] });
+      } else if (code === "A" && parts.length >= 2) {
+        changes.push({ status: "added", path: parts[1] });
+      } else if (code === "D" && parts.length >= 2) {
+        changes.push({ status: "deleted", path: parts[1] });
+      } else if (parts.length >= 2) {
+        changes.push({ status: "modified", path: parts[1] });
+      }
+    }
+    return changes;
+  } catch {
+    return null;
+  }
+}
+async function countCommitsBehind(resolvedRoot, fromHash) {
+  try {
+    const { stdout } = await exec3(
+      "git",
+      ["rev-list", "--count", `${fromHash}..HEAD`],
+      { cwd: resolvedRoot }
+    );
+    const count = Number.parseInt(stdout.trim(), 10);
+    return Number.isNaN(count) ? null : count;
+  } catch {
+    return null;
+  }
+}
+function collectMappedFiles(snapshot) {
+  const mappedFiles = /* @__PURE__ */ new Set();
+  for (const feature of Object.values(snapshot.features)) {
+    for (const f of feature.files) mappedFiles.add(f);
+    for (const t of feature.tests ?? []) mappedFiles.add(t);
+  }
+  for (const flow of Object.values(snapshot.flows)) {
+    for (const f of flow.chain) mappedFiles.add(f);
+  }
+  return mappedFiles;
+}
+async function findGhostFiles(resolvedRoot, mappedFiles) {
+  const ghosts = [];
+  for (const file of mappedFiles) {
+    try {
+      await fs3.access(path4.join(resolvedRoot, file));
+    } catch {
+      ghosts.push(file);
+    }
+  }
+  return ghosts.sort();
+}
+async function computeDrift(rootDir) {
+  const resolvedRoot = path4.resolve(rootDir);
+  const snapshot = await loadSnapshot(resolvedRoot);
+  if (!snapshot) return null;
+  const headHash = await getCurrentGitHash(resolvedRoot);
+  const totalFeatures = Object.keys(snapshot.features).length;
+  const totalFlows = Object.keys(snapshot.flows).length;
+  const hashFor = (entry) => entry.refreshedHash ?? snapshot.gitHash;
+  const distinctHashes = /* @__PURE__ */ new Set([snapshot.gitHash]);
+  for (const feature of Object.values(snapshot.features)) {
+    distinctHashes.add(hashFor(feature));
+  }
+  for (const flow of Object.values(snapshot.flows)) {
+    distinctHashes.add(hashFor(flow));
+  }
+  distinctHashes.delete("unknown");
+  const staleHashes = headHash === "unknown" ? [] : [...distinctHashes].filter((h) => h !== headHash);
+  const stale = staleHashes.length > 0;
+  const report = {
+    stale,
+    snapshotHash: snapshot.gitHash,
+    headHash,
+    commitsBehind: stale ? null : 0,
+    historyAvailable: true,
+    changedFiles: [],
+    staleFeatures: {},
+    staleFlows: {},
+    totalFeatures,
+    totalFlows,
+    unmappedFiles: [],
+    ghostFiles: [],
+    renames: [],
+    recommendation: "up-to-date"
+  };
+  if (!stale) return report;
+  const mappedFiles = collectMappedFiles(snapshot);
+  report.ghostFiles = await findGhostFiles(resolvedRoot, mappedFiles);
+  const changesByHash = /* @__PURE__ */ new Map();
+  const touchedByHash = /* @__PURE__ */ new Map();
+  for (const hash of staleHashes) {
+    const changes = await getChangesWithStatus(resolvedRoot, hash);
+    if (changes === null) {
+      report.historyAvailable = false;
+      report.recommendation = "full-rebuild";
+      return report;
+    }
+    changesByHash.set(hash, changes);
+    const touched = /* @__PURE__ */ new Set();
+    for (const change of changes) {
+      touched.add(change.path);
+      if (change.previousPath) touched.add(change.previousPath);
+    }
+    touchedByHash.set(hash, touched);
+  }
+  const commitCounts = await Promise.all(
+    staleHashes.map((hash) => countCommitsBehind(resolvedRoot, hash))
+  );
+  const validCounts = commitCounts.filter((c) => c !== null);
+  report.commitsBehind = validCounts.length > 0 ? Math.max(...validCounts) : null;
+  const emptySet = /* @__PURE__ */ new Set();
+  const touchedFor = (entry) => touchedByHash.get(hashFor(entry)) ?? emptySet;
+  for (const [name, feature] of Object.entries(snapshot.features)) {
+    const touched = touchedFor(feature);
+    const hits = [...feature.files, ...feature.tests ?? []].filter(
+      (f) => touched.has(f)
+    );
+    if (hits.length > 0) report.staleFeatures[name] = [...new Set(hits)];
+  }
+  for (const [name, flow] of Object.entries(snapshot.flows)) {
+    const touched = touchedFor(flow);
+    const hits = flow.chain.filter((f) => touched.has(f));
+    if (hits.length > 0) report.staleFlows[name] = [...new Set(hits)];
+  }
+  const allChanges = [...changesByHash.values()].flat();
+  report.changedFiles = [...new Set(allChanges.map((c) => c.path))].sort();
+  const sourceFileSet = new Set(await listSourceFiles(resolvedRoot));
+  const newPaths = allChanges.filter((c) => c.status === "added" || c.status === "renamed").map((c) => c.path);
+  report.unmappedFiles = [...new Set(newPaths)].filter((p) => sourceFileSet.has(p) && !mappedFiles.has(p)).sort();
+  const renameKeys = /* @__PURE__ */ new Set();
+  for (const change of allChanges) {
+    if (change.status !== "renamed" || !change.previousPath) continue;
+    const key = `${change.previousPath}\0${change.path}`;
+    if (renameKeys.has(key)) continue;
+    renameKeys.add(key);
+    report.renames.push({ from: change.previousPath, to: change.path });
+  }
+  const changedMapped = /* @__PURE__ */ new Set([
+    ...Object.values(report.staleFeatures).flat(),
+    ...Object.values(report.staleFlows).flat()
+  ]);
+  const changedFraction = mappedFiles.size > 0 ? changedMapped.size / mappedFiles.size : 0;
+  report.recommendation = changedMapped.size >= FULL_REBUILD_MIN_CHANGED_MAPPED_FILES && changedFraction > FULL_REBUILD_FRACTION ? "full-rebuild" : "incremental";
+  return report;
+}
+
+// src/decisions/drift.ts
+import path7 from "path";
+
+// src/decisions/decisions.ts
+import fs4 from "fs/promises";
+import path6 from "path";
+import { createHash } from "crypto";
+
+// src/context/lexical.ts
+import path5 from "path";
+
+// src/decisions/decisions.ts
+function decisionsDir(rootDir) {
+  return path6.join(rootDir, ".mason", "decisions");
+}
+async function loadDecisions(rootDir) {
+  let entries;
+  try {
+    entries = await fs4.readdir(decisionsDir(rootDir));
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    try {
+      const raw = await fs4.readFile(
+        path6.join(decisionsDir(rootDir), entry),
+        "utf-8"
+      );
+      const parsed = JSON.parse(raw);
+      if (parsed.version !== 1 || !parsed.id || !parsed.title || !parsed.body) {
+        continue;
+      }
+      records.push(parsed);
+    } catch {
+      continue;
+    }
+  }
+  return records.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+// src/decisions/drift.ts
+async function computeDecisionDrift(rootDir, decisions) {
+  const resolvedRoot = path7.resolve(rootDir);
+  const records = decisions ?? await loadDecisions(resolvedRoot);
+  const report = {
+    historyAvailable: true,
+    totalDecisions: records.length,
+    staleDecisions: {}
+  };
+  const head = await getCurrentGitHash(resolvedRoot);
+  const changesByHash = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    if (record.status !== "active" || record.files.length === 0) continue;
+    if (record.refreshedHash === head) continue;
+    let touched = changesByHash.get(record.refreshedHash);
+    if (touched === void 0) {
+      const changes = await getChangesWithStatus(
+        resolvedRoot,
+        record.refreshedHash
+      );
+      if (changes === null) {
+        touched = null;
+      } else {
+        touched = /* @__PURE__ */ new Set();
+        for (const change of changes) {
+          touched.add(change.path);
+          if (change.previousPath) touched.add(change.previousPath);
+        }
+      }
+      changesByHash.set(record.refreshedHash, touched);
+    }
+    if (touched === null) {
+      report.historyAvailable = false;
+      continue;
+    }
+    const hits = record.files.filter((f) => touched.has(f));
+    if (hits.length > 0) {
+      report.staleDecisions[record.id] = hits;
+    }
+  }
+  return report;
+}
+
+// src/drift/cli.ts
+var USAGE = `Usage: mason-drift [--dir <path>] [--json | --refresh-prompt]
+
+Checks the Mason concept map (.mason/snapshot.json) against git HEAD.
+Deterministic: no LLM call, no network \u2014 safe for CI.
+
+Options:
+  --dir <path>       Project root to check (default: current directory)
+  --json             Print the full drift report as JSON
+  --refresh-prompt   When stale, print refresh instructions for ANY coding
+                     assistant with the Mason MCP server connected (Claude,
+                     Codex, Gemini, ...) \u2014 pipe it to your agent CLI to
+                     close the loop. Prints nothing extra when fresh.
+  --help             Show this help
+
+Exit codes:
+  0  concept map is up to date
+  1  concept map is stale
+  2  error (no snapshot, not a git repository, bad arguments)`;
+function parseArgs(argv) {
+  const parsed = {
+    dir: process.cwd(),
+    json: false,
+    refreshPrompt: false,
+    help: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      parsed.json = true;
+    } else if (arg === "--refresh-prompt") {
+      parsed.refreshPrompt = true;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else if (arg === "--dir") {
+      const value = argv[++i];
+      if (!value) throw new Error("--dir requires a path argument");
+      parsed.dir = value;
+    } else if (!arg.startsWith("-") && parsed.dir === process.cwd()) {
+      parsed.dir = arg;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return parsed;
+}
+function formatDriftSummary(report) {
+  if (!report.stale) {
+    return `Concept map is up to date (HEAD ${report.headHash.slice(0, 7)}).`;
+  }
+  const lines = [];
+  const behind = report.commitsBehind !== null ? `${report.commitsBehind} commit${report.commitsBehind === 1 ? "" : "s"} behind HEAD` : "an unknown number of commits behind HEAD";
+  lines.push(`Concept map is STALE \u2014 ${behind}.`);
+  if (!report.historyAvailable) {
+    lines.push(
+      "The snapshot's base commit is unreachable (shallow clone or rewritten history); per-feature drift could not be computed."
+    );
+  }
+  const staleFeatures = Object.keys(report.staleFeatures);
+  const staleFlows = Object.keys(report.staleFlows);
+  if (staleFeatures.length > 0) {
+    lines.push(
+      `Stale features (${staleFeatures.length}/${report.totalFeatures}): ${staleFeatures.join(", ")}`
+    );
+  }
+  if (staleFlows.length > 0) {
+    lines.push(
+      `Stale flows (${staleFlows.length}/${report.totalFlows}): ${staleFlows.join(", ")}`
+    );
+  }
+  if (report.unmappedFiles.length > 0) {
+    lines.push(
+      `Unmapped new files (${report.unmappedFiles.length}): ${report.unmappedFiles.join(", ")}`
+    );
+  }
+  if (report.ghostFiles.length > 0) {
+    lines.push(
+      `Ghost files \u2014 mapped but deleted (${report.ghostFiles.length}): ${report.ghostFiles.join(", ")}`
+    );
+  }
+  lines.push(`Recommendation: ${report.recommendation}`);
+  return lines.join("\n");
+}
+function formatRefreshPrompt(report, decisionDrift) {
+  const lines = [];
+  lines.push(
+    "The Mason concept map for this project is stale. Refresh it using the Mason MCP tools (server name: mason). Work autonomously; do not ask questions. Modify ONLY the concept map via Mason tools \u2014 do not edit source files."
+  );
+  lines.push("");
+  lines.push("DRIFT REPORT (deterministic, computed against git HEAD):");
+  lines.push(
+    JSON.stringify(
+      {
+        commitsBehind: report.commitsBehind,
+        recommendation: report.recommendation,
+        staleFeatures: report.staleFeatures,
+        staleFlows: report.staleFlows,
+        changedFiles: report.changedFiles,
+        unmappedFiles: report.unmappedFiles,
+        ghostFiles: report.ghostFiles,
+        renames: report.renames
+      },
+      null,
+      2
+    )
+  );
+  lines.push("");
+  const scopedFiles = [...report.changedFiles, ...report.unmappedFiles];
+  if (!report.historyAvailable || report.recommendation === "full-rebuild") {
+    lines.push(
+      "PROCEDURE (full rebuild): run the complete Map-Reduce build. Call generate_snapshot_batch repeatedly (follow nextOffset until null), calling save_partial_snapshot after each batch, then reduce_snapshot, then save_snapshot once with the unified map. Derive features ONLY from files shown in each batch prompt \u2014 never invent paths."
+    );
+  } else {
+    lines.push(
+      "PROCEDURE (scoped refresh): call generate_snapshot_batch with the files list below \u2014 the SAME list on every call \u2014 following nextOffset until null, calling save_partial_snapshot after each batch. Then call reduce_snapshot (it merges into the existing map, preserving untouched entries) and save_snapshot once. Use save_snapshot's removeFeatures/removeFlows for features that no longer exist (see ghostFiles/renames). Derive features ONLY from files shown in each batch prompt \u2014 never invent paths."
+    );
+    lines.push("");
+    lines.push(`files: ${JSON.stringify(scopedFiles)}`);
+  }
+  const staleDecisionIds = Object.keys(decisionDrift.staleDecisions);
+  if (staleDecisionIds.length > 0) {
+    lines.push("");
+    lines.push(
+      `NOTE: decisions [${staleDecisionIds.join(", ")}] have anchor files that changed. Do NOT modify decision records in this automated run \u2014 they encode human knowledge. Mention them in your final summary so the team re-verifies them.`
+    );
+  }
+  lines.push("");
+  lines.push(
+    "Finish by confirming the map was saved and summarizing which entries changed."
+  );
+  return lines.join("\n");
+}
+async function runDriftCli(argv, io = {
+  out: (line) => process.stdout.write(`${line}
+`),
+  err: (line) => process.stderr.write(`${line}
+`)
+}) {
+  let args;
+  try {
+    args = parseArgs(argv);
+    if (args.json && args.refreshPrompt) {
+      throw new Error("--json and --refresh-prompt are mutually exclusive");
+    }
+  } catch (error) {
+    io.err(error instanceof Error ? error.message : String(error));
+    io.err(USAGE);
+    return 2;
+  }
+  if (args.help) {
+    io.out(USAGE);
+    return 0;
+  }
+  const rootDir = path8.resolve(args.dir);
+  const report = await computeDrift(rootDir);
+  if (!report) {
+    io.err(
+      `No Mason snapshot found at ${path8.join(rootDir, ".mason", "snapshot.json")}. Build one via the Mason MCP server first.`
+    );
+    return 2;
+  }
+  if (report.headHash === "unknown") {
+    io.err(
+      `Could not determine git HEAD in ${rootDir} \u2014 not a git repository, or git is unavailable.`
+    );
+    return 2;
+  }
+  const decisionDrift = await computeDecisionDrift(rootDir);
+  if (args.refreshPrompt) {
+    io.out(
+      report.stale ? formatRefreshPrompt(report, decisionDrift) : formatDriftSummary(report)
+    );
+    return report.stale ? 1 : 0;
+  }
+  if (args.json) {
+    const output = report;
+    if (decisionDrift.totalDecisions > 0) {
+      output.decisions = decisionDrift;
+    }
+    io.out(JSON.stringify(output, null, 2));
+  } else {
+    const lines = [formatDriftSummary(report)];
+    const staleIds = Object.keys(decisionDrift.staleDecisions);
+    if (staleIds.length > 0) {
+      lines.push(
+        `Decisions needing verification (${staleIds.length}/${decisionDrift.totalDecisions}): ${staleIds.join(", ")}`
+      );
+    }
+    io.out(lines.join("\n"));
+  }
+  return report.stale ? 1 : 0;
+}
+
+// bin/mason-drift.ts
+runDriftCli(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`mason-drift error: ${err}
+`);
+    process.exit(2);
+  }
+);
+//# sourceMappingURL=mason-drift.js.map