@theholocron/astromech 4.19.0 → 5.0.0-alpha.11

package/dist/index.d.mts

@@ -1,32 +1,33 @@
-import { r as TasksConfig } from "./schema-BegK4MsY.mjs";
+import { r as TasksConfig } from "./schema-D01VYg43.mjs";
 //#region src/run.d.ts
 /**
  * `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.
+ * A `job` argument only applies to tasks that declare `jobs`; for any other
+ * task it is folded back into the passthrough (`holocron run delivery.build
+ * src/`).
  *
  * Resolution:
  *
- *   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>`
+ *   3b. TASKS[task].linterGroup               → run each resolved linter natively (see below)
  *   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 /
- * `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.
+ * A `linterGroup` task (`sourceQuality.staticAnalysis`, etc.) runs its fixed
+ * set of `linters.ts` entries, each still gated by that linter's own
+ * `detect`/`always` rule — every entry runs its `localBin` natively when
+ * found on PATH. Missing tools are flagged; the exit code is the worst of
+ * the lot. Unlike the old single `lint` task, this check runs *after*
+ * turbo/`package.json` resolution (step 3b, not step 0) — a `linterGroup`
+ * task is a normal turbo-delegatable task like any other.
  */
 /** Minimal structural logger — `@theholocron/observability`'s `Logger` satisfies it. */
 interface RunLogger {
@@ -70,8 +71,6 @@ 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[];
   /** `turbo --filter=<pkg>` passthrough (monorepo). Ignored when the repo has no `turbo.json`. */
   filter?: string;
 }
@@ -107,68 +106,9 @@ interface CiReport {
 interface CiInput extends RunDeps, CiOptions {
   cwd: string;
   config: TasksConfig;
-  /** Explicit linter list for the `lint` task (the config's lint entry `linters`). */
-  linters?: string[];
 }
 declare function runCi(input: CiInput): CiReport;
 //#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.
@@ -183,10 +123,17 @@ declare const KNOWN_WORKFLOWS: Set<string>;
  * The GitHub status-check context a `required` task contributes to branch
  * protection. Format: `"{workflow name} / {job name}"`.
  *
- * These name the **aggregate `Conclusion` job** (fan-in, `if: always()`), not
- * an individual inner job — `test` has several conditionally-run sub-jobs, so
- * `"Test / Conclusion"` is the only stable gate. Only merge-gating workflows
- * are listed. `astromech.requiredChecks()` reads this for every `required` task.
+ * Most of these are single-job workflows now (D3's decomposition split what
+ * used to be multi-job `lint`/`audit` into one task per concern) — the
+ * context names that job directly, no `Conclusion` aggregator needed; a
+ * single job's own conclusion already *is* the workflow's conclusion.
+ * `Conclusion` fan-in jobs are kept only where a task genuinely has several
+ * conditionally-run jobs feeding one required check:
+ * `verification.unitTests` (unit / Storybook / Chromatic / interaction /
+ * user-flow, each gated by its own `run-*` input) and
+ * `platform.repoValidation` (its three script jobs all must pass). Only
+ * merge-gating workflows are listed. `astromech.requiredChecks()` reads this
+ * for every `required` task.
  */
 declare const WORKFLOW_CHECK_CONTEXTS: Partial<Record<string, string>>;
 /**
@@ -274,6 +221,12 @@ declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<str
  */
 declare function deriveDeployPaths(raw: Record<string, unknown>): string[];
 //#endregion
+//#region src/turbo.d.ts
+interface EnsureRootWorkspaceMemberResult {
+  content: string;
+  changed: boolean;
+}
+//#endregion
 //#region src/astromech.d.ts
 interface AstromechOptions {
   /** Repo root. */
@@ -348,14 +301,6 @@ 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;
   /**
    * The branch-protection required-status-check contexts for this repo —
    * every `required: true` task's check context plus `extraRequiredChecks`,
@@ -370,6 +315,23 @@ interface Astromech {
    * as {@link requiredChecks} — `holocron setup` owns writing the result.
    */
   codecovConfig(existing: string | null): string;
+  /**
+   * The generated `turbo.json` for this repo's manifest, pretty-printed —
+   * write directly, no merge. `null` when no manifest task has turbo fan-out
+   * config (nothing to write). See {@link TurboTaskConfig} in `registry.ts`.
+   */
+  turboConfig(): string | null;
+  /**
+   * Fixes #692: whenever {@link turboConfig} isn't `null`, this repo's root
+   * package needs to actually be a workspace member for the tasks it fans
+   * out — otherwise a root that's genuinely a directly-buildable package
+   * (not just an orchestrator) silently vanishes from `turbo run <task>`.
+   * Pass `pnpm-workspace.yaml`'s current content (or `""` if none exists —
+   * a no-op either way, since no `packages:` key means single-package mode
+   * already) and root `package.json`'s own `scripts` keys. `changed: false`
+   * means don't write anything — the file is already correct.
+   */
+  ensureRootWorkspaceMember(workspaceYaml: string, rootScripts: readonly string[]): EnsureRootWorkspaceMemberResult;
 }
 declare function createAstromech(options: AstromechOptions): Astromech;
 //#endregion
@@ -495,7 +457,19 @@ declare function resolveLinters(opts: {
  * Actions. `holocron run <task>` and `holocron ci` resolve against this;
  * adding a task here gives every repo that task.
  *
- * Keyed identically to the workflow templates — a task IS a workflow.
+ * Keyed identically to the workflow templates — a task IS a workflow. This
+ * is the canonical vocabulary table (epic #672, D11): every other artifact
+ * (`KNOWN_TASKS`, `thin-callers.ts`'s `KNOWN_WORKFLOWS`/`WORKFLOW_CHECK_CONTEXTS`,
+ * `CI_ORDER`) derives from these keys rather than hand-duplicating them —
+ * including the future GitHub App (#679), which imports this same table for
+ * config-schema validation instead of reimplementing its own copy.
+ *
+ * Task names are an intent-facing vocabulary (`verification.*`,
+ * `sourceQuality.*`, `security.*`, `delivery.*`, `platform.*`,
+ * `knowledge.*`), not tool names — `eslint`/`vitest`/`tsdown`/… stay
+ * internal to this file and `theholocron/configs`. See
+ * `.notes/tech-vocabulary-rename.spec.md` (#675) for the full mapping and
+ * the reasoning behind each namespace and decomposition.
  *
  * Spec: `docs/wiki/specifications/tech-astromech-task-runner.spec.md` (epic #581).
  */
@@ -514,40 +488,65 @@ interface LocalRunner {
   /** The task is already a holocron subcommand (`sync`, `sync-wiki`). */
   command?: string;
 }
+/**
+ * How a task fans out across every workspace via Turborepo — content-hash
+ * caching + `^`-prefixed cross-package ordering, epic #672 D9 (#681).
+ * Present only on tasks that genuinely run *per workspace* (a real build/
+ * compile/test step); whole-repo single-run tools (prettier, gitleaks,
+ * commitlint, yamllint, …) have no entry here — they stay off turbo.json
+ * entirely and run once, un-fanned-out, the way they already do.
+ */
+interface TurboTaskConfig {
+  /** Glob patterns turbo hashes to decide whether a cached run is still valid. */
+  inputs: string[];
+  /** Glob patterns turbo caches/restores after a run. Empty array for a task with no build artifact (lint, typecheck). */
+  outputs: string[];
+  /** Task names this depends on — a bare name runs in this package first; `^name` waits on every upstream workspace's task. */
+  dependsOn: 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`.
+   * The CI status-check context this job reports as (e.g.
+   * `platform.repoValidation / Validate registry consistency`) — every sub-job is a CI job.
+   * `holocron run <task>` and `holocron ci` label each job line with it;
+   * the task-level `… / Conclusion` context (only for tasks with several
+   * jobs) lives in `WORKFLOW_CHECK_CONTEXTS`.
    */
   checkContext: string;
 }
 interface TaskDef {
   /**
-   * `null` — the registry has no built-in runner (CodeQL, deploys, audit's
-   * server / baseline jobs). An explicit turbo task or `package.json` script
-   * still runs (resolution steps 1–2); with neither, `holocron run` does
-   * nothing and `holocron ci` skips it — never a failure, even when the task
-   * is `required` (a CI-only check isn't a local one).
+   * `null` — the registry has no built-in runner (CodeQL, deploys, the
+   * bundle-size job). An explicit turbo task or `package.json` script still
+   * runs (resolution steps 1–2); with neither, `holocron run` does nothing
+   * and `holocron ci` skips it — never a failure, even when the task is
+   * `required` (a CI-only check isn't a local one).
    */
   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.
+   * Sub-jobs, keyed by slug. Declared order is run order: `holocron run
+   * <task>` (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[]>;
   /**
-   * 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`.
+   * This task is a linter-group aggregate: `holocron run <task>` resolves
+   * this fixed set of `linters.ts` entries (still gated by each linter's
+   * own `detect`/`always` rule) and runs each natively, instead of using
+   * `local`. Replaces the old single `lint` task's auto-detected linter
+   * list (`config.tasks[].linters`) — a repo's choice of which of these
+   * run is now just whether it includes this task in `tasks: [...]`, same
+   * as any other task. See `linters.ts` / `run.ts`.
    */
-  linters?: boolean;
+  linterGroup?: string[];
+  /** Carries a `preview` mode (Cloudflare/Vercel deploy, npm dist-tag, Fern preview docs, …). Cross-cutting, not its own task. */
+  preview?: boolean;
+  /** Turborepo fan-out config for this task — see {@link TurboTaskConfig}. Omitted for whole-repo, non-fan-out tasks. */
+  turbo?: TurboTaskConfig;
 }
 declare const TASKS: Record<string, TaskDef>;
 /** Every task name the registry knows. */
@@ -564,6 +563,46 @@ declare const CI_ORDER: string[];
 /** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
 declare function requiredChecks(config: TasksConfig): string[];
 //#endregion
+//#region src/resolver.d.ts
+/**
+ * Resolves the absolute path to a Bucket A tool's shared `@theholocron/*-config`
+ * entry point, installed in the consuming repo's own `node_modules` — and the
+ * CLI flag(s) to hand it via (`--config`, `--extends`, …). `run.ts` splices the
+ * result into the command it builds for a tool/detect runner or a linter-group
+ * entry, right after the tool's own args.
+ *
+ * Every mapped package's resolved entry point already carries a ready-to-use
+ * default export (a plain re-export for `prettier`/`commitlint`; an invoked,
+ * zero-arg preset for `eslint`/`vitest`/`tsdown` — verified end-to-end against
+ * each tool's real `--config`/`--extends` loader, not just the file's shape).
+ * A repo doesn't need this package installed at all — every lookup degrades to
+ * `[]` (no flag added, the tool falls back to its own auto-discovery of a
+ * local file, unchanged from today) rather than throwing, so this is additive
+ * and safe to run unconditionally.
+ *
+ * `semantic-release`, `devmoji`, `editorconfig-checker`, and `knip` are
+ * deliberately absent — `semantic-release-config`'s `defineConfig()` needs
+ * real per-repo data (branches, npm options) a static `--extends <path>` can't
+ * carry; `devmoji` runs through a git hook template, not `holocron run
+ * <task>`; `editorconfig-checker` has no shared-config package yet; `knip` is
+ * repo-specific by nature, never a shared-config candidate. See
+ * `.notes/tech-config-resolution.spec.md` (#676).
+ */
+interface ResolverDeps {
+  readFile: (path: string) => string;
+  fileExists: (path: string) => boolean;
+}
+/** Every tool name the resolver knows how to point at a shared config. */
+declare const RESOLVABLE_TOOLS: ReadonlySet<string>;
+/**
+ * `<flag> <absolute path>` for `tool`, resolved against `cwd`'s
+ * `node_modules` — or `[]` when the tool isn't mapped, the package isn't
+ * installed, its `package.json` doesn't declare the export subpath this
+ * needs, or the resolved file doesn't actually exist on disk (a stale
+ * install, or a package version that predates the export existing).
+ */
+declare function resolveToolConfig(tool: string, cwd: string, deps: ResolverDeps): string[];
+//#endregion
 //#region src/reusable.d.ts
 /**
  * The **reusable** GitHub Actions surface pushed to `theholocron/.github` by
@@ -591,4 +630,73 @@ 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, 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, type WorkspacePackage, baselineSuperLinterEnv, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, reusableTemplates, runCi, runTask, superLinterConfig };
+//#region src/tsconfig.d.ts
+/**
+ * `tsconfig.json` generation — Bucket B (config-resolution workstream, #676):
+ * the file must stay committed (the TypeScript language server discovers it
+ * directly from disk, no `--config` override mechanism to hand it a path
+ * instead), but its content is fully derivable, so it's generated rather
+ * than hand-authored — the same category as `.editorconfig`
+ * ({@link "./templates/configs/editorconfig/create-config.js" createConfig})
+ * and {@link codecovConfig}.
+ *
+ * Surveyed every package-level `tsconfig.json` across the org (`holocron`,
+ * `clients`, `utils` — 20+ packages). `extends: "@theholocron/tsconfig/
+ * node-lts"`, `compilerOptions.baseUrl: "./"`, `compilerOptions.outDir:
+ * "./dist"`, `include: ["src/**\/*.ts"]`, and `exclude: ["node_modules",
+ * "dist"]` are uniform in every one — safe defaults here. `paths` (a `@/*`
+ * → `./src/*` import alias) is a real per-package choice, present in
+ * roughly 40% of packages checked — an opt-in parameter, not a default.
+ *
+ * Two fields checked and deliberately *not* absorbed as defaults, unlike
+ * `eslint-config`'s `tsconfigRootDir`/`settings.node` (which turned out
+ * redundant with the shared package's own behavior, `configs`#461):
+ * `compilerOptions.module`/`moduleResolution` (only `@theholocron/cli`
+ * overrides these, to `esnext`/`bundler` — a genuine deviation from the
+ * shared `node-lts` preset's `nodenext`/`nodenext`, needed for its bundler
+ * tooling, not something every package should inherit) and
+ * `compilerOptions.rootDir` (present in exactly two packages, always the
+ * same value `./src` that `include` already implies — an unnecessary
+ * override wherever it appears, not a pattern worth generalizing).
+ *
+ * Monorepo *root* `tsconfig.json` (a TS project-references "solution
+ * file" — `holocron`'s own root is `{ files: [], references: [...] }`,
+ * listing which packages to build) is a structurally different, genuinely
+ * per-repo document — out of scope here, same as Bucket C content.
+ *
+ * Not yet wired into `holocron setup`'s per-package write loop (every
+ * other Bucket B file there is a single repo-root file, safely
+ * overwritten every run — `tsconfig.json` is per-package, and most
+ * packages' files still carry real hand-authored content today, not yet
+ * migrated to a fully-generated state). That per-package iteration +
+ * safe-migration design is `#680`'s job, not duplicated here — this is
+ * the generator itself, ready for it to call.
+ */
+interface TsconfigOptions {
+  /** Human-readable name for the `display` field — the package's own name is the usual choice. */
+  display: string;
+  /**
+   * `@theholocron/tsconfig` variant. Defaults to `"node-lts"` — every
+   * checked package uses it; the other three (`astro`, `nextjs`, `react`)
+   * exist for a template repo's app-shaped packages, not the plain
+   * Node.js library packages this org's currently-migrated repos ship.
+   */
+  variant?: "astro" | "nextjs" | "node-lts" | "react";
+  /**
+   * Add a `@/*` → `./src/*` path alias. A real per-package choice, not a
+   * default — roughly 40% of packages checked use one, the rest don't.
+   */
+  paths?: boolean;
+}
+/**
+ * A package-level `tsconfig.json` — the uniform shape confirmed across
+ * every package checked, parameterized only by the two fields that
+ * genuinely vary (`display`, `paths`). No scaffold/workflow header (matches
+ * `.alexrc.json`'s existing precedent for a strict-JSON Bucket B file —
+ * JSON has no comment syntax to carry one, and TypeScript's own tolerance
+ * for JSONC comments in `tsconfig.json` isn't worth relying on for a file
+ * this thin).
+ */
+declare function createTsconfig(options: TsconfigOptions): string;
+//#endregion
+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, RESOLVABLE_TOOLS, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, type ResolverDeps, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, TASKS, type TaskDef, type TsconfigOptions, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, type WorkspacePackage, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, createTsconfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, resolveToolConfig, reusableTemplates, runCi, runTask };