Repository navigation
openspec: propose CLI enum flag vocabulary - #250
Merged
Merged
Conversation
…neo4j-push-mode full) Five enum options are built with `option auto`, so the accepted vocabulary is the derived Read instance (Sparse, FullPush, MemgraphSubgraph) while --help, the README and the workflow docs all document lowercase tokens. Help text, docs and reader are three independent strings and they have drifted: $ graphos --edge-density sparse . option --edge-density: cannot parse value `sparse' $ graphos --neo4j-push-mode full . option --neo4j-push-mode: cannot parse value `full' The second one also violates accepted spec 12-neo4j-push, which requires `Override: --neo4j-push-mode full|subgraph|community`. Proposes one token table per enum from which reader, metavar and help fragment are all derived, lowercase as the primary vocabulary, constructor spellings kept as silent case-insensitive aliases so no current invocation breaks, bounded readers for the ~30 numeric `option auto` sites, and a registry-walking ParserSpec test so the drift fails the build. New capability spec: cli-enum-vocabulary.
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.
Why
graphos --edge-density sparseis rejected while the same binary's--helpdocumentssparse|normal|dense|maximum:Five enum options are built with
option auto, so the accepted vocabulary is the derivedReadinstance (Sparse,FullPush,MemgraphSubgraph). Help text, documentation and the reader are three independent strings in the source, and they have drifted.Two findings beyond the reported symptom:
openspec/specs/12-neo4j-push/spec.md:7requiresOverride: --neo4j-push-mode full|subgraph|community. The implementation has never conformed — this is a spec-conformance bug, not only a UX nit.docs/workflows/01-full-pipeline.md:209anddocs/workflows/09-merge.md:90document--edge-density N | 0.0, i.e. as a float.What this PR contains
Planning artifacts only — no source changes. New OpenSpec change
cli-enum-flag-vocabulary(proposal, design, tasks) plus one new capability speccli-enum-vocabulary.The proposed fix is one token table per enum, from which the reader, the
metavarand the help fragment are all derived, so an option can no longer document a token it rejects. Lowercase is the primary vocabulary — it already matchesPushMode's JSON instances,graphos.yaml, the workflow docs and spec 12. Constructor spellings stay as silent case-insensitive aliases, so no invocation accepted today is rejected after the change. The ~30 numericoption autosites (--threads -1,--port 99999,--resolution 0all parse today) move to bounded readers with the range named in the error. Anti-drift is enforced by a registry-walkingParserSpectest rather than by review attention.Deliberately out of scope
neo4jPushMode/mgPushModeinDomain/Config/Export.hsare parsed fromgraphos.yamlbut never read by any consumer —UseCase/Export.hsuses the CLI value only. The shippedgraphos.yamlalso documents the key aspush_modewhile theFromJSONinstance readspushMode. Wiring config → push mode is a behaviour change and needs its own proposal; recorded at the end ofproposal.mdso it is not lost.Verification
openspec validate cli-enum-flag-vocabulary --strict→ valid;openspec status→ 4/4 artifacts complete. Reproduction commands above were run againstdist-newstyle/.../graphos.