ctxman 3.1.0 → 3.2.7

package/lib/map/rank.js

@@ -117,9 +117,28 @@ export function pageRank(ids, edges, options = {}) {
 }
 
 /**
- * Files of the graph matched by focus paths (a file, or a folder for every file in it)
+ * Split a `file[:symbol]` target into `{ pathPart, symbol }` (ignoring Windows drive colons).
+ * @param {string} entry
+ * @returns {{ pathPart: string, symbol: string | null }}
+ */
+export function splitTargetSymbol(entry) {
+  if (typeof entry !== 'string') return { pathPart: '', symbol: null };
+  const lastColon = entry.lastIndexOf(':');
+  // Ignore Windows drive letters like `C:\foo` (colon at index 1)
+  if (lastColon > 1) {
+    const candidatePath = entry.slice(0, lastColon);
+    const candidateSymbol = entry.slice(lastColon + 1).trim();
+    if (candidatePath && candidateSymbol && !candidateSymbol.includes('/')) {
+      return { pathPart: candidatePath, symbol: candidateSymbol };
+    }
+  }
+  return { pathPart: entry, symbol: null };
+}
+
+/**
+ * Files of the graph matched by focus paths (a file, `file:symbol`, or a folder for every file in it)
  * @param {import('./graph.js').RepoGraph} graph
- * @param {string[]} focus - Absolute or project-relative paths
+ * @param {string[]} focus - Absolute or project-relative paths (optionally with `:symbol`)
  * @returns {{files: string[], unmatched: string[]}}
  * @throws {Error} When a path lies outside the project
  */
@@ -127,11 +146,22 @@ export function resolveFocus(graph, focus = []) {
   const files = new Set();
   const unmatched = [];
   const nodePaths = graph.nodes.map((node) => node.path);
+  const nodeMap = new Map(graph.nodes.map((node) => [node.path, node]));
   for (const entry of focus) {
-    const relative = toProjectPath(graph.root, entry);
-    const matches = nodePaths.filter(
+    const { pathPart, symbol } = splitTargetSymbol(entry);
+    const relative = toProjectPath(graph.root, pathPart);
+    let matches = nodePaths.filter(
       (file) => relative === '' || file === relative || file.startsWith(`${relative}/`)
     );
+    if (symbol && matches.length === 1) {
+      const node = nodeMap.get(matches[0]);
+      if (node && Array.isArray(node.methods) && node.methods.length > 0) {
+        const hasSymbol = node.methods.some(
+          (m) => m.name === symbol || m.name.replace(/^(?:get|set)\s+/, '') === symbol
+        );
+        if (!hasSymbol) matches = [];
+      }
+    }
     if (matches.length === 0) unmatched.push(entry);
     for (const file of matches) files.add(file);
   }
@@ -160,7 +190,8 @@ export function toProjectPath(root, entry) {
  * Rank the files of a graph, best first
  * @param {import('./graph.js').RepoGraph} graph
  * @param {Object} [options]
- * @param {string[]} [options.focus] - Files or folders to personalise PageRank toward
+ * @param {string[]} [options.focus] - Files, `file:symbol` targets, or folders to personalise PageRank toward
+ * @param {boolean} [options.callGraph=false] - Blend cross-file AST symbol call edges into PageRank
  * @param {{pagerank?: number, history?: number, symbols?: number}} [options.weights]
  * @param {number} [options.damping=0.85]
  * @returns {Array<{path: string, rank: number, score: number, pagerank: number,
@@ -171,12 +202,19 @@ export function rankFiles(graph, options = {}) {
   const weights = { ...DEFAULT_WEIGHTS, ...options.weights };
   const ids = graph.nodes.map((node) => node.path);
   const focus = new Set(resolveFocus(graph, options.focus || []).files);
+  const activeEdges =
+    options.callGraph && Array.isArray(graph.callEdges) && graph.callEdges.length > 0
+      ? [
+          ...graph.edges,
+          ...graph.callEdges.map(({ from, to, weight }) => ({ from, to, weight: weight ?? 1 })),
+        ]
+      : graph.edges;
 
   let personalization = null;
   if (focus.size > 0) {
     const preference = new Map();
     for (const file of focus) preference.set(file, FOCUS_WEIGHT);
-    for (const { from, to } of graph.edges) {
+    for (const { from, to } of activeEdges) {
       for (const [a, b] of [
         [from, to],
         [to, from],
@@ -196,7 +234,7 @@ export function rankFiles(graph, options = {}) {
     );
   }
 
-  const { scores } = pageRank(ids, graph.edges, {
+  const { scores } = pageRank(ids, activeEdges, {
     damping: options.damping ?? DEFAULT_DAMPING,
     personalization,
   });

package/lib/map/render.js

@@ -1,6 +1,6 @@
 /**
  * Rendering for `ctxman map`: the ranked files with their function signatures, trimmed
- * to a token budget, or the dependency graph itself
+ * to a token budget, or the dependency & cross-file call graph itself
  */
 
 import fs from 'fs';
@@ -37,6 +37,7 @@ export function normalizeMapOptions(options = {}) {
     importantLast: Boolean(options.importantLast),
     style: options.style ?? 'text',
     graph: Boolean(options.graph),
+    callGraph: Boolean(options.callGraph),
     redact: options.redact !== false,
     weights: { ...DEFAULT_WEIGHTS, ...options.weights },
     damping: options.damping ?? DEFAULT_DAMPING,
@@ -77,6 +78,7 @@ export function normalizeMapOptions(options = {}) {
  * @param {boolean} [options.importantLast=false] - Highest-ranked file at the end
  * @param {'text'|'markdown'|'json'|'dot'} [options.style='text']
  * @param {boolean} [options.graph=false] - Render the dependency edges instead of the map
+ * @param {boolean} [options.callGraph=false] - Include cross-file AST symbol call graph edges
  * @param {boolean} [options.redact=true] - Mask secrets in signatures
  * @param {{pagerank?: number, history?: number, symbols?: number}} [options.weights]
  * @returns {{output: string, style: string, budget: number, tokens: number,
@@ -102,6 +104,7 @@ export function renderRepoMap(root, options = {}) {
   let timer = performance.now();
   const ranked = rankFiles(graph, {
     focus: focus.files,
+    callGraph: opts.callGraph,
     weights: opts.weights,
     damping: opts.damping,
   });
@@ -116,7 +119,7 @@ export function renderRepoMap(root, options = {}) {
     warnings,
   };
   if (opts.graph || opts.style === 'dot') {
-    result.output = renderGraph(graph, ranked, opts.style);
+    result.output = renderGraph(graph, ranked, opts.style, { callGraph: opts.callGraph });
     result.tokens = countTokens(result.output);
     result.files = [];
     result.skipped = 0;
@@ -174,13 +177,18 @@ function selectFiles(graph, ranked, opts) {
       path: row.path,
       score: row.score,
       tokens: 0,
-      methods: node.methods.map((method) => ({ ...method, tokens: 0 })),
+      methods: node.methods.map((method) => ({
+        line: method.line,
+        name: method.name,
+        signature: method.signature,
+        tokens: 0,
+      })),
     });
     if (countTokens(skeleton + separator) > remaining) {
       skipped++;
       continue;
     }
-    const entry = describeFile(graph, node, row, analyzer);
+    const entry = describeFile(graph, node, row, analyzer, opts);
     const block = renderBlock(style, entry);
     const cost = countTokens(block + separator);
     if (cost > remaining) {
@@ -216,7 +224,7 @@ function displayOrder(chosen, opts) {
 }
 
 /** Map entry of a file: its tokens and the tokens of each of its methods */
-function describeFile(graph, node, row, analyzer) {
+function describeFile(graph, node, row, analyzer, opts = {}) {
   const absolute = path.join(graph.root, node.path);
   let content = '';
   try {
@@ -225,17 +233,37 @@ function describeFile(graph, node, row, analyzer) {
     // Deleted since the scan: keep the signatures, count nothing
   }
   const sources = content ? analyzer.extractMethodSources(content, node.methods, absolute) : [];
+  const outgoingCallsByMethod = new Map();
+  if (opts.callGraph && Array.isArray(graph.callEdges)) {
+    for (const edge of graph.callEdges) {
+      if (edge.from !== node.path) continue;
+      const key = `${edge.caller}:${edge.callerLine}`;
+      let list = outgoingCallsByMethod.get(key);
+      if (!list) {
+        list = [];
+        outgoingCallsByMethod.set(key, list);
+      }
+      list.push(`${edge.to}:${edge.callee}`);
+    }
+  }
   return {
     path: node.path,
     rank: row.rank,
     score: row.score,
     tokens: content ? TokenUtils.calculate(content, absolute) : 0,
-    methods: node.methods.map((method, i) => ({
-      line: method.line,
-      name: method.name,
-      signature: method.signature,
-      tokens: sources[i] ? TokenUtils.calculate(sources[i], absolute) : 0,
-    })),
+    methods: node.methods.map((method, i) => {
+      const item = {
+        line: method.line,
+        name: method.name,
+        signature: method.signature,
+        tokens: sources[i] ? TokenUtils.calculate(sources[i], absolute) : 0,
+      };
+      if (opts.callGraph) {
+        const targets = outgoingCallsByMethod.get(`${method.name}:${method.line}`) || [];
+        if (targets.length > 0) item.calls = targets;
+      }
+      return item;
+    }),
   };
 }
 
@@ -246,13 +274,23 @@ export function renderBlock(style, entry) {
     const lines = [`## ${entry.path}`, `score ${score} · ${entry.tokens} tokens`];
     if (entry.methods.length > 0) lines.push('');
     for (const method of entry.methods) {
-      lines.push(`- L${method.line} ${inlineCode(method.signature)} (${method.tokens} tokens)`);
+      const callSuffix =
+        Array.isArray(method.calls) && method.calls.length > 0
+          ? ` -> ${method.calls.join(', ')}`
+          : '';
+      lines.push(
+        `- L${method.line} ${inlineCode(method.signature)} (${method.tokens} tokens)${callSuffix}`
+      );
     }
     return lines.join('\n');
   }
   const lines = [`${entry.path} (score ${score}, ${entry.tokens} tokens)`];
   for (const method of entry.methods) {
-    lines.push(`  ${method.line}: ${method.signature} [${method.tokens} tok]`);
+    const callSuffix =
+      Array.isArray(method.calls) && method.calls.length > 0
+        ? ` -> ${method.calls.join(', ')}`
+        : '';
+    lines.push(`  ${method.line}: ${method.signature} [${method.tokens} tok]${callSuffix}`);
   }
   return lines.join('\n');
 }
@@ -265,6 +303,10 @@ function inlineCode(text) {
 
 function renderJson(graph, ranked, selection, opts) {
   const included = new Set(selection.files.map((file) => file.path));
+  const callEdges = (graph.callEdges || []).map((edge) => ({
+    ...edge,
+    weight: round(edge.weight, 6),
+  }));
   const document = {
     root: graph.root,
     budget: opts.tokens,
@@ -290,9 +332,11 @@ function renderJson(graph, ranked, selection, opts) {
       included: included.has(row.path),
     })),
     edges: graph.edges.map((edge) => ({ ...edge, weight: round(edge.weight, 6) })),
+    callEdges,
     stats: {
       files: graph.stats.files,
       edges: graph.stats.edges,
+      callEdges: graph.stats.callEdges ?? callEdges.length,
       unresolvedImports: graph.stats.unresolvedImports,
       skippedFiles: graph.stats.skipped,
     },
@@ -302,24 +346,28 @@ function renderJson(graph, ranked, selection, opts) {
 
 /**
  * The dependency edges: `a -> b` lines (text), a fenced block (markdown), nodes and edges
- * (json) or a Graphviz digraph (dot)
+ * (json) or a Graphviz digraph (dot). When `options.callGraph` is true, cross-file AST
+ * symbol call edges (`from:caller -> to:callee`) are also included.
  */
-export function renderGraph(graph, ranked, style) {
+export function renderGraph(graph, ranked, style, options = {}) {
+  const includeCalls = Boolean(options.callGraph);
   const weightNote = (edge) => (edge.weight === 1 ? '' : ` (${round(edge.weight, 3)})`);
+  const callEdges = graph.callEdges || [];
+
   if (style === 'json') {
-    return `${JSON.stringify(
-      {
-        root: graph.root,
-        nodes: ranked.map((row) => ({
-          path: row.path,
-          rank: row.rank,
-          score: round(row.score, 6),
-        })),
-        edges: graph.edges.map((edge) => ({ ...edge, weight: round(edge.weight, 6) })),
-      },
-      null,
-      2
-    )}\n`;
+    const payload = {
+      root: graph.root,
+      nodes: ranked.map((row) => ({
+        path: row.path,
+        rank: row.rank,
+        score: round(row.score, 6),
+      })),
+      edges: graph.edges.map((edge) => ({ ...edge, weight: round(edge.weight, 6) })),
+    };
+    if (includeCalls) {
+      payload.callEdges = callEdges.map((edge) => ({ ...edge, weight: round(edge.weight, 6) }));
+    }
+    return `${JSON.stringify(payload, null, 2)}\n`;
   }
   if (style === 'dot') {
     const escape = (value) => value.replace(/["\\]/g, '\\$&');
@@ -335,10 +383,23 @@ export function renderGraph(graph, ranked, style) {
       const attributes = edge.weight === 1 ? '' : ` [weight=${round(edge.weight, 3)}]`;
       lines.push(`  ${quote(edge.from)} -> ${quote(edge.to)}${attributes};`);
     }
+    if (includeCalls) {
+      for (const edge of callEdges) {
+        const callLabel = `"${escape(`${edge.caller}->${edge.callee}`)}"`;
+        lines.push(
+          `  ${quote(edge.from)} -> ${quote(edge.to)} [style=dashed, label=${callLabel}];`
+        );
+      }
+    }
     lines.push('}');
     return `${lines.join('\n')}\n`;
   }
   const lines = graph.edges.map((edge) => `${edge.from} -> ${edge.to}${weightNote(edge)}`);
+  if (includeCalls) {
+    for (const edge of callEdges) {
+      lines.push(`${edge.from}:${edge.caller} -> ${edge.to}:${edge.callee}${weightNote(edge)}`);
+    }
+  }
   if (style === 'markdown') {
     return `# Dependency graph\n\n\`\`\`text\n${lines.join('\n')}${lines.length ? '\n' : ''}\`\`\`\n`;
   }

package/lib/pack/index.js

@@ -95,6 +95,7 @@ function normalizeOptions(options) {
     include: stringList(options.include, 'include'),
     exclude: stringList(options.exclude, 'exclude'),
     files: options.files ? stringList(options.files, 'files') : null,
+    rankOrder: options.rankOrder ? stringList(options.rankOrder, 'rankOrder') : null,
     cwd: options.cwd,
     excludeFiles: stringList(options.excludeFiles, 'excludeFiles'),
     maxFileSize: positiveInteger(options.maxFileSize, 'maxFileSize') ?? DEFAULT_MAX_FILE_SIZE,
@@ -209,6 +210,23 @@ function modelFit(profile, tokens, encoding) {
   };
 }
 
+/**
+ * Order entries according to an explicit priority list, falling back to `rankEntries()`
+ * for any entry not named in `rankOrder`.
+ */
+function orderEntriesByPriority(root, entries, rankOrder) {
+  if (!rankOrder || rankOrder.length === 0) {
+    return rankEntries(root, entries).ranked;
+  }
+  const priority = new Map(rankOrder.map((p, idx) => [p, idx]));
+  const named = entries
+    .filter((entry) => priority.has(entry.path))
+    .sort((a, b) => priority.get(a.path) - priority.get(b.path));
+  const unnamed = entries.filter((entry) => !priority.has(entry.path));
+  if (unnamed.length === 0) return named;
+  return [...named, ...rankEntries(root, unnamed).ranked];
+}
+
 /**
  * Pack the contents of a project's files into one document
  * @param {string} root - Project root
@@ -217,6 +235,7 @@ function modelFit(profile, tokens, encoding) {
  * @param {string[]} [options.include] - Gitignore-style globs: keep only matching files
  * @param {string[]} [options.exclude] - Gitignore-style globs: leave matching files out
  * @param {string[]} [options.files] - Explicit file list instead of scanning the root
+ * @param {string[]} [options.rankOrder] - Explicit priority order for budget trimming
  * @param {string} [options.cwd] - Base for relative `files` entries (default: root)
  * @param {string[]} [options.excludeFiles] - Absolute paths to leave out
  * @param {number} [options.maxFileSize=1048576] - Skip larger files (bytes)
@@ -269,7 +288,7 @@ export async function packContext(root, options = {}) {
   let omitted = [];
   let rendered;
   if (opts.budget) {
-    const { ranked } = rankEntries(selection.root, entries);
+    const ranked = orderEntriesByPriority(selection.root, entries, opts.rankOrder);
     const separator = count('\n\n');
     const wrapperCost = (entry) =>
       opts.style === 'json'

package/lib/pack/select.js

@@ -128,11 +128,14 @@ function isIgnored(scanner, rootPath, relativePath) {
 
 /**
  * An explicit list, in the given order. A path that leaves the root (`..`, an absolute path
- * elsewhere, a symlink pointing out) is an error; files the ignore rules exclude are skipped.
+ * elsewhere, a symlink pointing out) is an error; files the ignore rules or export policy
+ * exclude are skipped.
  */
 function listedFiles(rootPath, entries, cwd, skipped) {
   const realRoot = fs.realpathSync(rootPath);
   const scanner = new Scanner(rootPath);
+  const policy = scanner.getPolicy();
+  scanner.getIgnoreFileRules();
   const files = [];
   const seen = new Set();
   for (const entry of entries) {
@@ -165,6 +168,10 @@ function listedFiles(rootPath, entries, cwd, skipped) {
       skipped.push({ path: relativePath, reason: 'not-a-file' });
       continue;
     }
+    if (policy?.isAuditLog(relative) || scanner.isDenied(relative)) {
+      skipped.push({ path: relativePath, reason: 'denied' });
+      continue;
+    }
     if (isIgnored(scanner, rootPath, relative)) {
       skipped.push({ path: relativePath, reason: 'ignored' });
       continue;

package/lib/parsers/gitignore-parser.js

@@ -43,7 +43,10 @@ class GitIgnoreParser {
     } catch (error) {
       // A directory, or a file that doesn't exist or can't be read
       if (error.code === 'EISDIR') {
-        console.warn(`Warning: ${filePath} is a directory, expected a file`);
+        // Quoted and escaped: a line break in the path cannot start a line of its own
+        console.warn(
+          `Warning: ${JSON.stringify(String(filePath))} is a directory, expected a file`
+        );
       }
       return [];
     }

package/lib/policy/audit.js

@@ -12,7 +12,7 @@ import os from 'os';
 import path from 'path';
 import { execFileSync } from 'child_process';
 import { createRequire } from 'module';
-import { relativePathOf } from './policy.js';
+import { relativePathOf, loadPolicy, DEFAULT_AUDIT_PATH } from './policy.js';
 
 const { version: CTXMAN_VERSION } = createRequire(import.meta.url)('../../package.json');
 
@@ -167,6 +167,24 @@ export function recordExport(policy, event = {}, { warn = defaultWarn } = {}) {
   return record;
 }
 
+/**
+ * The audit logs of a project's policy, or the default location when the policy names none
+ * @param {string} root - Project root
+ * @param {Object} [options]
+ * @param {object} [options.env=process.env] - Environment for loading the policy
+ * @returns {{files: string[], error: Error|null}} `error` when the policy could not be
+ *   loaded (the default location is returned then)
+ */
+export function auditLogFiles(root, { env = process.env } = {}) {
+  try {
+    const policy = loadPolicy(root, { env });
+    if (policy.audit.paths.length > 0) return { files: policy.audit.paths, error: null };
+    return { files: [path.join(root, DEFAULT_AUDIT_PATH)], error: null };
+  } catch (error) {
+    return { files: [path.join(root, DEFAULT_AUDIT_PATH)], error };
+  }
+}
+
 /**
  * Read audit logs. Lines that are not JSON objects are skipped and counted; events that
  * appear in several logs (organisation and project) are listed once.
@@ -252,7 +270,7 @@ export function filterAuditEvents(events, { since = null, limit = null } = {}) {
 const fit = (value, width, { keepEnd = false } = {}) => {
   const text = value === null || value === undefined || value === '' ? '-' : String(value);
   if (text.length <= width) return text.padEnd(width);
-  return keepEnd ? `…${text.slice(-(width - 1))}` : `${text.slice(0, width - 1)}…`;
+  return keepEnd ? `\u2026${text.slice(-(width - 1))}` : `${text.slice(0, width - 1)}\u2026`;
 };
 
 // A file destination inside the exported project is shown relative to it
@@ -271,9 +289,11 @@ const destinationOf = (event) => {
  * @returns {string}
  */
 export function formatAuditTable(events) {
+  const hasRepo = events.some((e) => typeof e?.repo === 'string' && e.repo.length > 0);
   const columns = [
     ['TIME (UTC)', 20, (e) => String(e.timestamp ?? '').replace(/\.\d+Z$/, 'Z')],
     ['RESULT', 8, (e) => e.outcome],
+    ...(hasRepo ? [['REPO', 14, (e) => e.repo]] : []),
     ['USER', 12, (e) => e.user],
     ['COMMAND', 26, (e) => e.command],
     ['DESTINATION', 28, destinationOf, { keepEnd: true }],

package/lib/policy/index.js

@@ -38,6 +38,7 @@ export {
   recordExport,
   buildAuditRecord,
   readAuditLog,
+  auditLogFiles,
   filterAuditEvents,
   formatAuditTable,
   parseSince,
@@ -50,3 +51,8 @@ export {
   loadIgnoreFileRules,
   IgnoreFileRules,
 } from './ignore-files.js';
+export {
+  resolvePolicyWorkspaceDirs,
+  checkWorkspacePolicies,
+  readWorkspaceAuditLogs,
+} from './workspace.js';