dslinter 0.0.12 → 0.0.16

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.0.16
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.15...v0.0.16)
+
+## v0.0.15
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.12...v0.0.15)
+
+### 🚀 Enhancements
+
+- Update release workflow and versioning ([5e28f64](https://github.com/jrmybtlr/DSLinter/commit/5e28f64))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
 ## v0.0.12
 
 [compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.11...v0.0.12)

package/README.md

@@ -35,7 +35,7 @@ Environment variables:
 | `DSLINT_RELEASE_TAG` | Override release tag (default `v` + `dslinter` version from `package.json`). |
 | `DSLINT_GITHUB_REPO` | Override `owner/repo` for downloads (default from `package.json` → `jrmybtlr/DSLinter`). |
 | `DSLINT_VERBOSE=1` | Log which GitHub releases/assets were tried when downloading. |
-| `GITHUB_TOKEN` / `GH_TOKEN` | Optional token for private repos or higher API rate limits. |
+| `GITHUB_TOKEN` / `GH_TOKEN` | **Required for private repos** (`jrmybtlr/DSLinter`). Token needs read access to releases. |
 
 ### How this differs from `oxlint`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dslinter",
-  "version": "0.0.12",
+  "version": "0.0.16",
   "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,6 +1,5 @@
 /**
  * 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";
@@ -8,7 +7,9 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   fetchReleasesForVersion,
+  githubAuthToken,
   pickReleaseAsset,
+  tryDirectAssetDownload,
 } from "./github-release.mjs";
 import {
   githubRepoFromPackage,
@@ -41,15 +42,31 @@ function releaseRepo(packageRoot) {
   return githubRepoFromPackage(packageRoot);
 }
 
+/**
+ * @param {string} dest
+ * @param {{ buf: Buffer }} payload
+ */
+async function writeVendorBinary(dest, { buf }) {
+  const tmp = `${dest}.part`;
+  writeFileSync(tmp, buf);
+  try {
+    if (await pathExists(dest)) unlinkSync(dest);
+  } catch {
+    /* ignore */
+  }
+  renameSync(tmp, dest);
+  if (process.platform !== "win32") {
+    await chmod(dest, 0o755);
+  }
+}
+
 /**
  * @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);
-  const verbose = process.env.DSLINT_VERBOSE === "1";
 
   if (process.env.DSLINT_SKIP_DOWNLOAD === "1") {
     return pathExists(vendorBinaryPath(packageRoot));
@@ -68,89 +85,94 @@ export async function ensureDslintBinary(packageRoot = defaultPackageRoot, opts
 
   const version = readPackageVersion(packageRoot);
   const repo = releaseRepo(packageRoot);
-  const vendorDir = join(packageRoot, "vendor");
-  await mkdir(vendorDir, { recursive: true });
-  const tmp = `${dest}.part`;
+  await mkdir(join(packageRoot, "vendor"), { recursive: true });
 
-  let releases;
-  try {
-    releases = await fetchReleasesForVersion(repo, version);
-  } catch (err) {
-    log(
-      `[dslinter] Could not query GitHub releases for ${repo}: ${err instanceof Error ? err.message : err}`,
-    );
-    if (process.env.GITHUB_TOKEN || process.env.GH_TOKEN) {
-      log("  (token was set but request still failed — check repo access)");
-    } else {
+  const direct = await tryDirectAssetDownload(repo, version, candidates, log);
+  if (direct) {
+    await writeVendorBinary(dest, direct);
+    if (direct.tag !== `v${version}` && !quiet) {
       log(
-        "  For private repos, set GITHUB_TOKEN or GH_TOKEN with read access to releases.",
+        `[dslinter] Installed ${direct.name} from release ${direct.tag} (npm v${version}).`,
       );
     }
-    return false;
-  }
-
-  if (releases.length === 0) {
-    log(
-      `[dslinter] No GitHub release found on ${repo} for v${version}.\n` +
-        `  Publish tag v${version} with workflow release-dslint-binaries.yml (assets: ${candidates.join(" or ")}).`,
-    );
-    return false;
+    return true;
   }
 
-  for (const release of releases) {
-    const asset = pickReleaseAsset(release, candidates);
-    if (!asset) {
-      if (verbose) {
-        log(
-          `[dslinter] Release ${release.tag_name} has no asset in ${candidates.join(", ")} (has: ${release.assets.map((a) => a.name).join(", ") || "none"})`,
-        );
-      }
-      continue;
+  let apiDenied = false;
+  let tagExistsWithoutBinaries = null;
+  try {
+    const {
+      releases,
+      apiDenied: denied,
+      apiError,
+      tagExistsWithoutBinaries: emptyTag,
+    } = await fetchReleasesForVersion(repo, version);
+    apiDenied = denied;
+    tagExistsWithoutBinaries = emptyTag ?? null;
+
+    if (apiError) {
+      log(
+        `[dslinter] GitHub API error: ${apiError.message}`,
+      );
     }
 
-    if (verbose) {
-      log(`[dslinter] Downloading ${asset.name} from ${release.tag_name}…`);
-    }
+    for (const release of releases) {
+      const asset = pickReleaseAsset(release, candidates);
+      if (!asset) continue;
 
-    try {
-      const res = await fetch(asset.browser_download_url, { redirect: "follow" });
-      if (!res.ok) {
-        log(`[dslinter] Download failed (${res.status}): ${asset.browser_download_url}`);
-        continue;
-      }
+      const headers = {};
+      const token = githubAuthToken();
+      if (token) headers.Authorization = `Bearer ${token}`;
+
+      const res = await fetch(asset.browser_download_url, {
+        headers,
+        redirect: "follow",
+      });
+      if (!res.ok) continue;
 
       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);
-      }
+      await writeVendorBinary(dest, { buf });
       if (release.tag_name !== `v${version}` && !quiet) {
         log(
-          `[dslinter] Installed scanner from release ${release.tag_name} (npm v${version}).`,
+          `[dslinter] Installed ${asset.name} from release ${release.tag_name} (npm v${version}).`,
         );
       }
       return true;
-    } catch (err) {
-      log(
-        `[dslinter] Could not download ${asset.name}: ${err instanceof Error ? err.message : err}`,
-      );
-      try {
-        unlinkSync(tmp);
-      } catch {
-        /* ignore */
-      }
     }
+  } catch (err) {
+    log(
+      `[dslinter] GitHub API: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+
+  const tag = `v${version}`;
+  const releasePage = `https://github.com/${repo}/releases/tag/${tag}`;
+
+  if (tagExistsWithoutBinaries) {
+    log(
+      `[dslinter] GitHub release ${tagExistsWithoutBinaries} exists but has no scanner binaries attached.\n` +
+        `  Run the "Release dslinter binaries" workflow on ${repo} (Actions → workflow_dispatch, tag ${tagExistsWithoutBinaries}),\n` +
+        `  or push a new tag so CI uploads assets like ${candidates[0]}.\n` +
+        `  ${releasePage}`,
+    );
+    return false;
+  }
+
+  if (apiDenied || !githubAuthToken()) {
+    log(
+      `[dslinter] Cannot reach ${repo} releases without authentication (GitHub returned 404).\n` +
+        `  If you can open ${releasePage} in a browser, the repo is likely private.\n` +
+        `  Create a fine-grained or classic token with repo read access, then:\n` +
+        `    export GITHUB_TOKEN=ghp_...\n` +
+        `    npx dslinter\n` +
+        `  Or install from source: cargo install --git https://github.com/${repo} dslinter --locked`,
+    );
+    return false;
   }
 
   log(
-    `[dslinter] Found releases on ${repo} but none include ${candidates.join(" or ")} for this platform.\n` +
-      `  Upload platform binaries via .github/workflows/release-dslint-binaries.yml, or set DSLINT_BIN.`,
+    `[dslinter] No release with asset ${candidates.join(" or ")} on ${repo} for ${tag}.\n` +
+      `  Create ${releasePage} and run release-dslint-binaries.yml, or set DSLINT_BIN.`,
   );
   return false;
 }

package/scripts/github-release.mjs

@@ -1,79 +1,150 @@
 /**
- * Resolve GitHub release assets via the REST API (works with exact names + legacy names).
+ * Resolve and download GitHub release assets (API + direct URLs; supports private repos with a token).
  */
 
 const API = "https://api.github.com";
 
+export function githubAuthToken() {
+  return (
+    process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim() || null
+  );
+}
+
+export function downloadAuthHeaders() {
+  const token = githubAuthToken();
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
 function apiHeaders() {
-  const headers = {
+  return {
     Accept: "application/vnd.github+json",
     "User-Agent": "dslinter-npm",
     "X-GitHub-Api-Version": "2022-11-28",
+    ...downloadAuthHeaders(),
   };
-  const token =
-    process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim();
-  if (token) headers.Authorization = `Bearer ${token}`;
-  return headers;
 }
 
 /**
  * @param {string} repo `owner/name`
+ * @param {string} tag `v0.0.12` or `latest`
+ * @param {string} assetName
+ */
+export function directAssetUrl(repo, tag, assetName) {
+  const file = encodeURIComponent(assetName);
+  if (tag === "latest") {
+    return `https://github.com/${repo}/releases/latest/download/${file}`;
+  }
+  return `https://github.com/${repo}/releases/download/${encodeURIComponent(tag)}/${file}`;
+}
+
+/**
+ * @param {string} npmVersion
+ */
+export function releaseTagsToTry(npmVersion) {
+  const override = process.env.DSLINT_RELEASE_TAG?.trim();
+  if (override) {
+    return [override.startsWith("v") ? override : `v${override}`];
+  }
+  return [`v${npmVersion}`, npmVersion, "latest"];
+}
+
+/**
+ * @param {string} repo
  * @param {string} path
+ * @returns {Promise<{ data: unknown } | { notFound: true } | { error: Error }>}
  */
 async function githubGet(repo, path) {
   const res = await fetch(`${API}/repos/${repo}${path}`, {
     headers: apiHeaders(),
     redirect: "follow",
   });
-  if (res.status === 404) return null;
+  if (res.status === 404) return { notFound: true };
   if (!res.ok) {
     const body = await res.text().catch(() => "");
-    throw new Error(`GitHub API ${res.status} for ${path}: ${body.slice(0, 200)}`);
+    return {
+      error: new Error(`GitHub API ${res.status} for ${path}: ${body.slice(0, 200)}`),
+    };
   }
-  return res.json();
+  return { data: await res.json() };
 }
 
 /**
  * @param {string} repo
- * @param {string} tag e.g. `v0.0.11` or `latest`
+ * @param {string} tag e.g. `v0.0.12` or `latest`
  */
 export async function fetchRelease(repo, tag) {
-  if (tag === "latest") {
-    return githubGet(repo, "/releases/latest");
-  }
-  const byTag = await githubGet(repo, `/releases/tags/${encodeURIComponent(tag)}`);
-  if (byTag) return byTag;
-  // Some releases use tag without `v` prefix.
-  if (tag.startsWith("v")) {
-    return githubGet(repo, `/releases/tags/${encodeURIComponent(tag.slice(1))}`);
+  const path =
+    tag === "latest" ? "/releases/latest" : `/releases/tags/${encodeURIComponent(tag)}`;
+  let result = await githubGet(repo, path);
+  if (result.notFound && tag.startsWith("v")) {
+    result = await githubGet(
+      repo,
+      `/releases/tags/${encodeURIComponent(tag.slice(1))}`,
+    );
   }
+  if ("data" in result) return result.data;
   return null;
 }
 
 /**
  * @param {string} repo
- * @param {string} npmVersion e.g. `0.0.11`
+ * @param {string} npmVersion
  */
+/** @param {unknown} release */
+function hasScannerAssets(release) {
+  const names = release?.assets?.map((a) => a.name) ?? [];
+  return names.some((n) => n.startsWith("dslinter-") || n.startsWith("dslint-"));
+}
+
 export async function fetchReleasesForVersion(repo, npmVersion) {
   const out = [];
   const seen = new Set();
+  /** @type {string | null} */
+  let tagExistsWithoutBinaries = null;
+
+  const consider = (release) => {
+    if (!release?.tag_name) return;
+    const tag = String(release.tag_name);
+    const matches =
+      tag === `v${npmVersion}` || tag === npmVersion;
+    if (matches && !hasScannerAssets(release)) {
+      tagExistsWithoutBinaries = tag;
+    }
+  };
 
   const push = (release) => {
-    if (!release?.assets?.length) return;
+    if (!hasScannerAssets(release)) return;
     const key = release.id ?? release.tag_name;
     if (seen.has(key)) return;
     seen.add(key);
     out.push(release);
   };
 
-  push(await fetchRelease(repo, `v${npmVersion}`));
-  push(await fetchRelease(repo, npmVersion));
-  push(await fetchRelease(repo, "latest"));
+  const vRelease = await fetchRelease(repo, `v${npmVersion}`);
+  consider(vRelease);
+  push(vRelease);
+
+  const bareRelease = await fetchRelease(repo, npmVersion);
+  consider(bareRelease);
+  push(bareRelease);
+
+  const latestRelease = await fetchRelease(repo, "latest");
+  push(latestRelease);
 
-  if (out.length > 0) return out;
+  if (out.length > 0) {
+    return { releases: out, apiDenied: false, tagExistsWithoutBinaries };
+  }
 
-  const list = await githubGet(repo, "/releases?per_page=30");
-  if (!Array.isArray(list)) return out;
+  const listResult = await githubGet(repo, "/releases?per_page=30");
+  if ("error" in listResult) {
+    return { releases: out, apiDenied: false, apiError: listResult.error };
+  }
+  if (listResult.notFound) {
+    return { releases: out, apiDenied: !githubAuthToken() };
+  }
+
+  const list = listResult.data;
+  if (!Array.isArray(list)) return { releases: out, apiDenied: false };
 
   for (const release of list) {
     const tag = String(release.tag_name ?? "");
@@ -81,9 +152,10 @@ export async function fetchReleasesForVersion(repo, npmVersion) {
       push(release);
     }
   }
-  if (out.length > 0) return out;
+  if (out.length > 0) {
+    return { releases: out, apiDenied: false, tagExistsWithoutBinaries };
+  }
 
-  // Newest release that has any scanner-looking asset.
   for (const release of list) {
     const names = release.assets?.map((a) => a.name) ?? [];
     if (names.some((n) => n.startsWith("dslinter-") || n.startsWith("dslint-"))) {
@@ -92,13 +164,12 @@ export async function fetchReleasesForVersion(repo, npmVersion) {
     }
   }
 
-  return out;
+  return { releases: out, apiDenied: false, tagExistsWithoutBinaries };
 }
 
 /**
  * @param {string[]} candidateNames
  * @param {{ assets: { name: string; browser_download_url: string }[] }} release
- * @returns {{ name: string; browser_download_url: string } | null}
  */
 export function pickReleaseAsset(release, candidateNames) {
   for (const name of candidateNames) {
@@ -107,3 +178,42 @@ export function pickReleaseAsset(release, candidateNames) {
   }
   return null;
 }
+
+/**
+ * Download via public/private release URLs (no API metadata required).
+ * @param {(msg: string) => void} log
+ */
+export async function tryDirectAssetDownload(repo, npmVersion, candidateNames, log) {
+  const verbose = process.env.DSLINT_VERBOSE === "1";
+  const headers = downloadAuthHeaders();
+  const tags = releaseTagsToTry(npmVersion);
+
+  for (const tag of tags) {
+    for (const name of candidateNames) {
+      const url = directAssetUrl(repo, tag, name);
+      if (verbose) log(`[dslinter] GET ${url}`);
+      try {
+        const res = await fetch(url, { headers, redirect: "follow" });
+        if (res.status === 404) continue;
+        if (!res.ok) {
+          if (verbose) log(`[dslinter] ${res.status} ${url}`);
+          continue;
+        }
+        const contentType = res.headers.get("content-type") ?? "";
+        if (contentType.includes("text/html")) continue;
+
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length < 512) continue;
+
+        return { buf, tag, name, url };
+      } catch (err) {
+        if (verbose) {
+          log(
+            `[dslinter] ${url}: ${err instanceof Error ? err.message : err}`,
+          );
+        }
+      }
+    }
+  }
+  return null;
+}

package/scripts/print-missing-scanner.mjs

@@ -1,27 +1,32 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { githubRepoFromPackage } from "./resolve-dslint-binary.mjs";
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
 const version = JSON.parse(
   readFileSync(join(packageRoot, "package.json"), "utf8"),
 ).version;
+const repo = githubRepoFromPackage(packageRoot);
 
 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).
+Do NOT run:  cargo install dslint
+  That installs a different package on crates.io (design-file linter).
 
-To run the design-system scanner:
+Install the design-system scanner from this repo instead:
 
-  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/DSLinter dslinter --locked
-       export DSLINT_BIN="$(command -v dslinter)"
-       npx dslinter ...
-  3. Or set DSLINT_BIN to your local target/release/dslinter
+  cargo install --git https://github.com/${repo} dslinter --locked
+  export DSLINT_BIN="$(command -v dslinter)"
+  npx dslinter ...
 
-Releases: https://github.com/jrmybtlr/DSLinter/releases
+If releases exist at https://github.com/${repo}/releases/tag/v${version} but
+download failed, the repo may be private — set a GitHub token then retry:
 
-Tip: re-run with DSLINT_VERBOSE=1 to see which GitHub releases/assets were tried.
+  export GITHUB_TOKEN=ghp_...   # needs read access to ${repo}
+  npx dslinter
+
+Or point at a local build:  DSLINT_BIN=/path/to/dslinter
+
+Tip: DSLINT_VERBOSE=1 shows each download URL tried.
 `);

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

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
+  directAssetUrl,
   pickReleaseAsset,
+  releaseTagsToTry,
 } from "../scripts/github-release.mjs";
 import {
   CLI_BINARY_NAME,
@@ -37,6 +39,30 @@ describe("parseGitHubRepo", () => {
   });
 });
 
+describe("directAssetUrl", () => {
+  it("uses releases/latest/download for latest tag", () => {
+    expect(
+      directAssetUrl("jrmybtlr/DSLinter", "latest", "dslinter-aarch64-apple-darwin"),
+    ).toBe(
+      "https://github.com/jrmybtlr/DSLinter/releases/latest/download/dslinter-aarch64-apple-darwin",
+    );
+  });
+
+  it("uses releases/download for version tags", () => {
+    expect(
+      directAssetUrl("jrmybtlr/DSLinter", "v0.0.12", "dslinter-aarch64-apple-darwin"),
+    ).toBe(
+      "https://github.com/jrmybtlr/DSLinter/releases/download/v0.0.12/dslinter-aarch64-apple-darwin",
+    );
+  });
+});
+
+describe("releaseTagsToTry", () => {
+  it("tries v-prefixed tag first", () => {
+    expect(releaseTagsToTry("0.0.12")).toEqual(["v0.0.12", "0.0.12", "latest"]);
+  });
+});
+
 describe("releaseAssetCandidateNames", () => {
   it("includes legacy dslint asset name", () => {
     expect(releaseAssetCandidateNames(proc("darwin", "arm64"))).toEqual([