diff --git a/gitnexus/src/cli/ai-context.ts b/gitnexus/src/cli/ai-context.ts index d4d6129ea..487a9c23f 100644 --- a/gitnexus/src/cli/ai-context.ts +++ b/gitnexus/src/cli/ai-context.ts @@ -199,7 +199,9 @@ async function fileExists(filePath: string): Promise { async function upsertGitNexusSection( filePath: string, content: string, -): Promise<'created' | 'updated' | 'appended'> { + projectName: string, + stats: RepoStats, +): Promise<'created' | 'updated' | 'appended' | 'preserved'> { const exists = await fileExists(filePath); if (!exists) { @@ -232,18 +234,27 @@ async function upsertGitNexusSection( // custom layout and only update the stats line (node/edge/flow counts). // This lets teams trim the verbose default template to a lean format without // having it overwritten on every `gitnexus analyze`. + // + // Note: the keep-marker check operates on `existingSection` (the substring + // between valid section markers identified by findSectionMarkerIndex), so + // a keep marker in user prose OUTSIDE the GitNexus block has no effect. if (existingSection.includes('')) { - // Match both formats: - // "Indexed as **name** (N symbols, M relationships, P execution flows)" - // "This project is indexed by GitNexus as **name** (N symbols, ...)" - const statsPattern = /(?:Indexed as|indexed by GitNexus as) \*\*[^*]+\*\* \([^)]+\)/; + // Build the new stats line from the caller-provided values directly. + // We do NOT re-extract from `content` because: + // (a) first-bold extraction is fragile if the template evolves + // (b) the parenthesized-text fallback can match unrelated tuples + // like `({target: "symbolName", direction: "upstream"})` + // when noStats is set + // Passing projectName + stats explicitly makes the contract obvious. + const newStatsInner = `${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows`; + const statsLine = `Indexed as **${projectName}** (${newStatsInner})`; - // Extract fresh stats from the newly generated content - const newName = (content.match(/\*\*([^*]+)\*\*/) || [])[1] || 'unknown'; - const newStats = - (content.match(/\((\d[\d,]* symbols[^)]+)\)/) || content.match(/\(([^)]+)\)/) || [])[1] || - '0 nodes'; - const statsLine = `Indexed as **${newName}** (${newStats})`; + // Match either canonical phrasing, anchored to line boundaries (`^`/`$` + // with `m` flag) so we cannot replace prose embedded mid-paragraph like + // "you'll see it Indexed as **Foo** (note: ...)". The trailing period + // / sentence text the generator emits is preserved by sitting outside + // the matched pattern. + const statsPattern = /^(?:Indexed as|indexed by GitNexus as) \*\*[^*]+\*\* \([^)]+\)/m; if (statsPattern.test(existingSection)) { const updatedSection = existingSection.replace(statsPattern, statsLine); @@ -252,8 +263,10 @@ async function upsertGitNexusSection( await fs.writeFile(filePath, (before + updatedSection + after).trim() + '\n', 'utf-8'); return 'updated'; } - // Keep marker present but no stats line found — preserve section as-is - return 'updated'; + // Keep marker present but no stats line matched. Section is preserved + // unchanged on disk; return a distinct status so callers/CLI output + // don't mis-report this as 'updated' (which would imply a write). + return 'preserved'; } // No keep marker — replace existing section with full verbose content @@ -377,12 +390,12 @@ export async function generateAIContextFiles( if (!options?.skipAgentsMd) { // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.) const agentsPath = path.join(repoPath, 'AGENTS.md'); - const agentsResult = await upsertGitNexusSection(agentsPath, content); + const agentsResult = await upsertGitNexusSection(agentsPath, content, projectName, stats); createdFiles.push(`AGENTS.md (${agentsResult})`); // Create CLAUDE.md (for Claude Code) const claudePath = path.join(repoPath, 'CLAUDE.md'); - const claudeResult = await upsertGitNexusSection(claudePath, content); + const claudeResult = await upsertGitNexusSection(claudePath, content, projectName, stats); createdFiles.push(`CLAUDE.md (${claudeResult})`); } else { createdFiles.push('AGENTS.md (skipped via --skip-agents-md)'); diff --git a/gitnexus/test/unit/ai-context.test.ts b/gitnexus/test/unit/ai-context.test.ts index 015d73b1f..bf614b9bd 100644 --- a/gitnexus/test/unit/ai-context.test.ts +++ b/gitnexus/test/unit/ai-context.test.ts @@ -442,4 +442,238 @@ Old content here. await fs.rm(crlfDir, { recursive: true, force: true }); } }); + + // ────────────────────────────────────────────────────────────────── + // Keep-marker edge cases (added to address PR #1508 review findings) + // ────────────────────────────────────────────────────────────────── + + it('keep marker OUTSIDE the GitNexus section has no effect (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-scope-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + // Keep marker appears in user prose BEFORE the GitNexus section. + // The keep-path must NOT be triggered — full template replacement + // is the correct behavior here, because the marker is not inside + // the generated block. + const fileWithOutOfBandMarker = `# My Project + +A note about markers: they only apply inside the +GitNexus block below, not in prose like this. + + +Old verbose stub here. + +`; + await fs.writeFile(claudePath, fileWithOutOfBandMarker, 'utf-8'); + + const stats = { nodes: 50, edges: 100, processes: 5 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'TestProject', stats); + + const result = await fs.readFile(claudePath, 'utf-8'); + // Section MUST have been fully replaced — keep marker outside section ignored + expect(result).toContain('## Always Do'); + expect(result).not.toContain('Old verbose stub here.'); + // User's prose with the marker reference is preserved untouched + expect(result).toContain('A note about markers'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('AGENTS.md keep path preserves custom layout (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-agents-')); + try { + const agentsPath = path.join(dir, 'AGENTS.md'); + const customAgents = `# AGENTS instructions + +Project-specific agent guidance. + + + +# GitNexus context for AGENTS + +Indexed as **AgentsTest** (10 symbols, 20 relationships, 1 execution flows). + +Use 'query' for finding flows, 'context' for symbol details. + +`; + await fs.writeFile(agentsPath, customAgents, 'utf-8'); + + const stats = { nodes: 777, edges: 888, processes: 9 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'AgentsTest', stats); + + const result = await fs.readFile(agentsPath, 'utf-8'); + // Stats updated + expect(result).toContain('777 symbols'); + expect(result).toContain('888 relationships'); + expect(result).toContain('9 execution flows'); + // Custom layout preserved + expect(result).toContain('# GitNexus context for AGENTS'); + expect(result).toContain("Use 'query' for finding flows"); + // Verbose template NOT injected + expect(result).not.toContain('## Always Do'); + // Non-GitNexus content preserved + expect(result).toContain('# AGENTS instructions'); + expect(result).toContain('Project-specific agent guidance.'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('idempotent: second run with keep marker produces byte-identical output (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-idem-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + const seed = `# Project + + + +Indexed as **Idem** (1 symbols, 2 relationships, 3 execution flows). Custom. + +`; + await fs.writeFile(claudePath, seed, 'utf-8'); + + const stats = { nodes: 99, edges: 100, processes: 7 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'Idem', stats); + const afterFirst = await fs.readFile(claudePath, 'utf-8'); + + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'Idem', stats); + const afterSecond = await fs.readFile(claudePath, 'utf-8'); + + expect(afterSecond).toBe(afterFirst); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('CRLF file with keep marker: stats line updates without corrupting content (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-crlf-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + const crlfContent = + '# Project\r\n' + + '\r\n' + + '\r\n' + + '\r\n' + + 'Indexed as **CRLFTest** (5 symbols, 6 relationships, 7 execution flows). Custom CRLF.\r\n' + + '\r\n'; + await fs.writeFile(claudePath, crlfContent, 'utf-8'); + + const stats = { nodes: 50, edges: 60, processes: 7 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'CRLFTest', stats); + + const result = await fs.readFile(claudePath, 'utf-8'); + // Stats updated correctly + expect(result).toContain('50 symbols'); + expect(result).toContain('60 relationships'); + // Custom prose preserved + expect(result).toContain('Custom CRLF'); + // No verbose template injected + expect(result).not.toContain('## Always Do'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('noStats + keep marker: stats line update is NOT corrupted by Always-Do tuple text (#1508 review F3)', async () => { + // Regression guard: with the old fallback regex `\(([^)]+)\)`, when + // noStats=true suppressed the canonical stats line from generated + // content, the fallback matched the FIRST parenthesized text in the + // template, which was `({target: "symbolName", direction: "upstream"})` + // from the Always Do bullet — silently writing that as the stats line. + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-nostats-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + const seed = ` + +Indexed as **NoStatsTest** (1 symbols, 1 relationships, 1 execution flows). Custom. + +`; + await fs.writeFile(claudePath, seed, 'utf-8'); + + const stats = { nodes: 42, edges: 84, processes: 3 }; + await generateAIContextFiles( + dir, + path.join(dir, '.gitnexus'), + 'NoStatsTest', + stats, + undefined, + { noStats: true }, + ); + + const result = await fs.readFile(claudePath, 'utf-8'); + // Stats line MUST NOT have been corrupted with the Always-Do tuple text + expect(result).not.toMatch(/\(\{target:/); + expect(result).not.toMatch(/direction:\s*"upstream"/); + // Stats line should reflect a sensible numeric update (passed stats) + expect(result).toContain('42 symbols'); + // Custom prose still preserved + expect(result).toContain('Custom.'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it("returns 'preserved' (not 'updated') when keep marker is present but no stats line matches (#1508 review F1)", async () => { + // Regression guard for the misleading-return-value bug: previously the + // function returned 'updated' without writing when the keep-section had + // no recognizable stats line, causing CLI output to claim files were + // updated when they were not. + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-noline-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + // Custom keep-section with NO "Indexed as ..." or "indexed by GitNexus as ..." line + const seed = `# Project + + + +# GitNexus block (custom, no stats line) + +This block intentionally omits the standard stats line. + +`; + await fs.writeFile(claudePath, seed, 'utf-8'); + + const stats = { nodes: 100, edges: 200, processes: 10 }; + const result = await generateAIContextFiles( + dir, + path.join(dir, '.gitnexus'), + 'NoLineTest', + stats, + ); + + // The result manifest should reflect 'preserved', not 'updated' + expect(result.files).toContain('CLAUDE.md (preserved)'); + // File on disk is unchanged + const onDisk = await fs.readFile(claudePath, 'utf-8'); + expect(onDisk).toBe(seed); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('project name with markdown-sensitive punctuation lands intact in stats line (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-punct-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + const seed = ` + +Indexed as **placeholder** (1 symbols, 1 relationships, 1 execution flows). Custom. + +`; + await fs.writeFile(claudePath, seed, 'utf-8'); + + // Name with hyphens, dot, and slash — exactly what dp-web4/some-repo + // style names look like + const trickyName = 'dp-web4/some-repo.v2'; + const stats = { nodes: 5, edges: 10, processes: 1 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), trickyName, stats); + + const result = await fs.readFile(claudePath, 'utf-8'); + // The full name appears in the bold of the stats line, intact + expect(result).toContain(`Indexed as **${trickyName}** (5 symbols`); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); });