@savvy-web/tsdown-plugins 2.1.8 → 2.2.0

package/README.md

@@ -53,7 +53,19 @@ export default defineConfig({
 - **Bundled declarations** — each target runs two `tsdown` passes: a JavaScript pass that preserves per-module output, then a declaration-only pass that rolls every re-exported type into a single `.d.ts` per public entry (`deriveDtsPassOptions`). Per-module JavaScript stays intact while consumers keep reaching re-exported types through your published subpaths.
 - **API Extractor meta** — `runMetaPass` is the single meta-generation orchestrator the bundler front door and both self-hosting escape hatches share: it derives the export paths, applies the optimistic next-version forward-look and drives API Extractor over a package's emitted `.d.ts` to write an api-model bundle (`.api.json`, `tsdoc-metadata.json`, resolved `tsconfig.json`). `generateMeta` is the lower-level pass it wraps, and `normalizeMetaOptions` fills the `MetaOptions` defaults that drive it.
 - **Output reporter** — `renderReport` plus the `BuildReport` schema and a set of formatters (terminal, JSON, markdown, CI annotations, silent) render a build report for humans, agents or CI.
-- **Issues artifact** — `writeIssuesArtifact` (with the pure `flattenIssues` and `serializeIssues` behind it) writes a deduplicated `dist/<target>/issues.json` on every build, collecting the build's warnings, errors and suppressed diagnostics in a stable JSON shape (`BuildIssues`/`PlainDiagnostic`) so an agent or CI script reads the diagnostics straight from disk instead of parsing terminal output.
+- **Issues artifact** — `writeIssuesArtifact` (with the pure `flattenIssues` and `serializeIssues` behind it) writes a deduplicated `dist/<target>/issues.json` on every build, successful or failed, collecting the build's warnings, errors and suppressed diagnostics in a stable JSON shape (`BuildIssues`/`PlainDiagnostic`) so an agent or CI script reads the diagnostics straight from disk instead of parsing terminal output. The artifact lands through a temp file and a rename, so a concurrent reader sees the previous file or the complete new one, never a half-written one.
+
+## Reading the issues artifact
+
+`dist/<target>/issues.json` is written on every terminal path — the build that finished and the build that blew up both leave one behind. Read the `buildOk` field before you read anything else: a crashed build leaves `warnings`, `errors` and `suppressed` empty, which is byte-for-byte what a clean build writes, so empty buckets alone prove nothing. When `buildOk` is `false`, the optional `failure` object carries the terminal error's `name` and `message` (truncated at 2000 characters).
+
+```bash
+jq -c '{ ok: .buildOk, errors: (.errors | length) }' dist/prod/issues.json
+# {"ok":true,"errors":0}    a build that ran to completion with no diagnostics
+# {"ok":false,"errors":0}   a build that died before it could report any
+```
+
+An artifact produced before the field existed has no `buildOk` at all. Treat a missing value as unknown, not as a pass. If you drive `writeIssuesArtifact` yourself from a hand-written config, it defaults `buildOk` to `true` — pass `buildOk: false` (and a `failure`) explicitly from your own error path, or your artifact will claim a clean gate the build never reached.
 
 ## Effect
 

package/index.d.ts

@@ -1713,6 +1713,23 @@ interface BuildIssues {
   generatedAt: string;
   package: string;
   target: "dev" | "prod";
+  /**
+   * Whether the build that produced this artifact reached its end without a terminal failure.
+   *
+   * The artifact is written on EVERY terminal path — success and failure alike — so a reader must
+   * gate on this flag, not on `errors.length`. A crashed build (API Extractor blowing up, a racing
+   * `rm -rf dist`) can leave all three diagnostic buckets empty; without this stamp that file is
+   * byte-identical to a perfectly clean gate. Absent on artifacts written before this field existed;
+   * treat a missing value as unknown rather than as a pass.
+   */
+  buildOk: boolean;
+  /** The terminal error that ended the build. Present only when `buildOk` is false. */
+  failure?: {
+    /** The error's `name` (e.g. `"Error"`, `"ConfigValidationError"`), when it has one. */
+    name?: string;
+    /** The error message, truncated to 2000 characters. */
+    message: string;
+  };
   warnings: PlainDiagnostic[];
   errors: PlainDiagnostic[];
   suppressed: PlainDiagnostic[];
@@ -1720,11 +1737,20 @@ interface BuildIssues {
 /**
  * Flatten a build snapshot into the aggregated, de-duplicated issues artifact. Pure.
  *
+ * `buildOk` defaults to `true`, so an existing caller that never fails keeps its current output plus
+ * the stamp; a caller that also writes on a failure path MUST pass `buildOk: false` (and ideally the
+ * `failure`), otherwise the artifact reads as a clean gate.
+ *
  * @public
  */
 declare function flattenIssues(reports: ReadonlyArray<BuildReport>, opts: {
   target: "dev" | "prod";
   generatedAt: string;
+  buildOk?: boolean | undefined;
+  failure?: {
+    name?: string | undefined;
+    message: string;
+  } | undefined;
 }): BuildIssues;
 /**
  * Serialize the issues artifact to pretty JSON with a trailing newline.
@@ -1735,6 +1761,11 @@ declare function serializeIssues(issues: BuildIssues): string;
 /**
  * Write the aggregated issues artifact to `<cwd>/dist/<target>/issues.json`. Returns the path written.
  *
+ * The write is atomic: the JSON lands in a sibling temp file which is then `rename`d over the
+ * destination, so a concurrent reader observes either the previous artifact or the complete new one,
+ * never a torn or half-written file. Pass `buildOk: false` (plus `failure`, when there is an error to
+ * report) on a failure path — see the `buildOk` field of `BuildIssues`.
+ *
  * @public
  */
 declare function writeIssuesArtifact(opts: {
@@ -1742,6 +1773,11 @@ declare function writeIssuesArtifact(opts: {
   target: "dev" | "prod";
   reports: ReadonlyArray<BuildReport>;
   now?: () => Date;
+  buildOk?: boolean | undefined;
+  failure?: {
+    name?: string | undefined;
+    message: string;
+  } | undefined;
 }): string;
 //#endregion
 //#region src/report/services/EnvironmentDetector.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/tsdown-plugins",
-	"version": "2.1.8",
+	"version": "2.2.0",
 	"private": false,
 	"description": "Interface-only tsdown/rolldown plugin pack powering @savvy-web/bundler",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/tsdown-plugins",
@@ -31,10 +31,10 @@
 	"dependencies": {
 		"@changesets/get-release-plan": "^5.0.0-next.7",
 		"@effect/platform-node": "4.0.0-beta.101",
-		"@effected/npm": "^0.3.1",
-		"@effected/package-json": "^0.5.1",
-		"@effected/tsconfig-json": "^0.3.1",
-		"@effected/workspaces": "^0.6.2",
+		"@effected/npm": "^0.4.0",
+		"@effected/package-json": "^0.5.2",
+		"@effected/tsconfig-json": "^0.3.2",
+		"@effected/workspaces": "^0.8.0",
 		"@microsoft/api-extractor": "^7.58.12",
 		"@microsoft/tsdoc": "^0.16.0",
 		"@microsoft/tsdoc-config": "^0.18.1",

package/report/issues-artifact.js

@@ -1,4 +1,4 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 //#region src/report/issues-artifact.ts
@@ -36,9 +36,23 @@ function dedupe(entries) {
 	}
 	return out;
 }
+/** Longest failure message kept in the artifact — enough for a stack-free error, short of a log dump. */
+const MAX_FAILURE_MESSAGE = 2e3;
+/** Normalize a caller-supplied failure into the stamped shape (message truncated, empty name dropped). */
+function toFailure(failure) {
+	const message = failure.message.length > MAX_FAILURE_MESSAGE ? `${failure.message.slice(0, MAX_FAILURE_MESSAGE - 1)}…` : failure.message;
+	return failure.name !== void 0 && failure.name !== "" ? {
+		name: failure.name,
+		message
+	} : { message };
+}
 /**
 * Flatten a build snapshot into the aggregated, de-duplicated issues artifact. Pure.
 *
+* `buildOk` defaults to `true`, so an existing caller that never fails keeps its current output plus
+* the stamp; a caller that also writes on a failure path MUST pass `buildOk: false` (and ideally the
+* `failure`), otherwise the artifact reads as a clean gate.
+*
 * @public
 */
 function flattenIssues(reports, opts) {
@@ -54,6 +68,8 @@ function flattenIssues(reports, opts) {
 		generatedAt: opts.generatedAt,
 		package: reports[0]?.package ?? "unknown",
 		target: opts.target,
+		buildOk: opts.buildOk ?? true,
+		...opts.failure !== void 0 ? { failure: toFailure(opts.failure) } : {},
 		warnings: dedupe(warnings),
 		errors: dedupe(errors),
 		suppressed: dedupe(suppressed)
@@ -70,17 +86,31 @@ function serializeIssues(issues) {
 /**
 * Write the aggregated issues artifact to `<cwd>/dist/<target>/issues.json`. Returns the path written.
 *
+* The write is atomic: the JSON lands in a sibling temp file which is then `rename`d over the
+* destination, so a concurrent reader observes either the previous artifact or the complete new one,
+* never a torn or half-written file. Pass `buildOk: false` (plus `failure`, when there is an error to
+* report) on a failure path — see the `buildOk` field of `BuildIssues`.
+*
 * @public
 */
 function writeIssuesArtifact(opts) {
 	const clock = opts.now ?? (() => /* @__PURE__ */ new Date());
 	const issues = flattenIssues(opts.reports, {
 		target: opts.target,
-		generatedAt: clock().toISOString()
+		generatedAt: clock().toISOString(),
+		buildOk: opts.buildOk,
+		failure: opts.failure
 	});
 	const outPath = join(opts.cwd, "dist", opts.target, "issues.json");
 	mkdirSync(dirname(outPath), { recursive: true });
-	writeFileSync(outPath, serializeIssues(issues), "utf8");
+	const tmpPath = `${outPath}.${process.pid}.tmp`;
+	try {
+		writeFileSync(tmpPath, serializeIssues(issues), "utf8");
+		renameSync(tmpPath, outPath);
+	} catch (err) {
+		rmSync(tmpPath, { force: true });
+		throw err;
+	}
 	return outPath;
 }