ctxman 3.1.1 → 3.2.8

package/lib/why/analyzer-bridge.js

@@ -0,0 +1,223 @@
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { redactSecrets } from '../utils/secret-redactor.js';
+
+const require = createRequire(import.meta.url);
+let cachedDatabaseSync = null;
+
+function getDatabaseSync() {
+  if (cachedDatabaseSync) return cachedDatabaseSync;
+  const origEmitWarning = process.emitWarning;
+  process.emitWarning = function (warning, ...args) {
+    const msg = typeof warning === 'string' ? warning : warning?.message || '';
+    if (/SQLite is an experimental feature/i.test(msg)) return;
+    return origEmitWarning.call(this, warning, ...args);
+  };
+  try {
+    ({ DatabaseSync: cachedDatabaseSync } = require('node:sqlite'));
+    return cachedDatabaseSync;
+  } finally {
+    process.emitWarning = origEmitWarning;
+  }
+}
+
+export const DEFAULT_ANALYZER_DB_REL = path.join('.plansmith', 'analyzer.sqlite');
+
+/**
+ * Resolves the path to the analyzer SQLite database.
+ * @param {string} rootOrDbPath
+ * @returns {string|null} Absolute path to analyzer.sqlite, or null if not found
+ */
+export function resolveAnalyzerDbPath(rootOrDbPath) {
+  if (!rootOrDbPath) return null;
+  const p = path.resolve(rootOrDbPath);
+  if (p.endsWith('.sqlite') || p.endsWith('.db')) {
+    return fs.existsSync(p) ? p : null;
+  }
+  const candidate = path.join(p, DEFAULT_ANALYZER_DB_REL);
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+/**
+ * Extracts a concise snippet from the document body centered around the match term.
+ */
+function extractSnippet(body, term, maxChars = 240) {
+  if (!body) return '';
+  if (!term) return body.slice(0, maxChars);
+
+  const idx = body.toLowerCase().indexOf(term.toLowerCase());
+  if (idx === -1) {
+    return body.slice(0, maxChars).trim();
+  }
+
+  const start = Math.max(0, idx - 60);
+  const end = Math.min(body.length, idx + term.length + 140);
+  let snippet = body.slice(start, end).replace(/\s+/g, ' ').trim();
+  if (start > 0) snippet = `...${snippet}`;
+  if (end < body.length) snippet = `${snippet}...`;
+  return snippet;
+}
+
+/**
+ * Query @plansmithai/analyzer's SQLite documents table for matching institutional citations
+ * (commits, PRs, issues, Slack, Linear, Jira, incidents, architectural docs).
+ *
+ * @param {string} rootOrDbPath - Path to analyzer.sqlite or project root directory
+ * @param {Object} [options]
+ * @param {string} [options.file] - Target file relative path
+ * @param {string} [options.symbol] - Target symbol name
+ * @param {string[]} [options.commits] - Commit SHAs from history
+ * @param {number} [options.limit=10] - Max citations to return
+ * @param {boolean} [options.redact=true] - Redact secrets
+ * @returns {Array<{
+ *   id: string,
+ *   kind: string,
+ *   title: string,
+ *   snippet: string,
+ *   url: string|null,
+ *   author: string|null,
+ *   timestamp: string|null,
+ *   refs: string[],
+ *   score: number
+ * }>}
+ */
+export function queryAnalyzerCitations(rootOrDbPath, options = {}) {
+  const dbPath = resolveAnalyzerDbPath(rootOrDbPath);
+  if (!dbPath) return [];
+
+  const file = options.file ? String(options.file).trim() : null;
+  const symbol = options.symbol ? String(options.symbol).trim() : null;
+  const commits = Array.isArray(options.commits) ? options.commits : [];
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 10;
+  const redact = options.redact !== false;
+
+  let db = null;
+  try {
+    const DatabaseSync = getDatabaseSync();
+    db = new DatabaseSync(dbPath, { open: true, readOnly: true });
+
+    // Check if documents table exists
+    const tableCheck = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='documents'")
+      .get();
+    if (!tableCheck) {
+      db.close();
+      return [];
+    }
+
+    const rows = db
+      .prepare('SELECT id, kind, title, body, path, url, author, timestamp, refs FROM documents')
+      .all();
+    const scored = [];
+
+    const fileBase = file ? path.basename(file) : null;
+    const searchTerms = [file, fileBase, symbol, ...commits].filter(Boolean);
+
+    for (const r of rows) {
+      let score = 0;
+      let matchedTerm = null;
+
+      const rPath = r.path ? String(r.path) : '';
+      const rTitle = r.title ? String(r.title) : '';
+      const rBody = r.body ? String(r.body) : '';
+      const rRefs = r.refs ? String(r.refs) : '';
+
+      // Check path match
+      if (
+        file &&
+        (rPath === file ||
+          rPath.endsWith(`/${file}`) ||
+          (fileBase && rPath.endsWith(`/${fileBase}`)))
+      ) {
+        score = Math.max(score, 1.0);
+        matchedTerm = file;
+      }
+
+      // Check refs match
+      for (const c of commits) {
+        if (c && rRefs.includes(c)) {
+          score = Math.max(score, 0.95);
+          matchedTerm = c;
+          break;
+        }
+      }
+
+      if (file && rRefs.includes(file)) {
+        score = Math.max(score, 0.9);
+        matchedTerm = file;
+      }
+
+      // Check symbol match
+      if (symbol) {
+        if (rTitle.includes(symbol)) {
+          score = Math.max(score, 0.85);
+          matchedTerm = symbol;
+        } else if (rBody.includes(symbol)) {
+          score = Math.max(score, 0.7);
+          matchedTerm = symbol;
+        }
+      }
+
+      // Check general text search
+      if (score === 0) {
+        for (const term of searchTerms) {
+          if (rTitle.toLowerCase().includes(term.toLowerCase())) {
+            score = Math.max(score, 0.6);
+            matchedTerm = term;
+            break;
+          }
+          if (rBody.toLowerCase().includes(term.toLowerCase())) {
+            score = Math.max(score, 0.4);
+            matchedTerm = term;
+            break;
+          }
+        }
+      }
+
+      if (score > 0) {
+        let title = rTitle;
+        let snippet = extractSnippet(rBody, matchedTerm);
+
+        if (redact) {
+          title = redactSecrets(title).text;
+          snippet = redactSecrets(snippet).text;
+        }
+
+        let parsedRefs = [];
+        try {
+          parsedRefs = JSON.parse(rRefs);
+        } catch {
+          parsedRefs = [];
+        }
+
+        scored.push({
+          id: r.id,
+          kind: r.kind,
+          title,
+          snippet,
+          url: r.url ?? null,
+          author: r.author ?? null,
+          timestamp: r.timestamp ?? null,
+          refs: parsedRefs,
+          score,
+        });
+      }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit);
+  } catch (_err) {
+    return [];
+  } finally {
+    if (db) {
+      try {
+        db.close();
+      } catch {
+        // ignore close errors
+      }
+    }
+  }
+}
+
+export default queryAnalyzerCitations;

package/lib/why/discussions.js

@@ -0,0 +1,314 @@
+/**
+ * Remote issue / pull-request / merge-request discussions enrichment for `ctxman why --discussions`
+ *
+ * Opt-in only (`discussions: true`). Fetches titles, states, descriptions, labels, and top
+ * comments from GitHub (REST v3, including GitHub Enterprise) or GitLab (REST v4, including
+ * self-hosted instances) for references mined from commit history.
+ *
+ * Network failures, missing tokens, 404s, and rate limits never abort `explainHistory()`:
+ * they are recorded as human-readable warnings while local git history still renders.
+ */
+
+export const DEFAULT_MAX_DISCUSSIONS = 10;
+export const DEFAULT_MAX_COMMENTS = 5;
+export const DEFAULT_DISCUSSION_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_BODY_CHARS = 2000;
+const DEFAULT_MAX_COMMENT_CHARS = 800;
+
+function truncateText(text, maxChars) {
+  if (!text || typeof text !== 'string') return '';
+  const normalized = text.replace(/\r\n/g, '\n').trim();
+  if (normalized.length <= maxChars) return normalized;
+  return `${normalized.slice(0, maxChars).trimEnd()}…`;
+}
+
+async function fetchJson(fetchFn, url, headers, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchFn(url, {
+      method: 'GET',
+      headers,
+      signal: controller.signal,
+    });
+    let payload = null;
+    if (response.ok) {
+      payload = await response.json();
+    }
+    return { ok: response.ok, status: response.status, headers: response.headers, data: payload };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function githubApiBase(host) {
+  return host === 'github.com' ? 'https://api.github.com' : `https://${host}/api/v3`;
+}
+
+function gitlabApiBase(host) {
+  return `https://${host}/api/v4`;
+}
+
+function resolveAuthToken(provider, options) {
+  if (options.token) return String(options.token).trim();
+  const env = options.env ?? process.env;
+  if (provider === 'github') {
+    return (env.GITHUB_TOKEN || env.GH_TOKEN || '').trim() || null;
+  }
+  if (provider === 'gitlab') {
+    return (env.GITLAB_TOKEN || env.GL_TOKEN || '').trim() || null;
+  }
+  return null;
+}
+
+async function fetchGitHubDiscussion(issue, remote, ctx) {
+  const repoPath = issue.repo || remote.repoPath;
+  const base = githubApiBase(remote.host);
+  const issueUrl = `${base}/repos/${repoPath}/issues/${issue.number}`;
+  const res = await fetchJson(ctx.fetchFn, issueUrl, ctx.headers, ctx.timeoutMs);
+
+  if (!res.ok) {
+    if (res.status === 401 || res.status === 403 || res.status === 429) {
+      const authHint = ctx.hasToken
+        ? ''
+        : ' (set GITHUB_TOKEN or GH_TOKEN for private repositories and higher rate limits)';
+      return {
+        rateLimited: res.status === 403 || res.status === 429,
+        warning: `GitHub API returned HTTP ${res.status} for ${issue.id}${authHint}.`,
+      };
+    }
+    if (res.status === 404) {
+      return { warning: `Discussion ${issue.id} was not found on GitHub (HTTP 404).` };
+    }
+    return { warning: `GitHub API returned HTTP ${res.status} for ${issue.id}.` };
+  }
+
+  const item = res.data ?? {};
+  const isPr = Boolean(item.pull_request) || issue.kind === 'pr';
+  const merged = Boolean(item.pull_request?.merged_at);
+  const state = merged ? 'merged' : String(item.state || 'unknown');
+  const labels = Array.isArray(item.labels)
+    ? item.labels.map((label) => (typeof label === 'string' ? label : label?.name)).filter(Boolean)
+    : [];
+
+  const comments = [];
+  const remoteCommentCount = typeof item.comments === 'number' ? item.comments : 1;
+  if (ctx.maxComments > 0 && remoteCommentCount > 0) {
+    const commentsUrl = `${issueUrl}/comments?per_page=${ctx.maxComments}`;
+    try {
+      const commentsRes = await fetchJson(ctx.fetchFn, commentsUrl, ctx.headers, ctx.timeoutMs);
+      if (commentsRes.ok && Array.isArray(commentsRes.data)) {
+        for (const comment of commentsRes.data.slice(0, ctx.maxComments)) {
+          const body = truncateText(comment?.body, ctx.maxCommentChars);
+          if (!body) continue;
+          comments.push({
+            author: String(comment?.user?.login || 'unknown'),
+            createdAt: comment?.created_at || null,
+            body,
+          });
+        }
+      }
+    } catch (_err) {
+      // Non-fatal: keep main issue/PR discussion even if comments endpoint times out
+    }
+  }
+
+  return {
+    discussion: {
+      id: issue.id,
+      number: issue.number,
+      repo: repoPath,
+      provider: 'github',
+      kind: isPr ? 'pr' : 'issue',
+      title: String(item.title || ''),
+      state,
+      author: String(item.user?.login || 'unknown'),
+      createdAt: item.created_at || null,
+      url: item.html_url || issue.url || null,
+      labels,
+      body: truncateText(item.body, ctx.maxBodyChars),
+      commits: issue.commits ?? [],
+      comments,
+    },
+  };
+}
+
+async function fetchGitLabDiscussion(issue, remote, ctx) {
+  const repoPath = issue.repo || remote.repoPath;
+  const encodedRepo = encodeURIComponent(repoPath);
+  const base = gitlabApiBase(remote.host);
+
+  const resourceOrder =
+    issue.kind === 'mr' ? ['merge_requests', 'issues'] : ['issues', 'merge_requests'];
+
+  let chosenResource = null;
+  let res = null;
+  for (const resource of resourceOrder) {
+    const candidateUrl = `${base}/projects/${encodedRepo}/${resource}/${issue.number}`;
+    res = await fetchJson(ctx.fetchFn, candidateUrl, ctx.headers, ctx.timeoutMs);
+    if (res.ok) {
+      chosenResource = resource;
+      break;
+    }
+    // Only try fallback resource on 404 when kind wasn't explicitly mr
+    if (res.status !== 404 || issue.kind === 'mr') break;
+  }
+
+  if (!res?.ok || !chosenResource) {
+    const status = res?.status ?? 'error';
+    if (status === 401 || status === 403 || status === 429) {
+      const authHint = ctx.hasToken
+        ? ''
+        : ' (set GITLAB_TOKEN for private projects and higher rate limits)';
+      return {
+        rateLimited: status === 429,
+        warning: `GitLab API returned HTTP ${status} for ${issue.id}${authHint}.`,
+      };
+    }
+    if (status === 404) {
+      return { warning: `Discussion ${issue.id} was not found on GitLab (HTTP 404).` };
+    }
+    return { warning: `GitLab API returned HTTP ${status} for ${issue.id}.` };
+  }
+
+  const item = res.data ?? {};
+  const isMr = chosenResource === 'merge_requests';
+  const labels = Array.isArray(item.labels)
+    ? item.labels.map((label) => (typeof label === 'string' ? label : label?.name)).filter(Boolean)
+    : [];
+
+  const comments = [];
+  if (ctx.maxComments > 0) {
+    const notesUrl = `${base}/projects/${encodedRepo}/${chosenResource}/${issue.number}/notes?sort=asc&per_page=${ctx.maxComments * 2}`;
+    try {
+      const notesRes = await fetchJson(ctx.fetchFn, notesUrl, ctx.headers, ctx.timeoutMs);
+      if (notesRes.ok && Array.isArray(notesRes.data)) {
+        for (const note of notesRes.data) {
+          if (note?.system) continue;
+          const body = truncateText(note?.body, ctx.maxCommentChars);
+          if (!body) continue;
+          comments.push({
+            author: String(note?.author?.username || note?.author?.name || 'unknown'),
+            createdAt: note?.created_at || null,
+            body,
+          });
+          if (comments.length >= ctx.maxComments) break;
+        }
+      }
+    } catch (_err) {
+      // Non-fatal: keep main issue/MR discussion
+    }
+  }
+
+  return {
+    discussion: {
+      id: issue.id,
+      number: issue.number,
+      repo: repoPath,
+      provider: 'gitlab',
+      kind: isMr ? 'mr' : 'issue',
+      title: String(item.title || ''),
+      state: String(item.state || 'unknown'),
+      author: String(item.author?.username || item.author?.name || 'unknown'),
+      createdAt: item.created_at || null,
+      url: item.web_url || issue.url || null,
+      labels,
+      body: truncateText(item.description, ctx.maxBodyChars),
+      commits: issue.commits ?? [],
+      comments,
+    },
+  };
+}
+
+/**
+ * Fetch remote issue / PR / MR discussions for mined commit references.
+ *
+ * @param {Array<{id: string, number: number, repo: string|null, kind: string, url: string|null, commits: string[]}>} issues
+ * @param {{provider: string|null, host: string, repoPath: string, webUrl: string}|null} remote
+ * @param {object} [options]
+ * @param {number} [options.maxDiscussions=10]
+ * @param {number} [options.maxComments=5]
+ * @param {number} [options.timeoutMs=5000]
+ * @param {number} [options.maxBodyChars=2000]
+ * @param {number} [options.maxCommentChars=800]
+ * @param {string} [options.token]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {typeof globalThis.fetch} [options.fetch]
+ * @returns {Promise<{discussions: object[], warnings: string[]}>}
+ */
+export async function fetchDiscussions(issues, remote, options = {}) {
+  const warnings = [];
+  if (!Array.isArray(issues) || issues.length === 0) {
+    return { discussions: [], warnings };
+  }
+
+  if (!remote || !remote.provider) {
+    warnings.push(
+      'Cannot fetch discussions: repository has no supported GitHub or GitLab remote URL.'
+    );
+    return { discussions: [], warnings };
+  }
+
+  if (remote.provider !== 'github' && remote.provider !== 'gitlab') {
+    warnings.push(
+      `Discussions enrichment is not supported for provider "${remote.provider}" (supported: github, gitlab).`
+    );
+    return { discussions: [], warnings };
+  }
+
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  if (typeof fetchFn !== 'function') {
+    warnings.push('Cannot fetch discussions: fetch API is unavailable in this Node.js runtime.');
+    return { discussions: [], warnings };
+  }
+
+  const maxDiscussions = options.maxDiscussions ?? DEFAULT_MAX_DISCUSSIONS;
+  if (maxDiscussions <= 0) return { discussions: [], warnings };
+
+  const token = resolveAuthToken(remote.provider, options);
+  const headers =
+    remote.provider === 'github'
+      ? {
+          Accept: 'application/vnd.github+json',
+          'User-Agent': 'ctxman',
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        }
+      : {
+          Accept: 'application/json',
+          'User-Agent': 'ctxman',
+          ...(token ? { 'PRIVATE-TOKEN': token } : {}),
+        };
+
+  const ctx = {
+    fetchFn,
+    headers,
+    hasToken: Boolean(token),
+    maxComments: options.maxComments ?? DEFAULT_MAX_COMMENTS,
+    timeoutMs: options.timeoutMs ?? DEFAULT_DISCUSSION_TIMEOUT_MS,
+    maxBodyChars: options.maxBodyChars ?? DEFAULT_MAX_BODY_CHARS,
+    maxCommentChars: options.maxCommentChars ?? DEFAULT_MAX_COMMENT_CHARS,
+  };
+
+  const candidates = issues.slice(0, maxDiscussions);
+  const discussions = [];
+
+  for (const issue of candidates) {
+    try {
+      const outcome =
+        remote.provider === 'github'
+          ? await fetchGitHubDiscussion(issue, remote, ctx)
+          : await fetchGitLabDiscussion(issue, remote, ctx);
+
+      if (outcome.warning) warnings.push(outcome.warning);
+      if (outcome.discussion) discussions.push(outcome.discussion);
+      if (outcome.rateLimited) break;
+    } catch (error) {
+      const msg = error?.name === 'AbortError' ? 'request timed out' : error?.message || 'error';
+      warnings.push(`Failed to fetch discussion ${issue.id}: ${msg}.`);
+    }
+  }
+
+  return { discussions, warnings };
+}
+
+export default fetchDiscussions;