ctxman 3.0.0 → 3.1.1

package/lib/why/ownership.js

@@ -0,0 +1,79 @@
+/**
+ * Ownership of a target from `git blame --line-porcelain`: who wrote which share of the
+ * lines, and when each author last touched them
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { GitClient } from '../integrations/git/GitClient.js';
+import { tryGit, utcDate } from './git.js';
+
+const UNCOMMITTED = /^0+$/;
+
+/**
+ * Blame summary for a line range (or the whole file)
+ * @param {string} top - Work tree root
+ * @param {object} query
+ * @param {string} query.path - Forward-slash path relative to `top`
+ * @param {number} [query.startLine]
+ * @param {number} [query.endLine]
+ * @param {string} [query.rev] - Blame this revision instead of the working tree
+ * @returns {{startLine: number|null, endLine: number|null, totalLines: number,
+ *   lastChanged: string|null, authors: Array<{name: string, lines: number, share: number,
+ *   commits: number, lastTouched: string|null}>}|null} null when blame fails
+ */
+export function collectOwnership(top, query) {
+  const args = ['blame', '--line-porcelain', '-w'];
+  if (query.startLine) args.push('-L', `${query.startLine},${query.endLine}`);
+  if (query.rev) args.push(query.rev);
+  args.push('--', query.path);
+
+  // Honour the conventional list of formatting-only commits, when the project has one
+  const ignoreRevs = path.join(top, '.git-blame-ignore-revs');
+  let output = null;
+  if (fs.existsSync(ignoreRevs)) {
+    output = tryGit(top, [
+      args[0],
+      '--ignore-revs-file',
+      '.git-blame-ignore-revs',
+      ...args.slice(1),
+    ]);
+  }
+  output ??= tryGit(top, args);
+  if (output === null) return null;
+
+  // GitClient knows the porcelain format: one entry per line with commit, author, time
+  const lines = GitClient.prototype.parseBlameOutput.call(null, output);
+  const authors = new Map();
+  let lastChanged = 0;
+
+  for (const line of lines) {
+    const uncommitted = UNCOMMITTED.test(line.commit ?? '');
+    const name = uncommitted ? '(uncommitted)' : line.author || '(unknown)';
+    const entry = authors.get(name) ?? { name, lines: 0, commits: new Set(), lastTouched: 0 };
+    entry.lines++;
+    if (!uncommitted) {
+      entry.commits.add(line.commit);
+      entry.lastTouched = Math.max(entry.lastTouched, line.timestamp || 0);
+      lastChanged = Math.max(lastChanged, line.timestamp || 0);
+    }
+    authors.set(name, entry);
+  }
+
+  const total = lines.length;
+  return {
+    startLine: query.startLine ?? null,
+    endLine: query.endLine ?? null,
+    totalLines: total,
+    lastChanged: utcDate(lastChanged),
+    authors: [...authors.values()]
+      .map((entry) => ({
+        name: entry.name,
+        lines: entry.lines,
+        share: total ? Math.round((entry.lines / total) * 1000) / 1000 : 0,
+        commits: entry.commits.size,
+        lastTouched: utcDate(entry.lastTouched),
+      }))
+      .sort((a, b) => b.lines - a.lines || a.name.localeCompare(b.name)),
+  };
+}

package/lib/why/paths.js

@@ -0,0 +1,207 @@
+/**
+ * Path rules for `ctxman why`: keeping targets inside the project, applying the
+ * project's ignore files, and classifying files (tests, docs, ADRs, changelogs)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { Scanner } from '../core/Scanner.js';
+import FileUtils from '../utils/file-utils.js';
+import { WhyError } from './errors.js';
+
+/** Extensions searched as prose: every line that mentions a term counts */
+export const DOC_EXTENSIONS = new Set([
+  '.md',
+  '.markdown',
+  '.mdx',
+  '.adoc',
+  '.asciidoc',
+  '.asc',
+  '.rst',
+  '.txt',
+]);
+
+/**
+ * Resolve `file` (relative to `base`, or absolute) and check that it stays inside `root`,
+ * also after following symlinks
+ * @param {string} root - Real path of the project root
+ * @param {string} base - Directory relative paths start from
+ * @param {string} file
+ * @param {object} [options]
+ * @param {boolean} [options.mustExist=true] - false: a path that only exists in history
+ * @param {string} [options.label='the repository'] - What `root` is, for error messages
+ * @returns {{absolute: string, relative: string}} relative uses the OS separator
+ */
+export function resolveInsideRoot(
+  root,
+  base,
+  file,
+  { mustExist = true, label = 'the repository' } = {}
+) {
+  if (typeof file !== 'string' || file.trim() === '' || file.includes('\0')) {
+    throw new WhyError('INVALID_TARGET', 'A file path is required');
+  }
+  const absolute = path.resolve(base, file);
+  // The root itself, or a path above it (`..foo` is a valid name inside it)
+  const outside = (candidate) => {
+    const relative = path.relative(root, candidate);
+    return (
+      relative === '' ||
+      relative === '..' ||
+      relative.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(relative)
+    );
+  };
+  if (outside(absolute)) {
+    throw new WhyError('PATH_OUTSIDE_ROOT', `Path is outside ${label}: ${file}`);
+  }
+
+  const stat = fs.statSync(absolute, { throwIfNoEntry: false });
+  if (!stat && !mustExist) {
+    return { absolute, relative: path.relative(root, absolute) };
+  }
+  if (!stat) {
+    throw new WhyError('FILE_NOT_FOUND', `File not found: ${file}`);
+  }
+  if (!stat.isFile()) {
+    throw new WhyError('NOT_A_FILE', `Not a file: ${file}`);
+  }
+  const real = fs.realpathSync(absolute);
+  if (outside(real)) {
+    throw new WhyError('PATH_OUTSIDE_ROOT', `Path leads outside ${label}: ${file}`);
+  }
+
+  const relative = path.relative(root, real);
+  if (relative.split(path.sep)[0] === '.git') {
+    throw new WhyError('PATH_OUTSIDE_ROOT', `Path is inside the .git directory: ${file}`);
+  }
+  return { absolute: real, relative };
+}
+
+/**
+ * The scanner's rules as a predicate on project-relative paths: .gitignore,
+ * .contextignore / .contextinclude and the always-skipped directories, applied to every
+ * ancestor directory the way a scan would meet them
+ * @param {string} root
+ * @returns {(relativePath: string) => boolean} true when the path is excluded
+ */
+export function createPathFilter(root) {
+  const scanner = new Scanner(root);
+  // Load now: an invalid export policy fails the command instead of being skipped
+  scanner.getPolicy();
+  const cache = new Map();
+
+  const excludedDirectory = (relativeDir) => {
+    if (cache.has(relativeDir)) return cache.get(relativeDir);
+    const name = relativeDir.split('/').pop();
+    const parent = relativeDir.includes('/')
+      ? relativeDir.slice(0, relativeDir.lastIndexOf('/'))
+      : '';
+    const excluded =
+      (parent !== '' && excludedDirectory(parent)) ||
+      FileUtils.isSkippedDirectory(name) ||
+      scanner.shouldIgnore(
+        relativeDir.split('/').join(path.sep),
+        path.join(root, ...relativeDir.split('/'))
+      );
+    cache.set(relativeDir, excluded);
+    return excluded;
+  };
+
+  const isExcluded = (relativePath) => {
+    const posix = relativePath.split(path.sep).join('/');
+    // Denied by the export policy: left out like an ignored file, and never named
+    if (scanner.isDenied(posix)) return true;
+    const parent = posix.includes('/') ? posix.slice(0, posix.lastIndexOf('/')) : '';
+    if (parent !== '' && excludedDirectory(parent)) return true;
+    return scanner.shouldIgnore(
+      posix.split('/').join(path.sep),
+      path.join(root, ...posix.split('/'))
+    );
+  };
+  isExcluded.isDenied = (relativePath) => scanner.isDenied(relativePath.split(path.sep).join('/'));
+  return isExcluded;
+}
+
+/**
+ * Whether a file holds binary data (a NUL byte in its first 8000 bytes, git's heuristic)
+ * @param {Buffer} buffer
+ * @returns {boolean}
+ */
+export function isBinaryBuffer(buffer) {
+  return buffer.subarray(0, 8000).includes(0);
+}
+
+/**
+ * Whether ctxman may print this file's content: the scanner's text-file rule, which
+ * also keeps secret-bearing files such as .env or *.pem out of exports
+ * @param {string} relativePath
+ * @returns {boolean}
+ */
+export function isExportableText(relativePath) {
+  return FileUtils.isText(relativePath);
+}
+
+/**
+ * Test files by common conventions (test/ and spec/ folders, *.test.*, *_test.go,
+ * test_*.py, FooTest.java, ...)
+ * @param {string} relativePath - Forward-slash path
+ * @returns {boolean}
+ */
+export function isTestFile(relativePath) {
+  const posix = relativePath.split(path.sep).join('/');
+  const base = posix.split('/').pop();
+  return (
+    /(^|\/)(test|tests|__tests__|spec|specs|testing)\//i.test(posix) ||
+    /[._-](test|spec)s?\.[^./]+$/i.test(base) ||
+    /^test_.+\.py$/i.test(base) ||
+    /(Test|Tests|Spec|IT)\.(java|kt|kts|cs|scala|swift|php|groovy)$/.test(base)
+  );
+}
+
+/**
+ * git pathspecs that select the files isTestFile() accepts (a superset; results are
+ * filtered with isTestFile again)
+ */
+export const TEST_PATHSPECS = [
+  ':(glob)**/test/**',
+  ':(glob)**/tests/**',
+  ':(glob)**/__tests__/**',
+  ':(glob)**/spec/**',
+  ':(glob)**/specs/**',
+  ':(glob)**/testing/**',
+  ':(glob)**/*.test.*',
+  ':(glob)**/*.spec.*',
+  ':(glob)**/*_test.*',
+  ':(glob)**/*-test.*',
+  ':(glob)**/*.tests.*',
+  ':(glob)**/test_*',
+  ':(glob)**/*Test.*',
+  ':(glob)**/*Tests.*',
+  ':(glob)**/*Spec.*',
+  ':(glob)**/*IT.*',
+];
+
+/**
+ * Kind of prose file: 'adr' (architecture decision records), 'changelog', 'doc', or
+ * null for anything else
+ * @param {string} relativePath
+ * @returns {'adr'|'changelog'|'doc'|null}
+ */
+export function classifyTextFile(relativePath) {
+  const posix = relativePath.split(path.sep).join('/');
+  const base = posix.split('/').pop();
+  const ext = path.extname(base).toLowerCase();
+  const prose = DOC_EXTENSIONS.has(ext);
+
+  if (
+    /(^|\/)(adr|adrs|decisions|architecture[-_]decisions?)\//i.test(posix) ||
+    /(^|[^a-z])adr([^a-z]|$)/i.test(base)
+  ) {
+    return prose || ext === '' ? 'adr' : null;
+  }
+  if (/^(changelog|changes|history|news|releases?)(\.|$)/i.test(base)) {
+    return 'changelog';
+  }
+  return prose ? 'doc' : null;
+}

package/lib/why/references.js

@@ -0,0 +1,259 @@
+/**
+ * References mined from commit messages: issue and pull request numbers, ticket keys,
+ * CVE ids, URLs and Co-authored-by / Reviewed-by trailers, with web links when `origin`
+ * is a GitHub, GitLab or Bitbucket remote
+ */
+
+// Upper-case words followed by a number that are not ticket keys
+const NOT_TICKETS = new Set([
+  'AES',
+  'ANSI',
+  'ASCII',
+  'BASE',
+  'BSD',
+  'CC',
+  'CP',
+  'CRC',
+  'CVE',
+  'CWE',
+  'DES',
+  'ECMA',
+  'ES',
+  'GH',
+  'GPL',
+  'HTTP',
+  'HTTPS',
+  'IEC',
+  'IEEE',
+  'IPV',
+  'ISO',
+  'LGPL',
+  'AGPL',
+  'MD',
+  'MPL',
+  'PEP',
+  'POSIX',
+  'RFC',
+  'RSA',
+  'SHA',
+  'SSL',
+  'TLS',
+  'UCS',
+  'UTF',
+  'WCAG',
+  'WIN',
+  'X',
+]);
+
+const KIND_RANK = { pr: 2, mr: 2, issue: 1 };
+
+/**
+ * Parse a remote URL (https, ssh, scp-like `git@host:owner/repo.git`) into a provider and
+ * a web base URL. Credentials and ports of ssh remotes are dropped
+ * @param {string|null} url
+ * @returns {{provider: 'github'|'gitlab'|'bitbucket'|null, host: string, repoPath: string,
+ *   webUrl: string}|null} null for local paths and unparsable URLs
+ */
+export function parseRemote(url) {
+  if (!url || typeof url !== 'string') return null;
+  const trimmed = url.trim();
+  let host;
+  let port = '';
+  let repoPath;
+
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    let parsed;
+    try {
+      parsed = new URL(trimmed);
+    } catch (_error) {
+      return null;
+    }
+    if (parsed.protocol === 'file:') return null;
+    host = parsed.hostname;
+    if (/^https?:$/.test(parsed.protocol) && parsed.port) port = `:${parsed.port}`;
+    repoPath = decodeURIComponent(parsed.pathname);
+  } else {
+    // scp-like syntax; a single letter before ':' is a Windows drive
+    const scp = trimmed.match(/^(?:[^@/\s]+@)?([^:/\s]{2,}):(?!\/\/)(.+)$/);
+    if (!scp) return null;
+    host = scp[1];
+    repoPath = scp[2];
+  }
+
+  repoPath = repoPath.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '');
+  if (!host || !repoPath.includes('/')) return null;
+
+  const provider = /github/i.test(host)
+    ? 'github'
+    : /gitlab/i.test(host)
+      ? 'gitlab'
+      : /bitbucket/i.test(host)
+        ? 'bitbucket'
+        : null;
+  if (provider === 'github' || provider === 'bitbucket') {
+    repoPath = repoPath.split('/').slice(0, 2).join('/');
+  }
+  // ssh.github.com / altssh.gitlab.com serve ssh only
+  const webHost = host.replace(/^(alt)?ssh\./i, '').toLowerCase();
+  return { provider, host: webHost, repoPath, webUrl: `https://${webHost}${port}/${repoPath}` };
+}
+
+/**
+ * Web link for an issue / pull request / merge request
+ * @param {ReturnType<typeof parseRemote>} remote
+ * @param {string|null} repoPath - Another repository on the same host (owner/repo#12)
+ * @param {number} number
+ * @param {string} kind
+ * @returns {string|null}
+ */
+export function issueLink(remote, repoPath, number, kind) {
+  if (!remote?.provider) return null;
+  const base = repoPath
+    ? remote.webUrl.slice(0, remote.webUrl.length - remote.repoPath.length) + repoPath
+    : remote.webUrl;
+  const isChange = kind === 'pr' || kind === 'mr';
+  switch (remote.provider) {
+    case 'github':
+      // GitHub redirects /issues/N to /pull/N for pull requests
+      return `${base}/${isChange ? 'pull' : 'issues'}/${number}`;
+    case 'gitlab':
+      return `${base}/-/${isChange ? 'merge_requests' : 'issues'}/${number}`;
+    case 'bitbucket':
+      return `${base}/${isChange ? 'pull-requests' : 'issues'}/${number}`;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Remove user:password@ from a URL
+ * @param {string} url
+ * @returns {string}
+ */
+function stripCredentials(url) {
+  return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/i, '$1');
+}
+
+/**
+ * Collect references from commits (newest first). Each entry lists the short hashes of
+ * the commits that mention it, in history order
+ * @param {Array<{shortSha: string, subject: string, body: string}>} commits
+ * @param {ReturnType<typeof parseRemote>} remote
+ * @returns {{issues: object[], tickets: object[], cves: object[], urls: object[],
+ *   coAuthors: object[], reviewers: object[]}}
+ */
+export function mineReferences(commits, remote) {
+  const issues = new Map();
+  const tickets = new Map();
+  const cves = new Map();
+  const urls = new Map();
+  const coAuthors = new Map();
+  const reviewers = new Map();
+
+  const note = (map, key, entry, sha) => {
+    const existing = map.get(key);
+    if (!existing) {
+      map.set(key, { ...entry, commits: [sha] });
+      return;
+    }
+    if (!existing.commits.includes(sha)) existing.commits.push(sha);
+    if (entry.closes) existing.closes = true;
+    if (entry.kind && (KIND_RANK[entry.kind] ?? 0) > (KIND_RANK[existing.kind] ?? 0)) {
+      existing.kind = entry.kind;
+      existing.url = entry.url;
+    }
+  };
+
+  // kind: issue, pr (pull request) or mr (GitLab merge request); closes: a closing
+  // keyword (fixes / closes / resolves) referred to it
+  const addIssue = (repoPath, number, kind, sha, closes = false) => {
+    if (!/^[1-9]\d{0,8}$/.test(number)) return;
+    const id = `${repoPath ?? ''}#${number}`;
+    note(
+      issues,
+      id,
+      {
+        id,
+        number: Number(number),
+        repo: repoPath ?? null,
+        kind,
+        closes,
+        url: issueLink(remote, repoPath, number, kind),
+      },
+      sha
+    );
+  };
+
+  for (const commit of commits) {
+    const sha = commit.shortSha;
+    const message = `${commit.subject}\n\n${commit.body}`;
+
+    // URLs first, then blank them out so their fragments and paths are not read as refs
+    let text = message.replace(/\bhttps?:\/\/[^\s<>"'`]+/gi, (raw) => {
+      const url = stripCredentials(raw.replace(/[).,;:!?\]}>]+$/, ''));
+      note(urls, url, { url }, sha);
+      return ' '.repeat(raw.length);
+    });
+
+    for (const match of text.matchAll(/^\s*(Co-authored-by|Reviewed-by)\s*:\s*(.+?)\s*$/gim)) {
+      const value = match[2];
+      const map = match[1].toLowerCase() === 'co-authored-by' ? coAuthors : reviewers;
+      note(map, value.toLowerCase(), { value }, sha);
+    }
+    // Trailers carry e-mail addresses, not references
+    text = text.replace(/^\s*[\w-]+-by\s*:.*$/gim, '');
+
+    // Pull / merge requests: squash suffix "(#45)", merge commits, GitLab "!45"
+    const squash = commit.subject.match(/\(#(\d+)\)\s*$/);
+    if (squash) addIssue(null, squash[1], remote?.provider === 'gitlab' ? 'issue' : 'pr', sha);
+    for (const match of text.matchAll(/\b(?:Merge pull request|pull request) #(\d+)/gi)) {
+      addIssue(null, match[1], 'pr', sha);
+    }
+    if (remote?.provider === 'gitlab') {
+      for (const match of text.matchAll(/(?:^|[\s(])(?:([\w.-]+(?:\/[\w.-]+)+))?!(\d+)\b/g)) {
+        addIssue(match[1] ?? null, match[2], 'mr', sha);
+      }
+    }
+
+    for (const match of text.matchAll(
+      /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s+(?:([\w.-]+\/[\w.-]+))?#(\d+)\b/gi
+    )) {
+      addIssue(match[1] ?? null, match[2], 'issue', sha, true);
+    }
+    for (const match of text.matchAll(/(?:^|[^\w&/#])(?:([\w.-]+\/[\w.-]+))?#(\d+)(?!\w)/g)) {
+      addIssue(match[1] ?? null, match[2], 'issue', sha);
+    }
+    for (const match of text.matchAll(/\bGH-(\d+)\b/g)) {
+      addIssue(null, match[1], 'issue', sha);
+    }
+
+    for (const match of text.matchAll(/\bCVE-\d{4}-\d{4,}\b/g)) {
+      note(cves, match[0], { id: match[0] }, sha);
+    }
+    for (const match of text.matchAll(/(?<![\w-])([A-Z][A-Z0-9]{1,9})-(\d{1,7})(?![\w])/g)) {
+      if (NOT_TICKETS.has(match[1]) || /^0/.test(match[2])) continue;
+      note(tickets, match[0], { id: match[0] }, sha);
+    }
+  }
+
+  return {
+    issues: [...issues.values()],
+    tickets: [...tickets.values()],
+    cves: [...cves.values()],
+    urls: [...urls.values()],
+    coAuthors: [...coAuthors.values()],
+    reviewers: [...reviewers.values()],
+  };
+}
+
+/**
+ * Ids of the references a single commit mentions (for the history section)
+ * @param {ReturnType<typeof mineReferences>} references
+ * @param {string} shortSha
+ * @returns {string[]}
+ */
+export function referencesOf(references, shortSha) {
+  return [...references.issues, ...references.tickets, ...references.cves]
+    .filter((entry) => entry.commits.includes(shortSha))
+    .map((entry) => entry.id);
+}