Skip to content

openspec: propose CLI enum flag vocabulary - #250

Merged
jeremiepas merged 1 commit into
mainfrom
spec/cli-enum-flag-vocabulary
Nov 12, 2026
Merged

jeremiepas merged 1 commit into
mainfrom
spec/cli-enum-flag-vocabulary

Conversation

@jeremiepas

Copy link
Copy Markdown
Owner

Why

graphos --edge-density sparse is rejected while the same binary's --help documents sparse|normal|dense|maximum:

$ graphos --edge-density sparse .
option --edge-density: cannot parse value `sparse'
$ graphos --neo4j-push-mode full .
option --neo4j-push-mode: cannot parse value `full'
$ graphos --help | grep edge-density
  --edge-density ARG       Edge density: sparse|normal|dense|maximum (default: normal)

Five enum options are built with option auto, so the accepted vocabulary is the derived Read instance (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:

  1. It breaks an accepted spec. openspec/specs/12-neo4j-push/spec.md:7 requires Override: --neo4j-push-mode full|subgraph|community. The implementation has never conformed — this is a spec-conformance bug, not only a UX nit.
  2. The docs are wrong in the other direction too. docs/workflows/01-full-pipeline.md:209 and docs/workflows/09-merge.md:90 document --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 spec cli-enum-vocabulary.

The proposed fix is one token table per enum, from which the reader, the metavar and the help fragment are all derived, so an option can no longer document a token it rejects. Lowercase is the primary vocabulary — it already matches PushMode'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 numeric option auto sites (--threads -1, --port 99999, --resolution 0 all parse today) move to bounded readers with the range named in the error. Anti-drift is enforced by a registry-walking ParserSpec test rather than by review attention.

Deliberately out of scope

neo4jPushMode / mgPushMode in Domain/Config/Export.hs are parsed from graphos.yaml but never read by any consumer — UseCase/Export.hs uses the CLI value only. The shipped graphos.yaml also documents the key as push_mode while the FromJSON instance reads pushMode. Wiring config → push mode is a behaviour change and needs its own proposal; recorded at the end of proposal.md so it is not lost.

Verification

openspec validate cli-enum-flag-vocabulary --strict → valid; openspec status → 4/4 artifacts complete. Reproduction commands above were run against dist-newstyle/.../graphos.

…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.
@jeremiepas
jeremiepas merged commit 69390d8 into main Nov 12, 2026
5 checks passed
@jeremiepas
jeremiepas deleted the spec/cli-enum-flag-vocabulary branch November 12, 2026 12:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant