ctxman 3.1.0 → 3.2.7

package/lib/why/index.js

@@ -2,17 +2,18 @@
  * ctxman why - "why is the code like this?" context from local git history
  *
  * For a file, a symbol (`file:symbol`) or a line range (`file#L10-L40`) this collects the
- * commits that shaped it, the issues / tickets / URLs those commits reference, blame
- * ownership, files that change together with it, docs / ADRs / changelog entries / code
- * comments that mention it, TODO-style notes inside it and the tests that reference it,
- * and renders all of it as one document for an LLM (or a person). Everything comes from
- * the repository itself: no network access.
+ * commits that shaped it, the issues / tickets / URLs those commits reference (and
+ * optionally their GitHub / GitLab issue, PR & MR discussions when `discussions: true`),
+ * blame ownership, files that change together with it, docs / ADRs / changelog entries /
+ * code comments that mention it, TODO-style notes inside it and the tests that reference
+ * it, and renders all of it as one document for an LLM (or a person). Offline by default.
  */
 
 import fs from 'fs';
 import path from 'path';
 import { isValidGitRef } from '../integrations/git/GitClient.js';
 import { redactSecrets, formatRedactionSummary } from '../utils/secret-redactor.js';
+import { resolveWorkspaceRepos } from '../workspace/index.js';
 import { WhyError } from './errors.js';
 import {
   findRepositoryRoot,
@@ -35,32 +36,58 @@ import {
 } from './target.js';
 import { collectHistory, funcnamePattern } from './history.js';
 import { mineReferences, parseRemote, referencesOf } from './references.js';
+import {
+  fetchDiscussions,
+  DEFAULT_MAX_DISCUSSIONS,
+  DEFAULT_MAX_COMMENTS,
+  DEFAULT_DISCUSSION_TIMEOUT_MS,
+} from './discussions.js';
 import { collectOwnership } from './ownership.js';
 import { collectCoupling } from './coupling.js';
 import { findNotes, searchRelated } from './search.js';
 import { STYLES, renderWithinBudget } from './render.js';
+import { queryAnalyzerCitations, resolveAnalyzerDbPath } from './analyzer-bridge.js';
 
-export { WhyError, findRepositoryRoot, parseTargetSpec, parseRemote, mineReferences };
+export {
+  WhyError,
+  queryAnalyzerCitations,
+  findRepositoryRoot,
+  parseTargetSpec,
+  parseRemote,
+  mineReferences,
+  fetchDiscussions,
+};
 
 const DEFAULTS = {
   limit: 20,
   since: null,
   rev: null,
   patches: false,
+  discussions: false,
+  maxDiscussions: DEFAULT_MAX_DISCUSSIONS,
+  maxComments: DEFAULT_MAX_COMMENTS,
+  discussionTimeoutMs: DEFAULT_DISCUSSION_TIMEOUT_MS,
+  token: null,
+  fetch: null,
+  env: null,
   couplingWindow: 500,
   couplingTop: 10,
   maxFilesPerCommit: 50,
   maxRelated: 20,
   maxTests: 10,
   style: 'markdown',
+  analyzerDb: null,
+  analyzer: false,
   budget: null,
   ask: null,
   redact: true,
   cwd: null,
+  repos: null,
 };
 
 const MAX_NOTES = 50;
 const NEVER_COMMITTED = 'the file is staged but has never been committed';
+const RELATED_KIND_ORDER = { adr: 0, changelog: 1, doc: 2, comment: 3 };
 
 // File names too common to search for on their own: `index.js` becomes `cart/index.js`
 const GENERIC_STEMS = new Set([
@@ -112,6 +139,14 @@ function normalizeOptions(options) {
   }
 
   opts.limit = integerOption('limit', opts.limit, 1, 10000);
+  opts.maxDiscussions = integerOption('maxDiscussions', opts.maxDiscussions, 0, 100);
+  opts.maxComments = integerOption('maxComments', opts.maxComments, 0, 50);
+  opts.discussionTimeoutMs = integerOption(
+    'discussionTimeoutMs',
+    opts.discussionTimeoutMs,
+    100,
+    60000
+  );
   opts.couplingWindow = integerOption('couplingWindow', opts.couplingWindow, 0, 100000);
   opts.couplingTop = integerOption('couplingTop', opts.couplingTop, 1, 1000);
   opts.maxFilesPerCommit = integerOption('maxFilesPerCommit', opts.maxFilesPerCommit, 1, 100000);
@@ -122,12 +157,15 @@ function normalizeOptions(options) {
   if (!STYLES.includes(opts.style)) {
     throw new WhyError(
       'INVALID_OPTION',
-      `style must be one of ${STYLES.join(', ')} (got ${JSON.stringify(opts.style)})`
+      `style must be one of ${STYLES.join(', ')}(got ${JSON.stringify(opts.style)})`.replace(
+        ')(',
+        ') ('
+      )
     );
   }
   if (opts.since !== null) {
     const since = String(opts.since).trim();
-    if (!since || since.length > 100 || since.startsWith('-') || !/^[\w .:+\-/,]+$/.test(since)) {
+    if (!since || since.length > 100 || since.startsWith('-') || !/^[\w .:+/\-,]+$/.test(since)) {
       throw new WhyError('INVALID_OPTION', `Invalid --since date: ${JSON.stringify(opts.since)}`);
     }
     opts.since = since;
@@ -139,6 +177,7 @@ function normalizeOptions(options) {
     opts.ask = String(opts.ask).trim() || null;
   }
   opts.patches = Boolean(opts.patches);
+  opts.discussions = Boolean(opts.discussions);
   opts.redact = opts.redact !== false;
   return opts;
 }
@@ -210,13 +249,17 @@ function objectTarget(target) {
 /**
  * The project, its repository and the rules that apply to it
  */
-function openProject(root, opts) {
+function openProject(root, opts, { checkRev = true } = {}) {
   if (typeof root !== 'string' || !fs.statSync(root, { throwIfNoEntry: false })?.isDirectory()) {
     throw new WhyError('ROOT_NOT_FOUND', `Project root is not a directory: ${root}`);
   }
   const projectRoot = fs.realpathSync(root);
   const top = findRepositoryRoot(projectRoot);
-  if (opts.rev && !tryGit(top, ['rev-parse', '--verify', '--quiet', `${opts.rev}^{commit}`])) {
+  if (
+    checkRev &&
+    opts.rev &&
+    !tryGit(top, ['rev-parse', '--verify', '--quiet', `${opts.rev}^{commit}`])
+  ) {
     throw new WhyError('UNKNOWN_REF', `Unknown revision: ${opts.rev}`);
   }
   const info = readRepositoryInfo(top);
@@ -238,6 +281,126 @@ function openProject(root, opts) {
   };
 }
 
+function isGitWorkTree(dir) {
+  try {
+    return Boolean(findRepositoryRoot(dir));
+  } catch {
+    return false;
+  }
+}
+
+function buildWorkspaceRepoInputs(primaryRoot, extraRepos) {
+  const realPrimary = fs.existsSync(primaryRoot)
+    ? fs.realpathSync(primaryRoot)
+    : path.resolve(primaryRoot);
+  const isContainerOfExtra = extraRepos.some((item) => {
+    const raw = typeof item === 'string' ? item : item?.path;
+    if (typeof raw !== 'string' || !raw.trim()) return false;
+    const resolved = path.resolve(raw);
+    const real = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
+    return real !== realPrimary && real.startsWith(realPrimary + path.sep);
+  });
+  if (isContainerOfExtra || !isGitWorkTree(realPrimary)) {
+    return [...extraRepos];
+  }
+  return [primaryRoot, ...extraRepos];
+}
+
+function resolveWorkspaceWhyTarget(workspaceRepos, target, opts) {
+  const repoByAlias = new Map(workspaceRepos.map((r) => [r.alias, r]));
+  const realCwd =
+    opts.cwd && fs.existsSync(opts.cwd)
+      ? fs.realpathSync(opts.cwd)
+      : opts.cwd
+        ? path.resolve(opts.cwd)
+        : null;
+  const cwdRepo = realCwd
+    ? workspaceRepos.find(
+        (r) => realCwd === r.realRoot || realCwd.startsWith(r.realRoot + path.sep)
+      )
+    : null;
+
+  // 1. Check explicit `<alias>/<rest>` prefix
+  if (typeof target === 'string') {
+    const posix = target.replace(/\\/g, '/').replace(/^\/+/, '');
+    const slashIdx = posix.indexOf('/');
+    if (slashIdx > 0) {
+      const alias = posix.slice(0, slashIdx);
+      const rest = posix.slice(slashIdx + 1);
+      const matched = repoByAlias.get(alias);
+      if (matched && rest) {
+        matched.project.base = matched.project.projectRoot;
+        return { targetRepo: matched, innerTarget: rest };
+      }
+    }
+  } else if (target && typeof target === 'object' && typeof target.file === 'string') {
+    const posix = target.file.replace(/\\/g, '/').replace(/^\/+/, '');
+    const slashIdx = posix.indexOf('/');
+    if (slashIdx > 0) {
+      const alias = posix.slice(0, slashIdx);
+      const rest = posix.slice(slashIdx + 1);
+      const matched = repoByAlias.get(alias);
+      if (matched && rest) {
+        matched.project.base = matched.project.projectRoot;
+        return { targetRepo: matched, innerTarget: { ...target, file: rest } };
+      }
+    }
+  }
+
+  // 2. Unprefixed target: check cwdRepo first (if cwd is inside a workspace repo), then each repo
+  const ordered = cwdRepo
+    ? [cwdRepo, ...workspaceRepos.filter((r) => r.alias !== cwdRepo.alias)]
+    : workspaceRepos;
+
+  const hasCandidateInRepo = (repo, useCwdBase) => {
+    const base = useCwdBase ? realCwd : repo.project.projectRoot;
+    try {
+      const spec =
+        typeof target === 'string'
+          ? parseTargetSpec(target, (file) =>
+              Boolean(fs.statSync(path.resolve(base, file), { throwIfNoEntry: false })?.isFile())
+            )
+          : objectTarget(target);
+      const located = resolveInsideRoot(repo.project.projectRoot, base, spec.file, {
+        mustExist: false,
+      });
+      const gitPath = toGitPath(path.relative(repo.project.top, located.absolute));
+      if (opts.rev) {
+        return (
+          tryGit(repo.project.top, ['cat-file', '-t', `${opts.rev}:${gitPath}`])?.trim() === 'blob'
+        );
+      }
+      if (fs.statSync(located.absolute, { throwIfNoEntry: false })?.isFile()) {
+        return true;
+      }
+      const deleted = tryGit(repo.project.top, [
+        'log',
+        '-n',
+        '1',
+        '--format=%h',
+        '--',
+        literal(gitPath),
+      ])?.trim();
+      return Boolean(deleted);
+    } catch {
+      return false;
+    }
+  };
+
+  for (const repo of ordered) {
+    const useCwdBase = Boolean(cwdRepo && repo.alias === cwdRepo.alias);
+    if (hasCandidateInRepo(repo, useCwdBase)) {
+      repo.project.base = useCwdBase ? realCwd : repo.project.projectRoot;
+      return { targetRepo: repo, innerTarget: target };
+    }
+  }
+
+  const fallback = cwdRepo ?? workspaceRepos[0];
+  fallback.project.base =
+    cwdRepo && fallback.alias === cwdRepo.alias ? realCwd : fallback.project.projectRoot;
+  return { targetRepo: fallback, innerTarget: target };
+}
+
 /**
  * Point a missing file at the commit that removed (or renamed) it, if history has one
  * @param {object} project
@@ -579,12 +742,19 @@ function couplingSection(project, file, opts) {
  *   inside it; its .gitignore / .contextignore / .contextinclude apply
  * @param {string|{file: string, symbol?: string, startLine?: number, endLine?: number}} target
  *   `file`, `file:symbol` (function, method, class; `Class.method` too), `file#L10-L40`
- *   or `file:10-40`
+ *   or `file:10-40` (or `<alias>/<file>...` when `options.repos` is set)
  * @param {object} [options]
  * @param {number} [options.limit=20] - Commits to include
  * @param {string} [options.since] - Only commits after this date (git date syntax)
  * @param {string} [options.rev] - Explain the code as of this revision instead of the work tree
  * @param {boolean} [options.patches=false] - Include each commit's diff of the target
+ * @param {boolean} [options.discussions=false] - Fetch referenced GitHub/GitLab issue/PR/MR discussions
+ * @param {number} [options.maxDiscussions=10] - Maximum remote discussions fetched
+ * @param {number} [options.maxComments=5] - Maximum comments fetched per discussion
+ * @param {number} [options.discussionTimeoutMs=5000] - Per-request timeout (ms)
+ * @param {string} [options.token] - Explicit GitHub/GitLab API token override
+ * @param {typeof globalThis.fetch} [options.fetch] - Injectable fetch implementation
+ * @param {NodeJS.ProcessEnv} [options.env] - Environment override for token lookup
  * @param {number} [options.couplingWindow=500] - Commits of the file examined for co-changes (0 = off)
  * @param {number} [options.couplingTop=10] - Co-changed files listed
  * @param {number} [options.maxFilesPerCommit=50] - Larger commits are ignored for coupling
@@ -595,21 +765,98 @@ function couplingSection(project, file, opts) {
  * @param {string} [options.ask] - Question appended at the end of the document
  * @param {boolean} [options.redact=true] - Mask secrets (lib/utils/secret-redactor.js)
  * @param {string} [options.cwd] - Directory relative target paths start from (default: root)
+ * @param {Array<string|{path: string, alias?: string}>} [options.repos] - Additional workspace repositories
  * @returns {Promise<{text: string, style: string, tokens: number, budget: number|null,
- *   omitted: Record<string, number>, warnings: string[], data: object}>}
+ *   omitted: Record<string, number>, warnings: string[], data: object, repos?: Array<{alias: string, root: string}>}>}
  */
 export async function explainHistory(root, target, options = {}) {
   const opts = normalizeOptions(options);
-  const project = openProject(root, opts);
-  const file = readTarget(project, target);
+  const isWorkspace = Array.isArray(options.repos) && options.repos.length > 0;
+
+  let project;
+  let effectiveTarget = target;
+  let workspaceRepos = null;
+  let targetRepo = null;
+
+  if (isWorkspace) {
+    if (typeof root !== 'string' || !fs.statSync(root, { throwIfNoEntry: false })?.isDirectory()) {
+      throw new WhyError('ROOT_NOT_FOUND', `Project root is not a directory: ${root}`);
+    }
+    let resolvedRepos;
+    try {
+      resolvedRepos = resolveWorkspaceRepos(
+        buildWorkspaceRepoInputs(path.resolve(root), options.repos)
+      );
+    } catch (error) {
+      if (error instanceof WhyError) throw error;
+      throw new WhyError('ROOT_NOT_FOUND', error.message);
+    }
+
+    if (!opts.redact) {
+      const requiringRepo = resolvedRepos.find((r) => r.policy?.requireRedaction);
+      if (requiringRepo) {
+        throw new WhyError(
+          'POLICY_DENIED',
+          `Secret redaction is required by export policy in ${requiringRepo.alias} (--no-redact is refused)`
+        );
+      }
+    }
+
+    workspaceRepos = resolvedRepos.map((repo) => ({
+      ...repo,
+      project: openProject(repo.realRoot, { ...opts, cwd: null }, { checkRev: false }),
+    }));
+
+    const resolved = resolveWorkspaceWhyTarget(workspaceRepos, target, opts);
+    targetRepo = resolved.targetRepo;
+    effectiveTarget = resolved.innerTarget;
+    project = targetRepo.project;
+
+    if (
+      opts.rev &&
+      !tryGit(project.top, ['rev-parse', '--verify', '--quiet', `${opts.rev}^{commit}`])
+    ) {
+      throw new WhyError('UNKNOWN_REF', `Unknown revision: ${opts.rev}`);
+    }
+  } else {
+    project = openProject(root, opts);
+  }
+
+  const file = readTarget(project, effectiveTarget);
   const selection = selectLines(project, file);
   const { wholeFile, range, symbol } = selection;
   const { spec, relPath, lines, totalLines, contentOmitted } = file;
+  const displayTargetPath = isWorkspace ? `${targetRepo.alias}/${relPath}` : relPath;
 
   const history = historySection(project, file, selection, opts);
   const references = mineReferences(history.commits, project.remote);
   for (const commit of history.commits) commit.refs = referencesOf(references, commit.shortSha);
 
+  let discussions = [];
+  if (opts.discussions) {
+    const fetched = await fetchDiscussions(references.issues, project.remote, {
+      maxDiscussions: opts.maxDiscussions,
+      maxComments: opts.maxComments,
+      timeoutMs: opts.discussionTimeoutMs,
+      token: opts.token ?? undefined,
+      env: opts.env ?? undefined,
+      fetch: opts.fetch ?? undefined,
+    });
+    discussions = fetched.discussions;
+    project.warnings.push(...fetched.warnings);
+  }
+
+  let institutionalCitations = [];
+  if (opts.analyzerDb || opts.analyzer || resolveAnalyzerDbPath(project.projectRoot) !== null) {
+    const dbPath = opts.analyzerDb || project.projectRoot;
+    institutionalCitations = queryAnalyzerCitations(dbPath, {
+      file: relPath,
+      symbol: spec.symbol,
+      commits: history.commits.map((c) => c.sha),
+      redact: opts.redact,
+    });
+  }
+
   // Blame of the current lines
   const covered = wholeFile || range !== null;
   let ownership = null;
@@ -623,7 +870,16 @@ export async function explainHistory(root, target, options = {}) {
     if (!ownership) project.warnings.push('git blame failed; ownership not available.');
   }
 
-  const coupling = history.reason === NEVER_COMMITTED ? null : couplingSection(project, file, opts);
+  let coupling = history.reason === NEVER_COMMITTED ? null : couplingSection(project, file, opts);
+  if (isWorkspace && coupling) {
+    coupling = {
+      ...coupling,
+      files: coupling.files.map((entry) => ({
+        ...entry,
+        path: `${targetRepo.alias}/${entry.path}`,
+      })),
+    };
+  }
 
   // Definitions inside a line range double as search terms
   const symbolsInRange =
@@ -637,19 +893,67 @@ export async function explainHistory(root, target, options = {}) {
         ].slice(0, 10)
       : [];
 
-  // Docs, comments and tests that mention the target (work tree)
+  // Docs, comments and tests that mention the target (work tree across all workspace repos)
   const member = spec.symbol ? spec.symbol.split(/\.|::|#/).pop() : null;
-  const found = searchRelated(project.projectRoot, {
-    ...searchTerms(relPath, member ? [member] : symbolsInRange.slice(0, 3)),
-    target: {
-      path: relPath,
-      startLine: range ? range.startLine : null,
-      endLine: range ? range.endLine : null,
-    },
-    isExcluded: project.isExcluded,
-    maxRelated: opts.maxRelated,
-    maxTests: opts.maxTests,
-  });
+  const terms = searchTerms(relPath, member ? [member] : symbolsInRange.slice(0, 3));
+
+  let relatedList;
+  let testList;
+  if (isWorkspace) {
+    const mergedRelated = [];
+    const mergedTests = [];
+    for (const repo of workspaceRepos) {
+      const isTargetRepo = repo.alias === targetRepo.alias;
+      const repoFound = searchRelated(repo.project.projectRoot, {
+        ...terms,
+        target: isTargetRepo
+          ? {
+              path: relPath,
+              startLine: range ? range.startLine : null,
+              endLine: range ? range.endLine : null,
+            }
+          : { path: '\0__other_repo__', startLine: null, endLine: null },
+        isExcluded: repo.project.isExcluded,
+        maxRelated: opts.maxRelated,
+        maxTests: opts.maxTests,
+      });
+      for (const item of repoFound.related) {
+        mergedRelated.push({ ...item, path: `${repo.alias}/${item.path}` });
+      }
+      for (const testItem of repoFound.tests) {
+        mergedTests.push({ ...testItem, path: `${repo.alias}/${testItem.path}` });
+      }
+    }
+    mergedRelated.sort(
+      (a, b) =>
+        RELATED_KIND_ORDER[a.kind] - RELATED_KIND_ORDER[b.kind] ||
+        (a.mentions === 'symbol' ? 0 : 1) - (b.mentions === 'symbol' ? 0 : 1) ||
+        a.path.localeCompare(b.path) ||
+        a.line - b.line
+    );
+    mergedTests.sort(
+      (a, b) =>
+        (a.references === 'symbol' ? 0 : 1) - (b.references === 'symbol' ? 0 : 1) ||
+        b.totalMatches - a.totalMatches ||
+        a.path.localeCompare(b.path)
+    );
+    relatedList = mergedRelated.slice(0, opts.maxRelated);
+    testList = mergedTests.slice(0, opts.maxTests);
+  } else {
+    const found = searchRelated(project.projectRoot, {
+      ...terms,
+      target: {
+        path: relPath,
+        startLine: range ? range.startLine : null,
+        endLine: range ? range.endLine : null,
+      },
+      isExcluded: project.isExcluded,
+      maxRelated: opts.maxRelated,
+      maxTests: opts.maxTests,
+    });
+    relatedList = found.related;
+    testList = found.tests;
+  }
 
   const shown = !contentOmitted && covered;
   const first = range?.startLine ?? 1;
@@ -661,9 +965,14 @@ export async function explainHistory(root, target, options = {}) {
   }
 
   const { info, remote, rev } = project;
+  const reposMeta = isWorkspace
+    ? workspaceRepos.map(({ alias, root: repoRoot }) => ({ alias, root: repoRoot }))
+    : undefined;
+
   let data = {
+    ...(reposMeta ? { repos: reposMeta } : {}),
     target: {
-      path: relPath,
+      path: displayTargetPath,
       symbol: spec.symbol ?? null,
       kind: symbol?.kind ?? null,
       line: symbol?.line ?? null,
@@ -686,11 +995,13 @@ export async function explainHistory(root, target, options = {}) {
     },
     history,
     references,
+    discussions,
+    institutionalCitations,
     ownership,
     coupling,
-    related: found.related,
+    related: relatedList,
     notes,
-    tests: found.tests,
+    tests: testList,
     warnings: project.warnings,
     question: opts.ask,
   };
@@ -706,7 +1017,22 @@ export async function explainHistory(root, target, options = {}) {
   }
 
   const rendered = renderWithinBudget(data, { style: opts.style, budget: opts.budget });
+
+  if (isWorkspace) {
+    for (const repo of workspaceRepos) {
+      if (repo.policy?.maxExportTokens !== null && repo.policy?.maxExportTokens !== undefined) {
+        if (rendered.tokens > repo.policy.maxExportTokens) {
+          throw new WhyError(
+            'POLICY_DENIED',
+            `Export of ${rendered.tokens} tokens exceeds maxExportTokens (${repo.policy.maxExportTokens}) in ${repo.alias}`
+          );
+        }
+      }
+    }
+  }
+
   return {
+    ...(reposMeta ? { repos: reposMeta } : {}),
     text: rendered.text,
     style: opts.style,
     tokens: rendered.tokens,