Classify GraphQL API surfaces and version scope evidence

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Classify Admin, Storefront, Customer Account, and ambiguous GraphQL operations independently using nearby source context.
+- Add explicit Shopify API version status and evidence applicability to CLI, Action, JSON, human, and SARIF reports.
+- Make standalone GraphQL documents without API client context UNKNOWN and restrict explicit configuration scans to the selected app root.
+
 ## 0.2.4
 
 - Add versioned 2026-10 access-scope evidence for payment instrument email, billing fee details, market relationships, and documented Events topics.

CONTRIBUTING.md

@@ -29,3 +29,5 @@ Before opening a pull request, also run `npm run coverage`, `npm audit --omit=de
 - Use privacy-safe fixtures with no credentials, tokens, or merchant data.
 
 See the [open issues](https://github.com/RexCode-Digital/shopify-scope-guard/issues) for current opportunities.
+
+These repositories use a solo-maintainer review model. Keep changes in pull requests and merge only after the required automated checks pass. CODEOWNERS may route review requests, but human approval is not a merge requirement.

README.md

@@ -92,16 +92,19 @@ See the [GitHub Action guide](docs/github-action.md).
 | --- | --- | --- |
 | `path` | Repository path to scan | `.` |
 | `config` | Shopify app TOML path | auto-discovered |
+| `api-version` | Admin GraphQL API version used for evidence applicability | `2026-10` |
 | `fail-on` | Minimum finding severity that fails the job | `high` |
 | `format` | Output format: `human`, `json`, or `sarif` | `human` |
 | `show-unmapped` | Show detailed unmapped patterns in human output | `false` |
 
 ### Action outputs
 
-`outcome`, `finding-count`, `high-count`, `medium-count`, `low-count`, `unknown-count`, `missing-scope-count`, `redundant-scope-count`, and `report`.
+`outcome`, `finding-count`, `high-count`, `medium-count`, `low-count`, `unknown-count`, `missing-scope-count`, `redundant-scope-count`, `api-version`, `api-version-status`, `evidence-version`, `evidence-applicable`, and `report`.
 
 The `report` output is a JSON report file in the runner temporary directory. SARIF format also writes `scope-guard.sarif` there. `outcome` reflects the selected `fail-on` policy.
 
+The example above pins v0.2.4, which does not accept the `api-version` Action input or expose the version and evidence outputs listed above. Those additions and the `--api-version` CLI option below are part of the unreleased changes here; npm v0.2.4 does not support that option.
+
 The Action is bundled and runs on GitHub's `node24` JavaScript Action runtime. Consumer jobs do not install Scope Guard dependencies separately.
 
 ## What it catches today
@@ -138,7 +141,7 @@ See the [evidence model](docs/evidence-model.md).
 ## CLI
 
 ```text
-shopify-scope-guard audit [--format human|json|sarif] [--fail-on ...]
+shopify-scope-guard audit [--api-version YYYY-MM] [--format human|json|sarif] [--fail-on ...]
 shopify-scope-guard rules
 shopify-scope-guard explain SG-SCOPE-001
 shopify-scope-guard --version
@@ -156,6 +159,9 @@ npx shopify-scope-guard audit --format json
 # SARIF for code-scanning workflows
 npx shopify-scope-guard audit --format sarif
 
+# Inspect scope evidence for the current release candidate
+npx shopify-scope-guard audit --api-version 2027-01 --format json
+
 # Fail when medium-or-higher findings are present
 npx shopify-scope-guard audit --fail-on medium
 
@@ -166,6 +172,8 @@ npx shopify-scope-guard explain SG-SCOPE-001
 
 The `--fail-on` option accepts `none`, `low`, `medium`, or `high`. A scan exits `1` when a finding meets the selected threshold, `0` when policy passes, and `2` for usage or scanner errors.
 
+Reports identify the selected version's status, latest stable version, current release candidate, and whether the bundled evidence applies. The current pack is verified for `2026-10`; selecting `2027-01` or another version outside that pack leaves Admin operations UNKNOWN rather than applying mismatched rules.
+
 See the [CLI reference](docs/cli.md).
 
 ## Configuration
@@ -179,7 +187,7 @@ The CLI supports:
 
 Auto-discovery prefers `shopify.app.toml`, otherwise a single named root configuration. Missing or ambiguous configurations fail explicitly. For nested apps use `audit --path apps/my-app --config shopify.app.production.toml`. Scans are bounded to 2,000 code files and 1 MiB per file; symlinks and bounded-out files appear in `skipped` and require manual review.
 
-Local fragments, inline fragments, and aliases are supported. Explicit Storefront signals stay outside Admin scope evidence. A standalone GraphQL document without a surface signal is assumed to be Admin; do not point an Admin audit at an unlabelled Storefront document set.
+Local fragments, inline fragments, and aliases are supported. Admin, Storefront, and Customer Account operations are classified per GraphQL document when a nearby client signal is clear. Storefront operations stay outside Admin scope evidence; Customer Account and ambiguous operations are reported as UNKNOWN. Standalone `.graphql` documents without client context are UNKNOWN until their API surface can be established.
 
 GraphQL 16 is retained for Node 20 support. Dependabot PR #3 remains open: GraphQL 17.0.2 officially requires Node 22/24/25/26 and is incompatible with Node 20. The minimum Node version will not be raised to satisfy that update.
 
@@ -222,6 +230,8 @@ Building or maintaining Shopify apps?
 - **[Shopify Upgrade Guard](https://github.com/RexCode-Digital/shopify-upgrade-guard)** — Catch documented Shopify API and platform upgrade risks before production migrations.
 - **[Shopify App Review Guard](https://github.com/RexCode-Digital/shopify-app-review-guard)** — Run deterministic preflight checks for Shopify App Store and production readiness.
 
+See the [coordinated workflow example](https://github.com/RexCode-Digital/shopify-app-changeguard/blob/main/docs/ecosystem-workflow.md) to run all four published Actions in one pull-request workflow.
+
 These are independent open-source tools and are not affiliated with Shopify.
 
 ## Contributing

action.yml

@@ -7,6 +7,7 @@ branding:
 inputs:
   path: { description: Repository path to scan, required: false, default: '.' }
   config: { description: Shopify app TOML path, required: false }
+  api-version: { description: Admin GraphQL API version selected for scope evidence, required: false, default: '2026-10' }
   fail-on: { description: Minimum finding severity that fails the job, required: false, default: high }
   format: { description: Output format human, json, or sarif, required: false, default: human }
   show-unmapped: { description: Include unsupported Shopify patterns, required: false, default: false }
@@ -17,6 +18,10 @@ outputs:
   medium-count: { description: Medium findings }
   low-count: { description: Low findings }
   unknown-count: { description: Unknown code patterns }
+  api-version: { description: Selected Admin GraphQL API version }
+  api-version-status: { description: Shopify API version status: stable, release-candidate, unstable, or unverified }
+  evidence-version: { description: Bundled evidence version }
+  evidence-applicable: { description: Whether the evidence pack applies to the selected Admin GraphQL API version }
   missing-scope-count: { description: Missing or optional-required scope findings }
   redundant-scope-count: { description: Redundant scope findings }
   report: { description: JSON report path }