feat: Add multi-reference support for unquoted multi-word IDs (#184)

[konard]

Summary

This PR implements issue #184: adds support for multi-word references without quotes.

Key Changes:

JavaScript & Python:

• Link.ids is now the primary storage (array of strings)
• Link.id is a computed property that:
  • Returns the single string for single-reference IDs
  • Throws an error for multi-reference IDs with message: "Use the 'ids' property instead of 'id'"
• Removed context-aware value parsing (out of scope per feedback)
• Values are parsed as separate references, not grouped by context

Rust & C#:

• Already support multi-word IDs (stored as joined strings)
• No breaking changes to existing API

Usage Example:

// Parse multi-reference
const result = parser.parse('(some example: value)');

// Access ids (always works)
console.log(result[0].ids); // ['some', 'example']

// Access id (throws for multi-refs)
console.log(result[0].id); // Error: "Use the 'ids' property instead of 'id'"

// Single refs still work with id
const single = parser.parse('(papa: value)');
console.log(single[0].id); // 'papa'
console.log(single[0].ids); // ['papa']

Breaking Changes:

For multi-reference IDs:

• Must use .ids property to access the array of reference parts
• The .id property will throw an error if the ID has multiple parts

Test Plan:

• All JS tests pass (207 tests)
• All Python tests pass (195 tests)
• All Rust tests pass (39 tests)
• All C# tests pass (191 tests)
• Prettier formatting check passes

🤖 Generated with Claude Code

Fixes #184

[konard]

🔍 Clarification Needed for Issue #184 Implementation

Hi @konard,

I've been analyzing the issue requirements and want to ensure I understand the expected behavior correctly before implementing:

Current Understanding

The issue mentions supporting "multi-references" with this example:

(some example: some example is a link)

And switching to arrays for both id and values.

Questions

1. Multi-word ID representation: Should the id field change from a single string to an array of strings?

   • Current: id = "some example" (quoted)
   • Proposed: id = ["some", "example"] (array of tokens)

2. Syntax clarification: In (some example: some example is a link):

   • Is some example before the colon the multi-reference ID (2 tokens)?
   • Is some example is a link after the colon the values (5 tokens)?
   • Expected parse result would be: Link(id=["some", "example"], values=[Ref("some"), Ref("example"), Ref("is"), Ref("a"), Ref("link")])?

3. Reference resolution: The issue mentions "if we have defined any multi references in the file, it means we should treat some example in any places as single multi-reference."

   • Does this mean we need a two-pass parser or context-aware parsing?
   • When some example appears later in the document, should it be recognized as a single reference ["some", "example"] rather than two separate references?

4. Backward compatibility: Should the existing quoted string syntax still be supported?

   • e.g., ('some example': value) should still work and produce id = "some example"?

5. Formatting output: When formatting back to string, should multi-word IDs:

   • Be output without quotes: some example: ...
   • Or with quotes for compatibility: 'some example': ...

Please let me know if my understanding is correct or if there's additional context I should consider.

Thanks!

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $18.471777 USD
• Calculated by Anthropic: $13.166545 USD
• Difference: $-5.305232 (-28.72%)
  📎 Log file uploaded as GitHub Gist (2606KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

🔄 Auto-restart 1/3

Detected uncommitted changes from previous run. Starting new session to review and commit them.

Uncommitted files:

M js/package-lock.json
?? experiments/grammar_backup.pegjs

---

Auto-restart will stop after changes are committed or after 2 more iterations. Please wait until working session will end and give your feedback.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $1.129287 USD
• Calculated by Anthropic: $0.791603 USD
• Difference: $-0.337684 (-29.90%)
  📎 Log file uploaded as GitHub Gist (2857KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

Single quoted reference is single quoted reference. Not multiple references. There also should be no such thing as Link( ... Values[Ref(...)]). We need to have only something like this: Link(Id=["reference1", "reference2"], Values=(Link((Id=["reference1"])).

Does this mean we need a two-pass parser or context-aware parsing?
When some example appears later in the document, should it be recognized as a single reference ["some", "example"] rather than two separate references?

I think it is out of the scope of the parser for now. If later we will have interpreter it should handle multi-references as he likes.

Backward compatibility

Quoted references are just single references nothing else, of course they should continue to work.

We can keep id as a string for backward compatibility, but it should use actual ids array, and if array has more than one value we should throw an error to use ids instead of id.

So we should make id a computable property out of ids.

If everything is clear now, please implement it.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2025-12-14T20:57:41.591Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $12.320612 USD
• Calculated by Anthropic: $8.268780 USD
• Difference: $-4.051832 (-32.89%)
  📎 Log file uploaded as GitHub Gist (1857KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.