@neo4j-cypher/language-server 2.0.0-next.39 → 2.0.0-next.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-cypher/language-server",
-  "version": "2.0.0-next.39",
+  "version": "2.0.0-next.40",
   "description": "Cypher Language Server",
   "keywords": [
     "cypher",
@@ -34,9 +34,9 @@
     "vscode-languageserver": "^8.1.0",
     "vscode-languageserver-textdocument": "^1.0.8",
     "workerpool": "^9.3.3",
-    "@neo4j-cypher/language-support": "2.0.0-next.38",
-    "@neo4j-cypher/query-tools": "2.0.0-next.38",
-    "@neo4j-cypher/lint-worker": "1.10.1-next.15"
+    "@neo4j-cypher/lint-worker": "1.10.1-next.16",
+    "@neo4j-cypher/language-support": "2.0.0-next.39",
+    "@neo4j-cypher/query-tools": "2.0.0-next.39"
   },
   "devDependencies": {
     "@types/lodash.debounce": "^4.0.9",
@@ -50,6 +50,7 @@
     "copy-lint-worker": "copyfiles -u 4 ../lint-worker/dist/cjs/lintWorker.cjs dist/",
     "bundle": "esbuild ./src/server.ts --bundle --format=cjs --platform=node --outfile=dist/cypher-language-server.js --minify --conditions=require",
     "dev": "tsc --watch",
+    "test": "vitest run",
     "make-executable": "cd dist && echo '#!/usr/bin/env node' > cypher-language-server && cat cypher-language-server.js >> cypher-language-server",
     "clean": "rm -rf dist tsconfig*.tsbuildinfo"
   }

package/src/descriptionToMarkdown.ts

@@ -0,0 +1,55 @@
+/**
+ * Descriptions in hover info are rendered as markdown in VS Code, which eats
+ * the wildcard '*' usages some of them have, as in dbms.queryJmx' "(e.g.
+ * '*:*,name=*neo4j*' for all metrics)", so we escape those. Not the asterisks a
+ * description means as markup though - in a code span, or as a bullet - where
+ * the backslash would show up instead. Backslashes are escaped along with them.
+ *
+ * Some descriptions are map-style objects (often configs) rather than prose.
+ * Markdown would put those on one line, so we tag them as 'text' code blocks
+ * and let their own layout through.
+ */
+
+const bulletMarker = '* ';
+
+/* A code span, or the prose up to the next backtick. Pairing left to right, as
+   markdown does, leaves the stray backtick a few descriptions have
+   (apoc.nodes.rels', apoc.path.expandConfig') as prose. */
+const codeSpanOrProse = /(`[^`]*`)|([^`]+|`)/g;
+
+export function escapeDescriptionForMarkdown(description: string): string {
+  // Line by line, so that an unclosed backtick cannot reach the lines below
+  return description.split('\n').map(escapeLine).join('\n');
+}
+
+function escapeLine(line: string): string {
+  const bullet = line.startsWith(bulletMarker) ? bulletMarker : '';
+
+  return (
+    bullet +
+    line.slice(bullet.length).replace(
+      codeSpanOrProse,
+      /* Escaping inside a code span would show the backslash, and descriptions
+         put wildcards there too, e.g. 'use `*:*` to find all JMX beans'. */
+      (_matched, codeSpan: string | undefined, prose: string) =>
+        codeSpan ?? prose.replace(/[\\*]/g, '\\$&'),
+    )
+  );
+}
+
+/* For example a map-style description, laid out over several lines */
+function hasInnerNewlines(description: string): boolean {
+  const lines = description.trimEnd().split('\n');
+  return lines.length > 1;
+}
+
+export function formatLineForMarkdown(
+  name: string,
+  description: string,
+): string[] {
+  const bullet = `- \`${name}\` -`;
+
+  return hasInnerNewlines(description)
+    ? [bullet, '```text', description.trimEnd(), '```']
+    : [`${bullet} ${escapeLine(description)}`];
+}

package/src/hoverInfo.ts

@@ -1,7 +1,9 @@
 import type { Hover, HoverParams, TextDocuments } from 'vscode-languageserver';
+import { MarkupKind } from 'vscode-languageserver';
 import type { TextDocument } from 'vscode-languageserver-textdocument';
 import { languageService } from './server.js';
 import type { Neo4jSchemaPoller } from '@neo4j-cypher/query-tools';
+import { hoverInfoToMarkdown } from './hoverMarkdown.js';
 
 export function doHoverInfo(
   documents: TextDocuments<TextDocument>,
@@ -16,5 +18,12 @@ export function doHoverInfo(
     caretPosition: offset,
     dbSchema: neo4jSchemaPoller.metadata?.dbSchema ?? {},
   });
-  return hoverInfo ? hoverInfo : null;
+  if (!hoverInfo) return null;
+
+  return {
+    contents: {
+      kind: MarkupKind.Markdown,
+      value: hoverInfoToMarkdown(hoverInfo),
+    },
+  };
 }

package/src/hoverMarkdown.ts

@@ -0,0 +1,56 @@
+import type {
+  HoverDescription,
+  HoverInfo,
+} from '@neo4j-cypher/language-support';
+import {
+  escapeDescriptionForMarkdown,
+  formatLineForMarkdown,
+} from './descriptionToMarkdown.js';
+
+function cypherCodeBlock(fragment: string): string[] {
+  return ['```cypher', fragment, '```'];
+}
+
+export function hoverInfoToMarkdown(info: HoverInfo): string {
+  if (info.kind === 'variable') {
+    const typeLine = ['`', `${info.variable}: ${info.types.join(', ')}`, '`'];
+    return (
+      info.labelExpression === undefined
+        ? typeLine
+        : [...typeLine, '', ...cypherCodeBlock(info.labelExpression)]
+    ).join('\n');
+  }
+
+  return [
+    ...cypherCodeBlock(info.signature),
+    `${info.isDeprecated ? '(_deprecated_) ' : ''}${escapeDescriptionForMarkdown(
+      info.description,
+    )}`,
+    '',
+    ...descriptionsToMarkdown('**Parameters**', info.parameters),
+    '',
+    ...(info.kind === 'function'
+      ? functionReturn(info.returnType)
+      : descriptionsToMarkdown('**Returns**', info.returnValues)),
+  ].join('\n');
+}
+
+function descriptionsToMarkdown(
+  heading: string,
+  descriptions: HoverDescription[],
+): string[] {
+  if (descriptions.length === 0) {
+    return [];
+  }
+
+  return [
+    heading,
+    ...descriptions.flatMap(({ name, description }) =>
+      formatLineForMarkdown(name, description),
+    ),
+  ];
+}
+
+function functionReturn(returnType: string): string[] {
+  return returnType ? [`**Returns:** \`${returnType}\``] : [];
+}

package/src/tests/descriptionToMarkdown.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from 'vitest';
+import {
+  formatLineForMarkdown,
+  escapeDescriptionForMarkdown,
+} from '../descriptionToMarkdown.js';
+
+/* Uses descriptions from real procedures and
+   functions named in the test titles */
+
+describe('escapes the wildcards a description writes as prose', () => {
+  test('dbms.queryJmxs query parameter', () => {
+    expect(
+      escapeDescriptionForMarkdown(
+        "A query for MBeans on this MBeanServer (e.g. '*:*,name=*neo4j*' for all metrics in neo4j database).",
+      ),
+    ).toBe(
+      "A query for MBeans on this MBeanServer (e.g. '\\*:\\*,name=\\*neo4j\\*' for all metrics in neo4j database).",
+    );
+  });
+
+  test('apoc.math.sigmoidPrime description', () => {
+    expect(
+      escapeDescriptionForMarkdown(
+        'Returns the sigmoid prime [ sigmoid(val) * (1 - sigmoid(val)) ] of the given value.',
+      ),
+    ).toBe(
+      'Returns the sigmoid prime [ sigmoid(val) \\* (1 - sigmoid(val)) ] of the given value.',
+    );
+  });
+
+  test('apoc.algo.aStar description', () => {
+    expect(escapeDescriptionForMarkdown('Runs the A* search algorithm.')).toBe(
+      'Runs the A\\* search algorithm.',
+    );
+  });
+});
+
+describe('leaves the wildcards inside a code span alone', () => {
+  test('dbms.queryJmx description', () => {
+    const description =
+      'Query JMX management data by domain and name. For instance, use `*:*` to find all JMX beans.';
+
+    expect(escapeDescriptionForMarkdown(description)).toBe(description);
+  });
+
+  test('gds.graph.nodeProperties.streams nodeLabels parameter', () => {
+    const listed =
+      "The node labels to aggregate over. Use `['*']` to indicate all.";
+
+    expect(escapeDescriptionForMarkdown(listed)).toBe(listed);
+  });
+});
+
+describe('escaping descriptions', () => {
+  test('escapes the backslashes, so that the escaping can be undone', () => {
+    expect(escapeDescriptionForMarkdown('a \\ b')).toBe('a \\\\ b');
+    expect(escapeDescriptionForMarkdown('already \\* escaped')).toBe(
+      'already \\\\\\* escaped',
+    );
+  });
+
+  test('leaves the underscores of a description alone - apoc.json.path pathOptions parameter', () => {
+    const values =
+      "JSON path options: ('ALWAYS_RETURN_LIST', 'DEFAULT_PATH_LEAF_TO_NULL').";
+
+    expect(escapeDescriptionForMarkdown(values)).toBe(values);
+  });
+
+  test('leaves the underscores of a description alone - db.index.fulltext.queryNodes', () => {
+    const italics = 'Valid _key: value_ pairs for the `options` map are:';
+
+    expect(escapeDescriptionForMarkdown(italics)).toBe(italics);
+  });
+
+  test('leaves a backtick that is never closed alone - apoc.node.relationships.exist relTypes parameter', () => {
+    expect(
+      escapeDescriptionForMarkdown('syntax; `[<]TYPE[>]|.... with a * in it'),
+    ).toBe('syntax; `[<]TYPE[>]|.... with a \\* in it');
+  });
+
+  test('leaves a backtick that is never closed alone - apoc.path.expandConfig startNode parameter', () => {
+    const description =
+      'The node to start the algorithm from. `startNode` can be of type `STRING` (elementId()), `INTEGER` (id()), `NODE`, or `LIST<STRING | INTEGER | NODE>.';
+
+    expect(escapeDescriptionForMarkdown(description)).toBe(description);
+  });
+
+  test('pairs the backticks within a line, not across the description', () => {
+    expect(escapeDescriptionForMarkdown('a ` b\nc * d')).toBe('a ` b\nc \\* d');
+  });
+
+  test('keeps the newlines a description brings, including a trailing one', () => {
+    expect(escapeDescriptionForMarkdown('first\n\nsecond\n')).toBe(
+      'first\n\nsecond\n',
+    );
+  });
+
+  test('handles empty description', () => {
+    expect(escapeDescriptionForMarkdown('')).toBe('');
+  });
+});
+
+describe('description bullets', () => {
+  test('keeps the bullet markers of a description that writes a list - dbms.cluster.switchDiscoveryServiceVersion', () => {
+    const description = [
+      'Possible values are:',
+      '',
+      '* `V1_ONLY` -- it runs only discovery service v1.',
+      '* `V2_ONLY` -- it runs only discovery service v2.',
+    ].join('\n');
+
+    expect(escapeDescriptionForMarkdown(description)).toBe(description);
+  });
+
+  test('escapes an asterisk that only looks like a bullet marker', () => {
+    // An indented bullet is not one in react-codemirror's renderer
+    expect(escapeDescriptionForMarkdown('  * indented')).toBe('  \\* indented');
+    // And neither is a bare asterisk without the space
+    expect(escapeDescriptionForMarkdown('*emphasised*')).toBe(
+      '\\*emphasised\\*',
+    );
+    // The marker is kept, the wildcard on the same line is not
+    expect(escapeDescriptionForMarkdown("* 'skip' -- skips *:*")).toBe(
+      "* 'skip' -- skips \\*:\\*",
+    );
+  });
+
+  test('writes a prose description inline', () => {
+    expect(
+      formatLineForMarkdown('query', "A query for MBeans (e.g. '*:*')."),
+    ).toEqual(["- `query` - A query for MBeans (e.g. '\\*:\\*')."]);
+  });
+
+  test('accepts a description that is several lines of prose as a textblock', () => {
+    expect(
+      formatLineForMarkdown('sort', 'Sorts the list.\nTo sort ascending.'),
+    ).toEqual([
+      '- `sort` -',
+      '```text',
+      `Sorts the list.
+To sort ascending.`,
+      '```',
+    ]);
+  });
+
+  test('writes a description that carries its own layout as a code block - apoc.export.csv.all config parameter', () => {
+    const description =
+      '{\n    delimiter = "," :: STRING,\n    skipLines = 1 :: INTEGER\n}\n';
+
+    expect(formatLineForMarkdown('config', description)).toEqual([
+      '- `config` -',
+      '```text',
+      '{\n    delimiter = "," :: STRING,\n    skipLines = 1 :: INTEGER\n}',
+      '```',
+    ]);
+  });
+});

package/src/tests/hoverMarkdown.test.ts

@@ -0,0 +1,232 @@
+import {
+  CypherLanguageService,
+  testData,
+} from '@neo4j-cypher/language-support';
+import { describe, expect, test } from 'vitest';
+import { hoverInfoToMarkdown } from '../hoverMarkdown.js';
+
+const dbSchema = testData.mockSchema;
+const languageService = new CypherLanguageService();
+
+function hoverMarkdown(query: string, hovered: string): string {
+  const hoverInfo = languageService.hoverInfo(query, {
+    caretPosition: query.indexOf(hovered) + 1,
+    dbSchema,
+  });
+  return hoverInfoToMarkdown(hoverInfo);
+}
+
+function variableHoverMarkdown(query: string, caretPosition: number): string {
+  const { symbolTables } = languageService.lint(query, dbSchema);
+  languageService.setSymbolsInfo({ query, symbolTables });
+  return hoverInfoToMarkdown(
+    languageService.hoverInfo(query, { caretPosition, dbSchema }),
+  );
+}
+
+describe('Function hover markdown', () => {
+  test('writes the signature, description, parameters and return type', () => {
+    expect(hoverMarkdown('CYPHER 25 RETURN abs(1,2)', 'abs')).toBe(
+      `\`\`\`cypher
+abs(input :: INTEGER | FLOAT) :: INTEGER | FLOAT
+\`\`\`
+Returns the absolute value of an \`INTEGER\` or \`FLOAT\`.
+
+**Parameters**
+- \`input\` - A numeric value from which the absolute number will be returned.
+
+**Returns:** \`INTEGER | FLOAT\``,
+    );
+  });
+
+  test('marks deprecated functions as deprecated', () => {
+    expect(
+      hoverMarkdown('CYPHER 5 RETURN apoc.create.uuid()', 'apoc.create.uuid'),
+    ).toBe(
+      `\`\`\`cypher
+apoc.create.uuid() :: STRING
+\`\`\`
+(_deprecated_) Returns a UUID.
+
+
+**Returns:** \`STRING\``,
+    );
+  });
+
+  test('escapes the asterisk a description writes as prose, so its not interpreted as emphasis in markdown', () => {
+    expect(
+      hoverMarkdown(
+        'RETURN apoc.math.sigmoidPrime(1.0)',
+        'apoc.math.sigmoidPrime',
+      ),
+    ).toBe(
+      `\`\`\`cypher
+apoc.math.sigmoidPrime(value :: FLOAT) :: FLOAT
+\`\`\`
+Returns the sigmoid prime [ sigmoid(val) \\* (1 - sigmoid(val)) ] of the given value.
+
+**Parameters**
+- \`value\` - An angle in radians.
+
+**Returns:** \`FLOAT\``,
+    );
+  });
+});
+
+describe('Procedure hover markdown', () => {
+  test('writes the return values of a procedure without parameters', () => {
+    expect(hoverMarkdown('CALL db.labels()', 'db.labels')).toBe(
+      `\`\`\`cypher
+db.labels() :: (label :: STRING)
+\`\`\`
+List all labels attached to nodes within a database according to the user's access rights. The procedure returns empty results if the user is not authorized to view those labels.
+
+
+**Returns**
+- \`label\` - A label within the database.`,
+    );
+  });
+
+  test('writes the parameters of a procedure without return values', () => {
+    expect(
+      hoverMarkdown('CALL db.awaitIndex("MyIndex", 300)', 'db.awaitIndex'),
+    ).toBe(
+      `\`\`\`cypher
+db.awaitIndex(indexName :: STRING, timeOutSeconds = 300 :: INTEGER)
+\`\`\`
+Wait for an index to come online (for example: CALL db.awaitIndex("MyIndex", 300)).
+
+**Parameters**
+- \`indexName\` - The name of the awaited index.
+- \`timeOutSeconds\` - The maximum time to wait in seconds.
+`,
+    );
+  });
+
+  test('marks deprecated procedures as deprecated', () => {
+    expect(
+      hoverMarkdown(
+        'CYPHER 5 CALL db.create.setVectorProperty(n, "prop", [1.0])',
+        'db.create.setVectorProperty',
+      ),
+    ).toBe(
+      `\`\`\`cypher
+db.create.setVectorProperty(node :: NODE, key :: STRING, vector :: ANY) :: (node :: NODE)
+\`\`\`
+(_deprecated_) Set a vector property on a given node in a more space efficient representation than Cypher's SET.
+
+**Parameters**
+- \`node\` - The node on which the new property will be stored.
+- \`key\` - The name of the new property.
+- \`vector\` - The object containing the embedding.
+
+**Returns**
+- \`node\` - The node on which the vector property was set.`,
+    );
+  });
+
+  test('escapes the wildcards a description writes, but not the ones in its code spans', () => {
+    expect(hoverMarkdown('CALL dbms.queryJmx("*:*")', 'dbms.queryJmx')).toBe(
+      `\`\`\`cypher
+dbms.queryJmx(query :: STRING) :: (name :: STRING, description :: STRING, attributes :: MAP)
+\`\`\`
+Query JMX management data by domain and name. For instance, use \`*:*\` to find all JMX beans.
+
+**Parameters**
+- \`query\` - A query for MBeans on this MBeanServer (e.g. '\\*:\\*,name=\\*neo4j\\*' for all metrics in neo4j database).
+
+**Returns**
+- \`name\` - The name of the metric.
+- \`description\` - The description of the metric.
+- \`attributes\` - A collection with the attributes (values) of that metric.`,
+    );
+  });
+
+  test('keeps the bullet list and the italics of a description', () => {
+    expect(
+      hoverMarkdown(
+        'CALL db.index.fulltext.queryNodes("index", "query")',
+        'db.index.fulltext.queryNodes',
+      ),
+    ).toBe(
+      `\`\`\`cypher
+db.index.fulltext.queryNodes(indexName :: STRING, queryString :: STRING, options = {} :: MAP) :: (node :: NODE, score :: FLOAT)
+\`\`\`
+Query the given full-text index. Returns the matching nodes and their Lucene query score, ordered by score.
+Valid _key: value_ pairs for the \`options\` map are:
+
+* 'skip' -- to skip the top N results.
+* 'limit' -- to limit the number of results returned.
+* 'analyzer' -- to use the specified analyzer as a search analyzer for this query.
+
+The \`options\` map and any of the keys are optional.
+An example of the \`options\` map: \`{skip: 30, limit: 10, analyzer: 'whitespace'}\`
+
+
+**Parameters**
+- \`indexName\` - The name of the full-text index.
+- \`queryString\` - The string to find approximate matches for.
+- \`options\` - {skip :: INTEGER, limit :: INTEGER, analyzer :: STRING}
+
+**Returns**
+- \`node\` - A node which contains a property similar to the query string.
+- \`score\` - The score measuring how similar the node property is to the query string.`,
+    );
+  });
+
+  /* Some parameters are described with a map type rather than with prose.
+     Markdown would collapse the layout of those into one run-on line. */
+  test('writes a parameter that carries its own layout as a code block', () => {
+    expect(
+      hoverMarkdown(
+        'CALL apoc.export.csv.all("file.csv", {})',
+        'apoc.export.csv.all',
+      ),
+    ).toContain(
+      `**Parameters**
+- \`file\` - The name of the file to which the data will be exported.
+- \`config\` -
+\`\`\`text
+{
+        stream = false :: BOOLEAN,
+        batchSize = 20000 :: INTEGER,
+        bulkImport = false :: BOOLEAN,
+        timeoutSeconds = 100 :: INTEGER,
+        compression = 'None' :: STRING,
+        charset = 'UTF_8' :: STRING,
+        quotes = 'always' :: ['always', 'none', 'ifNeeded'],
+        differentiateNulls = false :: BOOLEAN,
+        sampling = false :: BOOLEAN,
+        samplingConfig :: MAP
+}
+\`\`\``,
+    );
+  });
+});
+
+describe('Variable hover markdown', () => {
+  test('writes the type of a variable without labels', () => {
+    expect(variableHoverMarkdown('MATCH (n) RETURN n', 'MATCH ('.length)).toBe(
+      `\`
+n: Node
+\``,
+    );
+  });
+
+  test('writes the label expression of a labeled variable', () => {
+    expect(
+      variableHoverMarkdown(
+        'MATCH (n:Person|Pet) WHERE n:Neighbour RETURN ',
+        'MATCH (n:Person|Pet) WHERE '.length,
+      ),
+    ).toBe(
+      `\`
+n: Node
+\`
+
+\`\`\`cypher
+((Person | Pet) & Neighbour)
+\`\`\``,
+    );
+  });
+});