@codebend3r/gale 0.2.1 → 0.2.3

package/bin/gale.cjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Launches the bundled Gale binary for this platform.
+ *
+ * A Node script rather than a shell script so the same launcher works on
+ * Windows, where npm wraps it in a .cmd shim. Everything is forwarded: the
+ * arguments, stdin/stdout/stderr, the exit code, and any terminating signal.
+ */
+
+const { spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const path = require("node:path");
+
+const { binaryFileName, resolveTarget, supportedPlatforms } = require("../platform.cjs");
+
+const target = resolveTarget(process.platform, process.arch);
+
+if (!target) {
+  process.stderr.write(`Unsupported platform: ${process.platform}-${process.arch}\n`);
+  process.stderr.write(`Supported: ${supportedPlatforms().join(", ")}\n`);
+  process.stderr.write("Build from source instead: cargo install gale-lint\n");
+  process.exit(1);
+}
+
+const binary = path.join(__dirname, target, binaryFileName(process.platform));
+
+if (!existsSync(binary)) {
+  process.stderr.write(`Gale binary missing for ${target} at ${binary}\n`);
+  process.stderr.write(`This package should ship prebuilt binaries for ${target}.\n`);
+  process.stderr.write("Try reinstalling the package, or build from source:\n");
+  process.stderr.write("  cargo install gale-lint\n");
+  process.exit(1);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), {
+  stdio: "inherit",
+  windowsHide: true,
+});
+
+if (result.error) {
+  process.stderr.write(`Failed to run ${binary}: ${result.error.message}\n`);
+  process.exit(1);
+}
+
+if (result.signal) {
+  // Re-raise so the parent sees the same signal the linter died from.
+  process.kill(process.pid, result.signal);
+}
+
+process.exit(result.status ?? 1);

package/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Type declarations for @codebend3r/gale.
+ *
+ * The shapes mirror Stylelint's public API so a project can swap the import
+ * without touching its call sites. Fields Gale never populates are typed as
+ * they are in Stylelint but are always empty.
+ */
+
+export type Severity = "error" | "warning";
+
+export type FormatterType = "string" | "json" | "compact" | "verbose" | "tap" | "unix";
+
+/** A single problem reported for a source. */
+export interface Warning {
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+  rule: string;
+  severity: Severity;
+  /** The message with ` (rule-name)` appended, as Stylelint prints it. */
+  text: string;
+  /** Present when the rule's `url` secondary option is set. */
+  url?: string;
+}
+
+/** The result of linting one source. */
+export interface LintResult {
+  source: string;
+  warnings: Warning[];
+  /** Always empty: Gale reports no deprecations. */
+  deprecations: unknown[];
+  /** Always empty: Gale does not validate rule options. */
+  invalidOptionWarnings: unknown[];
+  /** Always empty: parse errors surface as `parse-error` warnings. */
+  parseErrors: unknown[];
+  errored: boolean;
+  ignored: boolean;
+}
+
+export interface MaxWarningsExceeded {
+  maxWarnings: number;
+  foundWarnings: number;
+}
+
+/** What `lint()` resolves to. */
+export interface LinterResult {
+  cwd: string;
+  results: LintResult[];
+  errored: boolean;
+  /** The formatted report, in the formatter requested (JSON by default). */
+  report: string;
+  /** The fixed source when `fix` and `code` were both given. */
+  code?: string;
+  maxWarningsExceeded?: MaxWarningsExceeded;
+  /** Always empty: Gale exposes no per-rule metadata. */
+  ruleMetadata: Record<string, never>;
+}
+
+export type FormatterFunction = (
+  results: LintResult[],
+  returnValue: { cwd: string; results: LintResult[]; errored: boolean },
+) => string;
+
+/** Rule settings in any of Stylelint's accepted shapes. */
+export type RuleSetting = boolean | null | string | number | unknown[];
+
+export interface Config {
+  extends?: string | string[];
+  plugins?: string[];
+  rules?: Record<string, RuleSetting>;
+  overrides?: unknown[];
+  ignoreFiles?: string | string[];
+  ignorePatterns?: string | string[];
+  customSyntax?: string;
+  defaultSeverity?: Severity;
+  ignoreDisables?: boolean;
+  reportNeedlessDisables?: boolean;
+  reportInvalidScopeDisables?: boolean;
+  reportDescriptionlessDisables?: boolean;
+  reportUnscopedDisables?: boolean;
+  allowEmptyInput?: boolean;
+  quiet?: boolean;
+  fix?: boolean | "strict" | "lax";
+  cache?: boolean;
+  cacheLocation?: string;
+  [key: string]: unknown;
+}
+
+export interface LinterOptions {
+  /** Glob pattern(s) for files to lint. */
+  files?: string | string[];
+  /** CSS source to lint instead of files. */
+  code?: string;
+  /** Virtual filename for `code`, used for syntax detection. */
+  codeFilename?: string;
+  /** Inline config object. */
+  config?: Config;
+  /** Path to a config file. */
+  configFile?: string;
+  fix?: boolean | "strict" | "lax";
+  formatter?: FormatterType | FormatterFunction;
+  quiet?: boolean;
+  cache?: boolean;
+  cacheLocation?: string;
+  maxWarnings?: number;
+  allowEmptyInput?: boolean;
+  ignorePath?: string;
+  ignoreDisables?: boolean;
+  reportNeedlessDisables?: boolean;
+  reportInvalidScopeDisables?: boolean;
+  reportDescriptionlessDisables?: boolean;
+  /** Working directory; defaults to `process.cwd()`. */
+  cwd?: string;
+}
+
+/** Lint files or a code string and resolve with a Stylelint-shaped result. */
+export function lint(options?: LinterOptions): Promise<LinterResult>;
+
+/** Resolve the effective config for a file, or `undefined` when none applies. */
+export function resolveConfig(
+  filePath: string,
+  options?: { configFile?: string; cwd?: string },
+): Promise<Config | undefined>;
+
+/** Promise-based formatter functions keyed by name, like `stylelint.formatters`. */
+export const formatters: {
+  readonly json: Promise<FormatterFunction>;
+  readonly string: Promise<FormatterFunction>;
+  readonly compact: Promise<FormatterFunction>;
+  readonly verbose: Promise<FormatterFunction>;
+  readonly tap: Promise<FormatterFunction>;
+  readonly unix: Promise<FormatterFunction>;
+};
+
+/**
+ * Compatibility stub. Gale runs built-in Rust rules and cannot execute a
+ * JavaScript rule; calling this warns and returns an inert plugin object.
+ */
+export function createPlugin(
+  ruleName: string,
+  ruleFunction: (...args: unknown[]) => unknown,
+): { ruleName: string; rule: (...args: unknown[]) => unknown };
+
+declare const _default: {
+  lint: typeof lint;
+  formatters: typeof formatters;
+  resolveConfig: typeof resolveConfig;
+  createPlugin: typeof createPlugin;
+};
+
+export default _default;

package/index.mjs

@@ -12,6 +12,8 @@ import { tmpdir } from "node:os";
 import { randomBytes } from "node:crypto";
 import { fileURLToPath } from "node:url";
 
+import { binaryFileName, resolveTarget } from "./platform.cjs";
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
@@ -27,10 +29,13 @@ function findBinary() {
     return override;
   }
 
-  // 1. Check the bin/ directory within the npm package
-  const localBin = join(__dirname, "bin", "gale");
-  if (existsSync(localBin)) {
-    return localBin;
+  // 1. The binary bundled for this platform inside the npm package
+  const target = resolveTarget(process.platform, process.arch);
+  if (target) {
+    const bundled = join(__dirname, "bin", target, binaryFileName(process.platform));
+    if (existsSync(bundled)) {
+      return bundled;
+    }
   }
 
   // 2. Fall back to gale on PATH
@@ -129,9 +134,14 @@ function parseJsonOutput(jsonString) {
     warnings: (entry.warnings || []).map((w) => ({
       line: w.line,
       column: w.column,
+      endLine: w.endLine,
+      endColumn: w.endColumn,
       rule: w.rule,
       severity: w.severity || "warning",
       text: w.text,
+      // Only present when the rule's `url` secondary option is set, as in
+      // Stylelint, where an undefined url is dropped by JSON.stringify.
+      ...(w.url !== undefined ? { url: w.url } : {}),
     })),
     deprecations: [],
     invalidOptionWarnings: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codebend3r/gale",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "An extremely fast CSS linter, written in Rust. Drop-in replacement for Stylelint.",
   "license": "MIT",
   "repository": {
@@ -22,19 +22,23 @@
   ],
   "type": "module",
   "main": "index.mjs",
+  "types": "index.d.ts",
   "exports": {
     ".": {
+      "types": "./index.d.ts",
       "import": "./index.mjs",
       "require": "./index.cjs"
     }
   },
   "bin": {
-    "gale": "bin/gale"
+    "gale": "bin/gale.cjs"
   },
   "files": [
     "bin/",
     "index.cjs",
+    "index.d.ts",
     "index.mjs",
+    "platform.cjs",
     "test.mjs",
     "README.md"
   ],

package/platform.cjs

@@ -0,0 +1,49 @@
+"use strict";
+
+/**
+ * Maps a Node.js platform and architecture to the Rust target whose binary
+ * ships inside this package, and names the binary for that platform.
+ *
+ * Shared by the `gale` launcher and the programmatic API. CommonJS so the
+ * launcher can require it synchronously on every supported Node version.
+ */
+
+const TARGETS = {
+  "darwin-arm64": "aarch64-apple-darwin",
+  "darwin-x64": "x86_64-apple-darwin",
+  "linux-arm64": "aarch64-unknown-linux-gnu",
+  "linux-x64": "x86_64-unknown-linux-gnu",
+  "win32-arm64": "aarch64-pc-windows-msvc",
+  "win32-x64": "x86_64-pc-windows-msvc",
+};
+
+/**
+ * The Rust target triple for a platform/arch pair, or `null` when Gale does
+ * not ship a binary for it.
+ *
+ * @param {string} platform - `process.platform`
+ * @param {string} arch - `process.arch`
+ * @returns {string | null}
+ */
+function resolveTarget(platform, arch) {
+  return TARGETS[`${platform}-${arch}`] ?? null;
+}
+
+/**
+ * The file name of the Gale binary on a platform.
+ *
+ * @param {string} platform - `process.platform`
+ * @returns {string}
+ */
+function binaryFileName(platform) {
+  return platform === "win32" ? "gale.exe" : "gale";
+}
+
+/** Every `platform-arch` pair a binary ships for, for error messages. */
+function supportedPlatforms() {
+  return Object.keys(TARGETS);
+}
+
+exports.resolveTarget = resolveTarget;
+exports.binaryFileName = binaryFileName;
+exports.supportedPlatforms = supportedPlatforms;

package/bin/gale

@@ -1,54 +0,0 @@
-#!/bin/sh
-
-set -eu
-
-platform="$(uname -s)-$(uname -m)"
-
-case "$platform" in
-  Darwin-arm64)
-    target="aarch64-apple-darwin"
-    ;;
-  Darwin-x86_64)
-    target="x86_64-apple-darwin"
-    ;;
-  Linux-aarch64|Linux-arm64)
-    target="aarch64-unknown-linux-gnu"
-    ;;
-  Linux-x86_64)
-    target="x86_64-unknown-linux-gnu"
-    ;;
-  *)
-    echo "Unsupported platform: $platform" >&2
-    echo "Supported: Darwin-arm64, Darwin-x86_64, Linux-aarch64, Linux-x86_64" >&2
-    exit 1
-    ;;
-esac
-
-script="$0"
-
-while [ -L "$script" ]; do
-  script_dir="$(CDPATH= cd "$(dirname "$script")" && pwd)"
-  link="$(readlink "$script")"
-
-  case "$link" in
-    /*)
-      script="$link"
-      ;;
-    *)
-      script="$script_dir/$link"
-      ;;
-  esac
-done
-
-bin_dir="$(CDPATH= cd "$(dirname "$script")" && pwd)"
-binary="$bin_dir/$target/gale"
-
-if [ ! -x "$binary" ]; then
-  echo "Gale binary missing for $target at $binary" >&2
-  echo "This package should ship prebuilt binaries for $target." >&2
-  echo "Try reinstalling the package, or build from source:" >&2
-  echo "  cargo install gale-lint" >&2
-  exit 1
-fi
-
-exec "$binary" "$@"