links-notation 0.17.0 → 0.18.0

package/README.md

@@ -279,11 +279,44 @@ Container for grouping related links.
 - `constructor(links)` - Create a new group
 - `format()` - Format the group as a string
 
+#### `ParseError`
+
+Thrown by `parse(input)` when the document does not parse. The message says
+where the document stopped making sense and quotes the offending line:
+
+```js
+import { Parser, ParseError } from 'links-notation';
+
+try {
+  new Parser().parse('# ok line\n# break: two\nci_gate x\n');
+} catch (error) {
+  console.error(error.message);
+  if (error instanceof ParseError) {
+    console.error(`${error.line}:${error.column} (offset ${error.offset})`);
+  }
+}
+```
+
+```text
+Syntax error at line 2, column 8: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
+2 | # break: two
+  |        ^
+```
+
+- `offset` - Offset of the offending position from the start of the document
+- `line`, `column` - Where the document stopped parsing, counted from 1
+- `found` - The character found instead, or `null` at the end of the document
+- `lineText` - The offending line, as written
+- `snippet` - The offending line with a caret under the offending column
+- `location` - The position as the generated parser reports it
+- `cause` - The error the generated parser threw
+
 ## Project Structure
 
 - `src/grammar.pegjs` - Peggy.js grammar definition
 - `src/Link.js` - Link data structure
 - `src/LinksGroup.js` - Links group container
+- `src/ParseError.js` - Parse error with the position of the defect
 - `src/Parser.js` - Parser wrapper
 - `src/index.js` - Main entry point
 - `tests/` - Test files

package/README.ru.md

@@ -198,11 +198,44 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 - `constructor(links)` - Создание новой группы
 - `format()` - Форматирование группы в строку
 
+#### `ParseError`
+
+Выбрасывается методом `parse(input)`, когда документ не разбирается. Сообщение
+говорит, где документ перестал быть понятным, и цитирует сломанную строку:
+
+```js
+import { Parser, ParseError } from 'links-notation';
+
+try {
+  new Parser().parse('# ok line\n# break: two\nci_gate x\n');
+} catch (error) {
+  console.error(error.message);
+  if (error instanceof ParseError) {
+    console.error(`${error.line}:${error.column} (смещение ${error.offset})`);
+  }
+}
+```
+
+```text
+Syntax error at line 2, column 8: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
+2 | # break: two
+  |        ^
+```
+
+- `offset` - Смещение сломанной позиции от начала документа
+- `line`, `column` - Где документ перестал разбираться, счет с 1
+- `found` - Найденный символ или `null` в конце документа
+- `lineText` - Сломанная строка, как она написана
+- `snippet` - Сломанная строка с указателем под нужным столбцом
+- `location` - Позиция в том виде, в каком ее сообщает сгенерированный парсер
+- `cause` - Ошибка, которую выбросил сгенерированный парсер
+
 ## Структура проекта
 
 - `src/grammar.pegjs` - Определение грамматики Peggy.js
 - `src/Link.js` - Структура данных связи
 - `src/LinksGroup.js` - Контейнер групп связей
+- `src/ParseError.js` - Ошибка разбора с позицией дефекта
 - `src/Parser.js` - Обертка парсера
 - `src/index.js` - Главная точка входа
 - `tests/` - Файлы тестов

package/dist/index.js

@@ -269,6 +269,57 @@ class LinksGroup {
     return list.map((item) => `(${item.id || item})`).join(" ");
   }
 }
+// src/ParseError.js
+var QUOTED_LINE_WIDTH = 80;
+var ELLIPSIS = "...";
+
+class ParseError extends Error {
+  constructor(input, error) {
+    const start = error?.location?.start ?? { offset: 0, line: 1, column: 1 };
+    const lineText = lineAt(input, start.offset);
+    const summary = `line ${start.line}, column ${start.column}: ${error.message}`;
+    const snippet = quote(start.line, lineText, start.column);
+    super(`Syntax error at ${summary}
+${snippet}`);
+    this.name = "ParseError";
+    this.cause = error;
+    this.location = error.location;
+    this.offset = start.offset;
+    this.line = start.line;
+    this.column = start.column;
+    this.found = error.found ?? null;
+    this.lineText = lineText;
+    this.snippet = snippet;
+  }
+}
+function lineAt(input, offset) {
+  const at = Math.max(0, Math.min(offset, input.length));
+  const start = input.lastIndexOf(`
+`, at - 1) + 1;
+  const end = input.indexOf(`
+`, start);
+  const line = input.slice(start, end === -1 ? input.length : end);
+  return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+function quote(number, lineText, column) {
+  const [quoted, at] = windowAround(lineText, column);
+  const gutter = " ".repeat(String(number).length);
+  return `${number} | ${quoted}
+${gutter} | ${" ".repeat(at - 1)}^`;
+}
+function windowAround(lineText, column) {
+  if (lineText.length <= QUOTED_LINE_WIDTH) {
+    return [lineText, column];
+  }
+  const target = column - 1;
+  const lastStart = lineText.length - QUOTED_LINE_WIDTH;
+  const start = Math.min(Math.max(target - Math.floor(QUOTED_LINE_WIDTH / 2), 0), lastStart);
+  const end = start + QUOTED_LINE_WIDTH;
+  const quoted = (start > 0 ? ELLIPSIS : "") + lineText.slice(start, end) + (end < lineText.length ? ELLIPSIS : "");
+  const shift = start > 0 ? ELLIPSIS.length : 0;
+  return [quoted, target - start + shift + 1];
+}
+
 // src/parser-generated.js
 class peg$SyntaxError extends SyntaxError {
   constructor(message, expected, found, location) {
@@ -2024,9 +2075,11 @@ class Parser {
       const rawResult = peg$parse(input);
       return this.transformResult(rawResult);
     } catch (error) {
+      if (error && error.location) {
+        throw new ParseError(input, error);
+      }
       const parseError = new Error(`Parse error: ${error.message}`);
       parseError.cause = error;
-      parseError.location = error.location;
       throw parseError;
     }
   }
@@ -2163,6 +2216,7 @@ export {
   FormatOptions,
   Link,
   LinksGroup,
+  ParseError,
   Parser,
   formatLinks
 };

package/index.d.ts

@@ -144,11 +144,62 @@ export class Parser {
    * Parse Lino notation text into Link objects
    * @param input - The Lino notation text to parse
    * @returns Array of parsed Link objects
-   * @throws {Error} If parsing fails
+   * @throws {ParseError} If the text does not parse
    */
   parse(input: string): Link[];
 }
 
+/**
+ * The position a parse stopped at, as the generated parser reports it
+ */
+export interface ParseErrorLocation {
+  start: { offset: number; line: number; column: number };
+  end: { offset: number; line: number; column: number };
+}
+
+/**
+ * The error thrown when a document does not parse
+ *
+ * The message says where the document stopped making sense and quotes the
+ * offending line with a caret under it.
+ */
+export class ParseError extends Error {
+  /**
+   * Offset of the offending position from the start of the document
+   */
+  offset: number;
+
+  /**
+   * Line the offending position is on, counted from 1
+   */
+  line: number;
+
+  /**
+   * Column the offending position is at, counted from 1
+   */
+  column: number;
+
+  /**
+   * The character found instead, or null at the end of the document
+   */
+  found: string | null;
+
+  /**
+   * The offending line, as written, without its line ending
+   */
+  lineText: string;
+
+  /**
+   * The offending line with a caret under the offending column
+   */
+  snippet: string;
+
+  /**
+   * The position the generated parser reported
+   */
+  location: ParseErrorLocation;
+}
+
 /**
  * Options for formatting links
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "links-notation",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Links Notation parser for JavaScript",
   "main": "dist/index.js",
   "types": "index.d.ts",

package/src/ParseError.js

@@ -0,0 +1,104 @@
+/** The number of characters a quoted line is cut down to. */
+const QUOTED_LINE_WIDTH = 80;
+
+/** What a message writes in place of the part of a long line it left out. */
+const ELLIPSIS = '...';
+
+/**
+ * The error thrown when a document does not parse, carrying the position the
+ * parser stopped at.
+ *
+ * The generated parser reports that position, but only on the error object; the
+ * message it writes says what it expected without saying where. This error puts
+ * the line and the column in the message as well, and quotes the offending line
+ * with a caret under it, the way the Rust and C# ports do.
+ */
+export class ParseError extends Error {
+  /**
+   * @param {string} input - The document that failed to parse
+   * @param {Error} error - The error the generated parser threw
+   */
+  constructor(input, error) {
+    const start = error?.location?.start ?? { offset: 0, line: 1, column: 1 };
+    const lineText = lineAt(input, start.offset);
+    const summary = `line ${start.line}, column ${start.column}: ${error.message}`;
+    const snippet = quote(start.line, lineText, start.column);
+    super(`Syntax error at ${summary}\n${snippet}`);
+
+    this.name = 'ParseError';
+    /** @type {Error} The error the generated parser threw */
+    this.cause = error;
+    /** @type {{start: {offset: number, line: number, column: number}}} */
+    this.location = error.location;
+    /** @type {number} Offset of the offending position from the start of the document */
+    this.offset = start.offset;
+    /** @type {number} Line the offending position is on, counted from 1 */
+    this.line = start.line;
+    /** @type {number} Column the offending position is at, counted from 1 */
+    this.column = start.column;
+    /** @type {string|null} The character found instead, or null at the end of the document */
+    this.found = error.found ?? null;
+    /** @type {string} The offending line, as written, without its line ending */
+    this.lineText = lineText;
+    /** @type {string} The offending line with a caret under the offending column */
+    this.snippet = snippet;
+  }
+}
+
+/**
+ * The line the given offset falls on, without its line ending.
+ * @param {string} input - The document being parsed
+ * @param {number} offset - Offset of the offending position
+ * @returns {string} The offending line
+ */
+function lineAt(input, offset) {
+  const at = Math.max(0, Math.min(offset, input.length));
+  const start = input.lastIndexOf('\n', at - 1) + 1;
+  const end = input.indexOf('\n', start);
+  const line = input.slice(start, end === -1 ? input.length : end);
+  return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+
+/**
+ * The offending line with a caret under the offending column, quoted the way a
+ * compiler quotes source. A long line is shown as a window around the caret, so
+ * the message stays the same size whether the document has ten lines or fifteen
+ * hundred.
+ * @param {number} number - The line number, counted from 1
+ * @param {string} lineText - The offending line
+ * @param {number} column - The offending column, counted from 1
+ * @returns {string} The quoted line and the caret under it
+ */
+function quote(number, lineText, column) {
+  const [quoted, at] = windowAround(lineText, column);
+  const gutter = ' '.repeat(String(number).length);
+  return `${number} | ${quoted}\n${gutter} | ${' '.repeat(at - 1)}^`;
+}
+
+/**
+ * Cuts a line down to a window around the given column, and says which column
+ * the offending character sits at in that window. Both columns count from 1.
+ * @param {string} lineText - The offending line
+ * @param {number} column - The offending column, counted from 1
+ * @returns {[string, number]} The window and the column within it
+ */
+function windowAround(lineText, column) {
+  if (lineText.length <= QUOTED_LINE_WIDTH) {
+    return [lineText, column];
+  }
+
+  const target = column - 1;
+  const lastStart = lineText.length - QUOTED_LINE_WIDTH;
+  const start = Math.min(
+    Math.max(target - Math.floor(QUOTED_LINE_WIDTH / 2), 0),
+    lastStart
+  );
+  const end = start + QUOTED_LINE_WIDTH;
+
+  const quoted =
+    (start > 0 ? ELLIPSIS : '') +
+    lineText.slice(start, end) +
+    (end < lineText.length ? ELLIPSIS : '');
+  const shift = start > 0 ? ELLIPSIS.length : 0;
+  return [quoted, target - start + shift + 1];
+}

package/src/Parser.js

@@ -1,4 +1,5 @@
 import { Link } from './Link.js';
+import { ParseError } from './ParseError.js';
 import * as parserModule from './parser-generated.js';
 
 export class Parser {
@@ -35,10 +36,13 @@ export class Parser {
       const rawResult = parserModule.parse(input);
       return this.transformResult(rawResult);
     } catch (error) {
-      // Preserve original error information
+      // A syntax error knows where it stopped; anything else is passed on with
+      // the original error kept as the cause.
+      if (error && error.location) {
+        throw new ParseError(input, error);
+      }
       const parseError = new Error(`Parse error: ${error.message}`);
       parseError.cause = error;
-      parseError.location = error.location;
       throw parseError;
     }
   }

package/src/index.js

@@ -1,5 +1,6 @@
 export { Link, formatLinks } from './Link.js';
 export { LinksGroup } from './LinksGroup.js';
 export { Parser } from './Parser.js';
+export { ParseError } from './ParseError.js';
 export { FormatConfig } from './FormatConfig.js';
 export { FormatOptions } from './FormatOptions.js';

package/tests/ParseErrorPosition.test.js

@@ -0,0 +1,109 @@
+// A parse error has to say where the document stopped making sense.
+//
+// The positions asserted here are the ones the Rust and C# ports report for the
+// same input, so the implementations can be held to the same contract
+// (https://github.com/link-foundation/links-notation/issues/302).
+
+import { test, expect } from 'bun:test';
+import { Parser, ParseError } from '../src/index.js';
+
+const parser = new Parser();
+
+function syntaxError(document) {
+  try {
+    const links = parser.parse(document);
+    throw new Error(
+      `expected ${JSON.stringify(document)} not to parse, got ${links.length} links`
+    );
+  } catch (error) {
+    expect(error).toBeInstanceOf(ParseError);
+    return error;
+  }
+}
+
+test('reports the line and column of the defect', () => {
+  // The example from the issue: the defect is the colon on line 2, and the
+  // two lines after it are fine.
+  const error = syntaxError('# ok line\n# break: two\nci_gate x\n  stage rust');
+
+  expect(error.line).toBe(2);
+  expect(error.column).toBe(8);
+  expect(error.found).toBe(':');
+});
+
+test('offset agrees with the other implementations', () => {
+  // Rust and C# report offset 17, line 2, column 8 for this document.
+  const error = syntaxError('# ok line\n# break: two\n');
+
+  expect(error.offset).toBe(17);
+  expect(error.line).toBe(2);
+  expect(error.column).toBe(8);
+});
+
+test('reports the line a late defect is on', () => {
+  const error = syntaxError('a\nb\nc\nd\ne: f: g\nh\n');
+
+  expect(error.line).toBe(5);
+  expect(error.column).toBe(5);
+  expect(error.lineText).toBe('e: f: g');
+});
+
+test('reports the end of the document when a group is never closed', () => {
+  const error = syntaxError('a (b\n');
+
+  expect(error.offset).toBe(5);
+  expect(error.line).toBe(2);
+  expect(error.column).toBe(1);
+  expect(error.found).toBeNull();
+  expect(error.message).toContain('end of input');
+});
+
+test('reports an unmatched closing parenthesis', () => {
+  const error = syntaxError('a b)\n');
+
+  expect(error.offset).toBe(3);
+  expect(error.line).toBe(1);
+  expect(error.column).toBe(4);
+  expect(error.found).toBe(')');
+});
+
+test('message says where the document broke', () => {
+  const error = syntaxError('# ok line\n# break: two\n');
+
+  expect(error.message.startsWith('Syntax error at line 2, column 8:')).toBe(
+    true
+  );
+  expect(error.snippet).toBe('2 | # break: two\n  |        ^');
+});
+
+test('message quotes one line rather than the rest of the document', () => {
+  const document = `# ok line\n# break: two\n${'trailing line\n'.repeat(500)}`;
+
+  const error = syntaxError(document);
+
+  expect(error.message).toContain('line 2, column 8');
+  expect(error.message).not.toContain('trailing line');
+  expect(error.message.length).toBeLessThan(200);
+});
+
+test('message of a long line stays a message', () => {
+  const document = `${'a'.repeat(400)}: ${'b'.repeat(400)}: c`;
+
+  const error = syntaxError(document);
+
+  expect(error.line).toBe(1);
+  expect(error.column).toBe(803);
+  expect(error.message).toContain('...');
+  expect(error.message.length).toBeLessThan(300);
+});
+
+test('the location the parser used to report is still there', () => {
+  const error = syntaxError('a: b: c');
+
+  expect(error.location.start).toEqual({ offset: 4, line: 1, column: 5 });
+  expect(error.cause).toBeDefined();
+});
+
+test('a document that parses reports nothing', () => {
+  expect(parser.parse('a: b\n  c: d\n').length).toBe(2);
+});