@theholocron/astromech 5.0.0-alpha.6 → 5.0.0-alpha.8

package/dist/index.d.mts

@@ -546,6 +546,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
@@ -573,4 +613,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, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, type WorkspacePackage, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, reusableTemplates, runCi, runTask };
+//#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 };

package/dist/index.mjs

@@ -327,6 +327,98 @@ function resolveLinters(opts) {
 	}));
 }
 //#endregion
+//#region src/resolver.ts
+/**
+* `library` is every mapped tool's org-wide default variant today — every
+* currently-migrated repo (`holocron`, `clients`, `utils`, `configs`,
+* `themes`, `observability`, `skills`) is a publishable library package, and
+* `eslint-config`/`vitest-config`/`tsdown-config` all name their
+* general-purpose preset exactly that. Picking a different variant per repo
+* (an app-type template, say) needs new `holocron.config.ts` surface this
+* doesn't add yet — deliberately out of scope until a real consumer needs it.
+*/
+const TOOL_CONFIGS = {
+	eslint: {
+		package: "@theholocron/eslint-config",
+		exportPath: "./bundles/library",
+		flag: ["--config"]
+	},
+	prettier: {
+		package: "@theholocron/prettier-config",
+		exportPath: ".",
+		flag: ["--config"]
+	},
+	vitest: {
+		package: "@theholocron/vitest-config",
+		exportPath: "./bundles/library",
+		flag: ["--config"]
+	},
+	tsdown: {
+		package: "@theholocron/tsdown-config",
+		exportPath: "./presets/library",
+		flag: ["--config"]
+	},
+	commitlint: {
+		package: "@theholocron/commitlint-config",
+		exportPath: ".",
+		flag: ["--config"]
+	}
+};
+/** Every tool name the resolver knows how to point at a shared config. */
+const RESOLVABLE_TOOLS = new Set(Object.keys(TOOL_CONFIGS));
+/**
+* `<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).
+*/
+function resolveToolConfig(tool, cwd, deps) {
+	const spec = TOOL_CONFIGS[tool];
+	if (!spec) return [];
+	const pkgDir = joinPath(cwd, "node_modules", ...spec.package.split("/"));
+	const pkgJsonPath = joinPath(pkgDir, "package.json");
+	if (!deps.fileExists(pkgJsonPath)) return [];
+	let pkg;
+	try {
+		pkg = JSON.parse(deps.readFile(pkgJsonPath));
+	} catch {
+		return [];
+	}
+	const relative = resolveExportEntry(pkg.exports?.[spec.exportPath]);
+	if (!relative) return [];
+	const absolute = joinPath(pkgDir, relative.replace(/^\.\//, ""));
+	if (!deps.fileExists(absolute)) return [];
+	return [...spec.flag, absolute];
+}
+/**
+* Unwrap a `package.json#exports` subpath entry down to its file path —
+* either a bare string, or an object with condition keys (`import`,
+* `default`, `require`, …) that may themselves nest one level (`{ import: {
+* types, default } }`, the shape every `@theholocron/*-config` package
+* actually uses). Prefers `import` (this org ships ESM), then `default`,
+* then `require` as a last resort.
+*/
+function resolveExportEntry(entry) {
+	if (typeof entry === "string") return entry;
+	if (entry === null || typeof entry !== "object") return void 0;
+	const conditions = entry;
+	const value = conditions.import ?? conditions.default ?? conditions.require;
+	if (typeof value === "string") return value;
+	if (typeof value === "object" && value !== null) return resolveExportEntry(value);
+}
+/**
+* A minimal, POSIX-safe `path.join` — avoids importing `node:path` just for
+* this. Every path in play here is either already POSIX (a `package.json`
+* `exports` value, always forward-slashed regardless of platform) or built
+* from platform-neutral segments (`cwd`, `"node_modules"`, a scoped package
+* name split on `/`), so a manual join is safe and keeps this module
+* dependency-free like the rest of `run.ts`'s helpers.
+*/
+function joinPath(...segments) {
+	return segments.map((s, i) => i === 0 ? s.replace(/\/+$/, "") : s.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+}
+//#endregion
 //#region src/run.ts
 /**
 * `holocron run <task> [job] [-- <passthrough>]` — run a registry task (or one
@@ -448,8 +540,13 @@ function runTask(input) {
 		const runner = resolveRunner(def.local, cwd, listDir);
 		if (runner) {
 			const flags = (def.flags?.[runner.tool] ?? []).filter((f) => !passthrough.includes(f));
+			const configFlags = resolveToolConfig(runner.tool, cwd, {
+				readFile,
+				fileExists
+			});
 			return run(resolveBin(cwd, runner.tool, fileExists), [
 				...runner.args,
+				...configFlags,
 				...flags,
 				...passthrough
 			]);
@@ -582,7 +679,7 @@ function runAllJobs(input, jobs, passthrough) {
 * turbo/a package script would have already caught in steps 1–2.
 */
 function runLinterGroup(input, names, passthrough) {
-	const { print, logger, listDir, lookPath, cwd, task } = input;
+	const { print, logger, listDir, lookPath, cwd, task, readFile, fileExists } = input;
 	const dryRun = input.dryRun ?? false;
 	const runOne = makeRunOne(input);
 	let rootFiles;
@@ -609,7 +706,15 @@ function runLinterGroup(input, names, passthrough) {
 			print(`! ${name} — ${bin} not on PATH${def.installHint ? `. ${def.installHint}` : ""} (enforced in CI)`);
 			continue;
 		}
-		reports.push(runOne(found, [...def.localArgs ?? [], ...passthrough]));
+		const configFlags = resolveToolConfig(name, cwd, {
+			readFile,
+			fileExists
+		});
+		reports.push(runOne(found, [
+			...configFlags,
+			...def.localArgs ?? [],
+			...passthrough
+		]));
 	}
 	if (reports.length === 0) {
 		const required = input.required && anyHasLocalBin;
@@ -1445,4 +1550,31 @@ function createAstromech(options) {
 	};
 }
 //#endregion
-export { CI_ORDER, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, reusableTemplates, runCi, runTask };
+//#region src/tsconfig.ts
+/**
+* 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).
+*/
+function createTsconfig(options) {
+	const variant = options.variant ?? "node-lts";
+	const compilerOptions = {
+		baseUrl: "./",
+		outDir: "./dist"
+	};
+	if (options.paths) compilerOptions.paths = { "@/*": ["./src/*"] };
+	const config = {
+		display: options.display,
+		extends: `@theholocron/tsconfig/${variant}`,
+		compilerOptions,
+		include: ["src/**/*.ts"],
+		exclude: ["node_modules", "dist"]
+	};
+	return JSON.stringify(config, null, 2) + "\n";
+}
+//#endregion
+export { CI_ORDER, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, RESOLVABLE_TOOLS, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, createTsconfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, resolveToolConfig, reusableTemplates, runCi, runTask };

package/package.json

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