sdtk-wiki-kit 0.2.0 → 0.2.2

package/src/lib/update.js

@@ -0,0 +1,217 @@
+"use strict";
+
+const { spawn } = require("child_process");
+const path = require("path");
+const { parseFlags } = require("./args");
+const { CliError, ValidationError } = require("./errors");
+
+const PACKAGE_NAME = "sdtk-wiki-kit";
+const PRODUCT_NAME = "SDTK-WIKI";
+const NPM_BIN = process.platform === "win32" ? "npm.cmd" : "npm";
+const NPM_DISPLAY = "npm";
+const NPM_VIEW_ARGS = ["view", PACKAGE_NAME, "version"];
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+const FLAG_DEFS = {
+  version: { type: "string" },
+  "project-path": { type: "string" },
+  "check-only": { type: "boolean" },
+  "skip-project-files": { type: "boolean" },
+  verbose: { type: "boolean" },
+};
+const pkg = require("../../package.json");
+
+let commandExecutor = defaultCommandExecutor;
+
+function defaultCommandExecutor(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      env: options.env || process.env,
+      shell: options.shell || false,
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdout += text;
+      if (options.verbose) process.stdout.write(text);
+    });
+    child.stderr.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderr += text;
+      if (options.verbose) process.stderr.write(text);
+    });
+    child.on("error", (error) => {
+      if (error && error.code === "ENOENT") {
+        reject(new CliError(`Required command not found in PATH: ${command}`));
+        return;
+      }
+      reject(error);
+    });
+    child.on("close", (exitCode) => {
+      resolve({ exitCode: typeof exitCode === "number" ? exitCode : 1, stdout, stderr });
+    });
+  });
+}
+
+function setCommandExecutorForTests(executor) {
+  commandExecutor = executor || defaultCommandExecutor;
+}
+
+function resetCommandExecutorForTests() {
+  commandExecutor = defaultCommandExecutor;
+}
+
+function quote(value) {
+  const text = String(value);
+  return /[\s"]/u.test(text) ? JSON.stringify(text) : text;
+}
+
+function formatCommand(command, args) {
+  return [command, ...args].map((value) => quote(value)).join(" ");
+}
+
+function validateVersion(targetVersion) {
+  if (targetVersion !== "latest" && !VERSION_PATTERN.test(targetVersion)) {
+    throw new ValidationError(`Invalid value for --version: "${targetVersion}". Must be "latest" or x.y.z.`);
+  }
+}
+
+function extractResolvedVersion(stdout) {
+  const lines = String(stdout || "")
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const candidate = (lines[lines.length - 1] || "").replace(/^['"]|['"]$/gu, "");
+  if (!VERSION_PATTERN.test(candidate)) {
+    throw new CliError(`npm registry lookup returned an invalid version for ${PACKAGE_NAME}: "${candidate || "<empty>"}"`);
+  }
+  return candidate;
+}
+
+async function resolveTargetVersion(options) {
+  if (options.requestedVersion !== "latest") {
+    return options.requestedVersion;
+  }
+
+  let result;
+  try {
+    result = await commandExecutor(NPM_BIN, NPM_VIEW_ARGS, {
+      verbose: options.verbose,
+      shell: process.platform === "win32",
+    });
+  } catch (error) {
+    throw new CliError(`npm registry lookup failed for ${PACKAGE_NAME} while resolving --version latest.\n${error.message}`, error.exitCode || 4);
+  }
+
+  if (result.exitCode !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw new CliError(`npm registry lookup failed for ${PACKAGE_NAME} while resolving --version latest (exit code ${result.exitCode}).${detail ? `\n${detail}` : ""}`);
+  }
+
+  try {
+    return extractResolvedVersion(result.stdout);
+  } catch (error) {
+    throw new CliError(`npm registry lookup failed for ${PACKAGE_NAME} while resolving --version latest.\n${error.message}`, error.exitCode || 4);
+  }
+}
+
+function buildPlan(options) {
+  const npmArgs = ["install", "-g", `${PACKAGE_NAME}@${options.targetVersion}`];
+  return {
+    installedVersion: pkg.version,
+    requestedVersion: options.requestedVersion,
+    targetVersion: options.targetVersion,
+    updateNeeded: pkg.version !== options.targetVersion,
+    npmArgs,
+    npmCommand: formatCommand(NPM_DISPLAY, npmArgs),
+    projectPath: options.projectPath,
+    checkOnly: options.checkOnly,
+    skipProjectFiles: options.skipProjectFiles,
+    projectRefreshCommand: options.skipProjectFiles
+      ? "skipped (--skip-project-files)"
+      : "skipped (R1 package-only update; project files are never mutated)",
+    runtimeRefreshCommand: "skipped (no runtime asset update in R1)",
+  };
+}
+
+function parseUpdateOptions(args) {
+  const { flags, positional } = parseFlags(args || [], FLAG_DEFS);
+
+  if (positional.length > 0) {
+    throw new ValidationError(`Unexpected arguments: ${positional.join(" ")}`);
+  }
+
+  const requestedVersion = flags.version || "latest";
+  validateVersion(requestedVersion);
+
+  return {
+    requestedVersion,
+    projectPath: path.resolve(flags["project-path"] || process.cwd()),
+    checkOnly: Boolean(flags["check-only"]),
+    skipProjectFiles: Boolean(flags["skip-project-files"]),
+    verbose: Boolean(flags.verbose),
+  };
+}
+
+function printPlan(plan) {
+  console.log(`${PRODUCT_NAME} update plan`);
+  console.log(`  Installed package version: ${plan.installedVersion}`);
+  console.log(`  Requested package version: ${plan.requestedVersion}`);
+  console.log(`  Target package version:    ${plan.targetVersion}`);
+  console.log(`  Package update needed:     ${plan.updateNeeded ? "yes" : `no (already installed: ${plan.installedVersion})`}`);
+  console.log(`  Package refresh command:   ${plan.npmCommand}`);
+  console.log(`  Project path:              ${plan.projectPath}`);
+  console.log(`  Project file refresh:      ${plan.projectRefreshCommand}`);
+  console.log(`  Runtime asset refresh:     ${plan.runtimeRefreshCommand}`);
+  console.log(`  Mode:                      ${plan.checkOnly ? "check-only (no changes applied)" : "apply"}`);
+}
+
+async function runCommand(label, command, args, options) {
+  const result = await commandExecutor(command, args, options);
+  if (result.exitCode !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw new CliError(`${label} failed (exit code ${result.exitCode}).${detail ? `\n${detail}` : ""}`);
+  }
+  return result;
+}
+
+async function applyPlan(plan, options) {
+  console.log("");
+  console.log(`Applying ${PRODUCT_NAME} update...`);
+  console.log(`  npm refresh: ${plan.npmCommand}`);
+  await runCommand("npm package refresh", NPM_BIN, plan.npmArgs, {
+    verbose: options.verbose,
+    shell: process.platform === "win32",
+  });
+  console.log(`  project refresh: ${plan.projectRefreshCommand}`);
+  console.log(`  runtime refresh: ${plan.runtimeRefreshCommand}`);
+  console.log("");
+  console.log(`${PRODUCT_NAME} update completed successfully.`);
+}
+
+async function executeUpdate(args) {
+  const options = parseUpdateOptions(args);
+  const targetVersion = await resolveTargetVersion(options);
+  const plan = buildPlan({ ...options, targetVersion });
+  printPlan(plan);
+
+  if (options.checkOnly) {
+    return 0;
+  }
+
+  await applyPlan(plan, options);
+  return 0;
+}
+
+module.exports = {
+  buildPlan,
+  executeUpdate,
+  formatCommand,
+  parseUpdateOptions,
+  resetCommandExecutorForTests,
+  resolveTargetVersion,
+  setCommandExecutorForTests,
+};

package/src/lib/wiki-ask.js

@@ -9,6 +9,11 @@ const { loadWikiAskHandler } = require("./wiki-premium-loader");
 const INDEX_FILE = "SDTK_DOC_INDEX.json";
 const GRAPH_FILE = "SDTK_DOC_GRAPH.json";
 const DEFAULT_MAX_SOURCES = 6;
+// BK-269 hyperedge-aware context expansion (--source filter only).
+// Mirrors run_doc_atlas_server.py so both grounding surfaces behave identically.
+const DEFAULT_MAX_HYPEREDGE_EXPANSION = 6;
+const DEFAULT_MIN_HYPEREDGE_CO_MEMBERSHIP = 1;
+const DEFAULT_MAX_FAMILY_HYPEREDGE_CONTRIB = 3;
 
 function readJsonFile(filePath, label) {
   try {
@@ -69,28 +74,251 @@ function extractDocumentText(document) {
   return "";
 }
 
-function buildSources(index, sourceFilters, maxSources) {
+function docId(document) {
+  return document.id || extractDocumentPath(document);
+}
+
+function docFacetKeys(document) {
+  const keys = [];
+  const groups = [
+    ["issue", document.issues],
+    ["knowledge", document.knowledge_ids],
+    ["skill", document.skill_refs],
+    ["lane", document.lane_refs],
+  ];
+  for (const [namespace, values] of groups) {
+    if (!Array.isArray(values)) {
+      continue;
+    }
+    for (const value of values) {
+      const text = String(value == null ? "" : value).trim();
+      if (text) {
+        keys.push(`${namespace}:${text}`);
+      }
+    }
+  }
+  const family = String(document.family == null ? "" : document.family).trim();
+  if (family) {
+    keys.push(`family:${family}`);
+  }
+  return keys;
+}
+
+// Invert shared reference facets into hyperedges (groups with >=2 docs). Pure and
+// deterministic; mirrors _derive_hyperedges in run_doc_atlas_server.py.
+function deriveHyperedges(documents) {
+  const facetToDocs = new Map();
+  for (const document of documents) {
+    if (!document || typeof document !== "object") {
+      continue;
+    }
+    const id = docId(document);
+    if (!id) {
+      continue;
+    }
+    for (const facetKey of docFacetKeys(document)) {
+      let members = facetToDocs.get(facetKey);
+      if (!members) {
+        members = [];
+        facetToDocs.set(facetKey, members);
+      }
+      if (!members.includes(id)) {
+        members.push(id);
+      }
+    }
+  }
+  const hyperedges = new Map();
+  for (const [facet, ids] of facetToDocs) {
+    if (ids.length >= 2) {
+      hyperedges.set(facet, ids.slice().sort());
+    }
+  }
+  const docHyperedges = new Map();
+  for (const [facet, ids] of hyperedges) {
+    for (const id of ids) {
+      let facets = docHyperedges.get(id);
+      if (!facets) {
+        facets = new Set();
+        docHyperedges.set(id, facets);
+      }
+      facets.add(facet);
+    }
+  }
+  return { hyperedges, docHyperedges };
+}
+
+function computeNodeDegree(graph, docIdSet) {
+  const degree = new Map();
+  const edges = graph && Array.isArray(graph.edges) ? graph.edges : [];
+  for (const edge of edges) {
+    const source = edge && edge.source;
+    const target = edge && edge.target;
+    if (docIdSet.has(source) && docIdSet.has(target)) {
+      degree.set(source, (degree.get(source) || 0) + 1);
+      degree.set(target, (degree.get(target) || 0) + 1);
+    }
+  }
+  return degree;
+}
+
+// Bounded hyperedge co-member expansion. Returns ranked expansion entries
+// ({ id, facets, relation }). Mirrors _expand_via_hyperedges in the Python server:
+// shared-facet-count desc -> node_degree desc -> title/id lexical, with a family cap.
+function expandSourcesViaHyperedges(seedIds, derived, nodeDegree, docsById, options) {
+  const opts = options || {};
+  const maxExpansion = Number.isInteger(opts.maxExpansion)
+    ? opts.maxExpansion
+    : DEFAULT_MAX_HYPEREDGE_EXPANSION;
+  const minCoMembership = Number.isInteger(opts.minCoMembership)
+    ? opts.minCoMembership
+    : DEFAULT_MIN_HYPEREDGE_CO_MEMBERSHIP;
+  const familyCap = Number.isInteger(opts.familyCap)
+    ? opts.familyCap
+    : DEFAULT_MAX_FAMILY_HYPEREDGE_CONTRIB;
+  if (maxExpansion <= 0) {
+    return [];
+  }
+  const seedSet = new Set(seedIds);
+  const seedFacets = new Set();
+  for (const seedId of seedIds) {
+    const facets = derived.docHyperedges.get(seedId);
+    if (facets) {
+      for (const facet of facets) {
+        seedFacets.add(facet);
+      }
+    }
+  }
+  if (seedFacets.size === 0) {
+    return [];
+  }
+  const candidateFacets = new Map();
+  for (const facet of seedFacets) {
+    const members = derived.hyperedges.get(facet) || [];
+    for (const id of members) {
+      if (seedSet.has(id)) {
+        continue;
+      }
+      let facets = candidateFacets.get(id);
+      if (!facets) {
+        facets = new Set();
+        candidateFacets.set(id, facets);
+      }
+      facets.add(facet);
+    }
+  }
+  const candidates = [];
+  for (const [id, facets] of candidateFacets) {
+    if (facets.size >= minCoMembership) {
+      candidates.push({ id, facets });
+    }
+  }
+  candidates.sort((a, b) => {
+    if (b.facets.size !== a.facets.size) {
+      return b.facets.size - a.facets.size;
+    }
+    const degreeDelta = (nodeDegree.get(b.id) || 0) - (nodeDegree.get(a.id) || 0);
+    if (degreeDelta !== 0) {
+      return degreeDelta;
+    }
+    const titleA = String((docsById.get(a.id) || {}).title || a.id).toLowerCase();
+    const titleB = String((docsById.get(b.id) || {}).title || b.id).toLowerCase();
+    if (titleA !== titleB) {
+      return titleA < titleB ? -1 : 1;
+    }
+    const idA = a.id.toLowerCase();
+    const idB = b.id.toLowerCase();
+    if (idA !== idB) {
+      return idA < idB ? -1 : 1;
+    }
+    return 0;
+  });
+  const selected = [];
+  let familyOnlyAdmitted = 0;
+  for (const candidate of candidates) {
+    if (selected.length >= maxExpansion) {
+      break;
+    }
+    let hasNonFamily = false;
+    for (const facet of candidate.facets) {
+      if (!facet.startsWith("family:")) {
+        hasNonFamily = true;
+        break;
+      }
+    }
+    if (!hasNonFamily) {
+      // OQ-C: cap how many docs can enter via a family facet alone.
+      if (familyOnlyAdmitted >= familyCap) {
+        continue;
+      }
+      familyOnlyAdmitted += 1;
+    }
+    const sortedFacets = Array.from(candidate.facets).sort();
+    selected.push({
+      id: candidate.id,
+      facets: sortedFacets,
+      relation: `shares ${sortedFacets.join(", ")}`,
+    });
+  }
+  return selected;
+}
+
+function buildSources(index, sourceFilters, maxSources, graph) {
   const documents = Array.isArray(index.documents) ? index.documents : [];
   const filters = (sourceFilters || []).map((item) => item.trim()).filter(Boolean);
   const limit = Number.isInteger(maxSources) && maxSources > 0 ? maxSources : DEFAULT_MAX_SOURCES;
 
-  return documents
-    .map((document) => {
-      const sourcePath = extractDocumentPath(document);
-      return {
-        id: document.id || sourcePath,
-        path: sourcePath,
-        title: document.title || sourcePath,
-        text: extractDocumentText(document),
-      };
-    })
-    .filter((source) => {
-      if (filters.length === 0) {
-        return true;
-      }
-      return filters.some((filter) => source.id === filter || source.path === filter);
-    })
-    .slice(0, limit);
+  const mapped = documents.map((document) => {
+    const sourcePath = extractDocumentPath(document);
+    return {
+      id: document.id || sourcePath,
+      path: sourcePath,
+      title: document.title || sourcePath,
+      text: extractDocumentText(document),
+      relation: "primary",
+    };
+  });
+
+  // No explicit --source filter: ground on all docs, unchanged (no expansion).
+  if (filters.length === 0) {
+    return mapped.slice(0, limit);
+  }
+
+  const primaries = mapped.filter((source) =>
+    filters.some((filter) => source.id === filter || source.path === filter)
+  );
+
+  // BK-269: append the filtered docs' hyperedge co-members (capped, labelled),
+  // so `--source <doc>` also grounds on its directly-related siblings.
+  const sourceById = new Map(mapped.map((source) => [source.id, source]));
+  const docsById = new Map();
+  for (const document of documents) {
+    if (!document || typeof document !== "object") {
+      continue;
+    }
+    const id = docId(document);
+    if (id && !docsById.has(id)) {
+      docsById.set(id, document);
+    }
+  }
+  const derived = deriveHyperedges(documents);
+  const nodeDegree = computeNodeDegree(graph, new Set(docsById.keys()));
+  const seedIds = primaries.map((source) => source.id);
+  const expansion = expandSourcesViaHyperedges(seedIds, derived, nodeDegree, docsById, {});
+
+  const result = primaries.slice();
+  const seen = new Set(seedIds);
+  for (const item of expansion) {
+    if (seen.has(item.id)) {
+      continue;
+    }
+    const base = sourceById.get(item.id);
+    if (!base) {
+      continue;
+    }
+    seen.add(item.id);
+    result.push({ ...base, relation: item.relation });
+  }
+  return result.slice(0, limit);
 }
 
 function normalizeCitations(citations) {
@@ -126,6 +354,7 @@ function normalizeAskResult(rawResult, context) {
     citations: normalizeCitations(result.citations),
     confidence: result.confidence,
     graphPath: context.graphPath,
+    expandedDocCount: Number.isInteger(context.expandedDocCount) ? context.expandedDocCount : 0,
   };
 }
 
@@ -139,7 +368,10 @@ async function runWikiAsk(options) {
   const graphInfo = assertWikiGraphReady(projectPath);
   const index = readJsonFile(graphInfo.indexPath, INDEX_FILE);
   const graph = readJsonFile(graphInfo.graphFilePath, GRAPH_FILE);
-  const sources = buildSources(index, options.sources, options.maxSources);
+  const sources = buildSources(index, options.sources, options.maxSources, graph);
+  const expandedDocCount = sources.filter(
+    (source) => source.relation && source.relation !== "primary"
+  ).length;
 
   const handlerState = await loadWikiAskHandler();
   if (!handlerState.ok) {
@@ -155,6 +387,7 @@ async function runWikiAsk(options) {
     graphFilePath: graphInfo.graphFilePath,
     graph,
     sources,
+    expandedDocCount,
     maxSources: options.maxSources,
   };
 
@@ -170,6 +403,8 @@ async function runWikiAsk(options) {
 
 module.exports = {
   buildSources,
+  deriveHyperedges,
+  expandSourcesViaHyperedges,
   normalizeAskResult,
   runWikiAsk,
 };

package/src/lib/wiki-config.js

@@ -71,7 +71,9 @@ function resolveWikiConfig(flags = {}) {
   ) {
     scanRoots = persisted.scanRoots.map((r) => path.resolve(r));
   } else {
-    scanRoots = [projectPath];
+    const docsDir = path.join(projectPath, "docs");
+    const hasDocsDir = fs.existsSync(docsDir) && fs.statSync(docsDir).isDirectory();
+    scanRoots = [hasDocsDir ? docsDir : projectPath];
   }
 
   const excludes =