fix(ts): browser bundle throws on load — move node:fs import into validateFile (1.0.1)

Author: badosa

CHANGELOG.md

@@ -14,6 +14,48 @@ The error-code vocabulary is versioned **independently** of the package via `met
 
 Staged for the next release. Not yet published.
 
+## [1.0.1] - 2026-07-04
+
+A hotfix republish. The 1.0.0 browser IIFE/ESM bundle
+([`dist/browser/jsonstat-validator.min.js`](packages/ts/dist/browser/jsonstat-validator.min.js)) threw
+on `<script src>` load in browsers: [`pipeline.ts`](packages/ts/src/pipeline.ts) imported `node:fs` at
+module top level, and esbuild preserved that top-level static import in the browser build as an eager
+`__require("node:fs")` that runs at load time (browsers have no `require`). The Node smoke test missed
+it because Node supplies a real `require`.
+
+### Fixed — broken browser bundle
+- Moved the `node:fs` import out of the top of [`pipeline.ts`](packages/ts/src/pipeline.ts) and into
+  [`validateFile()`](packages/ts/src/pipeline.ts) as a dynamic `await import("node:fs")`. Since the
+  browser entry ([`browser.ts`](packages/ts/src/browser.ts)) does not export `validateFile`, esbuild
+  now tree-shakes it — and the `node:fs` dependency — out of the browser bundle entirely. The
+  documented jsDelivr / unpkg `<script src>` path works again. `validateFile()` is unchanged for Node
+  consumers.
+
+### Added — regression guards (both run in `npm run build` via the `verify:browser` script)
+- [`tools/verify-browser-bundle.mjs`](packages/ts/tools/verify-browser-bundle.mjs): a static-content
+  guard that fails the build if `dist/browser/*` references a Node builtin (`node:*` or a core-module
+  `require`/`import`). Encodes the invariant the 1.0.0 build violated.
+- [`tools/smoke-browser-bundle.mjs`](packages/ts/tools/smoke-browser-bundle.mjs): a functional guard
+  that loads the built IIFE in a Node `vm` context with no `require`/`module` globals (browser-like)
+  and drives `validate()` — the test that would have caught 1.0.0.
+
+### Changed — version bump (lockstep across all surfaces)
+- Patch `1.0.0 → 1.0.1` across all four surfaces — [`@jsonstat-validator/ts`](packages/ts),
+  [`jsonstat-validate`](cli), [`@jsonstat-validator/wasm`](packages/wasm), and the
+  [`jsonstat-validator`](crates/validator) Rust crate — plus the lockfiles. The bug is confined to the
+  TS browser bundle, but this release keeps the repo's all-surfaces-in-lockstep convention.
+- `engineVersion` `1.0.0 → 1.0.1` in [`rules-manifest.json`](rules-manifest.json) and the Rust
+  [`_vendored`](crates/validator/src/_vendored/manifest/rules-manifest.json) snapshot (one commit, as
+  [`vendored_parity.rs`](crates/validator/tests/vendored_parity.rs) requires). **`ruleSetVersion`
+  stays `1.0.0`** — no codes/severities changed, the diagnostic vocabulary is unchanged.
+- Refreshed the [`packages/ts/README.md`](packages/ts/README.md) `meta.engineVersion` example to
+  `1.0.1`.
+
+### Deprecated
+- [`@jsonstat-validator/ts@1.0.0`](https://www.npmjs.com/package/@jsonstat-validator/ts/v/1.0.0) on npm
+  — its browser IIFE/ESM bundle is broken; upgrade to `>=1.0.1` for CDN / `<script src>` use. Node
+  usage of 1.0.0 is unaffected.
+
 ## [1.0.0] - 2026-07-01
 
 The `1.0.0` cut. The work tracked in the README "Toward 1.0.0" section is complete; this release
@@ -112,7 +154,8 @@ follow-up release.
 Initial TypeScript engine, full S/D/C rule set, shared corpus, and the CLI (M1/M2), and the Rust
 port with corpus parity (M3). See the git history for details.
 
-[Unreleased]: https://github.com/jsonstat/validator/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/jsonstat/validator/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/jsonstat/validator/releases/tag/v1.0.1
 [1.0.0]: https://github.com/jsonstat/validator/releases/tag/v1.0.0
 [0.3.0]: https://github.com/jsonstat/validator/releases/tag/v0.3.0
 [0.2.0]: https://github.com/jsonstat/validator/releases/tag/v0.2.0

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsonstat-validate",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Command-line semantic validator for JSON-stat 2.0.",
   "license": "Apache-2.0",
   "author": "JSON-stat contributors",

crates/validator/Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "jsonstat-validator"
-version = "1.0.0"
+version = "1.0.1"
 edition = "2021"
 license = "Apache-2.0"
 description = "Semantic validator for JSON-stat 2.0 — cross-field cube invariants on top of the official JSON Schema 2020-12 definitions."

crates/validator/Cargo.toml

@@ -1,5 +1,5 @@
 {
-  "engineVersion": "1.0.0",
+  "engineVersion": "1.0.1",
   "ruleSetVersion": "1.0.0",
   "schemaVersion": "1.05",
   "description": "Single source of truth for the jsonstat-validator rule catalogue, error codes, severities and message hints. Loaded verbatim by the TypeScript surface (fs) and the Rust surface (include_str!). Codes are append-only within a ruleSetVersion major.",

crates/validator/src/_vendored/manifest/rules-manifest.json

@@ -87,7 +87,7 @@ const result = await validateFile("./my-cube.json");
   ],
   "summary": { "errors": 1, "warnings": 0, "infos": 0, "structuralErrors": 0, "byCode": { "VALUE_LEN_MISMATCH": 1 } },
   "options": { /* resolved ValidateOptions */ },
-  "meta": { "engineVersion": "1.0.0", "ruleSetVersion": "1.0.0", "schemaVersion": "1.05", "durationMs": 3 }
+  "meta": { "engineVersion": "1.0.1", "ruleSetVersion": "1.0.0", "schemaVersion": "1.05", "durationMs": 3 }
 }
 ```
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonstat-validator/ts",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Semantic validator for JSON-stat 2.0 — layers cross-field cube invariants on top of the official JSON Schema 2020-12 definitions.",
   "license": "Apache-2.0",
   "author": "JSON-stat contributors",
@@ -55,7 +55,8 @@
   "scripts": {
     "gen": "node tools/gen-assets.mjs",
     "sync-license": "node tools/sync-license.mjs",
-    "build": "npm run sync-license && npm run gen && tsc && node tools/build-node-cjs.mjs && node tools/build-browser.mjs",
+    "build": "npm run sync-license && npm run gen && tsc && node tools/build-node-cjs.mjs && node tools/build-browser.mjs && npm run verify:browser",
+    "verify:browser": "node tools/verify-browser-bundle.mjs && node tools/smoke-browser-bundle.mjs",
     "build:types": "npm run gen && tsc",
     "test": "node --loader ./tools/ts-loader.mjs --test test/rules.test.ts test/corpus.test.ts test/curated-parity.test.ts",
     "test:rules": "node --loader ./tools/ts-loader.mjs --test test/rules.test.ts",

packages/ts/README.md

@@ -1,5 +1,4 @@
 // The validate pipeline: parse -> structural (JSON Schema) -> semantic rules -> aggregate.
-import { readFileSync, statSync } from "node:fs";
 import { analyzeDataset, runSemantic } from "./engine.js";
 import { validateStructural } from "./structural.js";
 import { lookupRule } from "./manifest.js";
@@ -151,6 +150,11 @@ function runCollection(doc: any, rootPointer: string, opts: ResolvedOptions, sin
 }
 
 export async function validateFile(file: string, options?: ValidateOptions): Promise<ValidationResult> {
+  // Imported dynamically so `node:fs` is never a top-level static import — that keeps the browser
+  // (IIFE/ESM) bundle free of any eager `__require("node:fs")` at load time. validateFile is
+  // Node-only and not exported by src/browser.ts, so this whole function is tree-shaken out of the
+  // browser build; the dynamic import is belt-and-suspenders for any consumer that does reference it.
+  const { statSync, readFileSync } = await import("node:fs");
   const opts = resolveOptions(options);
   const size = statSync(file).size;
   if (size > opts.budget.maxBytes) {