feat(docs): truth-sync intentional syntax contracts and UFCS docs#126
Merged
Conversation
…e UFCS dot-call DD-063 Rec 2. The agent-facing docs had drifted from the implementation — agents were being steered away from valid code by stale rules. This locks every behavioral claim with a test so the docs can never silently drift again. Tests: - tests/doc_claims_tests.rs: 32 tests, one per CLAUDE.md Critical Syntax Rule, asserting on error codes (E002/E005/E006/E007) and stable fragments. A failure means the language changed — update the docs in the same PR. Doc corrections (CLAUDE.md, CODEX.md, .github/copilot-instructions.md — all three carried the identical stale claims): - Rule 3: dot-call is UFCS sugar (x.f(a) == f(x, a)), not "WRONG". Documents the real gaps: parens disambiguate call vs property/key read; closures stored in map values are not dot-callable. - Rule 5: semicolons parse fine and lint-warn — they do not "corrupt parser state". - Rule 8: mut is enforced for indexed mutation only; plain rebinding currently succeeds without mut (documented, with a test locking the actual behavior). - Rule 10: module-level map literals work now; replaced in place (numbering kept stable) with the map-closure UFCS caveat. - Rule 11: the for..in-on-string skip emits a warning; it is not silent. UFCS support: - collect_used_names: dot-call method names now count as import usage, so an import used only via s.trim() is no longer flagged unused_import. - Method-call miss (E007) now suggests a near-match free function, so dot-call typos like 5.doubl() get a "did you mean" hint. - docs/AI_AGENT_GUIDE.md + syntax.toml document UFCS as first-class sugar. IAL honesty: - ial.toml gains a status field for the Sql (not implemented) and InvariantCheck (partial) primitives; generate_ial_markdown renders a Status column. IAL_REFERENCE no longer advertises capabilities that do not exist.
Contributor
Greptile SummaryThis PR updates the agent-facing syntax and IAL docs to match current language behavior. It changes:
Confidence Score: 5/5This looks safe to merge.
Reviews (4): Last reviewed commit: "docs: mark incomplete IAL primitives in ..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
…sses The method-call E007 suggestion drew from every environment binding, so a nearby non-callable variable could be suggested as the fix for a dot-call typo (5.doubl() -> a variable that still can't be called). New Environment::function_names() filters to Function/NativeFunction bindings; the suggestion now only ever names something callable.
larimonious
changed the title
Contributor
Author
|
Addressed Greptile’s IAL status issue in |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements a narrowed DD-063 Rec 2 slice: truth-sync the stale agent-facing syntax docs, embrace UFCS dot-call as intentional sugar, and add tests only for syntax contracts we actually want to treat as stable.
After review, this PR deliberately does not lock every current CLAUDE.md behavior. Current-but-questionable behavior should remain available for language improvement, not be fossilized because a test happened to observe it.
What this keeps
Intentional syntax contract tests
tests/doc_claims_tests.rshas 8 focused tests instead of the earlier broad snapshot.mapkeyword#{expr}interpolation works${expr}is diagnosed with a repair hintotherwiserecovery blocks must diverge{{expr}}Doc corrections
CLAUDE.md,CODEX.md, and.github/copilot-instructions.mdnow describe actual behavior instead of stale rules:mutis currently partial: indexed mutation requires it, plain reassignment does notfor..inon strings warns instead of failing silentlydocs/AI_AGENT_GUIDE.mdand generated syntax docs document UFCS as first-class sugar.Small code/doc fixes required by review
collect_used_namescounts dot-call method names as function usage, so imports used only through UFCS (" hi ".trim()) are not incorrectly reported asunused_import.IAL_REFERENCE.mdnow includes a generated primitive status column so agent-facing docs do not present stubs as implemented:Sql:Not implementedInvariantCheck:Resolver marker only; direct execution fails unless expandedWhat was removed from this PR
Removed tests that locked behavior we may want to reconsider:
mutsemanticsrange()absenceAlso removed the optional dot-call typo suggestion work. That belongs in a follow-up diagnostic PR, not this lighter syntax-doc slice.
Test plan
cargo fmt --checkcargo build --profile dev-release --lockedcargo test --test doc_claims_tests./target/dev-release/ntnt docs --generategit diff --checkNotes
This PR’s invariant is now: agent-facing docs must match implementation for intentional syntax contracts. It is not: “every current behavior is forever.”