@theholocron/astromech 4.5.0 → 4.6.0

package/README.md

@@ -119,7 +119,7 @@ one place, `src/linters.ts`.
 | `actionlint`                 | `GITHUB_ACTIONS`                          | yes                                 | `actionlint` (usually CI-only)           |
 | `gitleaks`                   | `GITLEAKS`                                | yes                                 | `gitleaks dir` (usually CI-only)         |
 | `editorconfig`               | `EDITORCONFIG`                            | yes                                 | `editorconfig-checker` (usually CI-only) |
-| `commitlint`                 | `GIT_COMMITLINT`                          | yes                                 | `commitlint --last`                      |
+| `commitlint`                 | `GIT_COMMITLINT`                          | yes                                 | — (commit-msg hook + CI)                 |
 | `git-merge-conflict-markers` | `GIT_MERGE_CONFLICT_MARKERS`              | yes                                 | — (CI only)                              |
 | `markdownlint`               | `MARKDOWN`                                | on `.markdownlint*`                 | `markdownlint-cli2`                      |
 

package/dist/index.d.mts

@@ -5,12 +5,19 @@ import { r as TasksConfig } from "./schema-DbpiBZCP.mjs";
  *
  * Resolution:
  *
+ *   0. task === "lint"                        → the linter aggregate (see below)
  *   1. turbo.json defines the task            → `turbo run <task>`
  *   2. package.json has a `<task>` script     → `<pm> run <task>`
  *      (unless it's the `holocron run …` thin caller — that recurses)
  *   3. TASKS[task].local resolves             → `<tool> <args> <org-flags> <passthrough>`
  *   4. known task, nothing to run             → "no <task> task" (exit 0, or 1 with --required)
  *   5. unknown task                           → "unknown task" (exit 1)
+ *
+ * `lint` runs the resolved linter set (`config.tasks` `linters`, else
+ * auto-detected): the eslint slot goes through the standard turbo / script /
+ * `eslint .` resolution (so turbo caching is kept); every other linter runs
+ * its `localBin` when found on PATH. Missing tools are flagged; the exit code
+ * is the worst of the lot.
  */
 /** Minimal structural logger — `@theholocron/logger`'s `Logger` satisfies it. */
 interface RunLogger {
@@ -35,6 +42,8 @@ interface RunDeps {
   readFile: (path: string) => string;
   fileExists: (path: string) => boolean;
   listDir: (path: string) => string[];
+  /** `node_modules/.bin/<bin>` or a PATH entry; `null` when not runnable. */
+  lookPath: (cwd: string, bin: string) => string | null;
 }
 interface RunTaskInput extends RunDeps {
   /** Registry task name, e.g. `"test"`. */
@@ -47,6 +56,8 @@ interface RunTaskInput extends RunDeps {
   dryRun?: boolean;
   /** Turn "no such task for this repo" (normally exit 0) into a failure. */
   required?: boolean;
+  /** The `lint` task's explicit linter list from `config.tasks`, if any. */
+  linters?: string[];
 }
 interface RunTaskReport {
   status: "ok" | "fail" | "skip" | "dry-run" | "unknown";
@@ -242,6 +253,8 @@ interface AstromechOptions {
   readFile?: (path: string) => string;
   fileExists?: (path: string) => boolean;
   listDir?: (path: string) => string[];
+  /** Injectable binary lookup (tests). Default checks `node_modules/.bin` then `PATH`. */
+  lookPath?: (cwd: string, bin: string) => string | null;
 }
 interface RunOptions {
   /** Args after `--`, forwarded to the tool / turbo / script. */

package/dist/index.mjs

@@ -51,24 +51,159 @@ const TASKS = {
 /** Every task name the registry knows. */
 const KNOWN_TASKS = new Set(Object.keys(TASKS));
 //#endregion
+//#region src/linters.ts
+/**
+* Known linters, in execution order. `always` entries are the current
+* hard-coded super-linter baseline; `prettier` is always-on because the org
+* applies it universally (super-linter only lints files that exist).
+*/
+const LINTERS = {
+	eslint: {
+		validate: ["VALIDATE_JAVASCRIPT_ES", "VALIDATE_TYPESCRIPT_ES"],
+		localBin: "eslint",
+		localArgs: ["."],
+		detect: [
+			"eslint.config.ts",
+			"eslint.config.js",
+			"eslint.config.mjs",
+			"eslint.config.cjs",
+			".eslintrc",
+			".eslintrc.json",
+			".eslintrc.yml",
+			".eslintrc.yaml",
+			".eslintrc.cjs"
+		],
+		configInput: "eslint-config"
+	},
+	prettier: {
+		validate: [
+			"VALIDATE_JAVASCRIPT_PRETTIER",
+			"VALIDATE_JSX_PRETTIER",
+			"VALIDATE_TYPESCRIPT_PRETTIER",
+			"VALIDATE_TSX",
+			"VALIDATE_MARKDOWN_PRETTIER"
+		],
+		fix: [
+			"FIX_JAVASCRIPT_PRETTIER",
+			"FIX_JSX_PRETTIER",
+			"FIX_TYPESCRIPT_PRETTIER",
+			"FIX_TSX",
+			"FIX_MARKDOWN_PRETTIER"
+		],
+		always: true,
+		localBin: "prettier",
+		localArgs: ["--check", "."],
+		configInput: "prettier-config"
+	},
+	yamllint: {
+		validate: ["VALIDATE_YAML"],
+		always: true,
+		localBin: "yamllint",
+		localArgs: ["."],
+		installHint: "brew install yamllint",
+		configInput: "yaml-config"
+	},
+	actionlint: {
+		validate: ["VALIDATE_GITHUB_ACTIONS"],
+		always: true,
+		localBin: "actionlint",
+		localArgs: [],
+		installHint: "brew install actionlint"
+	},
+	gitleaks: {
+		validate: ["VALIDATE_GITLEAKS"],
+		always: true,
+		localBin: "gitleaks",
+		localArgs: ["dir", "--no-banner"],
+		installHint: "brew install gitleaks"
+	},
+	editorconfig: {
+		validate: ["VALIDATE_EDITORCONFIG"],
+		always: true,
+		localBin: "editorconfig-checker",
+		localArgs: [],
+		installHint: "brew install editorconfig-checker"
+	},
+	commitlint: {
+		validate: ["VALIDATE_GIT_COMMITLINT"],
+		always: true
+	},
+	"git-merge-conflict-markers": {
+		validate: ["VALIDATE_GIT_MERGE_CONFLICT_MARKERS"],
+		always: true
+	},
+	markdownlint: {
+		validate: ["VALIDATE_MARKDOWN"],
+		localBin: "markdownlint-cli2",
+		localArgs: ["**/*.md"],
+		detect: [
+			".markdownlint.json",
+			".markdownlint.jsonc",
+			".markdownlint.yaml",
+			".markdownlint.yml",
+			".markdownlint-cli2.jsonc",
+			".markdownlint-cli2.yaml",
+			".markdownlint-cli2.mjs"
+		]
+	}
+};
+/** Every linter name the registry knows. */
+const LINTER_NAMES = new Set(Object.keys(LINTERS));
+/**
+* Resolve the linter set for a repo. An `explicit` list (from
+* `config.tasks`) wins verbatim; otherwise every `always` linter plus every
+* linter whose `detect` filenames are present at the repo root. Result is
+* ordered by {@link LINTERS} declaration order.
+*
+* @throws when an `explicit` name is not in the registry — a typo is a
+* config bug, not a linter to silently skip.
+*/
+function resolveLinters(opts) {
+	const order = Object.keys(LINTERS);
+	if (opts.explicit && opts.explicit.length > 0) {
+		const unknown = opts.explicit.filter((n) => !LINTER_NAMES.has(n));
+		if (unknown.length > 0) throw new Error(`unknown linter${unknown.length > 1 ? "s" : ""} ${unknown.map((n) => `"${n}"`).join(", ")} — known: ${order.join(", ")}`);
+		const wanted = new Set(opts.explicit);
+		return order.filter((n) => wanted.has(n)).map((name) => ({
+			name,
+			def: LINTERS[name]
+		}));
+	}
+	const present = new Set(opts.rootFiles);
+	return order.filter((name) => {
+		const def = LINTERS[name];
+		return def.always === true || def.detect.some((f) => present.has(f));
+	}).map((name) => ({
+		name,
+		def: LINTERS[name]
+	}));
+}
+//#endregion
 //#region src/run.ts
 /**
 * `holocron run <task> [-- <passthrough>]` — run a registry task locally.
 *
 * Resolution:
 *
+*   0. task === "lint"                        → the linter aggregate (see below)
 *   1. turbo.json defines the task            → `turbo run <task>`
 *   2. package.json has a `<task>` script     → `<pm> run <task>`
 *      (unless it's the `holocron run …` thin caller — that recurses)
 *   3. TASKS[task].local resolves             → `<tool> <args> <org-flags> <passthrough>`
 *   4. known task, nothing to run             → "no <task> task" (exit 0, or 1 with --required)
 *   5. unknown task                           → "unknown task" (exit 1)
+*
+* `lint` runs the resolved linter set (`config.tasks` `linters`, else
+* auto-detected): the eslint slot goes through the standard turbo / script /
+* `eslint .` resolution (so turbo caching is kept); every other linter runs
+* its `localBin` when found on PATH. Missing tools are flagged; the exit code
+* is the worst of the lot.
 */
-function runTask(input) {
-	const { print, logger, exec, readFile, fileExists, listDir, task, cwd } = input;
-	const passthrough = input.passthrough ?? [];
+/** The per-command runner — `runTask` and `runLintAggregate` share it. */
+function makeRunOne(input) {
+	const { print, logger, exec, task, cwd } = input;
 	const dryRun = input.dryRun ?? false;
-	const run = (cmd, args) => {
+	return (cmd, args) => {
 		const command = [cmd, ...args].join(" ");
 		if (dryRun) {
 			print(`would run: ${command}`);
@@ -97,6 +232,12 @@ function runTask(input) {
 			...status === "fail" ? { message: `\`${command}\` exited ${exitCode}` } : {}
 		};
 	};
+}
+function runTask(input) {
+	const { print, logger, readFile, fileExists, listDir, task, cwd } = input;
+	const passthrough = input.passthrough ?? [];
+	const run = makeRunOne(input);
+	if (task === "lint") return runLintAggregate(input);
 	if (turboDefinesTask(cwd, task, readFile, fileExists)) {
 		const args = [
 			"run",
@@ -150,6 +291,85 @@ function runTask(input) {
 		message: `unknown task "${task}"`
 	};
 }
+/**
+* `holocron run lint` — the resolved linter set, run natively. The eslint
+* slot reuses turbo / the `lint` script / `eslint .`; the rest run their
+* `localBin` when it resolves on PATH. Worst exit code wins.
+*/
+function runLintAggregate(input) {
+	const { print, logger, readFile, fileExists, listDir, lookPath, cwd } = input;
+	const passthrough = input.passthrough ?? [];
+	const dryRun = input.dryRun ?? false;
+	const runOne = makeRunOne(input);
+	const pass = passthrough.length ? ["--", ...passthrough] : [];
+	let rootFiles;
+	try {
+		rootFiles = listDir(cwd);
+	} catch {
+		rootFiles = [];
+	}
+	const resolved = resolveLinters({
+		explicit: input.linters,
+		rootFiles
+	});
+	const reports = [];
+	/** Run one linter's `localBin` natively, or flag it. */
+	const runLinter = (name, bin, args, hint) => {
+		if (!bin) {
+			print(`· ${name} (CI only)`);
+			return;
+		}
+		const found = lookPath(cwd, bin);
+		if (!found) {
+			print(`! ${name} — ${bin} not on PATH${hint ? `. ${hint}` : ""} (enforced in CI)`);
+			return;
+		}
+		reports.push(runOne(found, [...args, ...passthrough]));
+	};
+	if (resolved.some((r) => r.name === "eslint")) {
+		const script = packageJsonScript(cwd, "lint", readFile, fileExists);
+		if (turboDefinesTask(cwd, "lint", readFile, fileExists)) reports.push(runOne(resolveBin(cwd, "turbo", fileExists), [
+			"run",
+			"lint",
+			...pass
+		]));
+		else if (script && !/^holocron run\b/.test(script.trim())) reports.push(runOne(packageManager(cwd, readFile, fileExists), [
+			"run",
+			"lint",
+			...pass
+		]));
+		else runLinter("eslint", "eslint", ["."]);
+	}
+	for (const { name, def } of resolved) {
+		if (name === "eslint") continue;
+		runLinter(name, def.localBin, def.localArgs ?? [], def.installHint);
+	}
+	if (reports.length === 0) {
+		const msg = "no lint tooling available locally — every resolved linter is CI-only here";
+		print(input.required ? `✗ ${msg} (required)` : `· ${msg}`);
+		logger[input.required ? "warn" : "debug"]({
+			task: "lint",
+			status: input.required ? "fail" : "skip"
+		}, "run: lint");
+		return {
+			status: input.required ? "fail" : "skip",
+			message: msg
+		};
+	}
+	const command = reports.map((r) => r.command).filter((c) => Boolean(c)).join(" && ");
+	if (dryRun) return {
+		status: "dry-run",
+		command
+	};
+	return reports.some((r) => r.status === "fail") ? {
+		status: "fail",
+		command,
+		message: "one or more linters failed"
+	} : {
+		status: "ok",
+		command
+	};
+}
 const mkRunner = (tool, args = []) => ({
 	tool,
 	args
@@ -203,136 +423,6 @@ function packageJsonScript(cwd, task, readFile, fileExists) {
 	}
 }
 //#endregion
-//#region src/linters.ts
-/**
-* Known linters, in execution order. `always` entries are the current
-* hard-coded super-linter baseline; `prettier` is always-on because the org
-* applies it universally (super-linter only lints files that exist).
-*/
-const LINTERS = {
-	eslint: {
-		validate: ["VALIDATE_JAVASCRIPT_ES", "VALIDATE_TYPESCRIPT_ES"],
-		localBin: "eslint",
-		localArgs: ["."],
-		detect: [
-			"eslint.config.ts",
-			"eslint.config.js",
-			"eslint.config.mjs",
-			"eslint.config.cjs",
-			".eslintrc",
-			".eslintrc.json",
-			".eslintrc.yml",
-			".eslintrc.yaml",
-			".eslintrc.cjs"
-		],
-		configInput: "eslint-config"
-	},
-	prettier: {
-		validate: [
-			"VALIDATE_JAVASCRIPT_PRETTIER",
-			"VALIDATE_JSX_PRETTIER",
-			"VALIDATE_TYPESCRIPT_PRETTIER",
-			"VALIDATE_TSX",
-			"VALIDATE_MARKDOWN_PRETTIER"
-		],
-		fix: [
-			"FIX_JAVASCRIPT_PRETTIER",
-			"FIX_JSX_PRETTIER",
-			"FIX_TYPESCRIPT_PRETTIER",
-			"FIX_TSX",
-			"FIX_MARKDOWN_PRETTIER"
-		],
-		always: true,
-		localBin: "prettier",
-		localArgs: ["--check", "."],
-		configInput: "prettier-config"
-	},
-	yamllint: {
-		validate: ["VALIDATE_YAML"],
-		always: true,
-		localBin: "yamllint",
-		localArgs: ["."],
-		installHint: "brew install yamllint",
-		configInput: "yaml-config"
-	},
-	actionlint: {
-		validate: ["VALIDATE_GITHUB_ACTIONS"],
-		always: true,
-		localBin: "actionlint",
-		localArgs: [],
-		installHint: "brew install actionlint"
-	},
-	gitleaks: {
-		validate: ["VALIDATE_GITLEAKS"],
-		always: true,
-		localBin: "gitleaks",
-		localArgs: ["dir", "--no-banner"],
-		installHint: "brew install gitleaks"
-	},
-	editorconfig: {
-		validate: ["VALIDATE_EDITORCONFIG"],
-		always: true,
-		localBin: "editorconfig-checker",
-		localArgs: [],
-		installHint: "brew install editorconfig-checker"
-	},
-	commitlint: {
-		validate: ["VALIDATE_GIT_COMMITLINT"],
-		always: true,
-		localBin: "commitlint",
-		localArgs: ["--last"]
-	},
-	"git-merge-conflict-markers": {
-		validate: ["VALIDATE_GIT_MERGE_CONFLICT_MARKERS"],
-		always: true
-	},
-	markdownlint: {
-		validate: ["VALIDATE_MARKDOWN"],
-		localBin: "markdownlint-cli2",
-		localArgs: ["**/*.md"],
-		detect: [
-			".markdownlint.json",
-			".markdownlint.jsonc",
-			".markdownlint.yaml",
-			".markdownlint.yml",
-			".markdownlint-cli2.jsonc",
-			".markdownlint-cli2.yaml",
-			".markdownlint-cli2.mjs"
-		]
-	}
-};
-/** Every linter name the registry knows. */
-const LINTER_NAMES = new Set(Object.keys(LINTERS));
-/**
-* Resolve the linter set for a repo. An `explicit` list (from
-* `config.tasks`) wins verbatim; otherwise every `always` linter plus every
-* linter whose `detect` filenames are present at the repo root. Result is
-* ordered by {@link LINTERS} declaration order.
-*
-* @throws when an `explicit` name is not in the registry — a typo is a
-* config bug, not a linter to silently skip.
-*/
-function resolveLinters(opts) {
-	const order = Object.keys(LINTERS);
-	if (opts.explicit && opts.explicit.length > 0) {
-		const unknown = opts.explicit.filter((n) => !LINTER_NAMES.has(n));
-		if (unknown.length > 0) throw new Error(`unknown linter${unknown.length > 1 ? "s" : ""} ${unknown.map((n) => `"${n}"`).join(", ")} — known: ${order.join(", ")}`);
-		const wanted = new Set(opts.explicit);
-		return order.filter((n) => wanted.has(n)).map((name) => ({
-			name,
-			def: LINTERS[name]
-		}));
-	}
-	const present = new Set(opts.rootFiles);
-	return order.filter((name) => {
-		const def = LINTERS[name];
-		return def.always === true || def.detect.some((f) => present.has(f));
-	}).map((name) => ({
-		name,
-		def: LINTERS[name]
-	}));
-}
-//#endregion
 //#region src/super-linter.ts
 /**
 * `superLinterConfig()` — turn the resolved linter set into the exact
@@ -676,6 +766,13 @@ const realExec = (cmd, args, opts) => {
 		stdio: "inherit"
 	}).status ?? -1 };
 };
+/** `node_modules/.bin/<bin>`, else the first `PATH` entry that has it, else `null`. */
+const realLookPath = (cwd, bin) => {
+	const local = join(cwd, "node_modules", ".bin", bin);
+	if (existsSync(local)) return local;
+	for (const dir of (process.env["PATH"] ?? "").split(":")) if (dir && existsSync(join(dir, bin))) return join(dir, bin);
+	return null;
+};
 function createAstromech(options) {
 	const deps = {
 		print: options.print ?? ((line) => console.log(line)),
@@ -683,7 +780,8 @@ function createAstromech(options) {
 		exec: options.exec ?? realExec,
 		readFile: options.readFile ?? ((path) => readFileSync(path, "utf8")),
 		fileExists: options.fileExists ?? ((path) => existsSync(path)),
-		listDir: options.listDir ?? ((path) => readdirSync(path))
+		listDir: options.listDir ?? ((path) => readdirSync(path)),
+		lookPath: options.lookPath ?? realLookPath
 	};
 	const items = () => (options.config?.tasks ?? []).map((i) => normalizeTaskEntry(i));
 	const rootFiles = () => {
@@ -701,7 +799,8 @@ function createAstromech(options) {
 			cwd: options.cwd,
 			passthrough: opts.passthrough ?? [],
 			dryRun: opts.dryRun ?? false,
-			required: opts.required ?? false
+			required: opts.required ?? false,
+			...task === "lint" ? { linters: lintEntry()?.linters } : {}
 		}),
 		thinCallers: () => {
 			const orgCtx = options.orgContext ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/astromech",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "The Holocron task runner — one task manifest drives `holocron run`, `holocron ci`, the CI workflows, package.json scripts, linters, and required checks.",
   "keywords": [
     "ci",
@@ -37,7 +37,7 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/datapad": "4.5.0"
+    "@theholocron/datapad": "4.6.0"
   },
   "devDependencies": {
     "@theholocron/eslint-config": "^8.0.0",
@@ -53,7 +53,7 @@
     "tsdown": "^0.22.14",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/rollup-plugin-transform-template": "4.5.0"
+    "@theholocron/rollup-plugin-transform-template": "4.6.0"
   },
   "engines": {
     "node": ">=22"