@mcp-abap-adt/core 6.4.0 → 6.4.1

package/docs/superpowers/specs/2026-04-13-high-level-check-tools-design.md

@@ -1,204 +0,0 @@
-# High-Level Check Tools for ABAP Objects
-
-**Issue:** #54 — Add Check tools for ABAP objects (syntax/semantic validation)
-**Date:** 2026-04-13
-
-## Problem
-
-LLM agents create/update ABAP objects but errors are only discovered at activation time. This causes expensive retry loops. Low-level Check handlers exist but are not exposed as standalone high-level tools — check is only embedded inside Create/Update workflows.
-
-## Solution
-
-Add 13 high-level Check tools — one per object type that has a low-level check handler. Each is an adapter wrapper that delegates to the existing low-level handler and normalizes the response: strips session fields, adds a shared `object_name` field, and returns a consistent core response shape.
-
-## Non-goals / Limitations
-
-- Check tools do **not** perform lock/update/activate flows — they only run syntax/semantic validation.
-- Hypothetical source checking is only supported where the low-level handler already supports it (`source_code`, `ddl_code`, or `ddl_source`).
-- No automatic `super_package` resolution in Phase 1 — callers must provide it for `CheckPackage`.
-
-## Tools
-
-| High-level tool name | Low-level handler | source param | version default | available_in |
-|---|---|---|---|---|
-| `CheckBehaviorDefinition` | `handleCheckBehaviorDefinition` | — | — | onprem, cloud |
-| `CheckClass` | `handleCheckClass` | `source_code` | active | onprem, cloud, legacy |
-| `CheckDataElement` | `handleCheckDataElement` | — | — | onprem, cloud |
-| `CheckDomain` | `handleCheckDomain` | — | — | onprem, cloud |
-| `CheckFunctionGroup` | `handleCheckFunctionGroup` | — | — | onprem, cloud, legacy |
-| `CheckFunctionModule` | `handleCheckFunctionModule` | — | active | onprem, cloud, legacy |
-| `CheckInterface` | `handleCheckInterface` | — | — | onprem, cloud, legacy |
-| `CheckMetadataExtension` | `handleCheckMetadataExtension` | — | — | onprem, cloud |
-| `CheckPackage` | `handleCheckPackage` | — | — | onprem, cloud, legacy |
-| `CheckProgram` | `handleCheckProgram` | — | — | onprem, legacy |
-| `CheckStructure` | `handleCheckStructure` | `ddl_code` | inactive | onprem, cloud |
-| `CheckTable` | `handleCheckTable` | `ddl_code` | new | onprem, cloud |
-| `CheckView` | `handleCheckView` | `ddl_source` | inactive | onprem, cloud, legacy |
-
-## Handler pattern
-
-Each high-level Check handler:
-
-1. Exports a `TOOL_DEFINITION` with high-level name (no `Low` suffix)
-2. Same `available_in` as the low-level counterpart
-3. Input schema **excludes** `session_id` and `session_state`
-4. Passes through source param where supported by low-level
-5. Passes through `version` where supported by low-level
-6. Delegates to the existing low-level handler function
-7. Normalizes response: strips `session_id`/`session_state` from output, adds shared `object_name` field
-8. If low-level handler returns `isError: true` or a non-JSON payload, returns it unchanged without attempting normalization
-
-### File location
-
-Each handler in its object type's `high/` directory:
-
-```
-src/handlers/behavior_definition/high/handleCheckBehaviorDefinition.ts
-src/handlers/class/high/handleCheckClass.ts
-src/handlers/data_element/high/handleCheckDataElement.ts
-src/handlers/ddlx/high/handleCheckMetadataExtension.ts
-src/handlers/domain/high/handleCheckDomain.ts
-src/handlers/function/high/handleCheckFunctionGroup.ts
-src/handlers/function/high/handleCheckFunctionModule.ts
-src/handlers/interface/high/handleCheckInterface.ts
-src/handlers/package/high/handleCheckPackage.ts
-src/handlers/program/high/handleCheckProgram.ts
-src/handlers/structure/high/handleCheckStructure.ts
-src/handlers/table/high/handleCheckTable.ts
-src/handlers/view/high/handleCheckView.ts
-```
-
-Note: both FunctionGroup and FunctionModule handlers live in `src/handlers/function/high/` — same directory structure as low-level handlers.
-
-## Normalized response shape
-
-All high-level Check tools return a JSON response with the following normalized common fields (object-specific compatibility fields like `class_name`, `view_name`, `name` are preserved alongside):
-
-```typescript
-{
-  success: boolean;              // true if no errors
-  object_name: string;           // canonical shared field (uppercased)
-  check_result: {                // from parseCheckRunResponse()
-    success: boolean;
-    status: string;
-    message: string;
-    errors: Array<{ type: string; text: string; line?: string | number; href?: string }>;
-    warnings: Array<{ type: string; text: string; line?: string | number; href?: string }>;
-    info: Array<{ type: string; text: string; line?: string | number; href?: string }>;
-    total_messages: number;
-    has_errors: boolean;
-    has_warnings: boolean;
-  };
-  message: string;               // human-readable summary
-  // object-specific field preserved for compatibility:
-  class_name?: string;           // CheckClass
-  view_name?: string;            // CheckView
-  package_name?: string;         // CheckPackage
-  // etc.
-}
-```
-
-**Excluded from output:** `session_id`, `session_state`.
-
-**Error path:** If the low-level handler returns `isError: true` or a non-JSON payload, the high-level wrapper returns that error unchanged — no normalization applied.
-
-**Field naming for objects using `name`:** BehaviorDefinition and MetadataExtension use `name` as their low-level input field. In the response, keep `name` for compatibility but always add `object_name` as the canonical shared field.
-
-## Special parameters per object type
-
-- **CheckFunctionModule**: requires `function_group_name` + `function_module_name`
-- **CheckPackage**: requires `package_name` + `super_package`
-- **CheckTable**: `reporter` removed from high-level API (low-level default `abapCheckRun` is used)
-
-## Example: CheckClass
-
-```typescript
-import { handleCheckClass as handleCheckClassLow } from '../low/handleCheckClass';
-import type { HandlerContext } from '../../../lib/handlers/interfaces';
-import { return_response } from '../../../lib/utils';
-
-export const TOOL_DEFINITION = {
-  name: 'CheckClass',
-  available_in: ['onprem', 'cloud', 'legacy'] as const,
-  description: 'Perform syntax check on an ABAP class. Can check existing class (active/inactive) or validate hypothetical source code. Returns syntax errors, warnings, and messages.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      class_name: { type: 'string', description: 'Name of the ABAP class to check' },
-      version: { type: 'string', enum: ['active', 'inactive'], description: 'Version to check. Default: active' },
-      source_code: { type: 'string', description: 'Optional source code to check instead of the saved version' },
-    },
-    required: ['class_name'],
-  },
-} as const;
-
-export async function handleCheckClass(context: HandlerContext, args: Record<string, unknown>) {
-  const result = await handleCheckClassLow(context, args);
-  // Normalize: parse low-level JSON, add object_name, strip session fields
-  const data = JSON.parse(result.content[0].text);
-  delete data.session_id;
-  delete data.session_state;
-  data.object_name = data.class_name;
-  return return_response({ data: JSON.stringify(data, null, 2) });
-}
-```
-
-## Example: CheckBehaviorDefinition (no source param, no version)
-
-```typescript
-import { handleCheckBehaviorDefinition as handleCheckBdefLow } from '../low/handleCheckBehaviorDefinition';
-import type { HandlerContext } from '../../../lib/handlers/interfaces';
-import { return_response } from '../../../lib/utils';
-
-export const TOOL_DEFINITION = {
-  name: 'CheckBehaviorDefinition',
-  available_in: ['onprem', 'cloud'] as const,
-  description: 'Perform syntax check on an ABAP behavior definition (BDEF). Returns syntax errors, warnings, and messages.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      name: { type: 'string', description: 'Name of the behavior definition to check' },
-    },
-    required: ['name'],
-  },
-} as const;
-
-export async function handleCheckBehaviorDefinition(context: HandlerContext, args: Record<string, unknown>) {
-  const result = await handleCheckBdefLow(context, args);
-  const data = JSON.parse(result.content[0].text);
-  delete data.session_id;
-  delete data.session_state;
-  data.object_name = data.name;
-  return return_response({ data: JSON.stringify(data, null, 2) });
-}
-```
-
-## Registration
-
-All 13 handlers registered in `src/lib/handlers/groups/HighLevelHandlersGroup.ts` following existing pattern.
-
-## Acceptance criteria
-
-- [ ] High-level input schemas exclude `session_id` and `session_state`
-- [ ] High-level responses do not contain `session_id` or `session_state`
-- [ ] Response includes normalized `object_name` field
-- [ ] Response includes `success`, `message`, and `check_result` fields
-- [ ] Each tool is registered in `HighLevelHandlersGroup.ts`
-- [ ] Environment gating follows `available_in` from corresponding low-level handler
-- [ ] `CheckTable` does not expose `reporter` parameter
-- [ ] Each tool has integration test coverage in `src/__tests__/integration/high/` layout
-
-## Testing
-
-Integration tests for each Check tool in `src/__tests__/integration/high/` directories, following existing test patterns. Tests must verify:
-
-- Tool registration and availability per environment
-- Normalized response contract: `object_name` present, `session_id`/`session_state` absent
-- Preservation of object-specific fields (e.g., `class_name`, `view_name`)
-- `success`, `message`, `check_result` fields present in response
-
-## Phased delivery
-
-**Phase 1** (this PR): Adapter wrappers with response normalization, registration in HighLevelHandlersGroup, integration tests verifying normalized contract.
-
-**Phase 2** (future): API ergonomics — optional `super_package` resolution in CheckPackage, richer error descriptions for LLM agents.