@codebend3r/gale 0.2.0 → 0.2.2

package/README.md

@@ -27,4 +27,4 @@ console.log(result.errored);
 console.log(result.results);
 ```
 
-See the full documentation at [github.com/LyricalString/gale](https://github.com/LyricalString/gale).
+See the full documentation at [github.com/codebend3r/gale](https://github.com/codebend3r/gale).

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);
 
@@ -20,10 +22,20 @@ const __dirname = dirname(__filename);
 // ---------------------------------------------------------------------------
 
 function findBinary() {
-  // 1. Check the bin/ directory within the npm package
-  const localBin = join(__dirname, "bin", "gale");
-  if (existsSync(localBin)) {
-    return localBin;
+  // 0. An explicit override wins. Test suites and monorepos use this to point
+  //    at a freshly built binary instead of the bundled one.
+  const override = process.env.GALE_BINARY;
+  if (override) {
+    return override;
+  }
+
+  // 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
@@ -122,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,14 +1,14 @@
 {
   "name": "@codebend3r/gale",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "An extremely fast CSS linter, written in Rust. Drop-in replacement for Stylelint.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/LyricalString/gale"
+    "url": "https://github.com/codebend3r/gale"
   },
-  "homepage": "https://github.com/LyricalString/gale",
-  "bugs": "https://github.com/LyricalString/gale/issues",
+  "homepage": "https://github.com/codebend3r/gale",
+  "bugs": "https://github.com/codebend3r/gale/issues",
   "keywords": [
     "css",
     "linter",
@@ -22,24 +22,28 @@
   ],
   "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"
   ],
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "test": "node test.mjs"

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/test.mjs

@@ -8,18 +8,45 @@
  * Requires a working gale binary (either in npm/bin/ or on PATH).
  */
 
+import { createRequire } from "node:module";
+
 import { lint, formatters, resolveConfig, createPlugin } from "./index.mjs";
 
+const require = createRequire(import.meta.url);
+
 let passed = 0;
 let failed = 0;
+let current = "";
+
+// Dots reporter: one "." per passing assertion, "F" per failure. Failure
+// details are printed on their own line so the dots stay readable.
+function section(name) {
+  current = name;
+}
+
+function fail(message) {
+  process.stdout.write("F");
+  console.error(`\n  FAIL [${current}] ${message}`);
+  failed++;
+}
 
 function assert(condition, message) {
   if (condition) {
-    console.log(`  PASS: ${message}`);
+    process.stdout.write(".");
     passed++;
   } else {
-    console.error(`  FAIL: ${message}`);
-    failed++;
+    fail(message);
+  }
+}
+
+// Runs fn with console.warn muted, for APIs that warn by design.
+function quietly(fn) {
+  const warn = console.warn;
+  console.warn = () => {};
+  try {
+    return fn();
+  } finally {
+    console.warn = warn;
   }
 }
 
@@ -28,7 +55,7 @@ function assert(condition, message) {
 // ---------------------------------------------------------------------------
 
 async function testLintCodeEmptyBlock() {
-  console.log("\nTest 1: lint({ code: 'a {}' })");
+  section("Test 1: lint({ code: 'a {}' })");
 
   try {
     const result = await lint({ code: "a {}" });
@@ -50,8 +77,7 @@ async function testLintCodeEmptyBlock() {
       assert(typeof first.ignored === "boolean", "first result has ignored boolean");
     }
   } catch (err) {
-    console.error(`  ERROR: ${err.message}`);
-    failed++;
+    fail(`ERROR: ${err.message}`);
   }
 }
 
@@ -60,7 +86,7 @@ async function testLintCodeEmptyBlock() {
 // ---------------------------------------------------------------------------
 
 async function testLintCodeWithConfig() {
-  console.log("\nTest 2: lint({ code: 'a { color: pink; }', config: { rules: { 'color-named': 'never' } } })");
+  section("Test 2: lint({ code: 'a { color: pink; }', config: { rules: { 'color-named': 'never' } } })");
 
   try {
     const result = await lint({
@@ -86,13 +112,10 @@ async function testLintCodeWithConfig() {
           w.rule === "color-named",
           `warning rule is "color-named" (got "${w.rule}")`,
         );
-      } else {
-        console.log("  INFO: No warnings returned (gale may not flag this without config).");
       }
     }
   } catch (err) {
-    console.error(`  ERROR: ${err.message}`);
-    failed++;
+    fail(`ERROR: ${err.message}`);
   }
 }
 
@@ -101,7 +124,7 @@ async function testLintCodeWithConfig() {
 // ---------------------------------------------------------------------------
 
 async function testResolveConfig() {
-  console.log("\nTest 3: resolveConfig('test.css')");
+  section("Test 3: resolveConfig('test.css')");
 
   try {
     const config = await resolveConfig("test.css");
@@ -111,8 +134,7 @@ async function testResolveConfig() {
       "resolveConfig returns object or undefined",
     );
   } catch (err) {
-    console.error(`  ERROR: ${err.message}`);
-    failed++;
+    fail(`ERROR: ${err.message}`);
   }
 }
 
@@ -121,7 +143,7 @@ async function testResolveConfig() {
 // ---------------------------------------------------------------------------
 
 async function testFormattersJson() {
-  console.log("\nTest 4: formatters.json resolves to a function");
+  section("Test 4: formatters.json resolves to a function");
 
   try {
     const jsonFormatter = await formatters.json;
@@ -144,8 +166,7 @@ async function testFormattersJson() {
     const parsed = JSON.parse(output);
     assert(Array.isArray(parsed), "JSON formatter output is parseable as array");
   } catch (err) {
-    console.error(`  ERROR: ${err.message}`);
-    failed++;
+    fail(`ERROR: ${err.message}`);
   }
 }
 
@@ -154,9 +175,9 @@ async function testFormattersJson() {
 // ---------------------------------------------------------------------------
 
 async function testCreatePlugin() {
-  console.log("\nTest 5: createPlugin returns stub");
+  section("Test 5: createPlugin returns stub");
 
-  const plugin = createPlugin("my-rule", () => {});
+  const plugin = quietly(() => createPlugin("my-rule", () => {}));
   assert(plugin.ruleName === "my-rule", 'plugin.ruleName is "my-rule"');
   assert(typeof plugin.rule === "function", "plugin.rule is a function");
 }
@@ -166,7 +187,7 @@ async function testCreatePlugin() {
 // ---------------------------------------------------------------------------
 
 async function testLinterResultShape() {
-  console.log("\nTest 6: LinterResult has correct shape");
+  section("Test 6: LinterResult has correct shape");
 
   try {
     const result = await lint({ code: "a { color: red; }" });
@@ -179,8 +200,39 @@ async function testLinterResultShape() {
     assert("maxWarningsExceeded" in result, "result has maxWarningsExceeded key");
     assert("code" in result, "result has code key");
   } catch (err) {
-    console.error(`  ERROR: ${err.message}`);
-    failed++;
+    fail(`ERROR: ${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 7: CommonJS entry point bridges to the ESM implementation
+// ---------------------------------------------------------------------------
+
+async function testCommonJsEntry() {
+  section("Test 7: require('./index.cjs') exposes the same API");
+
+  try {
+    const cjs = require("./index.cjs");
+
+    assert(typeof cjs.lint === "function", "cjs.lint is a function");
+    assert(typeof cjs.resolveConfig === "function", "cjs.resolveConfig is a function");
+    assert(typeof cjs.createPlugin === "function", "cjs.createPlugin is a function");
+    assert(cjs.default === cjs, "cjs.default points back at module.exports");
+
+    const jsonFormatter = await cjs.formatters.json;
+    assert(typeof jsonFormatter === "function", "cjs.formatters.json resolves to a function");
+
+    const result = await cjs.lint({
+      code: "a {}",
+      config: { rules: { "block-no-empty": true } },
+    });
+    assert(Array.isArray(result.results), "cjs.lint returns results");
+    assert(
+      result.results[0]?.warnings[0]?.rule === "block-no-empty",
+      "cjs.lint reports block-no-empty",
+    );
+  } catch (err) {
+    fail(`ERROR: ${err.message}`);
   }
 }
 
@@ -189,16 +241,15 @@ async function testLinterResultShape() {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  console.log("=== @codebend3r/gale programmatic API tests ===");
-
   await testLintCodeEmptyBlock();
   await testLintCodeWithConfig();
   await testResolveConfig();
   await testFormattersJson();
   await testCreatePlugin();
   await testLinterResultShape();
+  await testCommonJsEntry();
 
-  console.log(`\n=== Results: ${passed} passed, ${failed} failed ===`);
+  console.log(`\n${passed} passed, ${failed} failed (Node ${process.versions.node})`);
 
   if (failed > 0) {
     process.exit(1);

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" "$@"