@boyingliu01/xp-gate 0.31.1 → 0.31.3

package/principles/rules/__tests__/solid/issue-588-lsp-base-contract.test.ts

@@ -0,0 +1,252 @@
+/**
+ * @test REQ-618
+ * @intent The LSP rule must still DETECT a real violation when the base contract is
+ *        available in the same file, so that #588's "stay silent when undetermined" fix
+ *        does not degenerate into "never report anything".
+ * @covers AC-618-04, AC-618-05
+ */
+import { describe, it, expect } from 'vitest';
+import { lspRule } from '../../solid/lsp';
+
+/** Adapter stub exposing exactly what the rule consumes. */
+function adapterFor(classes: Array<{ name?: string; line?: number; code?: string }>) {
+  return {
+    detectLanguage: () => 'java',
+    parseAST: () => undefined,
+    extractFunctions: () => [],
+    extractClasses: () => classes,
+    countLines: () => 0,
+  };
+}
+
+/**
+ * A base class and a derived class in ONE file.
+ *
+ * `handle(DataSource ds)` is the base contract; the derived class may honour it or break
+ * it. Both classes are visible, so the rule has everything it needs to decide — which is
+ * exactly the case #588's fix must NOT silence.
+ */
+const BASE_WITH_ONE_PARAM = `
+class BaseHandler {
+  public void handle(DataSource ds) { }
+}
+`;
+
+/** Line where the derived class starts in the two-class fixtures below. */
+const DERIVED_CLASS_LINE = 4;
+
+/** Line where the derived TypeScript class starts in the two-line-header fixtures. */
+const TS_DERIVED_CLASS_LINE = 3;
+
+describe('solid.lsp detects a violation when the base contract IS available', () => {
+  it('reports a derived parameter type the base method does not accept', () => {
+    const violations = lspRule.check('Handlers.java', adapterFor([
+      { name: 'BaseHandler', line: 1, code: BASE_WITH_ONE_PARAM },
+      {
+        name: 'CsvHandler',
+        line: DERIVED_CLASS_LINE,
+        code: `class CsvHandler extends BaseHandler {
+  public void handle(FileChannel channel) { }
+}`,
+      },
+    ]) as never);
+
+    // The point of the whole rule: an override that narrows or changes the parameter type
+    // breaks substitutability, and here both sides are visible so the claim is earned.
+    expect(violations.length).toBeGreaterThan(0);
+    expect(violations[0].ruleId).toBe('solid.lsp');
+    expect(violations[0].message).toContain('FileChannel');
+  });
+
+  it('stays silent when the override keeps the base parameter type', () => {
+    const violations = lspRule.check('Handlers.java', adapterFor([
+      { name: 'BaseHandler', line: 1, code: BASE_WITH_ONE_PARAM },
+      {
+        name: 'CsvHandler',
+        line: DERIVED_CLASS_LINE,
+        code: `class CsvHandler extends BaseHandler {
+  public void handle(DataSource ds) { }
+}`,
+      },
+    ]) as never);
+
+    expect(violations).toHaveLength(0);
+  });
+
+  it('stays silent when the base class is NOT in the file', () => {
+    // The control for the two cases above: same derived code, no base declaration
+    // available. Without this, a rule that simply reported every non-primitive parameter
+    // would pass the first case and fail only by accident elsewhere.
+    const violations = lspRule.check('Handlers.java', adapterFor([
+      {
+        name: 'CsvHandler',
+        line: 1,
+        code: `class CsvHandler extends BaseHandler {
+  public void handle(FileChannel channel) { }
+}`,
+      },
+    ]) as never);
+
+    expect(violations).toHaveLength(0);
+  });
+
+  it('stays silent when the base method itself is not declared', () => {
+    // Base visible, but it does not declare `handle` at all — an inherited method from
+    // further up, which this analysis cannot see. Not a violation, not verifiable.
+    const baseWithoutHandle = `class BaseHandler { public void close() { } }`;
+    const violations = lspRule.check('Handlers.java', adapterFor([
+      { name: 'BaseHandler', line: 1, code: baseWithoutHandle },
+      {
+        name: 'CsvHandler',
+        line: 2,
+        code: `class CsvHandler extends BaseHandler {
+  public void handle(FileChannel channel) { }
+}`,
+      },
+    ]) as never);
+
+    expect(violations).toHaveLength(0);
+  });
+
+  it('resolves a base class referenced through a qualified name', () => {
+    // `extends com.acme.BaseHandler` is ordinary Java; a plain string compare would miss
+    // the base and silently downgrade a decidable case to silence.
+    const violations = lspRule.check('Handlers.java', adapterFor([
+      { name: 'BaseHandler', line: 1, code: BASE_WITH_ONE_PARAM },
+      {
+        name: 'CsvHandler',
+        line: 2,
+        code: `class CsvHandler extends com.acme.BaseHandler {
+  public void handle(FileChannel channel) { }
+}`,
+      },
+    ]) as never);
+
+    expect(violations.length).toBeGreaterThan(0);
+  });
+
+  it('treats a parameter type the base method also declares as compatible', () => {
+    // The positive half of the base comparison: this is the branch that returns `true`,
+    // i.e. "I have a base contract AND it accepts this type". Without it the only
+    // observable outcome of the base path would be a violation, and a rule that reported
+    // every override with a resolvable base would still pass every other case here.
+    const base = `class BaseHandler { public void handle(DataSource ds) { } }`;
+    const violations = lspRule.check('Handlers.java', adapterFor([
+      { name: 'BaseHandler', line: 1, code: base },
+      {
+        name: 'CsvHandler',
+        line: 2,
+        code: `class CsvHandler extends BaseHandler {
+  public void handle(DataSource ds) { }
+}`,
+      },
+    ]) as never);
+
+    expect(violations).toHaveLength(0);
+  });
+
+  it('handles a generic and an array parameter type without crashing', () => {
+    // Exercises `normaliseTypeName`'s stripping of `<...>`, `[]` and `?`. Those suffixes
+    // are the reason `Map<String, Item>` does not get compared as the literal string
+    // "Map<String, Item>", and the array/optional forms are ordinary in both languages.
+    const base = `class BaseHandler { public void handle(Map<String, Item> index) { } }`;
+    const violations = lspRule.check('Handlers.java', adapterFor([
+      { name: 'BaseHandler', line: 1, code: base },
+      {
+        name: 'CsvHandler',
+        line: 2,
+        code: `class CsvHandler extends BaseHandler {
+  public void handle(Map<String, Item> index) { }
+}`,
+      },
+    ]) as never);
+
+    expect(violations).toHaveLength(0);
+  });
+
+  it('reads TypeScript `name: Type` parameters, not Java ones', () => {
+    // Every other case here runs the Java path. The rule is shared by both languages, and
+    // #588's whole lesson is that a parser which only works for one of them silently
+    // mangles the other — so the TypeScript path needs its own case, exercising
+    // `extractTsParamType` rather than `extractJavaParamType`.
+    const tsAdapter = { ...adapterFor([]), detectLanguage: () => 'typescript' };
+    const base = `class BaseHandler {
+  handle(ds: DataSource): void {}
+}`;
+    const derived = `class CsvHandler extends BaseHandler {
+  handle(channel: FileChannel): void {}
+}`;
+    const violations = lspRule.check('handlers.ts', {
+      ...tsAdapter,
+      extractClasses: () => [
+        { name: 'BaseHandler', line: 1, code: base },
+        { name: 'CsvHandler', line: TS_DERIVED_CLASS_LINE, code: derived },
+      ],
+    } as never);
+
+    expect(violations.length).toBeGreaterThan(0);
+    expect(violations[0].message).toContain('FileChannel');
+  });
+
+  it('stays silent for a TypeScript override that matches the base', () => {
+    const tsAdapter = { ...adapterFor([]), detectLanguage: () => 'typescript' };
+    const base = `class BaseHandler {
+  handle(ds: DataSource): void {}
+}`;
+    const derived = `class CsvHandler extends BaseHandler {
+  handle(ds: DataSource): void {}
+}`;
+    const violations = lspRule.check('handlers.ts', {
+      ...tsAdapter,
+      extractClasses: () => [
+        { name: 'BaseHandler', line: 1, code: base },
+        { name: 'CsvHandler', line: TS_DERIVED_CLASS_LINE, code: derived },
+      ],
+    } as never);
+
+    expect(violations).toHaveLength(0);
+  });
+
+  it('treats an adapter without detectLanguage as non-Java rather than crashing', () => {
+    // Older or third-party adapters may not implement `detectLanguage`. The rule must
+    // fall back to the `name: Type` reading instead of throwing on an absent method —
+    // a crash here would surface as a Gate 4 rule error, not as silence.
+    const adapterWithoutLanguage = {
+      parseAST: () => undefined,
+      extractFunctions: () => [],
+      countLines: () => 0,
+      extractClasses: () => [
+        { name: 'BaseHandler', line: 1, code: `class BaseHandler {\n  handle(ds: DataSource): void {}\n}` },
+        {
+          name: 'CsvHandler',
+          line: TS_DERIVED_CLASS_LINE,
+          code: `class CsvHandler extends BaseHandler {\n  handle(channel: FileChannel): void {}\n}`,
+        },
+      ],
+    };
+
+    const violations = lspRule.check('handlers.ts', adapterWithoutLanguage as never);
+
+    expect(violations.length).toBeGreaterThan(0);
+  });
+
+  it('ignores a TypeScript parameter with no type annotation', () => {
+    // `handle(id)` has no `: Type`, so `extractTsParamType` returns null and the parameter
+    // contributes nothing. Without this the missing-annotation path is untested after the
+    // #588 rewrite, and a regex change could start inventing types out of parameter names.
+    const tsAdapter = {
+      ...adapterFor([]),
+      detectLanguage: () => 'typescript',
+      extractClasses: () => [
+        { name: 'BaseHandler', line: 1, code: `class BaseHandler {\n  handle(id): void {}\n}` },
+        {
+          name: 'CsvHandler',
+          line: TS_DERIVED_CLASS_LINE,
+          code: `class CsvHandler extends BaseHandler {\n  handle(id): void {}\n}`,
+        },
+      ],
+    };
+
+    expect(lspRule.check('handlers.ts', tsAdapter as never)).toHaveLength(0);
+  });
+});

package/principles/rules/__tests__/solid/lsp.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { lspRule } from '../../solid/lsp';
+import { lspRule, buildViolation } from '../../solid/lsp';
 
 const mockAdapter = {
   detectLanguage: () => 'typescript',
@@ -10,7 +10,12 @@ const mockAdapter = {
 };
 
 describe('lsp.ts - Liskov Substitution Principle Rule', () => {
-  it('should detect parameter type changes in override', () => {
+  it('stays silent on a parameter type it cannot resolve against the base contract', () => {
+    // #588 changed what this rule is allowed to claim. `UserId` is neither a primitive nor
+    // a prefix of the class name, so a single-file analysis has no way to know what the
+    // BASE class declares — and "cannot determine" must not be reported as a violation.
+    // The previous expectation here asserted the defect: it read an unknown type as proof
+    // of incompatibility, which on Java flagged every class that has `extends`.
     const mockAdapterWithViolation = {
       ...mockAdapter,
       extractClasses: () => [{
@@ -19,11 +24,10 @@ describe('lsp.ts - Liskov Substitution Principle Rule', () => {
         code: `class DerivedRepo extends BaseRepo { findById(id: UserId): Entity {} }`
       }]
     };
-    
+
     const violations = lspRule.check('test.ts', mockAdapterWithViolation as never);
-    
-    expect(violations.length).toBeGreaterThan(0);
-    expect(violations[0].ruleId).toBe('solid.lsp');
+
+    expect(violations).toHaveLength(0);
   });
 
   it('should pass for proper override', () => {
@@ -152,8 +156,10 @@ class DerivedRepo extends BaseRepo {
     expect(violations).toHaveLength(0);
   });
 
-  it('reports violation with className undefined (className && ... false branch)', () => {
-    // cls.name undefined → className && ... short-circuits to false → incompatible
+  it('stays silent even when the class name is missing (no name is not evidence)', () => {
+    // This used to report, on the reasoning that `className && ...` short-circuits to
+    // false. Under #588 that is precisely the defect: an ABSENT name is one more thing the
+    // analysis does not know, so it cannot justify a verdict.
     const adapter = {
       ...mockAdapter,
       extractClasses: () => [{
@@ -162,21 +168,19 @@ class DerivedRepo extends BaseRepo {
       }],
     };
     const violations = lspRule.check('test.ts', adapter as never);
-    expect(violations.length).toBeGreaterThan(0);
-    expect(violations[0].ruleId).toBe('solid.lsp');
+    expect(violations).toHaveLength(0);
   });
 
-  it('falls back to line 0 when cls.line is missing', () => {
-    const adapter = {
-      ...mockAdapter,
-      extractClasses: () => [{
-        name: 'D',
-        // no line
-        code: `class D extends B { foo(id: CustomId) {} }`,
-      }],
-    };
-    const violations = lspRule.check('test.ts', adapter as never);
-    expect(violations.length).toBeGreaterThan(0);
-    expect(violations[0].line).toBe(0);
+  it('falls back to line 0 when a violation is built for a class with no line', () => {
+    // Asserted on the builder directly. After #588 `lspRule.check` can no longer reach
+    // this code path for an unknown type — that is the fix — so a case going through
+    // `check` would pass without exercising the `?? 0` fallback at all. A control that
+    // cannot fail proves nothing, which is why the import is explicit.
+    const violation = buildViolation('test.ts', { name: 'D' }, 'CustomId');
+    expect(violation.line).toBe(0);
+    expect(violation.ruleId).toBe('solid.lsp');
+    // And the line is honoured when present, so the fallback is not always taken.
+    const withLine = buildViolation('test.ts', { name: 'D', line: 42 }, 'CustomId');
+    expect(withLine.line).toBe(42);
   });
 });