@opengsd/gsd-core 1.15.0 → 1.16.0

package/gsd-core/bin/lib/ui-frontend-evidence.cjs

@@ -7,7 +7,7 @@
  * word boundary, so a phase section naming the repo `dashboard-financeiro` matches
  * the token `dashboard` exactly like the real UI compound `micro-frontend` does.
  * That boundary rule is intentional (#3718) and must not be weakened — instead,
- * the plan gate (`computeUiPlanGate` in check-command-router.cjs) corroborates the
+ * the plan gate (`computeUiPlanGate` in gate-ui-plan.cjs) corroborates the
  * token match against the static repo tree before blocking.
  *
  * This mirrors what the sibling post-wave gate (`computeUiSafetyGate`) already
@@ -19,7 +19,7 @@
  *       of file layout;
  *   (b) any `*.tsx` / `*.jsx` / `*.vue` / `*.svelte` file in the tree — the
  *       component-framework subset of `UI_FILE_EXTENSIONS_RE`
- *       (check-command-router.cjs). The weaker members of that list (css, scss,
+ *       (gate-ui-safety.cjs). The weaker members of that list (css, scss,
  *       html, ...) are deliberately NOT static evidence: docs sites and
  *       markdown/bash/config repos routinely carry stray `.html`/`.css`, which
  *       is precisely the false-positive class #3312 reports.
@@ -37,16 +37,22 @@
  *       (imports are case-sensitive in all four ecosystems); extension
  *       matching is case-insensitive, mirroring `UI_COMPONENT_FILE_RE`.
  *
- * All I/O failures degrade to `false` (no evidence) — never throw.
+ * #5170 (ADR-5057 §4): the detector reads typed evidence. An affirmative finding is
+ * `found`; a walk that completed without one is `none`; a `package.json` that exists but cannot be
+ * read or parsed, a directory that cannot be listed or a native source file that cannot be opened
+ * is `unreadable` WHEN no affirmative evidence was found — the gate that consumes this must not
+ * certify "no frontend" over a tree it could not look at. Never throws.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NATIVE_UI_CONTENT_MARKERS = exports.NATIVE_UI_XAML_RE = exports.NATIVE_UI_SOURCE_RE = exports.UI_COMPONENT_FILE_RE = void 0;
+exports.readStaticFrontendEvidence = readStaticFrontendEvidence;
 exports.hasStaticFrontendEvidence = hasStaticFrontendEvidence;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
 /** Component-framework file extensions — the static-evidence subset of UI_FILE_EXTENSIONS_RE. */
 exports.UI_COMPONENT_FILE_RE = /\.(tsx|jsx|vue|svelte)$/i;
 /** Native UI source files whose CONTENT is scanned for an import marker (#4658). */
@@ -111,23 +117,23 @@ const SKIP_DIRS = new Set([
 ]);
 /** Walk safety cap — beyond this the tree is treated as scanned (evidence decided by then). */
 const MAX_WALK_ENTRIES = 10_000;
-function packageJsonHasUiFramework(projectDir) {
-    let raw;
-    try {
-        raw = node_fs_1.default.readFileSync(node_path_1.default.join(projectDir, 'package.json'), 'utf8');
-    }
-    catch {
-        return false; // no/unreadable package.json → no evidence from this signal
-    }
+/** The first read failure of the package.json signal: `unreadable`, or `none` (absent), or `found`. */
+function packageJsonEvidence(projectDir) {
+    const read = (0, gate_evidence_cjs_1.readTextEvidence)(node_path_1.default.join(projectDir, 'package.json'));
+    if (read.kind === 'none')
+        return (0, gate_evidence_cjs_1.evidenceNone)();
+    if (read.kind === 'unreadable')
+        return (0, gate_evidence_cjs_1.evidenceUnreadable)(read.reason, read.span);
     let parsed;
     try {
-        parsed = JSON.parse(raw);
+        parsed = JSON.parse(read.value);
     }
-    catch {
-        return false; // malformed package.json → no evidence from this signal
+    catch (err) {
+        // A package.json that exists but is not valid JSON could not be read: unreadable, not "no deps".
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, 'package.json');
     }
     if (parsed === null || typeof parsed !== 'object')
-        return false;
+        return (0, gate_evidence_cjs_1.evidenceNone)();
     const pkg = parsed;
     for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
         const deps = pkg[field];
@@ -135,79 +141,83 @@ function packageJsonHasUiFramework(projectDir) {
             continue;
         for (const name of Object.keys(deps)) {
             if (UI_FRAMEWORK_DEPS.has(name))
-                return true;
+                return (0, gate_evidence_cjs_1.evidenceFound)(true);
         }
     }
-    return false;
+    return (0, gate_evidence_cjs_1.evidenceNone)();
 }
 /**
  * Shared bounded BFS over the project tree — the single home of the walk
  * semantics both evidence walks depend on: SKIP_DIRS pruning, the
- * MAX_WALK_ENTRIES entry cap (cap-hit → `false`: the tree is treated as
+ * MAX_WALK_ENTRIES entry cap (cap-hit → not found: the tree is treated as
  * scanned and evidence stays undecided), symlinks never followed
- * (withFileTypes Dirents), unreadable directories skipped. `visit` is called
- * for every regular file with its name and full path; returning `true` stops
- * the walk with `true` (evidence found).
+ * (withFileTypes Dirents). `visit` is called for every regular file with its
+ * name, full path and a `note` for a read failure it met; returning `true`
+ * stops the walk with `found`. A directory that cannot be listed is NOT
+ * silently skipped: it is noted, the walk goes on, and the caller learns that
+ * part of the tree was never seen (an absent directory is just skipped).
  */
 function walkProjectFiles(projectDir, visit) {
+    let unreadable = null;
+    const note = (reason) => {
+        unreadable = unreadable ?? reason;
+    };
     const queue = [projectDir];
     let visited = 0;
     while (queue.length > 0 && visited < MAX_WALK_ENTRIES) {
         const dir = queue.shift();
-        let entries;
-        try {
-            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            continue; // unreadable directory → skip it
+        const listing = (0, gate_evidence_cjs_1.readDirEntriesEvidence)(dir);
+        if (listing.kind === 'unreadable') {
+            note(listing.reason);
+            continue;
         }
-        for (const entry of entries) {
+        if (listing.kind === 'none')
+            continue; // vanished since it was queued: nothing to see
+        for (const entry of listing.value) {
             visited++;
             if (visited >= MAX_WALK_ENTRIES)
-                return false;
+                return { found: false, unreadable };
             if (entry.isDirectory()) {
                 if (!SKIP_DIRS.has(entry.name))
                     queue.push(node_path_1.default.join(dir, entry.name));
             }
-            else if (entry.isFile() && visit(entry.name, node_path_1.default.join(dir, entry.name))) {
-                return true;
+            else if (entry.isFile() && visit(entry.name, node_path_1.default.join(dir, entry.name), note)) {
+                return { found: true, unreadable };
             }
         }
     }
-    return false;
+    return { found: false, unreadable };
 }
-function treeHasComponentFile(projectDir) {
+function treeComponentFileEvidence(projectDir) {
     return walkProjectFiles(projectDir, (name) => exports.UI_COMPONENT_FILE_RE.test(name));
 }
 /**
- * Read at most the first 64 KiB of `file` and report whether any of `markers`
- * occurs in it (#4658). Import sections live at the top of a source file, so a
- * bounded prefix read keeps the gate's plan-time cost profile without reading
- * generated monsters in full. Any I/O failure degrades to false — never throw.
+ * Read at most the first 64 KiB of `file` as evidence (#4658). Import sections live at
+ * the top of a source file, so a bounded prefix read keeps the gate's plan-time cost
+ * profile without reading generated monsters in full.
  */
-function fileHasAnyMarker(file, markers) {
+function readPrefixEvidence(file) {
     let fd;
     try {
         fd = node_fs_1.default.openSync(file, 'r');
     }
-    catch {
-        return false;
+    catch (err) {
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, file);
     }
     try {
         const bytes = Buffer.alloc(64 * 1024);
         const read = node_fs_1.default.readSync(fd, bytes, 0, bytes.length, 0);
-        const prefix = bytes.toString('utf8', 0, read);
-        return markers.some((m) => prefix.includes(m));
+        return (0, gate_evidence_cjs_1.evidenceFound)(bytes.toString('utf8', 0, read));
     }
-    catch {
-        return false;
+    catch (err) {
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, file);
     }
     finally {
         try {
             node_fs_1.default.closeSync(fd);
         }
         catch {
-            // already closed — nothing to degrade
+            // already closed — the evidence was read (or its failure returned) above
         }
     }
 }
@@ -216,13 +226,20 @@ function fileHasAnyMarker(file, markers) {
  * extension alone; `.swift`/`.kt`/`.dart` are evidence only when the file's
  * content carries its ecosystem's import marker.
  */
-function treeHasNativeUiFile(projectDir) {
-    return walkProjectFiles(projectDir, (name, fullPath) => {
+function treeNativeUiEvidence(projectDir) {
+    return walkProjectFiles(projectDir, (name, fullPath, note) => {
         if (exports.NATIVE_UI_XAML_RE.test(name))
             return true;
         if (exports.NATIVE_UI_SOURCE_RE.test(name)) {
             const markers = exports.NATIVE_UI_CONTENT_MARKERS[node_path_1.default.extname(name).toLowerCase()];
-            return markers != null && fileHasAnyMarker(fullPath, markers);
+            if (markers == null)
+                return false;
+            const prefix = readPrefixEvidence(fullPath);
+            if (prefix.kind === 'unreadable') {
+                note(prefix.reason);
+                return false;
+            }
+            return prefix.kind === 'found' && markers.some((m) => prefix.value.includes(m));
         }
         return false;
     });
@@ -231,18 +248,37 @@ function treeHasNativeUiFile(projectDir) {
  * Does the project tree carry static evidence of a frontend?
  *
  * @param projectDir - Absolute path to the project root (the gate's cwd).
- * @returns true when package.json declares a UI-framework dependency, the tree
+ * @returns `found` when package.json declares a UI-framework dependency, the tree
  *          contains a component-framework file, or the tree contains native UI
  *          evidence (a `.xaml` file, or a `.swift`/`.kt`/`.dart` file carrying
- *          its ecosystem's UI import marker — #4658); false otherwise
- *          (including on any I/O failure — evidence must be affirmative).
+ *          its ecosystem's UI import marker — #4658); otherwise `unreadable` when
+ *          any part of the tree or manifest could not be read (the absence of
+ *          evidence is then not established), else `none`. Affirmative evidence
+ *          always wins over a read failure elsewhere.
  */
-function hasStaticFrontendEvidence(projectDir) {
+function readStaticFrontendEvidence(projectDir) {
     if (typeof projectDir !== 'string' || projectDir === '')
-        return false;
-    if (packageJsonHasUiFramework(projectDir))
-        return true;
-    if (treeHasComponentFile(projectDir))
-        return true;
-    return treeHasNativeUiFile(projectDir);
+        return (0, gate_evidence_cjs_1.evidenceNone)();
+    let unreadable = null;
+    const manifest = packageJsonEvidence(projectDir);
+    if (manifest.kind === 'found')
+        return manifest;
+    if (manifest.kind === 'unreadable')
+        unreadable = manifest.reason;
+    const components = treeComponentFileEvidence(projectDir);
+    if (components.found)
+        return (0, gate_evidence_cjs_1.evidenceFound)(true);
+    unreadable = unreadable ?? components.unreadable;
+    const native = treeNativeUiEvidence(projectDir);
+    if (native.found)
+        return (0, gate_evidence_cjs_1.evidenceFound)(true);
+    unreadable = unreadable ?? native.unreadable;
+    return unreadable === null ? (0, gate_evidence_cjs_1.evidenceNone)() : (0, gate_evidence_cjs_1.evidenceUnreadable)(unreadable, projectDir);
+}
+/**
+ * The boolean projection of {@link readStaticFrontendEvidence}: true only on affirmative evidence. It
+ * reads nothing itself; a gate that must tell "no frontend" from "could not look" uses the evidence.
+ */
+function hasStaticFrontendEvidence(projectDir) {
+    return readStaticFrontendEvidence(projectDir).kind === 'found';
 }

package/gsd-core/bin/lib/vendor/README.md

@@ -1,7 +1,7 @@
 # vendor/
 
-This directory holds **verbatim, unmodified** copies of third-party build
-artifacts that `gsd-core/bin/**` needs at runtime.
+This directory holds third-party artifacts that `gsd-core/bin/**` needs at
+runtime: verbatim upstream builds or reproducible bundles of unmodified upstream code.
 
 ## Why
 
@@ -15,6 +15,19 @@ in-tree instead of depending on it being installed as an npm package.
 
 ## Contents
 
+- `tap-parser.cjs` and `saxes.cjs` — standalone CJS bundles built with pinned
+  esbuild from the exact devDependency versions and their lockfile dependencies.
+  The TAP and JUnit adapters use these for report grammar and diagnostics.
+  `scripts/lib/vendor-bundle.cjs` rejects external imports other than Node
+  builtins; `lint-vendored-deps.cjs` rebuilds in memory and byte-compares both
+  code and companion `.LICENSE.txt` notices. Refresh with
+  `npm run lint:vendored-deps -- --fix`.
+  `tap-parser`'s npm metadata says BlueOak-1.0.0 while its shipped LICENSE says
+  MIT; the notices preserve both the metadata and the actual license text.
+  saxes 6.0.0 omits LICENSE from npm, so the tagged upstream license is preserved
+  verbatim in `scripts/lib/vendor-licenses/saxes-6.0.0.txt` and included in the
+  generated notices. Neither package's source is patched.
+
 - `re2js.cjs` — verbatim copy of `node_modules/re2js/build/index.cjs`
   (upstream package `re2js`, pinned version see `package.json`
   `devDependencies.re2js`). Used by `src/pattern.cts` (compiled to
@@ -30,12 +43,19 @@ in-tree instead of depending on it being installed as an npm package.
   `require()` calls of its own, and exposes `load`/`dump`/`FAILSAFE_SCHEMA`/
   `YAMLException`.
 
-## Two kinds of type twin
+## Type twins
+
+The bundled parsers use **upstream-reference** twins: declaration-only
+`export * from '<package>';` files under `src/vendor/`. TypeScript reads the
+actual upstream declarations during the build, with no hand-maintained API
+copy and no bare runtime import. The vendoring guard checks the exact forwarding
+declaration. The installed runtime needs only the bundled JavaScript.
 
 Each vendored package needs a `.d.cts` under `src/vendor/` so TypeScript can
 resolve types for a relative `./vendor/<pkg>.cjs` import from `src/**`
 (module resolution for a `.cts` source is relative to `src/`, not the
-compiled output dir). There are two kinds:
+compiled output dir). Besides the upstream-reference twins above, the prebuilt
+upstream artifacts use one of two kinds:
 
 - **upstream-verbatim** (`re2js.d.cts`) — a byte-for-byte copy of an
   upstream `.d.cts`/`.d.ts` that ships with the package. Both the
@@ -54,8 +74,8 @@ compiled output dir). There are two kinds:
 
 ## Do not hand-edit
 
-These files are **verbatim** copies of upstream build output. Never edit
-them directly — refresh them from `node_modules` instead:
+Never edit these artifacts directly. Refresh bundled packages through the
+vendoring command above. Refresh the prebuilt upstream artifacts as follows:
 
 ```
 cp node_modules/re2js/build/index.cjs gsd-core/bin/lib/vendor/re2js.cjs
@@ -68,8 +88,10 @@ cp node_modules/js-yaml/dist/js-yaml.js gsd-core/bin/lib/vendor/js-yaml.cjs
 ```
 
 `node scripts/lint-vendored-deps.cjs` fails CI if any vendored copy drifts
-byte-for-byte from its `node_modules` upstream, from its own source-side
-type twin (upstream-verbatim twins only), or from the version pinned in
+byte-for-byte from its `node_modules` upstream (for a bundled package: from
+an in-memory rebuild of the bundle and its license notices), from its own
+source-side type twin (upstream-verbatim twins only; an upstream-reference
+twin must be the exact forwarding declaration), or from the version pinned in
 `package.json` `devDependencies`. It is table-driven (`VENDORED` in that
-script) — adding a third vendored package means adding a row, not a second
+script) — adding a vendored package means adding a row, not another
 hardcoded check block (ADR-3473 §8.3, "one implementation per rule").