links-notation 0.21.1 → 0.21.3

package/src/quotes.js

@@ -0,0 +1,251 @@
+/**
+ * Delimited references, and how far each one reaches.
+ *
+ * A reference opened by a run of N delimiters (`"`, `'` or `` ` ``) closes at
+ * the next run of exactly N, and a run of 2N inside it is that delimiter
+ * escaped. An even run that encloses nothing substantive is the empty
+ * reference: the shortest reading, a bare delimiter pair enclosing nothing,
+ * wins over a longer n-quote delimiter.
+ *
+ * A run of R delimiters in a body is read as a whole: each 2N of it in turn are
+ * an escaped N, and the R % 2N left over close the reference when there are at
+ * least N of them - the last N close it, the ones before are content - and are
+ * content otherwise. So a run closes the reference exactly when
+ * `Math.floor(R / N)` is odd, and a run shorter than N never does.
+ *
+ * {@link DelimitedReferences} lists the runs of a delimiter once per document
+ * and links each run to the next longer one, so finding where a reference
+ * closes skips every run too short to close it. Reading a reference takes time
+ * linear in its body however wide its opening run is, and finding that a
+ * reference never closes does not take a pass over the rest of the document
+ * each time it is asked.
+ */
+
+/** The characters a reference can be written between. */
+export const QUOTES = ['"', "'", '`'];
+
+/**
+ * Every delimited reference of one document, read on demand.
+ *
+ * The grammar and the comment reader each keep one per document they read, so
+ * a reference asked for twice is read once.
+ */
+export class DelimitedReferences {
+  /**
+   * @param {string} document - The document the references are read from
+   */
+  constructor(document) {
+    this.document = document;
+    this.runsByQuote = new Map();
+    this.readings = new Map();
+  }
+
+  /**
+   * The reference opened at `start`.
+   * @param {number} start - Position of the opening delimiter
+   * @returns {{value: string, length: number}|null} What the reference holds
+   *   and how many characters it takes, or null when nothing opens there
+   */
+  readAt(start) {
+    if (!this.readings.has(start)) {
+      this.readings.set(start, this.#read(start));
+    }
+    return this.readings.get(start);
+  }
+
+  /**
+   * The position just past the reference opened at `start`.
+   * @param {number} start - Position of the opening delimiter
+   * @returns {number|null} The position, or null when nothing opens there
+   */
+  endAt(start) {
+    const reading = this.readAt(start);
+    return reading === null ? null : start + reading.length;
+  }
+
+  #read(start) {
+    const document = this.document;
+    const quote = document[start];
+    if (!QUOTES.includes(quote)) {
+      return null;
+    }
+
+    const runs = this.#runsOf(quote);
+    const opening = runs.indexOf(start);
+    const count = runs.end(opening) - start;
+
+    // The first run after the opening one that closes the reference.
+    let closing = opening + 1;
+    while (closing < runs.count) {
+      const length = runs.lengths[closing];
+      if (length < count) {
+        closing = runs.nextLonger[closing];
+      } else if (Math.floor(length / count) % 2 === 1) {
+        break;
+      } else {
+        closing++;
+      }
+    }
+    const end = closing < runs.count ? runs.end(closing) : null;
+    return reading(document, start, quote, count, end);
+  }
+
+  #runsOf(quote) {
+    if (!this.runsByQuote.has(quote)) {
+      this.runsByQuote.set(quote, new DelimiterRuns(this.document, quote));
+    }
+    return this.runsByQuote.get(quote);
+  }
+}
+
+/**
+ * The reference opened at `start`, read without a list of runs: for a single
+ * reference that is as quick, since it is read once.
+ * @param {string} document - The document being read
+ * @param {number} start - Position of the opening delimiter
+ * @returns {{value: string, length: number}|null} What the reference holds
+ *   and how many characters it takes, or null when nothing opens there
+ */
+export function readReference(document, start) {
+  const quote = document[start];
+  if (!QUOTES.includes(quote)) {
+    return null;
+  }
+  const count = runLength(document, start, quote);
+
+  let end = null;
+  let position = document.indexOf(quote, start + count);
+  while (position !== -1) {
+    const length = runLength(document, position, quote);
+    if (length >= count && Math.floor(length / count) % 2 === 1) {
+      end = position + length;
+      break;
+    }
+    position = document.indexOf(quote, position + length);
+  }
+  return reading(document, start, quote, count, end);
+}
+
+/**
+ * The reading of a reference opened by `count` delimiters at `start`, closed
+ * by the run that ends at `end` when there is one.
+ */
+function reading(document, start, quote, count, end) {
+  const emptyReference = count % 2 === 0 ? { value: '', length: count } : null;
+  if (end === null) {
+    return emptyReference;
+  }
+
+  const parts = [];
+  let position = start + count;
+  let run = document.indexOf(quote, position);
+  while (run !== -1 && run < end) {
+    const length = runLength(document, run, quote);
+    const escaped = Math.floor(length / (2 * count)) * count;
+    // The closing run is the last one of the body.
+    const closes = run + length === end ? count : 0;
+    parts.push(document.slice(position, run));
+    parts.push(quote.repeat(length - escaped - closes));
+    position = run + length;
+    run = document.indexOf(quote, position);
+  }
+  const value = parts.join('');
+
+  if (emptyReference !== null && !isSubstantiveBody(value)) {
+    return emptyReference;
+  }
+  return { value, length: end - start };
+}
+
+/** The number of `quote` delimiters in a row from `start` of `text`. */
+function runLength(text, start, quote) {
+  let end = start;
+  while (end < text.length && text[end] === quote) {
+    end++;
+  }
+  return end - start;
+}
+
+/**
+ * The maximal runs of one delimiter in a document, in order, each linked to the
+ * next run that is longer than it.
+ */
+class DelimiterRuns {
+  constructor(document, quote) {
+    this.starts = [];
+    this.lengths = [];
+
+    let position = document.indexOf(quote);
+    while (position !== -1) {
+      const length = runLength(document, position, quote);
+      this.starts.push(position);
+      this.lengths.push(length);
+      position = document.indexOf(quote, position + length);
+    }
+    this.count = this.starts.length;
+
+    // Every run between a run and the next longer one is at most as long as
+    // it, which is what lets a search for a run of some length jump over them.
+    this.nextLonger = new Array(this.count);
+    const longer = [];
+    for (let run = this.count - 1; run >= 0; run--) {
+      while (
+        longer.length > 0 &&
+        this.lengths[longer[longer.length - 1]] <= this.lengths[run]
+      ) {
+        longer.pop();
+      }
+      this.nextLonger[run] =
+        longer.length > 0 ? longer[longer.length - 1] : this.count;
+      longer.push(run);
+    }
+  }
+
+  /** Position just past the given run. */
+  end(run) {
+    return this.starts[run] + this.lengths[run];
+  }
+
+  /** The run that holds the given position of a delimiter. */
+  indexOf(position) {
+    let low = 0;
+    let high = this.count - 1;
+    while (low < high) {
+      const middle = (low + high + 1) >> 1;
+      if (this.starts[middle] <= position) {
+        low = middle;
+      } else {
+        high = middle - 1;
+      }
+    }
+    return low;
+  }
+}
+
+/**
+ * Whether a body written between an even run of delimiters carries something a
+ * pair of delimiters enclosing nothing cannot: at least one visible character,
+ * and no parenthesis it straddles.
+ * @param {string} content - The body between the delimiters
+ * @returns {boolean} True when the n-quote reading is the one to take
+ */
+export 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 (!/[ \t\n\r]/.test(character)) {
+      hasVisible = true;
+    }
+  }
+
+  return hasVisible && depth === 0;
+}

package/tests/Issue316QuoteRuns.test.js

@@ -0,0 +1,163 @@
+import { test, expect, setDefaultTimeout } from 'bun:test';
+import { performance } from 'node:perf_hooks';
+import { Parser } from '../src/Parser.js';
+import { quotedReferenceEnd, stripComments } from '../src/comments.js';
+import { DelimitedReferences } from '../src/quotes.js';
+import { StreamParser } from '../src/StreamParser.js';
+
+// Issue #316: a reference that opens with a wide run of delimiters used to be
+// read one character at a time, comparing the whole width at every position,
+// and every run that never closed was read to the end of the document again.
+// These documents took from seconds to tens of seconds; read a run at a time
+// they take milliseconds, so the bound below only fails on the old behaviour.
+
+const parser = new Parser();
+const BOUND_MS = 2000;
+const SIZE = 400000;
+// A regression fails on the bound; the timeout stops it from hanging the run.
+setDefaultTimeout(20000);
+
+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(source) {
+  return parser.parse(source).map(render).join('\n');
+}
+
+const q = (count) => "'".repeat(count);
+
+function timed(read) {
+  const started = performance.now();
+  const result = read();
+  return { result, elapsed: performance.now() - started };
+}
+
+// The shapes from the issue, and two that defeat shortcuts a fix could take.
+
+function wideQuoteOverALongRun(size) {
+  const width = Math.floor(size / 4);
+  return `${q(width + 1)} a ${q(width - 4)} ${'x'.repeat(2 * width)}`;
+}
+
+function narrowingUnclosedQuotes(size) {
+  const widths = [];
+  for (
+    let width = 2 * Math.floor(Math.sqrt(size / 2) / 2) + 1;
+    width >= 1;
+    width -= 2
+  ) {
+    widths.push(width);
+  }
+  const head = widths.map((width) => `${q(width)}x`).join(' ');
+  return `${head} ${"a' ".repeat(Math.floor((size - head.length) / 3))}`;
+}
+
+function closedWideQuoteOverQuotes(size) {
+  const width = Math.floor(size / 8);
+  return `${q(width)}${`${q(width - 1)}x`.repeat(6)}${q(width)}`;
+}
+
+function unclosedWidthsOverAnEvenRun(size) {
+  const run = Math.floor(size / 4);
+  const widths = [];
+  for (let width = Math.floor(Math.sqrt(size)); width >= 2; width--) {
+    if (Math.floor(run / width) % 2 === 0) widths.push(width);
+  }
+  const head = widths.map((width) => `${q(width)}x`).join(' ');
+  const tail = "a' ".repeat(Math.floor((size - head.length - run) / 3));
+  return `${head} ${tail}${q(run)} b`;
+}
+
+function expectParsedWithinBound(source) {
+  expect(timed(() => parser.parse(source)).elapsed).toBeLessThan(BOUND_MS);
+  expect(timed(() => stripComments(source)).elapsed).toBeLessThan(BOUND_MS);
+}
+
+test('a run inside a body is read as escapes then a closing run', () => {
+  expect(parsesAs("'''a'''")).toBe('(<a>)');
+  expect(parsesAs("'''a''''''b'''")).toBe("(<a'''b>)");
+  expect(parsesAs("''a'''")).toBe("(<a'>)");
+  expect(parsesAs("'a'''")).toBe("(<a'>)");
+  expect(parsesAs(`${q(3)}a${q(9)} b`)).toBe("(<a'''> <b>)");
+  expect(parsesAs(`${q(50)}a${q(100)}b${q(50)}`)).toBe(`(<a${q(50)}b>)`);
+  expect(parsesAs('"""a""b"""')).toBe('(<a""b>)');
+  expect(parsesAs('``a````b``')).toBe('(<a``b>)');
+});
+
+test('a run that never closes the reference leaves it unclosed', () => {
+  // Math.floor(7 / 3) is even: two escaped runs of three and one delimiter.
+  expect(parsesAs(`${q(3)}a${q(7)}`)).toBe(`(<${q(3)}a${q(7)}>)`);
+  expect(parsesAs(`${q(5)}a${q(4)}`)).toBe(`(<${q(5)}a${q(4)}>)`);
+  expect(parsesAs("''a'''''")).toBe("(<> <a'''''>)");
+  expect(parsesAs("''''x a")).toBe('(<> <x> <a>)');
+});
+
+test('a reference can open inside a run', () => {
+  // Comment stripping and the stream parser ask where a reference opened at
+  // any delimiter ends, including one in the middle of a run.
+  const cases = [
+    ["x'''a'''", 1, 8],
+    ["x'''a''", 2, 7],
+    ["x'''a'", 3, 6],
+    ["'''a", 0, null],
+    ["''''a", 0, 4],
+    ['a', 0, null],
+    ["'a'", 3, null],
+  ];
+  for (const [document, start, end] of cases) {
+    expect(quotedReferenceEnd(document, start)).toBe(end);
+    expect(new DelimitedReferences(document).endAt(start)).toBe(end);
+  }
+});
+
+test('a reference that opens with a wide run is read in linear time', () => {
+  const width = Math.floor(SIZE / 4);
+  const source = wideQuoteOverALongRun(SIZE);
+  const { result, elapsed } = timed(() => parser.parse(source));
+  // The odd opening run never closes, so it is a plain reference; the even
+  // run after `a` encloses nothing and is the empty reference.
+  expect(result.length).toBe(1);
+  expect(result[0].values.map((value) => value.id)).toEqual([
+    q(width + 1),
+    'a',
+    '',
+    'x'.repeat(2 * width),
+  ]);
+  expect(elapsed).toBeLessThan(BOUND_MS);
+});
+
+test('wide quote over a long run is parsed within the time bound', () => {
+  expectParsedWithinBound(wideQuoteOverALongRun(SIZE));
+});
+
+test('narrowing unclosed quotes is parsed within the time bound', () => {
+  expectParsedWithinBound(narrowingUnclosedQuotes(SIZE));
+});
+
+test('closed wide quote over quotes is parsed within the time bound', () => {
+  expectParsedWithinBound(closedWideQuoteOverQuotes(SIZE));
+});
+
+test('unclosed widths over an even run is parsed within the time bound', () => {
+  expectParsedWithinBound(unclosedWidthsOverAnEvenRun(SIZE));
+});
+
+test('a stream of wide quotes is read within the time bound', () => {
+  // The second line is what makes the stream ask whether the first is complete.
+  const source = `${closedWideQuoteOverQuotes(SIZE)}\nb`;
+  const links = [];
+  const { elapsed } = timed(() => {
+    const stream = new StreamParser();
+    stream.on('link', (link) => links.push(link));
+    stream.write(source);
+    stream.end();
+  });
+  expect(links.length).toBe(2);
+  expect(elapsed).toBeLessThan(BOUND_MS);
+});

package/tests/NestingDepth.test.js

@@ -0,0 +1,124 @@
+// Reading nested groups must take time that grows with the size of the
+// document, not with two to the power of its nesting depth
+// (https://github.com/link-foundation/links-notation/issues/314).
+//
+// Before the fix, every level of nesting doubled the work: a nine-byte document
+// took seconds. Each case is parsed on its own thread and fails when it has not
+// finished within the budget, so a regression fails instead of hanging.
+
+import { test, expect } from 'bun:test';
+import { clearTimeout, setTimeout } from 'node:timers';
+import { URL } from 'node:url';
+import { Worker } from 'node:worker_threads';
+import { Parser } from '../src/Parser.js';
+import { formatLinks } from '../src/Link.js';
+
+// Generous enough for a slow machine, and far below what the exponential
+// reading took at the depths used here.
+const BUDGET_MS = 5000;
+
+// The depth used for the shapes that used to take exponential time.
+const DEEP = 32;
+
+// A depth that shows the time grows with the size of the document.
+const VERY_DEEP = 256;
+
+function withinBudget(what, source) {
+  const worker = new Worker(
+    new URL('./support/nestingDepthWorker.js', import.meta.url)
+  );
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`${what} did not finish within ${BUDGET_MS} ms`)),
+      BUDGET_MS
+    );
+  });
+  const result = new Promise((resolve, reject) => {
+    worker.once('message', resolve);
+    worker.once('error', reject);
+  });
+  worker.postMessage(source);
+  return Promise.race([result, timeout]).finally(() => {
+    clearTimeout(timer);
+    worker.terminate();
+  });
+}
+
+const closed = (depth) => `${'('.repeat(depth)}a${')'.repeat(depth)}`;
+
+const valueAfter = (depth) => `${'('.repeat(depth)}a${') b'.repeat(depth)}`;
+
+const unclosed = (depth) => `${'('.repeat(depth)}a`;
+
+// Unclosed groups on lines that are each indented one space deeper.
+const indentedUnclosed = (depth) =>
+  Array.from({ length: depth }, (_, level) => `${' '.repeat(level)}(a`).join(
+    '\n'
+  );
+
+test(
+  'closed groups read in linear time',
+  async () => {
+    const source = closed(DEEP);
+    const result = await withinBudget('closed groups', source);
+    expect(result).toEqual({ formatted: source });
+  },
+  BUDGET_MS * 2
+);
+
+test(
+  'values after groups read in linear time',
+  async () => {
+    const source = valueAfter(DEEP);
+    const result = await withinBudget('values after groups', source);
+    expect(result).toEqual({ formatted: `(${source})` });
+  },
+  BUDGET_MS * 2
+);
+
+test(
+  'unclosed groups fail in linear time',
+  async () => {
+    const result = await withinBudget('unclosed groups', unclosed(DEEP));
+    expect(result).toEqual({ error: 'ParseError' });
+  },
+  BUDGET_MS * 2
+);
+
+test(
+  'unclosed groups on indented lines fail in linear time',
+  async () => {
+    const result = await withinBudget(
+      'unclosed indented groups',
+      indentedUnclosed(DEEP)
+    );
+    expect(result).toEqual({ error: 'ParseError' });
+  },
+  BUDGET_MS * 2
+);
+
+test(
+  'values after very deep groups read in linear time',
+  async () => {
+    const source = valueAfter(VERY_DEEP);
+    const result = await withinBudget('very deep values after groups', source);
+    expect(result).toEqual({ formatted: `(${source})` });
+  },
+  BUDGET_MS * 2
+);
+
+test('group followed by values keeps its structure', () => {
+  const cases = [
+    ['(a) b', '((a) b)'],
+    ['(a) (b) c', '((a) (b) c)'],
+    ['((a) b) c', '(((a) b) c)'],
+    ['(a: b) c', '((a: b) c)'],
+    ['(a)\n(b) c', '(a)\n((b) c)'],
+    ['x\n  (a) b\n  (c)', '(x)\n((x) ((a) b))\n((x) (c))'],
+  ];
+  const parser = new Parser();
+  for (const [source, expected] of cases) {
+    expect(formatLinks(parser.parse(source))).toBe(expected);
+  }
+});

package/tests/support/nestingDepthWorker.js

@@ -0,0 +1,15 @@
+// Parses the documents it is sent on its own thread, so a test can stop a
+// parse that takes too long instead of hanging.
+import { parentPort } from 'node:worker_threads';
+import { Parser } from '../../src/Parser.js';
+import { formatLinks } from '../../src/Link.js';
+
+const parser = new Parser();
+
+parentPort.on('message', (source) => {
+  try {
+    parentPort.postMessage({ formatted: formatLinks(parser.parse(source)) });
+  } catch (error) {
+    parentPort.postMessage({ error: error.name });
+  }
+});