Repository navigation
feat(conformance): add an anchor case kind for spec section 11 - #44
Merged
Merged
Conversation
A case of kind `anchor` holds a small repository: the current snapshot
under tree/, readable earlier blobs under blobs/, and optionally the
three sides of a merge that the runner performs with stock git. It
lists records and referrers with the outcome expected for each: the
status and reason, the anchored leaf, the span, the suggestion gate
with the written document, and every transclusion with its unit.
Authors write `{{blob:PATH}}` where an object id goes; the runner
replaces it with `git hash-object`'s id in a repository of the case's
object format. check_tree.py checks anchor cases for their files,
their controls, and that every asserted field is compared.
No anchor case is added: the cases come from an author who has not
read an implementation.
Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
check_tree.py now reports a placeholder target outside tree/, blobs/ and merge/ whose bytes equal a readable file's: ids are content-addressed, so such a file names a readable blob. Alterations now also turn a 0 or 1 index into a bool, and a test kills a not_integers that checks floats alone. The schema now requires a transclusion's leaf to be a paragraph and allows unmappable-offset only on RESOLVED or EDITED, as the README says. The self-test's good body follows that, and pins ten more rules. The README states the landing order of the anchor cases and the resolver, warns about content addressing, notes git's CRLF conflict markers, and lists what a tool writes among what a case cannot express. Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
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
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.
What this adds
A second case kind,
anchor, so that the conformance tree can state whatSPEC.md§11 resolves: comments, suggestions, replies and transclusions,across edits and stock
git merges. It adds the runner support, the treechecks and the documentation. It adds no anchor case: under the standing
rule (org contract §2.1), §11's cases come from an author who has not read an
implementation, and they are to be written from
SPEC.md, 0003 andconformance/cases/README.md, The kindanchor, which this PR adds.Landing order
The first anchor case turns the required
referencecheck red, because thereader has no
resolveuntil the resolver (#45). So: after this merges, theanchor cases are written blind from
main, on a branch and pull request oftheir own, and reviewed there. #45 is then rebased onto the cases branch, run
against them with no case changed, reviewed, and merged. That merge lands the
cases and the resolver together, and the cases' pull request closes as landed
through #45.
conformance/cases/README.md's anchor section states the same.The case shape
{{blob:PATH}}in any file is replaced bygit hash-object's id of the case file atPATH, in a repository of the case'sobject_format(sha1by default, orsha256). Authors write content,never hashes. A file outside
tree/,blobs/andmerge/can be namedbut is not readable, which is how
base-unavailableis set up."merge": {"policy.md": "clean" | "conflict"}runs kindkit'sgitmerge.merge(stock git, no configuration from the machine) over thethree sides; the working-tree result, markers and all, becomes the current
file, and git's outcome is asserted.
records: per record path,status(the six statuses of §11.6 with§11.10's reasons, plus
REPLY/#REF!(reply-to)for replies),leaf(the paired current leaf as a node path),
span(code point offsets inthat leaf's §11 text), and
suggestion(null, or the §11.7 gate:applywith a case file holding the exact written-back document, orstalewithnull/unmappable-offset).transclusions: per referrer, every transclusion paragraph in documentorder, each with its
leaf,status(RESOLVED,REFUSED(<reason>), or#REF!(<name>)) andunit(the target document's resolved path and whatthe name binds now).
controls: required when any outcome isREFUSED(...), as for aparserefusal.The implementation is handed
resolve(repo, queries)with the tree's textsand the readable blobs by id, so it needs no git (
run_cases.py'sdocstring).
Where it is checked
just conformand the mutation gate dispatchanchorcases throughrun_cases.py; an implementation withoutresolvefails each one.just tree(check_tree.py, stdlib only) checks each anchor case's rightanswer passes, an empty answer fails, every asserted field is compared
(one alteration at a time, an index or offset given as a float or a bool
included), its files are consistent (placeholder targets, merge sides,
written files, listed records and referrers, and no unreadable placeholder
target with a readable file's bytes, since ids are content-addressed), and
its controls.
conformancejob runsconformance/schema_selftest.py, which feedskindkit's own validator one valid synthetic anchor body and 44 broken
ones, each in a tree of its own, and requires each broken one to be
rejected. The empty-implementation step now defines an empty
resolvetoo, so it keeps failing every case once anchor cases exist.
tests/test_anchor_kind.pydrives the runner andcheck_tree.pyoversynthetic trees in a temporary directory, with a fake implementation that
checks the repository it is handed (ids recomputed with
hashlib, mergeresults, queries) and echoes a canned answer. Its bodies are not conformance
cases and say nothing about how an anchor resolves; flagging them here in
case they should go.
Gates
Break-checks
Each new check was broken and seen to fail, by a sweep run locally (not
committed) that hashes the file before and after each mutation and reports
BROKEN when a mutation does not land. Runner and
check_tree.pymutants runpytest tests/test_anchor_kind.py; schema mutants run the self-test.After review
Added in a second commit: the content-addressing lint above; bool
alterations and a test that kills a
not_integerschecking floats alone;the schema now requires a transclusion's leaf to be a paragraph and allows
unmappable-offsetonly onRESOLVEDorEDITED, as the README says (theself-test's good body no longer breaks that); ten more rules pinned in the
self-test; and the README now notes git's CRLF conflict markers and lists
re-anchoring, anchor creation and re-pinning among what a case cannot
express.
Notes for review
parsekind is unchanged: its schema branches are untouched (onlyacceptmoved from the top-levelrequiredinto aparsebranch), andjust conform,just treeandjust mutantsreport what they didbefore.
SPEC.md§10 says every case has the kindparse. That stays true untilthe first anchor case lands, which is the change that should update it.
under the org contract §3 and wants more than one review pass.