links-notation 0.21.2 → 0.22.0

package/index.d.ts

@@ -106,6 +106,12 @@ export class Link {
 /**
  * Parser options for configuring the parser behavior
  */
+/**
+ * How deep links may nest when nothing says otherwise (64). The same limit
+ * applies in every Links Notation implementation.
+ */
+export const DEFAULT_MAX_DEPTH: number;
+
 export interface ParserOptions {
   /**
    * Maximum input size in bytes (default: 10MB)
@@ -113,7 +119,9 @@ export interface ParserOptions {
   maxInputSize?: number;
 
   /**
-   * Maximum nesting depth (default: 1000)
+   * How deep links may nest: every parenthesized group and every indentation
+   * level is one level. A document nested deeper is refused with a ParseError
+   * whose maxDepth is set (default: 64)
    */
   maxDepth?: number;
 
@@ -293,6 +301,12 @@ export class ParseError extends Error {
    * The position the generated parser reported
    */
   location: ParseErrorLocation;
+
+  /**
+   * The deepest nesting allowed, when the document is nested deeper than
+   * that; null for any other error
+   */
+  maxDepth: number | null;
 }
 
 /**

package/package.json

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

package/src/ParseError.js

@@ -12,6 +12,9 @@ const ELLIPSIS = '...';
  * 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.
+ *
+ * A document nested deeper than the parser's maxDepth is refused with this
+ * error too; then maxDepth says how deep the nesting may go.
  */
 export class ParseError extends Error {
   /**
@@ -24,7 +27,9 @@ export class ParseError extends Error {
     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}`);
+    const maxDepth = error?.maxDepth ?? null;
+    const kind = maxDepth === null ? 'Syntax error' : 'Nesting too deep';
+    super(`${kind} at ${summary}\n${snippet}`);
 
     this.name = 'ParseError';
     /** @type {Error} The error the generated parser threw */
@@ -43,6 +48,8 @@ export class ParseError extends Error {
     this.lineText = lineText;
     /** @type {string} The offending line with a caret under the offending column */
     this.snippet = snippet;
+    /** @type {number|null} The deepest nesting allowed, when the document is nested deeper; null for any other error */
+    this.maxDepth = maxDepth;
   }
 }
 

package/src/Parser.js

@@ -3,17 +3,24 @@ import { ParseError } from './ParseError.js';
 import { stripComments } from './comments.js';
 import * as parserModule from './parser-generated.js';
 
+/**
+ * How deep links may nest when nothing says otherwise. The parser recurses once
+ * per level, and the same limit applies in every Links Notation implementation,
+ * so a document one of them reads is not too deep for another.
+ */
+export const DEFAULT_MAX_DEPTH = 64;
+
 export class Parser {
   /**
    * Create a new Parser instance
    * @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 {number} options.maxDepth - How deep links may nest: every parenthesized group and every indentation level is one level (default: 64)
    * @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.maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
     this.comments = options.comments ?? true;
   }
 
@@ -40,7 +47,9 @@ export class Parser {
     const prepared = this.comments ? stripComments(input) : input;
 
     try {
-      const rawResult = parserModule.parse(prepared);
+      const rawResult = parserModule.parse(prepared, {
+        maxDepth: this.maxDepth,
+      });
       return this.transformResult(rawResult);
     } catch (error) {
       // A syntax error knows where it stopped; anything else is passed on with

package/src/grammar.pegjs

@@ -9,16 +9,37 @@
   // group opens a nested context that starts fresh at indentation level zero,
   // so line breaks and indentation mean the same thing at every depth.
   let contextStack = [];
+  // How deeply the current context is nested: the enclosing groups and the
+  // indentation levels around them. Every level is a level of recursion, so
+  // links nested deeper than maxDepth are refused rather than recursed into
+  // until the stack overflows.
+  let contextDepth = 0;
+  const maxDepth = options.maxDepth ?? Infinity;
+  // Lines already found unreadable, keyed by where they start and whether they
+  // are inside a parenthesised group. Reading a line depends on nothing else: a
+  // group starts a fresh indentation context, and indentation only decides
+  // which lines become children, so a line that could not be read once never
+  // can be. A line that does not parse as the first child of the line above it
+  // is tried again as a sibling at every enclosing indentation level, and
+  // without this each of those attempts would read the whole line again.
+  let unreadableLines = new Set();
 
   function resetState() {
     indentationStack = [0];
     baseIndentation = null;
     contextStack = [];
+    contextDepth = 0;
+    unreadableLines = new Set();
     return true;
   }
 
+  function lineKey(position) {
+    return contextStack.length > 0 ? -1 - position : position;
+  }
+
   function enterNestedContext() {
-    contextStack.push({ indentationStack, baseIndentation });
+    contextStack.push({ indentationStack, baseIndentation, contextDepth });
+    contextDepth = depth() + 1;
     indentationStack = [0];
     baseIndentation = null;
     return true;
@@ -29,10 +50,32 @@
     if (saved) {
       indentationStack = saved.indentationStack;
       baseIndentation = saved.baseIndentation;
+      contextDepth = saved.contextDepth;
     }
     return true;
   }
 
+  // The nesting depth of the line being read: every enclosing group and every
+  // indentation level is one level, and the lines of a document are at level 0.
+  function depth() {
+    return contextDepth + indentationStack.length - 1;
+  }
+
+  // Refuses links at the given depth when it is deeper than maxDepth. The error
+  // is thrown rather than returned as a failed match, so no alternative is
+  // tried in its place, and says where the nesting got too deep.
+  function checkDepth(levels, where) {
+    if (levels <= maxDepth) {
+      return true;
+    }
+    try {
+      error(`nesting depth exceeds the maximum of ${maxDepth}`, where);
+    } catch (tooDeep) {
+      tooDeep.maxDepth = maxDepth;
+      throw tooDeep;
+    }
+  }
+
   function isInsideNestedContext() {
     return contextStack.length > 0;
   }
@@ -100,14 +143,42 @@ firstLine = SET_BASE_INDENTATION l:element { return l; }
 
 line = CHECK_INDENTATION l:element { return l; }
 
-element = e:anyLink PUSH_INDENTATION l:links {
+// A line is read once, whether or not indented children follow it: reading it
+// again after looking for children doubled the work at every level of nesting.
+// Only a line that parsed counts towards the depth, so trailing spaces indented
+// past the limit are still read as the whitespace they are.
+element = &{ return !unreadableLines.has(lineKey(offset())); }
+    start:HERE e:anyLink &{ return checkDepth(depth(), start); }
+    saved:SAVE_INDENTATION l:(PUSH_INDENTATION @links)? {
+    if (l === null) {
+      // No child line followed the indentation. Forget what looking for one
+      // pushed, so the next line is compared with this line's indentation.
+      indentationStack = saved;
+      return e;
+    }
     return Object.assign({}, e, { children: l });
   }
-  / e:anyLink { return e; }
+  // Remember that this line could not be read. The predicate always fails, so
+  // the "." is never reached; it only tells Peggy that this alternative cannot
+  // succeed without consuming input.
+  / &{ unreadableLines.add(lineKey(offset())); return false; } .
 
 referenceOrLink = l:multiLineAnyLink { return l; } / i:reference { return { id: i }; }
 
-anyLink = ml:multiLineAnyLink eol { return ml; } / il:indentedIdLink { return il; } / sl:singleLineAnyLink { return sl; }
+// A line that starts with a parenthesised group reads that group once and then
+// branches on what follows it: the end of the line makes the group the whole
+// link, and more values make it the first value of a value link. Neither an
+// indented ID nor a single-line link can start with a parenthesis, so nothing
+// else is tried for such a line; trying them read the group again, doubling
+// the work at every level of nesting.
+anyLink = &"(" @groupLink / !"(" @(indentedIdLink / singleLineAnyLink)
+
+groupLink = g:multiLineAnyLink rest:groupLinkRest {
+    return rest === null ? g : { values: [g].concat(rest) };
+  }
+
+groupLinkRest = eol { return null; }
+  / @singleLineValueAndWhitespace* eol
 
 multiLineAnyLink = nestedGroup
 
@@ -117,16 +188,23 @@ singleLineAnyLink = fl:singleLineLink eol { return fl; }
 // A parenthesised group opens a nested context that follows exactly the same
 // rules as the root of the document: line breaks separate links and
 // indentation nests them, starting fresh at indentation level zero.
-nestedGroup = "(" ENTER_NESTED_CONTEXT body:nestedGroupBody {
+nestedGroup = start:HERE "(" &{ return checkDepth(depth() + 1, start); }
+    ENTER_NESTED_CONTEXT body:nestedGroupBody {
     exitNestedContext();
     return body;
   }
+  // The group was opened but its body did not parse: restore the context it
+  // was opened in before failing, just as a parsed group does.
+  / "(" &{ exitNestedContext(); return false; }
 
 nestedGroupBody = skipEmptyLines l:links _ ")" { return { nested: l }; }
   / _ ")" { return { nested: [] }; }
 
 ENTER_NESTED_CONTEXT = &{ return enterNestedContext(); }
 
+// Where the parser is, to say where nesting got too deep.
+HERE = "" { return location(); }
+
 singleLineValueAndWhitespace = __ value:referenceOrLink { return value; }
 
 singleLineValues = list:singleLineValueAndWhitespace+ { return list; }
@@ -193,6 +271,8 @@ backtickQuotedUniversal = &'`' &{
 consumeBacktick = c:. cs:consumeBacktickMore* { return [c].concat(cs).join(''); }
 consumeBacktickMore = &{ return parsedLength > 1 && (parsedLength--, true); } c:. { return c; }
 
+SAVE_INDENTATION = "" { return indentationStack.slice(); }
+
 SET_BASE_INDENTATION = spaces:" "* { setBaseIndentation(spaces); }
 
 PUSH_INDENTATION = spaces:" "* &{ return normalizeIndentation(spaces) > getCurrentIndentation(); } { pushIndentation(spaces); }

package/src/index.js

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