Uh oh!
There was an error while loading. Please reload this page.
Document the language service, and the gap it leaves in Python - #3
Merged
Conversation
A capability page for `idf-language-service`, the answers an editor needs
about IDF text: which statement the cursor is in, what may be written here,
what this field means, where this name is declared, which characters a finding
is about. Reading a model answers none of them, because by the time a document
exists the text has been forgotten.
The page is language-neutral prose with the code in one language and an
explicit rendered absence in the other, which is the remedy Principle III
provides rather than an exception to Principle IV. It carries
`parity("idf-language-service")`, and that macro fails the site build when its
argument resolves to nothing, which is what makes the gap impossible to
publish as an empty panel. Verified by removing the id and watching the build
abort, then restoring it.
Python is `absent` with `absence_kind = "never"`, and the notice says so in
those terms: a permanent boundary, no issue tracking it, and a constitutional
amendment rather than a ledger edit to move it. The reason is on the page. The
answers are byte-offset arithmetic, and a second implementation of that
arithmetic is the drift surface the corpus is least able to police, since it
compares findings on (code, line, typeName) and never on a column. Two
implementations could disagree about a position for a long time with no gate
noticing. The editor extension needs no port either: its existing Python
server keeps serving Python source, and a second server serves IDF text.
parity.md and naming-map.md are regenerated at governance-2026.11. The parity
page had not been rendered since the ledger gained the capability, so the
notice linked to an anchor that did not exist and the tier was stated nowhere
the reader could reach. Both are generated artifacts, not hand edits.
The governance level moves to governance-2026.11. The conformance, docs and
library levels do not.
The two TypeScript snippets are checked by nothing in this repository, and
that is a gap rather than a decision. Every non-vendored snippet here is
Python, checked by pyright, and the only checked TypeScript tree is
docs/snippets/js/, which sync_js_artifacts.py compares byte for byte against
the pinned docs release and which is never hand-edited. Both files type-check
clean under strict against the live sources and are prettier-clean, proven by
hand rather than by a gate. Closing it properly means authoring them in
idfkit-js/docs-snippets/, publishing a docs artifact and bumping
[tool.idfkit.docs], which is a release cycle rather than an edit.Contributor
Docs preview for this PR is available at: Changed pages: |
Uh oh!
There was an error while loading. Please reload this page.
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
A capability page for
idf-language-service, the answers an editor needs about IDF text: which statement the cursor is in, what may be written here, what this field means, where this name is declared, which characters a finding is about. Reading a model answers none of them, because by the time a document exists the text has been forgotten.The page
Language-neutral prose with the code in one language and an explicit rendered absence in the other, which is the remedy Principle III provides rather than an exception to Principle IV. It follows the shape of
explanation/browser-simulation.md, the standing precedent.It carries
{{ parity("idf-language-service") }}, and that macro fails the site build when its argument resolves to nothing. That is what makes the gap impossible to publish as an empty panel, and it is verified rather than assumed: removing the id aborts the build with aBuildErrornaming the page and the id, and restoring it builds clean.Python is
absentwithabsence_kind = "never", and the notice says so in those terms: a permanent boundary, no issue tracking it, and a constitutional amendment rather than a ledger edit to move it. The reason is on the page. The answers are byte-offset arithmetic, and a second implementation of that arithmetic is the drift surface the corpus is least able to police, since it compares findings on(code, line, typeName)and never on a column. Two implementations could disagree about a position for a long time with no gate noticing. The editor extension needs no port either: its existing Python server keeps serving Python source, and a second server serves IDF text.Regenerated artifacts
parity.mdandnaming-map.mdare rendered atgovernance-2026.11. The parity page had not been regenerated since the ledger gained the capability, so the notice linked toexplanation/parity.md#idf-language-service, an anchor that did not exist, and the tier was stated nowhere the reader could reach. Both files are generated, not hand-edited: re-running the render scripts after this commit produces no diff.Levels
[tool.idfkit.governance]moves togovernance-2026.11. Theconformance,docsandlibrarylevels do not.What this PR does not close, and why
The two TypeScript snippets are checked by nothing in this repository, and that is a gap rather than a decision. Every non-vendored snippet here is Python, checked by pyright, and the only checked TypeScript tree is
docs/snippets/js/, whichsync_js_artifacts.pycompares byte for byte against the pinned docs release and which is never hand-edited. Both files type-check clean understrictagainst the live@idfkit/coreand@idfkit/languagesources and are prettier-clean, proven by hand rather than by a gate. Closing it properly means authoring them inidfkit-js/docs-snippets/, publishing adocs-2026.Nartifact, vendoring it, and bumping[tool.idfkit.docs], which is a release cycle rather than an edit.One of them is the worked protocol-translation example, and its whole content is translation: it contains no line or column computation of its own and splits no region it was given. That is the point of it. If a consumer finds itself counting commas, the service has failed.
Two pre-existing failures, neither caused by this branch
make checkis red.ruffreportsS310inscripts/sync_js_artifacts.py, a file this branch does not touch.make docs-testcannot pass in this environment. The strict build aborts with 107 warnings and all 107 are thesocialplugin reporting that cairosvg cannot load libcairo. libcairo is installed; macOS SIP stripsDYLD_*from the make and uv chain before the plugin sees it. None of the 107 name any file in this change. With that one plugin disabled the strict build exits 0 and the page renders correctly, with the parity link resolving and the absence statement naming the kind.check_page_kinds.pyandcheck_capability_declarations.pyboth pass.Separately, and worth flagging to whoever owns the library pin:
[tool.idfkit.library]is0.15.0, which carries neitherload_idf_with_diagnosticsnorParseResultnor the fivewrite_idfcontrols that pages already merged here document. A reader on the version the site itself declares would hit anImportErrorcopying those examples. That needs a library release plus auv lock, and is out of scope for this branch.