@abapify/adt-plugin-abapgit 0.4.0 → 0.4.3

package/README.md

@@ -4,6 +4,30 @@
 
 abapGit format plugin for ADT — serializes ABAP objects to Git-compatible XML/ABAP files.
 
+## Pure materialization
+
+The registered `abapgitFormatPlugin` can produce a desired object tree without
+filesystem, ADT, or Git side effects. Explicit source components override
+mutable ADK source getters, while existing XSD-backed handlers continue to
+produce metadata:
+
+```typescript
+const { files } = await abapgitFormatPlugin.materialize({
+  object: adkClass,
+  objectType: 'CLAS',
+  packagePath: ['ZROOT', 'ZROOT_FEATURE'],
+  sources: {
+    main: selectedMainSource,
+    definitions: selectedLocalDefinitions,
+  },
+  formatOptions: { folderLogic: 'prefix' },
+});
+```
+
+Paths are rooted below `src/`, ordered deterministically, and annotated with
+their semantic role and source-component identity. Existing filesystem import
+and Git-to-SAP export APIs remain unchanged.
+
 ## Architecture Overview
 
 ```

package/dist/index.d.mts

@@ -0,0 +1,224 @@
+import { AbapObjectType, AdtPlugin, AdtPlugin as AdtPlugin$1, ExportContext, ExportResult, FormatMaterializationInput, FormatMaterializationResult, FormatPlugin, FormatSerializeOptions, ImportContext, ImportResult, MaterializedFormatFile } from "@abapify/adt-plugin";
+import { AdkObject } from "@abapify/adk";
+import { SchemaLike, TypedSchema } from "@abapify/ts-xsd";
+import { adtUriToAbapGitPath, createAbapGitResolver as createFindingResolver } from "@abapify/adt-atc";
+//#region src/lib/format-plugin.d.ts
+declare const abapgitFormatPlugin: FormatPlugin;
+//#endregion
+//#region src/lib/folder-logic.d.ts
+/**
+ * abapGit Folder Logic
+ *
+ * Shared functions for resolving SAP package names from directory paths
+ * using abapGit's folder logic (PREFIX/FULL).
+ *
+ * Used by both the serializer (import: SAP → Git) and deserializer (export: Git → SAP).
+ */
+type FolderLogic = 'prefix' | 'full' | 'full-with-root';
+/**
+ * Parse abapGit repository metadata from .abapgit.xml content
+ */
+declare function parseAbapGitMetadata(xmlContent: string): {
+  folderLogic: FolderLogic;
+  startingFolder: string;
+};
+/**
+ * Reverse of calculatePackageDir — compute SAP package name from directory path
+ *
+ * Given a directory path relative to the starting folder, the folder logic,
+ * and the root package name, compute the SAP package name.
+ *
+ * PREFIX mode: root 'ZABAPGIT_EXAMPLES' + dir 'clas' → 'ZABAPGIT_EXAMPLES_CLAS'
+ * FULL mode: dir 'zabapgit_examples_clas' → 'ZABAPGIT_EXAMPLES_CLAS'
+ *
+ * @param dirPath - Directory path relative to starting folder
+ * @param folderLogic - Folder logic mode (prefix or full)
+ * @param rootPackage - Root SAP package name
+ * @returns SAP package name
+ */
+declare function resolvePackageFromDir(dirPath: string, folderLogic: FolderLogic, rootPackage: string): string;
+/**
+ * Reverse of resolvePackageFromDir — given a SAP package name and the
+ * relative directory of an object, back-derive the root package.
+ *
+ * PREFIX mode: sapPackage 'ZABAPGIT_EXAMPLES_FUGR' + dir 'fugr' → 'ZABAPGIT_EXAMPLES'
+ * FULL mode: cannot derive root (returns undefined)
+ *
+ * @param sapPackage - Actual SAP package name (from GET response)
+ * @param relDir - Directory path relative to starting folder
+ * @param folderLogic - Folder logic mode
+ * @returns Root package name, or undefined if it cannot be derived
+ */
+declare function reverseResolveRootPackage(sapPackage: string, relDir: string, folderLogic: FolderLogic): string | undefined;
+//#endregion
+//#region src/lib/abapgit.d.ts
+/**
+ * abapGit Plugin
+ *
+ * Provides import/export of ADK objects to abapGit repository format.
+ */
+declare const abapGitPlugin: AdtPlugin$1;
+//#endregion
+//#region src/lib/handlers/abapgit-schema.d.ts
+/**
+ * AbapGit schema instance with both full type and values type
+ *
+ * @typeParam TFull - Full AbapGitType (root XML structure)
+ * @typeParam TValues - Inner values type (e.g., DevcType)
+ * @typeParam S - Raw schema literal type
+ */
+interface AbapGitSchema<TFull, TValues, S extends SchemaLike = SchemaLike> extends TypedSchema<TFull, S> {
+  /** The inner values type - use with typeof for type extraction */
+  readonly _values: TValues;
+}
+/** Extract the values type from an AbapGitSchema */
+type InferValuesType<S> = S extends AbapGitSchema<unknown, infer V> ? V : unknown;
+//#endregion
+//#region src/lib/handlers/base.d.ts
+/**
+ * Extract the data type (D) from an AdkObject<K, D>
+ * This allows us to infer the payload type from the ADK class itself
+ */
+type InferAdkData<T> = T extends AdkObject<infer _K, infer D> ? D : never;
+/**
+ * ABAP object type code (e.g., 'CLAS', 'INTF', 'DOMA')
+ */
+type AbapObjectType$1 = string;
+/**
+ * Result of serializing a single file
+ */
+interface SerializedFile {
+  /** Relative path from object directory */
+  path: string;
+  /** File content */
+  content: string;
+  /** Optional encoding (default: utf-8) */
+  encoding?: BufferEncoding;
+}
+/**
+ * Handler interface for object serialization/deserialization
+ *
+ * @typeParam T - ADK object type
+ * @typeParam TSchema - AbapGit schema type (provides type-safe values)
+ */
+interface ObjectHandler<T extends AdkObject = AdkObject, TSchema extends AbapGitSchema<unknown, unknown> = AbapGitSchema<unknown, unknown>> {
+  /** ABAP object type (e.g., 'CLAS', 'INTF') */
+  readonly type: AbapObjectType$1;
+  /** File extension for this type (e.g., 'clas', 'intf') */
+  readonly fileExtension: string;
+  /** Schema for parsing/building XML */
+  readonly schema: TSchema;
+  /** Map abapGit file suffix to source key */
+  readonly suffixToSourceKey?: Record<string, string>;
+  /** Whether this handler treats an explicit `sources` map as authoritative. */
+  readonly supportsExplicitSources?: boolean;
+  /** Serialize object to files (SAP → Git) */
+  serialize(object: T, options?: FormatSerializeOptions): Promise<SerializedFile[]>;
+  /**
+   * Map abapGit values to ADK data (Git → SAP)
+   * Return type includes name (required) plus any ADK data fields
+   */
+  fromAbapGit?(values: InferValuesType<TSchema>): Partial<InferAdkData<T>> & {
+    name: string;
+  };
+  /**
+   * Map AFF JSON metadata to ADK data (Git → SAP)
+   * Used when the metadata file is `.json` (ABAP File Format) instead of legacy `.xml`.
+   * Receives the parsed JSON object and returns the full payload including name.
+   */
+  fromAffJson?(json: Record<string, unknown>): Partial<InferAdkData<T>> & {
+    name: string;
+  };
+  /**
+   * Set source files on ADK object during deserialization (Git → SAP)
+   * Symmetric counterpart to getSources
+   */
+  setSources?(object: T, sources: Record<string, string>): void;
+}
+/**
+ * Get handler for object type
+ *
+ * Tries the full type first (e.g., 'TABL/DS'), then falls back to the
+ * main type (e.g., 'CLAS/OC' → 'CLAS'). This matches ADK's resolveType()
+ * behaviour and handles quickSearch results that return subtypes.
+ */
+declare function getHandler(type: AbapObjectType$1): ObjectHandler | undefined;
+/**
+ * Check if object type is supported
+ *
+ * Tries the full type first, then falls back to the main type.
+ */
+declare function isSupported(type: AbapObjectType$1): boolean;
+/**
+ * Get all supported object types
+ */
+declare function getSupportedTypes(): AbapObjectType$1[];
+//#endregion
+//#region src/lib/filename-parser.d.ts
+/**
+ * abapGit filename parsing utilities.
+ *
+ * Extracted into a standalone module so it can be unit-tested without
+ * pulling in the full handler/schema dependency chain.
+ */
+/**
+ * abapGit file naming convention:
+ * - XML metadata: {name}.{type}.xml (e.g., zcl_myclass.clas.xml)
+ * - AFF JSON metadata: {name}.{type}.json (e.g., zfoo.bdef.json)
+ * - Source code: {name}.{type}.abap (e.g., zcl_myclass.clas.abap)
+ * - Source includes: {name}.{type}.{suffix}.abap (e.g., zcl_myclass.clas.testclasses.abap)
+ * - AFF source files: {name}.{type}.abdl, {name}.{type}.acds, {name}.{type}.asrvd
+ */
+/**
+ * Parse abapGit filename to extract object info
+ *
+ * Supports both legacy XML metadata (.xml) and AFF JSON metadata (.json),
+ * plus source file extensions (.abap, .abdl, .acds, .asrvd).
+ */
+declare function parseAbapGitFilename(filename: string): {
+  name: string;
+  type: string;
+  suffix?: string;
+  extension: string;
+} | null;
+//#endregion
+//#region src/lib/handlers/xml-format.d.ts
+/**
+ * XML formatting utilities for abapGit serialization.
+ *
+ * Centralizes XML post-processing that was previously duplicated
+ * across base.ts, fugr.ts, tabl.ts, and roundtrip.ts.
+ *
+ * Uses indexOf-based parsing instead of regex to avoid
+ * super-linear backtracking (SonarQube S5852).
+ */
+/**
+ * Format XML attributes on separate lines for better diff readability.
+ *
+ * Turns `<tag a="1" b="2">` into:
+ * ```
+ * <tag
+ *   a="1"
+ *   b="2"
+ * >
+ * ```
+ *
+ * Uses indexOf-based scanning to avoid regex backtracking (S5852).
+ */
+declare function formatXmlAttributes(xml: string): string;
+/**
+ * Move `xmlns:asx` declaration from root `<abapGit>` to nested `<asx:abap>`.
+ *
+ * Uses indexOf-based approach instead of regex to avoid backtracking on
+ * the `[\s\S]*?` pattern that SonarQube flags.
+ */
+declare function moveNamespaceToAbap(xml: string): string;
+/**
+ * Apply standard abapGit XML formatting:
+ * 1. Format attributes on separate lines
+ * 2. Move xmlns:asx to asx:abap element
+ */
+declare function formatAbapGitXml(xml: string): string;
+//#endregion
+export { abapGitPlugin as AbapGitPlugin, abapGitPlugin, abapGitPlugin as default, type AbapObjectType, type AdtPlugin, type ExportContext, type ExportResult, type FolderLogic, type FormatMaterializationInput, type FormatMaterializationResult, type ImportContext, type ImportResult, type MaterializedFormatFile, type ObjectHandler, type SerializedFile, abapgitFormatPlugin, adtUriToAbapGitPath, createFindingResolver, formatAbapGitXml, formatXmlAttributes, getHandler, getSupportedTypes, isSupported, moveNamespaceToAbap, parseAbapGitFilename, parseAbapGitMetadata, resolvePackageFromDir, reverseResolveRootPackage };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/lib/format-plugin.ts","../src/lib/folder-logic.ts","../src/lib/abapgit.ts","../src/lib/handlers/abapgit-schema.ts","../src/lib/handlers/base.ts","../src/lib/filename-parser.ts","../src/lib/handlers/xml-format.ts"],"mappings":";;;;;cAgGa,qBAAqB;;;;;;;;;;;KCvFtB;;;;iBA6CI,qBAAqB;EACnC,aAAa;EACb;;;;;;;;;;;;;;;;iBAsBc,sBACd,iBACA,aAAa,aACb;;;;;;;;;;;;;iBA2Cc,0BACd,oBACA,gBACA,aAAa;;;;;;;;cCwBF,eAAe;;;;;;;;;;UClIX,cACf,OACA,SACA,UAAU,aAAa,oBACf,YAAY,OAAO;;WAElB,SAAS;;;KA2CR,gBAAgB,KAC1B,UAAU,6BAA6B,KAAK;;;;;;;KC/ClC,aAAa,KACvB,UAAU,gBAAgB,UAAU,KAAK;;;;KAsB/B;;;;UAKK;;EAEf;;EAEA;;EAEA,WAAW;;;;;;;;UASI,cACf,UAAU,YAAY,WACtB,gBAAgB,kCAAkC;;WAMzC,MAAM;;WAEN;;WAEA,QAAQ;;WAER,oBAAoB;;WAEpB;;EAET,UACE,QAAQ,GACR,UAAU,yBACT,QAAQ;;;;;EAKX,aACE,QAAQ,gBAAgB,WACvB,QAAQ,aAAa;IAAQ;;;;;;;EAOhC,aAAa,MAAM,0BAA0B,QAAQ,aAAa;IAChE;;;;;;EAOF,YAAY,QAAQ,GAAG,SAAS;;;;;;;;;iBAyBlB,WAAW,MAAM,mBAAiB;;;;;;iBASlC,YAAY,MAAM;;;;iBAOlB,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;iBCjIrB,qBAAqB;EACnC;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;iBC+Bc,oBAAoB;;;;;;;iBA8DpB,oBAAoB;;;;;;iBA8BpB,iBAAiB"}