ctxman 3.1.0 → 3.2.7

package/lib/why/render.js

@@ -12,6 +12,8 @@ export const STYLES = ['markdown', 'xml', 'json'];
 /** Sections a budget can shorten */
 export const DROP_ORDER = [
   'patches',
+  'discussions',
+  'citations',
   'related',
   'tests',
   'coupling',
@@ -23,13 +25,15 @@ export const DROP_ORDER = [
 ];
 
 /**
- * What a budget drops, first to last, as [section, items kept at least]. The first five
- * steps follow the documented priority (patches, related text, tests, coupling details,
- * older commits, keeping the newest one); the rest only run when the budget is smaller
- * than the core of the document
+ * What a budget drops, first to last, as [section, items kept at least]. The first six
+ * steps follow the documented priority (patches, remote discussions, related text, tests,
+ * coupling details, older commits, keeping the newest one); the rest only run when the
+ * budget is smaller than the core of the document
  */
 const DROP_STEPS = [
   ['patches', 0],
+  ['discussions', 0],
+  ['citations', 0],
   ['related', 0],
   ['tests', 0],
   ['coupling', 0],
@@ -43,6 +47,8 @@ const DROP_STEPS = [
 
 const OMITTED_LABELS = {
   patches: 'patches',
+  discussions: 'remote discussions',
+  citations: 'institutional citations',
   related: 'related text snippets',
   tests: 'test files',
   coupling: 'co-changed files',
@@ -106,6 +112,8 @@ function flattenReferences(references) {
 export function countItems(data) {
   return {
     patches: data.history.commits.filter((commit) => commit.patch).length,
+    discussions: (data.discussions ?? []).length,
+    citations: (data.institutionalCitations ?? []).length,
     related: data.related.length,
     tests: data.tests.length,
     coupling: data.coupling?.files.length ?? 0,
@@ -162,6 +170,8 @@ export function applyView(data, view) {
     target,
     history: { ...data.history, commits },
     references,
+    discussions: (data.discussions ?? []).slice(0, view.discussions),
+    institutionalCitations: (data.institutionalCitations ?? []).slice(0, view.citations ?? 0),
     ownership: data.ownership && {
       ...data.ownership,
       authors: data.ownership.authors.slice(0, view.ownership),
@@ -293,8 +303,11 @@ function historyDescription(history) {
 
 function renderMarkdown(data, budget) {
   const out = [`# Why: ${title(data.target)}`, ''];
+  const hasDiscussions = (data.discussions?.length ?? 0) > 0 || Boolean(data.omitted?.discussions);
   out.push(
-    'Context for explaining why this code looks the way it does, collected by `ctxman why` from the local git history and the repository (no network).',
+    hasDiscussions
+      ? 'Context for explaining why this code looks the way it does, collected by `ctxman why` from the local git history, repository, and remote issue/PR discussions.'
+      : 'Context for explaining why this code looks the way it does, collected by `ctxman why` from the local git history and the repository (no network).',
     ''
   );
   for (const warning of data.warnings) out.push(`> **Warning:** ${warning}`);
@@ -307,6 +320,8 @@ function renderMarkdown(data, budget) {
     markdownTarget,
     markdownHistory,
     markdownReferences,
+    markdownDiscussions,
+    markdownCitations,
     markdownOwnership,
     markdownCoupling,
     markdownRelated,
@@ -320,8 +335,11 @@ function renderMarkdown(data, budget) {
   return out.join('\n');
 }
 
-function markdownTarget({ target, repository, omitted }) {
+function markdownTarget({ target, repository, repos, omitted }) {
   const out = ['## Target', '', `- File: ${code(target.path)}`];
+  if (Array.isArray(repos) && repos.length > 0) {
+    out.push(`- Workspace repositories: ${repos.map((r) => code(r.alias)).join(', ')}`);
+  }
   if (target.symbol) {
     const line = target.line ? `, declared on line ${target.line}` : '';
     out.push(`- Symbol: ${code(target.symbol)} (${target.kind}${line})`);
@@ -372,7 +390,7 @@ function markdownHistory({ history, omitted }) {
       );
     }
     if (commit.refs?.length) meta.push(`refs: ${commit.refs.join(', ')}`);
-    out.push(meta.join(' · '));
+    out.push(meta.join(' \u00b7 '));
     if (commit.body) {
       out.push('', commit.body.replace(/^/gm, '> ').replace(/^> $/gm, '>'));
     }
@@ -407,6 +425,68 @@ function markdownReferences({ references, history, omitted }) {
   return out;
 }
 
+function markdownDiscussions({ discussions = [], omitted }) {
+  if (!discussions.length) return [];
+  const out = ['## Discussions', ''];
+  for (const item of discussions) {
+    const label = { pr: 'Pull request', mr: 'Merge request' }[item.kind] ?? 'Issue';
+    const titleText = item.title ? `: ${item.title}` : '';
+    out.push(`### ${label} ${item.id}${titleText}`, '');
+    const meta = [item.state, item.author ? `@${item.author}` : null, day(item.createdAt)].filter(
+      Boolean
+    );
+    if (item.labels?.length) meta.push(`labels: ${item.labels.join(', ')}`);
+    if (item.commits?.length) meta.push(`commits: ${item.commits.join(', ')}`);
+    if (item.url) meta.push(item.url);
+    out.push(meta.join(' \u00b7 '));
+    if (item.body) {
+      out.push('', item.body.replace(/^/gm, '> ').replace(/^> $/gm, '>'));
+    }
+    if (item.comments?.length) {
+      out.push('', 'Comments:');
+      for (const comment of item.comments) {
+        const header = `@${comment.author}${comment.createdAt ? ` (${day(comment.createdAt)})` : ''}`;
+        const singleLine = comment.body.replace(/\n+/g, ' ');
+        out.push(`- **${header}:** ${singleLine}`);
+      }
+    }
+    out.push('');
+  }
+  if (out.at(-1) === '') out.pop();
+  if (omitted.discussions) {
+    out.push(
+      '',
+      `_${omitted.discussions} remote discussion(s) not shown to fit the token budget._`
+    );
+  }
+  return out;
+}
+
+function markdownCitations({ institutionalCitations, omitted }) {
+  if (!institutionalCitations || !institutionalCitations.length) return [];
+  const out = ['## Institutional Citations (Analyzer)', ''];
+  for (const item of institutionalCitations) {
+    const meta = [item.kind];
+    if (item.author) meta.push(`@${item.author}`);
+    if (item.timestamp) meta.push(day(item.timestamp));
+    if (item.url) meta.push(item.url);
+    out.push(`- **${item.title}** (${meta.join(' · ')}):`);
+    if (item.snippet) {
+      out.push(`  > ${item.snippet.replace(/\n+/g, ' ')}`);
+    }
+    if (item.refs && item.refs.length) {
+      out.push(`  *Refs: ${item.refs.join(', ')}*`);
+    }
+  }
+  if (omitted?.citations) {
+    out.push(
+      '',
+      `_${omitted.citations} institutional citation(s) not shown to fit the token budget._`
+    );
+  }
+  return out;
+}
+
 function markdownOwnership({ ownership, omitted }) {
   if (!ownership || !ownership.authors.length) return [];
   const scope =
@@ -427,7 +507,7 @@ function markdownOwnership({ ownership, omitted }) {
       `| ${name} | ${author.lines} | ${percent(author.share)} | ${author.commits} | ${day(author.lastTouched)} |`
     );
   }
-  if (omitted.ownership) out.push(`| … ${omitted.ownership} more | | | | |`);
+  if (omitted.ownership) out.push(`| \u2026 ${omitted.ownership} more | | | | |`);
   return out;
 }
 
@@ -452,7 +532,7 @@ function markdownCoupling({ coupling, target, omitted }) {
     const gone = file.exists === false ? ' (no longer in the tree)' : '';
     out.push(`| ${code(file.path)}${gone} | ${file.count} | ${percent(file.confidence)} |`);
   }
-  if (omitted.coupling) out.push(`| … ${omitted.coupling} more | | |`);
+  if (omitted.coupling) out.push(`| \u2026 ${omitted.coupling} more | | |`);
   return out;
 }
 
@@ -534,6 +614,13 @@ function attributes(values) {
 function renderXml(data, budget) {
   const { target, history } = data;
   const out = ['<why_context generator="ctxman why">'];
+  if (Array.isArray(data.repos) && data.repos.length > 0) {
+    out.push('<repositories>');
+    for (const repo of data.repos) {
+      out.push(`<repo${attributes({ alias: repo.alias, root: repo.root })}/>`);
+    }
+    out.push('</repositories>');
+  }
   if (Object.keys(data.omitted).length) {
     out.push(`<trimmed${attributes({ budget, ...data.omitted })}/>`);
   }
@@ -617,6 +704,64 @@ function renderXml(data, budget) {
   }
   out.push('</references>');
 
+  if ((data.discussions?.length ?? 0) > 0) {
+    out.push('<discussions>');
+    for (const item of data.discussions) {
+      out.push(
+        `<discussion${attributes({
+          id: item.id,
+          number: item.number,
+          repo: item.repo,
+          provider: item.provider,
+          kind: item.kind,
+          state: item.state,
+          author: item.author,
+          created_at: item.createdAt,
+          url: item.url,
+          labels: item.labels,
+          commits: item.commits,
+        })}>`
+      );
+      if (item.title) out.push(`<title>${xml(item.title)}</title>`);
+      if (item.body) out.push(`<body>${xml(item.body)}</body>`);
+      for (const comment of item.comments ?? []) {
+        out.push(
+          `<comment${attributes({
+            author: comment.author,
+            created_at: comment.createdAt,
+          })}>${xml(comment.body)}</comment>`
+        );
+      }
+      out.push('</discussion>');
+    }
+    out.push('</discussions>');
+  }
+
+  if ((data.institutionalCitations?.length ?? 0) > 0) {
+    out.push('<institutional_citations>');
+    for (const item of data.institutionalCitations) {
+      out.push(
+        `<citation${attributes({
+          id: item.id,
+          kind: item.kind,
+          title: item.title,
+          url: item.url,
+          author: item.author,
+          timestamp: item.timestamp,
+          score: item.score,
+        })}>`
+      );
+      if (item.snippet) out.push(`<snippet>${xml(item.snippet)}</snippet>`);
+      if (item.refs?.length) {
+        for (const ref of item.refs) {
+          out.push(`<ref>${xml(ref)}</ref>`);
+        }
+      }
+      out.push('</citation>');
+    }
+    out.push('</institutional_citations>');
+  }
+
   if (data.ownership) {
     const own = data.ownership;
     out.push(

package/lib/wizards/config-generator.js

@@ -81,37 +81,39 @@ class ConfigGenerator {
       }
 
       const filePath = path.join(this.projectRoot, filename);
-      const exists = fs.existsSync(filePath);
-
-      // Check if should skip
-      if (exists && !force) {
+      const skip = () =>
         result.skipped.push({
           type,
           filename,
           reason: 'File already exists (use --force to overwrite)',
         });
-        continue;
-      }
-
-      // Generate file content
-      const content = this.generateFileContent(type, patterns);
 
       if (dryRun) {
-        if (exists) {
-          result.overwritten.push({ type, filename, content });
-        } else {
-          result.created.push({ type, filename, content });
+        const exists = fs.existsSync(filePath);
+        if (exists && !force) {
+          skip();
+          continue;
         }
+        const content = this.generateFileContent(type, patterns);
+        (exists ? result.overwritten : result.created).push({ type, filename, content });
         continue;
       }
 
-      // Write file
+      const content = this.generateFileContent(type, patterns);
+      // Create exclusively first, so an existing file is found by the write itself rather
+      // than by a separate check that could be out of date
       try {
-        fs.writeFileSync(filePath, content, 'utf-8');
-        if (exists) {
-          result.overwritten.push({ type, filename });
-        } else {
+        try {
+          fs.writeFileSync(filePath, content, { encoding: 'utf-8', flag: 'wx' });
           result.created.push({ type, filename });
+        } catch (error) {
+          if (error.code !== 'EEXIST') throw error;
+          if (!force) {
+            skip();
+            continue;
+          }
+          fs.writeFileSync(filePath, content, 'utf-8');
+          result.overwritten.push({ type, filename });
         }
       } catch (error) {
         result.errors.push({

package/lib/wizards/project-detector.js

@@ -514,7 +514,8 @@ class ProjectDetector {
    * @returns {boolean} True if matches
    */
   matchesGlob(filename, pattern) {
-    const regex = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*');
+    // Every regex character is literal except `*`, which matches any run of characters
+    const regex = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
     return new RegExp(`^${regex}$`).test(filename);
   }