feat(adt-plugin-gcts): spec file-name grammar + full source-extension coverage

openspec/changes/add-aff-full-coverage/tasks.md

@@ -5,7 +5,8 @@
 - [x] 0.1 Vendored schemas — already done via `git_modules/abap-file-formats` submodule (pinned `5ed949a`); document the bump-to-sync workflow in the package AGENTS.md.
 - [x] 0.2 Wire existing `scripts/generate-aff-schemas.ts` into `nx codegen adt-plugin-gcts` → `src/schemas/generated/{type}-v{n}.ts` typed models, one file per schema version.
 - [ ] 0.3 AFF handler contract — gcts `createHandler` `toMetadata`/`fromMetadata` already is the contract; extend with `sourceExt`/`companions` declaration for source-bearing types. abapGit `toAffJson` stays a Wave-4 parity concern inside that plugin only.
-- [x] 0.4 ajv-based schema-validation harness — shared `affValidate(type, json, version)` reading schemas from `git_modules/` + golden-fixture runner over the submodule's `examples/` (match example→schema by `formatVersion` field; `.docu.`/`.reps.` files use their own companion schemas). Emit-side round-trip tests that pass handler-emitted metadata through `affValidate` land with the generic emitters in Waves 1–3 (`tests/aff/generic-roundtrip.test.ts`).
+- [x] 0.4 ajv-based schema-validation harness — shared `affValidate(type, json, version)` reading schemas from `git_modules/` + golden-fixture runner over the submodule's `examples/` (match example→schema by `formatVersion` field; `.docu.` files route to the docu companion schema). Emit-side round-trip tests that pass handler-emitted metadata through `affValidate` land with the generic emitters in Waves 1–3 (`tests/aff/generic-roundtrip.test.ts`).
+- [ ] 0.4a Route `.reps.`/`.func.` LIMU sub-object examples to their nested schemas (`fugr/func-v1.json` etc.) — currently counted but not schema-validated.
 - [x] 0.5 `aff-coverage` nx target on `adt-plugin-gcts` — emits `type × [handler-kind, versions, body-fields, examples, schema-validated]` matrix; fails under threshold.
 
 ## 1. Enrich stubs — AFF families (Wave 1)

packages/adt-plugin-gcts/src/lib/deserializer.ts

@@ -29,8 +29,19 @@ import { createAdk, type AdkObject, type AdtClient } from '@abapify/adk';
 import { getHandler, getSupportedTypes } from './handlers/base';
 import { parseGctsFilename, PACKAGE_FILENAME } from './format/filename';
 
-/** Source-file extensions emitted by gCTS handlers. */
-const SOURCE_EXTENSIONS = new Set(['abap', 'asddls', 'asdcls']);
+/** Source-file extensions emitted by gCTS handlers. `.properties`
+ * translation files are deliberately excluded — they are companions
+ * routed into `data.properties`, never ABAP source staging. */
+const SOURCE_EXTENSIONS = new Set([
+  'abap',
+  'asddls',
+  'asdcls',
+  'acds',
+  'abdl',
+  'csn',
+  'xdp',
+  'ddic',
+]);
 
 /**
  * Map numeric abapLanguageVersion codes (`'5'` etc.) to the descriptive
@@ -53,6 +64,10 @@ interface ObjectFiles {
   type: string;
   metadataFile?: string;
   sourceFiles: Array<{ path: string; suffix?: string }>;
+  /** `{name}.{type}.{docu}.json` companion — not the metadata anchor. */
+  docuFile?: string;
+  /** `.properties` translations keyed by suffix (`en`, `texts.en`, `''`). */
+  propertyFiles: Array<{ path: string; suffix?: string }>;
 }
 
 /**
@@ -98,9 +113,27 @@ export async function* deserialize(
         name: parsed.name.toUpperCase(),
         type: parsed.type.toUpperCase(),
         sourceFiles: [],
+        propertyFiles: [],
       });
     }
-    objectMap.get(key)!.metadataFile = jsonPath;
+    // `{name}.{type}.docu.json` is a DOCU companion, not a second
+    // metadata anchor — without this it can overwrite metadataFile
+    // depending on glob order.
+    if (parsed.suffix === 'docu') {
+      objectMap.get(key)!.docuFile = jsonPath;
+    } else {
+      objectMap.get(key)!.metadataFile = jsonPath;
+    }
+  }
+
+  // `.properties` translation companions — routed into `data.properties`
+  // so they round-trip through metadata, not source staging.
+  for (const path of await fileTree.glob('**/*.properties')) {
+    const filename = path.split('/').pop()!;
+    const parsed = parseGctsFilename(filename);
+    if (!parsed) continue;
+    const key = `${parsed.name.toUpperCase()}:${parsed.type.toUpperCase()}`;
+    objectMap.get(key)?.propertyFiles.push({ path, suffix: parsed.suffix });
   }
 
   // Collect every source file (.abap/.asddls/.asdcls) and group by name:type.
@@ -119,6 +152,38 @@ export async function* deserialize(
     }
   }
 
+  // Pre-read all companion contents in bounded batches — sequential
+  // `await`s inside the object loop both serialize I/O and trip static
+  // analysis, while an unbounded Promise.all over thousands of files can
+  // exhaust file descriptors (EMFILE). Per-path failures are recorded
+  // (not thrown) so one unreadable file fails only its owning object
+  // inside the per-object try/catch below.
+  const companionContents = new Map<string, string>();
+  const readErrors = new Map<string, unknown>();
+  const companionPaths = [...objectMap.values()].flatMap((o) => [
+    ...(o.docuFile ? [o.docuFile] : []),
+    ...o.propertyFiles.map((f) => f.path),
+    ...o.sourceFiles.map((f) => f.path),
+  ]);
+  const READ_BATCH = 32;
+  let cursor = 0;
+  const readNext = async (): Promise<void> => {
+    const path = companionPaths[cursor++];
+    if (path === undefined) return;
+    try {
+      companionContents.set(path, await fileTree.read(path));
+    } catch (error) {
+      readErrors.set(path, error);
+    }
+    return readNext();
+  };
+  await Promise.all(
+    Array.from(
+      { length: Math.min(READ_BATCH, companionPaths.length) },
+      readNext,
+    ),
+  );
+
   for (const [, objFiles] of objectMap) {
     if (!objFiles.metadataFile) continue;
 
@@ -131,10 +196,21 @@ export async function* deserialize(
       // metadata passed to fromMetadata.
       const metadata = handler.schema.parse(raw);
 
+      // Surface any companion read failure here, inside the per-object
+      // try — one bad file fails only this object, not the generator.
+      for (const path of [
+        ...(objFiles.docuFile ? [objFiles.docuFile] : []),
+        ...objFiles.propertyFiles.map((f) => f.path),
+        ...objFiles.sourceFiles.map((f) => f.path),
+      ]) {
+        if (readErrors.has(path)) throw readErrors.get(path);
+      }
+
       // Read sources, mapping suffix → source key via handler map.
       const sources: Record<string, string> = {};
       for (const { path, suffix } of objFiles.sourceFiles) {
-        const content = await fileTree.read(path);
+        const content = companionContents.get(path);
+        if (content === undefined) continue;
         const sourceKey = suffix
           ? (handler.suffixToSourceKey?.[suffix] ?? suffix)
           : 'main';
@@ -149,6 +225,29 @@ export async function* deserialize(
         ? handler.fromAbapGit(metadata)
         : { name: objFiles.name };
 
+      // DOCU companion → `data.docu` (genericGetExtraFiles re-emits it).
+      const docuRaw = objFiles.docuFile
+        ? companionContents.get(objFiles.docuFile)
+        : undefined;
+      if (docuRaw !== undefined) {
+        try {
+          payload.docu = JSON.parse(docuRaw) as unknown;
+        } catch {
+          payload.docu = docuRaw;
+        }
+      }
+
+      // `.properties` translations → `data.properties` keyed by suffix
+      // ('' = master file, 'en', 'texts.en', …).
+      if (objFiles.propertyFiles.length > 0) {
+        const props: Record<string, string> = {};
+        for (const { path, suffix } of objFiles.propertyFiles) {
+          const content = companionContents.get(path);
+          if (content !== undefined) props[suffix ?? ''] = content;
+        }
+        payload.properties = props;
+      }
+
       // AFF metadata frequently omits the object name (it's encoded in the
       // filename). Fall back to the filename-derived name.
       const objectName = payload.name || objFiles.name;

packages/adt-plugin-gcts/src/lib/format/filename.ts

@@ -31,6 +31,19 @@
   DCLS: 'asdcls',
   BDEF: 'abdl',
   SRVD: 'acds',
+  // AFF-`.acds` CDS-family sources (upstream examples are uniform:
+  // `<name>.<type>.acds` for every CDS-bearing type).
+  DDLA: 'acds',
+  DDLX: 'acds',
+  DTSC: 'acds',
+  DTIX: 'acds',
+  DTEB: 'acds',
+  DTDC: 'acds',
+  DRAS: 'acds',
+  DRTY: 'acds',
+  DSFD: 'acds',
+  CSNM: 'csn',
+  SFPF: 'xdp',
 };
 
 /** Metadata extension for all AFF/gCTS objects. */
@@ -64,6 +77,19 @@
     : `${base}.${typeLower}.${ext}`;
 }
 
+/** Source/companion extensions recognised by the spec file-name grammar. */
+const KNOWN_SOURCE_EXTS = new Set([
+  'abap',
+  'asddls',
+  'asdcls',
+  'abdl',
+  'acds',
+  'csn',
+  'xdp',
+  'ddic',
+  'properties',
+]);
+
 /**
  * Parse an AFF/gCTS filename back into its components.
  *
@@ -75,62 +101,88 @@
 ): ParsedFormatFilename | undefined {
   // Fixed package filename.
   if (filename === PACKAGE_FILENAME) {
-    return {
-      name: '',
-      type: 'DEVC',
-      extension: METADATA_EXTENSION,
-    };
+    return { name: '', type: 'DEVC', extension: METADATA_EXTENSION };
   }
 
   const parts = filename.split('.');
-  if (parts.length < 3) {
-    return undefined;
-  }
+  if (parts.length < 3) return undefined;
 
   const extension = parts.at(-1)!;
-  const maybeSuffix = parts.length >= 4 ? parts.at(-2) : undefined;
-  const nameParts = maybeSuffix ? parts.slice(0, -3) : parts.slice(0, -2);
+  if (extension === METADATA_EXTENSION) return parseMetadataName(parts);
+  if (extension === 'properties') return parsePropertiesName(parts);
+  return parseSourceName(parts, extension);
+}
 
-  if (nameParts.length === 0) {
-    return undefined;
+/**
+ * `{name}.{type}.json` metadata files, plus the DOCU companion form
+ * `{name}.{type}.docu.json` which belongs to the parent object.
+ */
+function parseMetadataName(parts: string[]): ParsedFormatFilename {
+  if (parts.at(-2) === 'docu' && parts.length >= 4) {
+    return {
+      name: parts.slice(0, -3).join('.'),
+      type: parts.at(-3)!.toUpperCase(),
+      suffix: 'docu',
+      extension: METADATA_EXTENSION,
+    };
   }
+  return {
+    name: parts.slice(0, -2).join('.'),
+    type: parts.at(-2)!.toUpperCase(),
+    extension: METADATA_EXTENSION,
+  };
+}
 
-  // For 3-part filenames (name.type.ext) the "maybeSuffix" branch would
-  // misclassify a 4-part filename vs a 3-part filename. Use a recognised
-  // source extension to decide: if ext is 'json' there can't be a suffix.
-  if (extension === METADATA_EXTENSION) {
+/**
+ * `.properties` text files have their own grammar:
+ *   {name}.{type}.properties                        — master (3 parts)
+ *   {name}.{type}.{lang}.properties                 — language (4 parts)
+ *   {name}.{type}.{content_type}.{lang}.properties  — e.g. PROG
+ *   selections/headings/texts (5 parts)
+ * The composite suffix (`de`, `texts.en`) stays opaque — handlers map
+ * suffixes to source keys via `suffixToSourceKey`.
+ */
+function parsePropertiesName(parts: string[]): ParsedFormatFilename {
+  if (parts.length >= 5) {
     return {
-      name: nameParts.length === 0 ? '' : parts.slice(0, -2).join('.'),
-      type: parts.at(-2)!.toUpperCase(),
-      extension,
+      name: parts.slice(0, -4).join('.'),
+      type: parts.at(-4)!.toUpperCase(),
+      suffix: `${parts.at(-3)}.${parts.at(-2)}`,
+      extension: 'properties',
     };
   }
-
-  // Source file — suffix is optional.
-  const knownSourceExts = new Set([
-    'abap',
-    'asddls',
-    'asdcls',
-    'abdl',
-    'acds',
-    'properties',
-  ]);
-  if (!knownSourceExts.has(extension)) {
-    return undefined;
+  if (parts.length === 4) {
+    return {
+      name: parts.slice(0, -3).join('.'),
+      type: parts.at(-3)!.toUpperCase(),
+      suffix: parts.at(-2),
+      extension: 'properties',
+    };
   }
+  return {
+    name: parts.slice(0, -2).join('.'),
+    type: parts.at(-2)!.toUpperCase(),
+    extension: 'properties',
+  };
+}
 
-  // Detect suffix: the part before the extension is a suffix only if the part
-  // before THAT is a valid-looking lowercase type code. Use a narrow heuristic:
-  // suffix present iff parts.length >= 4.
+/**
+ * `{name}.{type}.{ext}` and `{name}.{type}.{suffix}.{ext}` source files —
+ * a suffix is present iff there are ≥4 dot-segments.
+ */
+function parseSourceName(
+  parts: string[],
+  extension: string,
+): ParsedFormatFilename | undefined {
+  if (!KNOWN_SOURCE_EXTS.has(extension)) return undefined;
   if (parts.length >= 4) {
     return {
       name: parts.slice(0, -3).join('.'),
       type: parts.at(-3)!.toUpperCase(),
       suffix: parts.at(-2),
       extension,
     };
   }
-
   return {
     name: parts.slice(0, -2).join('.'),
     type: parts.at(-2)!.toUpperCase(),

packages/adt-plugin-gcts/src/lib/format/i18n.ts

@@ -43,11 +43,34 @@ export function propertiesFilename(
   name: string,
   type: string,
   language?: string,
+  contentType?: string,
 ): string {
+  // A content-type segment without a language would emit the ambiguous
+  // 4-part `{name}.{type}.{ct}.properties`, which reparses as a language
+  // file — the AFF grammar only defines 3-, 4- (lang) and 5-part forms.
+  if (contentType && !language) {
+    throw new Error(
+      'propertiesFilename: contentType requires a language — ' +
+        'the 4-part `{name}.{type}.{content_type}.properties` form is ambiguous',
+    );
+  }
+  // Filename segments are dot-separated — a dotted value would parse back
+  // with a different suffix/language than it was emitted with.
+  for (const [label, seg] of [
+    ['contentType', contentType],
+    ['language', language],
+  ] as const) {
+    if (seg?.includes('.')) {
+      throw new Error(
+        `propertiesFilename: ${label} must be a single filename segment, got "${seg}"`,
+      );
+    }
+  }
   const base = gctsFilename(name, type, 'metadata').replace(/\.json$/, '');
-  return language
-    ? `${base}.${language.toLowerCase()}.properties`
-    : `${base}.properties`;
+  const segments = [base];
+  if (contentType) segments.push(contentType.toLowerCase());
+  if (language) segments.push(language.toLowerCase());
+  return `${segments.join('.')}.properties`;
 }
 
 /**
@@ -57,18 +80,23 @@ export function propertiesFilename(
  * @param type        ABAP object type code
  * @param translations Map of language code → entries. The key '' (empty
  *                    string) represents the master / default language.
+ * @param contentType  Optional content-type segment (e.g. `texts`,
+ *                    `selections`, `headings`) — emits the 5-part
+ *                    `{name}.{type}.{content_type}.{lang}.properties`
+ *                    form and therefore requires a non-empty language key.
  */
 export function createPropertiesFiles(
   name: string,
   type: string,
   translations: Record<string, TranslationEntry[]>,
+  contentType?: string,
 ): PropertiesFile[] {
   const files: PropertiesFile[] = [];
   for (const [lang, entries] of Object.entries(translations)) {
     if (!entries || entries.length === 0) continue;
     const path = lang
-      ? propertiesFilename(name, type, lang)
-      : propertiesFilename(name, type);
+      ? propertiesFilename(name, type, lang, contentType)
+      : propertiesFilename(name, type, undefined, contentType);
     files.push({ path, content: buildProperties(entries) });
   }
   return files;