feat(cli): add bq-agent-sdk binding-validate + ontology-build --validate-binding flags (#105 PR 2b)

[caohy1988]

Implements #105 PR 2b per the working plan on #96: the user-facing CLI surface and docs. PR 2a (#109, merged) shipped the validator core + unit tests + a live integration test.

What's new in this PR

Standalone CLI: bq-agent-sdk binding-validate

bq-agent-sdk binding-validate \
  --project-id my-project \
  --ontology my.ontology.yaml \
  --binding my-bq-prod.binding.yaml \
  --location US \
  [--strict] \
  [--format json|text|table]

• Loads ontology + binding, builds a bigquery.Client, calls the validator, prints a structured JSON report on stdout.
• Failure-code values are emitted as lowercase strings (e.g. "missing_table"); the docs reference table shows both the Python FailureCode enum name and the JSON value.
• Warnings always print to stderr (one line each) so CI logs surface advisory drift even when stdout is consumed by a JSON-aware tool.
• Exit codes: 0 ok, 1 failure(s), 2 unexpected error (load failure, missing flags).

ontology-build integration flags

bq-agent-sdk ontology-build ... --validate-binding         # default mode
bq-agent-sdk ontology-build ... --validate-binding-strict  # strict mode

• When set, run the validator before phase 2 (extraction). On any failure, the build short-circuits before any AI.GENERATE call fires — authoring drift never costs tokens.
• Default-mode warnings print to stderr but don't block.
• Mutually exclusive; both incompatible with deprecated --spec-path (validator needs the unresolved Ontology + Binding pair).
• Helper _run_binding_preflight() centralizes the load + validate + print + exit logic.

Plus: --location on ontology-build

build_ontology_graph() has supported location since PR #108. The CLI was building without forwarding it. This PR threads it through.

Tests

14 new CLI tests, all pass (using patched validators — no live BQ; live coverage is in PR 2a's TestBindingValidationLive):

• TestBindingValidate (7 tests) — clean validation, failure payload, warnings to stderr (default mode does not flip exit), strict flag threading, missing-flag exit-2, load-failure exit-2, --location threaded to the BQ client.
• TestOntologyBuildValidateBindingFlag (7 tests):
  • test_validate_binding_short_circuits_on_failure_before_build — asserts build_ontology_graph is never called when validation fails. Extraction never starts; no AI.GENERATE tokens spent.
  • test_validate_binding_strict_short_circuits_on_nullable_keys
  • test_validate_binding_clean_proceeds_to_build
  • test_validate_binding_warnings_only_proceeds_to_build — asserts build_ontology_graph IS called when only warnings are present (default-mode advisory branch).
  • test_validate_binding_with_spec_path_rejected
  • test_both_flags_rejected (mutual exclusion)
  • test_location_threaded_through_orchestrator — --location=EU reaches build_ontology_graph.

256/256 tests pass across test_binding_validation.py, test_cli.py, test_ontology_orchestrator.py, test_ontology_materializer.py, test_resolved_spec.py (6 live tests skip without RUN_LIVE_BIGQUERY_TESTS=1).

Docs

New: docs/ontology/binding-validation.md — covers:

• When to run (binding authoring / CI gating / ontology-build).
• Standalone CLI examples (default + strict).
• ontology-build integration examples.
• Failure-code reference with both Python FailureCode enum names and JSON code values, plus a sample jq filter.
• CI usage pattern (GitHub Actions example).
• Python API example.

Updated: docs/ontology/ontology-build.md — new "BigQuery location" section covering --location and a "Pre-flight binding validation" section linking out to binding-validation.md.

Updated: docs/README.md — links binding-validation.md under "Ontology Reference."

Updated: CHANGELOG.md — [Unreleased] / Added entries for the standalone CLI, the two ontology-build flags, --location, and the Python API.

What's NOT in this PR

• Live integration test for the CLI subprocess flow. The validator's live coverage is in PR 2a (TestBindingValidationLive); the CLI tests here cover wiring + exit codes + flag threading + AI.GENERATE-not-called-on-failure comprehensively. A literal subprocess.run(['bq-agent-sdk', 'binding-validate', ...]) smoke test could land as a follow-up if anyone wants it.
• Refactor to share ontology+binding loading between _run_binding_preflight and _load_spec_from_args. Both currently load independently; small TOCTOU window. Worth a follow-up helper but not blocking 2b's scope.

Working plan position

After this lands, #76 (extracted-graph validator) is the next prereq for #75 C1 per the working plan.

[caohy1988]

Review fixes folded in (commit 1520ee2)

(1) Failure-code reference now uses lowercase JSON values. The CLI emits f.code.value (e.g. "missing_table"), not the enum attribute name ("MISSING_TABLE"). Docs previously listed the uppercase form, so users copying the table into jq filters would silently match nothing. The reference table now has two columns (Python FailureCode enum + JSON code value) with a sample jq filter using the lowercase form. Also added a one-paragraph note at the top of the failure-code section pointing this out.

(2) CHANGELOG entry added under [Unreleased]. Calls out the four public additions: bq-agent-sdk binding-validate, ontology-build --validate-binding[-strict], ontology-build --location, and the validate_binding_against_bigquery Python API.

(3) Warning-only path now tested. New test_validate_binding_warnings_only_proceeds_to_build patches the validator to return a BindingValidationReport(warnings=(...)) (no failures), runs ontology-build --validate-binding, and asserts:

• exit code 0
• build_ontology_graph is called (warnings don't short-circuit)
• WARN: key_column_nullable appears in the CLI output

This covers _run_binding_preflight()'s default-mode advisory branch, complementing the existing failure-short-circuit and clean-success tests.

(4) --location tests + docs.

• TestBindingValidate::test_location_threaded_to_bigquery_client — confirms binding-validate --location=EU constructs the BQ client with location='EU'.
• TestOntologyBuildValidateBindingFlag::test_location_threaded_through_orchestrator — confirms ontology-build --location=EU forwards to build_ontology_graph.
• docs/ontology/ontology-build.md gained a "BigQuery location" section covering --location, plus a "Pre-flight binding validation" section referencing binding-validation.md.

Verified locally: 256/256 tests pass (test_binding_validation.py, test_cli.py, test_ontology_orchestrator.py, test_ontology_materializer.py, test_resolved_spec.py). Autoformat clean.

Optional nit (deferred): _run_binding_preflight loads ontology + binding once for validation; _load_spec_from_args reloads them for resolve(). A small helper returning the pair once would close the small TOCTOU window, but acceptable as-is for PR 2b scope. Worth a follow-up if anyone wants it.

[caohy1988]

Rebased onto fresh main (PR 2a merged)

#109 (PR 2a) merged at upstream 8f8a36f. Rebased this branch with git rebase --onto upstream/main 6a14aa2 to drop the 6 PR 2a commits that are now on main, leaving only the 3 PR 2b commits:

828378d docs: avoid naming INFORMATION_SCHEMA as preflight mechanism (#105 PR 2b)
d4b1740 fix+test+docs: lowercase JSON codes, changelog, location + warning-only paths (#105 PR 2b)
7b032dd feat(cli): add bq-agent-sdk binding-validate + ontology-build flags (#105 PR 2b)

Force-pushed via --force-with-lease. The PR diff now shows only the CLI + docs additions.

Verified locally: 175/175 tests pass across test_binding_validation.py, test_cli.py, test_ontology_orchestrator.py (live integration tests skip without RUN_LIVE_BIGQUERY_TESTS=1).

PR body opening paragraph removed ("stacked on #109" note no longer applies).