@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/_test/run-all-tests.js

@@ -1,161 +1,173 @@
-// _site/_test/run-all-tests.js
-//
-// Single-command regression suite runner. Iterates the canonical test files
-// under _site/_test/ (everything matching *-test.js) and runs each one in a
-// separate child process, capturing exit code, duration, and the last few
-// lines of output. Writes a Markdown report to TEST-REPORT.md.
-//
-// Usage:
-//   node _site/_test/run-all-tests.js                  # run all *-test.js
-//   node _site/_test/run-all-tests.js --no-report      # do not write report
-//
-// Exit code is 0 only if every test passes.
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const TEST_DIR = __dirname;
-const REPORT_PATH = path.join(TEST_DIR, 'TEST-REPORT.md');
-
-const args = process.argv.slice(2);
-const WRITE_REPORT = !args.includes('--no-report');
-const BACKEND_ONLY = args.includes('--backend-only');
-const PER_TEST_TIMEOUT_MS = Number(process.env.PK_TEST_TIMEOUT_MS || 90_000);
-
-function listTestFiles() {
-  return fs.readdirSync(TEST_DIR)
-    .filter(file => file.endsWith('-test.js'))
-    .filter(file => file !== 'run-all-tests.js')
-    .filter(file => !BACKEND_ONLY || !fs.readFileSync(path.join(TEST_DIR, file), 'utf8').includes('helpers/cdp-browser'))
-    .sort();
-}
-
-function tail(text, lines = 12) {
-  const arr = String(text || '').split(/\r?\n/).filter(Boolean);
-  return arr.slice(-lines).join('\n');
-}
-
-function classifyFailure(result) {
-  if (result.status !== null) {
-    return { kind: 'exit', label: `FAIL (exit ${result.status})` };
-  }
-  if (result.error && result.error.code === 'ETIMEDOUT') {
-    return { kind: 'timeout', label: `TIMEOUT (killed after ${PER_TEST_TIMEOUT_MS}ms, signal ${result.signal || 'none'})` };
-  }
-  const code = result.error && result.error.code ? result.error.code : 'unknown';
-  return { kind: 'error', label: `FAIL (spawn error ${code}, signal ${result.signal || 'none'})` };
-}
-
-function runOne(file) {
-  const start = Date.now();
-  // Every test child gets its own Bridge journal sandbox so hook-trigger /
-  // server runtimes never touch the developer's ~/.ai-coding-event-bridge.
-  const bridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-bridge-${process.pid}-`));
-  const dataHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-data-${process.pid}-`));
-  const result = spawnSync(process.execPath, [path.join(TEST_DIR, file)], {
-    cwd: ROOT,
-    encoding: 'utf-8',
-    timeout: PER_TEST_TIMEOUT_MS,
-    env: { ...process.env, FORCE_COLOR: '0', KB_DATA_DIR: dataHome, AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' },
-  });
-  try { fs.rmSync(bridgeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
-  try { fs.rmSync(dataHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
-  const failure = result.status === 0 ? null : classifyFailure(result);
-  return {
-    file,
-    passed: result.status === 0,
-    failureKind: failure ? failure.kind : null,
-    failureLabel: failure ? failure.label : null,
-    exitCode: result.status,
-    signal: result.signal,
-    spawnErrorCode: result.error && result.error.code ? result.error.code : null,
-    durationMs: Date.now() - start,
-    stdout: result.stdout || '',
-    stderr: result.stderr || '',
-    outputTail: tail(`${result.stdout || ''}\n${result.stderr || ''}`.trim()),
-  };
-}
-
-(async () => {
-  const files = listTestFiles();
-  if (BACKEND_ONLY) console.log('Backend/contract scope only. Browser tests are excluded, not passed.');
-  console.log(`Running ${files.length} test file(s)...\n`);
-
-  const results = [];
-  let totalDuration = 0;
-  for (const file of files) {
-    process.stdout.write(`> ${file} ... `);
-    const result = runOne(file);
-    totalDuration += result.durationMs;
-    results.push(result);
-
-    if (result.passed) {
-      console.log(`PASS (${result.durationMs}ms)`);
-    } else {
-      console.log(`${result.failureLabel}, ${result.durationMs}ms`);
-      if (result.outputTail) {
-        console.log('--- tail ---');
-        console.log(result.outputTail);
-        console.log('--- end tail ---');
-      }
-    }
-  }
-
-  const passed = results.filter(result => result.passed).length;
-  const failed = results.length - passed;
-  console.log('\n=========================================');
-  console.log(`Regression suite: ${passed} passed, ${failed} failed (${totalDuration}ms total)`);
-  console.log('=========================================\n');
-
-  if (WRITE_REPORT) {
-    const lines = [];
-    lines.push('# KB Management Site Regression Test Report');
-    lines.push('');
-    lines.push(`**Generated**: ${new Date().toISOString()}`);
-    lines.push(`**Node**: ${process.version}`);
-    lines.push('**Runner**: node _site/_test/run-all-tests.js');
-    lines.push('');
-    lines.push('## Summary');
-    lines.push('');
-    lines.push(`**Per-test timeout**: ${PER_TEST_TIMEOUT_MS}ms (override with PK_TEST_TIMEOUT_MS)`);
-    lines.push('');
-    lines.push('| # | File | Status | Exit | Duration |');
-    lines.push('|--:|------|:------:|-----:|---------:|');
-    results.forEach((result, index) => {
-      const status = result.passed ? 'PASS' : (result.failureKind === 'timeout' ? 'TIMEOUT' : 'FAIL');
-      const exit = result.passed
-        ? String(result.exitCode)
-        : `${result.exitCode}${result.signal ? `, signal ${result.signal}` : ''}${result.spawnErrorCode ? `, error ${result.spawnErrorCode}` : ''}`;
-      lines.push(`| ${index + 1} | \`${result.file}\` | ${status} | ${exit} | ${result.durationMs}ms |`);
-    });
-    lines.push('');
-    lines.push(`**Total**: ${results.length} | **Passed**: ${passed} | **Failed**: ${failed} | **Time**: ${totalDuration}ms`);
-    lines.push('');
-
-    const failures = results.filter(result => !result.passed);
-    if (failures.length) {
-      lines.push('## Failures');
-      lines.push('');
-      for (const result of failures) {
-        lines.push(`### ${result.file}`);
-        lines.push('');
-        lines.push('```');
-        lines.push(result.outputTail);
-        lines.push('```');
-        lines.push('');
-      }
-    }
-
-    try {
-      fs.writeFileSync(REPORT_PATH, lines.join('\n'), 'utf-8');
-      console.log(`Report written to: ${REPORT_PATH}`);
-    } catch (e) {
-      console.error(`Failed to write report: ${e.message}`);
-    }
-  }
-
-  process.exit(failed > 0 ? 1 : 0);
-})();
+// _site/_test/run-all-tests.js
+//
+// Single-command regression suite runner. Iterates the canonical test files
+// under _site/_test/ (everything matching *-test.js) and runs each one in a
+// separate child process, capturing exit code, duration, and the last few
+// lines of output. Writes a Markdown report to TEST-REPORT.md.
+//
+// Usage:
+//   node _site/_test/run-all-tests.js                  # run all *-test.js
+//   node _site/_test/run-all-tests.js --no-report      # do not write report
+//
+// Exit code is 0 only if every test passes.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TEST_DIR = __dirname;
+const REPORT_PATH = path.join(TEST_DIR, 'TEST-REPORT.md');
+
+const args = process.argv.slice(2);
+const WRITE_REPORT = !args.includes('--no-report');
+const BACKEND_ONLY = args.includes('--backend-only');
+const PER_TEST_TIMEOUT_MS = Number(process.env.PK_TEST_TIMEOUT_MS || 90_000);
+
+function listTestFiles() {
+  return fs.readdirSync(TEST_DIR)
+    .filter(file => file.endsWith('-test.js'))
+    .filter(file => file !== 'run-all-tests.js')
+    .filter(file => !BACKEND_ONLY || !fs.readFileSync(path.join(TEST_DIR, file), 'utf8').includes('helpers/cdp-browser'))
+    .sort();
+}
+
+function tail(text, lines = 12) {
+  const arr = String(text || '').split(/\r?\n/).filter(Boolean);
+  return arr.slice(-lines).join('\n');
+}
+
+function classifyFailure(result) {
+  if (result.status !== null) {
+    return { kind: 'exit', label: `FAIL (exit ${result.status})` };
+  }
+  if (result.error && result.error.code === 'ETIMEDOUT') {
+    return { kind: 'timeout', label: `TIMEOUT (killed after ${PER_TEST_TIMEOUT_MS}ms, signal ${result.signal || 'none'})` };
+  }
+  const code = result.error && result.error.code ? result.error.code : 'unknown';
+  return { kind: 'error', label: `FAIL (spawn error ${code}, signal ${result.signal || 'none'})` };
+}
+
+function runOne(file) {
+  const start = Date.now();
+  // Every test child gets its own Bridge journal sandbox so hook-trigger /
+  // server runtimes never touch the developer's ~/.ai-coding-event-bridge,
+  // its own site data sandbox AND its own knowledge-module data sandbox
+  // (KB_KNOWLEDGE_DATA_DIR is a separate product surface; without it a child
+  // inherits whatever the developer shell points at live knowledge data).
+  // Ambient module URLs are the same leak (F-ENV-LEAK-001): a shell
+  // exporting KB_KNOWLEDGE_ENGINE_URL at the live instance used to point
+  // canonical children at it, and the live engine correctly refused the
+  // fixture binding. A test that deliberately wants a module address sets
+  // it for its own descendants, so ambient inheritance is dropped here.
+  const bridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-bridge-${process.pid}-`));
+  const dataHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-data-${process.pid}-`));
+  const knowledgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-knowledge-${process.pid}-`));
+  const childEnv = { ...process.env, FORCE_COLOR: '0', KB_DATA_DIR: dataHome, KB_KNOWLEDGE_DATA_DIR: knowledgeHome, AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' };
+  for (const ambientModuleUrl of ['KB_KNOWLEDGE_ENGINE_URL', 'KB_VECTORHUB_URL', 'KB_TERMINAL_URL', 'KB_EVENTBRIDGE_URL']) delete childEnv[ambientModuleUrl];
+  const result = spawnSync(process.execPath, [path.join(TEST_DIR, file)], {
+    cwd: ROOT,
+    encoding: 'utf-8',
+    timeout: PER_TEST_TIMEOUT_MS,
+    env: childEnv,
+  });
+  try { fs.rmSync(bridgeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
+  try { fs.rmSync(dataHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
+  try { fs.rmSync(knowledgeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
+  const failure = result.status === 0 ? null : classifyFailure(result);
+  return {
+    file,
+    passed: result.status === 0,
+    failureKind: failure ? failure.kind : null,
+    failureLabel: failure ? failure.label : null,
+    exitCode: result.status,
+    signal: result.signal,
+    spawnErrorCode: result.error && result.error.code ? result.error.code : null,
+    durationMs: Date.now() - start,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    outputTail: tail(`${result.stdout || ''}\n${result.stderr || ''}`.trim()),
+  };
+}
+
+(async () => {
+  const files = listTestFiles();
+  if (BACKEND_ONLY) console.log('Backend/contract scope only. Browser tests are excluded, not passed.');
+  console.log(`Running ${files.length} test file(s)...\n`);
+
+  const results = [];
+  let totalDuration = 0;
+  for (const file of files) {
+    process.stdout.write(`> ${file} ... `);
+    const result = runOne(file);
+    totalDuration += result.durationMs;
+    results.push(result);
+
+    if (result.passed) {
+      console.log(`PASS (${result.durationMs}ms)`);
+    } else {
+      console.log(`${result.failureLabel}, ${result.durationMs}ms`);
+      if (result.outputTail) {
+        console.log('--- tail ---');
+        console.log(result.outputTail);
+        console.log('--- end tail ---');
+      }
+    }
+  }
+
+  const passed = results.filter(result => result.passed).length;
+  const failed = results.length - passed;
+  console.log('\n=========================================');
+  console.log(`Regression suite: ${passed} passed, ${failed} failed (${totalDuration}ms total)`);
+  console.log('=========================================\n');
+
+  if (WRITE_REPORT) {
+    const lines = [];
+    lines.push('# KB Management Site Regression Test Report');
+    lines.push('');
+    lines.push(`**Generated**: ${new Date().toISOString()}`);
+    lines.push(`**Node**: ${process.version}`);
+    lines.push('**Runner**: node _site/_test/run-all-tests.js');
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`**Per-test timeout**: ${PER_TEST_TIMEOUT_MS}ms (override with PK_TEST_TIMEOUT_MS)`);
+    lines.push('');
+    lines.push('| # | File | Status | Exit | Duration |');
+    lines.push('|--:|------|:------:|-----:|---------:|');
+    results.forEach((result, index) => {
+      const status = result.passed ? 'PASS' : (result.failureKind === 'timeout' ? 'TIMEOUT' : 'FAIL');
+      const exit = result.passed
+        ? String(result.exitCode)
+        : `${result.exitCode}${result.signal ? `, signal ${result.signal}` : ''}${result.spawnErrorCode ? `, error ${result.spawnErrorCode}` : ''}`;
+      lines.push(`| ${index + 1} | \`${result.file}\` | ${status} | ${exit} | ${result.durationMs}ms |`);
+    });
+    lines.push('');
+    lines.push(`**Total**: ${results.length} | **Passed**: ${passed} | **Failed**: ${failed} | **Time**: ${totalDuration}ms`);
+    lines.push('');
+
+    const failures = results.filter(result => !result.passed);
+    if (failures.length) {
+      lines.push('## Failures');
+      lines.push('');
+      for (const result of failures) {
+        lines.push(`### ${result.file}`);
+        lines.push('');
+        lines.push('```');
+        lines.push(result.outputTail);
+        lines.push('```');
+        lines.push('');
+      }
+    }
+
+    try {
+      fs.writeFileSync(REPORT_PATH, lines.join('\n'), 'utf-8');
+      console.log(`Report written to: ${REPORT_PATH}`);
+    } catch (e) {
+      console.error(`Failed to write report: ${e.message}`);
+    }
+  }
+
+  process.exit(failed > 0 ? 1 : 0);
+})();

package/_site/_test/runtime-endpoint-test.js

@@ -1,64 +1,64 @@
-// Run: node _site/_test/runtime-endpoint-test.js
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const runtime = require('../lib/runtime-endpoint');
-
-function assert(condition, message) {
-  if (!condition) throw new Error(message);
-}
-
-const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runtime-endpoint-${process.pid}-`));
-
-try {
-  assert(runtime.readEndpoint(dataDir) === null, 'missing endpoint should read as null');
-
-  const written = runtime.writeEndpoint(dataDir, {
-    pid: process.pid,
-    host: '127.0.0.1',
-    port: 5761,
-    mode: 'desktop',
-  });
-  assert(written.schema === runtime.SCHEMA, 'endpoint schema should be current');
-  assert(written.mode === 'desktop', 'endpoint should preserve runtime mode');
-  assert(runtime.readLiveEndpoint(dataDir).pid === process.pid, 'current process endpoint should be live');
-
-  runtime.clearEndpoint(dataDir, { pid: process.pid + 1 });
-  assert(runtime.readEndpoint(dataDir) !== null, 'a different process must not clear the endpoint');
-  runtime.clearEndpoint(dataDir, { pid: process.pid });
-  assert(runtime.readEndpoint(dataDir) === null, 'owner should clear the endpoint');
-
-  const claim = runtime.claimEndpoint(dataDir, {
-    pid: process.pid,
-    host: '127.0.0.1',
-    port: 5762,
-    mode: 'cli',
-  });
-  assert(claim.claimed === true, 'first process should claim an empty endpoint');
-  const duplicate = runtime.claimEndpoint(dataDir, {
-    pid: process.pid + 1,
-    host: '127.0.0.1',
-    port: 5763,
-    mode: 'desktop',
-  });
-  assert(duplicate.claimed === false, 'second process must not replace a live endpoint');
-  assert(duplicate.endpoint.pid === process.pid, 'duplicate should discover the owner');
-  runtime.clearEndpoint(dataDir, { pid: process.pid });
-
-  runtime.writeEndpoint(dataDir, { pid: 2147483646, host: 'localhost', port: 5757 });
-  assert(runtime.readLiveEndpoint(dataDir) === null, 'dead process endpoint should be rejected');
-  assert(!fs.existsSync(runtime.endpointPath(dataDir)), 'dead process endpoint should be removed');
-
-  fs.writeFileSync(runtime.endpointPath(dataDir), JSON.stringify({
-    schema: runtime.SCHEMA,
-    pid: process.pid,
-    host: 'example.com',
-    port: 5757,
-  }), 'utf-8');
-  assert(runtime.readEndpoint(dataDir) === null, 'remote hosts must never be accepted');
-
-  console.log('runtime-endpoint-test PASS');
-} finally {
-  fs.rmSync(dataDir, { recursive: true, force: true });
-}
+// Run: node _site/_test/runtime-endpoint-test.js
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const runtime = require('../lib/runtime-endpoint');
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runtime-endpoint-${process.pid}-`));
+
+try {
+  assert(runtime.readEndpoint(dataDir) === null, 'missing endpoint should read as null');
+
+  const written = runtime.writeEndpoint(dataDir, {
+    pid: process.pid,
+    host: '127.0.0.1',
+    port: 5761,
+    mode: 'desktop',
+  });
+  assert(written.schema === runtime.SCHEMA, 'endpoint schema should be current');
+  assert(written.mode === 'desktop', 'endpoint should preserve runtime mode');
+  assert(runtime.readLiveEndpoint(dataDir).pid === process.pid, 'current process endpoint should be live');
+
+  runtime.clearEndpoint(dataDir, { pid: process.pid + 1 });
+  assert(runtime.readEndpoint(dataDir) !== null, 'a different process must not clear the endpoint');
+  runtime.clearEndpoint(dataDir, { pid: process.pid });
+  assert(runtime.readEndpoint(dataDir) === null, 'owner should clear the endpoint');
+
+  const claim = runtime.claimEndpoint(dataDir, {
+    pid: process.pid,
+    host: '127.0.0.1',
+    port: 5762,
+    mode: 'cli',
+  });
+  assert(claim.claimed === true, 'first process should claim an empty endpoint');
+  const duplicate = runtime.claimEndpoint(dataDir, {
+    pid: process.pid + 1,
+    host: '127.0.0.1',
+    port: 5763,
+    mode: 'desktop',
+  });
+  assert(duplicate.claimed === false, 'second process must not replace a live endpoint');
+  assert(duplicate.endpoint.pid === process.pid, 'duplicate should discover the owner');
+  runtime.clearEndpoint(dataDir, { pid: process.pid });
+
+  runtime.writeEndpoint(dataDir, { pid: 2147483646, host: 'localhost', port: 5757 });
+  assert(runtime.readLiveEndpoint(dataDir) === null, 'dead process endpoint should be rejected');
+  assert(!fs.existsSync(runtime.endpointPath(dataDir)), 'dead process endpoint should be removed');
+
+  fs.writeFileSync(runtime.endpointPath(dataDir), JSON.stringify({
+    schema: runtime.SCHEMA,
+    pid: process.pid,
+    host: 'example.com',
+    port: 5757,
+  }), 'utf-8');
+  assert(runtime.readEndpoint(dataDir) === null, 'remote hosts must never be accepted');
+
+  console.log('runtime-endpoint-test PASS');
+} finally {
+  fs.rmSync(dataDir, { recursive: true, force: true });
+}

package/_site/_test/scanner-test.js

@@ -1,83 +1,83 @@
-// Run: node _site/_test/scanner-test.js
-
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const { CommitScanner, scanProject } = require('../lib/scanner');
-
-const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-scanner-${process.pid}-`));
-
-function git(repo, args) {
-  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true });
-  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
-  return String(result.stdout || '').trim();
-}
-
-function initRepo(name) {
-  const repo = path.join(temp, name);
-  fs.mkdirSync(repo, { recursive: true });
-  git(repo, ['init', '--initial-branch=main']);
-  git(repo, ['config', 'user.email', 'scanner@example.test']);
-  git(repo, ['config', 'user.name', 'Scanner Test']);
-  return repo;
-}
-
-function commit(repo, index) {
-  fs.writeFileSync(path.join(repo, `${index}.txt`), `${index}\n`, 'utf8');
-  git(repo, ['add', `${index}.txt`]);
-  git(repo, ['commit', '-m', `commit ${index}`]);
-  return git(repo, ['rev-parse', 'HEAD']);
-}
-
-(async () => {
-  const scanner = new CommitScanner({ batchSize: 2 });
-  const emptyRepo = initRepo('empty');
-  const empty = await scanner.scan({ repoPath: emptyRepo }, { trackingMode: 'normal', trackingStartCommit: null, lastAnalyzedCommit: null });
-  assert.strictEqual(empty.status, 'empty-repo');
-  assert.deepStrictEqual(empty.commits, []);
-
-  const repo = initRepo('multi');
-  const importedHead = commit(repo, 1);
-  const initial = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: null, lastAnalyzedCommit: null });
-  assert.strictEqual(initial.status, 'establish-tracking');
-  assert.strictEqual(initial.head, importedHead);
-  assert.strictEqual(initial.commits.length, 0, 'pre-import history must not be analyzed');
-
-  const second = commit(repo, 2);
-  const third = commit(repo, 3);
-  const fourth = commit(repo, 4);
-  const pending = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: null });
-  assert.deepStrictEqual(pending.commits, [second, third]);
-  assert.strictEqual(pending.pendingCount, 3);
-  assert.deepStrictEqual(pending.continuation, { remaining: 1, after: third });
-
-  const next = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: third });
-  assert.deepStrictEqual(next.commits, [fourth], 'lastAnalyzedCommit must take priority over trackingStartCommit');
-  assert.strictEqual(next.continuation, null);
-
-  const firstAfterEmpty = await scanner.scan({ repoPath: repo }, { trackingMode: 'empty-repo', trackingStartCommit: null, lastAnalyzedCommit: null });
-  assert.deepStrictEqual(firstAfterEmpty.commits, [importedHead, second], 'empty-repo mode should start with the root commit and expose continuation');
-
-  const legacyView = await scanProject({ slug: 'legacy-view', gitPath: repo, trackingStartCommit: importedHead }, { batchSize: 10 });
-  assert.strictEqual(legacyView.repoStatus, 'ok');
-  assert.deepStrictEqual(legacyView.commits.map(item => item.hash), [second, third, fourth]);
-
-  const tree = git(repo, ['write-tree']);
-  const rewritten = git(repo, ['commit-tree', tree, '-m', 'rewritten']);
-  git(repo, ['update-ref', 'refs/heads/main', rewritten]);
-  const diverged = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: null });
-  assert.strictEqual(diverged.status, 'history-diverged');
-  assert.strictEqual(diverged.head, rewritten);
-  assert.deepStrictEqual(diverged.commits, []);
-
-  const missing = await scanner.scan({ repoPath: path.join(temp, 'missing') }, { trackingMode: 'normal' });
-  assert.strictEqual(missing.status, 'not-git');
-  console.log('scanner-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-}).finally(() => {
-  fs.rmSync(temp, { recursive: true, force: true });
-});
+// Run: node _site/_test/scanner-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { CommitScanner, scanProject } = require('../lib/scanner');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-scanner-${process.pid}-`));
+
+function git(repo, args) {
+  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+  return String(result.stdout || '').trim();
+}
+
+function initRepo(name) {
+  const repo = path.join(temp, name);
+  fs.mkdirSync(repo, { recursive: true });
+  git(repo, ['init', '--initial-branch=main']);
+  git(repo, ['config', 'user.email', 'scanner@example.test']);
+  git(repo, ['config', 'user.name', 'Scanner Test']);
+  return repo;
+}
+
+function commit(repo, index) {
+  fs.writeFileSync(path.join(repo, `${index}.txt`), `${index}\n`, 'utf8');
+  git(repo, ['add', `${index}.txt`]);
+  git(repo, ['commit', '-m', `commit ${index}`]);
+  return git(repo, ['rev-parse', 'HEAD']);
+}
+
+(async () => {
+  const scanner = new CommitScanner({ batchSize: 2 });
+  const emptyRepo = initRepo('empty');
+  const empty = await scanner.scan({ repoPath: emptyRepo }, { trackingMode: 'normal', trackingStartCommit: null, lastAnalyzedCommit: null });
+  assert.strictEqual(empty.status, 'empty-repo');
+  assert.deepStrictEqual(empty.commits, []);
+
+  const repo = initRepo('multi');
+  const importedHead = commit(repo, 1);
+  const initial = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: null, lastAnalyzedCommit: null });
+  assert.strictEqual(initial.status, 'establish-tracking');
+  assert.strictEqual(initial.head, importedHead);
+  assert.strictEqual(initial.commits.length, 0, 'pre-import history must not be analyzed');
+
+  const second = commit(repo, 2);
+  const third = commit(repo, 3);
+  const fourth = commit(repo, 4);
+  const pending = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: null });
+  assert.deepStrictEqual(pending.commits, [second, third]);
+  assert.strictEqual(pending.pendingCount, 3);
+  assert.deepStrictEqual(pending.continuation, { remaining: 1, after: third });
+
+  const next = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: third });
+  assert.deepStrictEqual(next.commits, [fourth], 'lastAnalyzedCommit must take priority over trackingStartCommit');
+  assert.strictEqual(next.continuation, null);
+
+  const firstAfterEmpty = await scanner.scan({ repoPath: repo }, { trackingMode: 'empty-repo', trackingStartCommit: null, lastAnalyzedCommit: null });
+  assert.deepStrictEqual(firstAfterEmpty.commits, [importedHead, second], 'empty-repo mode should start with the root commit and expose continuation');
+
+  const legacyView = await scanProject({ slug: 'legacy-view', gitPath: repo, trackingStartCommit: importedHead }, { batchSize: 10 });
+  assert.strictEqual(legacyView.repoStatus, 'ok');
+  assert.deepStrictEqual(legacyView.commits.map(item => item.hash), [second, third, fourth]);
+
+  const tree = git(repo, ['write-tree']);
+  const rewritten = git(repo, ['commit-tree', tree, '-m', 'rewritten']);
+  git(repo, ['update-ref', 'refs/heads/main', rewritten]);
+  const diverged = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: null });
+  assert.strictEqual(diverged.status, 'history-diverged');
+  assert.strictEqual(diverged.head, rewritten);
+  assert.deepStrictEqual(diverged.commits, []);
+
+  const missing = await scanner.scan({ repoPath: path.join(temp, 'missing') }, { trackingMode: 'normal' });
+  assert.strictEqual(missing.status, 'not-git');
+  console.log('scanner-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});