Skip to content

correct five stale claims in the docs and package comments #662

Description

@haribo

Why

Five statements in the docs and package comments describe a shellf that no longer exists. Each
verified against the current tree.

where says actually
docs/language.md:3-4 "One shipped construct has no chapter yet — as <user>" no chapter for on, parallel, override def, or the inventory syntax either (grep '^## ' docs/language.md)
docs/language.md:28 a def translates a ShellResult "via when/tags" when is not a keyword — zero occurrences in internal/lang
docs/design/inventory.md:16 address | yes | network endpoint not required for local: "true" (README.md:112). local and interpreter are absent from the table although both are host fields (internal/inventory/inventory.go:17-18)
internal/inventory/inventory.go:1-3 "Connection coordinates only — no business variables. Built in Go for now; a parsed shellf-language inventory comes later" both clauses false: Vars map[string]string at :19, and the inventory is parsed in the shellf language at internal/lang/parser.go:361
internal/std/postgres/postgres.shellf:3 "Only these two" four defs in the file. Worse, :5 argues that a postgres.config "would also inherit the versioned-path problem (#546), unresolved" — 130 lines above the postgres.config that resolves it with pg_conftool

docs/design/inventory.md:63 does carry a > **Superseded.** note, but it covers only the
free-form-variables point. The address/local/interpreter row is untouched by it — worth
saying, because an earlier audit in #642 read that note as covering the file and it does not.

Not a defect, listed so it is not re-raised

docs/dogfood.md:99"A plan cannot read another host's inventory entry" — is superseded by
ADR-0054. It stays: dogfood.md is a dated report of what a deployment could not express,
and history is allowed to describe a world the code has left (ADR-0001). A one-line forward
pointer to ADR-0054 is welcome; rewriting the finding is not.

Build

Correct the five. postgres.shellf's header is the one to think about rather than patch: it
argues a decision that the file itself has since reversed, so it needs rewriting, not a count
fix.

language.md is the largest: the missing chapters are real work, and the honest first move is
to make the header say what is missing instead of understating it. Writing the chapters can be
its own issue — but a spec that claims completeness it does not have is worse than one that
lists its holes.

Validation

  • grep -n 'when' docs/language.md — no occurrence presents it as a construct.
  • docs/language.md's header names every shipped construct that has no chapter, checked
    against grep '^## ' docs/language.md and the plan grammar in internal/lang/parser.go.
  • docs/design/inventory.md's host table lists local and interpreter, and address is not
    marked required unconditionally.
  • internal/inventory/inventory.go's package comment is true of the package as it is.
  • grep -c '^def ' internal/std/postgres/postgres.shellf agrees with its header.

Out of scope

Writing the missing language.md chapters. Naming the gap is this issue; filling it is
another, and pretending otherwise is how this one never closes.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    type: docsdocumentation change

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions