@sanqianx/project-knowledge 5.0.19 → 5.0.20

package/_site/_test/requirement-binding-test.js

@@ -1,113 +1,113 @@
-// Run: node _site/_test/requirement-binding-test.js
-
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { SCHEMAS } = require('../lib/contracts');
-const { StorageLayout } = require('../lib/storage-layout');
-const { ProjectRegistryStore } = require('../lib/project-registry-store');
-const { ProjectStore } = require('../lib/project-store');
-const { RequirementBinder } = require('../lib/requirement-binder');
-
-const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-requirement-binding-${process.pid}-`));
-const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
-const registry = new ProjectRegistryStore({ layout });
-const projects = new ProjectStore({ layout });
-const commit = 'c'.repeat(40);
-
-function record(id, projectId, sessionId, head, options = {}) {
-  return {
-    schema: SCHEMAS.requirement,
-    id,
-    ts: options.ts || '2026-08-17T00:00:00.000Z',
-    projectId,
-    client: options.client || 'codex',
-    sessionId,
-    conversationId: null,
-    branch: options.branch || 'main',
-    headAtRecord: head,
-    requirement: `Requirement ${id}`,
-    requirementHash: `sha256:${id}`,
-    explicitCommit: options.explicitCommit || null,
-  };
-}
-
-(async () => {
-  await registry.initialize();
-  for (const projectId of ['project-a', 'project-b']) {
-    const repoPath = path.join(temp, projectId);
-    fs.mkdirSync(repoPath, { recursive: true });
-    await projects.create(projectId, {
-      storageName: projectId,
-      displayName: projectId,
-      repoPath,
-      knowledgePath: path.join(temp, 'knowledge', projectId),
-    });
-    await registry.add(projectId, { displayName: projectId });
-  }
-  await projects.appendRequirement('project-a', record('req-a1', 'project-a', 'session-one', 'a'.repeat(40), { ts: '2026-08-17T00:00:01.000Z' }));
-  await projects.appendRequirement('project-a', record('req-a2', 'project-a', 'session-one', 'b'.repeat(40), { ts: '2026-08-17T00:00:02.000Z' }));
-  await projects.appendRequirement('project-a', record('req-a3', 'project-a', 'session-two', 'd'.repeat(40)));
-  await projects.appendRequirement('project-a', record('req-branch', 'project-a', 'session-one', 'e'.repeat(40), { branch: 'feature' }));
-  await projects.appendRequirement('project-a', record('req-future', 'project-a', 'session-one', 'f'.repeat(40)));
-  await projects.appendRequirement('project-a', record('req-explicit-commit', 'project-a', 'session-three', '9'.repeat(40), { explicitCommit: '8'.repeat(40) }));
-  await projects.appendRequirement('project-b', record('req-other-project', 'project-b', 'session-one', 'a'.repeat(40)));
-
-  const ancestry = new Set(['a'.repeat(40), 'b'.repeat(40), 'd'.repeat(40), 'e'.repeat(40)]);
-  const binder = new RequirementBinder({
-    layout,
-    registryStore: registry,
-    projectStore: projects,
-    gitReader: { isAncestor: async (_repoPath, headAtRecord, target) => target === commit && ancestry.has(headAtRecord) },
-  });
-
-  const sameSession = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'session-one' });
-  assert.deepStrictEqual(sameSession.requirementIds, ['req-a1', 'req-a2'], 'same session and ancestry should bind its ordered unclaimed sequence');
-  assert.strictEqual(sameSession.requirementBinding, 'session-ancestry');
-
-  const ambiguous = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main' });
-  assert.strictEqual(ambiguous.requirementBinding, 'unavailable');
-  assert.strictEqual(ambiguous.reason, 'ambiguous-sessions', 'multiple candidate sessions must never use most-recent guessing');
-
-  const wrongSession = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'unknown' });
-  assert.strictEqual(wrongSession.reason, 'no-reliable-requirement');
-  const changedBranch = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'release', client: 'codex', sessionId: 'session-one' });
-  assert.strictEqual(changedBranch.requirementBinding, 'unavailable', 'branch changes should lower confidence to unavailable');
-
-  const explicit = await binder.bind({ projectId: 'project-a', commitSha: commit, requirementId: 'req-a1' });
-  assert.deepStrictEqual(explicit.requirementIds, ['req-a1']);
-  assert.strictEqual(explicit.requirementBinding, 'explicit');
-  await assert.rejects(
-    binder.bind({ projectId: 'project-a', commitSha: commit, requirementId: 'req-other-project' }),
-    error => error.code === 'INVALID_ARGUMENT' && /different project/.test(error.message),
-  );
-
-  const unclaimed = await binder.bind({
-    projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'session-one', claimedRequirementIds: ['req-a1'],
-  });
-  assert.deepStrictEqual(unclaimed.requirementIds, ['req-a2'], 'already advanced requirements should be excluded from a later claim');
-
-  const explicitCommit = await binder.bind({ projectId: 'project-a', commitSha: '8'.repeat(40), branch: 'main' });
-  assert.deepStrictEqual(explicitCommit.requirementIds, ['req-explicit-commit']);
-  assert.strictEqual(explicitCommit.reason, 'explicit-commit');
-
-  const claim = {
-    schema: SCHEMAS.commitClaim,
-    projectId: 'project-a',
-    commitSha: commit,
-    requirementIds: ['req-a1'],
-    requirementBinding: 'session-ancestry',
-  };
-  await projects.appendRequirement('project-a', record('req-recorded-after-claim', 'project-a', 'session-one', 'a'.repeat(40), { ts: '2026-08-17T00:00:03.000Z' }));
-  const retry = await binder.bind({ projectId: 'project-a', commitSha: commit, claim });
-  assert.deepStrictEqual(retry.requirementIds, ['req-a1'], 'retry must reuse frozen IDs and ignore future records');
-  assert.strictEqual(retry.frozen, true);
-
-  console.log('requirement-binding-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/requirement-binding-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { SCHEMAS } = require('../lib/contracts');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { RequirementBinder } = require('../lib/requirement-binder');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-requirement-binding-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const registry = new ProjectRegistryStore({ layout });
+const projects = new ProjectStore({ layout });
+const commit = 'c'.repeat(40);
+
+function record(id, projectId, sessionId, head, options = {}) {
+  return {
+    schema: SCHEMAS.requirement,
+    id,
+    ts: options.ts || '2026-08-17T00:00:00.000Z',
+    projectId,
+    client: options.client || 'codex',
+    sessionId,
+    conversationId: null,
+    branch: options.branch || 'main',
+    headAtRecord: head,
+    requirement: `Requirement ${id}`,
+    requirementHash: `sha256:${id}`,
+    explicitCommit: options.explicitCommit || null,
+  };
+}
+
+(async () => {
+  await registry.initialize();
+  for (const projectId of ['project-a', 'project-b']) {
+    const repoPath = path.join(temp, projectId);
+    fs.mkdirSync(repoPath, { recursive: true });
+    await projects.create(projectId, {
+      storageName: projectId,
+      displayName: projectId,
+      repoPath,
+      knowledgePath: path.join(temp, 'knowledge', projectId),
+    });
+    await registry.add(projectId, { displayName: projectId });
+  }
+  await projects.appendRequirement('project-a', record('req-a1', 'project-a', 'session-one', 'a'.repeat(40), { ts: '2026-08-17T00:00:01.000Z' }));
+  await projects.appendRequirement('project-a', record('req-a2', 'project-a', 'session-one', 'b'.repeat(40), { ts: '2026-08-17T00:00:02.000Z' }));
+  await projects.appendRequirement('project-a', record('req-a3', 'project-a', 'session-two', 'd'.repeat(40)));
+  await projects.appendRequirement('project-a', record('req-branch', 'project-a', 'session-one', 'e'.repeat(40), { branch: 'feature' }));
+  await projects.appendRequirement('project-a', record('req-future', 'project-a', 'session-one', 'f'.repeat(40)));
+  await projects.appendRequirement('project-a', record('req-explicit-commit', 'project-a', 'session-three', '9'.repeat(40), { explicitCommit: '8'.repeat(40) }));
+  await projects.appendRequirement('project-b', record('req-other-project', 'project-b', 'session-one', 'a'.repeat(40)));
+
+  const ancestry = new Set(['a'.repeat(40), 'b'.repeat(40), 'd'.repeat(40), 'e'.repeat(40)]);
+  const binder = new RequirementBinder({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    gitReader: { isAncestor: async (_repoPath, headAtRecord, target) => target === commit && ancestry.has(headAtRecord) },
+  });
+
+  const sameSession = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'session-one' });
+  assert.deepStrictEqual(sameSession.requirementIds, ['req-a1', 'req-a2'], 'same session and ancestry should bind its ordered unclaimed sequence');
+  assert.strictEqual(sameSession.requirementBinding, 'session-ancestry');
+
+  const ambiguous = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main' });
+  assert.strictEqual(ambiguous.requirementBinding, 'unavailable');
+  assert.strictEqual(ambiguous.reason, 'ambiguous-sessions', 'multiple candidate sessions must never use most-recent guessing');
+
+  const wrongSession = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'unknown' });
+  assert.strictEqual(wrongSession.reason, 'no-reliable-requirement');
+  const changedBranch = await binder.bind({ projectId: 'project-a', commitSha: commit, branch: 'release', client: 'codex', sessionId: 'session-one' });
+  assert.strictEqual(changedBranch.requirementBinding, 'unavailable', 'branch changes should lower confidence to unavailable');
+
+  const explicit = await binder.bind({ projectId: 'project-a', commitSha: commit, requirementId: 'req-a1' });
+  assert.deepStrictEqual(explicit.requirementIds, ['req-a1']);
+  assert.strictEqual(explicit.requirementBinding, 'explicit');
+  await assert.rejects(
+    binder.bind({ projectId: 'project-a', commitSha: commit, requirementId: 'req-other-project' }),
+    error => error.code === 'INVALID_ARGUMENT' && /different project/.test(error.message),
+  );
+
+  const unclaimed = await binder.bind({
+    projectId: 'project-a', commitSha: commit, branch: 'main', client: 'codex', sessionId: 'session-one', claimedRequirementIds: ['req-a1'],
+  });
+  assert.deepStrictEqual(unclaimed.requirementIds, ['req-a2'], 'already advanced requirements should be excluded from a later claim');
+
+  const explicitCommit = await binder.bind({ projectId: 'project-a', commitSha: '8'.repeat(40), branch: 'main' });
+  assert.deepStrictEqual(explicitCommit.requirementIds, ['req-explicit-commit']);
+  assert.strictEqual(explicitCommit.reason, 'explicit-commit');
+
+  const claim = {
+    schema: SCHEMAS.commitClaim,
+    projectId: 'project-a',
+    commitSha: commit,
+    requirementIds: ['req-a1'],
+    requirementBinding: 'session-ancestry',
+  };
+  await projects.appendRequirement('project-a', record('req-recorded-after-claim', 'project-a', 'session-one', 'a'.repeat(40), { ts: '2026-08-17T00:00:03.000Z' }));
+  const retry = await binder.bind({ projectId: 'project-a', commitSha: commit, claim });
+  assert.deepStrictEqual(retry.requirementIds, ['req-a1'], 'retry must reuse frozen IDs and ignore future records');
+  assert.strictEqual(retry.frozen, true);
+
+  console.log('requirement-binding-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});

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 });
+});