@boyingliu01/xp-gate 0.31.3 → 0.32.0

package/principles/__tests__/baseline-entry-total-warnings.test.ts

@@ -0,0 +1,76 @@
+/**
+ * @test REQ-620
+ * @intent Pin the single behavioural difference introduced when the two copies
+ *         of the per-tool accumulator were merged into buildEntry:
+ *         `createFromFiles` tested `totalWarnings` for TRUTHINESS, so a caller
+ *         passing an explicit `0` had it replaced by the sum of the per-tool
+ *         counts. That is exactly the case where the caller is overriding a
+ *         stale per-tool number, so the override was silently discarded.
+ *
+ *         `initializeWithAnalyzer` already used `!== undefined`, so the two
+ *         entry points disagreed about the same input. The merged version uses
+ *         the `!== undefined` reading for both.
+ * @covers AC-620-04
+ */
+import { describe, it, expect } from 'vitest';
+import { BaselineStorage } from '../baseline';
+
+function storage(): InstanceType<typeof BaselineStorage> {
+  // Explicit config: a timeout far above any test's runtime.
+  return new BaselineStorage({ maxSize: 100, timeoutMs: 10000, batchSize: 5 });
+}
+
+describe('AC-620-04: an explicit totalWarnings wins, including zero', () => {
+  it('uses an explicit zero instead of the summed per-tool count', async () => {
+    const baseline = await storage().createFromFiles([
+      { file: 'a.ts', counts: { eslint: { warnings: 3, errors: 0 }, totalWarnings: 0 } },
+    ]);
+    expect(baseline['a.ts'].totalWarnings).toBe(0);
+  });
+
+  it('uses an explicit nonzero value instead of the summed count', async () => {
+    const baseline = await storage().createFromFiles([
+      { file: 'a.ts', counts: { eslint: { warnings: 3, errors: 0 }, totalWarnings: 42 } },
+    ]);
+    expect(baseline['a.ts'].totalWarnings).toBe(42);
+  });
+
+  it('sums the per-tool counts when no explicit total is given', async () => {
+    const baseline = await storage().createFromFiles([
+      {
+        file: 'a.ts',
+        counts: {
+          eslint: { warnings: 3, errors: 0 },
+          ruff: { warnings: 2, errors: 1 },
+        },
+      },
+    ]);
+    expect(baseline['a.ts'].totalWarnings).toBe(5);
+  });
+
+  it('keeps every per-tool count it was given', async () => {
+    const baseline = await storage().createFromFiles([
+      {
+        file: 'a.ts',
+        counts: {
+          eslint: { warnings: 1, errors: 2 },
+          ccn: { warnings: 3, max: 9 },
+          shellcheck: { warnings: 4, errors: 5 },
+        },
+      },
+    ]);
+    const entry = baseline['a.ts'];
+    expect(entry.eslint).toEqual({ warnings: 1, errors: 2 });
+    expect(entry.ccn).toEqual({ warnings: 3, max: 9 });
+    expect(entry.shellcheck).toEqual({ warnings: 4, errors: 5 });
+    // Tools that were not supplied must not appear at all.
+    expect(entry.ruff).toBeUndefined();
+    expect(entry.golangci).toBeUndefined();
+  });
+
+  it('reports zero warnings for a file with no tool counts', async () => {
+    const baseline = await storage().createFromFiles([{ file: 'a.ts', counts: {} }]);
+    expect(baseline['a.ts'].totalWarnings).toBe(0);
+    expect(baseline['a.ts'].lastAnalyzed).toBeTypeOf('string');
+  });
+});

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

@@ -336,3 +336,64 @@ describe('#452 REQ-3 stale baseline entries are pruned', () => {
     }
   });
 });
+
+/**
+ * @test REQ-628
+ * @intent `parseBaselineFiles` accepts two shapes: the FLAT map that
+ *         `saveBaseline` writes, and a legacy `{files: {...}}` wrapper kept for
+ *         forwards compatibility. The wrapper branch had no test, so deleting it
+ *         left the whole suite green — a silent regression that would make every
+ *         real baseline look empty (all entries filtered out as non-objects,
+ *         since the only top-level key is `files`). These cases pin both shapes
+ *         plus the scalar-filtering rule that follows from them.
+ * @covers AC-628-01, AC-628-02, AC-628-03
+ */
+describe('#628 REQ-3 parseBaselineFiles shape handling', () => {
+  it('AC-628-01: a flat map is read entry-for-entry', () => {
+    const { root } = makeRepoWithCommit();
+    const flat = JSON.stringify({
+      'src/a.ts': { totalWarnings: 2, lastAnalyzed: '2026-01-01T00:00:00Z' },
+      'src/gone.ts': { totalWarnings: 1, lastAnalyzed: '2026-01-01T00:00:00Z' },
+    });
+    stageIndexOnly(root, ['src/a.ts']);
+
+    const result = pruneBaselineEntries(flat, root);
+    expect(result.kept).toContain('src/a.ts');
+    expect(result.removed).toContain('src/gone.ts');
+    expect(result.error).toBeUndefined();
+  });
+
+  it('AC-628-02: a {files:{...}} wrapper is unwrapped, not treated as one entry', () => {
+    const { root } = makeRepoWithCommit();
+    // Without the unwrap, the sole top-level key `files` is an object, so the
+    // flat path would yield ONE entry called "files" and silently lose every
+    // real path. Assert the real paths surface.
+    const wrapped = JSON.stringify({
+      files: {
+        'src/a.ts': { totalWarnings: 2, lastAnalyzed: '2026-01-01T00:00:00Z' },
+        'src/gone.ts': { totalWarnings: 1, lastAnalyzed: '2026-01-01T00:00:00Z' },
+      },
+    });
+    stageIndexOnly(root, ['src/a.ts']);
+
+    const result = pruneBaselineEntries(wrapped, root);
+    expect(result.kept).toContain('src/a.ts');
+    expect(result.removed).toContain('src/gone.ts');
+    expect(result.kept).not.toContain('files');
+  });
+
+  it('AC-628-03: scalar top-level keys are metadata and are dropped, not kept as entries', () => {
+    const { root } = makeRepoWithCommit();
+    const withMeta = JSON.stringify({
+      version: 2,
+      generatedAt: '2026-01-01T00:00:00Z',
+      'src/a.ts': { totalWarnings: 2, lastAnalyzed: '2026-01-01T00:00:00Z' },
+    });
+    stageIndexOnly(root, ['src/a.ts']);
+
+    const result = pruneBaselineEntries(withMeta, root);
+    expect(result.kept).toEqual(['src/a.ts']);
+    expect(result.kept).not.toContain('version');
+    expect(result.kept).not.toContain('generatedAt');
+  });
+});

package/principles/__tests__/cli-files-separators.test.ts

@@ -0,0 +1,69 @@
+/**
+ * @test REQ-623
+ * @intent `--files` must accept the shapes a shell actually produces. CI passed
+ *         `--files "$SRC_FILES"` -- one argument containing newline-separated
+ *         paths -- and parseArgs split on spaces only, so the whole blob became
+ *         a single impossible path. The run then had nothing to analyse and fell
+ *         through to the console/empty path, writing "✓ No violations found"
+ *         into a file named principles.sarif. The step exited 0, so for months
+ *         the GitHub Security tab received a text file where SARIF was expected.
+ *
+ *         These tests pin the separator handling, not one call site: a fix that
+ *         only changes the workflow leaves the next caller to hit the same trap.
+ * @covers AC-623-01, AC-623-02, AC-623-03
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseArgs } from '../index';
+
+describe('AC-623-01: --files separates on any whitespace, not just spaces', () => {
+  it('splits a newline-separated list (the CI shape)', () => {
+    const opts = parseArgs(['--files', 'a.ts\nb.ts\nc.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts', 'c.ts']);
+  });
+
+  it('splits a space-separated list', () => {
+    const opts = parseArgs(['--files', 'a.ts b.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('splits a tab-separated list', () => {
+    const opts = parseArgs(['--files', 'a.ts\tb.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('drops the blank entries a trailing separators leave behind', () => {
+    const opts = parseArgs(['--files', 'a.ts\n\nb.ts\n']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('keeps a single path intact', () => {
+    const opts = parseArgs(['--files', 'src/one.ts']);
+    expect(opts.files).toEqual(['src/one.ts']);
+  });
+});
+
+describe('AC-623-02: a flag after --files is still parsed', () => {
+  it('reads --format sarif that follows a multi-line --files value', () => {
+    const opts = parseArgs(['--files', 'a.ts\nb.ts', '--format', 'sarif']);
+    expect(opts.format).toBe('sarif');
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('reads --format when it comes before --files', () => {
+    const opts = parseArgs(['--format', 'sarif', '--files', 'a.ts\nb.ts']);
+    expect(opts.format).toBe('sarif');
+  });
+});
+
+describe('AC-623-03: positional paths still accumulate', () => {
+  it('collects bare paths given without --files', () => {
+    const opts = parseArgs(['a.ts', 'b.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('accepts --files alongside positional paths', () => {
+    const opts = parseArgs(['--files', 'a.ts\nb.ts', 'c.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts', 'c.ts']);
+  });
+});

package/principles/__tests__/config-merge-warnings.test.ts

@@ -0,0 +1,148 @@
+/**
+ * @test REQ-620
+ * @intent Pin mergeRule's mistyped-override handling, which had NO coverage
+ *         before this change: nothing asserted the warning text or the
+ *         keep-the-default outcome for a bad .principlesrc value. That gap
+ *         meant the four per-key loops could be consolidated into one guarded
+ *         loop without any test noticing, so these tests are what makes the
+ *         consolidation verifiable rather than merely plausible.
+ *
+ *         Two properties per key category:
+ *           1. a correctly-typed override is applied;
+ *           2. a mistyped one is REJECTED and the default survives, with a
+ *              warning naming the rule and the key.
+ *         Property 2 is the one with teeth: silently accepting a bad value
+ *         would let a project believe it tightened a gate.
+ *
+ *         .principlesrc is JSON (config.ts parses it with JSON.parse), so the
+ *         fixtures are JSON objects rather than YAML text.
+ * @covers AC-620-05
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadConfig, getDefaultConfig } from '../config';
+
+let tmpDirs: string[] = [];
+let warnings: string[];
+
+beforeEach(() => {
+  tmpDirs = [];
+  warnings = [];
+  // config.ts reports through process.stderr.write, not console.warn, so the
+  // spy has to sit on the stream. (Mocking console.warn instead silently
+  // captured nothing and made every "must warn" assertion look like a bug.)
+  vi.spyOn(process.stderr, 'write').mockImplementation((chunk: unknown) => {
+    warnings.push(String(chunk));
+    return true;
+  });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function warnText(): string {
+  return warnings.join('\n');
+}
+
+/** Default value of one key on `clean-code.long-function`. */
+function defaultFor(key: string): unknown {
+  const rule = getDefaultConfig().rules['clean-code']['long-function'] as unknown as Record<string, unknown>;
+  return rule[key];
+}
+
+/** Write a .principlesrc from RAW JSON text and load it unchanged. */
+async function loadRaw(jsonText: string) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-gate-cfg-'));
+  tmpDirs.push(dir);
+  const cfgPath = path.join(dir, '.principlesrc');
+  fs.writeFileSync(cfgPath, jsonText, 'utf8');
+  return loadConfig(cfgPath);
+}
+
+/** Write a .principlesrc overriding `clean-code.long-function` and load it. */
+async function loadWithRule(overrides: Record<string, unknown>) {
+  return loadRaw(JSON.stringify({ rules: { 'clean-code': { 'long-function': overrides } } }));
+}
+
+describe('AC-620-05: a mistyped rule override keeps the default and warns', () => {
+  it('accepts a well-typed numeric override (threshold)', async () => {
+    const merged = await loadWithRule({ threshold: 12 });
+    expect(merged.rules['clean-code']['long-function'].threshold).toBe(12);
+    expect(warnText()).not.toMatch(/threshold/);
+  });
+
+  it('rejects a non-numeric threshold and keeps the default', async () => {
+    const merged = await loadWithRule({ threshold: 'not-a-number' });
+    expect(merged.rules['clean-code']['long-function'].threshold).toBe(defaultFor('threshold'));
+    expect(warnText()).toMatch(/threshold/);
+  });
+
+  it('rejects a non-finite threshold and keeps the default', async () => {
+    // A guard that only checks `typeof value === 'number'` would accept these
+    // and compare every function against NaN (or Infinity, which nothing ever
+    // exceeds -- silently disabling the rule).
+    //
+    // These literals have to be written as raw JSON TEXT: JSON.stringify turns
+    // NaN and Infinity into `null`, so handing them to the object-based helper
+    // would inject null and the test would pass against a broken guard. That
+    // exact mistake made the first version of this test vacuous.
+    const fallback = defaultFor('threshold');
+    for (const literal of ['1e999', '-1e999']) {
+      warnings = [];
+      const merged = await loadRaw(
+        `{"rules":{"clean-code":{"long-function":{"threshold":${literal}}}}}`,
+      );
+      expect(merged.rules['clean-code']['long-function'].threshold).toBe(fallback);
+      expect(warnText()).toMatch(/threshold/);
+    }
+  });
+
+  it('accepts a well-typed array override (exclude)', async () => {
+    const merged = await loadWithRule({ exclude: ['**/skip.ts'] });
+    expect(merged.rules['clean-code']['long-function'].exclude).toEqual(['**/skip.ts']);
+  });
+
+  it('rejects a scalar where an array is expected and keeps the default', async () => {
+    const merged = await loadWithRule({ exclude: '**/skip.ts' });
+    expect(merged.rules['clean-code']['long-function'].exclude).toEqual(defaultFor('exclude'));
+    expect(warnText()).toMatch(/exclude/);
+  });
+
+  it('copies the accepted array instead of aliasing the parsed one', async () => {
+    // mergeRule spreads array candidates; sharing the reference would let a
+    // later mutation of the caller's array leak into the active config.
+    const source = ['**/skip.ts'];
+    const merged = await loadWithRule({ exclude: source });
+    expect(merged.rules['clean-code']['long-function'].exclude).not.toBe(source);
+    expect(merged.rules['clean-code']['long-function'].exclude).toEqual(source);
+  });
+
+  it('accepts a well-typed enum override (severity)', async () => {
+    const merged = await loadWithRule({ severity: 'error' });
+    expect(merged.rules['clean-code']['long-function'].severity).toBe('error');
+  });
+
+  it('rejects an out-of-vocabulary severity and keeps the default', async () => {
+    // The dangerous case: a project writes a severity it believes is blocking
+    // but misspells it. Silently keeping the default would let that belief stand.
+    const merged = await loadWithRule({ severity: 'fatal' });
+    expect(merged.rules['clean-code']['long-function'].severity).toBe(defaultFor('severity'));
+    expect(warnText()).toMatch(/severity/);
+  });
+
+  it('rejects a non-boolean enabled flag and keeps the default', async () => {
+    const merged = await loadWithRule({ enabled: 'yes' });
+    expect(typeof merged.rules['clean-code']['long-function'].enabled).toBe('boolean');
+    expect(warnText()).toMatch(/enabled/);
+  });
+
+  it('names the offending rule and key in the warning', async () => {
+    await loadWithRule({ severity: 'fatal' });
+    expect(warnText()).toContain('long-function');
+    expect(warnText()).toContain('severity');
+  });
+});

package/principles/adapters/__tests__/cpp-code-block.test.ts

@@ -0,0 +1,123 @@
+/**
+ * @test REQ-620
+ * @intent Pin the C/C++ code-block scanner's treatment of comments and string
+ *         literals before its CCN-28 body is split.
+ *
+ *         Every case is built to DEFEAT the fallback path. `extractCodeBlock`
+ *         falls back to `substring(startPos)` capped at 200 characters, so a
+ *         short fixture returns "the whole thing" even when the scanner never
+ *         found a closing brace -- the assertions then pass on a broken scanner.
+ *         Each source below therefore pads past 200 characters and asserts the
+ *         exact end position, so a truncated scan cannot look correct.
+ *
+ *         Verified by injecting three real defects (brace tracker seeing into
+ *         strings, block comments untracked, backslash parity ignored): each one
+ *         reddens at least one case here.
+ * @covers AC-620-03
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { CppAdapter } from '../cpp';
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(() => true),
+}));
+
+import { readFileSync } from 'fs';
+
+const MARKER = 'END_OF_FUNCTION';
+/** Padding that keeps the source well past the 200-char fallback cap. */
+const PAD = ' '.repeat(240);
+
+function block(src: string, start = 0): string {
+  (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(src);
+  const adapter = new CppAdapter('probe.cpp');
+  return adapter.extractCodeBlock(start);
+}
+
+/**
+ * Build `void f() { <body> }` followed by `<MARKER>`, padded past the fallback
+ * cap. The padding sits INSIDE the function body so the fallback (which runs to
+ * the 200-char cap) would include the marker, while a correct scan stops at the
+ * real closing brace and does not.
+ */
+function wrap(body: string): { src: string; open: number } {
+  const src = `void f() {\n${body}\n${PAD}\n}${MARKER}`;
+  return { src, open: src.indexOf('{') };
+}
+
+describe('AC-620-03: the C/C++ block scanner ignores braces in comments and strings', () => {
+  it('returns exactly the balanced body of a plain function', () => {
+    const { src, open } = wrap('  int a = 1;');
+    const out = block(src, open);
+    expect(out, `tail=${JSON.stringify(out.slice(-60))} len=${out.length}`).toMatch(/}$/);
+  });
+
+  it('does not close on a brace inside a line comment', () => {
+    const { src, open } = wrap('  // } not the end\n  int a = 1;');
+    const out = block(src, open);
+    expect(out, `extracted: ${JSON.stringify(out.slice(0, 80))}`).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('does not close on a brace inside a block comment', () => {
+    const { src, open } = wrap('  /* } not the end */\n  int a = 1;');
+    const out = block(src, open);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('does not close on a brace inside a string literal', () => {
+    const { src, open } = wrap('  const char* s = "}";\n  int a = 1;');
+    const out = block(src, open);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('keeps scanning past a string that CONTAINS the only early close brace', () => {
+    // The string's `}` is the first `}` after the opener. A scanner that counts
+    // it ends the block immediately and never reaches the statements below.
+    const { src, open } = wrap('  const char* s = "}";\n  int markerStatement = 1;\n  int tail = 2;');
+    const out = block(src, open);
+    expect(out, `extracted: ${JSON.stringify(out.slice(0, 120))}`)
+      .toContain('int tail = 2;');
+  });
+
+  it('keeps scanning past a char literal that contains a close brace', () => {
+    const { src, open } = wrap("  char c = '}';\n  int tail = 2;");
+    const out = block(src, open);
+    expect(out).toContain('int tail = 2;');
+  });
+
+  it('does not close on a brace inside a char literal', () => {
+    const { src, open } = wrap("  char c = '}';\n  int a = 1;");
+    const out = block(src, open);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('treats an escaped quote inside a string as data, not a terminator', () => {
+    // `\"` does not close the string, so the `}` after it is still string data.
+    const { src, open } = wrap('  const char* s = "a\\"}b";\n  int a = 1;');
+    const out = block(src, open);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('treats an even run of backslashes as NOT escaping the quote', () => {
+    // `\\` is a literal backslash, so the following `"` DOES close the string,
+    // and the `}` that ends the line is real structure.
+    const { src, open } = wrap('  const char* s = "a\\\\";\n  int a = 1;');
+    const out = block(src, open);
+    expect(out.trimEnd().endsWith('}')).toBe(true);
+    expect(out).toContain('int a = 1;');
+    expect(out).not.toContain(MARKER);
+  });
+
+  it('falls back when no balanced block is ever found', () => {
+    const src = 'void f() {\n  int a = 1;' + PAD;
+    const out = block(src, 9);
+    expect(out.length).toBe(200);
+    expect(out.length).toBeLessThan(src.length);
+  });
+});

package/principles/adapters/__tests__/cpp-scanner-equivalence.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @test REQ-620
+ * @intent Prove the C/C++ block scanner split is behaviour-preserving on real
+ *         source, not just on the handful of fixtures above. The scanner feeds
+ *         every C/C++ metric (length, nesting, io operations), so an off-by-one
+ *         in the refactored loop would silently shift every reported span.
+ * @covers AC-620-03
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { CppAdapter } from '../cpp';
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(() => true),
+}));
+
+import { readFileSync } from 'fs';
+
+const SOURCE = [
+  '#include <stdio.h>',
+  '/* a header comment with a } brace */',
+  'int helper(int x) {',
+  '  // a line comment with a } brace',
+  '  return x * 2;',
+  '}',
+  '',
+  'int main(void) {',
+  '  const char* msg = "a } inside a string";',
+  "  char c = '}';",
+  '  /* block } comment */',
+  '  if (helper(1) > 0) {',
+  '    printf("%s", msg);',
+  '  }',
+  '  return 0;',
+  '}',
+].join('\n');
+
+describe('AC-620-03: the split scanner finds the same spans as the original', () => {
+  it('extracts main() up to its real closing brace', () => {
+    (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(SOURCE);
+    const adapter = new CppAdapter('probe.c');
+    const start = SOURCE.indexOf('int main(void)');
+    const open = SOURCE.indexOf('{', start);
+    const out = adapter.extractCodeBlock(open);
+
+    // The body must run to the LAST brace of main, not to the `}` in a comment
+    // or a string. Line count is the cheap proxy for "did not truncate".
+    const bodyLines = out.split('\n').length;
+    expect(bodyLines, `extracted: ${JSON.stringify(out)}`).toBe(
+      SOURCE.slice(open).split('\n').length,
+    );
+    expect(out).toContain('return 0;');
+  });
+
+  it('every declaration in the file yields a span that ends on a balanced brace', () => {
+    (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(SOURCE);
+    const adapter = new CppAdapter('probe.c');
+    const fns = adapter.extractFunctions() as Array<{ name: string; code?: string }>;
+    expect(fns.length).toBeGreaterThanOrEqual(2);
+    for (const fn of fns) {
+      if (!fn.code) continue;
+      // Balanced braces modulo the literals/comments the scanner masks.
+      expect(fn.code.length, `${fn.name} produced an empty or unbounded span`)
+        .toBeLessThanOrEqual(SOURCE.length);
+    }
+  });
+});

package/principles/adapters/__tests__/typescript-block-comment-lines.test.ts

@@ -0,0 +1,53 @@
+/**
+ * @test REQ-620
+ * @intent Prove the block-comment masking defect before fixing it. The masker's
+ *         contract is to preserve offsets and newlines so that `lineOf()` and
+ *         every line-numbered violation stays correct. A block comment
+ *         containing a newline is currently collapsed, shifting every later
+ *         line number up -- which silently mislabels every violation that
+ *         follows a multi-line comment in the file.
+ * @covers AC-620-02
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { TypeScriptAdapter } from '../typescript';
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(() => true),
+}));
+
+import { readFileSync } from 'fs';
+
+function mask(src: string): string {
+  (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(src);
+  const adapter = new TypeScriptAdapter('probe.ts');
+  return (adapter as unknown as { maskedSource: string }).maskedSource;
+}
+
+describe('AC-620-02: a multi-line block comment must not shift later line numbers', () => {
+  it('keeps the newline inside a block comment', () => {
+    const src = '/* a\nb */\nconst keep = 1;';
+    const out = mask(src);
+    expect(out.split('\n').length).toBe(src.split('\n').length);
+  });
+
+  it('keeps the line count when the block comment spans three lines', () => {
+    const src = '/* one\ntwo\nthree */\nconst keep = 1;\nconst also = 2;';
+    const out = mask(src);
+    expect(out.split('\n').length).toBe(src.split('\n').length);
+    expect(out).toContain('const keep = 1;');
+    expect(out).toContain('const also = 2;');
+  });
+
+  it('reports a function line number that matches the physical source', () => {
+    // The function starts on physical line 4; a collapsed block comment would
+    // make the adapter report line 2.
+    const src = ['/* a', 'b', 'c */', 'function target() {', '  return 1;', '}'].join('\n');
+    (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(src);
+    const adapter = new TypeScriptAdapter('probe.ts');
+    const fns = adapter.extractFunctions() as Array<{ name: string; line: number }>;
+    const target = fns.find((f) => f.name === 'target');
+    expect(target).toBeDefined();
+    expect(target!.line).toBe(4);
+  });
+});