agentsys 5.14.0 → 6.0.0

package/lib/repo-intel/queries.js

@@ -99,6 +99,19 @@ function runQuery(queryName, extraArgs, cwd) {
   return parsed;
 }
 
+/**
+ * Assert a query argument is a non-empty string. Centralizes the validation
+ * that file/symbol/concept-taking queries share, so a wrong-typed arg fails
+ * with a clear message instead of being stringified into a bogus CLI argument.
+ * @param {*} val - the value to check
+ * @param {string} label - "<fn>: <arg>" for the error message
+ */
+function assertString(val, label) {
+  if (typeof val !== 'string' || val.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Query functions
 // ---------------------------------------------------------------------------
@@ -123,6 +136,7 @@ function hotspots(cwd, opts = {}) {
  * @returns {Array}
  */
 function coupling(cwd, file, opts = {}) {
+  assertString(file, 'coupling: file');
   const extra = [file];
   if (opts.limit != null) extra.push('--top', String(opts.limit));
   return runQuery('coupling', extra, cwd);
@@ -154,17 +168,6 @@ function testGaps(cwd, opts = {}) {
   return runQuery('test-gaps', extra, cwd);
 }
 
-/**
- * AI-authored ratio per file or project.
- * @param {string} cwd
- * @param {{ pathFilter?: string }} [opts]
- * @returns {Object}
- */
-function aiRatio(cwd, opts = {}) {
-  const extra = [];
-  if (opts.pathFilter != null) extra.push('--path-filter', opts.pathFilter);
-  return runQuery('ai-ratio', extra, cwd);
-}
 
 /**
  * Risk score for a diff (set of changed files).
@@ -197,8 +200,12 @@ function diffRisk(cwd, files) {
  * @returns {Object}
  */
 function dependents(cwd, symbol, file) {
+  assertString(symbol, 'dependents: symbol');
   const extra = [symbol];
-  if (file != null) extra.push('--file', file);
+  if (file != null) {
+    assertString(file, 'dependents: file');
+    extra.push('--file', file);
+  }
   return runQuery('dependents', extra, cwd);
 }
 
@@ -255,6 +262,7 @@ function boundaries(cwd, opts = {}) {
  * @returns {Object}
  */
 function areaOf(cwd, file) {
+  assertString(file, 'areaOf: file');
   return runQuery('area-of', [file], cwd);
 }
 
@@ -273,6 +281,171 @@ function communityHealth(cwd, id) {
   return runQuery('community-health', [String(id)], cwd);
 }
 
+// ---------------------------------------------------------------------------
+// Activity / git queries
+// ---------------------------------------------------------------------------
+
+/** Least-changed files (no recent activity). @param {string} cwd @param {{limit?:number}} [opts] */
+function coldspots(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('coldspots', extra, cwd);
+}
+
+/** Ownership for a file or directory. @param {string} cwd @param {string} file */
+function ownership(cwd, file) {
+  assertString(file, 'ownership: file');
+  return runQuery('ownership', [file], cwd);
+}
+
+/** Project norms detected from git history. @param {string} cwd */
+function norms(cwd) {
+  return runQuery('norms', [], cwd);
+}
+
+/** Area-level health overview. @param {string} cwd */
+function areas(cwd) {
+  return runQuery('areas', [], cwd);
+}
+
+/** Contributors sorted by commit count. @param {string} cwd @param {{limit?:number}} [opts] */
+function contributors(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('contributors', extra, cwd);
+}
+
+/** Release cadence and tag info. @param {string} cwd */
+function releaseInfo(cwd) {
+  return runQuery('release-info', [], cwd);
+}
+
+/** History for a specific file. @param {string} cwd @param {string} file */
+function fileHistory(cwd, file) {
+  assertString(file, 'fileHistory: file');
+  return runQuery('file-history', [file], cwd);
+}
+
+/** Commit message conventions. @param {string} cwd */
+function conventions(cwd) {
+  return runQuery('conventions', [], cwd);
+}
+
+/** Doc files with low code coupling (likely stale). @param {string} cwd @param {{limit?:number}} [opts] */
+function docDrift(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('doc-drift', extra, cwd);
+}
+
+// ---------------------------------------------------------------------------
+// Narrative / guidance queries
+// ---------------------------------------------------------------------------
+
+/** Newcomer-oriented repo summary. @param {string} cwd */
+function onboard(cwd) {
+  return runQuery('onboard', [], cwd);
+}
+
+/** Contributor guidance matching skills to areas needing work. @param {string} cwd */
+function canIHelp(cwd) {
+  return runQuery('can-i-help', [], cwd);
+}
+
+/** Files ranked by pain score (hotspot x complexity x bug density). @param {string} cwd @param {{limit?:number}} [opts] */
+function painspots(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('painspots', extra, cwd);
+}
+
+/** Every place execution can start (binaries, main fns, npm scripts). @param {string} cwd @param {{files?:string[]|string}} [opts] */
+function entryPoints(cwd, opts = {}) {
+  const extra = [];
+  if (opts.files) {
+    const list = Array.isArray(opts.files) ? opts.files.join(',') : String(opts.files);
+    extra.push('--files', list);
+  }
+  return runQuery('entry-points', extra, cwd);
+}
+
+/** Project metadata: languages, CI, license, README. @param {string} cwd */
+function projectInfo(cwd) {
+  return runQuery('project-info', [], cwd);
+}
+
+// ---------------------------------------------------------------------------
+// AST / symbol queries
+// ---------------------------------------------------------------------------
+
+/** AST symbols (exports/imports/definitions) for a file. @param {string} cwd @param {string} file */
+function symbols(cwd, file) {
+  assertString(file, 'symbols: file');
+  return runQuery('symbols', [file], cwd);
+}
+
+/** Doc files with stale references to source symbols. @param {string} cwd @param {{limit?:number}} [opts] */
+function staleDocs(cwd, opts = {}) {
+  const extra = [];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('stale-docs', extra, cwd);
+}
+
+/** Concept-to-file search (ranked, replaces grep -r). @param {string} cwd @param {string} query @param {{limit?:number}} [opts] */
+function find(cwd, query, opts = {}) {
+  assertString(query, 'find: query');
+  const extra = [query];
+  if (opts.limit != null) extra.push('--top', String(opts.limit));
+  return runQuery('find', extra, cwd);
+}
+
+// ---------------------------------------------------------------------------
+// Deslop-agent queries
+// ---------------------------------------------------------------------------
+
+/** Structured slop fix actions for the deslop agent. @param {string} cwd */
+function slopFixes(cwd) {
+  return runQuery('slop-fixes', [], cwd);
+}
+
+/** Ranked slop targets (Sonnet/Opus tiers). @param {string} cwd @param {{top?:number}} [opts] */
+function slopTargets(cwd, opts = {}) {
+  const extra = [];
+  if (opts.top != null) extra.push('--top', String(opts.top));
+  return runQuery('slop-targets', extra, cwd);
+}
+
+/**
+ * Cached 3-depth narrative summary. Returns null when not yet generated;
+ * with opts.depth returns that single depth as plain text. Bypasses the
+ * JSON-parse path because the binary emits the literal 'null' or raw text.
+ * @param {string} cwd @param {{depth?:1|3|10}} [opts]
+ */
+function summary(cwd, opts = {}) {
+  const mapFile = requireMapFile(cwd);
+  const extra = [];
+  if (opts.depth != null) extra.push('--depth', String(opts.depth));
+  const args = ['repo-intel', 'query', 'summary', ...extra, '--map-file', mapFile, cwd];
+  // summary bypasses runQuery (a single --depth returns plain text, not JSON),
+  // so it must wrap the analyzer call + parse itself to match runQuery's error
+  // contract instead of leaking a raw spawn / SyntaxError.
+  let raw;
+  try {
+    raw = binary.runAnalyzer(args).trim();
+  } catch (err) {
+    throw new Error(`repo-intel query failed [summary]: ${err.message}`, { cause: err });
+  }
+  if (raw === 'null') return null;
+  if (opts.depth != null) return raw; // plain-text single depth
+  try {
+    return JSON.parse(raw);
+  } catch (_parseErr) {
+    throw new Error(
+      `repo-intel query [summary] returned non-JSON output: ${raw.slice(0, 200)}`
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
@@ -286,7 +459,6 @@ module.exports = {
   coupling,
   busFactor,
   testGaps,
-  aiRatio,
   diffRisk,
   dependents,
   bugspots,
@@ -297,4 +469,32 @@ module.exports = {
   boundaries,
   areaOf,
   communityHealth,
+
+  // Activity / git queries
+  coldspots,
+  ownership,
+  norms,
+  areas,
+  contributors,
+  releaseInfo,
+  fileHistory,
+  conventions,
+  docDrift,
+
+  // Narrative / guidance queries
+  onboard,
+  canIHelp,
+  painspots,
+  entryPoints,
+  projectInfo,
+
+  // AST / symbol queries
+  symbols,
+  staleDocs,
+  find,
+
+  // Deslop-agent queries
+  slopFixes,
+  slopTargets,
+  summary,
 };

package/lib/repo-intel/updater.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * Repo map staleness checker.
+ *
+ * Determines whether a cached repo-map is stale relative to the current git HEAD.
+ * The incremental update path is handled by agent-analyzer (repo-intel update).
+ *
+ * @module lib/repo-intel/updater
+ */
+
+const { execFileSync } = require('child_process');
+
+const cache = require('./cache');
+
+/**
+ * Check whether the cached map is stale
+ * @param {string} basePath - Repository root path
+ * @param {Object} map - Cached repo map
+ * @returns {{isStale: boolean, reason: string|null, commitsBehind: number, suggestFullRebuild: boolean}}
+ */
+function checkStaleness(basePath, map) {
+  const result = {
+    isStale: false,
+    reason: null,
+    commitsBehind: 0,
+    suggestFullRebuild: false
+  };
+
+  if (!map?.git?.commit) {
+    result.isStale = true;
+    result.reason = 'Missing base commit in repo-map';
+    result.suggestFullRebuild = true;
+    return result;
+  }
+
+  if (cache.isMarkedStale(basePath)) {
+    result.isStale = true;
+    result.reason = 'Marked stale by hook';
+  }
+
+  if (!commitExists(basePath, map.git.commit)) {
+    result.isStale = true;
+    result.reason = 'Base commit no longer exists (rebased?)';
+    result.suggestFullRebuild = true;
+    return result;
+  }
+
+  const currentBranch = getCurrentBranch(basePath);
+  if (currentBranch && map.git.branch && currentBranch !== map.git.branch) {
+    result.isStale = true;
+    result.reason = `Branch changed from ${map.git.branch} to ${currentBranch}`;
+    result.suggestFullRebuild = true;
+  }
+
+  const commitsBehind = getCommitsBehind(basePath, map.git.commit);
+  if (commitsBehind > 0) {
+    result.isStale = true;
+    result.commitsBehind = commitsBehind;
+    if (!result.reason) {
+      result.reason = `${commitsBehind} commits behind HEAD`;
+    }
+  }
+
+  return result;
+}
+
+function isValidCommitHash(commit) {
+  return typeof commit === 'string' && /^[0-9a-fA-F]{4,40}$/.test(commit);
+}
+
+function commitExists(basePath, commit) {
+  if (!isValidCommitHash(commit)) return false;
+  try {
+    execFileSync('git', ['cat-file', '-e', commit], { cwd: basePath, stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getCurrentBranch(basePath) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: basePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function getCommitsBehind(basePath, commit) {
+  if (!isValidCommitHash(commit)) return 0;
+  try {
+    const out = execFileSync('git', ['rev-list', `${commit}..HEAD`, '--count'], {
+      cwd: basePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    return Number(out) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+module.exports = { checkStaleness };

package/lib/repo-map/index.js

@@ -1,265 +1,30 @@
 'use strict';
 
 /**
- * Repo Map - repository symbol mapping via agent-analyzer
+ * DEPRECATED COMPAT SHIM — repo-map folded into lib/repo-intel.
  *
- * Uses agent-analyzer for symbol extraction. The binary is auto-downloaded
- * on first use - no external tool installation required.
+ * repo-map was a leftover split: it produced/converted the artifact while
+ * lib/repo-intel/ only queried it. They are one pipeline over one binary, now
+ * unified under lib/repo-intel. This shim re-exports the lifecycle surface so
+ * existing `require('.../repo-map')` consumers keep working unchanged.
+ *
+ * Migrate callers to `require('.../repo-intel')` and remove this shim.
  *
  * @module lib/repo-map
+ * @deprecated use lib/repo-intel
  */
 
-const fs = require('fs');
-const path = require('path');
-const { execFileSync } = require('child_process');
-
-const installer = require('./installer');
-const cache = require('./cache');
-const updater = require('./updater');
-const converter = require('./converter');
-const binary = require('../binary');
-const { getStateDirPath } = require('../platform/state-dir');
-const { writeJsonAtomic } = require('../utils/atomic-write');
-
-const REPO_INTEL_FILENAME = 'repo-intel.json';
-
-function getIntelMapPath(basePath) {
-  return path.join(getStateDirPath(basePath), REPO_INTEL_FILENAME);
-}
-
-/**
- * Initialize a new repo map (full scan)
- * @param {string} basePath - Repository root path
- * @param {Object} options - Options
- * @param {boolean} options.force - Force rebuild even if map exists
- * @returns {Promise<{success: boolean, map?: Object, error?: string}>}
- */
-async function init(basePath, options = {}) {
-  const installed = await installer.checkInstalled();
-  if (!installed.found) {
-    return {
-      success: false,
-      error: 'agent-analyzer binary unavailable: ' + (installed.error || 'unknown error'),
-      installSuggestion: installer.getInstallInstructions()
-    };
-  }
-
-  const existing = cache.load(basePath);
-  if (existing && !options.force) {
-    return {
-      success: false,
-      error: 'Repo map already exists. Use --force to rebuild or /repo-map update to refresh.',
-      existing: cache.getStatus(basePath)
-    };
-  }
-
-  const startTime = Date.now();
-
-  let intelJson;
-  try {
-    intelJson = await binary.runAnalyzerAsync(['repo-intel', 'init', basePath]);
-  } catch (e) {
-    return {
-      success: false,
-      error: 'agent-analyzer repo-intel init failed: ' + e.message
-    };
-  }
-
-  let intel;
-  try {
-    intel = JSON.parse(intelJson);
-  } catch (e) {
-    return {
-      success: false,
-      error: 'Failed to parse repo-intel output: ' + e.message
-    };
-  }
-
-  // Persist repo-intel.json for future incremental updates
-  const intelPath = getIntelMapPath(basePath);
-  try {
-    writeJsonAtomic(intelPath, intel);
-  } catch {
-    // Non-fatal: update() will fall back to full init
-  }
-
-  const map = converter.convertIntelToRepoMap(intel);
-  map.stats.scanDurationMs = Date.now() - startTime;
-  cache.save(basePath, map);
-
-  return {
-    success: true,
-    map,
-    summary: {
-      files: Object.keys(map.files).length,
-      symbols: map.stats.totalSymbols,
-      languages: map.project.languages,
-      duration: map.stats.scanDurationMs
-    }
-  };
-}
-
-/**
- * Update an existing repo map (incremental via agent-analyzer)
- * @param {string} basePath - Repository root path
- * @param {Object} options - Options
- * @param {boolean} options.full - Force full rebuild instead of incremental
- * @returns {Promise<{success: boolean, summary?: Object, error?: string}>}
- */
-async function update(basePath, options = {}) {
-  const installed = await installer.checkInstalled();
-  if (!installed.found) {
-    return {
-      success: false,
-      error: 'agent-analyzer binary unavailable: ' + (installed.error || 'unknown error'),
-      installSuggestion: installer.getInstallInstructions()
-    };
-  }
-
-  if (!cache.exists(basePath)) {
-    return {
-      success: false,
-      error: 'No repo map found. Run /repo-map init first.'
-    };
-  }
-
-  if (options.full) {
-    return init(basePath, { force: true });
-  }
-
-  const intelPath = getIntelMapPath(basePath);
-  if (!fs.existsSync(intelPath)) {
-    return init(basePath, { force: true });
-  }
-
-  const startTime = Date.now();
-
-  let intelJson;
-  try {
-    intelJson = await binary.runAnalyzerAsync([
-      'repo-intel', 'update',
-      '--map-file', intelPath,
-      basePath
-    ]);
-  } catch (e) {
-    return {
-      success: false,
-      error: 'agent-analyzer repo-intel update failed: ' + e.message
-    };
-  }
-
-  let intel;
-  try {
-    intel = JSON.parse(intelJson);
-  } catch (e) {
-    return {
-      success: false,
-      error: 'Failed to parse repo-intel update output: ' + e.message
-    };
-  }
-
-  try {
-    writeJsonAtomic(intelPath, intel);
-  } catch {
-    // Non-fatal
-  }
-
-  const map = converter.convertIntelToRepoMap(intel);
-  map.stats.scanDurationMs = Date.now() - startTime;
-  cache.save(basePath, map);
-
-  return {
-    success: true,
-    map,
-    summary: {
-      files: Object.keys(map.files).length,
-      symbols: map.stats.totalSymbols,
-      duration: map.stats.scanDurationMs
-    }
-  };
-}
-
-/**
- * Get repo map status
- * @param {string} basePath - Repository root path
- * @returns {{exists: boolean, status?: Object}}
- */
-function status(basePath) {
-  const map = cache.load(basePath);
-  if (!map) {
-    return { exists: false };
-  }
-
-  const staleness = updater.checkStaleness(basePath, map);
-
-  let branch;
-  try {
-    branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: basePath, encoding: 'utf8' }).trim();
-  } catch {
-    // Non-fatal
-  }
-
-  return {
-    exists: true,
-    status: {
-      generated: map.generated,
-      updated: map.updated,
-      commit: map.git?.commit,
-      branch,
-      files: Object.keys(map.files).length,
-      symbols: map.stats?.totalSymbols || 0,
-      languages: map.project?.languages || [],
-      staleness
-    }
-  };
-}
-
-/**
- * Load repo map (if exists)
- * @param {string} basePath - Repository root path
- * @returns {Object|null}
- */
-function load(basePath) {
-  return cache.load(basePath);
-}
-
-/**
- * Check if repo map exists
- * @param {string} basePath - Repository root path
- * @returns {boolean}
- */
-function exists(basePath) {
-  return cache.exists(basePath);
-}
-
-/**
- * Check if agent-analyzer is available (compat alias for checkInstalled).
- * Previously checked ast-grep; now checks agent-analyzer.
- * @returns {Promise<{found: boolean, version?: string, tool: string}>}
- */
-async function checkAstGrepInstalled() {
-  return installer.checkInstalled();
-}
-
-/**
- * Get install instructions (compat alias).
- * @returns {string}
- */
-function getInstallInstructions() {
-  return installer.getInstallInstructions();
-}
+const repoIntel = require('../repo-intel');
 
 module.exports = {
-  init,
-  update,
-  status,
-  load,
-  exists,
-  checkAstGrepInstalled,
-  getInstallInstructions,
-
-  // Re-export submodules for advanced usage
-  installer,
-  cache,
-  updater
+  init: repoIntel.init,
+  update: repoIntel.update,
+  status: repoIntel.status,
+  load: repoIntel.load,
+  exists: repoIntel.exists,
+  checkAstGrepInstalled: repoIntel.checkAstGrepInstalled,
+  getInstallInstructions: repoIntel.getInstallInstructions,
+  installer: repoIntel.installer,
+  cache: repoIntel.cache,
+  updater: repoIntel.updater
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.14.0",
+  "version": "6.0.0",
   "description": "A modular runtime and orchestration system for AI agents - works with Claude Code, OpenCode, and Codex CLI",
   "main": "lib/platform/detect-platform.js",
   "type": "commonjs",