tsdown-stale-guard 0.0.0 → 0.1.1

package/README.md

@@ -8,13 +8,17 @@
 
 Build freshness validation for [tsdown](https://github.com/rolldown/tsdown). Records hashes of all files involved in a build, enabling fast up-to-date checks without re-building.
 
+> This plugin requires `tsdown@0.21.9` or later.
+
 ## Features
 
 - **tsdown/Rolldown plugin** — automatically tracks source files, output files, config, and package lock file
 - **Composite hash** — single hash for quick freshness checks
 - **Find-up search** — detects lock files and configs in monorepo setups
-- **CLI** — `tsdown-stale-guard check` for CI pipelines
-- **Programmatic API** — `checkBuildFreshness()` for tool integrations
+- **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
 
@@ -29,17 +33,17 @@ npm i tsdown-stale-guard
 ```ts
 // tsdown.config.ts
 import { defineConfig } from 'tsdown'
-import { TsdownStaleGuard } from 'tsdown-stale-guard'
+import { StaleGuardRecorder } from 'tsdown-stale-guard'
 
 export default defineConfig({
   entry: ['src/index.ts'],
   plugins: [
-    TsdownStaleGuard(),
+    StaleGuardRecorder(),
   ],
 })
 ```
 
-After building, a hash file will be generated at `node_modules/.cache/tsdown-stale-guard/hash.yaml`. Since it lives inside `node_modules`, it does not need to be gitignored.
+After building, a hash file will be generated at `node_modules/.cache/tsdown-stale-guard/hash.yaml`.
 
 Example of the generated hash file:
 
@@ -65,7 +69,7 @@ outputs:
 ### Plugin Options
 
 ```ts
-TsdownStaleGuard({
+StaleGuardRecorder({
   hashFile: 'node_modules/.cache/tsdown-stale-guard/hash.yaml', // hash file path (default)
   root: process.cwd(), // root directory (default)
   hashOutputs: true, // hash output files (default)
@@ -76,10 +80,10 @@ TsdownStaleGuard({
 
 ```bash
 # Check if the build is up to date
-tsdown-stale-guard check
+tsdown-stale-guard
 
 # Use a custom hash file path
-tsdown-stale-guard check --hash-file custom.hash.yaml
+tsdown-stale-guard --hash-file custom.hash.yaml
 ```
 
 Exit code `0` if fresh, `1` if stale.
@@ -87,9 +91,9 @@ Exit code `0` if fresh, `1` if stale.
 ### Programmatic API
 
 ```ts
-import { checkBuildFreshness } from 'tsdown-stale-guard'
+import { checkBuildState } from 'tsdown-stale-guard'
 
-const result = await checkBuildFreshness()
+const result = await checkBuildState()
 
 if (result.fresh) {
   console.log('Build is up to date')
@@ -101,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:
@@ -133,7 +197,7 @@ Package lock files (`pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.loc
 [npm-downloads-href]: https://npmjs.com/package/tsdown-stale-guard
 [bundle-src]: https://img.shields.io/bundlephobia/minzip/tsdown-stale-guard?style=flat&colorA=080f12&colorB=1fa669&label=minzip
 [bundle-href]: https://bundlephobia.com/result?p=tsdown-stale-guard
-[license-src]: https://img.shields.io/github/license/antfu/tsdown-stale-guard.svg?style=flat&colorA=080f12&colorB=1fa669
-[license-href]: https://github.com/antfu/tsdown-stale-guard/blob/main/LICENSE
+[license-src]: https://img.shields.io/github/license/antfu-collective/tsdown-stale-guard.svg?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: https://github.com/antfu-collective/tsdown-stale-guard/blob/main/LICENSE
 [jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
 [jsdocs-href]: https://www.jsdocs.io/package/tsdown-stale-guard

package/dist/cli.mjs

@@ -1,31 +1,13 @@
 #!/usr/bin/env node
-import { t as checkBuildFreshness } from "./check-YFLy7mcd.mjs";
-import process from "node:process";
+import { t as guardStaleBuild } from "./guard-CAD3_wn0.mjs";
+import cac from "cac";
 //#region src/cli.ts
-const args = process.argv.slice(2);
-const command = args[0];
-if (command === "check") {
-	const hashFileIdx = args.indexOf("--hash-file");
-	const result = await checkBuildFreshness({ hashFile: hashFileIdx !== -1 ? args[hashFileIdx + 1] : void 0 });
-	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);
-	}
-} else {
-	console.log(`tsdown-stale-guard - Build freshness validation for tsdown
-
-Usage:
-  tsdown-stale-guard check              Check if the build is up to date
-  tsdown-stale-guard check --hash-file <path>  Use a custom hash file path
-
-Options:
-  --hash-file <path>  Path to the hash file (default: node_modules/.cache/tsdown-stale-guard/hash.yaml)
-  --help              Show this help message`);
-	process.exit(command === "--help" || command === "-h" ? 0 : 1);
-}
+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) => {
+	await guardStaleBuild({ hashFile: options.hashFile });
+	console.log("Build is up to date.");
+});
+cli.help();
+cli.parse();
 //#endregion
 export {};

package/dist/{check-YFLy7mcd.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);
@@ -34,7 +35,7 @@ function serializeHashFile(data) {
 		version: data.version,
 		hash: data.hash
 	};
-	if (data.config) obj.config = { [data.config.file]: data.config.hash };
+	if (data.configs) obj.configs = Object.fromEntries(data.configs.map((e) => [e.file, e.hash]));
 	if (data.lockfile) obj.lockfile = { [data.lockfile.file]: data.lockfile.hash };
 	if (data.sources.length > 0) obj.sources = Object.fromEntries(data.sources.map((e) => [e.file, e.hash]));
 	if (data.outputs.length > 0) obj.outputs = Object.fromEntries(data.outputs.map((e) => [e.file, e.hash]));
@@ -45,7 +46,7 @@ function parseHashFile(content) {
 	return {
 		version: obj.version,
 		hash: obj.hash,
-		config: parseSection(obj.config),
+		configs: parseSectionList(obj.configs),
 		lockfile: parseSection(obj.lockfile),
 		sources: parseSectionList(obj.sources),
 		outputs: parseSectionList(obj.outputs)
@@ -78,22 +79,24 @@ async function writeHashFile(path, data) {
 //#endregion
 //#region src/check.ts
 const DEFAULT_HASH_FILE = "node_modules/.cache/tsdown-stale-guard/hash.yaml";
-async function checkBuildFreshness(options = {}) {
+async function checkBuildState(options = {}) {
 	const root = options.root || process.cwd();
 	const data = await readHashFile(resolve(root, options.hashFile || DEFAULT_HASH_FILE));
 	const changes = [];
-	if (data.config) await checkEntry(data.config, "config", root, changes);
+	if (data.configs) for (const entry of data.configs) await checkEntry(entry, "config", root, changes);
 	if (data.lockfile) await checkEntry(data.lockfile, "lockfile", root, changes);
 	for (const entry of data.sources) await checkEntry(entry, "source", root, changes);
 	for (const entry of data.outputs) await checkEntry(entry, "output", root, changes);
 	const currentHash = computeCompositeHash([
 		...data.sources,
 		...data.outputs,
-		...data.config ? [data.config] : [],
+		...data.configs || [],
 		...data.lockfile ? [data.lockfile] : []
 	]);
+	const fresh = changes.length === 0 && currentHash === data.hash;
 	return {
-		fresh: changes.length === 0 && currentHash === data.hash,
+		fresh,
+		stale: !fresh,
 		changes
 	};
 }
@@ -114,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, checkBuildFreshness 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,20 +1,22 @@
-import { Plugin } from "rolldown";
+import * as _$logs_sdk0 from "logs-sdk";
+import { TsdownPlugin } from "tsdown";
 
 //#region src/types.d.ts
-interface TsdownStaleGuardEntry {
+interface StaleGuardEntry {
   file: string;
   hash: string;
 }
-interface TsdownStaleGuardData {
+interface StaleGuardData {
   version: 1;
   hash: string;
-  config?: TsdownStaleGuardEntry;
-  lockfile?: TsdownStaleGuardEntry;
-  sources: TsdownStaleGuardEntry[];
-  outputs: TsdownStaleGuardEntry[];
+  configs?: StaleGuardEntry[];
+  lockfile?: StaleGuardEntry;
+  sources: StaleGuardEntry[];
+  outputs: StaleGuardEntry[];
 }
 interface CheckResult {
   fresh: boolean;
+  stale: boolean;
   changes: CheckChange[];
 }
 interface CheckChange {
@@ -22,7 +24,7 @@ interface CheckChange {
   category: 'config' | 'lockfile' | 'source' | 'output';
   file: string;
 }
-interface TsdownStaleGuardPluginOptions {
+interface StaleGuardRecorderOptions {
   /**
    * Path to the hash file.
    * @default 'node_modules/.cache/tsdown-stale-guard/hash.yaml'
@@ -53,14 +55,49 @@ interface CheckOptions {
 }
 //#endregion
 //#region src/check.d.ts
-declare function checkBuildFreshness(options?: CheckOptions): Promise<CheckResult>;
+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: TsdownStaleGuardData): string;
-declare function parseHashFile(content: string): TsdownStaleGuardData;
-declare function readHashFile(path: string): Promise<TsdownStaleGuardData>;
+declare function serializeHashFile(data: StaleGuardData): string;
+declare function parseHashFile(content: string): StaleGuardData;
+declare function readHashFile(path: string): Promise<StaleGuardData>;
 //#endregion
 //#region src/plugin.d.ts
-declare function TsdownStaleGuard(options?: TsdownStaleGuardPluginOptions): Plugin;
+declare function StaleGuardRecorder(options?: StaleGuardRecorderOptions): TsdownPlugin;
 //#endregion
-export { type CheckChange, type CheckOptions, type CheckResult, TsdownStaleGuard, type TsdownStaleGuardData, type TsdownStaleGuardEntry, type TsdownStaleGuardPluginOptions, checkBuildFreshness, 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,7 +1,6 @@
-import { a as writeHashFile, c as hashFiles, i as serializeHashFile, n as parseHashFile, o as computeCompositeHash, r as readHashFile, s as hashFile, t as checkBuildFreshness } from "./check-YFLy7mcd.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 process from "node:process";
 import { readdir } from "node:fs/promises";
 //#region src/detect.ts
 const PACKAGE_LOCK_FILES = [
@@ -11,15 +10,6 @@ const PACKAGE_LOCK_FILES = [
 	"bun.lockb",
 	"bun.lock"
 ];
-const TSDOWN_CONFIG_FILES = [
-	"tsdown.config.ts",
-	"tsdown.config.mts",
-	"tsdown.config.cts",
-	"tsdown.config.js",
-	"tsdown.config.mjs",
-	"tsdown.config.cjs",
-	"tsdown.config.json"
-];
 function findUp(names, cwd) {
 	let dir = resolve(cwd);
 	while (true) {
@@ -35,23 +25,26 @@ function findUp(names, cwd) {
 function detectPackageLock(cwd) {
 	return findUp(PACKAGE_LOCK_FILES, cwd);
 }
-function detectTsdownConfig(cwd) {
-	return findUp(TSDOWN_CONFIG_FILES, cwd);
-}
 //#endregion
 //#region src/plugin.ts
 const RE_QUERY = /\?.*$/;
 const RE_WINDOWS_DRIVE = /^[a-z]:\\/i;
 const RE_NODE_MODULES = /node_modules/;
 const DEFAULT_HASH_FILE = "node_modules/.cache/tsdown-stale-guard/hash.yaml";
-function TsdownStaleGuard(options = {}) {
+function StaleGuardRecorder(options = {}) {
 	const { hashFile: hashFilePath = DEFAULT_HASH_FILE, hashOutputs = true } = options;
 	const sourceIds = /* @__PURE__ */ new Set();
 	let root;
+	let configDeps;
+	let outDir;
+	let isTsdownConfigResolvedCalled = false;
 	return {
 		name: "tsdown-stale-guard",
-		buildStart() {
-			root = options.root || process.cwd();
+		tsdownConfigResolved(config) {
+			isTsdownConfigResolvedCalled = true;
+			root = options.root || config.cwd;
+			configDeps = config.configDeps;
+			outDir = config.outDir;
 		},
 		transform: {
 			filter: { id: { exclude: [RE_NODE_MODULES] } },
@@ -60,8 +53,8 @@ function TsdownStaleGuard(options = {}) {
 				if (cleanId.startsWith("/") || RE_WINDOWS_DRIVE.test(cleanId)) sourceIds.add(cleanId);
 			}
 		},
-		async writeBundle(opts) {
-			const outDir = opts.dir || resolve(root, "dist");
+		async writeBundle() {
+			if (!isTsdownConfigResolvedCalled) return log.TSDSG0001().throw();
 			const resolvedHashFile = resolve(root, hashFilePath);
 			const sources = await hashFiles([...sourceIds].filter((f) => existsSync(f)), root);
 			let outputs = [];
@@ -74,14 +67,14 @@ function TsdownStaleGuard(options = {}) {
 				for (const file of files) if (file.isFile()) outputPaths.push(resolve(file.parentPath, file.name));
 				outputs = await hashFiles(outputPaths, root);
 			}
-			let config;
-			const configPath = detectTsdownConfig(root);
-			if (configPath) {
-				const hash = await hashFile(configPath);
-				config = {
-					file: toForwardSlash(relative(root, configPath)),
+			const configs = [];
+			if (configDeps) for (const dep of configDeps) {
+				const hash = await hashFile(dep);
+				const file = toForwardSlash(relative(root, dep));
+				configs.push({
+					file,
 					hash
-				};
+				});
 			}
 			let lockfileEntry;
 			const lockfilePath = detectPackageLock(root);
@@ -97,10 +90,10 @@ function TsdownStaleGuard(options = {}) {
 				hash: computeCompositeHash([
 					...sources,
 					...outputs,
-					...config ? [config] : [],
+					...configs,
 					...lockfileEntry ? [lockfileEntry] : []
 				]),
-				config,
+				configs,
 				lockfile: lockfileEntry,
 				sources,
 				outputs
@@ -112,4 +105,4 @@ function toForwardSlash(p) {
 	return p.replace(/\\/g, "/");
 }
 //#endregion
-export { TsdownStaleGuard, checkBuildFreshness, parseHashFile, readHashFile, serializeHashFile };
+export { StaleGuardRecorder, checkBuildState, diagnostics, guardStaleBuild, log, parseHashFile, readHashFile, serializeHashFile };

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "tsdown-stale-guard",
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "Build freshness validation for tsdown",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "funding": "https://github.com/sponsors/antfu",
-  "homepage": "https://github.com/antfu/tsdown-stale-guard#readme",
+  "homepage": "https://github.com/antfu-collective/tsdown-stale-guard#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/antfu/tsdown-stale-guard.git"
+    "url": "git+https://github.com/antfu-collective/tsdown-stale-guard.git"
   },
-  "bugs": "https://github.com/antfu/tsdown-stale-guard/issues",
+  "bugs": "https://github.com/antfu-collective/tsdown-stale-guard/issues",
   "keywords": [
     "tsdown",
     "build",
@@ -32,7 +32,12 @@
   "files": [
     "dist"
   ],
+  "peerDependencies": {
+    "tsdown": "^0.21.9"
+  },
   "dependencies": {
+    "cac": "^7.0.0",
+    "logs-sdk": "0.0.6",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
@@ -44,12 +49,12 @@
     "eslint": "^10.2.0",
     "lint-staged": "^16.4.0",
     "publint": "^0.3.18",
-    "rolldown": "1.0.0-rc.15",
     "simple-git-hooks": "^2.13.1",
-    "tsdown": "^0.21.8",
-    "tsnapi": "^0.2.1",
+    "skills-npm": "^1.1.1",
+    "tsdown": "^0.21.9",
+    "tsnapi": "^0.3.2",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
+    "typescript": "^6.0.3",
     "vite": "^8.0.8",
     "vitest": "^4.1.4"
   },