release-skill 0.2.7 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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/assess.mjs

@@ -23,6 +23,7 @@ import { promisify } from 'node:util';
 
 import { loadProjectConfig } from '../core/config.mjs';
 import { ReleaseError, CONFIG_INVALID, GATE_FAILED } from '../core/errors.mjs';
+import { collectExpectedPublicSurfaceAdoptionWarnings } from '../core/public-surface.mjs';
 
 const execFile = promisify(execFileCb);
 
@@ -880,23 +881,35 @@ export async function assessProject(options) {
   // --- 2. Topology identification ---
   const topology = identifyTopology(config);
 
-  // --- 3. Common docs check ---
+  // --- 3. Expected public-surface adoption ---
+  for (const warning of collectExpectedPublicSurfaceAdoptionWarnings(config)) {
+    allGaps.push(createGap({
+      scope: GapScope.PROJECT,
+      category: GapCategory.POLICY,
+      severity: Severity.WARNING,
+      code: warning.code,
+      message: warning.message,
+      file: '.release-skill/project.yaml',
+    }));
+  }
+
+  // --- 4. Common docs check ---
   const docGaps = await checkCommonDocs(root, config);
   allGaps.push(...docGaps);
 
-  // --- 4. Plugin manifest check ---
+  // --- 5. Plugin manifest check ---
   const manifestGaps = await checkPluginManifests(root, config);
   allGaps.push(...manifestGaps);
 
-  // --- 5. Package metadata check ---
+  // --- 6. Package metadata check ---
   const metadataGaps = await checkPackageMetadata(root, config);
   allGaps.push(...metadataGaps);
 
-  // --- 6. Remote prerequisites ---
+  // --- 7. Remote prerequisites ---
   const remoteGaps = await checkRemotePrerequisites(root, config, offline);
   allGaps.push(...remoteGaps);
 
-  // --- 7. README structure check ---
+  // --- 8. README structure check ---
   const readmeGaps = await checkReadmeStructure(root, config);
   allGaps.push(...readmeGaps);
 

package/src/commands/prepare.mjs

@@ -29,6 +29,10 @@ 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,
+  collectExpectedPublicSurfaceAdoptionWarnings,
+} 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';
@@ -1669,7 +1673,7 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
  *   every declared hook runs in full and the incremental hook cache is neither
  *   read nor written.
  *
- * @returns {Promise<{ planPath: string, planDigest: string, evidenceDir: string }>}
+ * @returns {Promise<{ planPath: string, planDigest: string, evidenceDir: string, warnings: ReadonlyArray<object> }>}
  *
  * @throws {ReleaseError} on any gate failure. No PREPARED plan is written.
  */
@@ -1749,6 +1753,7 @@ export async function prepareRelease(options) {
     await evidence.append({ phase: 'config', status: 'started' });
 
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
 
     await evidence.append({
       phase: 'config',
@@ -1756,6 +1761,13 @@ export async function prepareRelease(options) {
       configPath: relative(realRoot, configPath),
       configDigest,
     });
+    for (const warning of adoptionWarnings) {
+      await evidence.append({
+        phase: 'public-surface-adoption',
+        status: 'warning',
+        ...warning,
+      });
+    }
 
     // --- Step 1b: Resolve authoritative versions and gate release-document
     //     freshness BEFORE hook authorization ---
@@ -1925,6 +1937,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
@@ -2867,6 +2924,7 @@ export async function prepareRelease(options) {
       planPath: writtenPath,
       planDigest,
       evidenceDir,
+      warnings: adoptionWarnings,
     };
   } catch (err) {
     // Record failure evidence

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) {