agentsys 5.8.6 → 5.9.0

package/lib/repo-intel/queries.js

@@ -1,55 +1,37 @@
+'use strict';
+
 /**
- * Repo intel query functions
- *
  * Typed wrappers over `agent-analyzer repo-intel query <type>` subcommands.
- * Consumer plugins can call these instead of constructing CLI args by hand:
  *
- *   const { repoIntel } = require('@agentsys/lib');
- *   const hot = repoIntel.queries.hotspots(cwd, { limit: 20 });
+ * Each function constructs the exact argv expected by the binary, delegates to
+ * `binary.runAnalyzer`, parses the JSON output, and returns the result.
  *
- * Each function resolves the cached `repo-intel.json` via the platform
- * state-dir helper and shells out to the binary downloaded by lib/binary.
+ * All functions throw `RepoIntelMissingError` when the repo-intel map file
+ * has not been generated yet (run `agentsys repo-intel update` first).
  *
  * @module lib/repo-intel/queries
  */
 
-'use strict';
-
 const fs = require('fs');
 const path = require('path');
+const { getStateDir } = require('../platform/state-dir');
 const binary = require('../binary');
-const { getStateDirPath } = require('../platform/state-dir');
-
-const MAP_FILENAME = 'repo-intel.json';
 
-// Conservative bound on a single CLI argument length. Windows cmd-line max
-// is ~32 KB total; modern Linux/macOS typically allow ~128 KB. We throw an
-// actionable error rather than letting `execFileSync` fail with a cryptic
-// E2BIG/ENAMETOOLONG, which would otherwise look like a binary crash to
-// the caller.
-const MAX_FILES_ARG_LEN = 30000;
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
 
 /**
- * Absolute path to the cached repo-intel artifact for `basePath`.
- *
- * @param {string} basePath
- * @returns {string}
- */
-function mapFilePath(basePath) {
-  return path.join(getStateDirPath(basePath), MAP_FILENAME);
-}
-
-/**
- * Error thrown when the cached repo-intel artifact is missing.
- * Distinguished by a `.code = 'REPO_INTEL_MISSING'` field so callers can
- * choose between auto-init, fallback, or surfacing the message.
+ * Thrown when the repo-intel map file is absent.
  */
 class RepoIntelMissingError extends Error {
+  /**
+   * @param {string} mapFile - Expected path to the map file
+   */
   constructor(mapFile) {
     super(
-      `repo-intel artifact not found at ${mapFile}. Run ` +
-        '`agent-analyzer repo-intel init <path>` (or `/repo-intel init` ' +
-        'in a CC plugin) first to create it.'
+      `repo-intel map not found at ${mapFile}. ` +
+      'Run `agentsys repo-intel update` to generate it first.'
     );
     this.name = 'RepoIntelMissingError';
     this.code = 'REPO_INTEL_MISSING';
@@ -57,393 +39,260 @@ class RepoIntelMissingError extends Error {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+const MAP_FILE_NAME = 'repo-intel.json';
+
 /**
- * Run a binary query and return the parsed JSON result.
- *
- * @param {string} basePath - Repository root
- * @param {string[]} queryArgs - Arguments after `repo-intel query`
- * @returns {Object|Array} Parsed query result
- * @throws {RepoIntelMissingError} If the cached artifact is missing.
- * @throws {Error} If the binary fails or returns non-JSON output (with
- *   the failing query and an output preview included in the message).
+ * Resolve the map file path for a given project root.
+ * @param {string} cwd
+ * @returns {string}
  */
-function runQuery(basePath, queryArgs) {
-  const mapFile = mapFilePath(basePath);
+function resolveMapFile(cwd) {
+  const stateDir = getStateDir(cwd);
+  return path.join(cwd, stateDir, MAP_FILE_NAME);
+}
 
-  // Surface a clear "run init first" message instead of letting the binary
-  // exit non-zero with a low-level "no such file" error that would bubble
-  // up unannotated through `binary.runAnalyzer`.
+/**
+ * Assert the map file exists, throwing `RepoIntelMissingError` if not.
+ * @param {string} cwd
+ * @returns {string} resolved map file path
+ */
+function requireMapFile(cwd) {
+  const mapFile = resolveMapFile(cwd);
   if (!fs.existsSync(mapFile)) {
     throw new RepoIntelMissingError(mapFile);
   }
+  return mapFile;
+}
 
-  const args = ['repo-intel', 'query', ...queryArgs, '--map-file', mapFile, basePath];
-
-  let output;
+/**
+ * Run a repo-intel query and parse JSON output.
+ * @param {string} queryName - The subcommand name (e.g. 'hotspots')
+ * @param {string[]} extraArgs - Additional argv elements
+ * @param {string} cwd - Project root
+ * @returns {*} Parsed JSON result
+ */
+function runQuery(queryName, extraArgs, cwd) {
+  const mapFile = requireMapFile(cwd);
+  const args = ['repo-intel', 'query', queryName, ...extraArgs, '--map-file', mapFile, cwd];
+  let raw;
   try {
-    output = binary.runAnalyzer(args);
+    raw = binary.runAnalyzer(args);
   } catch (err) {
-    // Wrap so the caller learns which query failed without having to dig
-    // through the CLI argv. The original error stays as `cause`.
-    const wrapped = new Error(
-      `repo-intel query failed (${queryArgs.join(' ')}): ${err.message}`
+    throw new Error(
+      `repo-intel query failed [${queryName}]: ${err.message}`,
+      { cause: err }
     );
-    wrapped.cause = err;
-    throw wrapped;
   }
-
+  let parsed;
   try {
-    return JSON.parse(output);
-  } catch (err) {
-    const preview = output && output.length > 0 ? output.slice(0, 200) : '<empty>';
-    const wrapped = new Error(
-      `repo-intel query returned non-JSON output (${queryArgs.join(' ')}): ${preview}`
+    parsed = JSON.parse(raw);
+  } catch (_parseErr) {
+    const preview = raw.slice(0, 200);
+    throw new Error(
+      `repo-intel query [${queryName}] returned non-JSON output: ${preview}`
     );
-    wrapped.cause = err;
-    throw wrapped;
   }
+  return parsed;
 }
 
-// ─── Activity ───────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
+// Query functions
+// ---------------------------------------------------------------------------
 
 /**
- * Return files sorted by recency-weighted change score.
- *
- * @param {string} basePath
- * @param {Object} [options={}]
- * @param {number} [options.limit] - Maximum number of results
+ * Hotspot files by change frequency.
+ * @param {string} cwd
+ * @param {{ limit?: number }} [opts]
+ * @returns {Array}
  */
-function hotspots(basePath, options = {}) {
-  const args = ['hotspots'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
+function hotspots(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('hotspots', extra, cwd);
 }
 
 /**
- * Return least-changed files (no recent activity).
+ * Co-change coupling for a file.
+ * @param {string} cwd
+ * @param {string} file
+ * @param {{ limit?: number }} [opts]
+ * @returns {Array}
  */
-function coldspots(basePath, options = {}) {
-  const args = ['coldspots'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
+function coupling(cwd, file, opts = {}) {
+  const extra = [file];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('coupling', extra, cwd);
 }
 
 /**
- * Return change history for a specific file.
+ * Bus factor report.
+ * @param {string} cwd
+ * @param {{ adjustForAi?: boolean, limit?: number }} [opts]
+ * @returns {Object}
  */
-function fileHistory(basePath, file) {
-  return runQuery(basePath, ['file-history', file]);
+function busFactor(cwd, opts = {}) {
+  const extra = [];
+  if (opts.adjustForAi) extra.push('--adjust-for-ai');
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('bus-factor', extra, cwd);
 }
 
-// ─── Quality ────────────────────────────────────────────────────────────────
-
 /**
- * Return files with highest bug-fix density.
+ * Files with low test coverage relative to change frequency.
+ * @param {string} cwd
+ * @param {{ limit?: number, minChanges?: number }} [opts]
+ * @returns {Array}
  */
-function bugspots(basePath, options = {}) {
-  const args = ['bugspots'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
+function testGaps(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  if (opts.minChanges != null) extra.push('--min-changes', String(opts.minChanges));
+  return runQuery('test-gaps', extra, cwd);
 }
 
 /**
- * Return hot source files with no co-changing test file.
+ * AI-authored ratio per file or project.
+ * @param {string} cwd
+ * @param {{ pathFilter?: string }} [opts]
+ * @returns {Object}
  */
-function testGaps(basePath, options = {}) {
-  const args = ['test-gaps'];
-  if (options.limit) args.push('--top', String(options.limit));
-  if (options.minChanges) args.push('--min-changes', String(options.minChanges));
-  return runQuery(basePath, args);
+function aiRatio(cwd, opts = {}) {
+  const extra = [];
+  if (opts.pathFilter != null) extra.push('--path-filter', opts.pathFilter);
+  return runQuery('ai-ratio', extra, cwd);
 }
 
 /**
- * Score changed files by composite risk.
- *
- * Validates the joined file argument fits within the platform's argv length
- * cap before shelling out (Windows is the tight constraint at ~32 KB).
- * Callers with very large diffs should batch.
- *
- * @param {string} basePath
- * @param {string[]} files - List of changed file paths
- * @throws {TypeError} If `files` is not an array of strings.
- * @throws {RangeError} If the joined argument exceeds {@link MAX_FILES_ARG_LEN}.
+ * Risk score for a diff (set of changed files).
+ * @param {string} cwd
+ * @param {string[]} files
+ * @returns {Array}
  */
-function diffRisk(basePath, files) {
-  if (!Array.isArray(files) || !files.every((f) => typeof f === 'string')) {
-    throw new TypeError('diffRisk: `files` must be an array of strings');
+function diffRisk(cwd, files) {
+  if (!Array.isArray(files)) {
+    throw new TypeError('diffRisk: files must be an array of strings');
+  }
+  if (!files.every(f => typeof f === 'string')) {
+    throw new TypeError('diffRisk: all entries in files must be strings');
   }
   const joined = files.join(',');
-  if (joined.length > MAX_FILES_ARG_LEN) {
+  if (joined.length > 30000) {
     throw new RangeError(
-      `diffRisk: joined file argument is ${joined.length} chars, ` +
-        `exceeds platform-safe limit of ${MAX_FILES_ARG_LEN}. ` +
-        `Split the request into batches (~500 paths each is typically safe).`
+      `diffRisk: files argument exceeds 30000 character limit (got ${joined.length})`
     );
   }
-  return runQuery(basePath, ['diff-risk', '--files', joined]);
-}
-
-/**
- * Files ranked by hotspot × (1 + bug_rate) × (1 + complexity/30). Requires
- * Phase 2 AST data; falls back to git-only when unavailable.
- */
-function painspots(basePath, options = {}) {
-  const args = ['painspots'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
+  const extra = ['--files', joined];
+  return runQuery('diff-risk', extra, cwd);
 }
 
-// ─── People ─────────────────────────────────────────────────────────────────
-
 /**
- * Return ownership breakdown for a file or directory.
+ * Call-graph dependents of a symbol.
+ * @param {string} cwd
+ * @param {string} symbol
+ * @param {string} [file] - Scope to a specific file
+ * @returns {Object}
  */
-function ownership(basePath, file) {
-  return runQuery(basePath, ['ownership', file]);
+function dependents(cwd, symbol, file) {
+  const extra = [symbol];
+  if (file != null) extra.push('--file', file);
+  return runQuery('dependents', extra, cwd);
 }
 
 /**
- * Return contributors sorted by commit count.
+ * Bugspot risk scores.
+ * @param {string} cwd
+ * @param {{ limit?: number }} [opts]
+ * @returns {Array}
  */
-function contributors(basePath, options = {}) {
-  const args = ['contributors'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
+function bugspots(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('bugspots', extra, cwd);
 }
 
 /**
- * Detailed bus factor with critical owners and at-risk areas.
+ * Project health summary.
+ * @param {string} cwd
+ * @returns {Object}
  */
-function busFactor(basePath, options = {}) {
-  const args = ['bus-factor'];
-  if (options.adjustForAi) args.push('--adjust-for-ai');
-  return runQuery(basePath, args);
+function health(cwd) {
+  return runQuery('health', [], cwd);
 }
 
-// ─── Coupling ───────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
+// Graph queries (Phase 5.1 - agent-analyzer v0.4.0+)
+// ---------------------------------------------------------------------------
 
 /**
- * Files that frequently change together with `file`.
+ * Louvain-discovered file communities.
+ * @param {string} cwd
+ * @returns {Array}
  */
-function coupling(basePath, file) {
-  return runQuery(basePath, ['coupling', file]);
+function communities(cwd) {
+  return runQuery('communities', [], cwd);
 }
 
-// ─── Standards ──────────────────────────────────────────────────────────────
-
 /**
- * Project norms (commit conventions, etc.) detected from git history.
+ * Files bridging multiple communities (architectural seams).
+ * @param {string} cwd
+ * @param {{ limit?: number }} [opts]
+ * @returns {Array}
  */
-function norms(basePath) {
-  return runQuery(basePath, ['norms']);
+function boundaries(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('boundaries', extra, cwd);
 }
 
 /**
- * Commit message style + prefixes + scope usage.
+ * Which community a file belongs to.
+ * @param {string} cwd
+ * @param {string} file
+ * @returns {Object}
  */
-function conventions(basePath) {
-  return runQuery(basePath, ['conventions']);
+function areaOf(cwd, file) {
+  return runQuery('area-of', [file], cwd);
 }
 
-// ─── Health ─────────────────────────────────────────────────────────────────
-
 /**
- * Directory-level health overview.
+ * Composite health roll-up for a community.
+ * @param {string} cwd
+ * @param {number} id - Community id (non-negative integer)
+ * @returns {Object}
  */
-function areas(basePath) {
-  return runQuery(basePath, ['areas']);
-}
-
-/**
- * Repository-wide health summary.
- */
-function health(basePath) {
-  return runQuery(basePath, ['health']);
-}
-
-/**
- * Release cadence and tag history.
- */
-function releaseInfo(basePath) {
-  return runQuery(basePath, ['release-info']);
-}
-
-// ─── AI detection ───────────────────────────────────────────────────────────
-
-/**
- * AI vs human contribution ratio.
- */
-function aiRatio(basePath, options = {}) {
-  const args = ['ai-ratio'];
-  if (options.pathFilter) args.push('--path-filter', options.pathFilter);
-  return runQuery(basePath, args);
-}
-
-/**
- * Files with recent AI-authored changes.
- */
-function recentAi(basePath, options = {}) {
-  const args = ['recent-ai'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
-}
-
-// ─── Contributor guidance ───────────────────────────────────────────────────
-
-/**
- * Newcomer-oriented repo summary (tech stack, key areas, pain points).
- */
-function onboard(basePath) {
-  return runQuery(basePath, ['onboard']);
-}
-
-/**
- * Contribution guidance: good-first areas, test gaps, doc drift, bugspots.
- */
-function canIHelp(basePath) {
-  return runQuery(basePath, ['can-i-help']);
-}
-
-// ─── Documentation ──────────────────────────────────────────────────────────
-
-/**
- * Doc files with low code coupling (likely stale).
- */
-function docDrift(basePath, options = {}) {
-  const args = ['doc-drift'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
-}
-
-/**
- * Doc files with stale references to source symbols. Requires Phase 4
- * sync-check data.
- */
-function staleDocs(basePath, options = {}) {
-  const args = ['stale-docs'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
-}
-
-// ─── AST symbols ────────────────────────────────────────────────────────────
-
-/**
- * AST symbols (exports, imports, definitions) for a specific file. Requires
- * Phase 2 AST data.
- */
-function symbols(basePath, file) {
-  return runQuery(basePath, ['symbols', file]);
-}
-
-/**
- * Files that import a given symbol (reverse dependency lookup). Requires
- * Phase 2 AST data.
- */
-function dependents(basePath, symbol, file) {
-  const args = ['dependents', symbol];
-  if (file) args.push('--file', file);
-  return runQuery(basePath, args);
-}
-
-// ─── Phase 5: Graph-derived (analyzer-graph crate) ──────────────────────────
-
-/**
- * Communities discovered by Louvain modularity over the co-change graph.
- * Returns clusters of files that consistently change together - the natural
- * feature areas, independent of directory layout. Requires agent-analyzer
- * v0.4.0+.
- *
- * @param {string} basePath
- * @returns {Array<{id: number, size: number, files: string[]}>}
- */
-function communities(basePath) {
-  return runQuery(basePath, ['communities']);
-}
-
-/**
- * Files bridging multiple communities (high betweenness centrality). These
- * are the architectural seams - the highest-leverage files for refactoring
- * decisions. Requires agent-analyzer v0.4.0+.
- *
- * @param {string} basePath
- * @param {Object} [options={}]
- * @param {number} [options.limit] - Maximum number of results
- * @returns {Array<{path: string, betweenness: number, community: number|null}>}
- */
-function boundaries(basePath, options = {}) {
-  const args = ['boundaries'];
-  if (options.limit) args.push('--top', String(options.limit));
-  return runQuery(basePath, args);
-}
-
-/**
- * Look up which community a given file belongs to. Requires agent-analyzer
- * v0.4.0+.
- *
- * @param {string} basePath
- * @param {string} file - File path (relative to repo root)
- * @returns {{file: string, community: number|null, size: number|null}}
- */
-function areaOf(basePath, file) {
-  return runQuery(basePath, ['area-of', file]);
-}
-
-/**
- * Composite per-community health: total/recent changes, bug-fix rate,
- * AI ratio, stale-owner count. Use to identify communities under stress
- * (high bug rate or stale ownership). Requires agent-analyzer v0.4.0+.
- *
- * @param {string} basePath
- * @param {number} id - Community id (from `communities()`)
- * @returns {Object|null}
- */
-function communityHealth(basePath, id) {
-  if (!Number.isInteger(id) || id < 0) {
+function communityHealth(cwd, id) {
+  if (typeof id !== 'number' || !Number.isInteger(id) || id < 0) {
     throw new TypeError(
-      `communityHealth: \`id\` must be a non-negative integer, got: ${id} (${typeof id})`
+      'communityHealth: id must be a non-negative integer'
     );
   }
-  return runQuery(basePath, ['community-health', String(id)]);
+  return runQuery('community-health', [String(id)], cwd);
 }
 
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
 module.exports = {
-  // Errors
+  // Error class
   RepoIntelMissingError,
-  // Activity
+
+  // Core queries
   hotspots,
-  coldspots,
-  fileHistory,
-  // Quality
-  bugspots,
-  testGaps,
-  diffRisk,
-  painspots,
-  // People
-  ownership,
-  contributors,
-  busFactor,
-  // Coupling
   coupling,
-  // Standards
-  norms,
-  conventions,
-  // Health
-  areas,
-  health,
-  releaseInfo,
-  // AI detection
+  busFactor,
+  testGaps,
   aiRatio,
-  recentAi,
-  // Contributor guidance
-  onboard,
-  canIHelp,
-  // Documentation
-  docDrift,
-  staleDocs,
-  // AST symbols
-  symbols,
+  diffRisk,
   dependents,
-  // Phase 5: graph-derived
+  bugspots,
+  health,
+
+  // Graph queries
   communities,
   boundaries,
   areaOf,

package/lib/sources/policy-questions.js

@@ -6,7 +6,6 @@
  */
 
 const sourceCache = require('./source-cache');
-const { truncate } = require('../cross-platform');
 const customHandler = require('./custom-handler');
 
 /**
@@ -43,7 +42,7 @@ function getPolicyQuestions() {
     // Truncate to fit within 30 chars: "X (last used)" where X can be max 17 chars
     const maxBaseLen = 30 - ' (last used)'.length; // 18 chars for base
     const truncatedLabel = cachedLabel.length > maxBaseLen
-      ? truncate(cachedLabel, maxBaseLen - 1) + '…'
+      ? cachedLabel.substring(0, maxBaseLen - 1) + '…'
       : cachedLabel;
 
     sourceOptions.push({
@@ -156,12 +155,12 @@ function parseAndCachePolicy(responses) {
       // Validate and merge follow-up responses
       const rawNum = String(responses.project.number).trim();
       if (!/^[1-9][0-9]*$/.test(rawNum)) {
-        const safeNum = truncate(String(responses.project.number).replace(/[^\x20-\x7E]/g, '?'), 32);
+        const safeNum = String(responses.project.number).replace(/[^\x20-\x7E]/g, '?').substring(0, 32);
         throw new Error(`Invalid project number: "${safeNum}". Must be a positive integer.`);
       }
       const num = Number(rawNum);
       const owner = String(responses.project.owner || '').trim();
-      const safeOwner = truncate(String(responses.project.owner || '').replace(/[^\x20-\x7E]/g, '?'), 64);
+      const safeOwner = String(responses.project.owner || '').replace(/[^\x20-\x7E]/g, '?').substring(0, 64);
       if (!owner || !/^(@me|[a-zA-Z0-9][a-zA-Z0-9_-]*)$/.test(owner)) {
         throw new Error(`Invalid project owner: "${safeOwner}" (use @me or an org/user name)`);
       }