@boyingliu01/xp-gate 0.31.3 → 0.31.4

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

package/principles/adapters/__tests__/typescript-masking.test.ts

@@ -0,0 +1,96 @@
+/**
+ * @test REQ-620
+ * @intent Pin the behaviour of the literal/comment masker before it is
+ *         refactored. The masker is a four-state character scanner (line
+ *         comment, block comment, regex literal, string/template) whose output
+ *         feeds EVERY metric the rule set reads: a masking mistake changes
+ *         reported nesting depth, function length and body text for the whole
+ *         adapter. These cases are the safety net for the CCN-36 split, so they
+ *         assert observable masking outcomes (offsets preserved, literals
+ *         blanked, structure kept) rather than any internal helper shape.
+ * @covers AC-620-01
+ *
+ * Masking contract (from the function's own docblock):
+ *   - every comment / string / template / regex literal becomes spaces
+ *   - offsets and newlines are preserved exactly (length and line count equal)
+ *   - everything else is left byte-identical
+ */
+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';
+
+/** Mask a source string by round-tripping it through the adapter's parser. */
+function mask(src: string): string {
+  (readFileSync as unknown as { mockReturnValue: (v: string) => void }).mockReturnValue(src);
+  const adapter = new TypeScriptAdapter('probe.ts');
+  const ast = adapter.parseAST() as { masked?: string };
+  // The adapter exposes the masked source through a getter on the instance.
+  const masked = (adapter as unknown as { maskedSource?: string }).maskedSource;
+  return masked ?? ast.masked ?? '';
+}
+
+describe('AC-620-01: literal masking keeps offsets and blanks exactly the non-code', () => {
+  const cases: Array<[string, string]> = [
+    ['line comment', 'const a = 1; // hidden\nconst b = 2;'],
+    ['block comment', 'const a = 1; /* hidden\nstill hidden */ const b = 2;'],
+    ['single-quoted string', "const s = 'hidden text';"],
+    ['double-quoted string', 'const s = "hidden text";'],
+    ['template literal', 'const s = `hidden ${x} text`;'],
+    ['regex literal', 'const re = /hid+den/g;'],
+    ['escaped quote in string', "const s = 'it\\'s hidden';"],
+  ];
+
+  for (const [label, src] of cases) {
+    it(`preserves length and line count for a ${label}`, () => {
+      const out = mask(src);
+      expect(out.length).toBe(src.length);
+      expect(out.split('\n').length).toBe(src.split('\n').length);
+    });
+  }
+
+  it('blanks a line comment but keeps the code before it', () => {
+    const out = mask('const a = 1; // hidden');
+    expect(out).toContain('const a = 1;');
+    expect(out).not.toContain('hidden');
+  });
+
+  it('blanks a block comment across lines without eating the newline', () => {
+    const src = '/* a\nb */\nconst keep = 1;';
+    const out = mask(src);
+    expect(out).not.toContain('a\nb');
+    expect(out.split('\n').length).toBe(3);
+    expect(out).toContain('const keep = 1;');
+  });
+
+  it('blanks string contents and keeps the code around them', () => {
+    const out = mask('const s = "hidden"; const n = 42;');
+    expect(out).not.toContain('hidden');
+    expect(out).toContain('const s =');
+    expect(out).toContain('const n = 42;');
+  });
+
+  it('blanks a template literal including its interpolations', () => {
+    const out = mask('const s = `before ${x} after`;');
+    expect(out).not.toContain('before');
+    expect(out).not.toContain('after');
+    expect(out).toContain('const s =');
+  });
+
+  it('does not treat a division slash as the start of a regex literal', () => {
+    // `a / b` is division: the slash must not swallow the rest of the line.
+    const out = mask('const r = a / b; const keep = 1;');
+    expect(out).toContain('const keep = 1;');
+    expect(out).toContain('a / b');
+  });
+
+  it('leaves code with no literals byte-identical', () => {
+    const src = 'function f(a, b) {\n  return a + b;\n}';
+    expect(mask(src)).toBe(src);
+  });
+});

package/principles/adapters/cpp.ts

@@ -1,6 +1,17 @@
 import { BaseAdapter } from './base';
 import { Adapter } from '../types';
 
+/**
+ * Lexical state for the C/C++ block scanner: which comment/quote the scan is
+ * currently inside. Braces seen in any of these states are data, not structure.
+ */
+interface CppLexState {
+  inString: boolean;
+  /** Which quote character opened the string (`'` or `"`). */
+  stringChar: string;
+  inBlockComment: boolean;
+}
+
 export class CppAdapter extends BaseAdapter implements Adapter {
   detectLanguage(): string {
     const ext = this.filePath.toLowerCase();
@@ -49,61 +60,102 @@ export class CppAdapter extends BaseAdapter implements Adapter {
     return classMatches;
   }
 
+  /**
+   * Report how far the lexer can skip from `i`, updating `lex` as it goes.
+   *
+   * C and C++ share three constructs the brace tracker must not see into: line
+   * comments, block comments, and quoted literals. A `}` inside any of them is
+   * data, so counting it would truncate the function body at the wrong place.
+   *
+   * Extracted from `extractCodeBlock`, which carried all three state machines
+   * plus the brace tracking in one CCN-28 body (#620).
+   *
+   * IMPORTANT: this reports a skip distance and never decides that a character
+   * is "consumed". Returning 0 means "the caller must look at this character
+   * itself" -- which is what lets a `{` both end a literal-free run and open the
+   * block. A `//` or `/*` opener IS skippable (the tracker never wants it), and
+   * so are quotes; braces are not.
+   *
+   * @returns the number of characters to skip, or 0 when the caller must inspect.
+   */
+  private lexSkip(i: number, lex: CppLexState): number {
+    const char = this.fileContent[i];
+    const nextChar = this.fileContent[i + 1] || '';
+
+    if (lex.inBlockComment) return this.skipBlockCommentBody(i, char, nextChar, lex);
+    if (lex.inString) return this.skipStringBody(i, char, lex);
+
+    if (char === '/' && nextChar === '/') return this.skipLineComment(i);
+    if (char === '/' && nextChar === '*') {
+      lex.inBlockComment = true;
+      return 2;
+    }
+    if (char === '"' || char === "'") {
+      lex.inString = true;
+      lex.stringChar = char;
+      return 1;
+    }
+    return 0;
+  }
+
+  /** Skip a `//` comment through, but not including, the newline. */
+  private skipLineComment(start: number): number {
+    let i = start;
+    while (i < this.fileContent.length && this.fileContent[i] !== '\n') i++;
+    return i - start;
+  }
+
+  private skipBlockCommentBody(
+    i: number,
+    char: string,
+    nextChar: string,
+    lex: CppLexState,
+  ): number {
+    if (char === '*' && nextChar === '/') {
+      lex.inBlockComment = false;
+      return 2;
+    }
+    return 1;
+  }
+
+  private skipStringBody(i: number, char: string, lex: CppLexState): number {
+    if (char !== lex.stringChar) return 1;
+    // A quote closes the literal only after an EVEN number of backslashes:
+    // `"\\"` is a backslash then a terminator, `"\""` is a quote as data.
+    let backslashCount = 0;
+    let j = i - 1;
+    while (j >= 0 && this.fileContent[j] === '\\') {
+      backslashCount++;
+      j--;
+    }
+    if (backslashCount % 2 === 0) lex.inString = false;
+    return 1;
+  }
+
   override extractCodeBlock(startPos: number, maxFallback: number = 200): string {
     const state = { inBlock: false, braceCount: 0 };
+    const lex: CppLexState = { inString: false, stringChar: '', inBlockComment: false };
     let endPos = startPos;
-    let inString = false;
-    let stringChar = '';
-    let inComment = false;
-
-    for (let i = startPos; i < this.fileContent.length; i++) {
-      const char = this.fileContent[i];
-      const nextChar = this.fileContent[i + 1] || '';
-
-      if (!inString && !inComment) {
-        if (char === '/' && nextChar === '/') {
-          while (i < this.fileContent.length && this.fileContent[i] !== '\n') {
-            i++;
-          }
-          continue;
-        }
-        if (char === '/' && nextChar === '*') {
-          inComment = true;
-          i++;
-          continue;
-        }
-      } else if (inComment) {
-        if (char === '*' && nextChar === '/') {
-          inComment = false;
-          i++;
-        }
-        continue;
-      }
-
-      if (!inComment) {
-        if (!inString && (char === '"' || char === "'")) {
-          inString = true;
-          stringChar = char;
-        } else if (inString && char === stringChar) {
-          let backslashCount = 0;
-          let j = i - 1;
-          while (j >= 0 && this.fileContent[j] === '\\') {
-            backslashCount++;
-            j--;
-          }
-          if (backslashCount % 2 === 0) {
-            inString = false;
-          }
-        }
-      }
 
-      if (!inString && !inComment) {
-        const result = this.advanceBraceTracker(char, i, state);
-        if (result.closed) {
-          endPos = result.endPos;
-          break;
-        }
+    for (let i = startPos; i < this.fileContent.length;) {
+      // The lexer reports how far to skip, but must NEVER consume a character
+      // the brace tracker still has to see. A `{` both ends a literal-free run
+      // and opens the block; consuming it here would hide the function's own
+      // opening brace and leave every later brace off by one.
+      //
+      // `lexSkip` returns 0 ONLY for characters outside any literal or comment,
+      // so a positive skip already guarantees "not structural". There is
+      // deliberately no separate inString/inBlockComment test: it would be dead
+      // (verified by deleting it -- no test changes colour).
+      const skip = this.lexSkip(i, lex);
+      if (skip > 0) { i += skip; continue; }
+
+      const result = this.advanceBraceTracker(this.fileContent[i], i, state);
+      if (result.closed) {
+        endPos = result.endPos;
+        break;
       }
+      i++;
     }
 
     if (endPos > startPos) {