links-notation 0.27.0 → 0.28.0

package/tests/BrowserBundle.test.js

@@ -0,0 +1,187 @@
+import { describe, expect, test } from 'bun:test';
+import { on, once } from 'node:events';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath, URL } from 'node:url';
+import { Emitter } from '../src/Emitter.js';
+import { Parser, StreamParser } from '../src/index.js';
+
+const source = fileURLToPath(new URL('../src/index.js', import.meta.url));
+const published = fileURLToPath(new URL('../dist/index.js', import.meta.url));
+
+// Bundlers such as esbuild (`--platform=browser`) cannot resolve Node built-ins
+// like `events`, so any bare import in the package graph breaks browser builds
+// unless consumers add a polyfill (issue #351). Bun's own browser target would
+// silently polyfill them, so this plugin fails on every bare import instead.
+const rejectBareImports = (imports) => ({
+  name: 'reject-bare-imports',
+  setup(build) {
+    build.onResolve({ filter: /^[^./]/ }, (args) => {
+      imports.push(`${args.path} (from ${args.importer})`);
+      return { path: args.path, external: true };
+    });
+  },
+});
+
+async function bundleForBrowser(entrypoint) {
+  const imports = [];
+  const result = await globalThis.Bun.build({
+    entrypoints: [entrypoint],
+    target: 'browser',
+    plugins: [rejectBareImports(imports)],
+  });
+  return { result, imports };
+}
+
+describe('browser bundling (issue #351)', () => {
+  test('the source entry point imports no Node built-ins or packages', async () => {
+    const { result, imports } = await bundleForBrowser(source);
+    expect(result.success).toBe(true);
+    expect(imports).toEqual([]);
+  });
+
+  test('the published dist entry point imports no Node built-ins or packages', async () => {
+    const { result, imports } = await bundleForBrowser(published);
+    expect(result.success).toBe(true);
+    expect(imports).toEqual([]);
+
+    const text = readFileSync(published, 'utf8');
+    expect(text).not.toMatch(/^\s*import\s[^;]*from\s*["'][^./]/m);
+    expect(text).not.toMatch(/\brequire\(\s*["']/);
+  });
+
+  test('the dist bundle parses and streams like the source', async () => {
+    const dist = await import(published);
+    const input = '(law: text)\nnext value';
+    expect(dist.formatLinks(new dist.Parser().parse(input))).toBe(
+      dist.formatLinks(new Parser().parse(input))
+    );
+
+    const stream = new dist.StreamParser();
+    const seen = [];
+    stream.on('link', (link) => seen.push(link.toString()));
+    stream.end(input);
+    expect(seen).toEqual(['(law: text)', '(next value)']);
+  });
+});
+
+describe('Emitter', () => {
+  test('calls listeners in order with the emitter as this', () => {
+    const emitter = new Emitter();
+    const calls = [];
+    emitter.on('event', function (value) {
+      calls.push(['first', value, this === emitter]);
+    });
+    emitter.addListener('event', (value) => calls.push(['second', value]));
+    emitter.prependListener('event', (value) => calls.push(['zeroth', value]));
+
+    expect(emitter.emit('event', 1)).toBe(true);
+    expect(calls).toEqual([
+      ['zeroth', 1],
+      ['first', 1, true],
+      ['second', 1],
+    ]);
+    expect(emitter.emit('missing')).toBe(false);
+  });
+
+  test('once listeners run a single time', () => {
+    const emitter = new Emitter();
+    const calls = [];
+    emitter.once('event', (value) => calls.push(`once ${value}`));
+    emitter.prependOnceListener('event', (value) => calls.push(`pre ${value}`));
+    emitter.emit('event', 1);
+    emitter.emit('event', 2);
+    expect(calls).toEqual(['pre 1', 'once 1']);
+    expect(emitter.listenerCount('event')).toBe(0);
+  });
+
+  test('off removes the latest registration, including once listeners', () => {
+    const emitter = new Emitter();
+    const calls = [];
+    const listener = (value) => calls.push(value);
+    emitter.on('event', listener);
+    emitter.on('event', listener);
+    emitter.off('event', listener);
+    emitter.emit('event', 'a');
+    emitter.removeListener('event', listener);
+    emitter.emit('event', 'b');
+    emitter.once('event', listener);
+    emitter.off('event', listener);
+    emitter.emit('event', 'c');
+    expect(calls).toEqual(['a']);
+    expect(emitter.eventNames()).toEqual([]);
+  });
+
+  test('listener changes during emit take effect on the next emit', () => {
+    const emitter = new Emitter();
+    const calls = [];
+    const second = () => calls.push('second');
+    emitter.on('event', () => {
+      calls.push('first');
+      emitter.off('event', second);
+      emitter.on('event', () => calls.push('added'));
+    });
+    emitter.on('event', second);
+    emitter.emit('event');
+    expect(calls).toEqual(['first', 'second']);
+  });
+
+  test('inspects and removes listeners', () => {
+    const emitter = new Emitter();
+    const listener = () => {};
+    emitter.on('a', listener).on('b', listener).on('b', listener);
+    expect(emitter.listeners('b')).toEqual([listener, listener]);
+    expect(emitter.listenerCount('b')).toBe(2);
+    expect(emitter.eventNames()).toEqual(['a', 'b']);
+    emitter.removeAllListeners('b');
+    expect(emitter.eventNames()).toEqual(['a']);
+    emitter.removeAllListeners();
+    expect(emitter.listenerCount('a')).toBe(0);
+  });
+
+  test('an unhandled error event throws like Node.js', () => {
+    const emitter = new Emitter();
+    const error = new Error('boom');
+    expect(() => emitter.emit('error', error)).toThrow(error);
+    expect(() => emitter.emit('error', 'text')).toThrow(
+      'Unhandled error. (text)'
+    );
+    emitter.on('error', () => {});
+    expect(emitter.emit('error', error)).toBe(true);
+  });
+
+  test('rejects listeners that are not functions', () => {
+    expect(() => new Emitter().on('event', 'nope')).toThrow(TypeError);
+  });
+
+  test('works with the Node.js events.once helper', async () => {
+    const stream = new StreamParser();
+    const ended = once(stream, 'end');
+    stream.end('a b');
+    const [links] = await ended;
+    expect(links.map(String)).toEqual(['(a b)']);
+  });
+
+  test('works with the Node.js events.on async iterator', async () => {
+    const stream = new StreamParser();
+    const controller = new globalThis.AbortController();
+    const links = on(stream, 'link', { signal: controller.signal });
+    globalThis.setTimeout(() => stream.end('a b\nc d'), 0);
+    const seen = [];
+    try {
+      for await (const [link] of links) {
+        seen.push(String(link));
+        if (seen.length === 2) controller.abort();
+      }
+    } catch (error) {
+      if (error.name !== 'AbortError') throw error;
+    }
+    expect(seen).toEqual(['(a b)', '(c d)']);
+    expect(stream.listenerCount('link')).toBe(0);
+    expect(stream.listenerCount('error')).toBe(0);
+  });
+
+  test('StreamParser still throws the stream error without a listener', () => {
+    const stream = new StreamParser();
+    expect(() => stream.write(1)).toThrow(TypeError);
+  });
+});

package/tests/Cst.test.js

@@ -0,0 +1,109 @@
+import { describe, expect, test } from 'bun:test';
+import { CstKind, CstNode, Parser } from '../src/index.js';
+
+const roundTrip = (input, options) =>
+  new Parser(options).parseCst(input).toString();
+
+describe('concrete syntax tree (issue #364)', () => {
+  test('is the default lossless view of a document', () => {
+    const input = "(t 1 '1')";
+    const cst = new Parser().parseCst(input);
+    expect(cst).toBeInstanceOf(CstNode);
+    expect(cst.kind).toBe(CstKind.DOCUMENT);
+    expect(cst.toString()).toBe(input);
+    expect(cst.toSExpression()).toBe(
+      '(document (line (group open_paren:"(" (line reference:"t" whitespace:" " reference:"1" whitespace:" " reference:"\'1\'") close_paren:")")))'
+    );
+  });
+
+  test('reference tokens carry their value and delimiter', () => {
+    const references = new Parser()
+      .parseCst("(a \"b c\" ~1{64} ''e''''f'')")
+      .tokens()
+      .filter((token) => token.kind === CstKind.REFERENCE);
+    expect(
+      references.map((token) => [token.text, token.value, token.quote])
+    ).toEqual([
+      ['a', 'a', null],
+      ['"b c"', 'b c', '"'],
+      ['~1{64}', 'd', null],
+      ["''e''''f''", "e''f", "'"],
+    ]);
+  });
+
+  test.each([
+    ['empty', ''],
+    ['only whitespace', ' \t '],
+    ['blank lines', '\n\n'],
+    ['CRLF and CR', 'a\r\nb\rc\r\n'],
+    ['tabs and trailing spaces', 'a\t b  \n'],
+    ['comments everywhere', '# head\na: b # tail\n  # inner\n  c\n# end'],
+    ['multiline quotes', '(note: "one\n  two\r\nthree")'],
+    ['nested groups over lines', '(a (b\n  (c d)\n) e)\n'],
+    ['indentation', 'root:\n  child:\n    leaf\n  tail'],
+    ['literals', '(~1{} ~1{e6a0b9})'],
+    ['comment marks inside quotes', '(\'#a\' "b # c" `#`)'],
+    ['unicode', '(根: café 🙂)\n'],
+  ])('recovers %s exactly', (_, input) => {
+    expect(roundTrip(input)).toBe(input);
+  });
+
+  test('without comment support, # is part of references', () => {
+    const input = 'a #b';
+    const cst = new Parser({ comments: false }).parseCst(input);
+    expect(cst.toString()).toBe(input);
+    expect(cst.tokens().map((token) => token.kind)).toEqual([
+      'reference',
+      'whitespace',
+      'reference',
+    ]);
+  });
+
+  test('a group belongs to the line it opens on', () => {
+    const cst = new Parser().parseCst('a (b\nc)\nd');
+    expect(cst.children.map((line) => line.toString())).toEqual([
+      'a (b\nc)\n',
+      'd',
+    ]);
+    const group = cst.children[0].children[2];
+    expect(group.kind).toBe(CstKind.GROUP);
+    expect(group.children.map((child) => child.kind)).toEqual([
+      'open_paren',
+      'line',
+      'line',
+      'close_paren',
+    ]);
+  });
+
+  test('reads versioned literals in linear time', () => {
+    // CodeQL js/polynomial-redos flagged the regular expression that used to
+    // find where a literal ends; the scanner that replaced it is one pass.
+    const input = [
+      `~1{${'61'.repeat(50000)}}`,
+      `~${'1'.repeat(50000)}x`,
+      '~1{61} '.repeat(20000),
+    ].join('\n');
+    const started = Date.now();
+    const cst = new Parser().parseCst(input);
+    expect(Date.now() - started).toBeLessThan(5000);
+    expect(cst.toString()).toBe(input);
+    expect(
+      new Parser()
+        .parseCst('(~1{64} ~{} ~a{b} ~1x)')
+        .tokens()
+        .filter((token) => token.kind === CstKind.REFERENCE)
+        .map((token) => [token.text, token.value])
+    ).toEqual([
+      ['~1{64}', 'd'],
+      ['~{}', '~{}'],
+      ['~a{b}', '~a{b}'],
+      ['~1x', '~1x'],
+    ]);
+  });
+
+  test('rejects what parse() rejects', () => {
+    expect(() => new Parser().parseCst('(a')).toThrow();
+    expect(() => new Parser().parseCst('a)')).toThrow();
+    expect(() => new Parser({ maxDepth: 1 }).parseCst('((a))')).toThrow();
+  });
+});

package/tests/SharedSyntaxParity.test.js

@@ -0,0 +1,47 @@
+import { readFileSync } from 'node:fs';
+import { URL } from 'node:url';
+import { expect, test } from 'bun:test';
+import { Parser, StreamParser } from '../src/index.js';
+
+const read = (name) =>
+  JSON.parse(
+    readFileSync(new URL(`../../parity/${name}`, import.meta.url), 'utf8')
+  );
+const syntaxFixtures = read('syntax-fixtures.json');
+const textFixtures = read('text-fixtures.json');
+const tree = (links) =>
+  links.map((link) => ({
+    id: link.id,
+    raw: link.rawId,
+    quote: link.quote,
+    values: tree(link.values),
+  }));
+
+test('shared syntax parity: raw references and concrete syntax trees', () => {
+  for (const fixture of syntaxFixtures) {
+    const parser = new Parser();
+    expect(tree(parser.parse(fixture.input)), fixture.id).toEqual(
+      fixture.links
+    );
+    const cst = parser.parseCst(fixture.input);
+    expect(cst.toSExpression(), fixture.id).toBe(fixture.cst);
+    expect(cst.toString(), fixture.id).toBe(fixture.input);
+    const stream = new StreamParser();
+    for (const character of fixture.input) stream.write(character);
+    expect(tree(stream.end()), fixture.id).toEqual(fixture.links);
+  }
+});
+
+test('every shared input is recovered exactly from its concrete syntax tree', () => {
+  for (const { id, input } of [...textFixtures, ...syntaxFixtures]) {
+    const cst = new Parser().parseCst(input);
+    expect(cst.toString(), id).toBe(input);
+    expect(
+      cst
+        .tokens()
+        .map((token) => token.text)
+        .join(''),
+      id
+    ).toBe(input);
+  }
+});

package/tests/SyntaxMetadata.test.js

@@ -0,0 +1,102 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  Link,
+  Parser,
+  StreamParser,
+  formatLinks,
+  referenceQuote,
+} from '../src/index.js';
+
+describe('syntax metadata on parsed links (issue #364)', () => {
+  test("1 and '1' are the same reference but keep how they were written", () => {
+    const [link] = new Parser().parse("(t 1 '1')");
+    const [, bare, quoted] = link.values;
+    expect(bare.id).toBe('1');
+    expect(quoted.id).toBe('1');
+    expect(bare.rawId).toBe('1');
+    expect(quoted.rawId).toBe("'1'");
+    expect(bare.quote).toBeNull();
+    expect(quoted.quote).toBe("'");
+    // Equality and formatting ignore the metadata.
+    expect(bare.equals(quoted)).toBe(true);
+    expect(link.format()).toBe('(t 1 1)');
+  });
+
+  test('records every quote kind and run length', () => {
+    const [link] = new Parser().parse('("a": \'b\' `c` ""d"" ~1{65} f)');
+    expect(link.rawId).toBe('"a"');
+    expect(link.quote).toBe('"');
+    expect(link.values.map((value) => [value.rawId, value.quote])).toEqual([
+      ["'b'", "'"],
+      ['`c`', '`'],
+      ['""d""', '"'],
+      ['~1{65}', null],
+      ['f', null],
+    ]);
+  });
+
+  test('keeps raw text from the source, not from comment stripping', () => {
+    const [link] = new Parser().parse("(a 'b # c') # d");
+    expect(link.values[1].rawId).toBe("'b # c'");
+  });
+
+  test('leaves links without written IDs without raw text', () => {
+    const [link] = new Parser().parse('(a b)');
+    expect(link.rawId).toBeNull();
+    expect(link.quote).toBeNull();
+    expect(new Link('x').rawId).toBeNull();
+    expect(new Link('x').quote).toBeNull();
+  });
+
+  test('does not change equality, formatting or serialization', () => {
+    const quoted = new Parser().parse("('a': 'b')");
+    const bare = new Parser().parse('(a: b)');
+    expect(quoted[0].equals(bare[0])).toBe(true);
+    expect(formatLinks(quoted)).toBe(formatLinks(bare));
+    expect(quoted[0].toString()).toBe(bare[0].toString());
+    expect(JSON.stringify(quoted)).toBe(JSON.stringify(bare));
+    expect(quoted).toEqual(bare);
+  });
+
+  test('AST mode (syntax: false) drops the metadata', () => {
+    const [link] = new Parser({ syntax: false }).parse("('a': 'b')");
+    expect(link.rawId).toBeNull();
+    expect(link.values[0].rawId).toBeNull();
+    expect(link.values[0].quote).toBeNull();
+    expect(link.equals(new Parser().parse("('a': 'b')")[0])).toBe(true);
+  });
+
+  test('parseGroups and StreamParser keep the metadata', () => {
+    const groups = new Parser().parseGroups('\'root\':\n  "child"');
+    expect(groups[0].element.rawId).toBe("'root'");
+    expect(groups[0].children[0].element.values[0].rawId).toBe('"child"');
+    const stream = new StreamParser();
+    stream.write("(a '");
+    stream.write("b')");
+    const [link] = stream.end();
+    expect(link.values[1].rawId).toBe("'b'");
+    expect(link.values[1].quote).toBe("'");
+  });
+
+  test('rawId can be set on links built in code and must be text or null', () => {
+    const link = new Link('a');
+    link.rawId = '"a"';
+    expect(link.quote).toBe('"');
+    link.rawId = null;
+    expect(link.quote).toBeNull();
+    expect(() => {
+      link.rawId = 1;
+    }).toThrow(TypeError);
+  });
+
+  test('referenceQuote reads the delimiter of one complete reference', () => {
+    expect(referenceQuote("'1'")).toBe("'");
+    expect(referenceQuote('""a b""')).toBe('"');
+    expect(referenceQuote('`x`')).toBe('`');
+    expect(referenceQuote('1')).toBeNull();
+    expect(referenceQuote('~1{31}')).toBeNull();
+    expect(referenceQuote("'unclosed")).toBeNull();
+    expect(referenceQuote("'a' b")).toBeNull();
+    expect(referenceQuote(null)).toBeNull();
+  });
+});