@theholocron/astromech 4.4.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";
@@ -56,6 +67,63 @@ interface RunTaskReport {
 }
 declare function runTask(input: RunTaskInput): RunTaskReport;
 //#endregion
+//#region src/super-linter.d.ts
+/**
+ * `superLinterConfig()` — turn the resolved linter set into the exact
+ * super-linter `VALIDATE_*` / `FIX_*` env the CI `lint` job needs. The CLI
+ * serializes {@link SuperLinterConfig.env} as the `super-linter-env` input
+ * on each repo's generated `lint` thin caller; the reusable workflow
+ * expands it verbatim. This is the CI half of "lint parity" — the local
+ * half is the `holocron run lint` aggregate, driven by the same
+ * {@link resolveLinters}.
+ */
+interface SuperLinterConfig {
+  /**
+   * Enabled `VALIDATE_*` / `FIX_*` keys → `"true"`. Only enabled keys are
+   * present (super-linter allow-list mode). Ready for `JSON.stringify`.
+   */
+  env: Record<string, string>;
+  /** Resolved linter names in execution order — for the human-readable comment. */
+  linters: string[];
+  /** Config-file inputs the resolved set honors (`eslint-config`, …). */
+  configInputs: Partial<Record<"eslint-config" | "prettier-config" | "yaml-config", true>>;
+}
+/**
+ * Resolve the super-linter env for a repo's `lint` task.
+ *
+ * @param opts.explicit  the task's `linters` list, if any (else auto-detect)
+ * @param opts.rootFiles  repo-root filenames (from `listDir(cwd)`)
+ * @param opts.includeFix  emit `FIX_*` keys too (default `true`)
+ */
+declare function superLinterConfig(opts: {
+  explicit?: string[];
+  rootFiles: string[];
+  includeFix?: boolean;
+}): SuperLinterConfig;
+/**
+ * The always-on baseline env — every `always` linter, no detection. This is
+ * what the reusable `lint.yml`'s `super-linter-env` input defaults to, so a
+ * repo whose thin caller has not been re-synced yet behaves exactly as before.
+ */
+declare function baselineSuperLinterEnv(): Record<string, string>;
+/**
+ * The `lint` thin caller's `with:` overrides + the `# linters: …` comment,
+ * from the resolved linter set. Shared by `createAstromech().thinCallers()`
+ * and the CLI's `sync` / `setup` workflow writers so the three stay in step.
+ *
+ * @param opts.explicit  the `lint` task's `linters` list, if any
+ * @param opts.rootFiles  repo-root filenames (auto-detect fallback)
+ * @param opts.extra  per-repo `with:` overrides that win over the defaults
+ */
+declare function lintThinCallerWith(opts: {
+  explicit?: string[];
+  rootFiles: string[];
+  extra?: Record<string, unknown>;
+}): {
+  withOverrides: Record<string, unknown>;
+  comments: Record<string, string>;
+};
+//#endregion
 //#region src/thin-callers.d.ts
 /**
  * Workflow templates + thin-caller generation.
@@ -92,7 +160,13 @@ declare function generateThinCallerContent(name: string, withOverrides?: Record<
 /** Optional sink for the "could not inject `with:`" warning. */
 logger?: {
   warn(obj: Record<string, unknown>, msg: string): void;
-}): string;
+},
+/**
+ * `with:` key → a `# comment` line rendered immediately above that entry.
+ * Only honored when injecting a fresh `with:` block (no template today
+ * ships one), which is the path `lint` takes.
+ */
+comments?: Record<string, string>): string;
 interface PreviewConfig {
   /** Cloudflare Pages project name shared across all repos for previews. */
   project: string;
@@ -179,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. */
@@ -206,6 +282,14 @@ interface Astromech {
    * when there is no config or `syncScripts: false`.
    */
   packageScripts(): Record<string, string>;
+  /**
+   * The resolved super-linter env for this repo's `lint` task — the CI half
+   * of lint parity. `thinCallers()` already bakes `env` into the `lint` thin
+   * caller's `super-linter-env` input; this method exposes the full result
+   * for `holocron doctor` / diagnostics. Driven by the `lint` entry's
+   * `linters` list, else auto-detection from the repo's config files.
+   */
+  superLinterConfig(): SuperLinterConfig;
 }
 declare function createAstromech(options: AstromechOptions): Astromech;
 //#endregion
@@ -324,44 +408,4 @@ declare const TASKS: Record<string, TaskDef>;
 /** Every task name the registry knows. */
 declare const KNOWN_TASKS: Set<string>;
 //#endregion
-//#region src/super-linter.d.ts
-/**
- * `superLinterConfig()` — turn the resolved linter set into the exact
- * super-linter `VALIDATE_*` / `FIX_*` env the CI `lint` job needs. The CLI
- * serializes {@link SuperLinterConfig.env} as the `super-linter-env` input
- * on each repo's generated `lint` thin caller; the reusable workflow
- * expands it verbatim. This is the CI half of "lint parity" — the local
- * half is the `holocron run lint` aggregate, driven by the same
- * {@link resolveLinters}.
- */
-interface SuperLinterConfig {
-  /**
-   * Enabled `VALIDATE_*` / `FIX_*` keys → `"true"`. Only enabled keys are
-   * present (super-linter allow-list mode). Ready for `JSON.stringify`.
-   */
-  env: Record<string, string>;
-  /** Resolved linter names in execution order — for the human-readable comment. */
-  linters: string[];
-  /** Config-file inputs the resolved set honors (`eslint-config`, …). */
-  configInputs: Partial<Record<"eslint-config" | "prettier-config" | "yaml-config", true>>;
-}
-/**
- * Resolve the super-linter env for a repo's `lint` task.
- *
- * @param opts.explicit  the task's `linters` list, if any (else auto-detect)
- * @param opts.rootFiles  repo-root filenames (from `listDir(cwd)`)
- * @param opts.includeFix  emit `FIX_*` keys too (default `true`)
- */
-declare function superLinterConfig(opts: {
-  explicit?: string[];
-  rootFiles: string[];
-  includeFix?: boolean;
-}): SuperLinterConfig;
-/**
- * The always-on baseline env — every `always` linter, no detection. This is
- * what the reusable `lint.yml`'s `super-linter-env` input defaults to, so a
- * repo whose thin caller has not been re-synced yet behaves exactly as before.
- */
-declare function baselineSuperLinterEnv(): Record<string, string>;
-//#endregion
-export { type Astromech, type AstromechOptions, type ExecFn, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, type LinterDef, type LocalRunner, type OrgContext, type PreviewConfig, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, type SuperLinterConfig, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith, resolveLinters, runTask, superLinterConfig };
+export { type Astromech, type AstromechOptions, type ExecFn, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, type LinterDef, type LocalRunner, type OrgContext, type PreviewConfig, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, type SuperLinterConfig, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, resolveLinters, runTask, superLinterConfig };

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,6 +423,74 @@ function packageJsonScript(cwd, task, readFile, fileExists) {
 	}
 }
 //#endregion
+//#region src/super-linter.ts
+/**
+* `superLinterConfig()` — turn the resolved linter set into the exact
+* super-linter `VALIDATE_*` / `FIX_*` env the CI `lint` job needs. The CLI
+* serializes {@link SuperLinterConfig.env} as the `super-linter-env` input
+* on each repo's generated `lint` thin caller; the reusable workflow
+* expands it verbatim. This is the CI half of "lint parity" — the local
+* half is the `holocron run lint` aggregate, driven by the same
+* {@link resolveLinters}.
+*/
+/**
+* Resolve the super-linter env for a repo's `lint` task.
+*
+* @param opts.explicit  the task's `linters` list, if any (else auto-detect)
+* @param opts.rootFiles  repo-root filenames (from `listDir(cwd)`)
+* @param opts.includeFix  emit `FIX_*` keys too (default `true`)
+*/
+function superLinterConfig(opts) {
+	const includeFix = opts.includeFix ?? true;
+	const resolved = resolveLinters({
+		explicit: opts.explicit,
+		rootFiles: opts.rootFiles
+	});
+	const env = {};
+	const configInputs = {};
+	for (const { def } of resolved) {
+		for (const key of def.validate) env[key] = "true";
+		if (includeFix) for (const key of def.fix ?? []) env[key] = "true";
+		if (def.configInput) configInputs[def.configInput] = true;
+	}
+	return {
+		env,
+		linters: resolved.map((r) => r.name),
+		configInputs
+	};
+}
+/**
+* The always-on baseline env — every `always` linter, no detection. This is
+* what the reusable `lint.yml`'s `super-linter-env` input defaults to, so a
+* repo whose thin caller has not been re-synced yet behaves exactly as before.
+*/
+function baselineSuperLinterEnv() {
+	return superLinterConfig({ rootFiles: [] }).env;
+}
+/**
+* The `lint` thin caller's `with:` overrides + the `# linters: …` comment,
+* from the resolved linter set. Shared by `createAstromech().thinCallers()`
+* and the CLI's `sync` / `setup` workflow writers so the three stay in step.
+*
+* @param opts.explicit  the `lint` task's `linters` list, if any
+* @param opts.rootFiles  repo-root filenames (auto-detect fallback)
+* @param opts.extra  per-repo `with:` overrides that win over the defaults
+*/
+function lintThinCallerWith(opts) {
+	const sl = superLinterConfig({
+		explicit: opts.explicit,
+		rootFiles: opts.rootFiles
+	});
+	return {
+		withOverrides: {
+			"enable-auto-commit": true,
+			"super-linter-env": JSON.stringify(sl.env),
+			...opts.extra ?? {}
+		},
+		comments: { "super-linter-env": `linters: ${sl.linters.join(", ")}` }
+	};
+}
+//#endregion
 //#region src/thin-callers.ts
 /**
 * Workflow templates + thin-caller generation.
@@ -255,7 +543,7 @@ const WORKFLOW_CHECK_CONTEXTS = {
 * If neither pattern matches the template, a warning is emitted and the
 * base template is returned unchanged.
 */
-function generateThinCallerContent(name, withOverrides, additionalPaths, logger) {
+function generateThinCallerContent(name, withOverrides, additionalPaths, logger, comments) {
 	const base = WORKFLOW_TEMPLATES[name];
 	if (!base) return "";
 	const yamlScalar = (v) => {
@@ -264,7 +552,10 @@ function generateThinCallerContent(name, withOverrides, additionalPaths, logger)
 		const s = String(v);
 		return s.startsWith("[") || s.startsWith("{") ? `'${s}'` : s;
 	};
-	const fmt = (k, v) => `      ${k}: ${yamlScalar(v)}`;
+	const fmt = (k, v) => {
+		const line = `      ${k}: ${yamlScalar(v)}`;
+		return comments?.[k] ? `      # ${comments[k]}\n${line}` : line;
+	};
 	let result = base;
 	if (additionalPaths && additionalPaths.length > 0) {
 		const pathsBlockRe = /( {4}paths:\n)((?:[ ]{6}- [^\n]+\n)+)/;
@@ -282,7 +573,7 @@ function generateThinCallerContent(name, withOverrides, additionalPaths, logger)
 	const withBlockRe = /( {4}with:\n)((?:[ ]{6}[^\n]+\n)*)/;
 	const existingMatch = result.match(withBlockRe);
 	if (existingMatch) {
-		const existingEntries = new Map(existingMatch[2].split("\n").filter(Boolean).map((line) => {
+		const existingEntries = new Map(existingMatch[2].split("\n").filter(Boolean).filter((line) => !line.trim().startsWith("#")).map((line) => {
 			const m = line.match(/^ {6}([^:]+):\s*(.*)/);
 			return m ? [m[1].trim(), m[2].trim()] : null;
 		}).filter((e) => e !== null));
@@ -475,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)),
@@ -482,9 +780,18 @@ 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 = () => {
+		try {
+			return deps.listDir(options.cwd);
+		} catch {
+			return [];
+		}
+	};
+	const lintEntry = () => items().filter((e) => e.name === "lint").at(-1);
 	return {
 		run: (task, opts = {}) => runTask({
 			...deps,
@@ -492,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 ?? {};
@@ -501,10 +809,17 @@ function createAstromech(options) {
 				if (entry.ci === false || !KNOWN_WORKFLOWS.has(entry.name)) continue;
 				const rawWith = entry.with;
 				const normalized = rawWith ? normalizeWorkflowWith(rawWith) : void 0;
-				const withOverrides = entry.name === "lint" ? {
-					"enable-auto-commit": true,
-					...normalized ?? {}
-				} : normalized;
+				let withOverrides = normalized;
+				let comments;
+				if (entry.name === "lint") {
+					const lint = lintThinCallerWith({
+						explicit: entry.linters,
+						rootFiles: rootFiles(),
+						extra: normalized
+					});
+					withOverrides = lint.withOverrides;
+					comments = lint.comments;
+				}
 				const additionalPaths = entry.paths ?? (entry.name === "deploy" && rawWith ? deriveDeployPaths(rawWith) : void 0);
 				if (entry.name === "deploy" && rawWith) {
 					const preview = extractPreviewConfig(rawWith, orgCtx);
@@ -515,7 +830,7 @@ function createAstromech(options) {
 						continue;
 					}
 				}
-				out.set(`${entry.name}.yml`, generateThinCallerContent(entry.name, withOverrides, additionalPaths, deps.logger));
+				out.set(`${entry.name}.yml`, generateThinCallerContent(entry.name, withOverrides, additionalPaths, deps.logger, comments));
 			}
 			return out;
 		},
@@ -528,183 +843,12 @@ function createAstromech(options) {
 				out[entry.name] = `holocron run ${entry.name}`;
 			}
 			return out;
-		}
-	};
-}
-//#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
-* super-linter `VALIDATE_*` / `FIX_*` env the CI `lint` job needs. The CLI
-* serializes {@link SuperLinterConfig.env} as the `super-linter-env` input
-* on each repo's generated `lint` thin caller; the reusable workflow
-* expands it verbatim. This is the CI half of "lint parity" — the local
-* half is the `holocron run lint` aggregate, driven by the same
-* {@link resolveLinters}.
-*/
-/**
-* Resolve the super-linter env for a repo's `lint` task.
-*
-* @param opts.explicit  the task's `linters` list, if any (else auto-detect)
-* @param opts.rootFiles  repo-root filenames (from `listDir(cwd)`)
-* @param opts.includeFix  emit `FIX_*` keys too (default `true`)
-*/
-function superLinterConfig(opts) {
-	const includeFix = opts.includeFix ?? true;
-	const resolved = resolveLinters({
-		explicit: opts.explicit,
-		rootFiles: opts.rootFiles
-	});
-	const env = {};
-	const configInputs = {};
-	for (const { def } of resolved) {
-		for (const key of def.validate) env[key] = "true";
-		if (includeFix) for (const key of def.fix ?? []) env[key] = "true";
-		if (def.configInput) configInputs[def.configInput] = true;
-	}
-	return {
-		env,
-		linters: resolved.map((r) => r.name),
-		configInputs
+		},
+		superLinterConfig: () => superLinterConfig({
+			explicit: lintEntry()?.linters,
+			rootFiles: rootFiles()
+		})
 	};
 }
-/**
-* The always-on baseline env — every `always` linter, no detection. This is
-* what the reusable `lint.yml`'s `super-linter-env` input defaults to, so a
-* repo whose thin caller has not been re-synced yet behaves exactly as before.
-*/
-function baselineSuperLinterEnv() {
-	return superLinterConfig({ rootFiles: [] }).env;
-}
 //#endregion
-export { KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith, resolveLinters, runTask, superLinterConfig };
+export { KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, resolveLinters, runTask, superLinterConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/astromech",
-  "version": "4.4.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.4.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.4.0"
+    "@theholocron/rollup-plugin-transform-template": "4.6.0"
   },
   "engines": {
     "node": ">=22"