@a11ign/screenreader-fleet 0.5.0 → 0.5.2

package/dist/doctor.d.mts

@@ -91,30 +91,22 @@ export function resolvesToThisCheckout(resolvedRealPath: string, thisCheckoutRoo
  */
 export function checkoutRootFor(resolvedRealPath: string): string | null;
 /**
- * Whether `tsc --build --dry` -- the SAME authority the real build uses, deferred to rather than
- * reimplemented -- considers `tsconfigPath`'s own outputs up to date.
- *
- * NOT a timestamp comparison, and that correction cost a wrong first version of this check (#256, live-
- * measured): a directory's mtime does not move on rewrite; a file's mtime moves on `git checkout` with no
- * content change at all, which is the ordinary case of switching branches; and `tsc --build` itself is
- * content-addressed for the files it actually recompiles, so a real build can be legitimately up to date
- * with source files whose mtimes are newer than its outputs. Measured on two live worktrees straight
- * after a branch switch: several source files newer than `dist/index.js`, and `tsc --build --dry` still
- * correctly reported "is up to date". A raw mtime comparison would have flagged both as stale --
- * permanently, on every worktree, the moment `git checkout` runs -- which is exactly the "readiness
- * command that cries wolf" this file's own `advise` doc warns against.
- *
- * `null`, not `false`, when the run failed outright or its report never mentioned this project at all --
- * "could not tell" and "not up to date" need opposite responses (investigate vs. rebuild), and this repo's
- * own rule is that a lookup failure is never silently read as a clean answer.
- *
- * @param {string} tsconfigPath
- * @param {{ run?: (cmd: string, args: string[]) => string }} [deps]
- * @returns {boolean | null}
+ * The `exports` targets of `packageDir` that are NOT on disk, or `null` when the package's manifest could not be
+ * read or declares none -- "could not tell" and "missing" need opposite responses (investigate vs. rebuild), and a
+ * lookup failure is never read as a clean answer.
+ *
+ * WHY EXISTENCE AND NOT FRESHNESS. This asked `tsc --build --dry` whether the package's outputs were current, and
+ * a11ign builds `judge` with Rslib now (a11ign/a11ign#3580): its `tsconfig.json` is `noEmit`, so tsc has no output to
+ * be up to date about and answered wrongly on every run (a11ign/a11ign#3810). Rslib writes no stamp of the source it
+ * built from, and a timestamp comparison is the wrong first version this check once had (#256: `git checkout` moves
+ * source mtimes with no content change, so every worktree would read stale the moment it switched branches). So what
+ * is read is what Rslib's output actually IS: the files `exports` promises. A present but out-of-date `dist` is
+ * therefore NOT caught here, and the check says "present", never "up to date".
+ *
+ * @param {string} packageDir
+ * @returns {string[] | null}
  */
-export function tscProjectUpToDate(tsconfigPath: string, { run }?: {
-    run?: (cmd: string, args: string[]) => string;
-}): boolean | null;
+export function missingExportTargets(packageDir: string): string[] | null;
 /**
  * WHOSE dist a cross-package import actually resolves to, and is IT stale (#256) -- both computed from
  * the exact SPECIFIER a real import site in this repo uses, never the bare package name. CLAUDE.md's own

package/dist/doctor.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
-import { existsSync as external_node_fs_existsSync, readFileSync, realpathSync as external_node_fs_realpathSync, statSync } from "node:fs";
-import { delimiter as external_node_path_delimiter, dirname as external_node_path_dirname, join as external_node_path_join, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir } from "node:os";
 import { createRequire } from "node:module";
@@ -26,51 +26,6 @@ function controlPlaneIsolation({ hasNodeModules, hasFleetKey, packages, isWorksp
         why: `ADR 0012 VIOLATED: node_modules${count} sits beside the fleet SSH key. A compromised transitive dependency here can reach the key that reconfigures every Windows worker, each of which auto-logs-in to an unlocked desktop. ${remedy}`
     };
 }
-function pnpmCliInvocation(args) {
-    const fromParent = process.env.npm_execpath ?? "";
-    if (/pnpm\.c?js$/.test(fromParent) && external_node_fs_existsSync(fromParent)) return {
-        command: process.execPath,
-        args: [
-            fromParent,
-            ...args
-        ]
-    };
-    const shim = onPath("pnpm");
-    if (null !== shim) return shimInvocation(shim, external_node_path_join("node_modules", "pnpm", "bin", "pnpm.cjs"), args);
-    const corepack = onPath("corepack");
-    if (null !== corepack) return shimInvocation(corepack, external_node_path_join("node_modules", "corepack", "dist", "corepack.js"), [
-        "pnpm",
-        ...args
-    ]);
-    throw new Error("could not find pnpm: `npm_execpath` is not a pnpm script, and neither `pnpm` nor `corepack` is on PATH. `packageManager` in the root package.json names the version -- `corepack enable` or `pnpm/action-setup` provides it.");
-}
-function onPath(name) {
-    for (const dir of (process.env.PATH ?? "").split(external_node_path_delimiter))if ("" !== dir) {
-        for (const candidate of [
-            external_node_path_join(dir, name),
-            external_node_path_join(dir, `${name}.cmd`)
-        ])if (external_node_fs_existsSync(candidate)) return candidate;
-    }
-    return null;
-}
-function shimInvocation(shim, script, args) {
-    if (!shim.endsWith(".cmd")) return {
-        command: shim,
-        args
-    };
-    const found = [
-        external_node_path_join(external_node_path_dirname(shim), script),
-        external_node_path_join(external_node_path_dirname(process.execPath), script)
-    ].find((path)=>external_node_fs_existsSync(path));
-    if (void 0 === found) throw new Error(`${shim} is a .cmd shim and its script ${script} is not beside it or beside node`);
-    return {
-        command: process.execPath,
-        args: [
-            found,
-            ...args
-        ]
-    };
-}
 refuseUnknownFlags([
     "--json",
     "--runs-dir="
@@ -78,14 +33,14 @@ refuseUnknownFlags([
     entry: import.meta.url,
     command: "pnpm run doctor"
 });
-const doctor_run = promisify(execFile);
+const run = promisify(execFile);
 const JSON_OUT = process.argv.includes("--json");
 const REFUSED = 2;
 const WORKERS_ENV = configuredWorkers();
 const PAGES_PORT = Number(process.env.DATASET_PAGES_PORT || 5050);
 const CTL = fleetScriptPaths().workerCtl;
 const MODULE_DIR = fileURLToPath(new URL(".", import.meta.url));
-const isMonorepoRoot = (root)=>external_node_fs_existsSync(resolve(root, "packages")) && external_node_fs_existsSync(resolve(root, "package.json"));
+const isMonorepoRoot = (root)=>existsSync(resolve(root, "packages")) && existsSync(resolve(root, "package.json"));
 function checkoutLayout(baseDir = MODULE_DIR) {
     const root = resolve(baseDir, "..", "..", "..");
     return {
@@ -99,7 +54,7 @@ const notACheckout = (names, root)=>{
 function runsDirFor({ argv = process.argv.slice(2), baseDir = MODULE_DIR } = {}) {
     const supplied = flagValue(argv, "runs-dir");
     if (void 0 !== supplied) {
-        if (external_node_fs_existsSync(supplied)) return resolve(supplied);
+        if (existsSync(supplied)) return resolve(supplied);
         throw new Error(`doctor: --runs-dir=${supplied} does not exist. Pass --runs-dir=<the runs directory>.`);
     }
     const root = resolve(baseDir, "..", "..", "..");
@@ -169,7 +124,7 @@ function workerControlFix(observed) {
         fix: `${CTL} pool`,
         note: "UTM has no registered worker VM; re-register the existing a11y-worker*.utm bundles in UTM first"
     };
-    return external_node_fs_existsSync("/Applications/UTM.app") ? {
+    return existsSync("/Applications/UTM.app") ? {
         fix: `${CTL} pool`,
         note: "unlock the Mac first if it is locked"
     } : {
@@ -178,7 +133,7 @@ function workerControlFix(observed) {
     };
 }
 async function shell(cmd, args, timeout = 30000) {
-    const { stdout } = await doctor_run(cmd, args, {
+    const { stdout } = await run(cmd, args, {
         timeout,
         encoding: "utf8"
     });
@@ -229,8 +184,8 @@ function checkControlPlaneIsolation({ baseDir = MODULE_DIR } = {}) {
     ], root);
     const raw = process.env.A11Y_SSH_KEY || "~/.ssh/a11y-witness_ed25519";
     const keyPath = raw.startsWith("~/") ? resolve(homedir(), raw.slice(2)) : raw;
-    const hasFleetKey = external_node_fs_existsSync(keyPath);
-    const hasNodeModules = external_node_fs_existsSync(resolve(root, "node_modules"));
+    const hasFleetKey = existsSync(keyPath);
+    const hasNodeModules = existsSync(resolve(root, "node_modules"));
     const verdict = controlPlaneIsolation({
         hasNodeModules,
         hasFleetKey,
@@ -246,27 +201,23 @@ function checkoutRootFor(resolvedRealPath) {
     const idx = resolvedRealPath.indexOf("/packages/");
     return -1 === idx ? null : resolvedRealPath.slice(0, idx);
 }
-const defaultTscRun = (cmd, args)=>execFileSync(cmd, args, {
-        encoding: "utf8"
-    });
-function tscProjectUpToDate(tsconfigPath, { run = defaultTscRun } = {}) {
-    let output;
+function exportTargets(exportsField) {
+    if ("string" == typeof exportsField) return [
+        exportsField
+    ];
+    if (null === exportsField || "object" != typeof exportsField) return [];
+    return Object.values(exportsField).flatMap(exportTargets);
+}
+function missingExportTargets(packageDir) {
+    let manifest;
     try {
-        const tsc = pnpmCliInvocation([
-            "exec",
-            "tsc",
-            "--build",
-            "--dry",
-            tsconfigPath
-        ]);
-        output = run(tsc.command, tsc.args);
-    } catch (error) {
-        output = error?.stdout ?? "";
-        if (!output) return null;
+        manifest = JSON.parse(readFileSync(resolve(packageDir, "package.json"), "utf8"));
+    } catch  {
+        return null;
     }
-    const line = output.split("\n").find((l)=>l.includes(tsconfigPath));
-    if (!line) return null;
-    return /is up to date/.test(line);
+    const targets = exportTargets(manifest?.exports);
+    if (0 === targets.length) return null;
+    return targets.filter((target)=>!existsSync(resolve(packageDir, target)));
 }
 function behindOriginMainNote(otherRoot) {
     if (!otherRoot) return "";
@@ -294,25 +245,25 @@ function checkCrossPackageDist({ baseDir = MODULE_DIR } = {}) {
     ], thisCheckoutRoot);
     let resolvedRealPath;
     try {
-        resolvedRealPath = external_node_fs_realpathSync(createRequire(import.meta.url).resolve(specifier));
+        resolvedRealPath = realpathSync(createRequire(import.meta.url).resolve(specifier));
     } catch (error) {
         return advise("dist-resolution", `could not resolve ${specifier} to check whose dist it comes from -- ${error.message}`, "pnpm run build");
     }
-    if (resolvesToThisCheckout(resolvedRealPath, external_node_fs_realpathSync(thisCheckoutRoot))) add("dist-resolution", true, `${specifier} resolves to this checkout's own dist`);
+    if (resolvesToThisCheckout(resolvedRealPath, realpathSync(thisCheckoutRoot))) add("dist-resolution", true, `${specifier} resolves to this checkout's own dist`);
     else {
         const behindNote = behindOriginMainNote(checkoutRootFor(resolvedRealPath));
         advise("dist-resolution", `${specifier} resolves to ${resolvedRealPath} (NOT this checkout${behindNote})`, "pnpm run primary:update && pnpm run build   # if that is the primary checkout");
     }
     const distRoot = checkoutRootFor(resolvedRealPath) ?? thisCheckoutRoot;
-    const tsconfigPath = resolve(distRoot, "packages/judge/tsconfig.json");
-    const upToDate = tscProjectUpToDate(tsconfigPath);
-    if (null === upToDate) return advise("dist-freshness", `could not ask tsc whether ${tsconfigPath} is up to date`, "pnpm run build");
-    if (upToDate) return add("dist-freshness", true, `packages/judge under ${distRoot} is up to date (tsc --build --dry)`);
-    advise("dist-freshness", `packages/judge under ${distRoot} is NOT up to date (tsc --build --dry) -- a build compiled before the source it now reflects`, "pnpm run build   # in that checkout");
+    const judgeDir = resolve(distRoot, "packages/judge");
+    const missing = missingExportTargets(judgeDir);
+    if (null === missing) return advise("dist-freshness", `could not read the exports of ${judgeDir}/package.json to see whether its dist is built`, "pnpm run build");
+    if (0 === missing.length) return add("dist-freshness", true, `every exports target of packages/judge under ${distRoot} is present (existence only: Rslib leaves no stamp to read freshness from)`);
+    advise("dist-freshness", `packages/judge under ${distRoot} is missing ${missing.length} exports target(s): ${missing.join(", ")}`, "pnpm run build   # in that checkout");
 }
 async function scorerWeightsFor({ from = import.meta.url } = {}) {
-    const judgeEntry = external_node_fs_realpathSync(createRequire(from).resolve("@a11ign/judge"));
-    const scorerEntry = external_node_fs_realpathSync(createRequire(judgeEntry).resolve("@a11ign/scorer"));
+    const judgeEntry = realpathSync(createRequire(from).resolve("@a11ign/judge"));
+    const scorerEntry = realpathSync(createRequire(judgeEntry).resolve("@a11ign/scorer"));
     const { scorerPaths } = await import(pathToFileURL(scorerEntry).href);
     return scorerPaths().weights;
 }
@@ -327,7 +278,7 @@ async function checkJudge({ from = import.meta.url } = {}) {
         } catch (error) {
             return add("judge", false, `backend=local, but @a11ign/scorer could not be resolved from @a11ign/judge: ${error.message}`, "install @a11ign/scorer (a peer dependency of @a11ign/judge) beside @a11ign/judge");
         }
-        return add("judge", external_node_fs_existsSync(weights), external_node_fs_existsSync(weights) ? "backend=local, trained scorer present" : "backend=local, but the trained scorer is missing", `expected weights at ${weights} (where @a11ign/scorer says they are) — reinstall @a11ign/scorer`);
+        return add("judge", existsSync(weights), existsSync(weights) ? "backend=local, trained scorer present" : "backend=local, but the trained scorer is missing", `expected weights at ${weights} (where @a11ign/scorer says they are) — reinstall @a11ign/scorer`);
     }
     if ("anthropic" === backend || "openai" === backend) {
         const key = "anthropic" === backend ? "ANTHROPIC_API_KEY" : "JUDGE_BASE_URL";
@@ -339,7 +290,7 @@ async function checkWorker() {
     if (WORKERS_ENV.length) return checkConfiguredFleet(WORKERS_ENV);
     const inventory = namedInventoryWorkers();
     if (inventory.length) return checkConfiguredFleet(inventory);
-    if ("darwin" !== process.platform || !external_node_fs_existsSync(CTL)) return add("worker", false, "no A11Y_WORKERS set, no inventory.yml fleet, and no local VM tooling here", "set A11Y_WORKERS=http://host:8765[,http://host2:8765], or see docs/getting-started.md");
+    if ("darwin" !== process.platform || !existsSync(CTL)) return add("worker", false, "no A11Y_WORKERS set, no inventory.yml fleet, and no local VM tooling here", "set A11Y_WORKERS=http://host:8765[,http://host2:8765], or see docs/getting-started.md");
     let pool;
     try {
         pool = JSON.parse(await shell(CTL, [
@@ -466,7 +417,7 @@ function checkHostCapacity(pool) {
 }
 async function checkDatasetPages() {
     const manifestPath = resolve(datasetDir(), "manifest.json");
-    if (!external_node_fs_existsSync(manifestPath)) return add("dataset", false, "no manifest — the dataset has not been generated", "pnpm run training:generate");
+    if (!existsSync(manifestPath)) return add("dataset", false, "no manifest — the dataset has not been generated", "pnpm run training:generate");
     const sample = JSON.parse(readFileSync(manifestPath, "utf8")).cases?.[0]?.id;
     const probe = sample ? `${sample}/good.html` : "";
     try {
@@ -481,7 +432,7 @@ async function checkDatasetPages() {
 }
 function checkRunState() {
     const progress = resolve(datasetDir(), "capture-progress.json");
-    if (!external_node_fs_existsSync(progress)) return add("run", true, "no capture run recorded");
+    if (!existsSync(progress)) return add("run", true, "no capture run recorded");
     const p = JSON.parse(readFileSync(progress, "utf8"));
     if (!p.startedAt) return add("run", true, "no capture run recorded");
     if (!p.finishedAt) return add("run", false, `a run is UNFINISHED (started ${p.startedAt})`, "pnpm run training:wait, or pnpm run training:capture -- --resume --no-cache");
@@ -563,5 +514,5 @@ function renderDoctor({ json, out }) {
 async function main() {
     process.exit(await doctorRun());
 }
-if (import.meta.url === pathToFileURL(process.argv[1] ? external_node_fs_realpathSync(process.argv[1]) : "").href) await main();
-export { addCheck, allChecks, checkControlPlaneIsolation, checkCrossPackageDist, checkJudge, checkPrimaryCheckoutMark, checkoutRootFor, doctorRun, errorDocument, fleetAgreementLine, gatingChecks, isRunnableCommand, nextCommand, readyFrom, recordedChecks, resolvesToThisCheckout, runsDirFor, scorerWeightsFor, tscProjectUpToDate, workerControlFix };
+if (import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href) await main();
+export { addCheck, allChecks, checkControlPlaneIsolation, checkCrossPackageDist, checkJudge, checkPrimaryCheckoutMark, checkoutRootFor, doctorRun, errorDocument, fleetAgreementLine, gatingChecks, isRunnableCommand, missingExportTargets, nextCommand, readyFrom, recordedChecks, resolvesToThisCheckout, runsDirFor, scorerWeightsFor, workerControlFix };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11ign/screenreader-fleet",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Host-side lifecycle, health and capacity for a fleet of Windows NVDA capture workers: lease one, judge whether it is degrading, and know how many the host can afford.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -73,7 +73,7 @@
   },
   "devDependencies": {
     "@a11ign/evidence": "0.1.0",
-    "@a11ign/toolchain": "0.1.2",
+    "@a11ign/toolchain": "0.1.4",
     "@rslib/core": "1.0.3",
     "typescript": "^6.0.3",
     "yaml": "^2.9.1"