@abapify/adt-plugin-gcts 0.4.34 → 0.4.37

package/README.md

@@ -1,42 +1,18 @@
 # @abapify/adt-plugin-gcts
 
-**Status:** v0.1 (E06 — SAP → disk direction)
+[![npm](https://img.shields.io/npm/v/%40abapify%2Fadt-plugin-gcts)](https://www.npmjs.com/package/@abapify/adt-plugin-gcts)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/abapify/adt-cli/blob/main/LICENSE)
 
-Serializes ABAP objects to **gCTS / AFF** layout (`SAP/abap-file-formats`):
-JSON metadata files (`<name>.<type>.json`) alongside source files
-(`<name>.<type>.abap`, `.asddls`, `.asdcls`).
+gCTS (git-enabled CTS) plugin for adt-cli — repository, commit, pull/push operations on SAP gCTS.
 
-## Why a single plugin for both gCTS and AFF?
+## Install
 
-gCTS (git-enabled CTS) and AFF (`SAP/abap-file-formats`) use the same
-on-disk layout: JSON metadata, AFF-specific extensions, `(ns)` bracket
-namespace folders. A single `--format gcts` (alias: `--format aff`) serves
-both communities. The open question on naming is tracked in
-`docs/roadmap/epics/e06-gcts-format-plugin.md`.
-
-## Filename conventions
-
-| Object | Metadata            | Source                                                            |
-| ------ | ------------------- | ----------------------------------------------------------------- |
-| CLAS   | `<name>.clas.json`  | `<name>.clas.abap` (+ `.locals_def.abap`, `.testclasses.abap`, …) |
-| INTF   | `<name>.intf.json`  | `<name>.intf.abap`                                                |
-| PROG   | `<name>.prog.json`  | `<name>.prog.abap`                                                |
-| FUGR   | `<name>.fugr.json`  | — (FM files handled separately)                                   |
-| DOMA   | `<name>.doma.json`  | —                                                                 |
-| DTEL   | `<name>.dtel.json`  | —                                                                 |
-| TABL   | `<name>.tabl.json`  | —                                                                 |
-| TTYP   | `<name>.ttyp.json`  | —                                                                 |
-| DEVC   | `package.devc.json` | —                                                                 |
-| DDLS   | `<name>.ddls.json`  | `<name>.ddls.asddls`                                              |
-| DCLS   | `<name>.dcls.json`  | `<name>.dcls.asdcls`                                              |
-
-vs abapGit: metadata is **JSON** (not XML) and CDS uses **`.asddls` /
-`.asdcls`** (not `.acds`).
+```bash
+npm install @abapify/adt-plugin-gcts
+```
 
 ## Usage
 
-Install and import — the plugin self-registers:
-
 ```ts
 import '@abapify/adt-plugin-gcts';
 import { getFormatPlugin } from '@abapify/adt-plugin';
@@ -44,22 +20,15 @@ import { getFormatPlugin } from '@abapify/adt-plugin';
 const gcts = getFormatPlugin('gcts')!;
 ```
 
-Via the CLI (after E06 wiring):
-
-```bash
-bunx adt import package --format gcts ZMYPKG ./out
-```
+## Features
 
-The SAP → disk direction is fully supported in v0.1. disk → SAP (adt-cli's
-`export` command) is deferred — see the epic's "Open questions".
+- gCTS / ABAP File Formats (AFF) serialization
+- Registers itself as the `gcts` format plugin
 
-## Architecture
+## Documentation
 
-This plugin is a peer of `@abapify/adt-plugin-abapgit`:
+**[adt-cli.netlify.app/sdk/packages/adt-plugin-gcts](https://adt-cli.netlify.app/sdk/packages/adt-plugin-gcts)**
 
-- `FormatPlugin` (declarative contract) is in `src/lib/format/gcts-format.ts`
-- `AdtPlugin` (higher-level import behaviour) is in `src/lib/gcts-plugin.ts`
-- Per-object-type handlers live in `src/lib/handlers/objects/` and
-  auto-register through the `createHandler` factory in `handlers/base.ts`
+---
 
-See [`AGENTS.md`](./AGENTS.md) for internal conventions.
+Part of [**abapify**](https://github.com/abapify/adt-cli) — open, typed tooling for SAP ABAP Development Tools (ADT): CLI, MCP server, and SDK.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { AdtPlugin, AdtPlugin as AdtPlugin$1, FormatHandler, FormatHandler as FormatHandler$1, FormatPlugin, FormatPlugin as FormatPlugin$1, ParsedFormatFilename, SerializedFile, SerializedFile as SerializedFile$1 } from "@abapify/adt-plugin";
-import { AdkClass, AdkDataElement, AdkDomain, AdkFunctionGroup, AdkInterface, AdkKind, AdkObject, AdkPackage, AdkProgram, AdkTable, AdkTableType } from "@abapify/adk";
+import { AdkDataElement, AdkDomain, AdkKind, AdkObject, AdkProgram } from "@abapify/adk";
 /**
  * gCTS / AFF format type definitions.
  *
@@ -14,28 +14,35 @@ import { AdkClass, AdkDataElement, AdkDomain, AdkFunctionGroup, AdkInterface, Ad
  */
 /** Header common to every AFF/gCTS metadata JSON file. */
 interface GctsHeader {
-  /** AFF format version (e.g. `1.0`). */
-  formatVersion: string;
+  /** Legacy header version; current AFF schemas put formatVersion at the top level. */
+  formatVersion?: string;
   /** Description of the object. */
   description?: string;
   /** Master language (ISO code, lowercase — e.g. `en`). */
   originalLanguage?: string;
   /** ABAP language version (e.g. `standard`, `cloudDevelopment`). */
   abapLanguageVersion?: string;
-  /** Indicates whether the object source is Unicode. */
-  [key: string]: unknown;
 }
 /**
  * Top-level shape of an AFF/gCTS metadata JSON file.
  *
  * Concrete handlers tighten this with per-type payload shapes.
+ *
+ * A format version is mandatory: either the current top-level `formatVersion`
+ * or the legacy `header.formatVersion`.
  */
-interface GctsMetadata<_TPayload extends object = object> {
+type GctsMetadata<_TPayload extends object = object> = {
+  /** Current AFF format version. */
+  formatVersion: string;
   /** Format header (mandatory on every file). */
   header: GctsHeader;
-  /** Type-specific payload. Extended per ABAP object type. */
-  [payloadKey: string]: unknown;
-}
+} | {
+  formatVersion?: string;
+  /** Legacy form: the version lives in the header. */
+  header: GctsHeader & {
+    formatVersion: string;
+  };
+};
 /** Convenience helper for concrete metadata shapes. */
 type WithHeader<TPayload extends object> = {
   header: GctsHeader;
@@ -98,7 +105,7 @@ declare function parseGctsFilename(filename: string): ParsedFormatFilename | und
  * Matches the `adtUriToAbapGitPath` helper in the abapGit plugin.
  */
 declare function adtUriToGctsPath(uri: string): string | undefined;
-type AbapObjectType = string;
+type HandlerObject = Pick<AdkObject, 'name'>;
 type AdkObjectClass<T extends AdkObject = AdkObject> = {
   new (...args: any[]): T;
   readonly kind: AdkKind;
@@ -136,7 +143,7 @@ interface GctsExtraFile {
  * friction. The `toMetadata` function is the only required hook: it maps an
  * ADK object to the JSON metadata shape for the target type.
  */
-interface GctsHandlerDefinition<T extends AdkObject, M extends GctsMetadata = GctsMetadata> {
+interface GctsHandlerDefinition<T extends HandlerObject, M extends GctsMetadata = GctsMetadata> {
   /** Map ADK object → JSON metadata payload (including the required `header`). */
   toMetadata(object: T): M;
   /** Optional: single primary source file. */
@@ -161,8 +168,8 @@ interface GctsHandlerDefinition<T extends AdkObject, M extends GctsMetadata = Gc
   setSources?(object: T, sources: Record<string, string>): void;
 }
 /** Runtime shape of a gCTS handler after `createHandler` processing. */
-interface GctsHandler<T extends AdkObject = AdkObject> extends FormatHandler$1 {
-  readonly type: AbapObjectType;
+interface GctsHandler<T extends HandlerObject = AdkObject> extends FormatHandler$1 {
+  readonly type: string;
   readonly fileExtension: string;
   readonly schema: {
     parse(raw: string): unknown;
@@ -175,85 +182,13 @@ interface GctsHandler<T extends AdkObject = AdkObject> extends FormatHandler$1 {
   setSources?(object: T, sources: Record<string, string>): void;
 }
 /** Look up a handler (full-type first, then main-type fallback). */
-declare function getHandler(type: AbapObjectType): GctsHandler | undefined;
+declare function getHandler(type: string): GctsHandler<HandlerObject> | undefined;
 /** `true` iff the given object type has a registered handler. */
-declare function isSupported(type: AbapObjectType): boolean;
+declare function isSupported(type: string): boolean;
 /** Snapshot of all registered object types. */
-declare function getSupportedTypes(): AbapObjectType[];
-/**
- * Register a handler for an ADK class (preferred — `type` is derived from
- * the static `kind`) or an explicit type string (for types without an ADK
- * class, e.g. DOMA/DTEL).
- */
-declare function createHandler<T extends AdkObject, M extends GctsMetadata = GctsMetadata>(adkClass: AdkObjectClass<T>, definition: GctsHandlerDefinition<T, M>): GctsHandler<T>;
-declare function createHandler<T extends AdkObject, M extends GctsMetadata = GctsMetadata>(type: AbapObjectType, definition: GctsHandlerDefinition<T, M>): GctsHandler<T>;
-declare const gctsFormatPlugin: FormatPlugin$1;
-declare const gctsPlugin: AdtPlugin$1;
-/**
- * AFF schema access over the `git_modules/abap-file-formats` submodule.
- *
- * The submodule pin (`.gitmodules`) is the provenance record — schemas and
- * examples are always read from it at the pinned upstream SHA. This module
- * has no workspace dependencies (ajv + node builtins only) so schema
- * conformance tests run without building the workspace.
- */
-/** Resolved AFF schema root, or `undefined` when unavailable. */
-declare function affRoot(): string | undefined;
-/** All official AFF object types (directories in `file-formats/`). */
-declare function listAffTypes(): string[];
-/**
- * Reference to a schema-bearing AFF artefact: an object `type` code plus an
- * optional format `version` (defaults to the latest wherever it matters).
- */
-interface AffRef {
-  type: string;
-  version?: number;
-}
-/** Format versions available for a type, newest first. */
-declare function affVersions(ref: AffRef): number[];
-declare function latestAffVersion(ref: AffRef): number | undefined;
-interface AffSchema {
-  title: string;
-  type: string;
-  properties: Record<string, {
-    const?: string;
-    type?: string;
-  }>;
-  required?: string[];
-  [key: string]: unknown;
-}
-declare function affSchema(ref: AffRef): AffSchema;
-/**
- * Top-level body properties of a type's schema (everything beyond the
- * mandatory `formatVersion`/`header` envelope), newest version by default.
- * Empty array for header-only types or when schemas are unavailable.
- */
-declare function affBodyProps(ref: AffRef): string[];
-/** Validate AFF JSON against the official schema for `ref`. */
-declare function affValidate(ref: AffRef, json: unknown): {
-  valid: boolean;
-  errors: string[];
-};
-/**
- * Example JSON files shipped with a type — recursively, relative paths.
- * Companion files (`.docu.json`, LIMU sub-objects like `.reps.json`) are
- * included; callers match each to its schema (see `schemaTargetForExample`).
- */
-declare function affExamples(ref: AffRef): string[];
-/**
- * Pick the schema a given example file should validate against.
- *
- * - `z_x.doma.docu.json` → the `docu` schema (companion documentation)
- * - `x.fugr.z_fm.func.json` / `x.fugr.y.reps.json` → the LIMU
- *   sub-object's own schema (nested under the parent type dir)
- * - otherwise → the type's own schema at the example's `formatVersion`
- */
-declare function schemaTargetForExample(ref: AffRef, filename: string, json: unknown): {
-  type: string;
-  version?: number;
-  companion: boolean;
-};
-declare function readAffExample(ref: AffRef, rel: string): Record<string, unknown>;
+declare function getSupportedTypes(): string[];
+declare function createHandler<T extends HandlerObject, M extends GctsMetadata = GctsMetadata>(adkClass: AdkObjectClass, definition: GctsHandlerDefinition<T, M>): GctsHandler<T>;
+declare function createHandler<T extends HandlerObject, M extends GctsMetadata = GctsMetadata>(type: string, definition: GctsHandlerDefinition<T, M>): GctsHandler<T>;
 declare namespace advc_v1_d_exports {
   export { ABAPLanguageVersion$84 as ABAPLanguageVersion, AdvcAff, AffAdvcV1, Description$91 as Description, FormatVersion$27 as FormatVersion, Header$90 as Header, OriginalLanguage$89 as OriginalLanguage };
 }
@@ -11645,5 +11580,74 @@ type UistAff = AffUistV1;
 declare namespace index_d_exports {
   export { AdvcAff, advc_v1_d_exports as AdvcV1, AifaAff, aifa_v1_d_exports as AifaV1, AifdAff, aifd_v1_d_exports as AifdV1, AiffAff, aiff_v1_d_exports as AiffV1, AifiAff, aifi_v1_d_exports as AifiV1, AifnAff, aifn_v1_d_exports as AifnV1, AifpAff, aifp_v1_d_exports as AifpV1, AifrAff, aifr_v1_d_exports as AifrV1, AobjAff, aobj_v1_d_exports as AobjV1, ApicAff, apic_v1_d_exports as ApicV1, AploAff, aplo_v1_d_exports as AploV1, ApobAff, apob_v1_d_exports as ApobV1, BdefAff, bdef_v1_d_exports as BdefV1, BgqcAff, bgqc_v1_d_exports as BgqcV1, CdboAff, cdbo_v1_d_exports as CdboV1, CfdfAff, cfdf_v1_d_exports as CfdfV1, cfdf_v2_d_exports as CfdfV2, ChdoAff, chdo_v1_d_exports as ChdoV1, ChkcAff, chkc_v1_d_exports as ChkcV1, ChkoAff, chko_v1_d_exports as ChkoV1, ChkvAff, chkv_v1_d_exports as ChkvV1, ClasAff, clas_v1_d_exports as ClasV1, CotaAff, cota_v1_d_exports as CotaV1, CsnmAff, csnm_v1_d_exports as CsnmV1, DcatAff, dcat_v1_d_exports as DcatV1, DclsAff, dcls_v1_d_exports as DclsV1, DdlaAff, ddla_v1_d_exports as DdlaV1, DdlsAff, ddls_v1_d_exports as DdlsV1, DdlxAff, ddlx_v1_d_exports as DdlxV1, DesdAff, desd_v1_d_exports as DesdV1, DmonAff, dmon_v1_d_exports as DmonV1, DobjAff, dobj_v1_d_exports as DobjV1, DocuAff, docu_v1_d_exports as DocuV1, DomaAff, doma_v1_d_exports as DomaV1, DrasAff, dras_v1_d_exports as DrasV1, DrtyAff, drty_v1_d_exports as DrtyV1, DsfdAff, dsfd_v1_d_exports as DsfdV1, DsfiAff, dsfi_v1_d_exports as DsfiV1, DtdcAff, dtdc_v1_d_exports as DtdcV1, DtebAff, dteb_v1_d_exports as DtebV1, DtelAff, dtel_v1_d_exports as DtelV1, DtixAff, dtix_v1_d_exports as DtixV1, DtscAff, dtsc_v1_d_exports as DtscV1, EdccAff, edcc_v1_d_exports as EdccV1, EdckAff, edck_v1_d_exports as EdckV1, EdcrAff, edcr_v1_d_exports as EdcrV1, EdoiAff, edoi_v1_d_exports as EdoiV1, EeecAff, eeec_v1_d_exports as EeecV1, EnhoAff, enho_v1_d_exports as EnhoV1, EnhsAff, enhs_v1_d_exports as EnhsV1, EnquAff, enqu_v1_d_exports as EnquV1, EvtbAff, evtb_v1_d_exports as EvtbV1, EvtoAff, evto_v1_d_exports as EvtoV1, FugrAff, fugr_v1_d_exports as FugrV1, FuncAff, func_v1_d_exports as FuncV1, GsmpAff, gsmp_v1_d_exports as GsmpV1, HttpAff, http_v1_d_exports as HttpV1, IlmbAff, ilmb_v1_d_exports as IlmbV1, IntfAff, intf_v1_d_exports as IntfV1, IntmAff, intm_v1_d_exports as IntmV1, IntsAff, ints_v1_d_exports as IntsV1, IwngAff, iwng_v1_d_exports as IwngV1, MsagAff, msag_v1_d_exports as MsagV1, NontAff, nont_v1_d_exports as NontV1, NrobAff, nrob_v1_d_exports as NrobV1, NttaAff, ntta_v1_d_exports as NttaV1, NttyAff, ntty_v1_d_exports as NttyV1, ProgAff, prog_v1_d_exports as ProgV1, RepsAff, reps_v1_d_exports as RepsV1, RontAff, ront_v1_d_exports as RontV1, RvbcAff, rvbc_v1_d_exports as RvbcV1, SaiaAff, saia_v1_d_exports as SaiaV1, SajcAff, sajc_v1_d_exports as SajcV1, SajtAff, sajt_v1_d_exports as SajtV1, Scp1Aff, scp1_v1_d_exports as Scp1V1, SfpfAff, sfpf_v1_d_exports as SfpfV1, SiadAff, siad_v1_d_exports as SiadV1, SitoAff, sito_v1_d_exports as SitoV1, sito_v2_d_exports as SitoV2, SmbcAff, smbc_v1_d_exports as SmbcV1, SmtgAff, smtg_v1_d_exports as SmtgV1, SprvAff, sprv_v1_d_exports as SprvV1, SrvbAff, srvb_v1_d_exports as SrvbV1, SrvcAff, srvc_v1_d_exports as SrvcV1, SrvdAff, srvd_v1_d_exports as SrvdV1, SucoAff, suco_v1_d_exports as SucoV1, SusiAff, susi_v1_d_exports as SusiV1, SwcrAff, swcr_v1_d_exports as SwcrV1, SxtgAff, sxtg_v1_d_exports as SxtgV1, UiadAff, uiad_v1_d_exports as UiadV1, uiad_v2_d_exports as UiadV2, UipgAff, uipg_v1_d_exports as UipgV1, UistAff, uist_v1_d_exports as UistV1 };
 }
+declare const gctsFormatPlugin: FormatPlugin$1;
+declare const gctsPlugin: AdtPlugin$1;
+/**
+ * AFF schema access over the `git_modules/abap-file-formats` submodule.
+ *
+ * The submodule pin (`.gitmodules`) is the provenance record — schemas and
+ * examples are always read from it at the pinned upstream SHA. This module
+ * has no workspace dependencies (ajv + node builtins only) so schema
+ * conformance tests run without building the workspace.
+ */
+/** Resolved AFF schema root, or `undefined` when unavailable. */
+declare function affRoot(): string | undefined;
+/** All official AFF object types (directories in `file-formats/`). */
+declare function listAffTypes(): string[];
+/**
+ * Reference to a schema-bearing AFF artefact: an object `type` code plus an
+ * optional format `version` (defaults to the latest wherever it matters).
+ */
+interface AffRef {
+  type: string;
+  version?: number;
+}
+/** Format versions available for a type, newest first. */
+declare function affVersions(ref: AffRef): number[];
+declare function latestAffVersion(ref: AffRef): number | undefined;
+interface AffSchemaProperty {
+  const?: string;
+  type?: string;
+  properties?: Record<string, AffSchemaProperty>;
+}
+interface AffSchema {
+  title: string;
+  type: string;
+  properties: Record<string, AffSchemaProperty>;
+  required?: string[];
+  [key: string]: unknown;
+}
+declare function affSchema(ref: AffRef): AffSchema;
+/**
+ * Top-level body properties of a type's schema (everything beyond the
+ * mandatory `formatVersion`/`header` envelope), newest version by default.
+ * Empty array for header-only types or when schemas are unavailable.
+ */
+declare function affBodyProps(ref: AffRef): string[];
+/** Validate AFF JSON against the official schema for `ref`. */
+declare function affValidate(ref: AffRef, json: unknown): {
+  valid: boolean;
+  errors: string[];
+};
+/**
+ * Example JSON files shipped with a type — recursively, relative paths.
+ * Companion files (`.docu.json`, LIMU sub-objects like `.reps.json`) are
+ * included; callers match each to its schema (see `schemaTargetForExample`).
+ */
+declare function affExamples(ref: AffRef): string[];
+/**
+ * Pick the schema a given example file should validate against.
+ *
+ * - `z_x.doma.docu.json` → the `docu` schema (companion documentation)
+ * - `x.fugr.z_fm.func.json` / `x.fugr.y.reps.json` → the LIMU
+ *   sub-object's own schema (nested under the parent type dir)
+ * - otherwise → the type's own schema at the example's `formatVersion`
+ */
+declare function schemaTargetForExample(ref: AffRef, filename: string, json: unknown): {
+  type: string;
+  version?: number;
+  companion: boolean;
+};
+declare function readAffExample(ref: AffRef, rel: string): Record<string, unknown>;
 export { type AdtPlugin, index_d_exports as AffGenerated, type AffRef, type FormatHandler, type FormatPlugin, type GctsHandler, type GctsHandlerDefinition, type GctsHeader, type GctsMetadata, gctsPlugin as GctsPlugin, gctsPlugin as default, gctsPlugin, type GctsSourceEntry, LIMU_SUBTYPES, METADATA_EXTENSION, PACKAGE_FILENAME, type SerializedFile, type WithHeader, adtUriToGctsPath, affBodyProps, affExamples, affRoot, affSchema, affValidate, affVersions, createHandler, gctsFilename, gctsFormatPlugin, gctsSourceExt, getHandler, getSupportedTypes, isSupported, latestAffVersion, listAffTypes, parseGctsFilename, readAffExample, schemaTargetForExample, sourceKey, splitSourceKey };
 //# sourceMappingURL=index.d.mts.map