@cosyte/script-utils 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.11
+
+### Patch Changes
+
+- c854d59: `@cosyte/script-utils`: the attw gate (`cosyte-attw`, `runAttwGate` and `runAttwCli`) now starts on
+  Windows. It used to check `node_modules/.bin/attw` and start it without a shell; on Windows that file
+  is a POSIX shell script, so the start failed with ENOENT, and npm and pnpm, which the gate also
+  starts, are `.cmd` files there that Node will not start without a shell. On Windows the gate now
+  checks and starts `node_modules/.bin/attw.cmd`, and starts all three tools through `cmd.exe` with
+  every argument and every path on the command line in double quotes, a trailing run of backslashes
+  doubled so each argument arrives whole. Elsewhere nothing changes. Two new exports,
+  `attwBinaryPath(callerUrl, platform?)` and `toolCommand(file, args, platform?)`, say which binary and
+  which command line. The gate now refuses an argument carrying a double quote, a percent sign or a
+  line break, on every system: no argument it accepts needs one. A repository that skipped the attw
+  step on Windows can drop the skip once it takes this version. Callers change nothing.
+
+  `@cosyte/bench`: the README now says what the small-input memory budget gives up: a cost in fewer
+  than half of a small case's 20 calls is not bounded, the rule switches at a hard 64 KiB edge, and
+  the empty-call floor's highest call is not a fixed figure (usually about 29 KiB, once 369,888
+  bytes) while its median is stable at about 3.4 KiB. No behavior changes.
+
 ## 0.1.10
 
 ### Patch Changes

package/README.md

@@ -807,6 +807,16 @@ Four nets, each catching something the others cannot:
 What each net does and does not claim, and every measurement behind them, is in `attw.js`'s own
 docblock. It is not restated here: a claim written down twice is a claim that drifts.
 
+On Windows the gate checks and starts `node_modules/.bin/attw.cmd`, because the extensionless
+`attw` there is a POSIX shell script, and it starts attw, npm and pnpm through `cmd.exe`, because
+all three are `.cmd` files that Node will not start without a shell. Every argument and every path
+on that command line is in double quotes (a bare name found on PATH, such as `npm`, is not: `cmd.exe`
+gives a quoted one the wrong `%~dp0`), with a trailing run of backslashes doubled so node still
+reads the closing quote as one, and an argument carrying a double quote, a percent sign or a line break is
+refused on every system. Two exports say what the gate starts: `attwBinaryPath(callerUrl,
+platform?)`, the binary's path, and `toolCommand(file, args, platform?)`, the command, its arguments
+and whether a shell runs it.
+
 ## Compatibility
 
 Node `>=22.14`, ESM only, published as source (`index.js`, `phi-scan.js`, `internal-refs.js` and
@@ -814,7 +824,8 @@ Node `>=22.14`, ESM only, published as source (`index.js`, `phi-scan.js`, `inter
 relative path from a checkout as well as by specifier. `runPhiScan` shells out to `git` for the
 index-backed half of its sweep, so `all` mode needs git on the path, `runInternalRefsScan` shells
 out to `git` for its whole enumeration, and `runAttwGate` spawns the consuming package's own `attw`
-binary, `npm pack` and, where a `publishConfig` object is present, `pnpm pack`.
+binary, `npm pack` and, where a `publishConfig` object is present, `pnpm pack`, through `cmd.exe`
+on Windows.
 
 ## Contributing
 

package/attw.d.ts

@@ -52,3 +52,31 @@ export declare function readAttwExclusions(text: string): {
  * `scripts/attw.exclude`, with no caller file. `node node_modules/@cosyte/script-utils/attw.js`.
  */
 export declare function runAttwCli(argv: string[]): number;
+
+/**
+ * The consuming package's own attw binary, resolved as `../node_modules/.bin/attw` from
+ * `callerUrl`, or `../node_modules/.bin/attw.cmd` on Windows, where the extensionless file is a
+ * POSIX shell script that Windows cannot start.
+ *
+ * @param callerUrl The caller's `import.meta.url`.
+ * @param platform Defaults to `process.platform`.
+ */
+export declare function attwBinaryPath(callerUrl: string, platform?: string): string;
+
+/**
+ * How the gate starts attw, npm and pnpm. Off Windows: the file and its arguments as they are,
+ * with no shell. On Windows, where all three are `.cmd` files that Node will not start without
+ * one: a single command line, every part but a bare tool name in double quotes, run through `cmd.exe`. A part carrying
+ * a double quote, a percent sign or a line break throws there rather than being escaped.
+ * A trailing run of backslashes in an argument is doubled, so node, which halves backslashes
+ * before a quote, still reads the closing quote as one.
+ *
+ * @param file The tool: a path, or a name found on PATH.
+ * @param args Its arguments.
+ * @param platform Defaults to `process.platform`.
+ */
+export declare function toolCommand(
+  file: string,
+  args: string[],
+  platform?: string,
+): { file: string; args: string[]; shell: boolean };

package/attw.js

@@ -787,6 +787,18 @@ const ALLOWED = new Set(["--profile", "--no-definitely-typed"]);
  */
 function forwardable(args) {
   const forwarded = [];
+  // REFUSED ON EVERY PLATFORM, though only Windows needs it: there attw is started
+  // through cmd.exe, which cannot take these characters inside quotes (see
+  // `toolCommand`). No option or value this gate accepts carries one, and refusing
+  // them everywhere keeps one behaviour on every system.
+  const unsafe = args.find((arg) => /["%\r\n]/.test(arg));
+  if (unsafe !== undefined) {
+    die(
+      `${JSON.stringify(unsafe)} carries a double quote, a percent sign or a line break.\n` +
+        `  No argument this gate accepts needs one, and on Windows, where attw is started\n` +
+        `  through cmd.exe, none of them can be passed on safely.`,
+    );
+  }
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     const name = arg.split("=")[0];
@@ -832,6 +844,92 @@ const PACK_PLACEMENT_CONFIG = /^npm_config_(dry[_-]run|pack[_-]destination)$/i;
 // rather than left as `spawnSync ... ENOBUFS`.
 const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
 
+/**
+ * Where the consuming package's own attw binary is, on the platform given.
+ *
+ * ON WINDOWS THE RUNNABLE ONE IS `attw.cmd`. A package manager writes three files
+ * into `node_modules/.bin` there: `attw` (a POSIX shell script), `attw.cmd` and
+ * `attw.ps1`. The extensionless one exists, so a check for it passes, and then
+ * starting it fails with ENOENT, because Windows cannot start a shell script. That
+ * was the whole failure on the Windows legs that first ran this gate.
+ *
+ * @param {string} callerUrl The caller's `import.meta.url`.
+ * @param {NodeJS.Platform} [platform] Defaults to this process's own.
+ * @returns {string} The absolute path of the binary to check and start.
+ */
+export function attwBinaryPath(callerUrl, platform = process.platform) {
+  const name = platform === "win32" ? "attw.cmd" : "attw";
+  return fileURLToPath(new URL(`../node_modules/.bin/${name}`, callerUrl));
+}
+
+/**
+ * How many backslashes end `text`. Counted by hand rather than by a regular
+ * expression anchored at the end, which backtracks over every run of backslashes
+ * that does not end the string and is slow on a long one.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function trailingBackslashes(text) {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === "\\") end--;
+  return text.length - end;
+}
+
+/**
+ * How to start one of the three tools this gate runs (attw, npm and pnpm), on the
+ * platform given, with no shell wherever a shell is not needed.
+ *
+ * Off Windows it is the file and its arguments, as they are. ON WINDOWS a `.cmd`
+ * file cannot be started without `cmd.exe`: Node refuses it (EINVAL) since the
+ * April 2024 security releases, and npm and pnpm are `.cmd` files there too. So
+ * the command line is built here, every part in double quotes (but one, below),
+ * and handed to the
+ * shell whole, with no separate arguments for Node to join. Inside double quotes
+ * `cmd.exe` takes `&`, `|`, `<`, `>`, `^` and spaces literally. It does not take
+ * `"` (which ends the quoting) or `%` (which expands a variable) literally, and a
+ * line break ends the command, so a part carrying any of those THROWS rather than
+ * being escaped: an escape that is wrong runs a different command. Nothing this
+ * gate passes carries one, because `forwardable()` refuses them in a caller's
+ * arguments on every platform, so a throw here is a defect in this file and is
+ * left to propagate. A trailing run of backslashes in an argument is doubled, for
+ * node's own reading of the line after cmd.exe (see below).
+ *
+ * A BARE NAME FOUND ON PATH IS THE ONE PART LEFT UNQUOTED. `cmd.exe` starts a
+ * quoted batch file found through PATH with `%~dp0` pointing at the working
+ * directory instead of the file's own, and `npm.cmd` finds `npm-cli.js` through
+ * `%~dp0`. Measured on `windows-latest` with every part quoted: npm looked for
+ * `<package>\node_modules\npm\bin\npm-cli.js` and exited 1. A name made only of
+ * letters, digits, `.`, `_` and `-` needs no quotes; a path is quoted, and a
+ * batch file named by its full path gets the right `%~dp0` either way.
+ *
+ * @param {string} file The tool: a path, or a name found on PATH.
+ * @param {string[]} args Its arguments.
+ * @param {NodeJS.Platform} [platform] Defaults to this process's own.
+ * @returns {{ file: string, args: string[], shell: boolean }}
+ */
+export function toolCommand(file, args, platform = process.platform) {
+  if (platform !== "win32") return { file, args, shell: false };
+  const parts = [file, ...args];
+  const unsafe = parts.find((part) => /["%\r\n]/.test(part));
+  if (unsafe !== undefined) {
+    throw new Error(
+      `${JSON.stringify(unsafe)} cannot be passed through cmd.exe safely: it carries a ` +
+        `double quote, a percent sign or a line break.`,
+    );
+  }
+  const command = /^[\w.-]+$/.test(file) ? file : `"${file}"`;
+  // A TRAILING RUN OF BACKSLASHES IS DOUBLED. cmd.exe passes the quotes on, and node then splits
+  // its command line by the Microsoft C rules, where backslashes before a quote are halved and an
+  // odd one makes the quote literal. Unescaped, `node16\` would arrive as `node16" --format json`,
+  // one argument where three were sent. A backslash anywhere else is literal and left alone.
+  const line = [
+    command,
+    ...args.map((arg) => `"${arg}${"\\".repeat(trailingBackslashes(arg))}"`),
+  ].join(" ");
+  return { file: line, args: [], shell: true };
+}
+
 /**
  * The fields that CAN name a file and that `declaredArtifacts()` deliberately does
  * not read. THIS IS THE ONLY COPY OF THAT CLAIM: the pass line prints it, and
@@ -1050,7 +1148,9 @@ function packReportEntries(doc, name) {
  * @returns {{ files: Set<string>, error?: undefined } | { error: string, files?: undefined }}
  */
 function packedFiles(pkg, childEnv) {
-  const res = spawnSync("npm", ["pack", "--dry-run", "--json"], {
+  const npm = toolCommand("npm", ["pack", "--dry-run", "--json"]);
+  const res = spawnSync(npm.file, npm.args, {
+    shell: npm.shell,
     encoding: "utf8",
     stdio: ["inherit", "pipe", "pipe"],
     env: childEnv,
@@ -1263,7 +1363,9 @@ function pnpmPublished(childEnv) {
     return { error: `could not create a temporary directory for \`pnpm pack\`: ${err.message}` };
   }
   try {
-    const res = spawnSync("pnpm", ["pack", "--pack-destination", dest], {
+    const pnpm = toolCommand("pnpm", ["pack", "--pack-destination", dest]);
+    const res = spawnSync(pnpm.file, pnpm.args, {
+      shell: pnpm.shell,
       encoding: "utf8",
       stdio: ["inherit", "pipe", "pipe"],
       env: childEnv,
@@ -1361,7 +1463,8 @@ function gate({ callerUrl, argv = process.argv.slice(2) }) {
         `  node_modules, which is not the package being checked.`,
     );
   }
-  const ATTW_BIN = fileURLToPath(new URL("../node_modules/.bin/attw", callerUrl));
+  // `attw.cmd` on Windows, `attw` everywhere else: see `attwBinaryPath`.
+  const ATTW_BIN = attwBinaryPath(callerUrl);
   // THE BINARY IS CHECKED BEFORE IT IS SPAWNED, so the refusal NAMES THE PATH it
   // looked for. spawnSync reports ENOENT and EACCES the same way, and a message
   // built out of `res.error.message` is about a syscall rather than about which
@@ -1449,7 +1552,9 @@ function gate({ callerUrl, argv = process.argv.slice(2) }) {
   // reads structure, so the structure has to be there. A `.attw.json` can still
   // override it (config is applied after argv), and that is handled where it lands,
   // as an unparseable transcript, rather than by refusing the key by name.
-  const res = spawnSync(ATTW_BIN, ["--pack", ".", ...forwarded, "--format", "json"], {
+  const attw = toolCommand(ATTW_BIN, ["--pack", ".", ...forwarded, "--format", "json"]);
+  const res = spawnSync(attw.file, attw.args, {
+    shell: attw.shell,
     encoding: "utf8",
     stdio: ["inherit", "pipe", "pipe"],
     env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",