docs: explain what query-report reports and where the query name comes from

[ogenstad]

What changed

Improves the help text for infrahubctl graphql query-report. No behavior change.

The command's description was "Run a GraphQL query through InfrahubGraphQLQueryReport and report its analysis." That names an internal server type and tells a user nothing about what the answer means or why they would want it.

It now:

• Leads with the consequence: artifact and generator definitions use the verdict to decide how much to regenerate when data changes. true means only the objects that changed are reprocessed, false means all of them are.
• States the rule that produces the verdict.
• Says on NAME that it is the query name declared under queries in .infrahub.yml.
• Records on --branch that the answer is branch-dependent, because uniqueness constraints come from the schema.

Kept as plain prose with no markdown links, since the same text renders in terminal --help.

Rendered output

Regenerated with uv run invoke docs-generate; docs/docs/infrahubctl/infrahubctl-graphql.mdx is included.

Related

The Infrahub docs are updated in a companion PR (opsmill/infrahub#10293), which documents the command on the canonical Single-target queries page. The concept this command reports on is called a single-target query in user documentation.

Testing

• uv run invoke format and uv run invoke lint-code - clean
• uv run invoke lint-docs - no findings on the changed pages (20 pre-existing spelling errors remain in generated sdk_ref/ files)

---

Summary by cubic

Clarifies the help text for infrahubctl graphql query-report so it explains the verdict, the uniqueness rule, and where the query name comes from. No behavior change; this makes it clear how artifact and generator definitions decide regeneration scope.

Review notes

• CLI help and docs now describe when a query targets unique nodes (filters on ids/hfid or fully satisfies one uniqueness constraint with provided values), how the verdict affects regeneration, that NAME comes from the queries section of .infrahub.yml, and that --branch can change the result because constraints are schema-based.
• Updates infrahub_sdk/ctl/graphql.py, docs/docs/infrahubctl/infrahubctl-graphql.mdx, and adds a changelog entry; no changes to command behavior or outputs.

^{Written for commit 0590568. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##           stable    #1253      +/-   ##
==========================================
+ Coverage   82.47%   82.54%   +0.06%     
==========================================
  Files         138      138              
  Lines       12186    12186              
  Branches     1833     1833              
==========================================
+ Hits        10051    10059       +8     
+ Misses       1572     1568       -4     
+ Partials      563      559       -4     

Flag	Coverage Δ
integration-tests	40.57% <ø> (+<0.01%)	⬆️
python-3.10	56.34% <ø> (+0.06%)	⬆️
python-3.11	56.34% <ø> (+0.06%)	⬆️
python-3.12	56.34% <ø> (+0.06%)	⬆️
python-3.13	56.32% <ø> (+0.06%)	⬆️
python-3.14	56.32% <ø> (+0.06%)	⬆️
python-filler-3.12	22.27% <ø> (+0.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
infrahub_sdk/ctl/graphql.py	91.05% <ø> (ø)

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.