@cyd-prc/dsh-audit-chain 0.1.0 → 0.1.1

package/README.md

@@ -77,9 +77,32 @@ reads and leaves.
 ## Tests
 
 ```
-node --test test/core.test.mjs        # 32 tests, no dependencies
+node --test test/core.test.mjs        # 33 tests, no dependencies
 ```
 
+## Changelog
+
+### 0.1.1
+
+- **`ChainLog.readAll()`** — the reader shape the shape-guard side historically
+  used (`{ entries, corrupt }`), so the migration's adapter layer stays a pure
+  re-export.
+- **`verify-release` checks the root packument (M6, found by the test side).**
+  The version document and the tarball can both be 200 while
+  `npm install <name>` still fails — the root packument propagates later
+  (measured: ~2.5 minutes behind on a fresh package). A `--spec` verification is
+  no longer green in that window, and a `dist-tags.latest` mismatch is printed
+  as a note (verifying an older release is ordinary work).
+- **`verify-release` understands `bundleDependencies`.** Bundled copies leave
+  the tree comparison (they are someone else's package) but their versions are
+  the release's contract: each bundled copy must match an *exact* pin in
+  `dependencies` — a range makes the artifact's bytes depend on when it was
+  packed. This is the shape the three plugins' migration to this package takes.
+
+### 0.1.0
+
+- First cut, extracted from the two drifted copies. See the provenance section.
+
 The suite is the union of the anchors that pinned both historical
 implementations (entropy-guard defects 14/15/16/19/20, shape-guard I7–I13 /
 S1–S4), plus the byte-compatibility pin.

package/README.zh-CN.md

@@ -68,9 +68,27 @@ node tools/verify-release.mjs --spec @cyd-prc/dsh-audit-chain@<v> --run-tests --
 ## 测试
 
 ```
-node --test test/core.test.mjs        # 32 项，无依赖
+node --test test/core.test.mjs        # 33 项，无依赖
 ```
 
+## 变更节
+
+### 0.1.1
+
+- **`ChainLog.readAll()`**——shape-guard 一侧历史上使用的读取形状（`{ entries, corrupt }`），
+  迁移时的适配层因此是纯 re-export。
+- **`verify-release` 现在检查根 packument（M6，测试侧咬出）。** 版本文档与 tarball 都已 200 时
+  `npm install <name>` 仍可能失败——根文档传播更慢（实测：新包晚约 2.5 分钟）。这个窗口内
+  `--spec` 校验不再报绿；`dist-tags.latest` 与被验版本不一致时打印一条 note
+  （验旧版本是正常工作，不算失败）。
+- **`verify-release` 认识 `bundleDependencies`。** 内嵌副本退出树比较（那是别人家的包），
+  但它们的版本是本发布的契约：每个内嵌副本必须与 `dependencies` 里的**精确**钉版一致——
+  区间会让实件的字节取决于打包的时间。这正是三个插件迁移到本包时采取的形状。
+
+### 0.1.0
+
+- 首版，从两份漂移的副本抽出。见溯源节。
+
 套件是两份历史实现的锚的并集（entropy-guard 缺陷 14/15/16/19/20、shape-guard
 I7–I13 / S1–S4），外加字节兼容针。
 

package/lib/chain.js

@@ -466,6 +466,15 @@ export class ChainLog {
     return this._readAll().map((entry) => structuredClone(entry));
   }
 
+  /**
+   * Every entry plus the corrupt-line count — the reader shape the shape-guard
+   * side historically used (`readAll().entries`).
+   * @returns {{ entries: Record<string, unknown>[], corrupt: number }} the read.
+   */
+  readAll() {
+    return { entries: this.entries, corrupt: this.corruptLines };
+  }
+
   /** @returns {Record<string, unknown>[]} the cached read. */
   _readAll() {
     if (this.path !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyd-prc/dsh-audit-chain",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "The one tamper-evident JSONL audit chain every dsh guard shares: a multi-writer-safe writer (exclusive lock, fresh tail, torn-tail termination) and the chain-grading contract verifier. Extracted from dsh-entropy-guard and dsh-shape-guard, where the copies drifted; one chain, one implementation.",
   "type": "module",

package/test/core.test.mjs

@@ -33,6 +33,7 @@ import {
   verifyChain,
 } from '../index.js';
 import {
+  checkBundledDependencies,
   jsonEquivalent,
   looksLikeText,
   matchesReference,
@@ -339,6 +340,10 @@ describe('grading (the contract, pinned)', () => {
       assert.equal(reading.entries, 1);
       assert.equal(reading.corrupt, 1);
       assert.equal(reading.status, 'verified', 'clause 8: corrupt alone never grades hostile');
+      // The reader shape the shape-guard side historically used.
+      const all = new ChainLog(path).readAll();
+      assert.equal(all.entries.length, 1);
+      assert.equal(all.corrupt, 1);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -423,6 +428,28 @@ describe('release tooling', () => {
     assert.deepEqual(scanShippedReferences(artifact).unresolved, [{ file: 'lib/tool.mjs', reference: 'DESIGN-v1.md' }]);
   });
 
+  it('checks bundled dependencies against their exact pins', () => {
+    const manifest = {
+      bundleDependencies: ['@cyd-prc/dsh-audit-chain'],
+      dependencies: { '@cyd-prc/dsh-audit-chain': '0.1.0' },
+    };
+    const packed = (version) => readTarGz(buildTarGz({
+      'package/index.js': 'export {};\n',
+      'package/node_modules/@cyd-prc/dsh-audit-chain/package.json': JSON.stringify({ name: '@cyd-prc/dsh-audit-chain', version }),
+    }));
+    const ok = checkBundledDependencies(manifest, packed('0.1.0'));
+    assert.equal(ok.mismatches, 0);
+    assert.equal(ok.excluded.length, 1, 'the bundled copy leaves the tree comparison');
+    assert.equal(checkBundledDependencies(manifest, packed('0.0.9')).mismatches, 1, 'a drifted bundled copy fails');
+    const unpinned = checkBundledDependencies(
+      { bundleDependencies: ['x'], dependencies: { x: '^1.0.0' } },
+      readTarGz(buildTarGz({ 'package/index.js': '', 'package/node_modules/x/package.json': '{"name":"x","version":"1.2.3"}' })),
+    );
+    assert.equal(unpinned.mismatches, 1, 'a range makes the artifact non-deterministic');
+    const absent = checkBundledDependencies(manifest, readTarGz(buildTarGz({ 'package/index.js': '' })));
+    assert.equal(absent.mismatches, 1, 'a declared bundle missing from the artifact fails');
+  });
+
   it('names the tree HEAD it compared against', () => {
     const probe = spawnSync('git', ['rev-parse', '--short=7', 'HEAD'], { cwd: REPO_ROOT, encoding: 'utf8' });
     const expected = probe.status === 0 ? probe.stdout.trim() : null;

package/tools/verify-release.mjs

@@ -350,12 +350,24 @@ async function fetchArtifact(spec, waitSeconds = 0) {
         lastProblem = `${name}@${version} is not in the registry yet`;
       } else {
         const response = await fetch(tarball);
-        if (response.ok) {
-          const bytes = Buffer.from(await response.arrayBuffer());
-          const integrityOk = meta.dist.shasum ? sha1(bytes) === meta.dist.shasum : null;
-          return { name, version: meta.version, bytes, meta, integrityOk };
+        if (!response.ok) {
+          lastProblem = `the tarball is not fetchable yet (HTTP ${response.status})`;
+        } else {
+          // M6: the version document and the tarball being 200 is not enough —
+          // `npm install <name>` enters through the ROOT packument, which
+          // propagates later (measured on a fresh package: ~2.5 minutes behind).
+          // A release is not verified while the name itself still 404s.
+          const packumentResponse = await fetch(base);
+          const packument = packumentResponse.ok ? await packumentResponse.json() : null;
+          if (packument?.versions?.[meta.version] === undefined) {
+            lastProblem = 'the root packument does not list it yet (install-by-name still fails)';
+          } else {
+            const bytes = Buffer.from(await response.arrayBuffer());
+            const integrityOk = meta.dist.shasum ? sha1(bytes) === meta.dist.shasum : null;
+            const latest = packument?.['dist-tags']?.latest ?? null;
+            return { name, version: meta.version, bytes, meta, integrityOk, latest };
+          }
         }
-        lastProblem = `the tarball is not fetchable yet (HTTP ${response.status})`;
       }
     } catch (error) {
       lastProblem = `registry read failed (${error?.message ?? error})`;
@@ -431,6 +443,35 @@ function runTestsInside(artifact) {
   }
 }
 
+/**
+ * A package carrying `bundleDependencies` ships those deps inlined under
+ * `node_modules/` in the tarball. They are not part of the tree comparison —
+ * they are somebody else's package — but their *versions* are this release's
+ * contract: the bundled copy must match the declared spec, and the spec must be
+ * an exact pin (a range makes the artifact's contents depend on when it was
+ * packed).
+ * @param manifest - the tree's package.json, parsed.
+ * @param artifact - the readTarGz map.
+ * @returns `{ checked: [{name, spec, bundled, ok}], mismatches: number, excluded: string[] }`.
+ */
+export function checkBundledDependencies(manifest, artifact) {
+  const bundled = Array.isArray(manifest.bundleDependencies) ? manifest.bundleDependencies : [];
+  const checked = [];
+  let mismatches = 0;
+  for (const name of bundled) {
+    const spec = manifest.dependencies?.[name] ?? null;
+    const packedManifest = artifact.get(`node_modules/${name}/package.json`);
+    const bundledVersion = packedManifest === undefined ? null : JSON.parse(packedManifest.toString('utf8')).version;
+    const ok = spec !== null && spec === bundledVersion;
+    if (!ok) mismatches += 1;
+    checked.push({ name, spec, bundled: bundledVersion, ok });
+  }
+  const excluded = bundled.length === 0
+    ? []
+    : [...artifact.keys()].filter((path) => bundled.some((name) => path.startsWith(`node_modules/${name}/`)));
+  return { checked, mismatches, excluded };
+}
+
 function main(argv) {
   const options = { spec: null, pack: false, runTests: false, json: false, packer: null, wait: 0 };
   for (let index = 0; index < argv.length; index += 1) {
@@ -489,10 +530,22 @@ function main(argv) {
         if (fetched.integrityOk === false) {
           process.stdout.write(`container integrity: MISMATCH (dist.shasum ${fetched.meta.dist.shasum})\n`);
         }
+        // Informational, never a failure: verifying an older release while a
+        // newer one is `latest` is ordinary work.
+        if (fetched.latest !== null && fetched.latest !== fetched.version) {
+          process.stdout.write(`note: dist-tags.latest is ${fetched.latest}; you are verifying ${fetched.version}\n`);
+        }
       }
       const artifact = readTarGz(bytes);
       const tree = walkTree(ROOT);
-      const comparison = compareArtifact(artifact, tree);
+      // Bundled dependencies ship inside the artifact under node_modules/: they
+      // are someone else's package, so they leave the tree comparison — but
+      // their versions are this release's contract.
+      const bundled = checkBundledDependencies(manifest, artifact);
+      const artifactForCompare = bundled.excluded.length === 0
+        ? artifact
+        : new Map([...artifact].filter(([path]) => !bundled.excluded.includes(path)));
+      const comparison = compareArtifact(artifactForCompare, tree);
       // The artifact's *own* metadata is what has to be self-consistent: a package
       // whose manifest points at something it does not carry is broken wherever it
       // is installed from, which is exactly what shipped in 0.2.2.
@@ -509,7 +562,7 @@ function main(argv) {
 
       if (options.json) {
         process.stdout.write(`${JSON.stringify({
-          source, spec, treeHead, files: artifact.size, comparison, references, codeReferences, localOnly, tests,
+          source, spec, treeHead, files: artifact.size, comparison, references, codeReferences, bundled, localOnly, tests,
         }, null, 2)}\n`);
       } else {
         process.stdout.write(`verify-release: ${source} (${artifact.size} files) · tree ${treeHead ?? '(unknown HEAD)'}\n`);
@@ -529,6 +582,14 @@ function main(argv) {
           process.stdout.write(`    UNRESOLVED ${entry.file} -> ${entry.reference}\n`);
         }
         process.stdout.write(`  in the tree but not in the artifact: ${localOnly.length === 0 ? '(none)' : localOnly.join(', ')}\n`);
+        if (bundled.checked.length > 0) {
+          process.stdout.write(`  bundled dependencies: ${bundled.checked.length}  mismatches: ${bundled.mismatches} (excluded from the tree comparison: ${bundled.excluded.length} files)\n`);
+          for (const entry of bundled.checked) {
+            if (!entry.ok) {
+              process.stdout.write(`    BUNDLED-MISMATCH ${entry.name}: manifest pins ${entry.spec ?? '(undeclared)'}, the artifact carries ${entry.bundled ?? '(absent)'}\n`);
+            }
+          }
+        }
         if (tests !== null) {
           process.stdout.write(`  suite inside the artifact: ${tests.ran ? `ran ${tests.testFile}, exit ${tests.status}` : tests.reason}\n`);
         }
@@ -537,6 +598,7 @@ function main(argv) {
         || references.missing > 0
         || references.promisedButAbsent.length > 0
         || codeReferences.unresolved.length > 0
+        || bundled.mismatches > 0
         || (tests !== null && tests.ran && tests.status !== 0);
       return failed ? 1 : 0;
     })