@theholocron/astromech 4.10.3 → 4.11.0

package/dist/index.d.mts

@@ -1,18 +1,26 @@
 import { r as TasksConfig } from "./schema-BegK4MsY.mjs";
 //#region src/run.d.ts
 /**
- * `holocron run <task> [-- <passthrough>]` — run a registry task locally.
+ * `holocron run <task> [job] [-- <passthrough>]` — run a registry task (or one
+ * of its sub-jobs) locally.
+ *
+ * A `job` argument only applies to tasks that declare `jobs` (today: `audit`);
+ * for any other task it is folded back into the passthrough (`holocron run
+ * build src/`). `holocron run audit performance` runs one job; `holocron run
+ * audit` runs every job in declared order.
  *
  * Resolution:
  *
- *   0. task === "lint"                        → the linter aggregate (see below)
+ *   0. task === "lint" (no job)               → the linter aggregate (see below)
+ *   J. job given                              → TASKS[task].jobs[job].local (unknown job → exit 1)
  *   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. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
- *   4b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
- *   5. unknown task                           → "unknown task" (exit 1)
+ *   4. TASKS[task].jobs has entries           → run each job in declared order
+ *   5. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
+ *   5b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
+ *   6. 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 /
@@ -49,6 +57,11 @@ interface RunDeps {
 interface RunTaskInput extends RunDeps {
   /** Registry task name, e.g. `"test"`. */
   task: string;
+  /**
+   * Sub-job within the task, e.g. `"performance"` in `holocron run audit
+   * performance`. Ignored (folded into `passthrough`) for tasks with no `jobs`.
+   */
+  job?: string;
   /** Directory to run in. */
   cwd: string;
   /** Args after `--` on the command line, forwarded to the tool / turbo / script. */
@@ -290,6 +303,12 @@ interface AstromechOptions {
   lookPath?: (cwd: string, bin: string) => string | null;
 }
 interface RunOptions {
+  /**
+   * Sub-job within the task — `performance` in `holocron run audit
+   * performance`. Only meaningful for tasks that declare `jobs` (`audit`);
+   * ignored otherwise. Omit to run every job the task has.
+   */
+  job?: string;
   /** Args after `--`, forwarded to the tool / turbo / script. */
   passthrough?: string[];
   /** Print the resolved command without running it. */
@@ -300,7 +319,7 @@ interface RunOptions {
   filter?: string;
 }
 interface Astromech {
-  /** Run one task locally. */
+  /** Run one task — or one of its sub-jobs (`opts.job`) — locally. */
   run(task: string, opts?: RunOptions): RunTaskReport;
   /**
    * Run the merge-gating checks locally, in CI order — "will CI pass?".
@@ -439,6 +458,18 @@ interface LocalRunner {
   /** The task is already a holocron subcommand (`sync`, `sync-wiki`). */
   command?: string;
 }
+/** One sub-job of a task — `performance` in `holocron run audit performance`. */
+interface JobDef {
+  /** How the job runs locally; `null` → no local equivalent (enforced in CI). */
+  local: LocalRunner | null;
+  /**
+   * The CI status-check context this job reports as (`audit / Knip`) — every
+   * sub-job is a CI job. `holocron run audit` and `holocron ci` label each job
+   * line with it; the task-level `… / Conclusion` context lives in
+   * `WORKFLOW_CHECK_CONTEXTS`.
+   */
+  checkContext: string;
+}
 interface TaskDef {
   /**
    * `null` — the registry has no built-in runner (CodeQL, deploys, audit's
@@ -448,10 +479,11 @@ interface TaskDef {
    * is `required` (a CI-only check isn't a local one).
    */
   local: LocalRunner | null;
-  /** Sub-jobs, keyed by slug — `holocron run audit performance`. */
-  jobs?: Record<string, {
-    local: LocalRunner | null;
-  }>;
+  /**
+   * Sub-jobs, keyed by slug — `holocron run audit performance`. Declared order
+   * is run order: `holocron run audit` (no job) runs each in turn.
+   */
+  jobs?: Record<string, JobDef>;
   /** Org-default flags injected by tool name. Removed by a repo override. */
   flags?: Record<string, string[]>;
   /**
@@ -503,4 +535,4 @@ declare const WORKFLOW_TEMPLATE_PROPERTIES: Record<string, string>;
  */
 declare function reusableTemplates(): Map<string, string>;
 //#endregion
-export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type ExecFn, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, type LinterDef, type LocalRunner, type OrgContext, type PreviewConfig, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, type SuperLinterConfig, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, requiredChecks, resolveLinters, reusableTemplates, runCi, runTask, superLinterConfig };
+export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type ExecFn, type JobDef, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, type LinterDef, type LocalRunner, type OrgContext, type PreviewConfig, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, type SuperLinterConfig, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, requiredChecks, resolveLinters, reusableTemplates, runCi, runTask, superLinterConfig };

package/dist/index.mjs

@@ -45,7 +45,31 @@ const TASKS = {
 	] } },
 	sync: { local: { command: "sync" } },
 	wiki: { local: { command: "sync-wiki" } },
-	audit: { local: null },
+	audit: {
+		local: null,
+		jobs: {
+			"bundle-size": {
+				local: null,
+				checkContext: "audit / Audit the bundle size"
+			},
+			knip: {
+				local: { tool: "knip" },
+				checkContext: "audit / Knip"
+			},
+			performance: {
+				local: { detect: [{
+					when: /^lighthouse\.config\.(cjs|js|mjs|ts)$/,
+					tool: "lhci",
+					args: ["autorun"]
+				}, {
+					when: /^lighthouserc\.(cjs|js|mjs|json|yml|yaml)$/,
+					tool: "lhci",
+					args: ["autorun"]
+				}] },
+				checkContext: "audit / Audit the performance"
+			}
+		}
+	},
 	codeql: { local: null },
 	deploy: { local: null }
 };
@@ -197,18 +221,26 @@ function resolveLinters(opts) {
 //#endregion
 //#region src/run.ts
 /**
-* `holocron run <task> [-- <passthrough>]` — run a registry task locally.
+* `holocron run <task> [job] [-- <passthrough>]` — run a registry task (or one
+* of its sub-jobs) locally.
+*
+* A `job` argument only applies to tasks that declare `jobs` (today: `audit`);
+* for any other task it is folded back into the passthrough (`holocron run
+* build src/`). `holocron run audit performance` runs one job; `holocron run
+* audit` runs every job in declared order.
 *
 * Resolution:
 *
-*   0. task === "lint"                        → the linter aggregate (see below)
+*   0. task === "lint" (no job)               → the linter aggregate (see below)
+*   J. job given                              → TASKS[task].jobs[job].local (unknown job → exit 1)
 *   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. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
-*   4b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
-*   5. unknown task                           → "unknown task" (exit 1)
+*   4. TASKS[task].jobs has entries           → run each job in declared order
+*   5. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
+*   5b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
+*   6. 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 /
@@ -252,9 +284,36 @@ function makeRunOne(input) {
 }
 function runTask(input) {
 	const { print, logger, readFile, fileExists, listDir, task, cwd } = input;
-	const passthrough = input.passthrough ?? [];
+	const def = TASKS[task];
+	let job = input.job;
+	let passthrough = input.passthrough ?? [];
+	if (job !== void 0 && !def?.jobs) {
+		passthrough = [job, ...passthrough];
+		job = void 0;
+	}
+	if (job !== void 0) {
+		const jobDef = def.jobs[job];
+		if (!jobDef) {
+			const known = Object.keys(def.jobs).join(", ");
+			print(`✗ unknown job "${job}" for "${task}" (known: ${known})`);
+			logger.warn({
+				task,
+				job,
+				status: "unknown"
+			}, `run: ${task} ${job}`);
+			return {
+				status: "unknown",
+				message: `unknown job "${task} ${job}"`
+			};
+		}
+		const label = `${task} ${job}`;
+		return runUnit(input, label, jobDef.local, makeRunOne({
+			...input,
+			task: label
+		}), passthrough);
+	}
 	const run = makeRunOne(input);
-	if (task === "lint") return runLintAggregate(input);
+	if (task === "lint") return runLintAggregate(input, passthrough);
 	if (turboDefinesTask(cwd, task, readFile, fileExists)) {
 		const args = [
 			"run",
@@ -264,7 +323,6 @@ function runTask(input) {
 		];
 		return run(resolveBin(cwd, "turbo", fileExists), args);
 	}
-	const def = TASKS[task];
 	const script = packageJsonScript(cwd, task, readFile, fileExists);
 	if (script && !/^holocron run\b/.test(script.trim())) return run(packageManager(cwd, readFile, fileExists), [
 		"run",
@@ -287,6 +345,7 @@ function runTask(input) {
 			]);
 		}
 	}
+	if (def?.jobs && Object.keys(def.jobs).length > 0) return runAllJobs(input, def.jobs, passthrough);
 	if (def?.local === null) {
 		const msg = `no local equivalent for ${task} — enforced in CI`;
 		print(`· ${msg}`);
@@ -322,13 +381,94 @@ function runTask(input) {
 	};
 }
 /**
+* Run one registry unit — a task's own runner or a single sub-job. Resolution
+* is registry-only (`turbo` / `package.json` scripts are keyed by task, not
+* `task/job`). `label` names the unit in messages (`audit performance`).
+*
+* `local: null` → CI-only by design, always a skip (never a failure, even with
+* `--required`). A declared runner with no matching repo file, or whose tool
+* isn't installed locally → a skip (`--required` turns it into a failure — the
+* repo claims a check it can't back). Mirrors the lint aggregate: run what's
+* here, flag the rest, let CI enforce.
+*/
+function runUnit(input, label, local, run, passthrough) {
+	const { print, logger, listDir, lookPath, cwd } = input;
+	const skip = (msg) => {
+		print(input.required ? `✗ ${msg} (required)` : `· ${msg}`);
+		logger[input.required ? "warn" : "debug"]({
+			task: label,
+			status: input.required ? "fail" : "skip"
+		}, `run: ${label}`);
+		return {
+			status: input.required ? "fail" : "skip",
+			message: msg
+		};
+	};
+	if (local) {
+		const runner = resolveRunner(local, cwd, listDir);
+		if (!runner) return skip(`no ${label} runner for this repo`);
+		const found = lookPath(cwd, runner.tool);
+		if (!found) return skip(`${runner.tool} not installed locally for ${label} — enforced in CI`);
+		return run(found, [...runner.args, ...passthrough]);
+	}
+	const msg = `no local equivalent for ${label} — enforced in CI`;
+	print(`· ${msg}`);
+	logger.debug({
+		task: label,
+		status: "skip"
+	}, `run: ${label}`);
+	return {
+		status: "skip",
+		message: msg
+	};
+}
+/**
+* `holocron run <task>` for a task that is a container of sub-jobs (`audit`) —
+* run each job in declared order. Status precedence: any `fail` → `fail`; else
+* any `ok` → `ok`; else any `dry-run` → `dry-run`; else `skip` (nothing ran).
+*/
+function runAllJobs(input, jobs, passthrough) {
+	const { print, task } = input;
+	const perJob = {
+		...input,
+		required: false
+	};
+	const reports = [];
+	for (const [name, jobDef] of Object.entries(jobs)) {
+		const label = `${task} ${name}`;
+		print(`▶ ${jobDef.checkContext}`);
+		reports.push(runUnit(perJob, label, jobDef.local, makeRunOne({
+			...perJob,
+			task: label
+		}), passthrough));
+	}
+	const command = reports.map((r) => r.command).filter((c) => Boolean(c)).join(" && ");
+	const statuses = new Set(reports.map((r) => r.status));
+	if (statuses.has("fail")) return {
+		status: "fail",
+		command,
+		message: `one or more ${task} jobs failed`
+	};
+	if (statuses.has("ok")) return {
+		status: "ok",
+		command
+	};
+	if (statuses.has("dry-run")) return {
+		status: "dry-run",
+		command
+	};
+	return {
+		status: "skip",
+		message: `no ${task} job has a local equivalent — enforced in CI`
+	};
+}
+/**
 * `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) {
+function runLintAggregate(input, passthrough) {
 	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] : [];
@@ -1026,11 +1166,12 @@ function createAstromech(options) {
 			...deps,
 			task,
 			cwd: options.cwd,
+			...opts.job !== void 0 ? { job: opts.job } : {},
 			passthrough: opts.passthrough ?? [],
 			dryRun: opts.dryRun ?? false,
 			required: opts.required ?? false,
 			...opts.filter ? { filter: opts.filter } : {},
-			...task === "lint" ? { linters: lintEntry()?.linters } : {}
+			...task === "lint" && opts.job === void 0 ? { linters: lintEntry()?.linters } : {}
 		}),
 		ci: (opts = {}) => runCi({
 			...deps,

package/package.json

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