dslinter 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.0.10
+
+[compare changes](https://github.com/jrmybtlr/DSLint/compare/v0.0.9...v0.0.10)
+
+### 💅 Refactors
+
+- Rename dslint to dslinter and update related configurations ([9f15898](https://github.com/jrmybtlr/DSLint/commit/9f15898))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
 ## v0.0.8
 
 [compare changes](https://github.com/jrmybtlr/DSLint/compare/v0.0.7...v0.0.8)
@@ -53,7 +65,6 @@
 
 ## v0.0.2
 
-
 ### 🚀 Enhancements
 
 - Add DSLint MVP — JSX/Vue scan, usage rollup, governance rules ([4d64b76](https://github.com/jrmybtlr/DSLint/commit/4d64b76))
@@ -93,4 +104,3 @@
 
 - Jeremy Butler <jeremy.butler@laravel.com>
 - Cursor Agent ([@cursoragent](https://github.com/cursoragent))
-

package/README.md

@@ -39,29 +39,34 @@ Environment variables:
 
 **`oxlint`** on npm ships **Node native addons** as **`optionalDependencies`** (`@oxlint/binding-darwin-arm64`, …) built with **napi-rs** — each package is a small prebuilt library loaded by Node.
 
-**`dslint`** is a **standalone executable**. The practical pattern here is **download on install** from **GitHub Releases** (similar in spirit to tools that pull a platform binary once), instead of publishing dozens of `@dslinter/binding-*` packages.
+**`dslinter`** is a **standalone executable**. The practical pattern here is **download on install** from **GitHub Releases** (similar in spirit to tools that pull a platform binary once), instead of publishing dozens of `@dslinter/binding-*` packages.
+
+### Do not `cargo install dslint`
+
+The crates.io crate **`dslint`** (v0.0.x) is a **different project** (design-file linting). It is **not** this design-system scanner. Installing it will break `npx dslinter` if it ends up on your `PATH`.
+
+Use **`cargo install --git https://github.com/jrmybtlr/DSLint dslinter --locked`** or set **`DSLINT_BIN`** to a local `target/release/dslinter` build.
 
 ### If there is no matching release asset yet
 
-You’ll see a **warning** during install (install still succeeds) and **`dslinter`** falls back to **`dslint` on your PATH**, or prints install hints if missing:
+You’ll see a **warning** during install (install still succeeds). **`dslinter`** will try to download on first run; if no GitHub release exists yet, you get a clear error (not a silent fallback to the wrong `dslint` on crates.io):
 
 ```bash
 npx dslinter /path/to/repo --json -o dslint-report.json
 ```
 
-| Distribution | How users get `dslint` |
+| Distribution | How users get the scanner |
 |--------------|-------------------------|
-| **npm + GitHub Releases** | Default: postinstall download when release `vX.Y.Z` includes your platform asset. |
-| **GitHub Releases** | Manual download of `dslint-*` from the release; add to `PATH`. |
-| **crates.io** | `cargo install dslint` once published. |
+| **npm + GitHub Releases** | Default: download when release `vX.Y.Z` includes your platform asset. |
+| **GitHub Releases** | Manual download of `dslinter-*` from the release; run directly or set `DSLINT_BIN`. |
+| **From source** | `cargo install --git https://github.com/jrmybtlr/DSLint dslinter --locked` (not `cargo install dslint`). |
 
 Typical usage:
 
 ```bash
-dslint /path/to/repo --json -o dslint-report.json
-# or --serve for live reload while developing a dashboard
-# or equivalently (vendored or PATH):
 dslinter /path/to/repo --json -o dslint-report.json
+# or --serve for live reload while developing a dashboard
+# (npm `npx dslinter` runs the same binary)
 ```
 
 ## Styles (Tailwind v4)

package/bin/dslinter.mjs

@@ -1,37 +1,70 @@
 #!/usr/bin/env node
 /**
- * Runs the `dslint` scanner: prefers a vendored binary from postinstall, else `dslint` on PATH.
+ * Runs the design-system scanner (`dslinter` binary from GitHub Releases or DSLINT_BIN).
+ * Does NOT use bare `dslint` on PATH — that name is a different crate on crates.io.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { vendorBinaryPath } from "../scripts/resolve-dslint-binary.mjs";
+import { ensureDslintBinary } from "../scripts/ensure-dslint.mjs";
+import {
+  SCANNER_VERSION_MARKER,
+  vendorBinaryPath,
+} from "../scripts/resolve-dslint-binary.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
 
 const args = process.argv.slice(2);
 
-const vendored = vendorBinaryPath(packageRoot);
-const cmd = vendored && existsSync(vendored) ? vendored : "dslint";
-const child = spawnSync(cmd, args, { stdio: "inherit" });
+function isOurScanner(binary) {
+  const help = spawnSync(binary, ["--help"], { encoding: "utf8" });
+  const out = `${help.stdout ?? ""}${help.stderr ?? ""}`;
+  return out.includes(SCANNER_VERSION_MARKER);
+}
 
-if (child.error && "code" in child.error && child.error.code === "ENOENT") {
-  process.stderr.write(`dslint: command not found.
+async function resolveCommand() {
+  const fromEnv = process.env.DSLINT_BIN?.trim();
+  if (fromEnv) {
+    if (!existsSync(fromEnv)) {
+      process.stderr.write(`dslinter: DSLINT_BIN not found: ${fromEnv}\n`);
+      process.exit(127);
+    }
+    if (!isOurScanner(fromEnv)) {
+      process.stderr.write(
+        `dslinter: DSLINT_BIN does not look like the DSLint design-system scanner.\n` +
+          `  Expected output containing "${SCANNER_VERSION_MARKER}".\n`,
+      );
+      process.exit(1);
+    }
+    return fromEnv;
+  }
+
+  const vendored = vendorBinaryPath(packageRoot);
+  if (!existsSync(vendored)) {
+    await ensureDslintBinary(packageRoot, { quiet: true });
+  }
+  if (existsSync(vendored)) {
+    return vendored;
+  }
 
-The dslinter package can download a prebuilt dslint on npm install when a matching
-GitHub release exists (same tag as this package version, e.g. v0.0.6). See:
-https://github.com/jrmybtlr/DSLint/releases
+  if (process.env.DSLINT_ALLOW_PATH === "1") {
+    const onPath = spawnSync("dslinter", ["--version"], { encoding: "utf8" });
+    if (onPath.status === 0 && `${onPath.stdout}`.includes(SCANNER_VERSION_MARKER)) {
+      return "dslinter";
+    }
+  }
 
-Otherwise install dslint on PATH:
+  await import("../scripts/print-missing-scanner.mjs");
+  process.exit(127);
+}
 
-  cargo install dslint
-  # or from this repo:
-  cargo install --path .
+const cmd = await resolveCommand();
+const child = spawnSync(cmd, args, { stdio: "inherit" });
 
-Skip auto-download (air-gapped): DSLINT_SKIP_DOWNLOAD=1
-`);
+if (child.error && "code" in child.error && child.error.code === "ENOENT") {
+  process.stderr.write(`dslinter: failed to execute ${cmd}\n`);
   process.exit(127);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dslinter",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "DSLinter dashboard UI: playground shell, token wall, and governance panels (consumes dslint-report.json).",
   "license": "Apache-2.0",
   "type": "module",

package/scripts/ensure-dslint.mjs

@@ -1,16 +1,18 @@
 /**
- * Best-effort download of the prebuilt `dslint` CLI for this platform.
- * Runs on `npm install dslinter` (postinstall). Exits 0 even when the binary
- * is missing (no release yet / offline) so installs never fail.
+ * Best-effort download of the prebuilt `dslinter` CLI for this platform.
+ * Used by postinstall and on first `dslinter` / `npx dslinter` invocation.
  */
 import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { chmod, mkdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { releaseAssetBaseName, vendorBinaryPath } from "./resolve-dslint-binary.mjs";
+import {
+  releaseAssetBaseName,
+  vendorBinaryPath,
+} from "./resolve-dslint-binary.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const packageRoot = join(__dirname, "..");
+const defaultPackageRoot = join(__dirname, "..");
 
 async function pathExists(p) {
   try {
@@ -21,8 +23,10 @@ async function pathExists(p) {
   }
 }
 
-function readPackageVersion() {
-  const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+function readPackageVersion(packageRoot) {
+  const pkg = JSON.parse(
+    readFileSync(join(packageRoot, "package.json"), "utf8"),
+  );
   return pkg.version;
 }
 
@@ -32,65 +36,99 @@ function releaseTag(version) {
   return `v${version}`;
 }
 
-async function main() {
-  if (process.env.DSLINT_SKIP_DOWNLOAD === "1") return;
+function releaseRepo() {
+  return process.env.DSLINT_GITHUB_REPO?.trim() || "jrmybtlr/DSLint";
+}
+
+function assetUrl(tag, asset) {
+  return `https://github.com/${releaseRepo()}/releases/download/${tag}/${asset}`;
+}
+
+/**
+ * @param {string} packageRoot
+ * @param {{ quiet?: boolean }} [opts]
+ * @returns {Promise<boolean>} true if vendored binary exists after this call
+ */
+export async function ensureDslintBinary(packageRoot = defaultPackageRoot, opts = {}) {
+  const { quiet = false } = opts;
+  const log = quiet ? () => {} : console.warn.bind(console);
+
+  if (process.env.DSLINT_SKIP_DOWNLOAD === "1") {
+    return pathExists(vendorBinaryPath(packageRoot));
+  }
 
   const dest = vendorBinaryPath(packageRoot);
-  if (await pathExists(dest)) return;
+  if (await pathExists(dest)) return true;
 
   const asset = releaseAssetBaseName();
   if (!asset) {
-    console.warn(
-      `[dslinter] No prebuilt dslint for ${process.platform}-${process.arch}. Install Rust and put dslint on PATH, or set DSLINT_SKIP_DOWNLOAD=1.`,
+    log(
+      `[dslinter] No prebuilt scanner for ${process.platform}-${process.arch}.`,
     );
-    return;
+    return false;
   }
 
-  const version = readPackageVersion();
-  const tag = releaseTag(version);
-  const repo = process.env.DSLINT_GITHUB_REPO?.trim() || "jrmybtlr/DSLint";
-  const url = `https://github.com/${repo}/releases/download/${tag}/${asset}`;
+  const version = readPackageVersion(packageRoot);
+  const tagsToTry = [releaseTag(version)];
+  if (process.env.DSLINT_USE_LATEST_RELEASE !== "0") {
+    tagsToTry.push("latest");
+  }
 
   const vendorDir = join(packageRoot, "vendor");
   await mkdir(vendorDir, { recursive: true });
-
   const tmp = `${dest}.part`;
 
-  try {
-    const res = await fetch(url, { redirect: "follow" });
-    if (res.status === 404) {
-      console.warn(
-        `[dslinter] No GitHub release asset at ${url}\n` +
-          `  Create release ${tag} with ${asset} (see .github/workflows/release-dslint-binaries.yml), or install dslint via cargo / PATH.`,
-      );
-      return;
-    }
-    if (!res.ok) {
-      console.warn(`[dslinter] Download failed (${res.status}): ${url}`);
-      return;
-    }
-
-    const buf = Buffer.from(await res.arrayBuffer());
-    writeFileSync(tmp, buf);
-
+  for (const tag of tagsToTry) {
+    const url = assetUrl(tag, asset);
     try {
-      if (await pathExists(dest)) unlinkSync(dest);
-    } catch {
-      /* ignore */
-    }
-    renameSync(tmp, dest);
+      const res = await fetch(url, { redirect: "follow" });
+      if (res.status === 404) continue;
+      if (!res.ok) {
+        log(`[dslinter] Download failed (${res.status}): ${url}`);
+        continue;
+      }
 
-    if (process.platform !== "win32") {
-      await chmod(dest, 0o755);
-    }
-  } catch (err) {
-    console.warn(`[dslinter] Could not download dslint: ${err instanceof Error ? err.message : err}`);
-    try {
-      unlinkSync(tmp);
-    } catch {
-      /* ignore */
+      const buf = Buffer.from(await res.arrayBuffer());
+      writeFileSync(tmp, buf);
+      try {
+        if (await pathExists(dest)) unlinkSync(dest);
+      } catch {
+        /* ignore */
+      }
+      renameSync(tmp, dest);
+      if (process.platform !== "win32") {
+        await chmod(dest, 0o755);
+      }
+      if (tag === "latest" && !quiet) {
+        log(
+          `[dslinter] Installed scanner from latest GitHub release (no asset for npm v${version}).`,
+        );
+      }
+      return true;
+    } catch (err) {
+      log(
+        `[dslinter] Could not download: ${err instanceof Error ? err.message : err}`,
+      );
+      try {
+        unlinkSync(tmp);
+      } catch {
+        /* ignore */
+      }
     }
   }
+
+  log(
+    `[dslinter] No GitHub release with asset "${asset}" (tried ${tagsToTry.join(", ")}).\n` +
+      `  Publish tag ${releaseTag(version)} with workflow release-dslint-binaries.yml, or set DSLINT_BIN to a local build.`,
+  );
+  return false;
 }
 
-await main();
+const isMain =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === process.argv[1];
+
+if (isMain) {
+  const ok = await ensureDslintBinary();
+  process.exit(ok ? 0 : 0);
+}

package/scripts/print-missing-scanner.mjs

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const version = JSON.parse(
+  readFileSync(join(packageRoot, "package.json"), "utf8"),
+).version;
+
+process.stderr.write(`dslinter: scanner binary not available.
+
+This npm package is NOT the same as \`cargo install dslint\` on crates.io (that is a
+different "design file" linter and will crash or misbehave).
+
+To run the design-system scanner:
+
+  1. Re-run after a GitHub release exists for v${version} (prebuilt download), or
+  2. Build from this repo and point at it:
+       cargo install --git https://github.com/jrmybtlr/DSLint dslinter --locked
+       export DSLINT_BIN="$(command -v dslinter)"
+       npx dslinter ...
+  3. Or set DSLINT_BIN to your local target/release/dslinter
+
+Releases: https://github.com/jrmybtlr/DSLint/releases
+`);

package/scripts/resolve-dslint-binary.mjs

@@ -1,5 +1,8 @@
 import { join } from "node:path";
 
+/** CLI binary name (avoids collision with unrelated `dslint` on crates.io). */
+export const CLI_BINARY_NAME = "dslinter";
+
 /**
  * Maps the current OS/arch to the GitHub release asset basename (must match CI upload names).
  * @param {NodeJS.Process} [proc]
@@ -7,11 +10,21 @@ import { join } from "node:path";
  */
 export function releaseAssetBaseName(proc = process) {
   const { platform, arch } = proc;
-  if (platform === "darwin" && arch === "arm64") return "dslint-aarch64-apple-darwin";
-  if (platform === "darwin" && arch === "x64") return "dslint-x86_64-apple-darwin";
-  if (platform === "linux" && arch === "x64") return "dslint-x86_64-unknown-linux-gnu";
-  if (platform === "linux" && arch === "arm64") return "dslint-aarch64-unknown-linux-gnu";
-  if (platform === "win32" && arch === "x64") return "dslint-x86_64-pc-windows-msvc.exe";
+  if (platform === "darwin" && arch === "arm64") {
+    return "dslinter-aarch64-apple-darwin";
+  }
+  if (platform === "darwin" && arch === "x64") {
+    return "dslinter-x86_64-apple-darwin";
+  }
+  if (platform === "linux" && arch === "x64") {
+    return "dslinter-x86_64-unknown-linux-gnu";
+  }
+  if (platform === "linux" && arch === "arm64") {
+    return "dslinter-aarch64-unknown-linux-gnu";
+  }
+  if (platform === "win32" && arch === "x64") {
+    return "dslinter-x86_64-pc-windows-msvc.exe";
+  }
   return null;
 }
 
@@ -20,6 +33,10 @@ export function releaseAssetBaseName(proc = process) {
  * @param {NodeJS.Process} [proc]
  */
 export function vendorBinaryPath(packageRoot, proc = process) {
-  const name = proc.platform === "win32" ? "dslint.exe" : "dslint";
+  const name =
+    proc.platform === "win32" ? `${CLI_BINARY_NAME}.exe` : CLI_BINARY_NAME;
   return join(packageRoot, "vendor", name);
 }
+
+/** Our scanner prints this in `dslinter --version` help output (clap about line). */
+export const SCANNER_VERSION_MARKER = "design system linting";

package/src/{shell → components}/DashboardCommandPalette.tsx

@@ -10,7 +10,7 @@ import {
 } from "@/components/ui/command";
 
 import type { PlaygroundEntry } from "../types/playground";
-import type { HashRoute } from "./hashRoute";
+import type { HashRoute } from "../shell/hashRoute";
 
 type Props = {
   entries: PlaygroundEntry[];

package/src/{shell → components}/Sidebar.tsx

@@ -3,8 +3,8 @@ import { IconMoon, IconSearch, IconSun } from "@/components/icons";
 import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 
 import type { PlaygroundEntry } from "../types/playground";
-import type { HashRoute } from "./hashRoute";
-import type { DashboardThemePreference } from "./DashboardLayout";
+import type { HashRoute } from "../shell/hashRoute";
+import type { DashboardThemePreference } from "../shell/DashboardLayout";
 
 type Props = {
   entries: PlaygroundEntry[];

package/src/dashboard/ComponentUsageDetails.tsx

@@ -10,7 +10,7 @@ import {
 import type { UsageLocation, WorkspaceReport } from "../types/report";
 import { usageMap } from "./aggregate";
 import { shortPath } from "./paths";
-import { EmptyCard } from "../shell/EmptyCard";
+import { EmptyCard } from "../components/EmptyCard";
 import { InlineCode } from "@/components/InlineCode";
 
 function formatCallSiteProps(loc: UsageLocation): string {

package/src/dashboard/DashboardBody.tsx

@@ -1,4 +1,4 @@
-import { Section } from "../shell/Section";
+import { Section } from "../components/Section";
 import {
   Table,
   TableBody,

package/src/resolve-dslint-binary.test.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
+  CLI_BINARY_NAME,
   releaseAssetBaseName,
   vendorBinaryPath,
 } from "../scripts/resolve-dslint-binary.mjs";
@@ -12,19 +13,19 @@ function proc(platform: string, arch: string): NodeJS.Process {
 describe("releaseAssetBaseName", () => {
   it("maps darwin arm64", () => {
     expect(releaseAssetBaseName(proc("darwin", "arm64"))).toBe(
-      "dslint-aarch64-apple-darwin",
+      "dslinter-aarch64-apple-darwin",
     );
   });
 
   it("maps linux x64", () => {
     expect(releaseAssetBaseName(proc("linux", "x64"))).toBe(
-      "dslint-x86_64-unknown-linux-gnu",
+      "dslinter-x86_64-unknown-linux-gnu",
     );
   });
 
   it("maps win32 x64", () => {
     expect(releaseAssetBaseName(proc("win32", "x64"))).toBe(
-      "dslint-x86_64-pc-windows-msvc.exe",
+      "dslinter-x86_64-pc-windows-msvc.exe",
     );
   });
 
@@ -34,15 +35,15 @@ describe("releaseAssetBaseName", () => {
 });
 
 describe("vendorBinaryPath", () => {
-  it("uses dslint.exe on Windows", () => {
+  it("uses dslinter.exe on Windows", () => {
     expect(vendorBinaryPath(join("/", "pkg"), proc("win32", "x64"))).toBe(
-      join("/", "pkg", "vendor", "dslint.exe"),
+      join("/", "pkg", "vendor", `${CLI_BINARY_NAME}.exe`),
     );
   });
 
-  it("uses dslint on Unix", () => {
+  it("uses dslinter on Unix", () => {
     expect(vendorBinaryPath(join("/", "pkg"), proc("linux", "x64"))).toBe(
-      join("/", "pkg", "vendor", "dslint"),
+      join("/", "pkg", "vendor", CLI_BINARY_NAME),
     );
   });
 });

package/src/shell/DashboardLayout.tsx

@@ -12,11 +12,11 @@ import type { TokenCatalog } from "../types/tokenCatalog";
 import type { DslinterReportState } from "../dashboard/useWorkspaceReport";
 import { Button } from "@/components/ui/button";
 import { cn } from "../lib/utils";
-import { ComponentPlaygroundPane } from "./ComponentPlaygroundPane";
-import { GovernancePane } from "./GovernancePane";
-import { Sidebar } from "./Sidebar";
-import { TokensPane } from "./TokensPane";
-import { DashboardCommandPalette } from "./DashboardCommandPalette";
+import { ComponentPlaygroundPane } from "../components/ComponentPlaygroundPane";
+import { GovernancePane } from "../components/GovernancePane";
+import { Sidebar } from "../components/Sidebar";
+import { TokensPane } from "../components/TokensPane";
+import { DashboardCommandPalette } from "../components/DashboardCommandPalette";
 import { useHashRoute } from "./useHashRoute";
 
 const STORAGE_KEY = "dslinter-dashboard-theme";