dslinter 0.0.11 → 0.0.16

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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)
+
+### 🚀 Enhancements
+
+- Enhance GitHub release asset handling and logging ([4a62b9f](https://github.com/jrmybtlr/DSLinter/commit/4a62b9f))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
 ## v0.0.11
 
 [compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.10...v0.0.11)

package/README.md

@@ -33,7 +33,9 @@ Environment variables:
 |----------|---------|
 | `DSLINT_SKIP_DOWNLOAD=1` | Skip postinstall download (air-gapped / you only use `PATH`). |
 | `DSLINT_RELEASE_TAG` | Override release tag (default `v` + `dslinter` version from `package.json`). |
-| `DSLINT_GITHUB_REPO` | Override `owner/repo` for downloads (default `jrmybtlr/DSLinter`). |
+| `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` | **Required for private repos** (`jrmybtlr/DSLinter`). Token needs read access to releases. |
 
 ### How this differs from `oxlint`
 

package/bin/dslinter.mjs

@@ -43,7 +43,7 @@ async function resolveCommand() {
 
   const vendored = vendorBinaryPath(packageRoot);
   if (!existsSync(vendored)) {
-    await ensureDslintBinary(packageRoot, { quiet: true });
+    await ensureDslintBinary(packageRoot, { quiet: false });
   }
   if (existsSync(vendored)) {
     return vendored;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dslinter",
-  "version": "0.0.11",
+  "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,14 +1,19 @@
 /**
  * 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 {
+  fetchReleasesForVersion,
+  githubAuthToken,
+  pickReleaseAsset,
+  tryDirectAssetDownload,
+} from "./github-release.mjs";
 import {
   githubRepoFromPackage,
-  releaseAssetBaseName,
+  releaseAssetCandidateNames,
   vendorBinaryPath,
 } from "./resolve-dslint-binary.mjs";
 
@@ -31,26 +36,33 @@ function readPackageVersion(packageRoot) {
   return pkg.version;
 }
 
-function releaseTag(version) {
-  const o = process.env.DSLINT_RELEASE_TAG?.trim();
-  if (o) return o.startsWith("v") ? o : `v${o}`;
-  return `v${version}`;
-}
-
 function releaseRepo(packageRoot) {
   const override = process.env.DSLINT_GITHUB_REPO?.trim();
   if (override) return override;
   return githubRepoFromPackage(packageRoot);
 }
 
-function assetUrl(packageRoot, tag, asset) {
-  return `https://github.com/${releaseRepo(packageRoot)}/releases/download/${tag}/${asset}`;
+/**
+ * @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;
@@ -63,8 +75,8 @@ export async function ensureDslintBinary(packageRoot = defaultPackageRoot, opts
   const dest = vendorBinaryPath(packageRoot);
   if (await pathExists(dest)) return true;
 
-  const asset = releaseAssetBaseName();
-  if (!asset) {
+  const candidates = releaseAssetCandidateNames();
+  if (candidates.length === 0) {
     log(
       `[dslinter] No prebuilt scanner for ${process.platform}-${process.arch}.`,
     );
@@ -72,57 +84,95 @@ export async function ensureDslintBinary(packageRoot = defaultPackageRoot, opts
   }
 
   const version = readPackageVersion(packageRoot);
-  const tagsToTry = [releaseTag(version)];
-  if (process.env.DSLINT_USE_LATEST_RELEASE !== "0") {
-    tagsToTry.push("latest");
+  const repo = releaseRepo(packageRoot);
+  await mkdir(join(packageRoot, "vendor"), { recursive: true });
+
+  const direct = await tryDirectAssetDownload(repo, version, candidates, log);
+  if (direct) {
+    await writeVendorBinary(dest, direct);
+    if (direct.tag !== `v${version}` && !quiet) {
+      log(
+        `[dslinter] Installed ${direct.name} from release ${direct.tag} (npm v${version}).`,
+      );
+    }
+    return true;
   }
 
-  const vendorDir = join(packageRoot, "vendor");
-  await mkdir(vendorDir, { recursive: true });
-  const tmp = `${dest}.part`;
+  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}`,
+      );
+    }
 
-  for (const tag of tagsToTry) {
-    const url = assetUrl(packageRoot, tag, asset);
-    try {
-      const res = await fetch(url, { redirect: "follow" });
-      if (res.status === 404) continue;
-      if (!res.ok) {
-        log(`[dslinter] Download failed (${res.status}): ${url}`);
-        continue;
-      }
+    for (const release of releases) {
+      const asset = pickReleaseAsset(release, candidates);
+      if (!asset) 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);
-      }
-      if (tag === "latest" && !quiet) {
+      await writeVendorBinary(dest, { buf });
+      if (release.tag_name !== `v${version}` && !quiet) {
         log(
-          `[dslinter] Installed scanner from latest GitHub release (no asset for npm v${version}).`,
+          `[dslinter] Installed ${asset.name} from release ${release.tag_name} (npm v${version}).`,
         );
       }
       return true;
-    } catch (err) {
-      log(
-        `[dslinter] Could not download: ${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] 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.`,
+    `[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;
 }
@@ -132,6 +182,6 @@ const isMain =
   fileURLToPath(import.meta.url) === process.argv[1];
 
 if (isMain) {
-  const ok = await ensureDslintBinary();
-  process.exit(ok ? 0 : 0);
+  await ensureDslintBinary();
+  process.exit(0);
 }

package/scripts/github-release.mjs

@@ -0,0 +1,219 @@
+/**
+ * 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() {
+  return {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "dslinter-npm",
+    "X-GitHub-Api-Version": "2022-11-28",
+    ...downloadAuthHeaders(),
+  };
+}
+
+/**
+ * @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 { notFound: true };
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    return {
+      error: new Error(`GitHub API ${res.status} for ${path}: ${body.slice(0, 200)}`),
+    };
+  }
+  return { data: await res.json() };
+}
+
+/**
+ * @param {string} repo
+ * @param {string} tag e.g. `v0.0.12` or `latest`
+ */
+export async function fetchRelease(repo, tag) {
+  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
+ */
+/** @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 (!hasScannerAssets(release)) return;
+    const key = release.id ?? release.tag_name;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(release);
+  };
+
+  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 { releases: out, apiDenied: false, tagExistsWithoutBinaries };
+  }
+
+  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 ?? "");
+    if (tag === `v${npmVersion}` || tag === npmVersion) {
+      push(release);
+    }
+  }
+  if (out.length > 0) {
+    return { releases: out, apiDenied: false, tagExistsWithoutBinaries };
+  }
+
+  for (const release of list) {
+    const names = release.assets?.map((a) => a.name) ?? [];
+    if (names.some((n) => n.startsWith("dslinter-") || n.startsWith("dslint-"))) {
+      push(release);
+      break;
+    }
+  }
+
+  return { releases: out, apiDenied: false, tagExistsWithoutBinaries };
+}
+
+/**
+ * @param {string[]} candidateNames
+ * @param {{ assets: { name: string; browser_download_url: string }[] }} release
+ */
+export function pickReleaseAsset(release, candidateNames) {
+  for (const name of candidateNames) {
+    const asset = release.assets.find((a) => a.name === name);
+    if (asset?.browser_download_url) return asset;
+  }
+  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,25 +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:
+
+  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/scripts/resolve-dslint-binary.mjs

@@ -58,6 +58,14 @@ export function releaseAssetBaseName(proc = process) {
   return null;
 }
 
+/** Primary GitHub asset name plus legacy `dslint-*` names from older releases. */
+export function releaseAssetCandidateNames(proc = process) {
+  const primary = releaseAssetBaseName(proc);
+  if (!primary) return [];
+  const legacy = primary.replace(/^dslinter/, "dslint");
+  return legacy === primary ? [primary] : [primary, legacy];
+}
+
 /**
  * @param {string} packageRoot — directory containing package.json
  * @param {NodeJS.Process} [proc]

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

@@ -1,10 +1,16 @@
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
+import {
+  directAssetUrl,
+  pickReleaseAsset,
+  releaseTagsToTry,
+} from "../scripts/github-release.mjs";
 import {
   CLI_BINARY_NAME,
   DEFAULT_GITHUB_REPO,
   parseGitHubRepo,
   releaseAssetBaseName,
+  releaseAssetCandidateNames,
   vendorBinaryPath,
 } from "../scripts/resolve-dslint-binary.mjs";
 
@@ -33,6 +39,55 @@ 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([
+      "dslinter-aarch64-apple-darwin",
+      "dslint-aarch64-apple-darwin",
+    ]);
+  });
+});
+
+describe("pickReleaseAsset", () => {
+  it("prefers primary name then legacy", () => {
+    const release = {
+      assets: [
+        {
+          name: "dslint-aarch64-apple-darwin",
+          browser_download_url: "https://example.com/legacy",
+        },
+      ],
+    };
+    expect(
+      pickReleaseAsset(release, releaseAssetCandidateNames(proc("darwin", "arm64"))),
+    ).toMatchObject({ name: "dslint-aarch64-apple-darwin" });
+  });
+});
+
 describe("releaseAssetBaseName", () => {
   it("maps darwin arm64", () => {
     expect(releaseAssetBaseName(proc("darwin", "arm64"))).toBe(