Apply readable Links Notation format to all languages and docs - #40
Conversation
Adding .gitkeep for PR creation (default mode). This file will be removed when the task is complete. Issue: #39
…anguage compact detection
…rget versions python/.ruff.toml replaced [tool.ruff] in pyproject.toml instead of adding to it, so the declared rule selection was dead and ruff ran its own default set. The stray file is gone, its isort setting moved in with the real package name, and the tool target versions now match requires-python.
…compact detection
…ures Add fixtures/readable-format/cases.json (39 hand-written cases from the format spec) and per-language suites that check each language encodes each value to exactly the shared text and decodes it back, so the four implementations verify each other rather than agreeing on a shared mistake. Also single-source the Python __version__ from installed distribution metadata so it never drifts from pyproject.toml.
JavaScript and Rust wrote (bool true) while Python and C# wrote (bool True), and each decoder understood only its own spelling, so a compact document written by one language decoded to the wrong boolean in another. Every language now writes the lowercase form and reads either spelling, so old documents keep working. Adds a regression suite in all four languages.
PR #38 changed only the Rust codec and no other language's CI ran, because each workflow filters itself by paths:. This adds .github/workflows/parity.yml (no paths: filter) and scripts/check-language-parity.mjs, which fails a pull request when one language's src/ changed without the others. An intentional single-language change opts out with [skip-parity] in the PR title or body. Covered by scripts/check-language-parity.test.mjs (7 cases).
…ing across all READMEs
…t works in the monorepo The check matched repo-root-relative git paths (rust/src/...) against subdirectory-relative patterns (^src/, ^scripts/, changelog.d/). In the monorepo this silently disabled fragment enforcement for real rust/src changes and falsely tripped on unrelated repo-root scripts/ changes. Adding --relative reports paths relative to the CI working-directory (rust/), so the existing patterns match correctly. Refs #39.
…udy, harden parity workflow - Remove tracked debugging leftovers: test_debug.py, python/test_encoder_fix.py, issue_details.json, pr_status.json, and the orphaned .github-workflows-test.yml (a workflow at repo root that GitHub Actions never ran). - Move PARSER_BUG.md into docs/case-studies/issue-39/data/ and record that the links-notation parser bug is fixed in 0.14.0 and already worked around here. - Add least-privilege permissions and a job timeout to the parity workflow, matching the hygiene in the language pipeline templates. Refs #39.
konard
changed the title
Working session summaryEverything is complete. Issue #39 is fully addressed in PR #40, now marked ready for review with all CI green. What was delivered against each requirement
Verification: All 6 CI runs green on the final commit This summary was automatically extracted from the AI working session output. |
🤖 Solution Draft LogThis log file contains the complete execution trace of the AI solution draft process. 💰 Cost: $24.729167📊 Context and tokens usage:Claude Opus 5: (6 sub-sessions)
Total: (11.5K new + 316.4K cache writes + 12.1M cache reads) input tokens, 147.9K output tokens, $12.963626 cost Claude Opus 4.8:
Total: (4.5K new + 236.4K cache writes + 12.7M cache reads) input tokens, 121.9K output tokens, $11.765542 cost 🤖 Models used:
📎 Log file uploaded as Gist (8840KB)Now working session is ended, feel free to review and add any feedback on the solution draft. |
🎉 Auto-mergedThis pull request has been automatically merged by hive-mind.
Auto-merged by hive-mind with --auto-merge flag |
1 participant
Summary
Closes #39. PR #38 made the readable indented Links Notation the default only in
Rust. This PR brings JavaScript, Python and C# to the same default, locks the
four implementations to byte-identical output, and removes the structural reason
the languages were able to drift apart in the first place.
What changed
1. Readable format is the default in all four languages
readablemodule in JS, Python and C# (Rust already had it);encode/decodenow produce the readable indented tree by default in every language.
(
fixtures/readable-format/cases.json, 39 cases) are executed by a harness inevery language and assert byte-identical encode and round-trip decode. This
is what makes "applied to all languages" machine-checked.
2. CI fails when languages drift (issue #39, requirement 2)
scripts/check-language-parity.mjs+.github/workflows/parity.ymlrun onevery PR with no
paths:filter, and fail unless 0 or all 4 languages'src/changed. An intentional single-language change opts out with[skip-parity]in the PR title/body. The gate has its own unit tests.3. Cross-language compact boolean interop fix
(bool true), Python/C# wrote(bool True), and each decoder onlyaccepted its own spelling — so a compact document written by one language decoded
to the wrong boolean in another. All encoders now write lowercase
true/false;all decoders compare case-insensitively. Regression tests added in every language.
4. Opt-in tracing / verbose mode (requirement 5)
LINO_CODEC_DEBUG(1/true/yes/on) or a code override(
set_debug_enabled/setDebugEnabled/CodecDebug.SetEnabled/debug::set_debug_enabled) enables stderr tracing in all four languages. Off bydefault.
5. Docs (requirement 1)
(base64 "…")marker,readable-vs-compact "How It Works", cycle/identity rule, and a Debugging section.
6. Deep case study (requirement 4)
docs/case-studies/issue-39/README.mdreconstructs the timeline, enumerates allseven requirements, gives per-requirement root cause + solution, compares the four
pipeline templates file-tree (requirement 3), and surveys the reused components.
Raw data (issue/PR JSON, CI logs, the parser-bug note) is under
docs/case-studies/issue-39/data/.7. Related-issue findings (requirement 6)
links-notation(id: …)parser bug — reproduced on 0.11.2, already fixedupstream in 0.14.0, and already worked around by the codec; documented in
docs/case-studies/issue-39/data/links-notation-parser-bug.md. Recommendedfollow-up (bump the Python/JS pins to 0.14.0) is noted but out of scope for this
format-focused PR.
CI hygiene from the templates (requirement 3)
permissions,timeout-minutesandconcurrencyon the parity workflow. The templates'security.yml(CodeQL + dependency-review) and
links.ymlare documented as recommendedfollow-ups in the case study — not merged here because they need repository
settings that would risk red first-run CI.
Release fragments
One coordinated
minorrelease fragment/changeset per language (js.changeset,csharp
.changeset, python + rustchangelog.d).Verification
All local CI green: Python (ruff/mypy, 162 tests), JS (
npm run check, 244 tests),Rust (fmt/clippy, 17+3 tests, 7 doctests, script tests, example), C# (format/build
/warnaserror, 171 tests), the 39 shared fixtures in every language, and theparity gate.