Skip to content

docs+gate: correct fluid plugins examples + teach the docs-honesty gate about CLI commands#14

Merged
fas89 merged 1 commit into
mainfrom
docs/cli-output-honesty-gate
Jun 27, 2026
Merged

docs+gate: correct fluid plugins examples + teach the docs-honesty gate about CLI commands#14
fas89 merged 1 commit into
mainfrom
docs/cli-output-honesty-gate

Conversation

@fas89

@fas89 fas89 commented Jun 27, 2026

Copy link
Copy Markdown
Contributor

What & why

Fixes two real fluid plugins-related doc inaccuracies and teaches the docs-honesty
gate about CLI-command-example drift (the class it was structurally blind to).

Doc corrections (verified against the real command)

  • plug-into-fluid-cli.md: the fluid plugins list example listed 4 providers
    under a (5) header — odps was missing. I ran the real command against a
    latest-main CLI venv: it prints aws / gcp / local / odps / snowflake. Fixed.
  • your-first-real-plugin.md: the comment claimed PluginMetadata identity
    "surfaces to fluid plugins list" — it does not. The command reads entry-point
    names + allow/block status only and never loads the plugin. Comment corrected to
    say these fields feed registry/marketplace tooling, not fluid plugins list.

Docs-honesty gate extension (the bonus)

  • test_documented_cli_commands_exist: every fluid <command> in a doc code fence
    must be a real CLI subcommand (argparse introspection). Runs only when the
    data-product-forge CLI is importable; skips with a clear reason in CLI-less
    SDK CI ("validate where feasible").
  • test_fluid_plugins_output_advertises_no_impossible_columns: feasible without
    the CLI — a documented fluid plugins block cannot advertise VERSION/AUTHOR/
    DESCRIPTION columns the command can't emit. Pins exactly this PR's drift class.

Borrow-before-build

Surveyed clitest / cram / markdown-clitest / cli-unit / mktestdocs (run-the-binary
doc testers) + the pytest argparse-introspection pattern. Adapted introspection;
diverged from clitest/cram — they need the fluid binary present, but this
zero-dependency SDK doesn't (and shouldn't) install the CLI in its CI.

Verification

  • Ran the real command (fluid plugins list on a latest-main CLI venv) to
    confirm the corrected output.
  • Proved the gate catches drift: injecting fluid totallyfakecmd fails the
    command check; injecting the old VERSION/AUTHOR/DESCRIPTION table fails the output
    guard — both green after revert.
  • 156 tests pass (+1 skip in CLI-less CI); ruff + black clean.
  • Security review: no findings — test-only, no eval/network/subprocess/file-write;
    build_parser introspection is first-party and runs only when the CLI is installed.

…te about CLI commands

The `fluid plugins list` example listed 4 providers under a "(5)" header (omitted
`odps`) — verified against the real command, which prints aws/gcp/local/odps/snowflake.
And your-first-real-plugin.md claimed PluginMetadata identity "surfaces to `fluid
plugins list`" — it does not (the command reads entry-point names + allow/block status
only and never loads the plugin). Both corrected.

Extends tests/unit/test_docs_honesty.py (previously blind to CLI-command-example drift,
which is how a fabricated table slipped through):
- test_documented_cli_commands_exist: asserts every `fluid <command>` in a doc code
  fence is a real CLI subcommand, via argparse introspection. Runs only when the
  data-product-forge CLI is importable; SKIPS with a clear reason in CLI-less SDK CI
  ("validate where feasible"). Borrowed the argparse-introspection pattern; diverged
  from clitest/cram (which run the binary) since this zero-dep SDK doesn't install it.
- test_fluid_plugins_output_advertises_no_impossible_columns: feasible WITHOUT the CLI
  — a documented `fluid plugins` block cannot advertise VERSION/AUTHOR/DESCRIPTION
  columns the command can't emit. Pins exactly the drift class this PR fixes.

Verified both checks catch injected regressions (fabricated command + the old
VERSION/AUTHOR/DESCRIPTION table) then go green. 156 tests pass (+1 skip in CLI-less CI).
@fas89
fas89 merged commit 9fcaa31 into main Jun 27, 2026
9 checks passed
@fas89
fas89 deleted the docs/cli-output-honesty-gate branch June 27, 2026 04:59
fas89 added a commit that referenced this pull request Jun 27, 2026
…not a provider (#15)

Cascade of forge-cli #298 (ODPS reclassified out of the provider registry).
PR #14 had added odps to the plug-into-fluid-cli.md 'fluid plugins list'
example under 'provider (5)'; ODPS (Open Data Product Standard) is a spec /
export format, not a cloud provider, and has now been de-registered, so the
real output is 'provider (4)': aws/gcp/local/snowflake. Verified against the
merged CLI.
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