Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
PRD-8406: Add generated-index union-merge regression tests (#4165)
serafin-garcia13c257f55e8e
diff --git a/docs/content/plugins/okf.mdx b/docs/content/plugins/okf.mdxindex 10a2ad66e..df197ab57 100644--- a/docs/content/plugins/okf.mdx+++ b/docs/content/plugins/okf.mdx@@ -26,7 +26,7 @@ The skill is optional. The plugin's checks are the same with or without it.**Maintain index.md** creates and maintains a navigation file in every folder that contains Markdown, listing that folder's documents by type and linking its subfolders.-Generated indexes are machine-owned: OpenKnowledge rewrites them as documents change, so manual edits are replaced. Turning the setting on shows a disclosure before any files are written. In a Git project it also adds a scoped `.gitattributes` rule (`merge=union`) so concurrent index changes merge cleanly. If another attribute already controls those paths, index maintenance pauses and the plugin page explains what to resolve.+Generated indexes are machine-owned: OpenKnowledge rewrites them as documents change, so manual edits are replaced. Turning the setting on shows a disclosure before any files are written. In a Git project it also adds a scoped `.gitattributes` rule (`merge=union`). A local or CLI merge then combines concurrent index changes instead of conflicting. A merge run on GitHub or GitLab ignores `.gitattributes`, so index changes there can still conflict and need resolving by hand. After a merge across a layout change the combined file can list a document twice until the index is next rebuilt. If another attribute already controls those paths, index maintenance pauses and the plugin page explains what to resolve.Turning it off stops rebuilds and removes the Git rule, but leaves the generated files in place.diff --git a/packages/server/src/server-factory.test.ts b/packages/server/src/server-factory.test.tsindex a1d11aebf..01634f0ef 100644--- a/packages/server/src/server-factory.test.ts+++ b/packages/server/src/server-factory.test.ts@@ -1,3 +1,4 @@+import { spawnSync } from 'node:child_process';import {existsSync,mkdirSync,@@ -12,7 +13,13 @@ import {import { mkdtemp, readFile, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { join, resolve } from 'node:path';-import { LOCAL_DIR, REMOVED_KEYS } from '@inkeep/open-knowledge-core';+import {+ DEFAULT_LINTER_CONFIG,+ type LinterConfig,+ LOCAL_DIR,+ lintDocument,+ REMOVED_KEYS,+} from '@inkeep/open-knowledge-core';import { readConfigSafely, resolveConfigPath } from '@inkeep/open-knowledge-core/server';import simpleGit from 'simple-git';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';@@ -4392,4 +4399,223 @@ describe('createServer() — generated index wiring', () => {expect(statSync(path).mtimeMs).toBe(mtime);}});++ const UNION_FIXTURE_ANCESTOR_INDEX = [+ '---',+ 'okf_version: "0.2"',+ '---',+ '',+ '# Index',+ '',+ '## Guide',+ '',+ '* [Alpha](./alpha.md)',+ '',+ '## Index',+ '',+ '* [Home](./README.md)',+ '',+ ].join('\n');++ const UNION_FIXTURE_OLD_SHAPE_BRANCH_INDEX = [+ '---',+ 'okf_version: "0.2"',+ '---',+ '',+ '# Index',+ '',+ '## Guide',+ '',+ '* [Alpha](./alpha.md)',+ '* [Beta](./beta.md)',+ '',+ '## Index',+ '',+ '* [Home](./README.md)',+ '',+ ].join('\n');++ const UNION_FIXTURE_NEW_SHAPE_BRANCH_INDEX = [+ '---',+ 'okf_version: "0.2"',+ '---',+ '',+ '# Index',+ '',+ '* [Home](./README.md)',+ '',+ '## Guide',+ '',+ '* [Alpha](./alpha.md)',+ '',+ ].join('\n');++ const UNION_FIXTURE_EXPECTED_SWEPT_INDEX = [+ '---',+ 'okf_version: "0.2"',+ '---',+ '',+ '# Index',+ '',+ '* [Home](./README.md)',+ '',+ '## Guide',+ '',+ '* [Alpha](./alpha.md)',+ '* [Beta](./beta.md)',+ '',+ ].join('\n');++ const DEFAULT_PROFILE_LINT_CONFIG: LinterConfig = {+ ...DEFAULT_LINTER_CONFIG,+ enabled: true,+ plugins: {+ ...DEFAULT_LINTER_CONFIG.plugins,+ markdownlint: { ...DEFAULT_LINTER_CONFIG.plugins.markdownlint, enabled: true },+ okf: { enabled: true },+ },+ };++ async function lintIndexCodes(markdown: string): Promise<string[]> {+ const findings = await lintDocument(markdown, DEFAULT_PROFILE_LINT_CONFIG, 'index.md');+ return findings.map((finding) => finding.code);+ }++ function countOccurrences(haystack: string, needle: string): number {+ return haystack.split(needle).length - 1;+ }++ function fixtureGit(...args: string[]): string {+ const result = spawnSync(+ 'git',+ [+ '-c',+ 'user.name=Open Knowledge Test',+ '-c',+ '[email protected]',+ '-c',+ 'commit.gpgsign=false',+ '-c',+ 'core.autocrlf=false',+ '-c',+ 'core.attributesFile=',+ '-c',+ 'core.hooksPath=',+ ...args,+ ],+ { cwd: projectDir, encoding: 'utf-8' },+ );+ const ended = result.signal ? `killed by ${result.signal}` : `exited ${result.status}`;+ expect(+ result.status,+ `git ${args.join(' ')} ${ended}\n${result.stdout ?? ''}${result.stderr ?? ''}${result.error?.message ?? ''}`,+ ).toBe(0);+ return result.stdout ?? '';+ }++ async function commitOldShapeAncestorUnderUnionMerge(): Promise<string> {+ fixtureGit('init', '-q', '--template=');++ const installed = await updateGeneratedIndexGitAttributes({+ projectDir,+ contentDir,+ generatedDocNames: ['index'],+ enabled: true,+ });+ expect(installed.ok).toBe(true);+ expect(installed.status).toEqual({ state: 'ready', ownership: 'open-knowledge' });++ writeDoc('README.md', 'Home', 'Index');+ writeDoc('alpha.md', 'Alpha', 'Guide');+ writeFileSync(indexPath(), UNION_FIXTURE_ANCESTOR_INDEX, 'utf-8');+ fixtureGit('add', '-A');+ fixtureGit('commit', '-qm', 'old-shape ancestor index');++ return fixtureGit('branch', '--show-current').trim();+ }++ test('a union merge across the index layout change leaves a duplicated entry that one boot sweep repairs to canonical bytes', async () => {+ const baseBranch = await commitOldShapeAncestorUnderUnionMerge();++ fixtureGit('checkout', '-q', '-b', 'edits-the-old-shape-index');+ writeDoc('beta.md', 'Beta', 'Guide');+ writeFileSync(indexPath(), UNION_FIXTURE_OLD_SHAPE_BRANCH_INDEX, 'utf-8');+ fixtureGit('add', '-A');+ fixtureGit('commit', '-qm', 'add beta to the old-shape guide section');++ fixtureGit('checkout', '-q', baseBranch);+ writeFileSync(indexPath(), UNION_FIXTURE_NEW_SHAPE_BRANCH_INDEX, 'utf-8');+ fixtureGit('add', '-A');+ fixtureGit('commit', '-qm', 'regenerate the index in the new shape');++ fixtureGit('merge', '--no-edit', '-q', 'edits-the-old-shape-index');++ const merged = readIndex();+ expect(await lintIndexCodes(merged)).toEqual(['MD024']);+ expect(countOccurrences(merged, '* [Home](./README.md)')).toBe(2);+ expect(merged).toContain('## Index');+ expect(UNION_FIXTURE_EXPECTED_SWEPT_INDEX).not.toBe(UNION_FIXTURE_OLD_SHAPE_BRANCH_INDEX);+ expect(UNION_FIXTURE_EXPECTED_SWEPT_INDEX).not.toBe(UNION_FIXTURE_NEW_SHAPE_BRANCH_INDEX);++ const fullSweepDirectories: string[] = [];+ const activeServer = await startServerWithIndexHooks({+ beforeDecision: ({ directory, fullSweep }) => {+ if (fullSweep) fullSweepDirectories.push(directory);+ },+ });+ await activeServer.ready;+ await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({+ status: 'completed',+ indexCount: 1,+ });+ expect(fullSweepDirectories).toEqual(['']);++ const swept = readIndex();+ expect(swept).toBe(UNION_FIXTURE_EXPECTED_SWEPT_INDEX);+ expect(await lintIndexCodes(swept)).toEqual([]);+ });++ test('the layout upgrade alone merges to canonical bytes that the boot sweep leaves unwritten', async () => {+ const logCapture = captureAllLoggers();+ const baseBranch = await commitOldShapeAncestorUnderUnionMerge();++ fixtureGit('checkout', '-q', '-b', 'leaves-the-index-alone');+ writeFileSync(+ join(contentDir, 'alpha.md'),+ '---\ntitle: Alpha\ntype: Guide\n---\n\n# Alpha\n\nRevised prose.\n',+ 'utf-8',+ );+ fixtureGit('add', '-A');+ fixtureGit('commit', '-qm', 'revise alpha without touching the index');++ fixtureGit('checkout', '-q', baseBranch);+ writeDoc('beta.md', 'Beta', 'Guide');+ writeFileSync(indexPath(), UNION_FIXTURE_EXPECTED_SWEPT_INDEX, 'utf-8');+ fixtureGit('add', '-A');+ fixtureGit('commit', '-qm', 'add beta and regenerate the index in the new shape');++ fixtureGit('merge', '--no-edit', '-q', 'leaves-the-index-alone');++ const merged = readIndex();+ expect(merged).toBe(UNION_FIXTURE_EXPECTED_SWEPT_INDEX);++ const bytesBeforeBoot = merged;+ const mtimeBeforeBoot = statSync(indexPath()).mtimeMs;++ const activeServer = await startServerWithIndexHooks({});+ await activeServer.ready;+ await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({+ status: 'completed',+ indexCount: 1,+ });++ expect(+ logCapture+ .getCalls()+ .filter((entry) => entry.payload.event === 'generated-index-regeneration')+ .map((entry) => entry.payload),+ ).toEqual([{ event: 'generated-index-regeneration', outcome: 'unchanged', directory: '' }]);+ expect(readIndex()).toBe(bytesBeforeBoot);+ expect(statSync(indexPath()).mtimeMs).toBe(mtimeBeforeBoot);+ });});