Add validation for select metadata fields.

Author: tjprescott

scripts/api_md_workflow/adapters/python.js

@@ -121,10 +121,15 @@ function generateApiForPackage({
   });
 }
 
+// Fields in API.metadata.yml that must match between working tree and committed version.
+// pythonVersion is excluded because it varies across CI environments.
+const metadataFieldsToValidate = ["apiMdSha256", "parserVersion"];
+
 module.exports = {
   name: "python",
   isPackageDir,
   findPackageDir,
   readVersion,
   generateApiForPackage,
+  metadataFieldsToValidate,
 };

scripts/api_md_workflow/create_api_review_pr.js

@@ -173,6 +173,14 @@ function apiMdRel(packageDir) {
   return `${packageRelDir(packageDir)}/API.md`;
 }
 
+function metadataPath(packageDir) {
+  return path.join(packageDir, "API.metadata.yml");
+}
+
+function metadataRel(packageDir) {
+  return `${packageRelDir(packageDir)}/API.metadata.yml`;
+}
+
 function findRealGitExe() {
   if (process.platform !== "win32") {
     return null;
@@ -389,7 +397,14 @@ function generateApiBytesForPackage({
     throw new Error(`ERROR: did not produce ${outputPath}`);
   }
 
-  return fs.readFileSync(outputPath);
+  const result = { apiMd: fs.readFileSync(outputPath), metadata: null };
+
+  const metaPath = metadataPath(packageDir);
+  if (fs.existsSync(metaPath)) {
+    result.metadata = fs.readFileSync(metaPath);
+  }
+
+  return result;
 }
 
 function main() {
@@ -415,11 +430,11 @@ function main() {
   const targetRef = args.target ? resolveTargetRef(args.target) : MAIN_REF;
 
   try {
-    let baseApiBytes = null;
+    let baseResult = null;
     if (args.base) {
       logInfo(`\n=== Capturing baseline API.md from tag ${args.base} ===`);
       git(["checkout", "--detach", args.base]);
-      baseApiBytes = generateApiBytesForPackage({
+      baseResult = generateApiBytesForPackage({
         adapter,
         repoRoot: REPO_ROOT,
         packageName: args.packageName,
@@ -434,7 +449,7 @@ function main() {
     logInfo(`\n=== Capturing target API.md from ${targetRef} ===`);
     git(["checkout", "--detach", targetRef]);
     const targetVersion = adapter.readVersion(packageDir);
-    const targetApiBytes = generateApiBytesForPackage({
+    const targetResult = generateApiBytesForPackage({
       adapter,
       repoRoot: REPO_ROOT,
       packageName: args.packageName,
@@ -453,10 +468,16 @@ function main() {
 
     const apiPath = apiMdPath(packageDir);
     const apiRelative = apiMdRel(packageDir);
+    const metaFilePath = metadataPath(packageDir);
+    const metaRelative = metadataRel(packageDir);
 
-    if (baseApiBytes !== null) {
-      writeBytes(apiPath, baseApiBytes);
+    if (baseResult !== null) {
+      writeBytes(apiPath, baseResult.apiMd);
       git(["add", apiRelative]);
+      if (baseResult.metadata) {
+        writeBytes(metaFilePath, baseResult.metadata);
+        git(["add", metaRelative]);
+      }
       git(["commit", "-m", `[API Review] Baseline API.md for ${args.packageName} ${baseVersion}`]);
     } else {
       const tracked = git(["ls-files", "--error-unmatch", apiRelative], {
@@ -466,11 +487,21 @@ function main() {
 
       if (tracked.status === 0) {
         git(["rm", apiRelative]);
+        const metaTracked = git(["ls-files", "--error-unmatch", metaRelative], {
+          capture: true,
+          check: false,
+        });
+        if (metaTracked.status === 0) {
+          git(["rm", metaRelative]);
+        }
         git(["commit", "-m", `[API Review] Remove API.md for ${args.packageName} (empty baseline)`]);
       } else {
         if (fs.existsSync(apiPath)) {
           fs.unlinkSync(apiPath);
         }
+        if (fs.existsSync(metaFilePath)) {
+          fs.unlinkSync(metaFilePath);
+        }
         git(["commit", "--allow-empty", "-m", `[API Review] Empty baseline for ${args.packageName}`]);
       }
     }
@@ -479,8 +510,12 @@ function main() {
 
     logInfo(`\n=== Creating review branch ${reviewBranch} ===`);
     git(["checkout", "-B", reviewBranch, baseBranch]);
-    writeBytes(apiPath, targetApiBytes);
+    writeBytes(apiPath, targetResult.apiMd);
     git(["add", apiRelative]);
+    if (targetResult.metadata) {
+      writeBytes(metaFilePath, targetResult.metadata);
+      git(["add", metaRelative]);
+    }
 
     const diff = git(["diff", "--cached", "--quiet"], {
       capture: true,

scripts/api_md_workflow/find_mismatches.js

@@ -3,8 +3,31 @@
 const fs = require("fs");
 
 const { appendGithubOutput, envPath, getDefaultLogger, readLines, runAsync, writeLines } = require("./common");
+const { loadAdapter, loadWorkflowConfig } = require("./adapter_config");
+
+/**
+ * Parse a simple key: value YAML file into an object.
+ * Only handles flat scalar mappings (no nesting, no multi-line values).
+ */
+function parseSimpleYaml(text) {
+  const result = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.match(/^(\w+)\s*:\s*(.*)$/);
+    if (match) {
+      result[match[1]] = match[2].trim();
+    }
+  }
+  return result;
+}
 
 async function main() {
+  const config = loadWorkflowConfig();
+  const adapter = loadAdapter(config.adapter);
+
+  // Fields to compare in API.metadata.yml. If the adapter doesn't specify,
+  // compare all fields (strict default for languages that don't opt out).
+  const fieldsToValidate = adapter.metadataFieldsToValidate || null;
+
   const packagesFile = envPath("API_MD_PACKAGES_FILE", ".artifacts/affected_package_dirs.txt");
   const mismatchesFile = envPath("API_MD_MISMATCHES_FILE", ".artifacts/mismatched_api_files.txt");
   const missingFile = envPath("API_MD_MISSING_FILE", ".artifacts/missing_api_files.txt");
@@ -13,9 +36,8 @@ async function main() {
   const mismatches = [];
   const missing = [];
   for (const pkgDir of packages) {
-    // Deliberately scope consistency gating to API.md only.
-    // API.metadata.yml is generated sidecar metadata and is not diff-gated here.
     const apiFile = `${pkgDir}/API.md`;
+    const metadataFile = `${pkgDir}/API.metadata.yml`;
 
     // Enforce that each affected package has a committed API.md file.
     if (!fs.existsSync(apiFile) || !fs.statSync(apiFile).isFile()) {
@@ -31,6 +53,30 @@ async function main() {
       continue;
     }
 
+    // API.metadata.yml must be present alongside API.md.
+    if (!fs.existsSync(metadataFile) || !fs.statSync(metadataFile).isFile()) {
+      missing.push(metadataFile);
+    } else {
+      const committedMeta = await runAsync("git", ["show", `HEAD:${metadataFile}`], {
+        check: false,
+      });
+      if (committedMeta.status !== 0) {
+        // Not yet committed — treat as missing
+        missing.push(metadataFile);
+      } else {
+        const current = parseSimpleYaml(fs.readFileSync(metadataFile, "utf-8"));
+        const committed = parseSimpleYaml(committedMeta.stdout);
+
+        // Compare only adapter-specified fields, or all fields if not specified.
+        const keys = fieldsToValidate || Object.keys({ ...committed, ...current });
+        const mismatch = keys.some((key) => current[key] !== committed[key]);
+        if (mismatch) {
+          mismatches.push(metadataFile);
+        }
+      }
+    }
+
+    // Diff-gate only API.md; metadata content differences are acceptable.
     const quietDiffResult = await runAsync("git", ["diff", "--quiet", "--", apiFile], {
       check: false,
     });