Skip to content

chore: remove the bindgen prototype - #386

Merged
David-Noble-at-work merged 1 commit into
developfrom
chore/remove-bindgen-prototype
Aug 12, 2026
Merged

David-Noble-at-work merged 1 commit into
developfrom
chore/remove-bindgen-prototype

Conversation

@David-Noble-at-work

Copy link
Copy Markdown
Contributor

Removes prototype/bindgen whole, per the ruling (2026-08-12) and docs/plans/remove-bindgen-prototype.md. Closes #215 — the learnings are preserved in a closing comment there, with this commit's SHA for retrieval.

Why

The prototype's own README documents the ceiling: AST extraction of cobra source yields syntax without semantics — ~6 of ~100 flags for run, no positional args, wrong invocation forms — so 144 generated commands each needed human refinement while 15 hand-written ones were production-ready. The successor is AI-driven authoring against vendor documentation (lore onboard today; the licensing draft's authoring-CAG strategically), plus the reflection-based codegen pipeline every provider now uses.

It was already dead by every mechanical measure

  • The extractor, its test, and cmd/main.go all carry //go:build ignore — the toolchain never compiles any of them
  • The extractor imports internal/bindgen, which does not exist
  • Nothing imports any package in the tree
  • go mod tidy had already dropped golang.org/x/tools — its only consumer is ignore-tagged

Effects

  • Audit remediation: nolint reasons, goast naming, plan status reconciliation, TODO triage #365 phase 1b-iii resolved by deletion — the two bare nolint directives in the extractor were dead (golangci-lint never loads ignore-tagged files); tree-wide bare directives 5 → 3, all 1b-iv/1b-v scope
  • Two audit-statement corrections recorded in the plan: the "no target path is lint-excluded" claim was false in effect here (a build tag excludes as thoroughly as config), and the gocognit live-finding count was 9, not 11
  • golang.org/x/text reclassifies direct → // indirect — a prototype file was its last direct importer; nothing leaves the graph, go.sum unchanged. (The plan originally predicted a diffless tidy; the commit script's guard caught the difference and the correction is recorded.)
  • devlore-test run fails on Windows: output streams default to /dev/stdout #379's two ignore-tagged /dev/stdout stragglers vanish; prototype/ stops needing special-casing in audits and per-GOOS sweeps

Verified before committing: go list reports no prototype/ package, zero bindgen references in Go source, exactly 3 bare nolint directives, go mod tidy converged. The suite loses one green package that nothing imports.

Closes #215

Ruling 2026-08-12: bindgen will not work well enough; remove it whole. Git
history keeps it — the rationale this repository recorded when PR #311 deleted
dead code.

The prototype generated Starlark bindings from cobra CLI source: an AST
extractor enumerated commands and flags (144 commands and 272 flags from
docker-cli v27.4.1 in its one recorded run, 2026-01-11), and a generator turned
the schema into receiver scaffolding. Its own README documents the ceiling that
ended it: AST extraction yields syntax without semantics — no positional
arguments, no valid flag combinations, wrong invocation forms — so every
generated command needed human refinement while fifteen hand-written ones were
production ready. The successor is AI-driven authoring against vendor
documentation: lore onboard today, the licensing draft's authoring-CAG
strategically, which gets the semantics extraction structurally cannot.

The tree was already dead by every mechanical measure, discovered when audit
phase 1b-iii went to decompose extractFromFunction: the extractor, its test,
and cmd/main.go all carry //go:build ignore; the extractor imports
internal/bindgen, which does not exist; nothing imports any of it; and go mod
tidy had already dropped golang.org/x/tools because its only consumer is
ignore-tagged. The two bare nolint directives in the extractor suppressed
nothing — golangci-lint never loads ignore-tagged files.

Phase 1b-iii of issue #365 is thereby resolved by deletion rather than
decomposition; bare nolint directives across the tree drop 5 -> 3, all of them
1b-iv/1b-v scope. Two audit-statement corrections ride in the plan: the claim
that no target path was excluded from the linter was false in effect for these
two functions (a build tag excludes as thoroughly as config, and the audit
never checked tags), and the repo-wide gocognit live-finding count was 9, not
11.

One more prediction fell to a guard during execution, and is recorded in the
plan: the verification bar said go mod tidy would be diffless, but
golang.org/x/text reclassifies from direct to indirect — a prototype file was
its last direct importer. Nothing leaves the graph; go.sum is unchanged; the
tidied go.mod rides here.

The learnings are preserved on issue #215, which this closes: the extraction
results, the README's comparison-table verdict, and this commit's SHA for
retrieval of any of it.

Verified before committing: no prototype package in go list, zero bindgen
references in Go source, exactly 3 bare nolint directives, go mod tidy
converged. The suite loses one green package (prototype/bindgen/internal) that
nothing imports.
Plan: docs/plans/remove-bindgen-prototype.md.
Issues: #215 (closed by this), #365 (phase 1b-iii)
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.

Reexamine bindgen prototype for CLI-wrapping providers

1 participant