@swarmvaultai/cli 3.7.3 → 3.9.0

package/README.md

@@ -17,6 +17,16 @@ Installed commands:
 - `swarmvault`
 - `vault` as a compatibility alias
 
+## Maintainer Validation
+
+Release preflight includes a direct CLI surface smoke before tarball smoke:
+
+```bash
+pnpm live:cli-surface
+```
+
+The smoke parses `packages/cli/src/index.ts` with the TypeScript compiler API, checks that every stable Commander command path and alias is classified in the surface manifest, runs `--help` across the full command tree, and exercises direct JSON behavior checks for the core local workflows.
+
 ## First Run
 
 ```bash
@@ -55,6 +65,8 @@ swarmvault explore "What should I research next?" --steps 3
 swarmvault lint --deep
 swarmvault graph blast ./src/index.ts
 swarmvault graph status ./src
+swarmvault graph stats
+swarmvault graph validate --strict
 swarmvault graph update .
 swarmvault graph cluster
 swarmvault graph tree --output ./exports/tree.html
@@ -429,6 +441,25 @@ Read-only graph freshness check for tracked repo roots or one explicit repo path
 - recommends `swarmvault compile` when graph/report artifacts are missing, non-code files changed, or a semantic refresh is pending
 - supports global `--json` for automation
 
+### `swarmvault graph stats`
+
+Summarize the current compiled graph without opening the viewer.
+
+- reports source, page, node, edge, hyperedge, and community counts
+- breaks down node types, evidence classes, source classes, edge relations, and hyperedge relations
+- keeps the same lightweight shape as the MCP `graph_stats` tool
+- supports global `--json` for automation
+
+### `swarmvault graph validate [graph] [--strict]`
+
+Validate graph artifact integrity before exporting, merging, pushing, or publishing generated graph evidence.
+
+- defaults to the current vault's compiled `state/graph.json`
+- accepts an explicit graph JSON path for exported or merged graph artifacts
+- checks duplicate ids, dangling node/page/community/hyperedge references, confidence bounds, empty critical fields, and conflicted-edge evidence consistency
+- exits non-zero when errors are present; with `--strict`, warnings also fail the command
+- supports global `--json` for automation
+
 ### `swarmvault graph cluster [--resolution <n>]`
 
 Recompute communities, node degrees, bridge scores, god-node flags, and graph report artifacts from the existing `state/graph.json` without re-ingesting or re-analyzing sources.

package/dist/index.js

@@ -39,6 +39,7 @@ import {
   getRetrievalStatus,
   getWatchStatus,
   graphDiff,
+  graphStatsVault,
   guideManagedSource,
   guideSourceScope,
   importInbox,
@@ -95,6 +96,7 @@ import {
   summarizeLocalWhisperSetup,
   uninstallGitHooks,
   updateMemoryTask,
+  validateGraphVault,
   watchVault
 } from "@swarmvaultai/engine";
 import { Command, Option } from "commander";
@@ -313,9 +315,9 @@ program.name("swarmvault").description("SwarmVault is a local-first knowledge co
 function readCliVersion() {
   try {
     const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.7.3";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.9.0";
   } catch {
-    return "3.7.3";
+    return "3.9.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -364,6 +366,9 @@ function summarizeRedactions(redactions) {
   const sourceLabel = redactions.length === 1 ? "source" : "sources";
   return `Redacted ${totalMatches} ${secretsLabel} across ${redactions.length} ${sourceLabel} (run --no-redact to disable).`;
 }
+function topCountEntries(record, limit = 8) {
+  return Object.entries(record).filter(([, count]) => count > 0).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).slice(0, limit);
+}
 function emitJson(data) {
   process2.stdout.write(`${JSON.stringify(data)}
 `);
@@ -1225,6 +1230,46 @@ graph.command("status").description("Read-only check for graph/report presence a
     log(`Recommended: ${status.recommendedCommand}`);
   }
 });
+graph.command("stats").description("Summarize compiled graph counts, node types, evidence classes, and relation mix.").action(async () => {
+  const stats = await graphStatsVault(process2.cwd());
+  if (isJson()) {
+    emitJson(stats);
+    return;
+  }
+  log(
+    `Graph stats: ${stats.counts.nodes} nodes, ${stats.counts.edges} edges, ${stats.counts.pages} pages, ${stats.counts.hyperedges} hyperedges, ${stats.counts.communities} communities.`
+  );
+  const nodeTypes = topCountEntries(stats.nodeTypes);
+  if (nodeTypes.length) {
+    log(`Node types: ${nodeTypes.map(([name, count]) => `${name}=${count}`).join(", ")}`);
+  }
+  const evidence = topCountEntries(stats.evidenceClasses);
+  if (evidence.length) {
+    log(`Evidence: ${evidence.map(([name, count]) => `${name}=${count}`).join(", ")}`);
+  }
+  const relations = topCountEntries(stats.edgeRelations);
+  if (relations.length) {
+    log(`Top relations: ${relations.map(([name, count]) => `${name}=${count}`).join(", ")}`);
+  }
+});
+graph.command("validate").description("Validate a compiled graph artifact for dangling references, duplicate ids, and confidence bounds.").argument("[graph]", "Optional graph JSON path; defaults to the current vault graph").option("--strict", "Treat warnings as failures", false).action(async (graphPath, options) => {
+  const result = await validateGraphVault(process2.cwd(), {
+    graphPath,
+    strict: options.strict ?? false
+  });
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(result.summary);
+    for (const issue of result.issues) {
+      const location = issue.path ? ` ${issue.path}` : "";
+      log(`[${issue.severity}] ${issue.code}${location}: ${issue.message}`);
+    }
+  }
+  if (!result.ok) {
+    process2.exitCode = 1;
+  }
+});
 graph.command("cluster").alias("clusters").description("Recompute graph communities, degrees, god-node flags, and graph report artifacts without re-ingesting sources.").option("--resolution <number>", "Override the Louvain community resolution for this run").action(async (options) => {
   const resolution = parsePositiveNumber(options.resolution);
   if (options.resolution && resolution === void 0) {
@@ -1383,18 +1428,33 @@ graph.command("share").description("Print a shareable summary of the compiled gr
   }
   log(options.post ? artifact.shortPost : renderGraphShareMarkdown(artifact));
 });
-graph.command("query").description("Traverse the compiled graph deterministically from local search seeds.").argument("<question>", "Question or graph search seed").option("--dfs", "Prefer a depth-first traversal instead of breadth-first", false).option("--budget <n>", "Maximum number of graph nodes to summarize").action(async (question, options) => {
-  const budget = options.budget ? parsePositiveInt(options.budget, 0) || void 0 : void 0;
-  const result = await queryGraphVault(process2.cwd(), question, {
-    traversal: options.dfs ? "dfs" : "bfs",
-    budget
-  });
-  if (isJson()) {
-    emitJson(result);
-    return;
+graph.command("query").description("Traverse the compiled graph deterministically from local search seeds.").argument("<question>", "Question or graph search seed").option("--dfs", "Prefer a depth-first traversal instead of breadth-first", false).option("--budget <n>", "Maximum number of graph nodes to summarize").option("--relation <name>", "Only traverse edges with this relation name (repeatable)", collectRepeated, []).option(
+  "--context <group>",
+  "Relation group context: calls, imports, types, data, rationale, or evidence (repeatable)",
+  collectRepeated,
+  []
+).option("--evidence <class>", "Evidence class: extracted, inferred, or ambiguous (repeatable)", collectRepeated, []).option("--node-type <type>", "Prefer traversal around this graph node type (repeatable)", collectRepeated, []).option("--language <lang>", "Prefer traversal around this code language (repeatable)", collectRepeated, []).action(
+  async (question, options) => {
+    const budget = options.budget ? parsePositiveInt(options.budget, 0) || void 0 : void 0;
+    const filters = {
+      relations: options.relation,
+      relationGroups: options.context,
+      evidenceClasses: options.evidence,
+      nodeTypes: options.nodeType,
+      languages: options.language
+    };
+    const result = await queryGraphVault(process2.cwd(), question, {
+      traversal: options.dfs ? "dfs" : "bfs",
+      budget,
+      filters
+    });
+    if (isJson()) {
+      emitJson(result);
+      return;
+    }
+    log(result.summary);
   }
-  log(result.summary);
-});
+);
 graph.command("path").description("Find the shortest graph path between two nodes or pages.").argument("<from>", "Source node/page label or id").argument("<to>", "Target node/page label or id").action(async (from, to) => {
   const result = await pathGraphVault(process2.cwd(), from, to);
   if (isJson()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "3.7.3",
+  "version": "3.9.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -44,7 +44,7 @@
     "prepublishOnly": "node ../../scripts/check-release-sync.mjs && node ../../scripts/check-published-manifests.mjs"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "3.7.3",
+    "@swarmvaultai/engine": "3.9.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {