@theholocron/astromech 4.2.0 → 4.3.0

package/README.md

@@ -104,6 +104,43 @@ there is no config.
 `holocron run` itself does not read the config yet — that (and
 `holocron ci`) come in later phases (epic #581).
 
+## Lint parity
+
+One linter list drives both CI and local — no asymmetry. Source: the
+`lint` task's `linters` array, or auto-detection from the config files
+present. The `linter name → super-linter VALIDATE_* keys` mapping lives in
+one place, `src/linters.ts`.
+
+| linter                       | `VALIDATE_*`                              | always-on                           | local binary                             |
+| ---------------------------- | ----------------------------------------- | ----------------------------------- | ---------------------------------------- |
+| `eslint`                     | `JAVASCRIPT_ES`, `TYPESCRIPT_ES`          | on `eslint.config.*` / `.eslintrc*` | `eslint .`                               |
+| `prettier`                   | `*_PRETTIER` (JS/JSX/TS/TSX/MD) + `FIX_*` | yes                                 | `prettier --check .`                     |
+| `yamllint`                   | `YAML`                                    | yes                                 | `yamllint .` (usually CI-only)           |
+| `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`                      |
+| `git-merge-conflict-markers` | `GIT_MERGE_CONFLICT_MARKERS`              | yes                                 | — (CI only)                              |
+| `markdownlint`               | `MARKDOWN`                                | on `.markdownlint*`                 | `markdownlint-cli2`                      |
+
+```ts
+import { superLinterConfig, resolveLinters } from "@theholocron/astromech";
+
+superLinterConfig({ explicit: ["eslint", "prettier"], rootFiles: fs.readdirSync(cwd) });
+// → { env: { VALIDATE_JAVASCRIPT_ES: "true", … }, linters: ["eslint","prettier"], configInputs: { … } }
+```
+
+`superLinterConfig().env` is the exact `VALIDATE_*`/`FIX_*` map the CI
+`lint` job needs — the CLI serializes it as the `super-linter-env` input on
+each repo's generated `lint` thin caller. Setting any `VALIDATE_*` puts
+super-linter in allow-list mode, so emitting only the enabled keys makes it
+run exactly the resolved set.
+
+`holocron run lint` (later phase) runs the same set natively: `turbo run
+lint` for the eslint portion (cached), then each other linter whose binary
+resolves; linters with a binary that is not on `PATH` are flagged with an
+install hint; the rest print "CI only".
+
 ## Development
 
 | Script               | Description             |

package/dist/index.d.mts

@@ -209,6 +209,73 @@ interface Astromech {
 }
 declare function createAstromech(options: AstromechOptions): Astromech;
 //#endregion
+//#region src/linters.d.ts
+/**
+ * The linter registry — one list of linter names (from `config.tasks`'
+ * `{ name: "lint", linters: [...] }`, or auto-detected) maps to both the
+ * CI super-linter `VALIDATE_*` env and the native local run. This table is
+ * the single source of truth for that mapping; {@link superLinterConfig}
+ * (CI) and the `holocron run lint` aggregate (local) both read it.
+ *
+ * Spec: `.notes/tech-astromech-task-runner.spec.md` "Lint parity".
+ */
+interface LinterDef {
+  /**
+   * super-linter `VALIDATE_*` keys this linter turns on. Setting any
+   * `VALIDATE_*` puts super-linter in allow-list mode, so emitting only the
+   * enabled keys makes it run exactly this set.
+   */
+  validate: string[];
+  /** super-linter `FIX_*` keys (auto-commit / `--write` parity). */
+  fix?: string[];
+  /**
+   * Local binary, resolved from `node_modules/.bin` then `PATH`. Absent →
+   * the linter has no meaningful local run (`holocron run lint` prints
+   * "CI only"); CI still enforces it.
+   */
+  localBin?: string;
+  /** Args for `localBin` in CHECK mode — never `--write` / `--fix`. */
+  localArgs?: string[];
+  /**
+   * Shown by `holocron run lint` when `localBin` is set but not found on
+   * PATH — the "you're missing a tool the repo needs" nudge.
+   */
+  installHint?: string;
+  /**
+   * Repo-root filenames that auto-enable this linter when the `lint` task
+   * has no explicit `linters` list. Ignored when {@link always} is set.
+   */
+  detect?: string[];
+  /** Enabled regardless of detection (the org baseline). */
+  always?: boolean;
+  /** Reusable-workflow config-file input this linter honors, if any. */
+  configInput?: "eslint-config" | "prettier-config" | "yaml-config";
+}
+/**
+ * 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).
+ */
+declare const LINTERS: Record<string, LinterDef>;
+/** Every linter name the registry knows. */
+declare const LINTER_NAMES: ReadonlySet<string>;
+/**
+ * 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.
+ */
+declare function resolveLinters(opts: {
+  explicit?: string[];
+  rootFiles: string[];
+}): Array<{
+  name: string;
+  def: LinterDef;
+}>;
+//#endregion
 //#region src/registry.d.ts
 /**
  * The task registry — how each task runs *locally*, without GitHub
@@ -246,9 +313,55 @@ interface TaskDef {
   }>;
   /** Org-default flags injected by tool name. Removed by a repo override. */
   flags?: Record<string, string[]>;
+  /**
+   * This task is the linter aggregate: `holocron run lint` resolves the
+   * linter set (`config.tasks` `linters` or auto-detect) and runs each
+   * natively instead of using `local`. See `linters.ts` / `super-linter.ts`.
+   */
+  linters?: boolean;
 }
 declare const TASKS: Record<string, TaskDef>;
 /** Every task name the registry knows. */
 declare const KNOWN_TASKS: Set<string>;
 //#endregion
-export { type Astromech, type AstromechOptions, type ExecFn, KNOWN_TASKS, KNOWN_WORKFLOWS, type LocalRunner, type OrgContext, type PreviewConfig, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith, runTask };
+//#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 };

package/dist/index.mjs

@@ -15,10 +15,13 @@ const TASKS = {
 		tool: "tsc",
 		args: ["--noEmit"]
 	} },
-	lint: { local: {
-		tool: "eslint",
-		args: ["."]
-	} },
+	lint: {
+		local: {
+			tool: "eslint",
+			args: ["."]
+		},
+		linters: true
+	},
 	build: { local: { detect: [
 		{
 			when: /^tsdown\.config\.(ts|js|mjs|cjs)$/,
@@ -529,4 +532,179 @@ function createAstromech(options) {
 	};
 }
 //#endregion
-export { KNOWN_TASKS, KNOWN_WORKFLOWS, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith, runTask };
+//#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
+	};
+}
+/**
+* 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/astromech",
-  "version": "4.2.0",
+  "version": "4.3.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.2.0"
+    "@theholocron/datapad": "4.3.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.2.0"
+    "@theholocron/rollup-plugin-transform-template": "4.3.0"
   },
   "engines": {
     "node": ">=22"