@codebend3r/gale 0.2.0

package/README.md

@@ -0,0 +1,30 @@
+# Gale
+
+**An extremely fast CSS linter. Drop-in replacement for Stylelint.**
+
+100x-400x faster. Same config. Zero migration.
+
+> **Compatibility:** Gale targets **Stylelint v17** semantics.
+
+```bash
+npm install -D @codebend3r/gale
+
+# Uses your existing .stylelintrc
+npx gale "src/**/*.css"
+```
+
+## Programmatic API
+
+```javascript
+import { lint, resolveConfig, formatters } from '@codebend3r/gale';
+
+const result = await lint({
+  files: 'src/**/*.css',
+  config: { rules: { 'block-no-empty': true } },
+});
+
+console.log(result.errored);
+console.log(result.results);
+```
+
+See the full documentation at [github.com/LyricalString/gale](https://github.com/LyricalString/gale).

package/bin/gale

@@ -0,0 +1,54 @@
+#!/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" "$@"

package/index.cjs

@@ -0,0 +1,60 @@
+// CommonJS entry point.
+//
+// The implementation lives in index.mjs (ESM). CommonJS cannot `require()` an
+// ES module synchronously, so this file bridges to it with a dynamic import.
+// Every bridged function is already async, which makes the bridge transparent.
+//
+// This file also exists so that tools like `resolve-bin` and `require.resolve()`
+// can locate the package.
+
+let modulePromise;
+
+function load() {
+  if (!modulePromise) {
+    modulePromise = import("./index.mjs");
+  }
+  return modulePromise;
+}
+
+/**
+ * Lint CSS files or code. See index.mjs for the full option list.
+ * @returns {Promise<object>} a Stylelint-compatible LinterResult
+ */
+async function lint(options) {
+  return (await load()).lint(options);
+}
+
+/**
+ * Resolve the effective config for a file path.
+ * @returns {Promise<object|undefined>}
+ */
+async function resolveConfig(filePath, options) {
+  return (await load()).resolveConfig(filePath, options);
+}
+
+/**
+ * Stub for Stylelint's createPlugin(). Gale uses built-in Rust rules.
+ * Kept synchronous to match Stylelint's signature.
+ */
+function createPlugin(ruleName, ruleFunction) {
+  console.warn(
+    `[gale] createPlugin("${ruleName}"): Gale uses built-in rules instead of JS plugins. ` +
+      "This plugin will not be executed.",
+  );
+  return { ruleName, rule: ruleFunction };
+}
+
+// Stylelint exposes each formatter as a promise-returning getter.
+const FORMATTER_NAMES = ["json", "string", "compact", "verbose", "tap", "unix"];
+const formatters = {};
+for (const name of FORMATTER_NAMES) {
+  Object.defineProperty(formatters, name, {
+    enumerable: true,
+    get() {
+      return load().then((m) => m.formatters[name]);
+    },
+  });
+}
+
+module.exports = { lint, resolveConfig, createPlugin, formatters };
+module.exports.default = module.exports;

package/index.mjs

@@ -0,0 +1,543 @@
+/**
+ * @codebend3r/gale — Stylelint-compatible programmatic API
+ *
+ * This module wraps the native Gale binary and exposes the same API surface
+ * as `stylelint.lint()`, `stylelint.formatters`, and `stylelint.resolveConfig`.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, writeFileSync, unlinkSync, rmSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Binary resolution
+// ---------------------------------------------------------------------------
+
+function findBinary() {
+  // 1. Check the bin/ directory within the npm package
+  const localBin = join(__dirname, "bin", "gale");
+  if (existsSync(localBin)) {
+    return localBin;
+  }
+
+  // 2. Fall back to gale on PATH
+  return "gale";
+}
+
+// ---------------------------------------------------------------------------
+// Spawn helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn the gale binary and return { stdout, stderr, exitCode }.
+ * If `stdinData` is provided it is piped to the process.
+ */
+function runGale(args, { stdinData, cwd } = {}) {
+  return new Promise((resolve, reject) => {
+    const bin = findBinary();
+    const proc = spawn(bin, args, {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env },
+    });
+
+    const stdoutChunks = [];
+    const stderrChunks = [];
+
+    proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+    proc.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+
+    proc.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        reject(
+          new Error(
+            `Gale binary not found. Looked for "${bin}". ` +
+              "Install @codebend3r/gale or ensure gale is on your PATH.",
+          ),
+        );
+      } else {
+        reject(err);
+      }
+    });
+
+    proc.on("close", (exitCode) => {
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf8"),
+        exitCode,
+      });
+    });
+
+    if (stdinData != null) {
+      proc.stdin.write(stdinData);
+      proc.stdin.end();
+    } else {
+      proc.stdin.end();
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Temp config helper
+// ---------------------------------------------------------------------------
+
+function writeTempConfig(config) {
+  const dir = mkdtempSync(join(tmpdir(), "gale-"));
+  const file = join(dir, "gale.json");
+  writeFileSync(file, JSON.stringify(config, null, 2));
+  return { file, dir };
+}
+
+function cleanupTempConfig({ file, dir }) {
+  try {
+    unlinkSync(file);
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // best-effort cleanup
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parse Gale JSON output into Stylelint-shaped results
+// ---------------------------------------------------------------------------
+
+function parseJsonOutput(jsonString) {
+  let raw;
+  try {
+    raw = JSON.parse(jsonString);
+  } catch {
+    return [];
+  }
+
+  if (!Array.isArray(raw)) return [];
+
+  return raw.map((entry) => ({
+    source: entry.source || "",
+    warnings: (entry.warnings || []).map((w) => ({
+      line: w.line,
+      column: w.column,
+      rule: w.rule,
+      severity: w.severity || "warning",
+      text: w.text,
+    })),
+    deprecations: [],
+    invalidOptionWarnings: [],
+    parseErrors: [],
+    errored: (entry.warnings || []).some((w) => w.severity === "error"),
+    ignored: false,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// lint()
+// ---------------------------------------------------------------------------
+
+/**
+ * Lint CSS files or code, returning a Stylelint-compatible `LinterResult`.
+ *
+ * @param {object} options
+ * @param {string|string[]} [options.files]        - Glob pattern(s) for files to lint
+ * @param {string}          [options.code]         - CSS code string to lint instead of files
+ * @param {string}          [options.codeFilename] - Virtual filename for `code` (for syntax detection)
+ * @param {object}          [options.config]       - Inline config object
+ * @param {string}          [options.configFile]   - Path to config file
+ * @param {boolean|string}  [options.fix]          - Enable autofix (true, "strict", or "lax")
+ * @param {string|Function} [options.formatter]    - Formatter name or function
+ * @param {boolean}         [options.quiet]        - Only report errors
+ * @param {boolean}         [options.cache]        - Enable caching
+ * @param {string}          [options.cacheLocation] - Override cache file location
+ * @param {number}          [options.maxWarnings]  - Max warnings before erroring
+ * @param {boolean}         [options.allowEmptyInput] - Don't error when no files match
+ * @param {string}          [options.ignorePath]   - Path to a custom ignore file
+ * @param {boolean}         [options.ignoreDisables] - Ignore all stylelint-disable comments
+ * @param {boolean}         [options.reportNeedlessDisables] - Report needless disable comments
+ * @param {boolean}         [options.reportInvalidScopeDisables] - Report invalid-scope disable comments
+ * @param {boolean}         [options.reportDescriptionlessDisables] - Report descriptionless disable comments
+ * @param {string}          [options.cwd]          - Working directory
+ * @returns {Promise<LinterResult>}
+ */
+export async function lint(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const args = [];
+  let tempConfig = null;
+
+  try {
+    // -- Formatter: always use JSON internally to get structured results --
+    args.push("--formatter", "json");
+
+    // -- Config --
+    if (options.config) {
+      tempConfig = writeTempConfig(options.config);
+      args.push("--config", tempConfig.file);
+    } else if (options.configFile) {
+      args.push("--config", resolve(cwd, options.configFile));
+    }
+
+    // -- Fix --
+    if (options.fix) {
+      if (typeof options.fix === "string") {
+        args.push(`--fix=${options.fix}`);
+      } else {
+        args.push("--fix");
+      }
+    }
+
+    // -- Quiet --
+    if (options.quiet) {
+      args.push("--quiet");
+    }
+
+    // -- Cache --
+    if (options.cache) {
+      args.push("--cache");
+    }
+
+    // -- Max warnings --
+    if (options.maxWarnings != null) {
+      args.push("--max-warnings", String(options.maxWarnings));
+    }
+
+    // -- Cache location --
+    if (options.cacheLocation) {
+      args.push("--cache-location", resolve(cwd, options.cacheLocation));
+    }
+
+    // -- Allow empty input --
+    if (options.allowEmptyInput) {
+      args.push("--allow-empty-input");
+    }
+
+    // -- Ignore path --
+    if (options.ignorePath) {
+      args.push("--ignore-path", resolve(cwd, options.ignorePath));
+    }
+
+    // -- Ignore disables --
+    if (options.ignoreDisables) {
+      args.push("--ignore-disables");
+    }
+
+    // -- Report needless disables --
+    if (options.reportNeedlessDisables) {
+      args.push("--report-needless-disables");
+    }
+
+    // -- Report invalid scope disables --
+    if (options.reportInvalidScopeDisables) {
+      args.push("--report-invalid-scope-disables");
+    }
+
+    // -- Report descriptionless disables --
+    if (options.reportDescriptionlessDisables) {
+      args.push("--report-descriptionless-disables");
+    }
+
+    // -- Input source --
+    let stdinData = null;
+
+    if (options.code != null) {
+      args.push("--stdin");
+      if (options.codeFilename) {
+        args.push("--stdin-filename", options.codeFilename);
+      }
+      stdinData = options.code;
+    } else if (options.files) {
+      const patterns = Array.isArray(options.files) ? options.files : [options.files];
+      args.push(...patterns);
+    } else {
+      throw new Error(
+        'Either "files" or "code" must be provided to lint().',
+      );
+    }
+
+    const { stdout, stderr, exitCode } = await runGale(args, {
+      stdinData,
+      cwd,
+    });
+
+    // When allowEmptyInput is true and no files were found, return an
+    // empty successful result instead of propagating any error.
+    if (options.allowEmptyInput && !stdout.trim()) {
+      return {
+        cwd,
+        results: [],
+        errored: false,
+        report: "",
+        code: undefined,
+        maxWarningsExceeded: undefined,
+        ruleMetadata: {},
+      };
+    }
+
+    // Parse the JSON results
+    const results = parseJsonOutput(stdout);
+
+    // Determine if any result had errors
+    const errored = results.some((r) => r.errored);
+
+    // Build formatted report if a specific formatter was requested
+    let report = stdout;
+    if (
+      options.formatter &&
+      typeof options.formatter === "string" &&
+      options.formatter !== "json"
+    ) {
+      // Re-run with the requested formatter for the report string
+      const reportArgs = [...args];
+      const jsonIdx = reportArgs.indexOf("json");
+      if (jsonIdx !== -1) {
+        reportArgs[jsonIdx] = options.formatter;
+      }
+      const reportResult = await runGale(reportArgs, { stdinData, cwd });
+      report = reportResult.stdout;
+    } else if (typeof options.formatter === "function") {
+      report = options.formatter(results, { cwd, results, errored });
+    }
+
+    // Determine fixed code (only when fix + code input)
+    let fixedCode;
+    if (options.fix && options.code != null) {
+      // When --fix + --stdin, gale outputs the fixed source to stdout.
+      // We need to re-run with fix to get the fixed code, without JSON formatter.
+      const fixArgs = [];
+      if (tempConfig) {
+        fixArgs.push("--config", tempConfig.file);
+      } else if (options.configFile) {
+        fixArgs.push("--config", resolve(cwd, options.configFile));
+      }
+      fixArgs.push("--fix", "--stdin");
+      if (options.codeFilename) {
+        fixArgs.push("--stdin-filename", options.codeFilename);
+      }
+      const fixResult = await runGale(fixArgs, { stdinData: options.code, cwd });
+      fixedCode = fixResult.stdout;
+    }
+
+    // Max warnings check
+    let maxWarningsExceeded;
+    if (options.maxWarnings != null) {
+      const totalWarnings = results.reduce(
+        (sum, r) =>
+          sum + r.warnings.filter((w) => w.severity === "warning").length,
+        0,
+      );
+      if (totalWarnings > options.maxWarnings) {
+        maxWarningsExceeded = {
+          maxWarnings: options.maxWarnings,
+          foundWarnings: totalWarnings,
+        };
+      }
+    }
+
+    return {
+      cwd,
+      results,
+      errored,
+      report,
+      code: fixedCode,
+      maxWarningsExceeded,
+      ruleMetadata: {},
+    };
+  } finally {
+    if (tempConfig) {
+      cleanupTempConfig(tempConfig);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// formatters
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a formatter function that calls gale with the given format name.
+ */
+function createFormatterFn(formatName) {
+  return async (results, returnValue) => {
+    // Build a minimal JSON array to pipe to gale for re-formatting.
+    // Since gale reads files (not a JSON stream), we format client-side
+    // for the simple built-in formats.
+    if (formatName === "json") {
+      return JSON.stringify(
+        results.map((r) => ({
+          source: r.source,
+          warnings: r.warnings,
+        })),
+      );
+    }
+
+    // For other formatters, produce a simple text representation
+    // matching what gale would output.
+    let output = "";
+
+    if (formatName === "compact") {
+      for (const r of results) {
+        for (const w of r.warnings) {
+          output += `${r.source}: line ${w.line}, col ${w.column}, ${w.severity} - ${w.text}\n`;
+        }
+      }
+      return output;
+    }
+
+    if (formatName === "tap") {
+      output += "TAP version 13\n";
+      output += `1..${results.length}\n`;
+      results.forEach((r, i) => {
+        if (r.warnings.length === 0) {
+          output += `ok ${i + 1} - ${r.source}\n`;
+        } else {
+          output += `not ok ${i + 1} - ${r.source}\n`;
+          for (const w of r.warnings) {
+            output += `  ---\n`;
+            output += `  message: "${w.text}"\n`;
+            output += `  severity: ${w.severity}\n`;
+            output += `  data:\n`;
+            output += `    line: ${w.line}\n`;
+            output += `    column: ${w.column}\n`;
+            output += `    ruleId: ${w.rule}\n`;
+            output += `  ...\n`;
+          }
+        }
+      });
+      return output;
+    }
+
+    if (formatName === "unix") {
+      for (const r of results) {
+        for (const w of r.warnings) {
+          output += `${r.source}:${w.line}:${w.column}: ${w.text} [${w.severity}]\n`;
+        }
+      }
+      const total = results.reduce((s, r) => s + r.warnings.length, 0);
+      if (total > 0) {
+        output += `\n${total} problem${total === 1 ? "" : "s"}\n`;
+      }
+      return output;
+    }
+
+    // "string" / "verbose" / default: human-readable
+    for (const r of results) {
+      if (r.warnings.length === 0) continue;
+      output += `${r.source}\n`;
+      for (const w of r.warnings) {
+        const icon = w.severity === "error" ? "\u2716" : "\u26A0";
+        output += `  ${w.line}:${w.column}  ${icon}  ${w.text}  ${w.rule}\n`;
+      }
+      output += "\n";
+    }
+
+    const totalErrors = results.reduce(
+      (s, r) => s + r.warnings.filter((w) => w.severity === "error").length,
+      0,
+    );
+    const totalWarnings = results.reduce(
+      (s, r) => s + r.warnings.filter((w) => w.severity === "warning").length,
+      0,
+    );
+    const total = totalErrors + totalWarnings;
+    if (total > 0) {
+      const p = total === 1 ? "problem" : "problems";
+      const e = totalErrors === 1 ? "error" : "errors";
+      const w = totalWarnings === 1 ? "warning" : "warnings";
+      output += `\u2716 ${total} ${p} (${totalErrors} ${e}, ${totalWarnings} ${w})\n`;
+    }
+
+    return output;
+  };
+}
+
+/**
+ * Lazy promise-based formatters matching Stylelint's API.
+ * Each getter returns a Promise<Function>.
+ */
+export const formatters = {
+  get json() {
+    return Promise.resolve(createFormatterFn("json"));
+  },
+  get string() {
+    return Promise.resolve(createFormatterFn("string"));
+  },
+  get compact() {
+    return Promise.resolve(createFormatterFn("compact"));
+  },
+  get verbose() {
+    return Promise.resolve(createFormatterFn("verbose"));
+  },
+  get tap() {
+    return Promise.resolve(createFormatterFn("tap"));
+  },
+  get unix() {
+    return Promise.resolve(createFormatterFn("unix"));
+  },
+};
+
+// ---------------------------------------------------------------------------
+// resolveConfig()
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the effective config for a given file path.
+ *
+ * @param {string} filePath - The file to resolve config for
+ * @param {object} [options]
+ * @param {string} [options.configFile] - Explicit config file to use
+ * @param {string} [options.cwd] - Working directory
+ * @returns {Promise<object|undefined>}
+ */
+export async function resolveConfig(filePath, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const args = ["--print-config", filePath];
+
+  if (options.configFile) {
+    args.push("--config", resolve(cwd, options.configFile));
+  }
+
+  try {
+    const { stdout, exitCode } = await runGale(args, { cwd });
+
+    if (exitCode !== 0 || !stdout.trim()) {
+      return undefined;
+    }
+
+    return JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// createPlugin() — compatibility stub
+// ---------------------------------------------------------------------------
+
+/**
+ * Stub for Stylelint's `createPlugin()` API.
+ * Gale uses built-in Rust rules instead of JS plugins.
+ *
+ * @param {string} ruleName
+ * @param {Function} ruleFunction
+ * @returns {{ ruleName: string, rule: Function }}
+ */
+export function createPlugin(ruleName, ruleFunction) {
+  console.warn(
+    `[gale] createPlugin("${ruleName}"): Gale uses built-in rules instead of JS plugins. ` +
+      "This plugin will not be executed.",
+  );
+  return { ruleName, rule: ruleFunction };
+}
+
+// ---------------------------------------------------------------------------
+// Default export (Stylelint compat)
+// ---------------------------------------------------------------------------
+
+export default {
+  lint,
+  formatters,
+  resolveConfig,
+  createPlugin,
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@codebend3r/gale",
+  "version": "0.2.0",
+  "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"
+  },
+  "homepage": "https://github.com/LyricalString/gale",
+  "bugs": "https://github.com/LyricalString/gale/issues",
+  "keywords": [
+    "css",
+    "linter",
+    "stylelint",
+    "scss",
+    "less",
+    "rust",
+    "fast",
+    "lint",
+    "gale"
+  ],
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.cjs"
+    }
+  },
+  "bin": {
+    "gale": "bin/gale"
+  },
+  "files": [
+    "bin/",
+    "index.cjs",
+    "index.mjs",
+    "test.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "test": "node test.mjs"
+  }
+}

package/test.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+/**
+ * Basic smoke tests for the @codebend3r/gale programmatic API.
+ *
+ * Run: node test.mjs
+ *
+ * Requires a working gale binary (either in npm/bin/ or on PATH).
+ */
+
+import { lint, formatters, resolveConfig, createPlugin } from "./index.mjs";
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, message) {
+  if (condition) {
+    console.log(`  PASS: ${message}`);
+    passed++;
+  } else {
+    console.error(`  FAIL: ${message}`);
+    failed++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: lint({ code }) with empty block
+// ---------------------------------------------------------------------------
+
+async function testLintCodeEmptyBlock() {
+  console.log("\nTest 1: lint({ code: 'a {}' })");
+
+  try {
+    const result = await lint({ code: "a {}" });
+
+    assert(result != null, "result is not null");
+    assert(typeof result.cwd === "string", "result.cwd is a string");
+    assert(Array.isArray(result.results), "result.results is an array");
+    assert(typeof result.errored === "boolean", "result.errored is a boolean");
+    assert(typeof result.report === "string", "result.report is a string");
+    assert(typeof result.ruleMetadata === "object", "result.ruleMetadata is an object");
+
+    if (result.results.length > 0) {
+      const first = result.results[0];
+      assert(typeof first.source === "string", "first result has source");
+      assert(Array.isArray(first.warnings), "first result has warnings array");
+      assert(Array.isArray(first.deprecations), "first result has deprecations array");
+      assert(Array.isArray(first.parseErrors), "first result has parseErrors array");
+      assert(typeof first.errored === "boolean", "first result has errored boolean");
+      assert(typeof first.ignored === "boolean", "first result has ignored boolean");
+    }
+  } catch (err) {
+    console.error(`  ERROR: ${err.message}`);
+    failed++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 2: lint({ code, config }) with color-named rule
+// ---------------------------------------------------------------------------
+
+async function testLintCodeWithConfig() {
+  console.log("\nTest 2: lint({ code: 'a { color: pink; }', config: { rules: { 'color-named': 'never' } } })");
+
+  try {
+    const result = await lint({
+      code: "a { color: pink; }",
+      config: { rules: { "color-named": "never" } },
+    });
+
+    assert(result != null, "result is not null");
+    assert(Array.isArray(result.results), "result.results is an array");
+
+    if (result.results.length > 0) {
+      const warnings = result.results[0].warnings;
+      assert(Array.isArray(warnings), "warnings is an array");
+
+      if (warnings.length > 0) {
+        const w = warnings[0];
+        assert(typeof w.line === "number", "warning has line number");
+        assert(typeof w.column === "number", "warning has column number");
+        assert(typeof w.rule === "string", "warning has rule name");
+        assert(typeof w.severity === "string", "warning has severity");
+        assert(typeof w.text === "string", "warning has text");
+        assert(
+          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++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 3: resolveConfig
+// ---------------------------------------------------------------------------
+
+async function testResolveConfig() {
+  console.log("\nTest 3: resolveConfig('test.css')");
+
+  try {
+    const config = await resolveConfig("test.css");
+    // May be undefined if no config file is found in the directory
+    assert(
+      config === undefined || typeof config === "object",
+      "resolveConfig returns object or undefined",
+    );
+  } catch (err) {
+    console.error(`  ERROR: ${err.message}`);
+    failed++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 4: formatters.json resolves to a function
+// ---------------------------------------------------------------------------
+
+async function testFormattersJson() {
+  console.log("\nTest 4: formatters.json resolves to a function");
+
+  try {
+    const jsonFormatter = await formatters.json;
+    assert(typeof jsonFormatter === "function", "formatters.json resolves to a function");
+
+    // Test it works
+    const output = await jsonFormatter(
+      [
+        {
+          source: "test.css",
+          warnings: [
+            { line: 1, column: 1, rule: "test-rule", severity: "warning", text: "test" },
+          ],
+        },
+      ],
+      {},
+    );
+    assert(typeof output === "string", "formatter returns a string");
+
+    const parsed = JSON.parse(output);
+    assert(Array.isArray(parsed), "JSON formatter output is parseable as array");
+  } catch (err) {
+    console.error(`  ERROR: ${err.message}`);
+    failed++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 5: createPlugin stub
+// ---------------------------------------------------------------------------
+
+async function testCreatePlugin() {
+  console.log("\nTest 5: createPlugin returns stub");
+
+  const plugin = createPlugin("my-rule", () => {});
+  assert(plugin.ruleName === "my-rule", 'plugin.ruleName is "my-rule"');
+  assert(typeof plugin.rule === "function", "plugin.rule is a function");
+}
+
+// ---------------------------------------------------------------------------
+// Test 6: LinterResult shape
+// ---------------------------------------------------------------------------
+
+async function testLinterResultShape() {
+  console.log("\nTest 6: LinterResult has correct shape");
+
+  try {
+    const result = await lint({ code: "a { color: red; }" });
+
+    assert("cwd" in result, "result has cwd");
+    assert("results" in result, "result has results");
+    assert("errored" in result, "result has errored");
+    assert("report" in result, "result has report");
+    assert("ruleMetadata" in result, "result has ruleMetadata");
+    assert("maxWarningsExceeded" in result, "result has maxWarningsExceeded key");
+    assert("code" in result, "result has code key");
+  } catch (err) {
+    console.error(`  ERROR: ${err.message}`);
+    failed++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Run all tests
+// ---------------------------------------------------------------------------
+
+async function main() {
+  console.log("=== @codebend3r/gale programmatic API tests ===");
+
+  await testLintCodeEmptyBlock();
+  await testLintCodeWithConfig();
+  await testResolveConfig();
+  await testFormattersJson();
+  await testCreatePlugin();
+  await testLinterResultShape();
+
+  console.log(`\n=== Results: ${passed} passed, ${failed} failed ===`);
+
+  if (failed > 0) {
+    process.exit(1);
+  }
+}
+
+main();