links-notation 0.18.0 → 0.19.0

package/README.md

@@ -252,6 +252,39 @@ const links = new Parser().parse(`value (
 console.log(formatLinks(links)); // (value ((id 1) (label one)))
 ```
 
+### Comments
+
+A `#` hides the rest of the line it stands on, so a document can carry prose
+about itself:
+
+```lino
+# the machines this deploys to
+deploy: staging # only staging, for now
+```
+
+Both comments are gone by the time the document is read, leaving the single
+link `(deploy: staging)`. A `#` only opens a comment where a reference could
+begin, so a `#` inside a token (`issue#1047`) and a `#` inside a delimited
+reference (`"#"`) stay ordinary characters.
+
+A formatter keeps the same rule from the other side: a reference that begins
+with a `#` is written quoted (`'#tag'`), so a document it writes reads back as
+itself.
+
+Comments are on by default, and a parser can be told to read `#` as an ordinary
+character again, for documents written before comments existed:
+
+```javascript
+import { Parser, formatLinks } from 'links-notation';
+
+const document =
+  '# the machines this deploys to\ndeploy: staging # only staging, for now\n';
+console.log(formatLinks(new Parser().parse(document))); // (deploy: staging)
+
+const plain = new Parser({ comments: false });
+console.log(formatLinks(plain.parse('# a b\n'))); // (# a b)
+```
+
 ## API Reference
 
 ### Classes
@@ -260,6 +293,8 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 
 Main parser class for converting strings to links.
 
+- `constructor(options)` - Create a parser; `options.comments` set to `false`
+  reads `#` as an ordinary character instead of the start of a comment
 - `initialize()` - Initialize the parser (async)
 - `parse(input)` - Parse a Lino string and return links
 
@@ -288,7 +323,7 @@ where the document stopped making sense and quotes the offending line:
 import { Parser, ParseError } from 'links-notation';
 
 try {
-  new Parser().parse('# ok line\n# break: two\nci_gate x\n');
+  new Parser().parse('ci_gate x\nstage: rust: nextest\n');
 } catch (error) {
   console.error(error.message);
   if (error instanceof ParseError) {
@@ -298,9 +333,9 @@ try {
 ```
 
 ```text
-Syntax error at line 2, column 8: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
-2 | # break: two
-  |        ^
+Syntax error at line 2, column 12: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
+2 | stage: rust: nextest
+  |            ^
 ```
 
 - `offset` - Offset of the offending position from the start of the document

package/README.ru.md

@@ -171,6 +171,39 @@ const links = new Parser().parse(`value (
 console.log(formatLinks(links)); // (value ((id 1) (label one)))
 ```
 
+### Комментарии
+
+`#` скрывает остаток строки, на которой стоит, поэтому документ может нести
+пояснения о самом себе:
+
+```lino
+# машины, на которые идёт выкладка
+deploy: staging # пока только staging
+```
+
+К моменту чтения документа обоих комментариев уже нет, остаётся одна связь
+`(deploy: staging)`. `#` открывает комментарий только там, где могла бы
+начаться ссылка, поэтому `#` внутри токена (`issue#1047`) и `#` внутри ссылки
+в кавычках (`"#"`) остаются обычными символами.
+
+Форматтер соблюдает то же правило с другой стороны: ссылка, начинающаяся с `#`,
+записывается в кавычках (`'#tag'`), поэтому написанный им документ читается
+обратно как он сам.
+
+Комментарии включены по умолчанию, а парсеру можно велеть снова читать `#` как
+обычный символ - для документов, написанных до появления комментариев:
+
+```javascript
+import { Parser, formatLinks } from 'links-notation';
+
+const document =
+  '# машины, на которые идёт выкладка\ndeploy: staging # пока только staging\n';
+console.log(formatLinks(new Parser().parse(document))); // (deploy: staging)
+
+const plain = new Parser({ comments: false });
+console.log(formatLinks(plain.parse('# a b\n'))); // (# a b)
+```
+
 ## Справочник API
 
 ### Классы
@@ -179,6 +212,8 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 
 Основной класс парсера для преобразования строк в связи.
 
+- `constructor(options)` - Создать парсер; `options.comments` со значением
+  `false` читает `#` как обычный символ, а не как начало комментария
 - `initialize()` - Инициализация парсера (асинхронно)
 - `parse(input)` - Парсинг строки Lino и возвращение связей
 
@@ -207,7 +242,7 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 import { Parser, ParseError } from 'links-notation';
 
 try {
-  new Parser().parse('# ok line\n# break: two\nci_gate x\n');
+  new Parser().parse('ci_gate x\nstage: rust: nextest\n');
 } catch (error) {
   console.error(error.message);
   if (error instanceof ParseError) {
@@ -217,9 +252,9 @@ try {
 ```
 
 ```text
-Syntax error at line 2, column 8: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
-2 | # break: two
-  |        ^
+Syntax error at line 2, column 12: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
+2 | stage: rust: nextest
+  |            ^
 ```
 
 - `offset` - Смещение сломанной позиции от начала документа

package/dist/index.js

@@ -44,7 +44,7 @@ class Link {
     }
     const hasSingleQuote = reference.includes("'");
     const hasDoubleQuote = reference.includes('"');
-    const needsQuoting = reference.includes(":") || reference.includes("(") || reference.includes(")") || reference.includes(" ") || reference.includes("\t") || reference.includes(`
+    const needsQuoting = reference.startsWith("#") || reference.includes(":") || reference.includes("(") || reference.includes(")") || reference.includes(" ") || reference.includes("\t") || reference.includes(`
 `) || reference.includes("\r") || hasDoubleQuote || hasSingleQuote;
     if (hasSingleQuote && hasDoubleQuote) {
       return `'${reference.replace(/'/g, "\\'")}'`;
@@ -320,6 +320,93 @@ function windowAround(lineText, column) {
   return [quoted, target - start + shift + 1];
 }
 
+// src/comments.js
+var COMMENT = "#";
+var QUOTES = ['"', "'", "`"];
+var BEFORE_REFERENCE = [" ", "\t", `
+`, "\r", "(", ":"];
+var BEFORE_COMMENT = [" ", "\t", `
+`, "\r"];
+function stripComments(document) {
+  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] !== `
+` && document[position] !== "\r") {
+        blanked[position] = " ";
+        position++;
+      }
+      continue;
+    }
+    position++;
+  }
+  return blanked === null ? document : blanked.join("");
+}
+function follows(document, position, allowed) {
+  return position === 0 || allowed.includes(document[position - 1]);
+}
+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;
+}
+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;
+}
+
 // src/parser-generated.js
 class peg$SyntaxError extends SyntaxError {
   constructor(message, expected, found, location) {
@@ -1751,42 +1838,189 @@ function peg$parse(input, options) {
     return s0;
   }
   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 {
@@ -2063,6 +2297,7 @@ class Parser {
   constructor(options = {}) {
     this.maxInputSize = options.maxInputSize || 10 * 1024 * 1024;
     this.maxDepth = options.maxDepth || 1000;
+    this.comments = options.comments ?? true;
   }
   parse(input) {
     if (typeof input !== "string") {
@@ -2071,8 +2306,9 @@ class Parser {
     if (input.length > this.maxInputSize) {
       throw new Error(`Input size exceeds maximum allowed size of ${this.maxInputSize} bytes`);
     }
+    const prepared = this.comments ? stripComments(input) : input;
     try {
-      const rawResult = peg$parse(input);
+      const rawResult = peg$parse(prepared);
       return this.transformResult(rawResult);
     } catch (error) {
       if (error && error.location) {
@@ -2218,5 +2454,6 @@ export {
   LinksGroup,
   ParseError,
   Parser,
-  formatLinks
+  formatLinks,
+  stripComments
 };

package/index.d.ts

@@ -116,6 +116,12 @@ export interface ParserOptions {
    * Maximum nesting depth (default: 1000)
    */
   maxDepth?: number;
+
+  /**
+   * If false, read `#` as an ordinary character instead of the start of a
+   * comment (default: true)
+   */
+  comments?: boolean;
 }
 
 /**
@@ -134,6 +140,11 @@ export class Parser {
    */
   maxDepth: number;
 
+  /**
+   * Whether `#` starts a comment that runs to the end of its line
+   */
+  comments: boolean;
+
   /**
    * Create a new Parser instance
    * @param options - Parser options
@@ -149,6 +160,14 @@ export class Parser {
   parse(input: string): Link[];
 }
 
+/**
+ * Blank out every comment in a document, keeping its length so that every
+ * character stays at the offset it was written at.
+ * @param document - The document to read
+ * @returns The document, of the same length, without its comments
+ */
+export function stripComments(document: string): string;
+
 /**
  * The position a parse stopped at, as the generated parser reports it
  */

package/package.json

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

package/src/Link.js

@@ -95,7 +95,11 @@ export class Link {
     const hasSingleQuote = reference.includes("'");
     const hasDoubleQuote = reference.includes('"');
 
+    // A reference that begins with a `#` has to be quoted, or it would read
+    // back as a comment. A `#` anywhere else in a reference is content
+    // (`issue#1047`), so only the first character matters.
     const needsQuoting =
+      reference.startsWith('#') ||
       reference.includes(':') ||
       reference.includes('(') ||
       reference.includes(')') ||

package/src/Parser.js

@@ -1,5 +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 {
@@ -8,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;
   }
 
   /**
@@ -32,8 +35,12 @@ 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) {
       // A syntax error knows where it stopped; anything else is passed on with

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

@@ -4,3 +4,4 @@ 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'");
+});

package/tests/ParseErrorPosition.test.js

@@ -22,22 +22,24 @@ function syntaxError(document) {
 }
 
 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');
+  // The defect is the second colon on line 2, and the two lines after it are
+  // fine.
+  const error = syntaxError(
+    'ci_gate x\nstage: rust: nextest\nnext stage\n  clippy'
+  );
 
   expect(error.line).toBe(2);
-  expect(error.column).toBe(8);
+  expect(error.column).toBe(12);
   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');
+  // Rust and C# report offset 21, line 2, column 12 for this document.
+  const error = syntaxError('ci_gate x\nstage: rust: nextest\n');
 
-  expect(error.offset).toBe(17);
+  expect(error.offset).toBe(21);
   expect(error.line).toBe(2);
-  expect(error.column).toBe(8);
+  expect(error.column).toBe(12);
 });
 
 test('reports the line a late defect is on', () => {
@@ -68,20 +70,20 @@ test('reports an unmatched closing parenthesis', () => {
 });
 
 test('message says where the document broke', () => {
-  const error = syntaxError('# ok line\n# break: two\n');
+  const error = syntaxError('ci_gate x\nstage: rust: nextest\n');
 
-  expect(error.message.startsWith('Syntax error at line 2, column 8:')).toBe(
+  expect(error.message.startsWith('Syntax error at line 2, column 12:')).toBe(
     true
   );
-  expect(error.snippet).toBe('2 | # break: two\n  |        ^');
+  expect(error.snippet).toBe('2 | stage: rust: nextest\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 document = `ci_gate x\nstage: rust: nextest\n${'trailing line\n'.repeat(500)}`;
 
   const error = syntaxError(document);
 
-  expect(error.message).toContain('line 2, column 8');
+  expect(error.message).toContain('line 2, column 12');
   expect(error.message).not.toContain('trailing line');
   expect(error.message.length).toBeLessThan(200);
 });