links-notation 0.23.0 → 0.25.0

package/src/references.js

@@ -0,0 +1,63 @@
+import { QUOTES, readReference } from './quotes.js';
+import {
+  decodeReferenceLiteral,
+  formatReference,
+  hasReferenceLiteralPrefix,
+} from './ReferenceLiteral.js';
+
+/**
+ * Quote one reference. Minimal mode allows ordinary single-space prose on a
+ * document line; token formatting still quotes spaces by default.
+ * @param {string|null|undefined} reference
+ * @param {{minimal?: boolean}} options
+ * @returns {string}
+ */
+export function escapeReference(reference, { minimal = false } = {}) {
+  if (reference === null || reference === undefined) return '';
+  if (typeof reference !== 'string' || !reference.isWellFormed()) {
+    throw new TypeError('Reference must be well-formed Unicode text');
+  }
+  // Keep ordinary Link formatting identical to binary text formatting. The
+  // versioned literal also preserves empty strings and control characters in
+  // minimal document lines, including exact line endings.
+  if (!minimal || !reference || /[\u0000-\u001f\u007f]/u.test(reference)) {
+    return formatReference(reference);
+  }
+
+  const needsQuoting =
+    /(^| )~[0-9]+\{/.test(reference) ||
+    /[:()'"`]|(?! )[\p{White_Space}\ufeff]/u.test(reference) ||
+    /(^ | $| {2,}|(^| )#)/.test(reference);
+  if (!needsQuoting) return reference;
+
+  const singleQuotes = reference.split("'").length - 1;
+  const doubleQuotes = reference.split('"').length - 1;
+  let quote = singleQuotes <= doubleQuotes ? "'" : '"';
+
+  // The opening delimiter must be a run of exactly one quote. Choosing the
+  // other wrapper keeps a leading content quote from extending that run.
+  if (reference.startsWith(quote)) quote = quote === "'" ? '"' : "'";
+  return quote + reference.replaceAll(quote, quote + quote) + quote;
+}
+
+/**
+ * Decode a complete, escaped reference using the parser's delimiter rules.
+ * Plain text is returned unchanged. Parsed Link IDs are already decoded and
+ * should not be passed through this function a second time.
+ * @param {string} reference
+ * @returns {string}
+ */
+export function unescapeReference(reference) {
+  if (typeof reference !== 'string') {
+    throw new TypeError('Reference must be a string');
+  }
+  if (hasReferenceLiteralPrefix(reference)) {
+    return decodeReferenceLiteral(reference);
+  }
+  if (!QUOTES.includes(reference[0])) return reference;
+  const reading = readReference(reference, 0);
+  if (reading === null || reading.length !== reference.length) {
+    throw new SyntaxError('Expected one complete quoted reference');
+  }
+  return reading.value;
+}

package/tests/Binary.test.js

@@ -23,7 +23,9 @@ test('binary text quotes every Unicode grammar whitespace character', () => {
     '\u001f',
     '\ufeff',
   ]) {
-    expect(formatBinaryReference(text)).toBe("'" + text + "'");
+    expect(
+      new Parser().parse(`(root: ${formatBinaryReference(text)})`)
+    ).toEqual([new Link('root', [new Link(text)])]);
   }
 });
 

package/tests/EmptyReference.test.js

@@ -86,6 +86,6 @@ test('TestEmptyReferenceSurvivesARoundTrip', () => {
   }
 });
 
-test('TestEmptyReferenceIsWrittenAsADelimiterPair', () => {
-  expect(formatLinks(parser.parse('(a "" b)'))).toBe('(a "" b)');
+test('TestEmptyReferenceIsWrittenAsAVersionedLiteral', () => {
+  expect(formatLinks(parser.parse('(a "" b)'))).toBe('(a ~1{} b)');
 });

package/tests/IndentedDocument.test.js

@@ -0,0 +1,256 @@
+import { readFileSync } from 'node:fs';
+import { test, expect } from 'bun:test';
+import * as lino from '../src/index.js';
+
+const { Link, LinksGroup, Parser, ParseError } = lino;
+
+test('mixed quotes round-trip through the existing Link formatter', () => {
+  const text = 'He said "it\'s ready"';
+  const formatted = new Link(text).toString();
+  expect(new Parser().parse(formatted)[0].values[0].id).toBe(text);
+  expect(formatted).not.toContain("\\'");
+  expect(lino.escapeReference(text, { minimal: true })).toBe(
+    "'He said \"it''s ready\"'"
+  );
+});
+
+test('minimal escaping leaves ordinary prose unquoted', () => {
+  expect(
+    Link.escapeReference('What is your experience?', { minimal: true })
+  ).toBe('What is your experience?');
+  expect(Link.escapeReference('What is your experience?')).toBe(
+    "'What is your experience?'"
+  );
+});
+
+test('public groups preserve immediate children and deeper indentation', () => {
+  const groups = new Parser().parseGroups(
+    'What is your experience?\n  JavaScript\n  Python\n    Django\nOther question\n  Answer'
+  );
+  expect(groups).toHaveLength(2);
+  expect(groups[0]).toBeInstanceOf(LinksGroup);
+  expect(groups[0].element.values.map((value) => value.id)).toEqual([
+    'What',
+    'is',
+    'your',
+    'experience?',
+  ]);
+  expect(groups[0].children).toHaveLength(2);
+  expect(groups[0].children[1].children[0].element.values[0].id).toBe('Django');
+  expect(groups[1].children[0].element.values[0].id).toBe('Answer');
+});
+
+test('groups retain named and nested links and share parser diagnostics', () => {
+  const parser = new Parser();
+  const [root] = parser.parseGroups(
+    'root:\n  child: (one two)\n  branch\n    leaf'
+  );
+  expect(root.element.id).toBe('root');
+  expect(root.element.values).toEqual([]);
+  expect(root.children[0].element.toString()).toBe('(child: (one two))');
+  expect(root.children[1].children).toHaveLength(1);
+  expect(() => parser.parseGroups('root: child: value')).toThrow(ParseError);
+  expect(() =>
+    new Parser({ maxDepth: 0 }).parseGroups('root\n  child')
+  ).toThrow(ParseError);
+  expect(() => new Parser({ maxInputSize: 2 }).parseGroups('root')).toThrow(
+    'Input size exceeds'
+  );
+  expect(() => parser.parseGroups(null)).toThrow(TypeError);
+});
+
+test('parse the issue document without inspecting private path flags', () => {
+  const input = `What is your experience?
+  I have worked with JavaScript
+'Question with "quotes": and colon'
+  Answer
+`;
+  expect(lino.parseIndentedDocument(input)).toEqual(
+    new Map([
+      ['What is your experience?', 'I have worked with JavaScript'],
+      ['Question with "quotes": and colon', 'Answer'],
+    ])
+  );
+});
+
+test('multiple child lines have explicit array or joined-text behavior', () => {
+  const input = 'Skills\n  JavaScript\n  Python\nUnanswered\nSkills\n  Go';
+  expect(lino.parseIndentedDocument(input)).toEqual(
+    new Map([
+      ['Skills', ['JavaScript', 'Python', 'Go']],
+      ['Unanswered', []],
+    ])
+  );
+  expect(lino.parseIndentedDocument(input, { multipleValues: 'join' })).toEqual(
+    new Map([
+      ['Skills', 'JavaScript\nPython\nGo'],
+      ['Unanswered', []],
+    ])
+  );
+  expect(() =>
+    lino.parseIndentedDocument(input, { multipleValues: 'guess' })
+  ).toThrow(TypeError);
+});
+
+test('format the issue document with two-space indentation and a final newline', () => {
+  const entries = new Map([
+    ['What is your experience?', 'I have worked with JavaScript'],
+    ['Skills', ['JavaScript', 'Python']],
+  ]);
+  expect(lino.formatIndentedDocument(entries)).toBe(
+    'What is your experience?\n  I have worked with JavaScript\nSkills\n  JavaScript\n  Python\n'
+  );
+  expect(
+    lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+  ).toEqual(entries);
+  expect(lino.formatIndentedDocument(new Map())).toBe('');
+  expect(lino.parseIndentedDocument('')).toEqual(new Map());
+});
+
+test('empty text, exact whitespace, comments, quotes, and multiline text survive', () => {
+  const references = [
+    '',
+    ' ',
+    '  leading',
+    'trailing  ',
+    'two  spaces',
+    'a\tb',
+    '# question',
+    'text # literal',
+    'issue#333',
+    'Question: (details)',
+    '`backticks`',
+    '"double" and \'single\'',
+    '\'starts with both "quotes"',
+    "\"starts with both 'quotes'",
+    'ends with both \'"',
+    'repeated \'\'\' and """',
+    "literal \\n and \\'",
+    'line one\n  line two',
+    'carriage\rreturn',
+    'Windows\r\nline',
+    'Привет 🌍',
+  ];
+  for (const text of references) {
+    const escaped = lino.escapeReference(text, { minimal: true });
+    expect(lino.unescapeReference(escaped)).toBe(text);
+    expect(Link.unescapeReference(escaped)).toBe(text);
+    const entries = new Map([[text, text]]);
+    expect(
+      lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+    ).toEqual(entries);
+  }
+});
+
+test('unescaping uses the grammar and never decodes already parsed IDs again', () => {
+  expect(lino.unescapeReference('"He said ""hello"""')).toBe('He said "hello"');
+  expect(lino.unescapeReference("'it''s ready'")).toBe("it's ready");
+  expect(lino.unescapeReference('``text with ` inside``')).toBe(
+    'text with ` inside'
+  );
+  expect(lino.unescapeReference('plain text')).toBe('plain text');
+  expect(lino.unescapeReference('literal \\n')).toBe('literal \\n');
+  expect(() => lino.unescapeReference('"unfinished')).toThrow(SyntaxError);
+  expect(() => lino.unescapeReference('"value" extra')).toThrow(SyntaxError);
+  expect(lino.parseIndentedDocument('Question\n  "two \'\' quotes"')).toEqual(
+    new Map([['Question', "two '' quotes"]])
+  );
+});
+
+test('document helpers reject deeper or named value structures instead of losing data', () => {
+  expect(() =>
+    lino.parseIndentedDocument('Question\n  Answer\n    Detail')
+  ).toThrow(TypeError);
+  expect(() => lino.parseIndentedDocument('Question\n  answer: value')).toThrow(
+    TypeError
+  );
+  expect(() =>
+    lino.formatIndentedDocument(new Map([['Question', 42]]))
+  ).toThrow(TypeError);
+  expect(() => lino.formatIndentedDocument(new Map([[42, 'Answer']]))).toThrow(
+    TypeError
+  );
+  expect(() =>
+    lino.formatIndentedDocument(new Map([['Question', ['ok', null]]]))
+  ).toThrow(TypeError);
+});
+
+test('document parsing respects comments and existing parser options', () => {
+  expect(
+    lino.parseIndentedDocument('# comment\nQuestion\n  Answer # comment')
+  ).toEqual(new Map([['Question', 'Answer']]));
+  expect(
+    lino.parseIndentedDocument('# question\n  Answer', { comments: false })
+  ).toEqual(new Map([['# question', 'Answer']]));
+});
+
+test('one-element arrays normalize to strings and unanswered parents remain distinct', () => {
+  const entries = new Map([
+    ['One option', ['only']],
+    ['No options', []],
+    ['Empty answer', ''],
+  ]);
+  expect(
+    lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+  ).toEqual(
+    new Map([
+      ['One option', 'only'],
+      ['No options', []],
+      ['Empty answer', ''],
+    ])
+  );
+  expect(() =>
+    lino.formatIndentedDocument(new Map([['Question', Array(1)]]))
+  ).toThrow(TypeError);
+});
+
+test('document helpers preserve the shared Unicode reference corpus and reserved prefixes', () => {
+  const references = readFileSync(
+    new globalThis.URL(
+      '../../docs/protocol/reference-literals.txt',
+      import.meta.url
+    ),
+    'utf8'
+  )
+    .trim()
+    .split('\n')
+    .filter((line) => !line.startsWith('#'))
+    .map((hex) =>
+      hex === '-' ? '' : Buffer.from(hex, 'hex').toString('utf8')
+    );
+  for (const text of [
+    ...references,
+    '~1{61}',
+    '~2{00}',
+    '~1{invalid}',
+    'text ~1{61} after',
+    'text ~2{00}',
+    'text ~1{invalid}',
+  ]) {
+    expect(lino.escapeReference(text)).toBe(lino.formatBinaryReference(text));
+    expect(lino.unescapeReference(lino.escapeReference(text))).toBe(text);
+    expect(
+      lino.unescapeReference(lino.escapeReference(text, { minimal: true }))
+    ).toBe(text);
+    const entries = new Map([[text, text]]);
+    expect(
+      lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+    ).toEqual(entries);
+  }
+});
+
+test('unescaping decodes versioned literals without decoding parsed document IDs twice', () => {
+  expect(lino.unescapeReference('~1{}')).toBe('');
+  expect(Link.unescapeReference('~1{00}')).toBe('\0');
+  expect(lino.unescapeReference('~1{C3A9}')).toBe('é');
+  for (const literal of ['~2{61}', '~1{0}', '~1{gg}', '~1{ff}']) {
+    expect(() => lino.unescapeReference(literal)).toThrow();
+  }
+  const entries = new Map([['~1{61}', '~1{62}']]);
+  expect(
+    lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+  ).toEqual(entries);
+  expect(() => lino.escapeReference('\ud800', { minimal: true })).toThrow(
+    TypeError
+  );
+});

package/tests/ReferenceFidelity.test.js

@@ -0,0 +1,99 @@
+import { readFileSync } from 'node:fs';
+import { expect, test } from 'bun:test';
+import {
+  BinaryLinoCodec,
+  decodeReferenceLiteral,
+  encodeReferenceLiteral,
+  formatBinaryReference,
+  formatLinks,
+  FormatConfig,
+  Link,
+  Parser,
+  StreamParser,
+} from '../src/index.js';
+
+const references = readFileSync(
+  new globalThis.URL(
+    '../../docs/protocol/reference-literals.txt',
+    import.meta.url
+  ),
+  'utf8'
+)
+  .trim()
+  .split('\n')
+  .filter((line) => !line.startsWith('#'))
+  .map((hex) => (hex === '-' ? '' : Buffer.from(hex, 'hex').toString('utf8')));
+
+test('native reference fidelity', () => {
+  for (const id of references) {
+    const original = new Link(id, [
+      new Link(id),
+      new Link('nested', [new Link(id)]),
+    ]);
+    for (const lessParentheses of [
+      false,
+      true,
+      new FormatConfig({ maxInlineRefs: 1, preferInline: false }),
+    ]) {
+      const text = formatLinks([original], lessParentheses);
+      expect(new Parser().parse(text)).toEqual([original]);
+    }
+  }
+});
+
+test('reference literals at every chunk split', () => {
+  for (const id of references) {
+    expect(decodeReferenceLiteral(encodeReferenceLiteral(id))).toBe(id);
+    for (const literal of [
+      Link.escapeReference(id),
+      formatBinaryReference(id),
+      encodeReferenceLiteral(id),
+    ]) {
+      const text = `(root: ${literal})\n(${literal}: fixture)`;
+      const expected = [
+        new Link('root', [new Link(id)]),
+        new Link(id, [new Link('fixture')]),
+      ];
+      expect(new Parser().parse(text)).toEqual(expected);
+      for (let split = 0; split <= text.length; split++) {
+        const stream = new StreamParser();
+        stream.write(text.slice(0, split));
+        stream.write(text.slice(split));
+        expect(stream.end()).toEqual(expected);
+      }
+    }
+  }
+}, 10000);
+
+test('binary reference fidelity', () => {
+  const codec = new BinaryLinoCodec();
+  for (const id of references) {
+    const original = [new Link(id, [new Link(id)])];
+    const decoded = codec.decode(codec.encode(original));
+    expect(decoded).toEqual(original);
+    expect(codec.parseDocument(codec.formatDocument(decoded))).toEqual(
+      original
+    );
+  }
+});
+
+test('malformed reference literals are rejected', () => {
+  const invalid = readFileSync(
+    new globalThis.URL(
+      '../../docs/protocol/invalid-reference-literals.txt',
+      import.meta.url
+    ),
+    'utf8'
+  )
+    .trim()
+    .split('\n')
+    .filter((line) => !line.startsWith('#'));
+  for (const literal of invalid) {
+    expect(() => decodeReferenceLiteral(literal)).toThrow();
+    expect(() => new Parser().parse(literal)).toThrow();
+  }
+  expect(() => decodeReferenceLiteral('~1{61}\n')).toThrow();
+  expect(decodeReferenceLiteral('~1{C3A9}')).toBe('é');
+  expect(() => encodeReferenceLiteral('\ud800')).toThrow();
+  expect(() => Link.escapeReference('\ud800')).toThrow();
+});