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

packages/adt-atc/README.md

@@ -82,6 +82,9 @@ const result: AtcResult = {
       objectType: 'CLAS',
       objectName: 'ZCL_MY_CLASS',
       location: '/sap/bc/adt/oo/classes/zcl_my_class/source/main#start=10,0',
+      // Optional: resolved by the atc command from the run's check variant
+      // form template (check categories are best-effort enrichment)
+      checkCategory: 'CI_PERFORMANCE',
     },
   ],
 };
@@ -90,6 +93,40 @@ await outputSarifReport(result, 'atc-results.sarif');
 await outputGitLabCodeQuality(result, 'gl-code-quality.json');
 ```
 
+## Check Categories
+
+Each finding can carry a `checkCategory` (e.g., `CI_PERFORMANCE`,
+`CI_SECURITY`): the name of the ATC check category its check is assigned
+to. The `atc` command resolves it automatically from the run's check
+variant form template (`GET /sap/bc/adt/atc/checkvariants/formtemplate`)
+by mapping the finding's `checkId` (the check's implementing class name)
+to the category that contains it. The enrichment is best-effort: when
+the form template is unavailable, or the check is outside its catalog,
+findings simply carry no category and the run still succeeds.
+
+The enrichment helpers are exported for reuse:
+
+```typescript
+import {
+  parseCheckCategoryIndex,
+  fetchCheckCategoryIndex,
+  enrichResultWithCategories,
+} from '@abapify/adt-atc';
+
+// Build the checkId -> category name index from a parsed form template
+const index = parseCheckCategoryIndex(formTemplateDocument);
+
+// Or fetch it through an ADT client (never throws)
+const fetched = await fetchCheckCategoryIndex(client, 'DEFAULT');
+
+// Enrich a result in place
+enrichResultWithCategories(result, index);
+```
+
+The GitLab Code Quality formatter emits the category as `check_category`
+per finding; the SARIF formatter sets it on each rule's
+`properties.category`.
+
 ## Output Formats
 
 ### Console (default)

packages/adt-atc/src/check-categories.ts

@@ -0,0 +1,188 @@
+/**
+ * Check Category Enrichment
+ *
+ * Resolves ATC 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}).
+ *
+ * The form template is the check catalog of the run's check variant: every
+ * available check category lists its checks, and each check carries its
+ * implementing class. When a finding's checkId matches a catalog
+ * implementing class, the index resolves it directly. Live worklist
+ * checkIds are check-instance GUIDs (observed on a live S/4 system,
+ * 2026-10-22); those resolve through the documentation bridge in
+ * ./documentation-bridge.ts.
+ *
+ * Enrichment is best-effort by design: without the form template, or for a
+ * checkId outside the catalog, findings keep no category and the run still
+ * succeeds.
+ */
+
+/**
+ * Structural shape of the parsed check variant form template document
+ * (GET /sap/bc/adt/atc/checkvariants/formtemplate).
+ *
+ * Only the fields needed for the checkId -> category index are declared.
+ */
+export interface FormTemplateDocument {
+  formTemplate?: {
+    availableCheckCategories?: {
+      availableCheckCategory?: FormTemplateCategoryEntry[];
+    };
+  };
+}
+
+/** One available check category with the checks it contains. */
+export interface FormTemplateCategoryEntry {
+  checkCategoryObject?: {
+    /** Category name (the enrichment key, e.g., 'CI_PERFORMANCE') */
+    name?: string;
+    /** Category display title (e.g., 'Performance') */
+    description?: string;
+  };
+  check?: FormTemplateCheckEntry[];
+}
+
+/** One check entry of a category. */
+export interface FormTemplateCheckEntry {
+  checkObject?: {
+    /** Check name (e.g., 'CI_ANALYZE_WHERE') */
+    name?: string;
+    content?: {
+      /** The check's category assignment (the category name) */
+      category?: { name?: string };
+      /**
+       * Implementing class of the check (e.g., 'CL_CI_TEST_SELECT_TAW_A').
+       * Worklist findings carry a check-instance GUID instead; the
+       * documentation bridge resolves that GUID to this class name.
+       */
+      implementingClass?: { name?: string };
+    };
+  };
+}
+
+/**
+ * Build a checkId -> check category name index from a parsed check variant
+ * form template document.
+ *
+ * The checkId key is the implementing class name; the value is the category
+ * object name (a stable key like 'CI_PERFORMANCE', not the display title).
+ *
+ * @param doc - Parsed form template document (nullable for convenience)
+ * @returns Map of checkId -> category name; empty when the document is
+ *   missing or malformed
+ */
+export function parseCheckCategoryIndex(
+  doc: FormTemplateDocument | null | undefined,
+): Map<string, string> {
+  const index = new Map<string, string>();
+  const categories =
+    doc?.formTemplate?.availableCheckCategories?.availableCheckCategory ?? [];
+  for (const category of categories) {
+    collectCategoryChecks(category, index);
+  }
+  return index;
+}
+
+/** Index every check of one category under the category's name. */
+function collectCategoryChecks(
+  category: FormTemplateCategoryEntry,
+  index: Map<string, string>,
+): void {
+  const categoryName = category.checkCategoryObject?.name;
+  if (!categoryName) return;
+  const checkIds = (category.check ?? [])
+    .map((check) => check.checkObject?.content?.implementingClass?.name)
+    .filter((checkId): checkId is string => !!checkId);
+  for (const checkId of checkIds) {
+    index.set(checkId, categoryName);
+  }
+}
+
+/** Structural client surface needed to fetch a form template. */
+export interface FormTemplateClient {
+  adt: {
+    atc: {
+      checkvariants: {
+        /** GET /sap/bc/adt/atc/checkvariants/formtemplate{?chkvName} */
+        formtemplate: (params?: {
+          chkvName?: string;
+        }) => Promise<FormTemplateDocument>;
+      };
+    };
+  };
+}
+
+/**
+ * Fetch the check variant form template and build the checkId -> category
+ * name index for a run.
+ *
+ * Best-effort: any error (network, 404, malformed document) is swallowed
+ * and reported through the optional logger so a failed enrichment never
+ * fails the ATC run itself.
+ *
+ * @param client - ADT client with the checkvariants.formtemplate surface
+ * @param checkVariant - The check variant name of the run (e.g., 'DEFAULT')
+ * @param logger - Optional CLI logger for diagnostics
+ * @returns checkId -> category name index; empty when unavailable
+ */
+export async function fetchCheckCategoryIndex(
+  client: FormTemplateClient,
+  checkVariant: string,
+  logger?: {
+    warn: (message: string) => void;
+    info?: (message: string) => void;
+  },
+): Promise<Map<string, string>> {
+  try {
+    const doc = await client.adt.atc.checkvariants.formtemplate({
+      chkvName: checkVariant,
+    });
+    return parseCheckCategoryIndex(doc);
+  } catch (error) {
+    logger?.warn?.(
+      `⚠️ Check category enrichment unavailable: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    return new Map();
+  }
+}
+
+/**
+ * Enrich findings with their check category in place.
+ *
+ * Generic over any finding shape carrying a checkId (and an optional
+ * checkCategory field), so both the CLI plugin's AtcFinding and other
+ * canonical finding types can be enriched with the same index.
+ *
+ * @param findings - Findings to enrich (mutated in place)
+ * @param index - checkId -> category name index
+ * @returns Number of findings that received a category
+ */
+export function enrichFindingsWithCategories<
+  T extends { checkId: string; checkCategory?: string },
+>(findings: T[], index: Map<string, string>): number {
+  let enriched = 0;
+  for (const finding of findings) {
+    const checkCategory = index.get(finding.checkId);
+    if (checkCategory) {
+      finding.checkCategory = checkCategory;
+      enriched++;
+    }
+  }
+  return enriched;
+}
+
+/**
+ * Enrich an ATC result with check categories in place.
+ *
+ * @param result - The run result (findings mutated in place)
+ * @param index - checkId -> category name index
+ * @returns Number of findings that received a category
+ */
+export function enrichResultWithCategories<
+  T extends { checkId: string; checkCategory?: string },
+>(result: { findings?: T[] }, index: Map<string, string>): number {
+  return enrichFindingsWithCategories(result.findings ?? [], index);
+}

packages/adt-atc/src/commands/atc.ts

@@ -8,6 +8,11 @@
 import type { CliCommandPlugin, CliContext } from '@abapify/adt-plugin';
 import chalk from 'chalk';
 import { outputSarifReport, outputGitLabCodeQuality } from '../formatters';
+import {
+  fetchCheckCategoryIndex,
+  enrichResultWithCategories,
+} from '../check-categories';
+import { resolveCategoriesViaDocumentation } from '../documentation-bridge';
 import type { AtcResult, AtcFinding, OutputFormat } from '../types';
 
 // Client type - the plugin receives a typed client from context
@@ -34,6 +39,11 @@ interface AdtClient {
           params: { includeExemptedFindings: string },
         ) => Promise<WorklistResponse>;
       };
+      checkvariants: {
+        formtemplate: (params?: {
+          chkvName?: string;
+        }) => Promise<import('../check-categories').FormTemplateDocument>;
+      };
       runs: {
         post: (
           params: { worklistId: string },
@@ -54,6 +64,15 @@ interface AdtClient {
       };
     };
   };
+  /**
+   * Bounded documentation text read (the real ADT client provides it).
+   * Optional: without it the documentation category bridge is skipped.
+   */
+  readTextBounded?: (
+    uri: string,
+    maxBytes: number,
+    options?: { headers?: Record<string, string> },
+  ) => Promise<string>;
 }
 
 // Worklist response type
@@ -75,6 +94,8 @@ interface WorklistResponse {
             checkTitle?: string;
             messageId?: string;
             messageTitle?: string;
+            /** Documentation link: the page that names the check class. */
+            link?: Array<{ href?: string; rel?: string }>;
           }>;
         };
       }>;
@@ -105,6 +126,25 @@ function adtLink(name: string, uri: string, systemName?: string): string {
   return hyperlink(chalk.cyan(name), url);
 }
 
+/**
+ * The trusted documentation link of one worklist finding.
+ *
+ * Live shape (2026-10-22): <atom:link rel="http://www.sap.com/adt/
+ * relations/documentation" href="/sap/bc/adt/documentation/atc/documents/
+ * itemid/{guid}/index/{n}"/> inside the atcfinding:finding element.
+ */
+function documentationUriFromFinding(
+  finding: NonNullable<
+    NonNullable<
+      NonNullable<WorklistResponse['worklist']>['objects']['object']
+    >[number]['findings']['finding']
+  >[number],
+): string | undefined {
+  return finding.link?.find(
+    (link) => link.rel === 'http://www.sap.com/adt/relations/documentation',
+  )?.href;
+}
+
 /**
  * Convert worklist response to AtcResult
  */
@@ -131,6 +171,7 @@ function convertWorklistToResult(
           objectName: obj.name || '',
           location: finding.location,
           findingUri: finding.uri,
+          documentationUri: documentationUriFromFinding(finding),
         });
       }
     }
@@ -406,6 +447,38 @@ export const atcCommand: CliCommandPlugin = {
       checkVariant,
     );
 
+    // Enrich findings with check categories from the run's check variant
+    // form template (best-effort: never fails the run itself)
+    const categoryIndex = await fetchCheckCategoryIndex(
+      client,
+      checkVariant,
+      ctx.logger,
+    );
+    const enriched = enrichResultWithCategories(result, categoryIndex);
+    if (enriched > 0) {
+      ctx.logger.info(
+        `🏷️ Enriched ${enriched}/${result.totalFindings} finding(s) with check categories`,
+      );
+    }
+
+    // Bridge remaining findings through their ATC documentation page: the
+    // worklist checkId is a check-instance GUID, not the implementing class
+    // the form-template catalog lists (live evidence, 2026-10-22), so
+    // the direct index match cannot resolve them. The documentation page
+    // names the check class, which resolves through the same index.
+    // Best-effort: never fails the run.
+    const bridged = await resolveCategoriesViaDocumentation(
+      client,
+      result.findings,
+      categoryIndex,
+      { logger: ctx.logger },
+    );
+    if (bridged > 0) {
+      ctx.logger.info(
+        `🏷 Bridged ${bridged} finding(s) to check categories via ATC documentation`,
+      );
+    }
+
     // Load finding resolver if requested
     let resolver: import('../types').FindingResolver | undefined;
     if (options.resolver) {