dslinter 0.0.27 → 0.0.29

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v0.0.29
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.28...v0.0.29)
+
+### 💅 Refactors
+
+- Enhance dashboard directory resolution and improve dev mode output ([5670315](https://github.com/jrmybtlr/DSLinter/commit/5670315))
+
+### 🏡 Chore
+
+- Update GitHub Actions and package.json ([b9541b2](https://github.com/jrmybtlr/DSLinter/commit/b9541b2))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
+## v0.0.28
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.27...v0.0.28)
+
+### 🏡 Chore
+
+- Update dashboard build process and CLI commands ([43c71d6](https://github.com/jrmybtlr/DSLinter/commit/43c71d6))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
 ## v0.0.27
 
 [compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.26...v0.0.27)

package/README.md

@@ -19,7 +19,17 @@ This package is **source-first**: entry points resolve to TypeScript/TSX under `
 
 ## CLI (`npx dslinter`)
 
-The **`dslinter`** command runs the design-system scanner with the same flags as the Rust CLI (`--json`, `-o`, `--serve`, etc.) via a **napi-rs** native binding (same distribution model as **`oxlint`**).
+The **`dslinter`** command orchestrates the Rust scanner (via **napi-rs**, same distribution model as **`oxlint`**) and, in a Vite host app, the dashboard dev loop.
+
+| Mode | Flag | Behavior |
+|------|------|----------|
+| Dev (default locally) | _(none)_ | `--serve`, watch, write `--output`, start Vite `--mode serve` |
+| Report | `--report` | One-shot scan; human stdout or `--json`; `--output` writes JSON |
+| Watch | `--watch` | Watch + write JSON only |
+| Build | `--build` | One-shot report to `--output`, then `vite build` |
+| CI default | `CI=true` | Same as `--report` |
+
+Scanner flags: `--json`, `-p` / `--parallel`, `--fail-on-warnings`, `--max-warnings`, `--output`, `[PATH]`. Low-level: `--serve <port>` (watch + HTTP, no Vite).
 
 ### Without installing Rust
 
@@ -38,10 +48,14 @@ The crates.io crate **`dslint`** is a **different project**. Use **`cargo instal
 Typical usage:
 
 ```bash
-dslinter /path/to/repo --json -o dslint-report.json
-# or --serve for live reload while developing a dashboard
+npx dslinter                              # dev (watch + dashboard)
+npx dslinter --report /path/to/repo --json
+npx dslinter --report --output public/dslint-report.json
+npx dslinter --watch --output public/dslint-report.json
 ```
 
+Set `DSLINT_SERVE_PORT` to override the default scanner port (`7878`). Your Vite config should proxy `/dslint-report.json` and `/events` to that port in `serve` mode (see repo `demo/vite.config.ts`).
+
 ## Styles (Tailwind v4)
 
 1. In your app CSS, load Tailwind, then point Tailwind at this package so utility scanning picks up dashboard classes:

package/bin/dslinter.mjs

@@ -1,77 +1,54 @@
 #!/usr/bin/env node
 /**
- * Runs the design-system scanner via the NAPI native binding (oxlint-style).
- * Falls back to DSLINT_BIN (cargo-built binary) when set.
+ * DSLinter CLI: mode routing (dev / report / watch / build) + scanner (NAPI or DSLINT_BIN).
  */
-import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { parseDslinterArgs } from "./lib/parse-args.mjs";
+import { runScannerInternal } from "./lib/run-scanner.mjs";
+import { runBuildMode } from "./modes/build.mjs";
+import { runDevMode } from "./modes/dev.mjs";
+import { runReportMode } from "./modes/report.mjs";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const packageRoot = join(__dirname, "..");
-const require = createRequire(import.meta.url);
+const rawArgs = process.argv.slice(2);
 
-const args = process.argv.slice(2);
-
-const SCANNER_VERSION_MARKER = "design system linting";
-
-function isOurScanner(binary) {
-  const help = spawnSync(binary, ["--help"], { encoding: "utf8" });
-  const out = `${help.stdout ?? ""}${help.stderr ?? ""}`;
-  return out.includes(SCANNER_VERSION_MARKER);
+if (process.env.DSLINTER_INTERNAL === "1") {
+  runScannerInternal(rawArgs);
 }
 
-function runViaNapi() {
-  let runCli;
-  try {
-    ({ runCli } = require(join(packageRoot, "index.cjs")));
-  } catch (err) {
-    process.stderr.write(
-      `dslinter: failed to load native binding.\n` +
-        `  Run \`pnpm --filter dslinter run build:napi\` from the repo root, or reinstall dslinter.\n` +
-        `  ${err instanceof Error ? err.message : err}\n`,
-    );
-    process.exit(127);
-  }
-
-  const argv = ["dslinter", ...args];
-  const code = runCli(argv);
-  process.exit(code);
+if (rawArgs.includes("--version") || rawArgs.includes("-V")) {
+  runScannerInternal(["--version"]);
 }
 
-function runViaBinary(binary) {
-  const child = spawnSync(binary, args, { stdio: "inherit" });
-  if (child.error && "code" in child.error && child.error.code === "ENOENT") {
-    process.stderr.write(`dslinter: failed to execute ${binary}\n`);
-    process.exit(127);
-  }
-  process.exit(child.status === null ? 1 : child.status);
+if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+  runScannerInternal(["--help"]);
 }
 
-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);
-  }
-  runViaBinary(fromEnv);
+let parsed;
+try {
+  parsed = parseDslinterArgs(rawArgs);
+} catch (err) {
+  process.stderr.write(`${err instanceof Error ? err.message : err}\n`);
+  process.exit(1);
 }
 
-if (process.env.DSLINT_ALLOW_PATH === "1") {
-  const onPath = spawnSync("dslinter", ["--help"], { encoding: "utf8" });
-  const out = `${onPath.stdout ?? ""}${onPath.stderr ?? ""}`;
-  if (onPath.status === 0 && out.includes(SCANNER_VERSION_MARKER)) {
-    runViaBinary("dslinter");
-  }
+const { mode, scannerArgs } = parsed;
+
+switch (mode) {
+  case "dev":
+    await runDevMode(parsed);
+    break;
+  case "report":
+    runReportMode(["--report", ...scannerArgs]);
+    break;
+  case "watch":
+    runScannerInternal(["--watch", ...scannerArgs]);
+    break;
+  case "scanner":
+    runScannerInternal(scannerArgs);
+    break;
+  case "build":
+    runBuildMode(parsed);
+    break;
+  default:
+    process.stderr.write(`dslinter: unknown mode ${mode}\n`);
+    process.exit(1);
 }
-
-runViaNapi();

package/bin/lib/parse-args.mjs

@@ -0,0 +1,79 @@
+/**
+ * Parse dslinter CLI argv into mode + scanner args (no subprocess).
+ */
+
+const MODE_FLAGS = new Set(["--report", "--watch", "--build"]);
+
+/** @param {string | undefined} raw */
+function parseServePort(raw) {
+  const n = Number.parseInt(raw ?? "", 10);
+  if (!Number.isFinite(n) || n < 1 || n > 65_535) return null;
+  return n;
+}
+
+/**
+ * @param {string[]} argv process.argv.slice(2)
+ * @returns {{
+ *   mode: "dev" | "report" | "watch" | "build" | "scanner";
+ *   scannerArgs: string[];
+ *   scanPath: string;
+ *   outputPath: string | null;
+ *   servePort: number | null;
+ * }}
+ */
+export function parseDslinterArgs(argv) {
+  const modes = [];
+  const scannerArgs = [];
+
+  for (const arg of argv) {
+    if (MODE_FLAGS.has(arg)) modes.push(arg.slice(2));
+    else scannerArgs.push(arg);
+  }
+
+  if (modes.length > 1) {
+    throw new Error(
+      `dslinter: mode flags are mutually exclusive (got ${modes.map((m) => `--${m}`).join(", ")})`,
+    );
+  }
+
+  let servePort = null;
+  let outputPath = null;
+  let positional = null;
+
+  for (let i = 0; i < scannerArgs.length; i++) {
+    const arg = scannerArgs[i];
+    if (arg === "--serve") {
+      servePort = parseServePort(scannerArgs[i + 1]);
+    } else if (arg.startsWith("--serve=")) {
+      servePort = parseServePort(arg.slice("--serve=".length));
+    } else if (arg === "--output" || arg === "-o") {
+      outputPath = scannerArgs[i + 1] ?? null;
+    } else if (arg.startsWith("--output=")) {
+      outputPath = arg.slice("--output=".length);
+    } else if (!arg.startsWith("-") && positional === null) {
+      positional = arg;
+    }
+  }
+
+  let mode;
+  if (servePort !== null && modes.length === 0) {
+    mode = "scanner";
+  } else if (modes.length === 1) {
+    mode = modes[0];
+  } else if (modes.length === 0) {
+    const ci = process.env.CI === "true" || process.env.CI === "1";
+    mode = ci ? "report" : "dev";
+  } else {
+    mode = "dev";
+  }
+
+  const scanPath = positional ?? ".";
+
+  return {
+    mode,
+    scannerArgs,
+    scanPath,
+    outputPath,
+    servePort,
+  };
+}

package/bin/lib/parse-args.test.mjs

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { parseDslinterArgs } from "./parse-args.mjs";
+
+describe("parseDslinterArgs", () => {
+  it("defaults to dev locally", () => {
+    const prev = process.env.CI;
+    delete process.env.CI;
+    expect(parseDslinterArgs([]).mode).toBe("dev");
+    process.env.CI = prev;
+  });
+
+  it("defaults to report in CI", () => {
+    const prev = process.env.CI;
+    process.env.CI = "true";
+    expect(parseDslinterArgs([]).mode).toBe("report");
+    process.env.CI = prev;
+  });
+
+  it("rejects multiple mode flags", () => {
+    expect(() => parseDslinterArgs(["--report", "--watch"])).toThrow(/mutually exclusive/);
+  });
+
+  it("passes through scanner flags", () => {
+    const p = parseDslinterArgs(["--report", "demo", "-p", "--json"]);
+    expect(p.mode).toBe("report");
+    expect(p.scannerArgs).toEqual(["demo", "-p", "--json"]);
+    expect(p.scanPath).toBe("demo");
+  });
+
+  it("uses scanner mode for --serve only", () => {
+    expect(parseDslinterArgs([".", "--serve", "7878"]).mode).toBe("scanner");
+  });
+
+  it("extracts output and serve ports", () => {
+    const p = parseDslinterArgs(["--watch", "--output", "out.json", "--serve", "9"]);
+    expect(p.mode).toBe("watch");
+    expect(p.outputPath).toBe("out.json");
+    expect(p.servePort).toBe(9);
+  });
+
+  it("parses --serve=port", () => {
+    const p = parseDslinterArgs(["--serve=7878"]);
+    expect(p.mode).toBe("scanner");
+    expect(p.servePort).toBe(7878);
+  });
+
+  it("does not use scanner mode when --serve port is missing or invalid", () => {
+    const prev = process.env.CI;
+    delete process.env.CI;
+    for (const argv of [
+      ["--serve"],
+      ["--serve", ""],
+      ["--serve", "abc"],
+      ["--serve=not-a-port"],
+      ["--serve", "0"],
+      ["--serve=70000"],
+    ]) {
+      const p = parseDslinterArgs(argv);
+      expect(p.servePort).toBeNull();
+      expect(p.mode).toBe("dev");
+    }
+    process.env.CI = prev;
+  });
+});

package/bin/lib/project-root.mjs

@@ -0,0 +1,108 @@
+import { createRequire } from "node:module";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+const VITE_CONFIG_NAMES = ["vite.config.ts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"];
+
+/**
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+export function findViteRoot(startDir) {
+  let dir = resolve(startDir);
+  for (;;) {
+    for (const name of VITE_CONFIG_NAMES) {
+      if (existsSync(join(dir, name))) return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * @param {string} scanPath
+ * @param {string | null} outputFlag
+ * @returns {string}
+ */
+export function defaultReportPath(scanPath, outputFlag) {
+  if (outputFlag) return resolve(outputFlag);
+  return resolve(scanPath, "public", "dslint-report.json");
+}
+
+/**
+ * @returns {number}
+ */
+export function defaultServePort() {
+  const fromEnv = process.env.DSLINT_SERVE_PORT?.trim();
+  if (fromEnv) {
+    const n = Number.parseInt(fromEnv, 10);
+    if (Number.isFinite(n) && n > 0 && n <= 65535) return n;
+  }
+  return 7878;
+}
+
+/**
+ * @param {string} dir
+ * @returns {string | null} canonical absolute path when `index.html` exists
+ */
+function dashboardDirIfReady(dir) {
+  const indexHtml = join(dir, "index.html");
+  if (!existsSync(indexHtml)) return null;
+  try {
+    return realpathSync(dir);
+  } catch {
+    return resolve(dir);
+  }
+}
+
+/**
+ * Pre-built dashboard SPA for `--dashboard-static` (same port as `--serve`).
+ *
+ * Resolution order:
+ * 1. Skip when `DSLINTER_NO_BUNDLED_DASHBOARD=1`
+ * 2. `DSLINT_DASHBOARD_STATIC` — absolute or cwd-relative (temp/gitignored dirs ok)
+ * 3. `dashboard-dist/` next to the installed `dslinter` package
+ *
+ * @returns {string | null}
+ */
+export function resolveBundledDashboardDir() {
+  const optOut = process.env.DSLINTER_NO_BUNDLED_DASHBOARD?.trim();
+  if (optOut === "1" || optOut?.toLowerCase() === "true") return null;
+
+  const fromEnv = process.env.DSLINT_DASHBOARD_STATIC?.trim();
+  if (fromEnv) {
+    const dir = isAbsolute(fromEnv) ? normalize(fromEnv) : resolve(process.cwd(), fromEnv);
+    return dashboardDirIfReady(dir);
+  }
+
+  return dashboardDirIfReady(join(packageRoot, "dashboard-dist"));
+}
+
+/**
+ * Resolve vite CLI entry from a project directory (supports hoisted / workspace installs).
+ * @param {string} projectDir
+ * @returns {string | null}
+ */
+export function resolveViteBin(projectDir) {
+  let dir = resolve(projectDir);
+  for (;;) {
+    const pkgJson = join(dir, "package.json");
+    if (existsSync(pkgJson)) {
+      try {
+        const req = createRequire(pkgJson);
+        return req.resolve("vite/bin/vite.js");
+      } catch {
+        // try parent
+      }
+    }
+    const nested = join(dir, "node_modules", "vite", "bin", "vite.js");
+    if (existsSync(nested)) return nested;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}

package/bin/lib/run-scanner.mjs

@@ -0,0 +1,135 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, "../..");
+const binScript = join(__dirname, "../dslinter.mjs");
+const require = createRequire(import.meta.url);
+
+const SCANNER_VERSION_MARKER = "design system linting";
+
+function isOurScanner(binary) {
+  const help = spawnSync(binary, ["--help"], { encoding: "utf8" });
+  const out = `${help.stdout ?? ""}${help.stderr ?? ""}`;
+  return out.includes(SCANNER_VERSION_MARKER);
+}
+
+/**
+ * @returns {Promise<import("node:child_process").ChildProcess>}
+ */
+export async function spawnScanner(scannerArgs, options = {}) {
+  const fromEnv = process.env.DSLINT_BIN?.trim();
+  if (fromEnv) {
+    if (!existsSync(fromEnv)) {
+      throw new Error(`dslinter: DSLINT_BIN not found: ${fromEnv}`);
+    }
+    if (!isOurScanner(fromEnv)) {
+      throw new Error("dslinter: DSLINT_BIN does not look like the DSLint scanner");
+    }
+    return spawn(fromEnv, scannerArgs, {
+      stdio: "inherit",
+      ...options,
+    });
+  }
+
+  return spawn(process.execPath, [binScript, ...scannerArgs], {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      DSLINTER_INTERNAL: "1",
+    },
+    ...options,
+  });
+}
+
+/**
+ * Run scanner synchronously (report / build scan). Returns exit code.
+ * @param {string[]} scannerArgs
+ * @param {{ captureStdout?: boolean }} [opts]
+ * @returns {number}
+ */
+export function runScannerSync(scannerArgs, opts = {}) {
+  const fromEnv = process.env.DSLINT_BIN?.trim();
+  if (fromEnv) {
+    const child = spawnSync(fromEnv, scannerArgs, {
+      stdio: opts.captureStdout ? ["ignore", "pipe", "inherit"] : "inherit",
+      encoding: opts.captureStdout ? "utf8" : undefined,
+    });
+    if (opts.captureStdout && child.stdout) {
+      process.stdout.write(child.stdout);
+    }
+    return child.status === null ? 1 : child.status;
+  }
+
+  let runCli;
+  try {
+    ({ runCli } = require(join(packageRoot, "index.cjs")));
+  } catch (err) {
+    process.stderr.write(
+      `dslinter: failed to load native binding.\n` +
+        `  Run \`pnpm --filter dslinter run build:napi\` from the repo root, or reinstall dslinter.\n` +
+        `  ${err instanceof Error ? err.message : err}\n`,
+    );
+    return 127;
+  }
+
+  if (opts.captureStdout) {
+    const { execFileSync } = require("node:child_process");
+    try {
+      const out = execFileSync(process.execPath, [binScript, ...scannerArgs], {
+        env: { ...process.env, DSLINTER_INTERNAL: "1" },
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "inherit"],
+      });
+      process.stdout.write(out);
+      return 0;
+    } catch (e) {
+      if (e && typeof e === "object" && "status" in e && typeof e.status === "number") {
+        if (e.stdout) process.stdout.write(String(e.stdout));
+        return e.status;
+      }
+      return 1;
+    }
+  }
+
+  const argv = ["dslinter", ...scannerArgs];
+  return runCli(argv);
+}
+
+/**
+ * Internal path: run scanner only (no orchestration).
+ * @param {string[]} args
+ */
+export function runScannerInternal(args) {
+  const fromEnv = process.env.DSLINT_BIN?.trim();
+  if (fromEnv) {
+    const child = spawnSync(fromEnv, args, { stdio: "inherit" });
+    process.exit(child.status === null ? 1 : child.status);
+  }
+
+  if (process.env.DSLINT_ALLOW_PATH === "1") {
+    const onPath = spawnSync("dslinter", ["--help"], { encoding: "utf8" });
+    const out = `${onPath.stdout ?? ""}${onPath.stderr ?? ""}`;
+    if (onPath.status === 0 && out.includes(SCANNER_VERSION_MARKER)) {
+      const child = spawnSync("dslinter", args, { stdio: "inherit" });
+      process.exit(child.status === null ? 1 : child.status);
+    }
+  }
+
+  let runCli;
+  try {
+    ({ runCli } = require(join(packageRoot, "index.cjs")));
+  } catch (err) {
+    process.stderr.write(
+      `dslinter: failed to load native binding.\n` +
+        `  ${err instanceof Error ? err.message : err}\n`,
+    );
+    process.exit(127);
+  }
+
+  const code = runCli(["dslinter", ...args]);
+  process.exit(code);
+}

package/bin/lib/wait-for-port.mjs

@@ -0,0 +1,30 @@
+import net from "node:net";
+
+/**
+ * @param {number} port
+ * @param {{ host?: string; timeoutMs?: number; intervalMs?: number }} [opts]
+ */
+export function waitForPort(port, opts = {}) {
+  const host = opts.host ?? "127.0.0.1";
+  const timeoutMs = opts.timeoutMs ?? 60_000;
+  const intervalMs = opts.intervalMs ?? 100;
+  const deadline = Date.now() + timeoutMs;
+
+  return new Promise((resolve, reject) => {
+    const tryConnect = () => {
+      if (Date.now() > deadline) {
+        reject(new Error(`dslinter: timed out waiting for ${host}:${port}`));
+        return;
+      }
+      const socket = net.connect({ host, port }, () => {
+        socket.end();
+        resolve();
+      });
+      socket.on("error", () => {
+        socket.destroy();
+        setTimeout(tryConnect, intervalMs);
+      });
+    };
+    tryConnect();
+  });
+}

package/bin/modes/build.mjs

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import { defaultReportPath, findViteRoot, resolveViteBin } from "../lib/project-root.mjs";
+import { runScannerSync } from "../lib/run-scanner.mjs";
+
+/**
+ * @param {{
+ *   scanPath: string;
+ *   outputPath: string | null;
+ *   scannerArgs: string[];
+ * }}
+ */
+export function runBuildMode({ scanPath, outputPath, scannerArgs }) {
+  const reportPath = defaultReportPath(scanPath, outputPath);
+  const args = ["--report", ...scannerArgs];
+  if (!args.some((a) => a === "--output" || a.startsWith("--output="))) {
+    args.push("--output", reportPath);
+  }
+
+  const code = runScannerSync(args);
+  if (code !== 0) process.exit(code);
+
+  const viteRoot = findViteRoot(process.cwd());
+  if (!viteRoot) {
+    process.stderr.write(
+      "dslinter: --build requires a Vite project (vite.config.* not found).\n",
+    );
+    process.exit(1);
+  }
+
+  const viteBin = resolveViteBin(viteRoot);
+  if (!viteBin) {
+    process.stderr.write(`dslinter: vite not installed in ${viteRoot}. Run npm install.\n`);
+    process.exit(1);
+  }
+  const child = spawnSync(process.execPath, [viteBin, "build"], {
+    cwd: viteRoot,
+    stdio: "inherit",
+  });
+  process.exit(child.status === null ? 1 : child.status);
+}