ref(cli): share the platform-binary resolver between ast-grep and Vale

Task 1.1. `findSgBinary()` hard-coded ast-grep's packaging: the `@ast-grep/cli`
prefix, the `-gnu`/`-msvc` suffixes, the two bin spellings, and an `ast-grep`
identity check. Vale needs the same search with different answers to all four,
so the search moves to `rules/platform-binary.ts` and each engine supplies a
spec.

The parameter that matters is `toolchainSuffix`. ast-grep publishes
`@ast-grep/cli-linux-x64-gnu`; add-vale-binary-packages publishes
`@taskless/vale-linux-x64` with no libc suffix at all. Reusing ast-grep's naming
for Vale would resolve nothing on Linux and surface as the ordinary "Vale is
unavailable" message — a naming bug wearing the costume of a host that never
installed it. test/platform-binary.test.ts pins the naming for both engines
across every published platform, and cross-checks the Vale names against the
optionalDependencies actually declared in package.json so a rename on either
side fails there rather than at runtime.

The resolver returns `{path, tried}` instead of throwing, because the two
callers need different things from a miss: ast-grep is the only executor for
`sg` rules, so `findSgBinary()` keeps throwing, while `findValeBinary()` returns
undefined per D6b — a missing Vale binary makes one engine unavailable and must
not abort the others. `findValeBinary()` caches the miss as well as the hit,
since an absent Vale is the common case and each resolution spawns a subprocess
per candidate.

ast-grep behaviour is unchanged: `isAstGrepBinary` and `findSgBinary` keep their
signatures and their existing tests, all 456 green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jwc9FFroR3mTZ4hLiSkkX3

Author: thecodedrift

packages/cli/src/rules/platform-binary.ts

@@ -0,0 +1,168 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Resolving a prebuilt binary that ships as a per-platform npm package.
+ *
+ * This was ast-grep's resolver in `scan.ts`, generalized when Vale became a
+ * second engine that needs the same treatment. Both depend on per-platform
+ * packages directly and exec by path, because neither can rely on an
+ * install-time step: `@ast-grep/cli`'s postinstall hardlink fails under pnpm
+ * dlx's strict isolation, and the `@taskless/vale-*` packages deliberately ship
+ * no `bin` and no scripts at all.
+ *
+ * WHAT IS PARAMETERIZED, and why each field exists rather than being derived:
+ *
+ * - `toolchainSuffix` is the one that bites. ast-grep publishes
+ *   `@ast-grep/cli-linux-x64-gnu` and `-win32-x64-msvc`; the Vale packages are
+ *   `@taskless/vale-linux-x64` with **no libc suffix at all**. Reusing
+ *   ast-grep's naming for Vale would look up `@taskless/vale-linux-x64-gnu` and
+ *   miss on every Linux host — a resolution failure that reads as "Vale is not
+ *   installed" rather than as a naming bug.
+ * - `identity` exists because existence is not proof. A file can sit exactly
+ *   where the binary belongs and not be the binary: ast-grep's failed hardlink
+ *   leaves a placeholder text file there. Asking a candidate to identify itself
+ *   is the only check that tells the two apart.
+ */
+export interface PlatformBinarySpec {
+  /** Name used in error messages, e.g. `ast-grep`. */
+  label: string;
+  /** Package name up to the platform suffix, e.g. `@ast-grep/cli`. */
+  packagePrefix: string;
+  /**
+   * Append the platform's toolchain suffix (`-gnu` on Linux, `-msvc` on
+   * Windows). True for ast-grep, false for the Vale packages.
+   */
+  toolchainSuffix: boolean;
+  /**
+   * Executable names to try, in confidence order, spelled for unix. `.exe` is
+   * appended on Windows. More than one because ast-grep declares both
+   * `ast-grep` and `sg` for the same target.
+   */
+  binaryNames: string[];
+  /** Pattern the candidate's own `--version` output must match. */
+  identity: RegExp;
+}
+
+/** The npm package carrying this host's prebuilt binary. */
+export function platformPackageName(spec: PlatformBinarySpec): string {
+  const parts: string[] = [process.platform, process.arch];
+  if (spec.toolchainSuffix) {
+    if (process.platform === "linux") {
+      parts.push("gnu");
+    } else if (process.platform === "win32") {
+      parts.push("msvc");
+    }
+  }
+  return `${spec.packagePrefix}-${parts.join("-")}`;
+}
+
+/** Executable name for this platform. */
+function executableName(name: string): string {
+  return process.platform === "win32" ? `${name}.exe` : name;
+}
+
+/** Absolute path to a binary inside the resolved platform package, if any. */
+function platformPackageBinary(
+  spec: PlatformBinarySpec,
+  binary: string
+): string | undefined {
+  try {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve(
+      `${platformPackageName(spec)}/package.json`
+    );
+    return resolve(dirname(packageJsonPath), binary);
+  } catch {
+    // Not installed for this host: an unsupported arch, or musl, where neither
+    // project publishes a build and `os`/`cpu` filtering skips the package.
+    return undefined;
+  }
+}
+
+/** First entry on PATH that holds a file named `command`. */
+export function findOnPath(command: string): string | undefined {
+  const separator = process.platform === "win32" ? ";" : ":";
+  for (const directory of (process.env.PATH ?? "").split(separator)) {
+    if (directory === "") continue;
+    const candidate = resolve(directory, command);
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * Whether `path` is really this binary, established by running it.
+ *
+ * See {@link PlatformBinarySpec.identity} — existence is not enough, because a
+ * placeholder file left by a failed install sits at exactly the right path and
+ * satisfies `existsSync` happily.
+ */
+export function isPlatformBinary(
+  spec: PlatformBinarySpec,
+  path: string
+): boolean {
+  if (!existsSync(path)) return false;
+  const result = spawnSync(path, ["--version"], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  if (result.error !== undefined || result.status !== 0) return false;
+  return spec.identity.test(`${result.stdout ?? ""}${result.stderr ?? ""}`);
+}
+
+export interface PlatformBinaryResolution {
+  /** Absolute path to the verified binary, or `undefined` when none resolved. */
+  path: string | undefined;
+  /** Locations searched, in order, for an actionable failure message. */
+  tried: string[];
+}
+
+/**
+ * Search every place the binary could reasonably live, verifying each.
+ *
+ * Candidates are ordered by confidence rather than by convenience — the
+ * platform package first because it is the version we pinned, then a locally
+ * linked binary, then whatever the host provides on PATH.
+ *
+ * Returns rather than throws. The two callers want different things from a
+ * miss: ast-grep cannot run at all without it, while a missing Vale binary
+ * makes one engine unavailable and must not abort the others (D6b). Encoding
+ * "not found" as a value rather than an exception is what lets each decide.
+ */
+export function resolvePlatformBinary(
+  spec: PlatformBinarySpec
+): PlatformBinaryResolution {
+  const localBin = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "node_modules",
+    ".bin"
+  );
+
+  const candidates: Array<[label: string, path: string | undefined]> = [
+    ...spec.binaryNames.map((name): [string, string | undefined] => [
+      platformPackageName(spec),
+      platformPackageBinary(spec, executableName(name)),
+    ]),
+    ...spec.binaryNames.map((name): [string, string | undefined] => [
+      "node_modules/.bin",
+      resolve(localBin, executableName(name)),
+    ]),
+    ...spec.binaryNames.map((name): [string, string | undefined] => [
+      "PATH",
+      findOnPath(executableName(name)),
+    ]),
+  ];
+
+  for (const [, path] of candidates) {
+    if (path !== undefined && isPlatformBinary(spec, path)) {
+      return { path, tried: candidates.map(([label]) => label) };
+    }
+  }
+
+  return { path: undefined, tried: candidates.map(([label]) => label) };
+}

packages/cli/src/rules/scan.ts

@@ -1,13 +1,16 @@
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { dirname, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 
 import type { AstGrepMatch } from "../types/check";
 import { toCheckResult, type CheckResult } from "../types/check";
 import { COMMITTED_SG_CONFIG } from "./engines";
+import {
+  isPlatformBinary,
+  resolvePlatformBinary,
+  type PlatformBinarySpec,
+} from "./platform-binary";
 
 export interface ScanResult {
   results: CheckResult[];
@@ -30,42 +33,23 @@ export function buildPath(): string {
   return `${binDirectory}${separator}${process.env.PATH ?? ""}`;
 }
 
-/** The npm package carrying this host's prebuilt ast-grep binary. */
-function platformPackageName(): string {
-  const parts: string[] = [process.platform, process.arch];
-  if (process.platform === "linux") {
-    parts.push("gnu");
-  } else if (process.platform === "win32") {
-    parts.push("msvc");
-  }
-  return `@ast-grep/cli-${parts.join("-")}`;
-}
-
-/** Absolute path to the binary inside the resolved platform package, if any. */
-function platformPackageBinary(binary: string): string | undefined {
-  try {
-    const require = createRequire(import.meta.url);
-    const packageJsonPath = require.resolve(
-      `${platformPackageName()}/package.json`
-    );
-    return resolve(dirname(packageJsonPath), binary);
-  } catch {
-    // Not installed for this host (unsupported arch, or musl — upstream
-    // publishes no musl package and marks the gnu ones `libc: [glibc]`).
-    return undefined;
-  }
-}
-
-/** First entry on PATH that holds a file named `command`. */
-function findOnPath(command: string): string | undefined {
-  const separator = process.platform === "win32" ? ";" : ":";
-  for (const directory of (process.env.PATH ?? "").split(separator)) {
-    if (directory === "") continue;
-    const candidate = resolve(directory, command);
-    if (existsSync(candidate)) return candidate;
-  }
-  return undefined;
-}
+/**
+ * ast-grep's per-platform packaging, as the shared resolver understands it.
+ *
+ * `toolchainSuffix: true` is what produces `@ast-grep/cli-linux-x64-gnu` and
+ * `-win32-x64-msvc`. The Vale packages set it false; see
+ * {@link PlatformBinarySpec} for why that distinction is load-bearing.
+ *
+ * Both `ast-grep` and `sg` are listed because the wrapper declares them as bin
+ * entries for the same target, so either may be what got linked.
+ */
+export const AST_GREP_BINARY: PlatformBinarySpec = {
+  label: "ast-grep",
+  packagePrefix: "@ast-grep/cli",
+  toolchainSuffix: true,
+  binaryNames: ["ast-grep", "sg"],
+  identity: /ast-grep/i,
+};
 
 /**
  * Whether `path` is really ast-grep, established by running it.
@@ -78,13 +62,7 @@ function findOnPath(command: string): string | undefined {
  * binary from a file merely sitting where the binary belongs.
  */
 export function isAstGrepBinary(path: string): boolean {
-  if (!existsSync(path)) return false;
-  const result = spawnSync(path, ["--version"], {
-    encoding: "utf8",
-    timeout: 5000,
-  });
-  if (result.error !== undefined || result.status !== 0) return false;
-  return /ast-grep/i.test(`${result.stdout ?? ""}${result.stderr ?? ""}`);
+  return isPlatformBinary(AST_GREP_BINARY, path);
 }
 
 /**
@@ -113,36 +91,18 @@ let cachedSgBinary: string | undefined;
 export function findSgBinary(): string {
   if (cachedSgBinary !== undefined) return cachedSgBinary;
 
-  const binary = process.platform === "win32" ? "ast-grep.exe" : "ast-grep";
-  const alternative = process.platform === "win32" ? "sg.exe" : "sg";
-  const localBin = resolve(
-    dirname(fileURLToPath(import.meta.url)),
-    "..",
-    "node_modules",
-    ".bin"
-  );
-
-  const candidates: Array<[label: string, path: string | undefined]> = [
-    [platformPackageName(), platformPackageBinary(binary)],
-    // Both names, matching the PATH search below: the wrapper declares `sg` and
-    // `ast-grep` as bin entries for the same target, so either may be linked.
-    ["node_modules/.bin", resolve(localBin, alternative)],
-    ["node_modules/.bin", resolve(localBin, binary)],
-    ["PATH", findOnPath(alternative)],
-    ["PATH", findOnPath(binary)],
-  ];
-
-  for (const [, path] of candidates) {
-    if (path !== undefined && isAstGrepBinary(path)) {
-      cachedSgBinary = path;
-      return path;
-    }
+  const { path, tried } = resolvePlatformBinary(AST_GREP_BINARY);
+  if (path !== undefined) {
+    cachedSgBinary = path;
+    return path;
   }
 
-  const tried = candidates.map(([label]) => label).join(", ");
+  // ast-grep, unlike Vale, has no degraded mode: it is the executor for every
+  // `sg` rule, so a miss is fatal for this command rather than one engine
+  // reporting itself unavailable.
   throw new Error(
-    `ast-grep binary not found. Looked in: ${tried}. Install a supported ` +
-      `platform build, or put \`${alternative}\` on your PATH.`
+    `ast-grep binary not found. Looked in: ${tried.join(", ")}. Install a ` +
+      `supported platform build, or put \`sg\` on your PATH.`
   );
 }
 

packages/cli/src/rules/vale/binary.ts

@@ -0,0 +1,66 @@
+import {
+  resolvePlatformBinary,
+  type PlatformBinarySpec,
+} from "../platform-binary";
+
+/**
+ * Vale's per-platform packaging.
+ *
+ * `toolchainSuffix: false` is the whole reason this spec exists separately from
+ * ast-grep's. `add-vale-binary-packages` publishes `@taskless/vale-<os>-<cpu>`
+ * — `@taskless/vale-linux-x64`, not `-linux-x64-gnu`. ast-grep's resolver
+ * appends `-gnu` on every Linux, so reusing its naming here would resolve
+ * nothing on Linux while reporting the ordinary "Vale is unavailable" message,
+ * making a naming bug indistinguishable from a host without the binary.
+ *
+ * One binary name, unlike ast-grep's two: these packages ship `vale` (or
+ * `vale.exe`) as pure payload, with no `bin` entry and no lifecycle script, so
+ * there is no wrapper spelling to also try.
+ */
+export const VALE_BINARY: PlatformBinarySpec = {
+  label: "vale",
+  packagePrefix: "@taskless/vale",
+  toolchainSuffix: false,
+  binaryNames: ["vale"],
+  identity: /vale/i,
+};
+
+/**
+ * Resolution is cached for the process, including a miss.
+ *
+ * Caching the miss matters as much as caching the hit: resolution spawns a
+ * subprocess per candidate, and an absent Vale is the common case on a host
+ * that never installed it. Without this, every rule would re-run the whole
+ * search to rediscover the same nothing.
+ */
+let cached: { path: string | undefined; tried: string[] } | undefined;
+
+/**
+ * Locate the Vale binary, or report that it is unavailable.
+ *
+ * Returns `undefined` rather than throwing, per D6b: a missing Vale binary
+ * makes the Vale engine unavailable and must not abort the other engines. The
+ * caller turns that into a reported-but-not-fatal outcome; ast-grep's resolver
+ * throws instead, because it has no degraded mode.
+ */
+export function findValeBinary(): {
+  path: string | undefined;
+  tried: string[];
+} {
+  cached ??= resolvePlatformBinary(VALE_BINARY);
+  return cached;
+}
+
+/** Reset the process cache. Tests only. */
+export function resetValeBinaryCache(): void {
+  cached = undefined;
+}
+
+/** An actionable message naming where we looked. */
+export function valeUnavailableMessage(tried: string[]): string {
+  return (
+    `Vale binary not found. Looked in: ${tried.join(", ")}. Install a ` +
+    `supported platform build, or put \`vale\` on your PATH. Other engines ` +
+    `still ran.`
+  );
+}