@gitset-dev/cli 2.3.2 → 2.4.0

package/lib/knowledge/write.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const DOC_SPECS = [
+  {
+    id: 'architecture',
+    filename: 'architecture.md',
+    title: 'Architecture',
+    llm: true,
+    sections: [
+      'System Overview',
+      'Entry Points',
+      'Core Components',
+      'Data Flow',
+      'External Dependencies',
+    ],
+    guidance: 'Core Components: one bullet per module with a one-line role — no per-file listings and no tables (module-map.md already covers per-file detail). Data Flow: a numbered list of at most 8 steps.',
+  },
+  {
+    id: 'developer-guide',
+    filename: 'developer-guide.md',
+    title: 'Developer Guide',
+    llm: true,
+    sections: [
+      'Prerequisites',
+      'Setup',
+      'Project Layout',
+      'Testing',
+      'Release & Deployment',
+    ],
+    guidance: 'Project Layout: at most 6 bullet lines describing the top-level directories — never a module table, module-map.md already covers that. Every section must be short and practical; this is an onboarding page, not a reference.',
+  },
+  {
+    id: 'commands-and-workflows',
+    filename: 'commands-and-workflows.md',
+    title: 'Commands & Workflows',
+    llm: true,
+    sections: [
+      'Package Scripts',
+      'CLI Commands',
+      'CI Workflows',
+      'Common Tasks',
+    ],
+    guidance: 'CLI Commands: bullets in the form `command` — one-line description, using only registered command names from the digest. Do not cite source file paths in this document.',
+  },
+];
+
+const AGENTS_START = '<!-- gitset-knowledge:start -->';
+const AGENTS_END = '<!-- gitset-knowledge:end -->';
+
+function buildStructuralDigest(map, files) {
+  const lines = [];
+  if (map.manifest) {
+    const m = map.manifest;
+    lines.push(`Project: ${m.name || 'unknown'}${m.version ? ` v${m.version}` : ''}`);
+    if (m.description) lines.push(`Description: ${m.description}`);
+    if (m.bin) lines.push(`Binaries: ${typeof m.bin === 'string' ? m.bin : Object.entries(m.bin).map(([k, v]) => `${k} -> ${v}`).join(', ')}`);
+    if (m.engines) lines.push(`Engines: ${JSON.stringify(m.engines)}`);
+    if (m.packageManager) lines.push(`Package manager: ${m.packageManager}`);
+    const scripts = Object.entries(m.scripts || {});
+    if (scripts.length) {
+      lines.push('Package scripts:');
+      for (const [name, cmd] of scripts) lines.push(`  ${name}: ${cmd}`);
+    }
+  }
+  if (map.entryPoints.length) lines.push(`Entry points: ${map.entryPoints.join(', ')}`);
+  if (map.registeredCommands && map.registeredCommands.length) {
+    lines.push(`CLI commands registered in the entry point (authoritative names): ${map.registeredCommands.join(', ')}`);
+  }
+
+  lines.push('Modules:');
+  for (const mod of map.modules) {
+    lines.push(`  ${mod.name} — ${mod.sourceCount} source, ${mod.testCount} test, ${mod.docCount} doc files`);
+  }
+
+  if (map.moduleEdges.length) {
+    lines.push('Module dependencies (imports between modules):');
+    for (const { edge, count } of map.moduleEdges) lines.push(`  ${edge} (${count})`);
+  }
+
+  if (map.externalDeps.length) {
+    const top = map.externalDeps.slice(0, 15).map((d) => `${d.name} (${d.count})`).join(', ');
+    lines.push(`External packages imported in code: ${top}`);
+  }
+
+  const workflows = files.filter((f) => /^\.github\/workflows\//.test(f.path)).map((f) => f.path);
+  if (workflows.length) lines.push(`CI workflow files: ${workflows.join(', ')}`);
+
+  const central = [...map.centrality.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, 10)
+    .map(([p, n]) => `${p} (imported by ${n})`);
+  if (central.length) lines.push(`Most imported files: ${central.join(', ')}`);
+
+  return lines.join('\n');
+}
+
+function buildSummarizeFilesBlock(batchFiles) {
+  return batchFiles
+    .map((f) => `FILE: ${f.path} [${f.mode}${f.centrality ? `, imported by ${f.centrality}` : ''}]\n${f.content}`)
+    .join('\n\n---\n\n');
+}
+
+function parseSummarizeResponse(text) {
+  let cleaned = String(text || '').trim()
+    .replace(/^```(?:json)?\n?/i, '')
+    .replace(/\n?```$/i, '')
+    .trim();
+  const start = cleaned.indexOf('[');
+  const end = cleaned.lastIndexOf(']');
+  if (start === -1 || end === -1 || end <= start) return null;
+  try {
+    const parsed = JSON.parse(cleaned.slice(start, end + 1));
+    if (!Array.isArray(parsed)) return null;
+    const entries = parsed
+      .filter((e) => e && typeof e.path === 'string')
+      .map((e) => ({
+        path: e.path,
+        purpose: typeof e.purpose === 'string' ? e.purpose : '',
+        exports: Array.isArray(e.exports) ? e.exports.map(String).slice(0, 20) : [],
+        dependencies: Array.isArray(e.dependencies) ? e.dependencies.map(String).slice(0, 20) : [],
+        notes: typeof e.notes === 'string' ? e.notes : '',
+      }));
+    return entries.length ? entries : null;
+  } catch {
+    return null;
+  }
+}
+
+function summariesToText(moduleSummaries) {
+  const blocks = [];
+  for (const modName of Object.keys(moduleSummaries).sort()) {
+    const entries = moduleSummaries[modName];
+    blocks.push(`MODULE: ${modName}`);
+    if (typeof entries === 'string') {
+      blocks.push(entries);
+      continue;
+    }
+    for (const e of entries) {
+      const parts = [`- ${e.path}: ${e.purpose}`];
+      if (e.exports && e.exports.length) parts.push(`  exports: ${e.exports.join(', ')}`);
+      if (e.notes) parts.push(`  notes: ${e.notes}`);
+      blocks.push(parts.join('\n'));
+    }
+  }
+  return blocks.join('\n');
+}
+
+function renderIndexDoc({ map, files, tag, validationSummary }) {
+  const stats = {
+    total: files.length,
+    source: files.filter((f) => f.kind === 'source').length,
+    test: files.filter((f) => f.kind === 'test').length,
+    config: files.filter((f) => f.kind === 'config').length,
+    doc: files.filter((f) => f.kind === 'doc').length,
+  };
+  const name = (map.manifest && map.manifest.name) || '(unnamed project)';
+  const description = (map.manifest && map.manifest.description) || '';
+  const lines = [
+    `# ${name} — Knowledge Base`,
+    '',
+    description,
+    '',
+    `> Generated by [Gitset](https://gitset.dev) Knowledge Mapper${tag ? ` at ${tag}` : ''}. Derived from source code, manifests and CI configuration — not from existing prose docs.`,
+    '',
+    '## Contents',
+    '',
+    '- [Architecture](architecture.md) — system design, entry points, data flow',
+    '- [Developer Guide](developer-guide.md) — setup, testing, release',
+    '- [Commands & Workflows](commands-and-workflows.md) — scripts, CLI commands, CI',
+    '- [Module Map](module-map.md) — per-module summaries and dependency edges',
+    '',
+    '## Repository Stats',
+    '',
+    `| Files | Source | Tests | Config | Docs |`,
+    `| ---: | ---: | ---: | ---: | ---: |`,
+    `| ${stats.total} | ${stats.source} | ${stats.test} | ${stats.config} | ${stats.doc} |`,
+    '',
+    map.entryPoints.length ? `Entry points: ${map.entryPoints.map((e) => `\`${e}\``).join(', ')}` : '',
+    '',
+  ];
+  if (validationSummary) {
+    lines.push(`Validation: ${validationSummary}`, '');
+  }
+  return `${lines.filter((l) => l !== null).join('\n').replace(/\n{3,}/g, '\n\n').trim()}\n`;
+}
+
+function renderModuleMapDoc({ map, moduleSummaries }) {
+  const lines = ['# Module Map', ''];
+  lines.push('## Modules', '');
+  for (const mod of map.modules) {
+    lines.push(`### \`${mod.name}\``, '');
+    const summary = moduleSummaries[mod.name];
+    if (typeof summary === 'string') {
+      lines.push(summary.trim(), '');
+    } else if (Array.isArray(summary)) {
+      for (const e of summary) {
+        lines.push(`- \`${e.path}\` — ${e.purpose || 'no summary'}`);
+        if (e.exports && e.exports.length) lines.push(`  - exports: ${e.exports.map((x) => `\`${x}\``).join(', ')}`);
+        if (e.notes) lines.push(`  - ${e.notes}`);
+      }
+      lines.push('');
+    } else {
+      const shown = mod.files.filter((f) => f.kind !== 'doc').slice(0, 30);
+      for (const f of shown) lines.push(`- \`${f.path}\` (${f.kind})`);
+      lines.push('');
+    }
+  }
+  if (map.moduleEdges.length) {
+    lines.push('## Dependency Edges', '');
+    lines.push('| From | To | Imports |', '| :--- | :--- | ---: |');
+    for (const { edge, count } of map.moduleEdges) {
+      const [from, to] = edge.split(' -> ');
+      lines.push(`| \`${from}\` | \`${to}\` | ${count} |`);
+    }
+    lines.push('');
+  }
+  if (map.externalDeps.length) {
+    lines.push('## External Packages (imported in code)', '');
+    for (const dep of map.externalDeps.slice(0, 25)) {
+      lines.push(`- \`${dep.name}\` (${dep.count} import${dep.count === 1 ? '' : 's'})`);
+    }
+    lines.push('');
+  }
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trim()}\n`;
+}
+
+function buildAgentsBlock() {
+  return [
+    AGENTS_START,
+    '## Repository knowledge base',
+    '',
+    'Structural context for this repository is maintained by [Gitset](https://gitset.dev) Knowledge Mapper.',
+    'Before making changes, read:',
+    '',
+    '- [docs/gitset-knowledge/index.md](docs/gitset-knowledge/index.md)',
+    '- [docs/gitset-knowledge/architecture.md](docs/gitset-knowledge/architecture.md)',
+    '- [docs/gitset-knowledge/module-map.md](docs/gitset-knowledge/module-map.md)',
+    AGENTS_END,
+  ].join('\n');
+}
+
+function applyAgentsPointer(existingContent) {
+  const block = buildAgentsBlock();
+  if (!existingContent || !existingContent.trim()) {
+    return { content: `# AGENTS.md\n\n${block}\n`, action: 'created' };
+  }
+  const markerRe = new RegExp(`${AGENTS_START}[\\s\\S]*?${AGENTS_END}`);
+  if (markerRe.test(existingContent)) {
+    return { content: existingContent.replace(markerRe, block), action: 'updated' };
+  }
+  return { content: `${existingContent.replace(/\n*$/, '\n\n')}${block}\n`, action: 'appended' };
+}
+
+module.exports = {
+  DOC_SPECS,
+  AGENTS_START,
+  AGENTS_END,
+  buildStructuralDigest,
+  buildSummarizeFilesBlock,
+  parseSummarizeResponse,
+  summariesToText,
+  renderIndexDoc,
+  renderModuleMapDoc,
+  buildAgentsBlock,
+  applyAgentsPointer,
+};

package/lib/prompts/defaults.js

@@ -98,7 +98,13 @@ const release = {
         'headings, ordering, and tone closely — treat it as the format to reproduce. ' +
         'Never invent a repository path (e.g. placeholders like "your-project/your-repo" ' +
         'or "user/repo") for a "Full Changelog" or compare link — only include such a link ' +
-        'when the real repository is given below, using that exact path; otherwise omit it.',
+        'when the real repository is given below, using that exact path; otherwise omit it. ' +
+        'Never attribute a change to a person (e.g. "by @username") — a commit author\'s ' +
+        'display name (e.g. "Jane Smith") is NOT their GitHub username and must never be ' +
+        'guessed into one (e.g. never invent "@jane-smith"). If a commit message already ' +
+        'ends in a real PR reference like "(#123)", you may link directly to that PR using ' +
+        'the given repository path (e.g. https://github.com/<repo>/pull/123), but state only ' +
+        'what changed — no author mention.',
       user: [
         repo && `Repository: ${clip(repo, 200)}`,
         tag && `Release: ${clip(tag, 100)}`,
@@ -129,6 +135,74 @@ const about = {
   },
 };
 
+const knowledgeSummarize = {
+  id: 'knowledgeSummarize',
+  build(ctx = {}) {
+    const { repo = '', module = '', files = '' } = ctx;
+    return {
+      system:
+        'You are a code cartographer producing structured file summaries for a ' +
+        'repository knowledge base consumed by AI agents and developers. Describe ' +
+        'ONLY what is present in the provided file contents — if something is not ' +
+        'visible in the input, do not claim it. Never invent file paths, exports, ' +
+        'or behavior. Respond with ONLY a valid JSON array, no prose, no code ' +
+        'fences: [{"path": string, "purpose": string (<= 220 chars, concrete and ' +
+        'specific), "exports": string[] (ONLY values the file actually exports/' +
+        'exposes — module.exports, export statements, __all__; an executable or ' +
+        'script with no exports gets [], never its internal functions; max 12), ' +
+        '"dependencies": string[] (notable internal files or external ' +
+        'packages this file relies on, max 10), "notes": string (<= 160 chars — ' +
+        'gotchas, side effects, or "" if none)}]. One entry per FILE block in the ' +
+        'input, using the exact path given. For a dispatcher/entry-point file, ' +
+        'note in "notes" the exact command or route names it registers.',
+      user: [
+        repo && `Repository: ${clip(repo, 200)}`,
+        module && `Module: ${clip(module, 200)}`,
+        `Files:\n\n${clip(files, 30000)}`,
+      ].filter(Boolean).join('\n\n'),
+    };
+  },
+};
+
+const knowledgeWrite = {
+  id: 'knowledgeWrite',
+  build(ctx = {}) {
+    const { repo = '', doc = '', sections = '', guidance = '', digest = '', summaries = '' } = ctx;
+    return {
+      system:
+        'You write one Markdown document of a repository knowledge base optimized ' +
+        'for AI agents and developers: dense, factual, skimmable. Ground every ' +
+        'statement in the structural digest and file summaries provided — never ' +
+        'cite a file path, command, script, or dependency that does not appear in ' +
+        'the input. If the input lacks information for a section, write what is ' +
+        'known and omit speculation entirely. Use the exact section headings ' +
+        'requested, as "## " headings, in the given order — every requested ' +
+        'section must appear. Start directly with ' +
+        'the "# " title line — no preamble, no sign-off, no code fences around ' +
+        'the document. Keep it concise: prefer tables and short bullet lists ' +
+        'over paragraphs. In Markdown tables, keep every cell compact with a ' +
+        'single space around each pipe (| Cell | Cell |) — never pad columns ' +
+        'with runs of spaces to align them. When referring to a repository file, format it as a ' +
+        'relative markdown link from docs/gitset-knowledge/ (e.g. ' +
+        '[src/x.js](../../src/x.js)) — the link target is the file path prefixed ' +
+        'with ../../, never a repeated or altered filename. When documenting CLI ' +
+        'commands or routes, use the exact names the dispatcher/entry point ' +
+        'registers (from the summaries/digest), never names derived from file ' +
+        'names. End the document immediately after the last line of the final ' +
+        'requested section — no trailing blank lines, separators, or repeated ' +
+        'characters of any kind.',
+      user: [
+        repo && `Repository: ${clip(repo, 200)}`,
+        `Document to write: ${clip(doc, 200)}`,
+        sections && `Required sections, in order: ${clip(sections, 500)}`,
+        guidance && `Section guidance (follow strictly): ${clip(guidance, 1000)}`,
+        digest && `Structural digest (ground truth):\n${clip(digest, 12000)}`,
+        summaries && `File summaries (ground truth):\n${clip(summaries, 40000)}`,
+      ].filter(Boolean).join('\n\n'),
+    };
+  },
+};
+
 const gitignore = {
   id: 'gitignore',
   build(ctx = {}) {
@@ -192,4 +266,4 @@ const labelDescriptions = {
   },
 };
 
-module.exports = { commit, issue, pr, readme, release, about, gitignore, labels, labelDescriptions };
+module.exports = { commit, issue, pr, readme, release, about, gitignore, labels, labelDescriptions, knowledgeSummarize, knowledgeWrite };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitset-dev/cli",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Gitset CLI — drafts commits, PRs, issues, READMEs and release notes with your own AI key. Fully local: your code and keys never touch a Gitset server. Draft. Refine. Ship.",
   "type": "commonjs",
   "bin": {