tsdown-stale-guard 0.1.0 → 0.1.1

package/README.md

@@ -17,6 +17,8 @@ Build freshness validation for [tsdown](https://github.com/rolldown/tsdown). Rec
 - **Find-up search** — detects lock files and configs in monorepo setups
 - **CLI** — `tsdown-stale-guard` for CI pipelines
 - **Programmatic API** — `checkBuildState()` for tool integrations
+- **Build guard** — `guardStaleBuild()` throws on stale builds, great for test setups
+- **Structured diagnostics** — errors use [logs-sdk](https://github.com/vercel-labs/logs-sdk) with stable codes and actionable fixes
 
 ## Install
 
@@ -103,6 +105,66 @@ else {
 }
 ```
 
+### Guard Stale Build
+
+`guardStaleBuild()` checks the build state and throws a structured [`TSDSG0002`](./docs/errors/tsdsg0002.md) error if the build is stale. This is useful for CI pipelines or test setups where you want to fail early when the build output is outdated.
+
+```ts
+import { guardStaleBuild } from 'tsdown-stale-guard'
+
+// Throws if the build is stale
+await guardStaleBuild()
+```
+
+#### With Vitest
+
+When writing tests against the built output (`dist/`), you can use `guardStaleBuild()` to ensure the build is fresh before tests run. Use `beforeAll` for a per-test-file check:
+
+```ts
+import { guardStaleBuild } from 'tsdown-stale-guard'
+import { beforeAll, describe, it } from 'vitest'
+
+beforeAll(async () => {
+  await guardStaleBuild()
+})
+
+it('should work', async () => {
+  const { myFunction } = await import('../dist/index.mjs')
+  // test against the built output
+})
+```
+
+Or use `globalSetup` for a one-time global check:
+
+```ts
+// test/setup.ts
+import { guardStaleBuild } from 'tsdown-stale-guard'
+
+await guardStaleBuild()
+```
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globalSetup: ['test/setup.ts'],
+  },
+})
+```
+
+Either way, tests fail immediately with a clear error message if the build is stale, instead of producing confusing failures from outdated output.
+
+### Diagnostic Codes
+
+All errors thrown by `tsdown-stale-guard` are structured [`CodedError`](https://github.com/vercel-labs/logs-sdk) objects with stable codes, actionable `fix` messages, and documentation links.
+
+| Code | Level | Description |
+|------|-------|-------------|
+| [`TSDSG0001`](./docs/errors/tsdsg0001.md) | error | `tsdownConfigResolved` hook was not called (tsdown version too old) |
+| [`TSDSG0002`](./docs/errors/tsdsg0002.md) | error | Build is stale — source files, config, or dependencies changed |
+
 ## How It Works
 
 The plugin hooks into Rolldown's build pipeline:

package/dist/cli.mjs

@@ -1,19 +1,11 @@
 #!/usr/bin/env node
-import { t as checkBuildState } from "./check-CWbzg4YR.mjs";
-import process from "node:process";
+import { t as guardStaleBuild } from "./guard-CAD3_wn0.mjs";
 import cac from "cac";
 //#region src/cli.ts
 const cli = cac("tsdown-stale-guard");
 cli.command("[...args]", "Check if the build is up to date").option("--hash-file <path>", "Path to the hash file").action(async (_args, options) => {
-	const result = await checkBuildState({ hashFile: options.hashFile });
-	if (result.fresh) {
-		console.log("Build is up to date.");
-		process.exit(0);
-	} else {
-		console.log("Build is stale. Changes detected:");
-		for (const change of result.changes) console.log(`  ${change.type}: [${change.category}] ${change.file}`);
-		process.exit(1);
-	}
+	await guardStaleBuild({ hashFile: options.hashFile });
+	console.log("Build is up to date.");
 });
 cli.help();
 cli.parse();

package/dist/{check-CWbzg4YR.mjs → guard-CAD3_wn0.mjs}

@@ -4,6 +4,7 @@ import process from "node:process";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { parse, stringify } from "yaml";
+import { consoleReporter, createLogger, defineDiagnostics } from "logs-sdk";
 //#region src/hash.ts
 async function hashFile(path) {
 	const content = await readFile(path);
@@ -116,4 +117,35 @@ async function checkEntry(entry, category, root, changes) {
 	});
 }
 //#endregion
-export { writeHashFile as a, hashFiles as c, serializeHashFile as i, parseHashFile as n, computeCompositeHash as o, readHashFile as r, hashFile as s, checkBuildState as t };
+//#region src/diagnostics.ts
+const diagnostics = defineDiagnostics({
+	docsBase: (code) => `https://github.com/antfu-collective/tsdown-stale-guard/blob/main/docs/errors/${code.toLowerCase()}.md`,
+	codes: {
+		TSDSG0001: {
+			message: "The `tsdownConfigResolved` hook was not called.",
+			why: "The `tsdownConfigResolved` hook is only available since `tsdown@0.21.9`. Your version of tsdown may not support it.",
+			fix: "Upgrade tsdown to `0.21.9` or later."
+		},
+		TSDSG0002: {
+			message: (p) => `Build is stale in \`${p.root}\`. ${p.changeCount} file${p.changeCount === 1 ? "" : "s"} changed since last build.`,
+			why: "Source files, config, or dependencies have changed since the last build.",
+			fix: "Run your build script (e.g. `npm run build`) or `tsdown` directly to rebuild the project."
+		}
+	}
+});
+const log = createLogger({
+	diagnostics: [diagnostics],
+	reporters: consoleReporter
+});
+//#endregion
+//#region src/guard.ts
+async function guardStaleBuild(options = {}) {
+	const root = options.root || process.cwd();
+	const result = await checkBuildState(options);
+	if (result.stale) return log.TSDSG0002({
+		root,
+		changeCount: result.changes.length
+	}).throw();
+}
+//#endregion
+export { parseHashFile as a, writeHashFile as c, hashFiles as d, checkBuildState as i, computeCompositeHash as l, diagnostics as n, readHashFile as o, log as r, serializeHashFile as s, guardStaleBuild as t, hashFile as u };

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import * as _$logs_sdk0 from "logs-sdk";
 import { TsdownPlugin } from "tsdown";
 
 //#region src/types.d.ts
@@ -56,6 +57,41 @@ interface CheckOptions {
 //#region src/check.d.ts
 declare function checkBuildState(options?: CheckOptions): Promise<CheckResult>;
 //#endregion
+//#region src/diagnostics.d.ts
+declare const diagnostics: _$logs_sdk0.DiagnosticsResult<{
+  TSDSG0001: {
+    message: string;
+    why: string;
+    fix: string;
+  };
+  TSDSG0002: {
+    message: (p: {
+      root: string;
+      changeCount: number;
+    }) => string;
+    why: string;
+    fix: string;
+  };
+}>;
+declare const log: _$logs_sdk0.Logger<[_$logs_sdk0.DiagnosticsResult<{
+  TSDSG0001: {
+    message: string;
+    why: string;
+    fix: string;
+  };
+  TSDSG0002: {
+    message: (p: {
+      root: string;
+      changeCount: number;
+    }) => string;
+    why: string;
+    fix: string;
+  };
+}>]>;
+//#endregion
+//#region src/guard.d.ts
+declare function guardStaleBuild(options?: CheckOptions): Promise<void>;
+//#endregion
 //#region src/lockfile.d.ts
 declare function serializeHashFile(data: StaleGuardData): string;
 declare function parseHashFile(content: string): StaleGuardData;
@@ -64,4 +100,4 @@ declare function readHashFile(path: string): Promise<StaleGuardData>;
 //#region src/plugin.d.ts
 declare function StaleGuardRecorder(options?: StaleGuardRecorderOptions): TsdownPlugin;
 //#endregion
-export { type CheckChange, type CheckOptions, type CheckResult, type StaleGuardData, type StaleGuardEntry, StaleGuardRecorder, type StaleGuardRecorderOptions, checkBuildState, parseHashFile, readHashFile, serializeHashFile };
+export { type CheckChange, type CheckOptions, type CheckResult, type StaleGuardData, type StaleGuardEntry, StaleGuardRecorder, type StaleGuardRecorderOptions, checkBuildState, diagnostics, guardStaleBuild, log, parseHashFile, readHashFile, serializeHashFile };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as writeHashFile, c as hashFiles, i as serializeHashFile, n as parseHashFile, o as computeCompositeHash, r as readHashFile, s as hashFile, t as checkBuildState } from "./check-CWbzg4YR.mjs";
+import { a as parseHashFile, c as writeHashFile, d as hashFiles, i as checkBuildState, l as computeCompositeHash, n as diagnostics, o as readHashFile, r as log, s as serializeHashFile, t as guardStaleBuild, u as hashFile } from "./guard-CAD3_wn0.mjs";
 import { existsSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { readdir } from "node:fs/promises";
@@ -54,7 +54,7 @@ function StaleGuardRecorder(options = {}) {
 			}
 		},
 		async writeBundle() {
-			if (!isTsdownConfigResolvedCalled) throw new Error("tsdownConfigResolved is not being called correctly. `tsdown-stale-guard` requires `tsdown@0.21.9` or later, please check your tsdown version.");
+			if (!isTsdownConfigResolvedCalled) return log.TSDSG0001().throw();
 			const resolvedHashFile = resolve(root, hashFilePath);
 			const sources = await hashFiles([...sourceIds].filter((f) => existsSync(f)), root);
 			let outputs = [];
@@ -105,4 +105,4 @@ function toForwardSlash(p) {
 	return p.replace(/\\/g, "/");
 }
 //#endregion
-export { StaleGuardRecorder, checkBuildState, parseHashFile, readHashFile, serializeHashFile };
+export { StaleGuardRecorder, checkBuildState, diagnostics, guardStaleBuild, log, parseHashFile, readHashFile, serializeHashFile };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tsdown-stale-guard",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Build freshness validation for tsdown",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -37,6 +37,7 @@
   },
   "dependencies": {
     "cac": "^7.0.0",
+    "logs-sdk": "0.0.6",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
@@ -49,10 +50,11 @@
     "lint-staged": "^16.4.0",
     "publint": "^0.3.18",
     "simple-git-hooks": "^2.13.1",
+    "skills-npm": "^1.1.1",
     "tsdown": "^0.21.9",
-    "tsnapi": "^0.3.0",
+    "tsnapi": "^0.3.2",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
+    "typescript": "^6.0.3",
     "vite": "^8.0.8",
     "vitest": "^4.1.4"
   },