links-notation 0.21.3 → 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.3",
+  "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,6 +9,12 @@
   // 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
@@ -22,6 +28,7 @@
     indentationStack = [0];
     baseIndentation = null;
     contextStack = [];
+    contextDepth = 0;
     unreadableLines = new Set();
     return true;
   }
@@ -31,7 +38,8 @@
   }
 
   function enterNestedContext() {
-    contextStack.push({ indentationStack, baseIndentation });
+    contextStack.push({ indentationStack, baseIndentation, contextDepth });
+    contextDepth = depth() + 1;
     indentationStack = [0];
     baseIndentation = null;
     return true;
@@ -42,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;
   }
@@ -115,8 +145,11 @@ line = CHECK_INDENTATION l:element { return l; }
 
 // 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())); }
-    e:anyLink saved:SAVE_INDENTATION l:(PUSH_INDENTATION @links)? {
+    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.
@@ -155,7 +188,8 @@ 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;
   }
@@ -168,6 +202,9 @@ nestedGroupBody = skipEmptyLines l:links _ ")" { return { nested: l }; }
 
 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; }

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';