ctxman 3.0.0 → 3.1.0

package/lib/watch/FileWatcher.js

@@ -13,6 +13,7 @@ import fs from 'fs';
 import path from 'path';
 import { EventEmitter } from 'events';
 import GitIgnoreParser from '../parsers/gitignore-parser.js';
+import FileUtils from '../utils/file-utils.js';
 import { getLogger } from '../utils/logger.js';
 
 const logger = getLogger('FileWatcher');
@@ -26,7 +27,7 @@ export class FileWatcher extends EventEmitter {
       debounce: 1000, // 1 second debounce
       recursive: true,
       ignorePatterns: [],
-      ...options
+      ...options,
     };
 
     // Initialize GitIgnoreParser with correct file paths
@@ -42,7 +43,7 @@ export class FileWatcher extends EventEmitter {
     this.stats = {
       totalChanges: 0,
       ignoredChanges: 0,
-      errors: 0
+      errors: 0,
     };
   }
 
@@ -71,7 +72,6 @@ export class FileWatcher extends EventEmitter {
 
       this.emit('watch:started', { path: this.rootPath });
       logger.info('Watch mode started');
-
     } catch (error) {
       logger.error(`Failed to start watch: ${error.message}`);
       this.emit('watch:error', { error });
@@ -153,7 +153,7 @@ export class FileWatcher extends EventEmitter {
       path: filePath,
       relativePath: relativePath,
       timestamp: Date.now(),
-      exists: fs.existsSync(filePath)
+      exists: fs.existsSync(filePath),
     };
 
     // Add file stats if exists
@@ -162,7 +162,7 @@ export class FileWatcher extends EventEmitter {
         const stats = fs.statSync(filePath);
         event.size = stats.size;
         event.modified = stats.mtime;
-      } catch (error) {
+      } catch (_error) {
         // Stats not available
       }
     }
@@ -176,8 +176,12 @@ export class FileWatcher extends EventEmitter {
    * @returns {boolean}
    */
   shouldIgnore(relativePath) {
+    // node_modules, .git and build output are skipped like in the scanners, .gitignore or not
+    if (relativePath.split(path.sep).some((part) => FileUtils.isSkippedDirectory(part))) {
+      return true;
+    }
     // Use GitIgnoreParser for ignore rules
-    return !this.gitIgnore.shouldIncludeFile(relativePath);
+    return this.gitIgnore.isIgnored(path.join(this.rootPath, relativePath), relativePath);
   }
 
   /**
@@ -189,7 +193,7 @@ export class FileWatcher extends EventEmitter {
       ...this.stats,
       isWatching: this.isWatching,
       activeWatchers: this.watchers.length,
-      pendingDebounce: this.debounceTimers.size
+      pendingDebounce: this.debounceTimers.size,
     };
   }
 
@@ -200,7 +204,7 @@ export class FileWatcher extends EventEmitter {
     this.stats = {
       totalChanges: 0,
       ignoredChanges: 0,
-      errors: 0
+      errors: 0,
     };
   }
 }

package/lib/watch/IncrementalAnalyzer.js

@@ -10,6 +10,7 @@
  */
 
 import { EventEmitter } from 'events';
+import path from 'path';
 import { Analyzer } from '../core/Analyzer.js';
 import { getLogger } from '../utils/logger.js';
 
@@ -21,7 +22,7 @@ export class IncrementalAnalyzer extends EventEmitter {
 
     this.options = {
       autoAnalyze: true,
-      ...options
+      ...options,
     };
 
     this.analyzer = new Analyzer(options);
@@ -52,7 +53,7 @@ export class IncrementalAnalyzer extends EventEmitter {
         name: path.basename(changeEvent.path),
         extension: path.extname(changeEvent.path),
         size: changeEvent.size,
-        modified: changeEvent.modified
+        modified: changeEvent.modified,
       };
 
       const analysis = await this.analyzer.analyzeFile(fileInfo);
@@ -71,17 +72,16 @@ export class IncrementalAnalyzer extends EventEmitter {
           file: changeEvent.relativePath,
           analysis,
           elapsed,
-          cached: false
+          cached: false,
         });
 
         logger.debug(`Analysis complete: ${changeEvent.relativePath} (${elapsed}ms)`);
       }
-
     } catch (error) {
       logger.error(`Analysis failed for ${changeEvent.relativePath}: ${error.message}`);
       this.emit('analysis:error', {
         file: changeEvent.relativePath,
-        error
+        error,
       });
     }
   }
@@ -114,7 +114,7 @@ export class IncrementalAnalyzer extends EventEmitter {
 
       this.emit('file:deleted', {
         file: changeEvent.relativePath,
-        oldTokens: oldAnalysis.tokens
+        oldTokens: oldAnalysis.tokens,
       });
 
       logger.debug(`File deleted from cache: ${changeEvent.relativePath}`);
@@ -198,7 +198,7 @@ export class IncrementalAnalyzer extends EventEmitter {
   getCacheStats() {
     return {
       cachedFiles: this.fileCache.size,
-      cacheSize: this.fileCache.size * 1024 // Rough estimate
+      cacheSize: this.fileCache.size * 1024, // Rough estimate
     };
   }
 }

package/lib/why/coupling.js

@@ -0,0 +1,81 @@
+/**
+ * Co-change coupling: files that changed in the same commits as the target. A file that
+ * nearly always changes with the target is usually part of the same decision (a test, a
+ * schema, a caller, the docs), which makes it a strong "what else" signal
+ */
+
+import { literalPathspec, runGit } from './git.js';
+
+const RS = '\x1e';
+
+/**
+ * Split `git log --format=<RS>%H --name-only` output into commits and their files
+ * @param {string} output
+ * @returns {Array<{sha: string, files: string[]}>}
+ */
+function parseNameOnly(output) {
+  return output
+    .split(RS)
+    .map((record) => record.split('\n').filter((line) => line !== ''))
+    .filter((lines) => lines.length > 0)
+    .map(([sha, ...files]) => ({ sha: sha.trim(), files }));
+}
+
+/**
+ * @param {string} top - Work tree root
+ * @param {object} query
+ * @param {string} query.path - Forward-slash path relative to `top`
+ * @param {number} query.window - Commits of the target to examine
+ * @param {number} [query.maxFilesPerCommit] - Larger commits are skipped as noise (default 50)
+ * @param {string} [query.rev]
+ * @param {(gitPath: string) => boolean} [query.keep] - Filter on candidate paths
+ * @returns {{window: number, targetChanges: number, skippedLargeCommits: number,
+ *   files: Array<{path: string, count: number, confidence: number}>}}
+ */
+export function collectCoupling(top, query) {
+  const maxFiles = query.maxFilesPerCommit ?? 50;
+  const args = ['log', '--follow', '--no-merges', '-n', String(query.window)];
+  args.push(`--format=${RS}%H`, '--name-only');
+  if (query.rev) args.push(query.rev);
+  args.push('--', literalPathspec(query.path));
+
+  // With a pathspec, --name-only lists only the target, under its name at that commit
+  const touches = parseNameOnly(runGit(top, args));
+  const aliases = new Set([query.path, ...touches.flatMap((commit) => commit.files)]);
+
+  let commits = [];
+  if (touches.length > 0) {
+    const input = touches.map((commit) => commit.sha).join('\n') + '\n';
+    commits = parseNameOnly(
+      runGit(top, ['log', '--no-walk=unsorted', '--stdin', `--format=${RS}%H`, '--name-only'], {
+        input,
+      })
+    );
+  }
+
+  const counts = new Map();
+  let considered = 0;
+  let skipped = 0;
+  for (const commit of commits) {
+    if (commit.files.length > maxFiles) {
+      skipped++;
+      continue;
+    }
+    considered++;
+    for (const file of new Set(commit.files)) {
+      if (aliases.has(file)) continue;
+      counts.set(file, (counts.get(file) ?? 0) + 1);
+    }
+  }
+
+  const files = [...counts.entries()]
+    .filter(([file]) => !query.keep || query.keep(file))
+    .map(([file, count]) => ({
+      path: file,
+      count,
+      confidence: considered ? Math.round((count / considered) * 1000) / 1000 : 0,
+    }))
+    .sort((a, b) => b.count - a.count || a.path.localeCompare(b.path));
+
+  return { window: query.window, targetChanges: considered, skippedLargeCommits: skipped, files };
+}

package/lib/why/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Errors raised by `ctxman why`
+ */
+
+/**
+ * An expected failure (bad target, not a repository, budget too small, ...) with a
+ * stable code callers can branch on and a message meant for the user
+ */
+export class WhyError extends Error {
+  /**
+   * @param {string} code - e.g. NOT_A_GIT_REPO, PATH_OUTSIDE_ROOT, SYMBOL_NOT_FOUND
+   * @param {string} message - User-facing message
+   * @param {object} [details] - Extra fields copied onto the error (e.g. candidates)
+   */
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'WhyError';
+    this.code = code;
+    Object.assign(this, details);
+  }
+}
+
+export default WhyError;

package/lib/why/git.js

@@ -0,0 +1,169 @@
+/**
+ * Git access for `ctxman why`
+ *
+ * Every command runs through execFileSync with an argument list (no shell). Unlike
+ * GitClient.exec() this runner keeps output untrimmed (blame and patches are
+ * whitespace-sensitive), allows large outputs, lets callers accept exit codes such as
+ * `git grep`'s 1 for "no match", and logs nothing: an expected failure must not print
+ * to stdout, which carries the document.
+ */
+
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { WhyError } from './errors.js';
+
+// Settings that would change the output format (signature blocks, quoted paths, colour)
+const BASE_ARGS = [
+  '-c',
+  'core.quotePath=false',
+  '-c',
+  'log.showSignature=false',
+  '-c',
+  'color.ui=false',
+];
+
+const MAX_BUFFER = 256 * 1024 * 1024;
+
+/**
+ * Run git and return its stdout
+ * @param {string} cwd - Working directory
+ * @param {string[]} args - Arguments after `git`
+ * @param {object} [options]
+ * @param {string} [options.input] - Text for stdin
+ * @param {number[]} [options.okStatuses] - Exit codes that count as success (default [0])
+ * @param {'utf-8'|'buffer'} [options.encoding] - 'buffer' returns the raw bytes
+ * @returns {string|Buffer}
+ */
+export function runGit(cwd, args, { input, okStatuses = [0], encoding = 'utf-8' } = {}) {
+  try {
+    return execFileSync('git', [...BASE_ARGS, ...args], {
+      cwd,
+      encoding,
+      maxBuffer: MAX_BUFFER,
+      input,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      // Read-only use: never take optional locks, never prompt
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' },
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new WhyError('GIT_NOT_FOUND', 'git is not installed or not on PATH');
+    }
+    if (typeof error.status === 'number' && okStatuses.includes(error.status)) {
+      if (encoding === 'buffer') return error.stdout ?? Buffer.alloc(0);
+      return error.stdout ? String(error.stdout) : '';
+    }
+    const stderr = error.stderr ? String(error.stderr).trim() : '';
+    const failure = new Error(stderr || error.message);
+    failure.status = error.status;
+    failure.stderr = stderr;
+    throw failure;
+  }
+}
+
+/**
+ * Like runGit, but returns null instead of throwing on a git error. Success can be an
+ * empty string (`git cat-file -e`), so test the result against null, not for truthiness
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {object} [options]
+ * @returns {string|Buffer|null}
+ */
+export function tryGit(cwd, args, options) {
+  try {
+    return runGit(cwd, args, options);
+  } catch (error) {
+    if (error instanceof WhyError) throw error;
+    return null;
+  }
+}
+
+/**
+ * Top-level directory of the work tree containing `dir`
+ * @param {string} dir
+ * @returns {string} Real (symlink-resolved) path
+ */
+export function findRepositoryRoot(dir) {
+  if (!dir || !fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) {
+    throw new WhyError('ROOT_NOT_FOUND', `Not a directory: ${dir}`);
+  }
+  let top;
+  try {
+    top = runGit(dir, ['rev-parse', '--show-toplevel']).trim();
+  } catch (error) {
+    if (error instanceof WhyError) throw error;
+    const reason = error.stderr ? ` (${error.stderr.split('\n')[0]})` : '';
+    throw new WhyError(
+      'NOT_A_GIT_REPO',
+      `Not a git repository: ${dir}${reason}. ctxman why reads git history; run it inside a git work tree.`
+    );
+  }
+  if (!top) {
+    throw new WhyError('NOT_A_GIT_REPO', `Not a git work tree: ${dir}`);
+  }
+  return fs.realpathSync(top);
+}
+
+/**
+ * Commits whose parents a shallow clone did not fetch (the `shallow` file in the git
+ * directory). git shows them as root commits, so their diff looks like they added
+ * everything
+ * @param {string} top - Work tree root
+ * @returns {Set<string>} Full hashes
+ */
+function readShallowBoundary(top) {
+  const file = tryGit(top, ['rev-parse', '--git-path', 'shallow'])?.trim();
+  if (!file) return new Set();
+  try {
+    const content = fs.readFileSync(path.resolve(top, file), 'utf-8');
+    return new Set(content.split('\n').filter((line) => /^[0-9a-f]{40,64}$/.test(line)));
+  } catch (_error) {
+    return new Set();
+  }
+}
+
+/**
+ * Facts about the repository that shape the output
+ * @param {string} top - Work tree root
+ * @returns {{shallow: boolean, boundary: Set<string>, head: string|null,
+ *   remoteUrl: string|null}} boundary: see readShallowBoundary (empty unless shallow)
+ */
+export function readRepositoryInfo(top) {
+  const shallow = tryGit(top, ['rev-parse', '--is-shallow-repository'])?.trim() === 'true';
+  const boundary = shallow ? readShallowBoundary(top) : new Set();
+  const head = tryGit(top, ['rev-parse', '--verify', '--quiet', 'HEAD'])?.trim() || null;
+  const remoteUrl = tryGit(top, ['remote', 'get-url', 'origin'])?.trim() || null;
+  return { shallow, boundary, head, remoteUrl };
+}
+
+/**
+ * A pathspec matching exactly this path: no glob characters, no pathspec magic
+ * @param {string} gitPath
+ * @returns {string}
+ */
+export function literalPathspec(gitPath) {
+  return `:(literal)${gitPath}`;
+}
+
+/**
+ * Convert an OS path relative to the work tree into git's forward-slash form
+ * @param {string} relativePath
+ * @returns {string}
+ */
+export function toGitPath(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+/**
+ * A git date as ISO 8601 in UTC, to the second (2024-01-02T10:00:00Z). Commit dates
+ * (`%aI`, author's offset) and blame times (epoch seconds) end up in one form, so dates
+ * compare and print alike across sections
+ * @param {string|number} value - ISO 8601 text, or seconds since the epoch
+ * @returns {string|null} null for a missing or unparsable date
+ */
+export function utcDate(value) {
+  const time = typeof value === 'number' ? value * 1000 : Date.parse(value);
+  if (!value || !Number.isFinite(time)) return null;
+  return new Date(time).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}

package/lib/why/history.js

@@ -0,0 +1,108 @@
+/**
+ * Commit history of a target: `git log -L` for a line range (or git's own funcname
+ * matching as a fallback), `git log --follow` for a whole file
+ */
+
+import { literalPathspec, runGit, utcDate } from './git.js';
+
+// Record separator, field separator, end of header: the patch (if any) follows the header
+const RS = '\x1e';
+const FS = '\x1f';
+const EOH = '\x1d';
+const FORMAT = `--format=${RS}%H${FS}%h${FS}%aI${FS}%an${FS}%ae${FS}%P${FS}%s${FS}%b${EOH}`;
+
+/**
+ * @typedef {object} HistoryCommit
+ * @property {string} sha
+ * @property {string} shortSha
+ * @property {string} date - Author date, ISO 8601 in UTC (2024-01-02T10:00:00Z)
+ * @property {string} author
+ * @property {string} email
+ * @property {boolean} merge
+ * @property {string} subject
+ * @property {string} body
+ * @property {string} [patch] - Diff for the target (only when patches were requested)
+ */
+
+/**
+ * Parse `git log` output written with FORMAT
+ * @param {string} output
+ * @param {boolean} keepPatches
+ * @returns {HistoryCommit[]}
+ */
+export function parseLog(output, keepPatches) {
+  const commits = [];
+  for (const record of output.split(RS)) {
+    const end = record.indexOf(EOH);
+    if (end === -1) continue;
+    const fields = record.slice(0, end).split(FS);
+    if (fields.length < 8) continue;
+    const [sha, shortSha, date, author, email, parents, subject, ...body] = fields;
+    const commit = {
+      sha,
+      shortSha,
+      date: utcDate(date) ?? date,
+      author,
+      email,
+      merge: parents.trim().split(/\s+/).length > 1,
+      subject,
+      body: body.join(FS).trim(),
+    };
+    if (keepPatches) {
+      const patch = record
+        .slice(end + 1)
+        .replace(/^\n+/, '')
+        .trimEnd();
+      if (patch) commit.patch = patch;
+    }
+    commits.push(commit);
+  }
+  return commits;
+}
+
+/**
+ * Commits that touched the target, newest first
+ * @param {string} top - Work tree root (git runs here)
+ * @param {object} query
+ * @param {string} query.path - Forward-slash path relative to `top`
+ * @param {'range'|'funcname'|'file'} query.mode
+ * @param {number} [query.startLine] - For 'range' (lines of `rev`)
+ * @param {number} [query.endLine]
+ * @param {string} [query.funcname] - For 'funcname': a basic regular expression
+ * @param {string} [query.rev] - Revision to start from (validated by the caller)
+ * @param {number} query.limit
+ * @param {string} [query.since]
+ * @param {boolean} [query.patches]
+ * @returns {HistoryCommit[]}
+ */
+export function collectHistory(top, query) {
+  const args = ['log', FORMAT, '-n', String(query.limit), '--no-ext-diff', '--no-color'];
+  if (query.since) args.push(`--since=${query.since}`);
+
+  if (query.mode === 'file') {
+    args.push('--follow');
+    if (query.patches) args.push('-p');
+    if (query.rev) args.push(query.rev);
+    args.push('--', literalPathspec(query.path));
+  } else {
+    const range =
+      query.mode === 'range'
+        ? `${query.startLine},${query.endLine}:${query.path}`
+        : `:${query.funcname}:${query.path}`;
+    args.push('-L', range);
+    // Older git versions ignore -s with -L; parseLog drops the patch text either way
+    if (!query.patches) args.push('-s');
+    if (query.rev) args.push(query.rev);
+  }
+
+  return parseLog(runGit(top, args), Boolean(query.patches));
+}
+
+/**
+ * Escape a symbol for git's `-L :<funcname>:<file>` (a POSIX basic regular expression)
+ * @param {string} name
+ * @returns {string}
+ */
+export function funcnamePattern(name) {
+  return name.replace(/[.[\]*^$\\]/g, '\\$&');
+}