Filter out "parameter missing" errors when not connected, fix flaky test suite (#688)

Author: anderson4j

.changeset/major-beds-wave.md

@@ -0,0 +1,7 @@
+---
+"@neo4j-cypher/language-support": patch
+"@neo4j-cypher/react-codemirror": patch
+"@neo4j-cypher/language-server": patch
+---
+
+Hide parameter errors when disconnected

packages/language-server/src/linting.ts

@@ -1,6 +1,8 @@
 import {
   clampUnsafePositions,
+  isNotParamError,
   SymbolTable,
+  SyntaxDiagnostic,
 } from '@neo4j-cypher/language-support';
 import { Neo4jSchemaPoller } from '@neo4j-cypher/query-tools';
 import debounce from 'lodash.debounce';
@@ -63,12 +65,6 @@ async function rawLintDocument(
     });
     const result = await lastSemanticJob;
 
-    //marks the entire text if any position is negative
-    const positionSafeResult = clampUnsafePositions(
-      result.diagnostics,
-      document,
-    );
-
     // Pass the computed symbol tables to the parser
     if (result.symbolTables) {
       languageService.setSymbolsInfo(
@@ -80,14 +76,30 @@ async function rawLintDocument(
       );
     }
 
-    sendDiagnostics(positionSafeResult);
+    sendDiagnostics(
+      filterLintResult(
+        result.diagnostics,
+        dbSchema?.databaseNames?.length ? false : true,
+        document,
+      ),
+    );
   } catch (err) {
     if (!(err instanceof workerpool.Promise.CancellationError)) {
       console.error(err);
     }
   }
 }
 
+function filterLintResult(
+  diagnostics: SyntaxDiagnostic[],
+  dontWarnOnParams: boolean,
+  document: TextDocument,
+) {
+  return dontWarnOnParams
+    ? clampUnsafePositions(diagnostics.filter(isNotParamError), document)
+    : clampUnsafePositions(diagnostics, document);
+}
+
 export const lintDocument: typeof rawLintDocument = debounce(
   rawLintDocument,
   600,

packages/language-support/src/index.ts

@@ -27,6 +27,7 @@ export type { ParsedCypherToken } from './syntaxHighlighting/syntaxHighlightingH
 export {
   lintCypherQuery,
   clampUnsafePositions,
+  isNotParamError,
 } from './syntaxValidation/syntaxValidation.js';
 export type { SyntaxDiagnostic } from './syntaxValidation/syntaxValidation.js';
 export { testData } from './tests/testData.js';

packages/language-support/src/syntaxValidation/syntaxValidation.ts

@@ -87,6 +87,17 @@ function detectNonDeclaredLabel(
   return undefined;
 }
 
+type GenericDiagnostic = { message: string };
+
+export function isNotParamError<T extends GenericDiagnostic>(
+  diagnostic: T,
+): boolean {
+  return (
+    !diagnostic.message.startsWith('Parameter ') ||
+    !diagnostic.message.endsWith(' is not defined.')
+  );
+}
+
 export function clampUnsafePositions(
   diagnostics: SyntaxDiagnostic[],
   document: TextDocument,
@@ -802,6 +813,8 @@ function warningOnDeprecatedFunction(
   return warnings;
 }
 
+export const paramMsgStart = 'Parameter ';
+
 function errorOnUndeclaredParameters(
   parsingResult: ParsedStatement,
   dbSchema: DbSchema,

packages/language-support/src/tests/misc.test.ts

@@ -1,9 +1,12 @@
 import { TextDocument } from 'vscode-languageserver-textdocument';
 import {
   clampUnsafePositions,
+  isNotParamError,
   SyntaxDiagnostic,
 } from '../syntaxValidation/syntaxValidation.js';
 import { DiagnosticSeverity, Position } from 'vscode-languageserver-types';
+import { getDiagnosticsForQuery } from './syntaxValidation/helpers.js';
+import { testData } from './testData.js';
 
 describe('Clean positions', () => {
   test('Cleaning positions should mark the entire document when a position is negative.', () => {
@@ -47,6 +50,24 @@ describe('Clean positions', () => {
   });
 });
 
+test('Can filter out missing parameter warnings when disconnected using isNotParamError', () => {
+  const query =
+    'MATCH (n: Person) WHERE n.name = $`missing param` and n.age = $`some param` RETURN n';
+
+  expect(
+    getDiagnosticsForQuery({
+      query,
+      dbSchema: {
+        ...testData.mockSchema,
+        parameters: {
+          'some param': 21,
+        },
+        databaseNames: [],
+      },
+    }).filter(isNotParamError),
+  ).toEqual([]);
+});
+
 function testPositionCoversDoc(
   text: string,
   endLine: number,

packages/react-codemirror/src/lang-cypher/syntaxValidation.ts

@@ -4,6 +4,7 @@ import { DiagnosticSeverity, DiagnosticTag } from 'vscode-languageserver-types';
 import workerpool from 'workerpool';
 import type { CypherConfig } from './langCypher';
 import type { LintWorker } from '@neo4j-cypher/lint-worker';
+import { isNotParamError } from '@neo4j-cypher/language-support';
 
 const WorkerURL = new URL('./lintWorker.mjs', import.meta.url).pathname;
 
@@ -44,8 +45,9 @@ export const cypherLinter: (config: CypherConfig) => Extension = (config) =>
 
       const a: Diagnostic[] = result.diagnostics.map((diagnostic) => {
         return {
-          from: diagnostic.offsets.start,
-          to: diagnostic.offsets.end,
+          from: diagnostic.offsets.start >= 0 ? diagnostic.offsets.start : 0,
+          to:
+            diagnostic.offsets.end >= 0 ? diagnostic.offsets.end : query.length,
           severity:
             diagnostic.severity === DiagnosticSeverity.Error
               ? 'error'
@@ -57,6 +59,9 @@ export const cypherLinter: (config: CypherConfig) => Extension = (config) =>
             : {}),
         };
       });
+      if (!config.schema?.databaseNames?.length) {
+        return a.filter(isNotParamError);
+      }
       return a;
     } catch (err) {
       if (!String(err).includes('Worker terminated')) {

packages/vscode-extension/tests/helpers.ts

@@ -44,6 +44,12 @@ export async function eventually(
   timeoutMs = 15000,
   backoffMs = 100,
 ) {
+  // Cap the backoff so the retry interval stays small. Without a cap the
+  // exponential growth means we both poll very rarely near the end (a correct
+  // state can appear and not be noticed for tens of seconds) and overshoot
+  // `timeoutMs` in wall-clock time by ~2x, so mocha's own timeout fires first
+  // and hides the real assertion error.
+  const maxBackoffMs = 5000;
   let totalWait = 0;
   let wait = backoffMs;
   let succeeded = false;
@@ -53,16 +59,15 @@ export async function eventually(
       await assertion();
       succeeded = true;
     } catch (e) {
-      totalWait += wait;
       if (totalWait > timeoutMs) {
         throw new Error(
           // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
           `Timeout of ${timeoutMs} exceeded for test with last error: ${e}`,
         );
-      } else {
-        wait *= 2;
-        await sleep(wait);
       }
+      await sleep(wait);
+      totalWait += wait;
+      wait = Math.min(wait * 2, maxBackoffMs);
     }
   }
 }

packages/vscode-extension/tests/specs/api/lintSwitching.spec.ts

@@ -29,6 +29,21 @@ suite('Lint switching spec', () => {
   let showErrorMessageSpy: sinon.SinonSpy;
 
   before(async () => {
+    textDocument = await newUntitledFileWithContent(`MATCH (n) RETURN m`);
+    await saveDefaultConnection();
+    await testSyntaxValidation({
+      docUri: textDocument.uri,
+      expected: [
+        new vscode.Diagnostic(
+          new vscode.Range(
+            new vscode.Position(0, 17),
+            new vscode.Position(0, 18),
+          ),
+          'Variable `m` not defined',
+          vscode.DiagnosticSeverity.Error,
+        ),
+      ],
+    });
     textDocument = await newUntitledFileWithContent(`
       UNWIND range(1, 100) AS i
       CALL (i) {
@@ -50,7 +65,6 @@ suite('Lint switching spec', () => {
       'switchWorkerOnLanguageServer',
     );
     sendNotificationSpy = sandbox.spy(mockLanguageClient, 'sendNotification');
-    await saveDefaultConnection();
     sandbox.resetHistory();
   });
 
@@ -81,7 +95,7 @@ suite('Lint switching spec', () => {
     }
   }
 
-  test('Switching the linter to an old one should show different errors', async () => {
+  test('Switching the linter to an old one should show different errors', async function () {
     const linterVersion = '5.26';
     const stub = sandbox.stub(
       window,
@@ -178,7 +192,7 @@ suite('Lint switching spec', () => {
     checkLinterUpdatedInLanguageServer('Default');
   });
 
-  test('Switching the linter back to a new one should show different errors', async () => {
+  test('Switching the linter back to a new one should show different errors', async function () {
     const linterVersion = '2025.06';
     const stub = sandbox.stub(
       window,

packages/vscode-extension/tests/specs/api/syntaxValidation.spec.ts

@@ -20,11 +20,13 @@ import {
 type InclusionTestArgs = {
   docUri: vscode.Uri;
   expected: vscode.Diagnostic[];
+  timeoutMs?: number;
 };
 
 export async function testSyntaxValidation({
   docUri,
   expected,
+  timeoutMs,
 }: InclusionTestArgs) {
   await eventually(
     () =>
@@ -66,6 +68,7 @@ export async function testSyntaxValidation({
           reject(e);
         }
       }),
+    timeoutMs,
   );
 }
 
@@ -74,7 +77,8 @@ suite('Syntax validation spec', () => {
     await toggleLinting(true);
   });
 
-  test('Suggests replacements for deprecated functions/procedures', async () => {
+  test('Suggests replacements for deprecated functions/procedures', async function () {
+    this.timeout(60000);
     const textFile = 'deprecated-by.cypher';
     const docUri = getDocumentUri(textFile);
 
@@ -100,10 +104,12 @@ suite('Syntax validation spec', () => {
           vscode.DiagnosticSeverity.Warning,
         ),
       ],
+      timeoutMs: 40000,
     });
   });
 
-  test('Relints when database connected / disconnected', async () => {
+  test('Relints when database connected / disconnected', async function () {
+    this.timeout(60000);
     const textFile = 'deprecated-by.cypher';
     const docUri = getDocumentUri(textFile);
 
@@ -125,16 +131,19 @@ suite('Syntax validation spec', () => {
     await testSyntaxValidation({
       docUri,
       expected: deprecationErrors,
+      timeoutMs: 40000,
     });
     await disconnectDefault();
     await testSyntaxValidation({
       docUri,
       expected: [],
+      timeoutMs: 40000,
     });
     await connectDefault();
     await testSyntaxValidation({
       docUri,
       expected: deprecationErrors,
+      timeoutMs: 40000,
     });
   });
 
@@ -342,7 +351,8 @@ suite('Syntax validation spec', () => {
     });
   });
 
-  test('Linting can be disabled with the config option', async () => {
+  test('Linting can be disabled with the config option', async function () {
+    this.timeout(60000);
     const textFile = 'deprecated-by.cypher';
     const docUri = getDocumentUri(textFile);
 
@@ -368,12 +378,14 @@ suite('Syntax validation spec', () => {
           vscode.DiagnosticSeverity.Warning,
         ),
       ],
+      timeoutMs: 40000,
     });
 
     await toggleLinting(false);
     await testSyntaxValidation({
       docUri,
       expected: [],
+      timeoutMs: 40000,
     });
   });
 });

packages/vscode-extension/tests/specs/api/versionSpecificLinting.spec.ts

@@ -32,7 +32,7 @@ suite('Neo4j version specific linting spec', () => {
     await connectDefault({ version: 'neo4j 2025' });
   });
 
-  async function testNeo4jSpecificLinting() {
+  async function testNeo4jSpecificLinting(timeoutMs?: number) {
     const textFile = 'cypher-versioned.cypher';
     const docUri = getDocumentUri(textFile);
     await openDocument(docUri);
@@ -49,6 +49,7 @@ suite('Neo4j version specific linting spec', () => {
           vscode.DiagnosticSeverity.Error,
         ),
       ],
+      timeoutMs,
     });
 
     await connectDefault({ version: 'neo4j 5' });
@@ -64,15 +65,17 @@ suite('Neo4j version specific linting spec', () => {
           vscode.DiagnosticSeverity.Error,
         ),
       ],
+      timeoutMs,
     });
 
     await connectDefault({ version: 'neo4j 2025' });
   }
 
-  test('Linting depends on the specific neo4j version and works when having to download new linters', async () => {
+  test('Linting depends on the specific neo4j version and works when having to download new linters', async function () {
+    this.timeout(60000);
     const lintersFolder = getExtensionStoragePath();
     rmSync(lintersFolder, { force: true, recursive: true });
-    await testNeo4jSpecificLinting();
+    await testNeo4jSpecificLinting(40000);
   });
 
   test('Linting depends on the specific neo4j version and works when linters are already present', async () => {