release-skill 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/schemas/.render-manifest.json

@@ -26,8 +26,8 @@
       "bytes": 35256
     },
     "release-project.schema.json": {
-      "digest": "a3d46be1e1e8105103a505c6d58d14f3733c8da91ab8289e097ffd259bf1cd93",
-      "bytes": 30982
+      "digest": "7ac18070ac41327a330ca35e32f466e3f2a8eb2b7df3a5755568e00f991ffdc1",
+      "bytes": 32497
     },
     "release-run.schema.json": {
       "digest": "bf3c8fb4ca2fc078272a45a6ee6bf663fd2420a722b2f995dbaabf2635e2179e",

package/schemas/release-project.schema.json

@@ -455,6 +455,9 @@
               ]
             }
           },
+          "expectedPublicSurface": {
+            "$ref": "#/definitions/expectedPublicSurface"
+          },
           "publicFiles": {
             "type": "array",
             "minItems": 1,
@@ -761,6 +764,63 @@
     }
   },
   "definitions": {
+    "expectedPublicSurface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "scanRoots"
+      ],
+      "properties": {
+        "scanRoots": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/publicSurfaceScanRoot"
+          }
+        }
+      }
+    },
+    "publicSurfaceScanRoot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "include",
+        "exclude"
+      ],
+      "properties": {
+        "sourceScope": {
+          "type": "string",
+          "enum": [
+            "unit",
+            "workspace"
+          ],
+          "default": "unit"
+        },
+        "root": {
+          "type": "string",
+          "minLength": 1,
+          "default": ".",
+          "pattern": "^(?:\\.$|(?!\\/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(?:\\/|$))(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/\\/$)(?!.*\\/$).*)$"
+        },
+        "include": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "exclude": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
     "hook": {
       "type": "object",
       "required": [

package/src/commands/prepare.mjs

@@ -29,6 +29,7 @@ import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
 import { runHook } from '../core/hooks.mjs';
 import { computeHookCacheKey, readHookCache, writeHookCache } from '../core/hook-cache.mjs';
+import { assertExpectedPublicSurface } from '../core/public-surface.mjs';
 import { runSnapshotVerificationGates } from '../core/verification-gates.mjs';
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import { computePlanDigest, writePlanAtomic, writePlanImmutable } from '../core/plan.mjs';
@@ -1925,6 +1926,51 @@ export async function prepareRelease(options) {
       });
     }
 
+    // --- Step 3b.1: Validate the post-build expected public surface ---
+    // This gate runs after every declared hook (and the post-hook docs check)
+    // but before source-authority closure, baseline, snapshots, remote reads,
+    // and plan write. Therefore build-generated files must be explicitly
+    // classified and every included source must already exist in publicFiles
+    // before downstream authorities bind the release inputs.
+    for (const unit of configUnits) {
+      if (!unit?.expectedPublicSurface) continue;
+      await evidence.append({
+        phase: 'public-surface',
+        status: 'started',
+        unitId: unit.id,
+      });
+      try {
+        const surface = await assertExpectedPublicSurface({
+          root: realRoot,
+          unit,
+        });
+        await evidence.append({
+          phase: 'public-surface',
+          status: 'completed',
+          unitId: unit.id,
+          ...surface.summary,
+        });
+      } catch (error) {
+        await evidence.append({
+          phase: 'public-surface',
+          status: 'failed',
+          unitId: unit.id,
+          reason: error.details?.reason ?? 'PUBLIC_SURFACE_CHECK_FAILED',
+          error: {
+            code: error.code,
+            message: error.message,
+          },
+          diagnostics: {
+            missingMappings: error.details?.missingMappings ?? [],
+            unexpectedMappings: error.details?.unexpectedMappings ?? [],
+            unclassifiedFiles: error.details?.unclassifiedFiles ?? [],
+            ambiguousFiles: error.details?.ambiguousFiles ?? [],
+          },
+        });
+        throw error;
+      }
+    }
+
     // --- Step 3c: Source authority content closure gate ---
     // After hooks complete, compute the deterministic source-input closure
     // and verify that closure inputs are clean (no staged/unstaged/untracked

package/src/core/config.mjs

@@ -23,6 +23,7 @@ import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { canonicalJson, sha256Hex } from './digest.mjs';
 import { ReleaseError, CONFIG_INVALID } from './errors.mjs';
+import { validatePublicSurfaceGlob } from './public-surface.mjs';
 import { canonicalPublicPath, publicPathCollisionKey } from '../snapshot/public-path.mjs';
 import { isReservedReleaseControlPath } from './baseline.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
@@ -294,6 +295,53 @@ export async function loadProjectConfig({ root, configPath } = {}) {
       );
     }
 
+    // Validate expected public-surface roots and the deliberately small glob
+    // language before generic schema validation so diagnostics identify the
+    // exact unit, scan root, and pattern.
+    const surface = unit.expectedPublicSurface;
+    if (surface && typeof surface === 'object' && Array.isArray(surface.scanRoots)) {
+      for (const [rootIndex, scanRoot] of surface.scanRoots.entries()) {
+        if (!scanRoot || typeof scanRoot !== 'object') continue;
+        if (typeof scanRoot.root === 'string') {
+          try {
+            canonicalPublicPath(scanRoot.root, { allowDot: true });
+          } catch (err) {
+            throw new ReleaseError(
+              CONFIG_INVALID,
+              `unit "${unit.id}" has invalid expectedPublicSurface scan root: ${err.message}`,
+              {
+                unitId: unit.id,
+                rootIndex,
+                root: scanRoot.root,
+                field: 'expectedPublicSurface.scanRoots[].root',
+              },
+            );
+          }
+        }
+        for (const field of ['include', 'exclude']) {
+          if (!Array.isArray(scanRoot[field])) continue;
+          for (const pattern of scanRoot[field]) {
+            if (typeof pattern !== 'string') continue;
+            try {
+              validatePublicSurfaceGlob(pattern);
+            } catch (err) {
+              throw new ReleaseError(
+                CONFIG_INVALID,
+                `unit "${unit.id}" has invalid expectedPublicSurface ${field} glob: ${err.message}`,
+                {
+                  unitId: unit.id,
+                  rootIndex,
+                  pattern,
+                  field: `expectedPublicSurface.scanRoots[].${field}`,
+                  reason: err.details?.reason ?? 'PUBLIC_SURFACE_GLOB_INVALID',
+                },
+              );
+            }
+          }
+        }
+      }
+    }
+
     // Validate publicFiles[].from and .to
     if (Array.isArray(unit.publicFiles)) {
       for (const mapping of unit.publicFiles) {