feat(atc): resolve finding check categories from the check variant form template

Merged
TH
3d ago
+8665-4138

What

Maps ATC worklist findings to their check category (e.g. CI_PERFORMANCE, CI_SECURITY) through the check variant form template (GET /sap/bc/adt/atc/checkvariants/formtemplate?chkvName={name}).

Key discovery (verified against a live S/4 system): the worklist finding's checkId is a check-instance GUID — not the implementing class name the form template catalog lists. No form-template check carries the finding's checkTitle, the GUID-addressed check object 404s exactly like the class-name form, and the finding's own itemid URI 404s. The working bridge is the finding's ATC documentation page (the worklist atom:link): its header line names the check class (Appl. Comp. Check / Check Class / Message Code), which resolves through the form-template index.

  • adt-schemas: custom XSDs for the form template and its chkc, chko, chkoParameter, chkvcheck dependencies; regenerated schemas + flattened types (chkvFormTemplate)
  • adt-contracts: manual atc.checkvariants.formtemplate GET endpoint with contract and typed scenario tests
  • adt-fixtures: real sanitized form template fixture (live S/4 capture, customer-owned entries renamed to ZEXAMPLE_*) + synthetic mock-server catalog matching the mock worklist fixture
  • adt-atc: AtcFinding.checkCategory + documentationUri; parseCheckCategoryIndex, fetchCheckCategoryIndex, resolveCategoriesViaDocumentation (bounded 64 KiB, deduplicated per URI, best-effort — never fails a run); the atc command enriches findings after the worklist fetch; the GitLab Code Quality formatter emits check_id (stable implementing-class identity) and check_category; SARIF rules carry properties.category
  • adt-server: CanonicalAtcFinding.checkCategory with best-effort enrichment in the ATC run flow; REST/OpenAPI finding shape
  • adt-mcp: atc_run enriches findings with the same shared helpers

Design notes

  • Enrichment is best-effort by design: an unavailable form template or documentation page never fails the run; findings simply keep no category.
  • The direct index pass resolves findings whose checkId already matches a catalog implementing class; the documentation bridge covers the GUID case.
  • check_id in the GitLab formatter gives downstream consumers a stable rule identity that survives SAP check-title renames.

Validation

  • nx affected -t lint test build — green
  • adt-schemas scenario (15), adt-atc unit (23) including the documentation-bridge tests, adt-contracts, adt-server broker, adt-mcp integration suites all pass

Made with Cursor

Summary by cubic

Resolves ATC finding categories from the check variant’s form template, including findings with GUID checkId values by using their documentation pages to identify the implementing class. Category enrichment is best-effort and never fails a run.

What changed

  • Adds optional checkCategory and documentationUri fields to findings returned by the CLI, REST server, and MCP atc_run.
  • Adds typed support for the form-template endpoint and sanitized fixtures.
  • Includes categories in GitLab Code Quality and SARIF output, and the SAP-reported check_id in GitLab output.

Summary by Sourcery

Enrich ATC findings with their check categories across supported interfaces and reporting formats.

New Features:

  • Resolve ATC findings to check categories using check variant form templates, including GUID-based findings through their documentation pages.
  • Expose check categories across CLI, server, and MCP ATC results, with category metadata in GitLab Code Quality and SARIF outputs.
  • Add typed support for the ATC check variant form-template endpoint and its catalog data.

Enhancements:

  • Make category enrichment best-effort so unavailable catalogs or documentation never fail an ATC run.
  • Add stable check identifiers and documentation links to finding processing for downstream enrichment and reporting.

Documentation:

  • Document check category enrichment and exported helper APIs in the ATC package README.

Tests:

  • Add schema, contract, formatter, documentation-bridge, server broker, and MCP integration coverage for category resolution and graceful degradation.

Chores:

  • Add sanitized live and synthetic ATC form-template and documentation fixtures, together with generated schemas and types.

Summary by CodeRabbit

  • New Features
    • ATC findings now include check categories when available, matched from the selected check variant or resolved from finding documentation. Category lookup is best-effort, so runs still return findings if category information is unavailable.
    • GitLab Code Quality and SARIF reports now include category information when available.

Summary by Gitar

  • Documentation bridge:
    • Resolves GUID-based checkId findings via their ATC documentation page's check class
  • Stable check identity:
    • GitLab Code Quality output emits check_id alongside the category
  • Server and MCP:
    • atc_run and the server broker enrich findings with check categories, best-effort

This will update automatically on new commits.