@boyingliu01/xp-gate 0.19.3 → 0.20.0

package/principles/__tests__/baseline-prune.test.ts

@@ -0,0 +1,338 @@
+/**
+ * @test REQ-452 REQ-3
+ * @intent A baseline entry for a file that no longer exists must not be kept
+ *         forever. Previously `classifyFiles` parsed `deleted` but nothing
+ *         consumed it, so `.warnings-baseline.json` accumulated stale entries
+ *         that let a re-created file inherit a bogus allowance.
+ * @covers AC-452-10, AC-452-11, AC-452-12, AC-452-13, AC-452-14
+ *
+ * The removal is deliberately DOUBLE-CONFIRMED: a path is only treated as
+ * deleted when the filesystem says it is absent AND git no longer tracks it.
+ * Either signal alone produces false positives -- a sparse checkout, a rebase
+ * mid-flight, a case-insensitive filesystem, or a symlink all make an existing
+ * tracked file look "missing".
+ */
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { pruneBaselineEntries } from '../baseline-prune';
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'xpgate-452-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+/** Create a git repo with one committed file, and return its root. */
+function makeRepoWithCommit(): { root: string; tracked: string } {
+  const root = makeTempDir();
+  const tracked = 'tracked.ts';
+  const run = (args: string[]): void => {
+    try {
+      execFileSync('git', args, { cwd: root, stdio: 'ignore' });
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`git ${args.join(' ')} failed in ${root}: ${detail}`);
+    }
+  };
+  try {
+    writeFileSync(join(root, tracked), 'export const a = 1;\n', 'utf8');
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`could not seed repo file: ${detail}`);
+  }
+  run(['init', '-b', 'main']);
+  run(['config', 'user.email', 'test@example.com']);
+  run(['config', 'user.name', 'Test']);
+  // This fixture is scaffolding, not a real commit: the global XP-Gate hooks are
+  // installed on this machine and would otherwise block the seed commit
+  // (Gate 5a rejects an untested source file). `core.hooksPath` is set to a
+  // non-existent path rather than using --no-verify so the intent is explicit
+  // and cannot be mistaken for bypassing this repository's own gates.
+  run(['config', 'core.hooksPath', join(root, '.no-hooks')]);
+  run(['add', tracked]);
+  run(['commit', '-m', 'seed']);
+  return { root, tracked };
+}
+
+/**
+ * Stage many paths at once, to push `git ls-files` output past the 1 MiB default
+ * stdout buffer that `execFileSync` would otherwise apply.
+ *
+ * Uses `git update-index --index-info` to write the index directly rather than
+ * creating files and running `git add`: that path costs over 50s for this many
+ * entries (filesystem + index churn), whereas feeding the index in one batch takes
+ * under a second. The blob hash is git's well-known empty-blob id, so nothing needs
+ * to exist on disk -- which is fine, because the assertion is about `git ls-files`
+ * reporting the index, not about the working tree.
+ */
+function stageManyPaths(root: string, count: number, nameFor: (index: number) => string): void {
+  const EMPTY_BLOB = 'e69de29bb2d1d6434b8b29ae775ad8c2e48c5391';
+  const lines: string[] = [];
+  for (let i = 0; i < count; i += 1) {
+    lines.push(`100644 ${EMPTY_BLOB}\t${nameFor(i)}`);
+  }
+  try {
+    execFileSync('git', ['update-index', '--index-info'], {
+      cwd: root,
+      input: `${lines.join('\n')}\n`,
+      stdio: ['pipe', 'ignore', 'ignore'],
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`could not stage filler paths: ${detail}`);
+  }
+}
+
+/**
+ * A baseline shaped like the real `.warnings-baseline.json` payload.
+ *
+ * The on-disk format is a FLAT path -> entry map, verified against the committed
+ * file; there is no `files` wrapper.
+ */
+function baselineWith(paths: string[]): string {
+  const files: Record<string, unknown> = {};
+  for (const path of paths) {
+    files[path] = { totalWarnings: 3, lastAnalyzed: '2026-10-03T00:00:00.000Z' };
+  }
+  return JSON.stringify(files);
+}
+
+/**
+ * Stage exact paths in the index without creating working-tree files.
+ *
+ * Index-only staging is what makes the case-sensitivity assertions portable:
+ * neither spelling exists on disk (so the `existsSync` half of the double-confirm
+ * is false everywhere), and the only signal left is the comparison against the
+ * git index -- which is exactly the behavior under test. The blob hash is git's
+ * well-known empty-blob id, so nothing needs to exist on disk.
+ */
+function stageIndexOnly(root: string, paths: string[]): void {
+  const EMPTY_BLOB = 'e69de29bb2d1d6434b8b29ae775ad8c2e48c5391';
+  const input = paths.map((path) => `100644 ${EMPTY_BLOB}\t${path}`).join('\n');
+  try {
+    execFileSync('git', ['update-index', '--index-info'], {
+      cwd: root,
+      input: `${input}\n`,
+      stdio: ['pipe', 'ignore', 'ignore'],
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`could not stage index paths: ${detail}`);
+  }
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+  }
+});
+
+describe('#452 REQ-3 stale baseline entries are pruned', () => {
+  it('AC-452-10: a path that is absent AND untracked is reported for removal', () => {
+    const { root } = makeRepoWithCommit();
+    const stale = 'gone-forever.ts';
+
+    const result = pruneBaselineEntries(baselineWith([stale]), root);
+
+    expect(result.removed).toContain(stale);
+    expect(result.kept).not.toContain(stale);
+  });
+
+  it('AC-452-11: an existing tracked file is KEPT even when absent from disk', () => {
+    // Simulates a sparse checkout / mid-rebase / symlinked worktree: the file
+    // is gone from the working tree but git still tracks it. Removing the entry
+    // here would silently discard a legitimate allowance.
+    const { root, tracked } = makeRepoWithCommit();
+    rmSync(join(root, tracked));
+
+    const result = pruneBaselineEntries(baselineWith([tracked]), root);
+
+    expect(result.kept).toContain(tracked);
+    expect(result.removed).not.toContain(tracked);
+  });
+
+  it('AC-452-12: a file present on disk is kept', () => {
+    const { root, tracked } = makeRepoWithCommit();
+
+    const result = pruneBaselineEntries(baselineWith([tracked]), root);
+
+    expect(result.kept).toContain(tracked);
+    expect(result.removed).toHaveLength(0);
+  });
+
+  it('AC-452-13: an untracked-but-present file is kept (git is not authoritative alone)', () => {
+    const { root } = makeRepoWithCommit();
+    const untracked = 'untracked.ts';
+    mkdirSync(root, { recursive: true });
+    try {
+      writeFileSync(join(root, untracked), 'export const b = 2;\n', 'utf8');
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`could not write untracked file: ${detail}`);
+    }
+
+    const result = pruneBaselineEntries(baselineWith([untracked]), root);
+
+    expect(result.kept).toContain(untracked);
+  });
+
+  it('AC-452-10: pruning is non-destructive — it never mutates the input', () => {
+    const { root } = makeRepoWithCommit();
+    const input = baselineWith(['gone-forever.ts', 'also-gone.ts']);
+
+    pruneBaselineEntries(input, root);
+
+    // The caller decides when to persist; the helper must not rewrite in place.
+    const parsed = JSON.parse(input) as Record<string, unknown>;
+    expect(Object.keys(parsed)).toHaveLength(2);
+  });
+
+  it('AC-452-11: every entry is preserved when git is unavailable', () => {
+    // A non-repo directory means `git ls-files` fails. Failing closed (keep
+    // everything) is safer than deleting entries we cannot confirm.
+    const dir = makeTempDir();
+    const paths = ['a.ts', 'b.ts'];
+
+    const result = pruneBaselineEntries(baselineWith(paths), dir);
+
+    expect(result.kept.sort()).toEqual(paths);
+    expect(result.removed).toHaveLength(0);
+  });
+
+  it('AC-452-13: an empty baseline yields empty kept/removed lists', () => {
+    const { root } = makeRepoWithCommit();
+
+    const result = pruneBaselineEntries(baselineWith([]), root);
+
+    expect(result.kept).toHaveLength(0);
+    expect(result.removed).toHaveLength(0);
+  });
+
+  it('AC-452-12: a malformed baseline is preserved rather than silently emptied', () => {
+    // The reporter's `{}` came from this path. Keeping the entries and
+    // reporting an error is the fail-safe behaviour.
+    const { root } = makeRepoWithCommit();
+
+    const result = pruneBaselineEntries('{ not json', root);
+
+    expect(result.removed).toHaveLength(0);
+    expect(result.error).toBeDefined();
+  });
+
+  it('AC-452-10: pruning still works when the git index exceeds the default pipe buffer', () => {
+    // `execFileSync` defaults to a 1 MiB stdout buffer. A repo whose `git
+    // ls-files` output exceeds it throws, which `listTrackedFiles` would report
+    // as "git unavailable" -- silently disabling pruning at exactly the scale
+    // where a stale baseline is most likely. Committing enough paths to blow past
+    // 1 MiB proves the raised maxBuffer is actually in effect: without it every
+    // entry is merely "kept" and the stale path below would never be reported.
+    const { root } = makeRepoWithCommit();
+    // Measured: each path is ~48 bytes once `git ls-files` newline-joins it, so
+    // 1 MiB / 48 = ~21.8k entries. Use 30000 (~1.4 MiB) so the threshold is
+    // cleared with real headroom rather than marginally -- an earlier version used
+    // 19000, which came to 0.88 MiB and passed even with the buffer bug present.
+    stageManyPaths(root, 30000, (i) => `filler/s${i}/a-fairly-long-file-name-padding.ts`);
+
+    const result = pruneBaselineEntries(baselineWith(['deleted-long-ago.ts']), root);
+
+    expect(result.removed).toEqual(['deleted-long-ago.ts']);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('AC-452-14: on a case-sensitive filesystem the index path is the canonical form', () => {
+    // Two tracked files whose names differ only by case are two DIFFERENT files on
+    // Linux. A baseline key that matches neither spelling exactly is a phantom:
+    // folding it to `case/alpha.ts` used to match the index and retain the entry
+    // forever -- the same stale-allowance bug this module exists to remove, since
+    // re-creating `case/ALPHA.ts` would inherit the retained allowance.
+    const { root } = makeRepoWithCommit();
+    stageIndexOnly(root, ['case/Alpha.ts', 'case/alpha.ts']);
+
+    const result = pruneBaselineEntries(
+      baselineWith(['case/ALPHA.ts']),
+      root,
+      { caseInsensitivePaths: false },
+    );
+
+    expect(result.removed).toEqual(['case/ALPHA.ts']);
+    expect(result.kept).toHaveLength(0);
+  });
+
+  it('AC-452-14: a case-sensitive filesystem does not conflate a differently-cased key with a tracked path', () => {
+    const { root } = makeRepoWithCommit();
+    stageIndexOnly(root, ['src/Tracked.ts']);
+
+    const result = pruneBaselineEntries(
+      baselineWith(['src/tracked.ts']),
+      root,
+      { caseInsensitivePaths: false },
+    );
+
+    expect(result.removed).toEqual(['src/tracked.ts']);
+  });
+
+  it('AC-452-14: an exact index match is kept on a case-sensitive filesystem', () => {
+    // Guards against the opposite regression: dropping the fold must not turn a
+    // legitimately tracked path into a prunable one.
+    const { root } = makeRepoWithCommit();
+    stageIndexOnly(root, ['case/alpha.ts']);
+
+    const result = pruneBaselineEntries(
+      baselineWith(['case/alpha.ts']),
+      root,
+      { caseInsensitivePaths: false },
+    );
+
+    expect(result.kept).toContain('case/alpha.ts');
+    expect(result.removed).toHaveLength(0);
+  });
+
+  it('AC-452-14: a case-insensitive filesystem keeps the retain-bias for a differently-cased key', () => {
+    // On Windows (and macOS default volumes) `src/tracked.ts` and `src/Tracked.ts`
+    // are the same file, and the key can be written by a tool that reported a
+    // different casing than the index. Losing that allowance in a sparse checkout
+    // -- when `existsSync` cannot confirm either spelling -- is the failure mode
+    // the original fold was introduced to prevent, so case-folding stays enabled
+    // exactly where the filesystem actually folds.
+    const { root } = makeRepoWithCommit();
+    stageIndexOnly(root, ['src/Tracked.ts']);
+
+    const result = pruneBaselineEntries(
+      baselineWith(['src/tracked.ts']),
+      root,
+      { caseInsensitivePaths: true },
+    );
+
+    expect(result.kept).toContain('src/tracked.ts');
+    expect(result.removed).toHaveLength(0);
+  });
+
+  it('AC-452-14: the default follows the host filesystem, not a hardcoded assumption', () => {
+    // This repository's own tests must stay portable: Linux CI and this Windows
+    // checkout have to disagree here, because the correct answer IS platform
+    // dependent. The assertion pins the wiring (default = detection) rather than a
+    // single outcome.
+    const { root } = makeRepoWithCommit();
+    stageIndexOnly(root, ['src/Tracked.ts']);
+
+    const result = pruneBaselineEntries(baselineWith(['src/tracked.ts']), root);
+    const folded = process.platform === 'win32' || process.platform === 'darwin';
+
+    if (folded) {
+      expect(result.kept).toContain('src/tracked.ts');
+      expect(result.removed).toHaveLength(0);
+    } else {
+      expect(result.removed).toEqual(['src/tracked.ts']);
+    }
+  });
+});

package/principles/__tests__/boy-scout-init-baseline.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('fs/promises')>();
+  return {
+    ...actual,
+    readFile: vi.fn(),
+    access: vi.fn(),
+    writeFile: vi.fn(),
+  };
+});
+
+vi.mock('../analyzer', () => ({
+  analyze: vi.fn(),
+  getAdapterForFile: vi.fn(),
+}));
+
+vi.mock('../index', () => ({
+  getAllRules: vi.fn(() => []),
+}));
+
+import { writeFile, readFile } from 'fs/promises';
+import { initBaselineCommand } from '../boy-scout';
+import { analyze } from '../analyzer';
+
+const mockAnalyze = vi.mocked(analyze);
+const mockWriteFile = vi.mocked(writeFile);
+const mockReadFile = vi.mocked(readFile);
+
+function violationsFor(counts: Record<string, number>) {
+  const violations = [];
+  for (const [file, n] of Object.entries(counts)) {
+    for (let i = 0; i < n; i++) {
+      violations.push({
+        file,
+        line: i + 1,
+        ruleId: 'clean-code.magic-numbers',
+        message: 'm',
+        severity: 'warning' as const,
+      });
+    }
+  }
+  return { violations, summary: {}, fileResults: {}, ruleResults: {}, executionTimeMs: 0, errors: [] };
+}
+
+/**
+ * A realistic ENOENT. `loadBaseline` distinguishes "no file yet" from every other
+ * I/O failure by `error.code`, so a mock that only says `new Error('ENOENT')`
+ * (no `code`) is not a real ENOENT and would be treated as unreadable (#455).
+ */
+function enoent(): NodeJS.ErrnoException {
+  return Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' });
+}
+
+/**
+ * @test REQ-DSH-014
+ * @intent 验证 `--init-baseline` 是**合并**语义而非覆盖：既有基线条目必须保留，
+ *         且写入路径必须尊重 `--baseline` 参数，不得硬编码 .warnings-baseline.json
+ *         （#445 —— 实测该命令会把已跟踪的基线摧毁成 {}）
+ * @covers AC-DSH-014-01
+ */
+describe('initBaselineCommand must not destroy existing baselines (#445)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockWriteFile.mockResolvedValue(undefined);
+  });
+
+  it('merges into the existing baseline instead of replacing it', async () => {
+    // Existing tracked baseline already has an entry for an unrelated file.
+    const existing = {
+      'src/legacy.ts': { totalWarnings: 3, lastAnalyzed: '2026-01-01T00:00:00.000Z' },
+    };
+    mockReadFile.mockResolvedValue(JSON.stringify(existing) as never);
+    mockAnalyze.mockResolvedValue(violationsFor({ 'src/new.ts': 2 }) as never);
+
+    await initBaselineCommand(['src/new.ts'], '.warnings-baseline.json');
+
+    expect(mockWriteFile).toHaveBeenCalledTimes(1);
+    const [, writtenRaw] = mockWriteFile.mock.calls[0];
+    const written = JSON.parse(String(writtenRaw));
+
+    // The pre-existing entry MUST survive.
+    expect(written['src/legacy.ts']).toBeDefined();
+    expect(written['src/legacy.ts'].totalWarnings).toBe(3);
+    // And the newly analysed file must be added.
+    expect(written['src/new.ts']).toBeDefined();
+    expect(written['src/new.ts'].totalWarnings).toBe(2);
+  });
+
+  it('writes to the path given by --baseline, not the hardcoded default', async () => {
+    mockReadFile.mockRejectedValue(enoent() as never);
+    mockAnalyze.mockResolvedValue(violationsFor({ 'src/a.ts': 1 }) as never);
+
+    await initBaselineCommand(['src/a.ts'], 'custom/baseline.json');
+
+    const [targetPath] = mockWriteFile.mock.calls[0];
+    expect(String(targetPath)).toBe('custom/baseline.json');
+    expect(String(targetPath)).not.toBe('.warnings-baseline.json');
+  });
+
+  it('does not persist an empty object when analysis yields no warnings', async () => {
+    const existing = {
+      'src/legacy.ts': { totalWarnings: 1, lastAnalyzed: '2026-01-01T00:00:00.000Z' },
+    };
+    mockReadFile.mockResolvedValue(JSON.stringify(existing) as never);
+    // File now has zero warnings.
+    mockAnalyze.mockResolvedValue(violationsFor({}) as never);
+
+    await initBaselineCommand(['src/clean.ts'], '.warnings-baseline.json');
+
+    const [, writtenRaw] = mockWriteFile.mock.calls[0];
+    const written = JSON.parse(String(writtenRaw));
+    // Must NOT be {} -- the legacy entry has to survive.
+    expect(Object.keys(written)).toContain('src/legacy.ts');
+  });
+
+  it('reports which entries were added and which were preserved', async () => {
+    const existing = {
+      'src/legacy.ts': { totalWarnings: 3, lastAnalyzed: '2026-01-01T00:00:00.000Z' },
+    };
+    mockReadFile.mockResolvedValue(JSON.stringify(existing) as never);
+    mockAnalyze.mockResolvedValue(violationsFor({ 'src/new.ts': 1 }) as never);
+    const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+    await initBaselineCommand(['src/new.ts'], '.warnings-baseline.json');
+
+    const output = log.mock.calls.map((c) => c.join(' ')).join('\n');
+    expect(output).toMatch(/src\/legacy\.ts/);
+    expect(output).toMatch(/src\/new\.ts/);
+    log.mockRestore();
+  });
+
+  it('signals outcome via its return value, never process.exitCode', async () => {
+    // Delphi Round 1: three experts independently flagged that this command
+    // reported failure by mutating global exit state, so an unrelated
+    // non-zero process.exitCode would be misread as this command failing.
+    mockReadFile.mockRejectedValue(enoent() as never);
+    mockAnalyze.mockResolvedValue(violationsFor({ 'src/a.ts': 1 }) as never);
+    const previousExitCode = process.exitCode;
+    process.exitCode = 0;
+
+    const result = await initBaselineCommand(['src/a.ts'], '.warnings-baseline.json');
+
+    expect(result.ok).toBe(true);
+    // Global state must be untouched by the command.
+    expect(process.exitCode).toBe(0);
+
+    process.exitCode = previousExitCode;
+  });
+
+  it('can never empty a non-empty baseline, even when analysis finds nothing', async () => {
+    // The merge starts from the existing entries, so the destructive overwrite
+    // from #445 is structurally impossible rather than merely guarded.
+    const existing = {
+      'src/legacy.ts': { totalWarnings: 1, lastAnalyzed: '2026-01-01T00:00:00.000Z' },
+    };
+    mockReadFile.mockResolvedValue(JSON.stringify(existing) as never);
+    mockAnalyze.mockResolvedValue(violationsFor({}) as never);
+
+    const result = await initBaselineCommand(['src/clean.ts'], '.warnings-baseline.json');
+
+    expect(result.ok).toBe(true);
+    const [, writtenRaw] = mockWriteFile.mock.calls[0];
+    const written = JSON.parse(String(writtenRaw));
+    expect(Object.keys(written)).toContain('src/legacy.ts');
+  });
+});

package/principles/__tests__/boy-scout-integration.test.ts

@@ -2,6 +2,8 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import * as path from 'path';
+import { tmpdir } from 'os';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
 
 const execAsync = promisify(exec);
 
@@ -147,6 +149,51 @@ describe('Boy Scout Rule - runEnforcement', () => {
     expect(vi.mocked(mockWriteFile).mock.calls[0][0]).toBe('/tmp/test-baseline.json');
   });
 
+  // #452: the auto-init path inside runEnforcement once wrote only the current
+  // commit's files, silently dropping entries for untouched files -- which then
+  // made Gate 6 BLOCK files the commit never touched. The explicit
+  // init-baseline command got merge semantics (#445); these tests pin the same
+  // guarantee on the automatic path.
+  it('REQ-452: auto-init preserves entries for files not in the current commit', async () => {
+    // 6 warnings so the entry survives the "small baselines must clear" rule;
+    // a clean file gains no entry by design (nothing to budget).
+    const warnings = Array.from({ length: 6 }, (_, i) => ({
+      file: 'plugins/dsh/src/command.ts', line: i + 1, ruleId: 'test', severity: 'warning' as const, message: 'm',
+    }));
+    mockAnalyze.mockResolvedValue(fakeAnalysis(warnings));
+    mockAccess.mockResolvedValue(undefined);
+    mockReadFile.mockResolvedValue(
+      JSON.stringify({ 'src/npm-package/lib/test-alignment.ts': { totalWarnings: 1, lastAnalyzed: '2024-01-01' } })
+    );
+    mockWriteFile.mockResolvedValue(undefined);
+
+    const result = await runEnforcement([], ['plugins/dsh/src/command.ts'], '/tmp/test-baseline.json');
+
+    expect(result.overallStatus).toBe('PASS');
+    expect(mockWriteFile).toHaveBeenCalled();
+    const saved = JSON.parse(vi.mocked(mockWriteFile).mock.calls[0][1] as string) as Record<string, BaselineEntry>;
+    expect(saved['src/npm-package/lib/test-alignment.ts']).toEqual({ totalWarnings: 1, lastAnalyzed: '2024-01-01' });
+    expect(saved['plugins/dsh/src/command.ts']?.totalWarnings).toBe(6);
+  });
+
+  it('REQ-452: auto-init is idempotent -- a second run over the same files writes the same entries', async () => {
+    mockAnalyze.mockResolvedValue(emptyAnalysis());
+    mockAccess.mockResolvedValue(undefined);
+    mockWriteFile.mockResolvedValue(undefined);
+    const first = JSON.stringify({});
+
+    mockReadFile.mockResolvedValue(first);
+    await runEnforcement([], ['src/a.ts'], '/tmp/test-baseline.json');
+    const savedOnce = vi.mocked(mockWriteFile).mock.calls.at(-1)![1] as string;
+
+    mockReadFile.mockResolvedValue(savedOnce);
+    mockWriteFile.mockClear();
+    await runEnforcement([], ['src/a.ts'], '/tmp/test-baseline.json');
+    const savedTwice = vi.mocked(mockWriteFile).mock.calls.at(-1)![1] as string;
+
+    expect(JSON.parse(savedOnce)).toEqual(JSON.parse(savedTwice));
+  });
+
   it('blocks modified file with <=5 baseline warnings that are not cleared', async () => {
     mockAnalyze.mockResolvedValue(
       fakeAnalysis([{ file: 'src/mod.ts', line: 1, ruleId: 'test', severity: 'warning' as const, message: 'm' }])
@@ -248,12 +295,56 @@ describe('CLI integration', () => {
     expect(stdout).toContain('Usage: boy-scout');
   }, CLI_TEST_TIMEOUT);
 
-  it('runs init-baseline via CLI', async () => {
-    const { stdout } = await execAsync(
-      `npx tsx ${BOY_SCOUT_PATH} --init-baseline src/principles/boy-scout.ts`,
-      { timeout: 30000 }
-    );
-    expect(stdout).toContain('Baseline initialized successfully');
+  it('runs init-baseline via CLI against an isolated baseline', async () => {
+    try {
+      // Never point --baseline at the repo's tracked .warnings-baseline.json: this
+      // test must not mutate tracked state. Use a throwaway path instead (#445).
+      // NOTE: this file mocks 'fs/promises' (which also covers 'node:fs/promises'),
+      // so use node:fs sync APIs -- they are not intercepted.
+      const tmpBaseline = path.join(mkdtempSync(path.join(tmpdir(), 'bs-init-')), 'baseline.json');
+      const { stdout } = await execAsync(
+        `npx tsx ${BOY_SCOUT_PATH} --init-baseline src/principles/boy-scout.ts --baseline "${tmpBaseline}"`,
+        { timeout: 30000 }
+      );
+      // The command now reports a merge summary instead of the old (misleading)
+      // "Baseline initialized successfully" — it updates rather than replaces.
+      expect(stdout).toContain('Baseline updated');
+      expect(stdout).toContain(tmpBaseline);
+      expect(typeof readFileSync(tmpBaseline, 'utf-8')).toBe('string');
+    } catch (error) {
+      throw error instanceof Error ? error : new Error(String(error));
+    }
+  }, CLI_TEST_TIMEOUT);
+
+  /**
+   * @test REQ-DSH-014
+   * @intent 验证 CLI 的 --init-baseline 是合并语义：既有条目不因初始化无关文件而丢失
+   *         （#445 实测会把已跟踪基线摧毁成 {}）
+   * @covers AC-DSH-014-01
+   */
+  it('init-baseline preserves pre-existing entries (merge, not replace)', async () => {
+    try {
+      const dir = mkdtempSync(path.join(tmpdir(), 'bs-merge-'));
+      const tmpBaseline = path.join(dir, 'baseline.json');
+      writeFileSync(
+        tmpBaseline,
+        JSON.stringify({
+          'src/legacy.ts': { totalWarnings: 3, lastAnalyzed: '2026-01-01T00:00:00.000Z' },
+        }),
+        'utf-8'
+      );
+
+      await execAsync(
+        `npx tsx ${BOY_SCOUT_PATH} --init-baseline src/principles/boy-scout.ts --baseline "${tmpBaseline}"`,
+        { timeout: 30000 }
+      );
+
+      const written = JSON.parse(readFileSync(tmpBaseline, 'utf-8'));
+      expect(written['src/legacy.ts']).toBeDefined();
+      expect(written['src/legacy.ts'].totalWarnings).toBe(3);
+    } catch (error) {
+      throw error instanceof Error ? error : new Error(String(error));
+    }
   }, CLI_TEST_TIMEOUT);
 
   it('runs enforcement via CLI with empty files', async () => {