Guard release workflow tag docs

Author: AbrahamGreenman

.github/workflows/ray-core-release.yml

@@ -4,7 +4,7 @@ name: "@razroo/ray-core Release to npm"
 #
 # Cutting a release (after bumping packages/core/package.json version):
 #   TAG="core-v$(bun -e 'console.log(require("./packages/core/package.json").version)')"
-#   git tag "$TAG" && git push origin "$TAG"
+#   git tag -a "$TAG" -m "Release $TAG (@razroo/ray-core)" && git push origin "$TAG"
 #   gh release create "$TAG" --generate-notes --title "$TAG"
 
 on:

.github/workflows/ray-sdk-release.yml

@@ -5,7 +5,7 @@ name: "@razroo/ray-sdk Release to npm"
 #
 # Cutting a release (after bumping packages/sdk/package.json version):
 #   TAG="sdk-v$(bun -e 'console.log(require("./packages/sdk/package.json").version)')"
-#   git tag "$TAG" && git push origin "$TAG"
+#   git tag -a "$TAG" -m "Release $TAG (@razroo/ray-sdk)" && git push origin "$TAG"
 #   gh release create "$TAG" --generate-notes --title "$TAG"
 
 on:

scripts/package-runtime-coverage.test.ts

@@ -1103,6 +1103,51 @@ test("validatePackageRuntimeCoverage requires bounded npm release workflow comma
   assert.ok(codes.includes("workflow_npm_publish_timeout_missing"));
 });
 
+test("validatePackageRuntimeCoverage rejects lightweight release tag workflow comments", async (t) => {
+  const tempDir = await mkdtemp(path.join(tmpdir(), "ray-package-runtime-release-tag-docs-"));
+  t.after(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+  const workflowDir = path.join(tempDir, ".github", "workflows");
+  await mkdir(workflowDir, { recursive: true });
+  await writeFile(
+    path.join(workflowDir, "ray-core-release.yml"),
+    [
+      'name: "@razroo/ray-core Release to npm"',
+      '#   TAG="core-v$(bun -e \'console.log(require("./packages/core/package.json").version)\')"',
+      '#   git tag "$TAG" && git push origin "$TAG"',
+      "jobs:",
+      "  publish:",
+      "    if: github.repository == 'razroo/ray'",
+      "    runs-on: ubuntu-latest",
+      "    timeout-minutes: 60",
+      "    permissions:",
+      "      id-token: write",
+      "    steps:",
+      "      - run: timeout 120s git fetch --no-tags --prune origin main:refs/remotes/origin/main",
+      '      - run: git merge-base --is-ancestor "$SHA" refs/remotes/origin/main',
+      "      - run: timeout 300s npm publish ./pkg.tgz --access public --provenance",
+      "        env:",
+      "          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}",
+      "",
+    ].join("\n"),
+  );
+
+  const summary = await validatePackageRuntimeCoverage({
+    cwd: tempDir,
+    packageJsonPaths: [],
+  });
+  const diagnostics = summary.results.flatMap((result) => result.diagnostics);
+
+  assert.equal(summary.ok, false);
+  assert.ok(
+    diagnostics.some(
+      (diagnostic) =>
+        diagnostic.code === "workflow_npm_release_lightweight_tag_doc" && diagnostic.line === 3,
+    ),
+  );
+});
+
 test("validatePackageRuntimeCoverage requires bounded quality release gate workflow commands", async (t) => {
   const tempDir = await mkdtemp(path.join(tmpdir(), "ray-package-runtime-quality-timeouts-"));
   t.after(async () => {

scripts/package-runtime-coverage.ts

@@ -69,6 +69,7 @@ const workflowReleaseMainAncestryPattern =
   /git\s+merge-base\s+--is-ancestor\s+"\$SHA"\s+refs\/remotes\/origin\/main/;
 const workflowIdTokenWritePattern = /^\s*id-token:\s*write\s*$/m;
 const workflowNpmTokenPattern = /NODE_AUTH_TOKEN:\s*\$\{\{\s*secrets\.NPM_TOKEN\s*\}\}/;
+const workflowLightweightReleaseTagCommentPattern = /^\s*#\s*git\s+tag\s+"\$TAG"(?:\s|$)/;
 const repoOwnedVpsWorkflowDocPattern =
   /\b(?:GitHub VPS workflow|workflow bootstrap|workflow appends|RAY_ENV_FILE_CONTENTS|repository variables|The deploy workflow)\b/;
 
@@ -1848,6 +1849,32 @@ function validateDeployWorkflowRayEnvReadGuards(
   return diagnostics;
 }
 
+function validateNpmReleaseWorkflowTagDocs(
+  workflowPath: string,
+  publishesToNpm: boolean,
+  lines: string[],
+): PackageRuntimeCoverageDiagnostic[] {
+  if (!publishesToNpm) {
+    return [];
+  }
+
+  const diagnostics: PackageRuntimeCoverageDiagnostic[] = [];
+  for (const [index, rawLine] of lines.entries()) {
+    if (workflowLightweightReleaseTagCommentPattern.test(rawLine)) {
+      diagnostics.push({
+        level: "error",
+        code: "workflow_npm_release_lightweight_tag_doc",
+        workflowPath,
+        line: index + 1,
+        message:
+          "npm release workflow cutting comments must use annotated git tags so operator docs do not recommend lightweight release tags.",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
 async function validateWorkflow(
   workflowPath: string,
 ): Promise<{ lineCount: number; diagnostics: PackageRuntimeCoverageDiagnostic[] }> {
@@ -1913,6 +1940,8 @@ async function validateWorkflow(
     });
   }
 
+  diagnostics.push(...validateNpmReleaseWorkflowTagDocs(workflowPath, publishesToNpm, lines));
+
   if (runsReleaseGate && !hasJobTimeout) {
     diagnostics.push({
       level: "error",