links-notation 0.17.0 → 0.19.0

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,6 @@
 import { Link } from './Link.js';
+import { ParseError } from './ParseError.js';
+import { stripComments } from './comments.js';
 import * as parserModule from './parser-generated.js';
 
 export class Parser {
@@ -7,10 +9,12 @@ export class Parser {
    * @param {Object} options - Parser options
    * @param {number} options.maxInputSize - Maximum input size in bytes (default: 10MB)
    * @param {number} options.maxDepth - Maximum nesting depth (default: 1000)
+   * @param {boolean} options.comments - If false, read `#` as an ordinary character instead of the start of a comment (default: true)
    */
   constructor(options = {}) {
     this.maxInputSize = options.maxInputSize || 10 * 1024 * 1024; // 10MB default
     this.maxDepth = options.maxDepth || 1000;
+    this.comments = options.comments ?? true;
   }
 
   /**
@@ -31,14 +35,21 @@ export class Parser {
       );
     }
 
+    // Comments are blanked rather than removed, so a position reported for the
+    // prepared document is the same position in the document the caller wrote.
+    const prepared = this.comments ? stripComments(input) : input;
+
     try {
-      const rawResult = parserModule.parse(input);
+      const rawResult = parserModule.parse(prepared);
       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/comments.js

@@ -0,0 +1,164 @@
+/**
+ * Comments, and the rule that decides where one starts.
+ *
+ * `#` starts a comment when it opens a token: at the start of the document or
+ * after a space, a tab or a line break. A `#` written inside a token
+ * (`issue#1047`) or inside a delimited reference (`"# not a comment"`) is an
+ * ordinary character.
+ *
+ * {@link stripComments} replaces every character of every comment with a space
+ * rather than removing it, so every later character keeps the offset it had in
+ * the document the caller wrote, and a parse error still points at the position
+ * the reader can see.
+ */
+
+/** The character that starts a comment. */
+export const COMMENT = '#';
+
+/** The delimiters a reference can be written between. */
+const QUOTES = ['"', "'", '`'];
+
+/** What a delimited reference may start after. */
+const BEFORE_REFERENCE = [' ', '\t', '\n', '\r', '(', ':'];
+
+/** What a comment may start after. */
+const BEFORE_COMMENT = [' ', '\t', '\n', '\r'];
+
+/**
+ * The document with every comment blanked out.
+ * @param {string} document - The document to read
+ * @returns {string} The document, of the same length, without its comments
+ * @example
+ * stripComments('a: b # why\n'); // 'a: b      \n'
+ * stripComments('"# kept"\n'); // '"# kept"\n'
+ * stripComments('issue#1047\n'); // 'issue#1047\n'
+ */
+export function stripComments(document) {
+  // Split into UTF-16 units, the units the positions here and the positions a
+  // parse error reports are both counted in.
+  let blanked = null;
+  let position = 0;
+
+  while (position < document.length) {
+    const character = document[position];
+
+    if (
+      QUOTES.includes(character) &&
+      follows(document, position, BEFORE_REFERENCE)
+    ) {
+      const end = quotedReferenceEnd(document, position);
+      position = end === null ? position + 1 : end;
+      continue;
+    }
+
+    if (character === COMMENT && follows(document, position, BEFORE_COMMENT)) {
+      blanked = blanked ?? document.split('');
+      while (
+        position < document.length &&
+        document[position] !== '\n' &&
+        document[position] !== '\r'
+      ) {
+        blanked[position] = ' ';
+        position++;
+      }
+      continue;
+    }
+
+    position++;
+  }
+
+  return blanked === null ? document : blanked.join('');
+}
+
+/**
+ * Whether the character before the given position is one the caller allows,
+ * the start of the document counting as allowed.
+ * @param {string} document - The document being read
+ * @param {number} position - Position of the character being judged
+ * @param {string[]} allowed - The characters that may stand before it
+ * @returns {boolean} True when the position opens a token
+ */
+function follows(document, position, allowed) {
+  return position === 0 || allowed.includes(document[position - 1]);
+}
+
+/**
+ * The position just past the delimited reference that starts at `start`, or
+ * `null` when nothing there opens one.
+ *
+ * This follows the same rules as the `parseQuotedStringAt` of the grammar: a
+ * run of N delimiters closes at the next run of exactly N, a run of 2N is that
+ * delimiter escaped, and an even run that encloses nothing substantive is the
+ * empty reference.
+ * @param {string} document - The document being read
+ * @param {number} start - Position of the opening delimiter
+ * @returns {number|null} The position just past the reference
+ */
+export function quotedReferenceEnd(document, start) {
+  const quote = document[start];
+  if (!QUOTES.includes(quote)) {
+    return null;
+  }
+
+  let position = start;
+  while (position < document.length && document[position] === quote) {
+    position++;
+  }
+  const count = position - start;
+  const isEvenRun = count % 2 === 0;
+  const emptyReference = isEvenRun ? start + count : null;
+
+  const closing = quote.repeat(count);
+  const escape = quote.repeat(count * 2);
+  let content = '';
+
+  while (position < document.length) {
+    if (document.startsWith(escape, position)) {
+      content += closing;
+      position += escape.length;
+      continue;
+    }
+
+    if (document.startsWith(closing, position)) {
+      const afterClosing = position + count;
+      if (afterClosing >= document.length || document[afterClosing] !== quote) {
+        if (isEvenRun && !isSubstantiveBody(content)) {
+          return emptyReference;
+        }
+        return afterClosing;
+      }
+    }
+
+    content += document[position];
+    position++;
+  }
+
+  return emptyReference;
+}
+
+/**
+ * Whether a body written between an even run of delimiters carries something a
+ * pair of delimiters enclosing nothing cannot.
+ * @param {string} content - The body between the delimiters
+ * @returns {boolean} True when the n-quote reading is the one to take
+ */
+function isSubstantiveBody(content) {
+  let depth = 0;
+  let hasVisible = false;
+
+  for (const character of content) {
+    if (character === '(') {
+      depth++;
+    } else if (character === ')') {
+      depth--;
+      if (depth < 0) {
+        return false;
+      }
+    }
+    if (!/\s/.test(character)) {
+      hasVisible = true;
+    }
+  }
+
+  return hasVisible && depth === 0;
+}

package/src/grammar.pegjs

@@ -264,7 +264,13 @@ PUSH_INDENTATION = spaces:" "* &{ return normalizeIndentation(spaces) > getCurre
 
 CHECK_INDENTATION = spaces:" "* &{ return checkIndentation(spaces); }
 
-eol = __ ([\r\n]+ / eof / nestedGroupEnd)
+eol = __ (lineBreaks / eof / nestedGroupEnd)
+
+// A line ends at the first line break, and the blank lines that follow it
+// belong to that ending: a line holding nothing but spaces or tabs separates
+// links exactly the way an empty line does. Blanking a comment leaves such a
+// line behind, so this is also what lets a comment stand on a line of its own.
+lineBreaks = [\r\n]+ ([ \t]+ [\r\n]+)*
 
 // Inside a parenthesised group the closing parenthesis terminates a line the
 // same way the end of the input does at the root.

package/src/index.js

@@ -1,5 +1,7 @@
 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';
+export { stripComments } from './comments.js';

package/src/parser-generated.js

@@ -1487,39 +1487,173 @@ function peg$parse(input, options) {
   }
 
   function peg$parseeol() {
-    let s0, s1, s2, s3;
+    let s0, s1, s2;
 
     s0 = peg$currPos;
     s1 = peg$parse__();
-    s2 = [];
-    s3 = input.charAt(peg$currPos);
-    if (peg$r1.test(s3)) {
+    s2 = peg$parselineBreaks();
+    if (s2 === peg$FAILED) {
+      s2 = peg$parseeof();
+      if (s2 === peg$FAILED) {
+        s2 = peg$parsenestedGroupEnd();
+      }
+    }
+    if (s2 !== peg$FAILED) {
+      s1 = [s1, s2];
+      s0 = s1;
+    } else {
+      peg$currPos = s0;
+      s0 = peg$FAILED;
+    }
+
+    return s0;
+  }
+
+  function peg$parselineBreaks() {
+    let s0, s1, s2, s3, s4, s5, s6;
+
+    s0 = peg$currPos;
+    s1 = [];
+    s2 = input.charAt(peg$currPos);
+    if (peg$r1.test(s2)) {
       peg$currPos++;
     } else {
-      s3 = peg$FAILED;
+      s2 = peg$FAILED;
       if (peg$silentFails === 0) { peg$fail(peg$e1); }
     }
-    if (s3 !== peg$FAILED) {
-      while (s3 !== peg$FAILED) {
-        s2.push(s3);
-        s3 = input.charAt(peg$currPos);
-        if (peg$r1.test(s3)) {
+    if (s2 !== peg$FAILED) {
+      while (s2 !== peg$FAILED) {
+        s1.push(s2);
+        s2 = input.charAt(peg$currPos);
+        if (peg$r1.test(s2)) {
           peg$currPos++;
         } else {
-          s3 = peg$FAILED;
+          s2 = peg$FAILED;
           if (peg$silentFails === 0) { peg$fail(peg$e1); }
         }
       }
     } else {
-      s2 = peg$FAILED;
+      s1 = peg$FAILED;
     }
-    if (s2 === peg$FAILED) {
-      s2 = peg$parseeof();
-      if (s2 === peg$FAILED) {
-        s2 = peg$parsenestedGroupEnd();
+    if (s1 !== peg$FAILED) {
+      s2 = [];
+      s3 = peg$currPos;
+      s4 = [];
+      s5 = input.charAt(peg$currPos);
+      if (peg$r0.test(s5)) {
+        peg$currPos++;
+      } else {
+        s5 = peg$FAILED;
+        if (peg$silentFails === 0) { peg$fail(peg$e0); }
+      }
+      if (s5 !== peg$FAILED) {
+        while (s5 !== peg$FAILED) {
+          s4.push(s5);
+          s5 = input.charAt(peg$currPos);
+          if (peg$r0.test(s5)) {
+            peg$currPos++;
+          } else {
+            s5 = peg$FAILED;
+            if (peg$silentFails === 0) { peg$fail(peg$e0); }
+          }
+        }
+      } else {
+        s4 = peg$FAILED;
+      }
+      if (s4 !== peg$FAILED) {
+        s5 = [];
+        s6 = input.charAt(peg$currPos);
+        if (peg$r1.test(s6)) {
+          peg$currPos++;
+        } else {
+          s6 = peg$FAILED;
+          if (peg$silentFails === 0) { peg$fail(peg$e1); }
+        }
+        if (s6 !== peg$FAILED) {
+          while (s6 !== peg$FAILED) {
+            s5.push(s6);
+            s6 = input.charAt(peg$currPos);
+            if (peg$r1.test(s6)) {
+              peg$currPos++;
+            } else {
+              s6 = peg$FAILED;
+              if (peg$silentFails === 0) { peg$fail(peg$e1); }
+            }
+          }
+        } else {
+          s5 = peg$FAILED;
+        }
+        if (s5 !== peg$FAILED) {
+          s4 = [s4, s5];
+          s3 = s4;
+        } else {
+          peg$currPos = s3;
+          s3 = peg$FAILED;
+        }
+      } else {
+        peg$currPos = s3;
+        s3 = peg$FAILED;
+      }
+      while (s3 !== peg$FAILED) {
+        s2.push(s3);
+        s3 = peg$currPos;
+        s4 = [];
+        s5 = input.charAt(peg$currPos);
+        if (peg$r0.test(s5)) {
+          peg$currPos++;
+        } else {
+          s5 = peg$FAILED;
+          if (peg$silentFails === 0) { peg$fail(peg$e0); }
+        }
+        if (s5 !== peg$FAILED) {
+          while (s5 !== peg$FAILED) {
+            s4.push(s5);
+            s5 = input.charAt(peg$currPos);
+            if (peg$r0.test(s5)) {
+              peg$currPos++;
+            } else {
+              s5 = peg$FAILED;
+              if (peg$silentFails === 0) { peg$fail(peg$e0); }
+            }
+          }
+        } else {
+          s4 = peg$FAILED;
+        }
+        if (s4 !== peg$FAILED) {
+          s5 = [];
+          s6 = input.charAt(peg$currPos);
+          if (peg$r1.test(s6)) {
+            peg$currPos++;
+          } else {
+            s6 = peg$FAILED;
+            if (peg$silentFails === 0) { peg$fail(peg$e1); }
+          }
+          if (s6 !== peg$FAILED) {
+            while (s6 !== peg$FAILED) {
+              s5.push(s6);
+              s6 = input.charAt(peg$currPos);
+              if (peg$r1.test(s6)) {
+                peg$currPos++;
+              } else {
+                s6 = peg$FAILED;
+                if (peg$silentFails === 0) { peg$fail(peg$e1); }
+              }
+            }
+          } else {
+            s5 = peg$FAILED;
+          }
+          if (s5 !== peg$FAILED) {
+            s4 = [s4, s5];
+            s3 = s4;
+          } else {
+            peg$currPos = s3;
+            s3 = peg$FAILED;
+          }
+        } else {
+          peg$currPos = s3;
+          s3 = peg$FAILED;
+        }
       }
-    }
-    if (s2 !== peg$FAILED) {
       s1 = [s1, s2];
       s0 = s1;
     } else {

package/tests/Comments.test.js

@@ -0,0 +1,160 @@
+// Conformance tests for line comments (issue #301).
+//
+// `#` starts a comment that runs to the end of the line, unless it sits inside
+// a token or inside a delimited reference. Parsers accept comments by default
+// and can be told to treat `#` as an ordinary character again. The table below
+// is shared with the Rust, Python, C#, Go, Java and PHP suites, so a document
+// written by one implementation reads the same in all of them.
+
+import { test, expect } from 'bun:test';
+import {
+  Link,
+  Parser,
+  ParseError,
+  formatLinks,
+  stripComments,
+} from '../src/index.js';
+
+const parser = new Parser();
+
+// Render a parsed node unambiguously: every reference is wrapped in angle
+// brackets, so a `#` that survived as content is visible.
+function render(node) {
+  if (!node.values || node.values.length === 0) {
+    return `<${node.id ?? ''}>`;
+  }
+  const head =
+    node.id === null || node.id === undefined ? '' : `<${node.id}>: `;
+  return `(${head}${node.values.map(render).join(' ')})`;
+}
+
+function parsesAs(input) {
+  return parser.parse(input).map(render).join('\n');
+}
+
+test('a line that starts with a hash is a comment', () => {
+  expect(parsesAs('# a b\n')).toBe('');
+});
+
+test('a comment may hold a colon', () => {
+  // The document from #301: prose with a colon used to be a parse error.
+  expect(parsesAs('# a: b\n')).toBe('');
+});
+
+test('a comment may hold anything at all', () => {
+  expect(parsesAs('# ) : ( " \' ` #\n')).toBe('');
+});
+
+test('a comment ends at the end of its line', () => {
+  expect(parsesAs('# note\na: b\n')).toBe('(<a>: <b>)');
+});
+
+test('a comment may follow a link', () => {
+  expect(parsesAs('a: b # why\n')).toBe('(<a>: <b>)');
+});
+
+test('a comment may follow a group', () => {
+  expect(parsesAs('(a b) # why\n')).toBe('(<a> <b>)');
+});
+
+test('a comment needs no closing newline', () => {
+  expect(parsesAs('a: b # why')).toBe('(<a>: <b>)');
+});
+
+test('a comment line inside an indented block is skipped', () => {
+  expect(parsesAs('parent\n  # what the child is for\n  child\n')).toBe(
+    parsesAs('parent\n  child\n')
+  );
+});
+
+test('a comment line inside a group is skipped', () => {
+  expect(parsesAs('(\n  a\n  # why\n  b\n)\n')).toBe(
+    parsesAs('(\n  a\n  b\n)\n')
+  );
+});
+
+test('a line of spaces separates links the way an empty line does', () => {
+  // Blanking a comment leaves a line of spaces behind, so such a line has to
+  // read as a blank line.
+  expect(parsesAs('a\n   \nb\n')).toBe(parsesAs('a\n\nb\n'));
+});
+
+test('a document of comments alone holds no links', () => {
+  expect(parsesAs('# one\n# two\n')).toBe('');
+});
+
+test('a hash inside a token is an ordinary character', () => {
+  expect(parsesAs('issue#1047\n')).toBe('(<issue#1047>)');
+});
+
+test('a hash that opens a token is an ordinary character', () => {
+  expect(parsesAs('a: b#c\n')).toBe('(<a>: <b#c>)');
+});
+
+test('a hash inside a delimited reference is content', () => {
+  expect(parsesAs('"# not a comment" a\n')).toBe('(<# not a comment> <a>)');
+});
+
+test('a comment may follow a delimited reference', () => {
+  expect(parsesAs('"a" # why\n')).toBe('(<a>)');
+});
+
+test('a hash inside a multiline delimited reference is content', () => {
+  expect(parsesAs('"a # b\nc" d\n')).toBe('(<a # b\nc> <d>)');
+});
+
+test('a parser without comments keeps the hash', () => {
+  const plain = new Parser({ comments: false });
+
+  expect(plain.parse('# a b\n').map(render).join('\n')).toBe('(<#> <a> <b>)');
+});
+
+test('a parser without comments still rejects the document from the issue', () => {
+  const plain = new Parser({ comments: false });
+
+  expect(() => plain.parse('# a: b\n')).toThrow(ParseError);
+});
+
+test('comments are on by default', () => {
+  expect(new Parser().comments).toBe(true);
+  expect(new Parser({}).comments).toBe(true);
+});
+
+test('a comment does not move the position a later error is reported at', () => {
+  // Blanking a comment keeps every later character where it was, so the
+  // position reported for a defect is the position in the original document.
+  let error = null;
+  try {
+    parser.parse('# a comment\nstage: rust: nextest\n');
+  } catch (thrown) {
+    error = thrown;
+  }
+
+  expect(error).toBeInstanceOf(ParseError);
+  expect(error.line).toBe(2);
+  expect(error.column).toBe(12);
+  expect(error.lineText).toBe('stage: rust: nextest');
+});
+
+test('blanking a comment keeps the length of the document', () => {
+  expect(stripComments('a: b # why\n')).toBe('a: b      \n');
+  expect(stripComments('"# kept"\n')).toBe('"# kept"\n');
+  expect(stripComments('issue#1047\n')).toBe('issue#1047\n');
+  expect(stripComments('a: b\n').length).toBe(5);
+});
+
+test('a reference that begins with a hash is written quoted', () => {
+  // Without the quotes the document would read as `a` followed by a comment.
+  const document = formatLinks([
+    new Link(null, [new Link('a'), new Link('#tag')]),
+  ]);
+
+  expect(document).toBe("(a '#tag')");
+  expect(parser.parse(document).map(render).join('\n')).toBe('(<a> <#tag>)');
+});
+
+test('a hash that cannot open a comment is left unquoted', () => {
+  expect(Link.escapeReference('issue#1047')).toBe('issue#1047');
+  expect(Link.escapeReference('#')).toBe("'#'");
+  expect(Link.escapeReference('#ff0000')).toBe("'#ff0000'");
+});