links-notation 0.18.0 → 0.20.0

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);
 });

package/tests/StreamParser.test.js

@@ -0,0 +1,165 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  formatLinks,
+  Parser,
+  StreamParseError,
+  StreamParser,
+} from '../src/index.js';
+
+const document = `first loves data
+# streamed comment
+profile:
+  name Ada
+  note "line one
+line two"
+(nested:
+  child value)
+last sees first`;
+
+const formatted = (links) => formatLinks(links);
+
+describe('StreamParser', () => {
+  test('matches canonical parser one symbol at a time', () => {
+    const stream = new StreamParser();
+    for (const character of document) stream.write(character);
+
+    expect(formatted(stream.end())).toBe(
+      formatted(new Parser().parse(document))
+    );
+  });
+
+  test('supports line chunks final record and position', () => {
+    const stream = new StreamParser();
+    for (const line of document.match(/.*(?:\n|$)/g).filter(Boolean)) {
+      stream.write(line);
+    }
+
+    expect(formatted(stream.end())).toBe(
+      formatted(new Parser().parse(document))
+    );
+    expect(stream.position().offset).toBe(document.length);
+    expect(stream.position().buffered).toBe(0);
+  });
+
+  test('emits a record as soon as the next top-level record starts', () => {
+    const stream = new StreamParser();
+    const seen = [];
+    stream.on('link', (link) => seen.push(link.toString()));
+
+    expect(stream.write('first loves data\n')).toEqual([]);
+    expect(stream.write('s').map(String)).toEqual(['(first loves data)']);
+    expect(seen).toEqual(['(first loves data)']);
+  });
+
+  test('emits only complete records', () => {
+    const stream = new StreamParser();
+    const seen = [];
+    stream.on('link', (link) => seen.push(link));
+
+    for (const character of 'profile:\n  name Ada\n  role engineer\n') {
+      stream.write(character);
+    }
+    expect(seen).toEqual([]);
+
+    stream.write('n');
+    expect(formatted(seen)).toBe('(profile: (name Ada) (role engineer))');
+  });
+
+  test('does not split multiline quotes or parenthesized contexts', () => {
+    const stream = new StreamParser();
+    const seen = [];
+    stream.on('link', (link) => seen.push(link));
+
+    stream.write('"first\nsecond"\n(nested:\n  value one)\n');
+    expect(seen).toHaveLength(1);
+    stream.write('n');
+    expect(seen).toHaveLength(2);
+  });
+
+  test('accepts a final record without a newline', () => {
+    const stream = new StreamParser();
+    stream.write('only one record');
+    expect(formatted(stream.end())).toBe('(only one record)');
+  });
+
+  test('reports positions relative to the whole stream', () => {
+    const stream = new StreamParser();
+    stream.on('error', () => {});
+    stream.write('good link\nnext link\nb');
+
+    let caught;
+    try {
+      stream.end('ad: value: nope');
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(StreamParseError);
+    expect(caught.line).toBe(3);
+    expect(caught.offset).toBeGreaterThan('good link\nnext link\n'.length);
+  });
+
+  test('can avoid retaining output for bounded-memory event processing', () => {
+    const stream = new StreamParser({ collect: false });
+    const seen = [];
+    stream.on('link', (link) => seen.push(link.toString()));
+    stream.write('one link\nt');
+    expect(stream.drain()).toEqual([]);
+    expect(stream.end('wo link').map(String)).toEqual(['(two link)']);
+    expect(seen).toEqual(['(one link)', '(two link)']);
+  });
+
+  test('supports drain reset and bounded memory', () => {
+    const stream = new StreamParser();
+    stream.write('one link\nt');
+    expect(stream.drain().map(String)).toEqual(['(one link)']);
+    expect(stream.end('wo link').map(String)).toEqual(['(two link)']);
+
+    stream.reset().write('fresh record');
+    expect(stream.end().map(String)).toEqual(['(fresh record)']);
+
+    const bounded = new StreamParser({ maxBufferSize: 4 });
+    bounded.on('error', () => {});
+    expect(() => bounded.write('12345')).toThrow(RangeError);
+  });
+
+  test('provides lazy adapters', async () => {
+    expect(
+      [...StreamParser.parse(['one link\n', 'two link'])].map(String)
+    ).toEqual(['(one link)', '(two link)']);
+
+    async function* chunks() {
+      yield 'one link\n';
+      yield 'two link';
+    }
+    const links = [];
+    for await (const link of StreamParser.parseAsync(chunks())) {
+      links.push(link.toString());
+    }
+    expect(links).toEqual(['(one link)', '(two link)']);
+  });
+
+  test('limits only the unresolved record, not total stream size', () => {
+    const stream = new StreamParser({ maxBufferSize: 12, collect: false });
+    stream.on('error', () => {});
+    for (let index = 0; index < 100; index++) stream.write(`a${index}\n`);
+    expect(stream.end().map(String)).toEqual(['(a99)']);
+  });
+
+  test('rejects writes after finish', () => {
+    const stream = new StreamParser();
+    stream.end('one');
+    stream.on('error', () => {});
+    expect(() => stream.write('two')).toThrow('after end');
+  });
+
+  test('tracks the absolute stream position', () => {
+    const stream = new StreamParser();
+    stream.write('one\ntw');
+    expect(stream.position()).toEqual({
+      offset: 6,
+      line: 2,
+      column: 3,
+      buffered: 2,
+    });
+  });
+});