tsdown-stale-guard 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# tsdown-stale-guard
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![JSDocs][jsdocs-src]][jsdocs-href]
+[![License][license-src]][license-href]
+
+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.
+
+## 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
+
+## Install
+
+```bash
+npm i tsdown-stale-guard
+```
+
+## Usage
+
+### As a tsdown Plugin
+
+```ts
+// tsdown.config.ts
+import { defineConfig } from 'tsdown'
+import { TsdownStaleGuard } from 'tsdown-stale-guard'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  plugins: [
+    TsdownStaleGuard(),
+  ],
+})
+```
+
+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.
+
+Example of the generated hash file:
+
+```yaml
+version: 1
+hash: sha256:abc123...
+
+config:
+  tsdown.config.ts: sha256:def456...
+
+lockfile:
+  ../../pnpm-lock.yaml: sha256:789abc...
+
+sources:
+  src/index.ts: sha256:111111...
+  src/utils.ts: sha256:222222...
+
+outputs:
+  dist/index.mjs: sha256:aaaaaa...
+  dist/index.d.mts: sha256:bbbbbb...
+```
+
+### Plugin Options
+
+```ts
+TsdownStaleGuard({
+  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)
+})
+```
+
+### CLI
+
+```bash
+# Check if the build is up to date
+tsdown-stale-guard check
+
+# Use a custom hash file path
+tsdown-stale-guard check --hash-file custom.hash.yaml
+```
+
+Exit code `0` if fresh, `1` if stale.
+
+### Programmatic API
+
+```ts
+import { checkBuildFreshness } from 'tsdown-stale-guard'
+
+const result = await checkBuildFreshness()
+
+if (result.fresh) {
+  console.log('Build is up to date')
+}
+else {
+  for (const change of result.changes) {
+    console.log(`${change.type}: [${change.category}] ${change.file}`)
+  }
+}
+```
+
+## How It Works
+
+The plugin hooks into Rolldown's build pipeline:
+
+1. **`transform`** — collects all source file paths during bundling
+2. **`generateBundle`** — collects output file names
+3. **`writeBundle`** — hashes all collected files plus the detected tsdown config and package lock file, then writes the hash file
+
+The hash file includes a composite `hash` computed from all individual file hashes, enabling a single-comparison freshness check.
+
+Package lock files (`pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.lockb`, `bun.lock`) and tsdown config files are found via find-up search, supporting monorepo setups where they may live in a parent directory.
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg">
+    <img src="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg" alt="Sponsors"/>
+  </a>
+</p>
+
+## License
+
+[MIT](./LICENSE) License © [Anthony Fu](https://github.com/antfu)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/tsdown-stale-guard?style=flat&colorA=080f12&colorB=1fa669
+[npm-version-href]: https://npmjs.com/package/tsdown-stale-guard
+[npm-downloads-src]: https://img.shields.io/npm/dm/tsdown-stale-guard?style=flat&colorA=080f12&colorB=1fa669
+[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
+[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/check-YFLy7mcd.mjs

@@ -0,0 +1,117 @@
+import { existsSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import process from "node:process";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { parse, stringify } from "yaml";
+//#region src/hash.ts
+async function hashFile(path) {
+	const content = await readFile(path);
+	return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+async function hashFiles(paths, root) {
+	return (await Promise.all(paths.map(async (p) => {
+		const hash = await hashFile(p);
+		return {
+			file: toForwardSlash(relative(root, p)),
+			hash
+		};
+	}))).sort((a, b) => a.file.localeCompare(b.file));
+}
+function computeCompositeHash(entries) {
+	const hash = createHash("sha256");
+	for (const entry of [...entries].sort((a, b) => a.file.localeCompare(b.file))) hash.update(`${entry.file}:${entry.hash}\n`);
+	return `sha256:${hash.digest("hex")}`;
+}
+function toForwardSlash(p) {
+	return p.replace(/\\/g, "/");
+}
+//#endregion
+//#region src/lockfile.ts
+const HEADER = "# auto-generated by tsdown-stale-guard\n# DO NOT EDIT\n";
+function serializeHashFile(data) {
+	const obj = {
+		version: data.version,
+		hash: data.hash
+	};
+	if (data.config) obj.config = { [data.config.file]: data.config.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]));
+	return HEADER + stringify(obj, { lineWidth: 0 });
+}
+function parseHashFile(content) {
+	const obj = parse(content);
+	return {
+		version: obj.version,
+		hash: obj.hash,
+		config: parseSection(obj.config),
+		lockfile: parseSection(obj.lockfile),
+		sources: parseSectionList(obj.sources),
+		outputs: parseSectionList(obj.outputs)
+	};
+}
+function parseSection(section) {
+	if (!section) return void 0;
+	const entries = Object.entries(section);
+	if (entries.length === 0) return void 0;
+	const [file, hash] = entries[0];
+	return {
+		file,
+		hash
+	};
+}
+function parseSectionList(section) {
+	if (!section) return [];
+	return Object.entries(section).map(([file, hash]) => ({
+		file,
+		hash
+	}));
+}
+async function readHashFile(path) {
+	return parseHashFile(await readFile(path, "utf-8"));
+}
+async function writeHashFile(path, data) {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, serializeHashFile(data), "utf-8");
+}
+//#endregion
+//#region src/check.ts
+const DEFAULT_HASH_FILE = "node_modules/.cache/tsdown-stale-guard/hash.yaml";
+async function checkBuildFreshness(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.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.lockfile ? [data.lockfile] : []
+	]);
+	return {
+		fresh: changes.length === 0 && currentHash === data.hash,
+		changes
+	};
+}
+async function checkEntry(entry, category, root, changes) {
+	const filePath = resolve(root, entry.file);
+	if (!existsSync(filePath)) {
+		changes.push({
+			type: "removed",
+			category,
+			file: entry.file
+		});
+		return;
+	}
+	if (await hashFile(filePath) !== entry.hash) changes.push({
+		type: "changed",
+		category,
+		file: entry.file
+	});
+}
+//#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 };

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { t as checkBuildFreshness } from "./check-YFLy7mcd.mjs";
+import process from "node:process";
+//#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);
+}
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,66 @@
+import { Plugin } from "rolldown";
+
+//#region src/types.d.ts
+interface TsdownStaleGuardEntry {
+  file: string;
+  hash: string;
+}
+interface TsdownStaleGuardData {
+  version: 1;
+  hash: string;
+  config?: TsdownStaleGuardEntry;
+  lockfile?: TsdownStaleGuardEntry;
+  sources: TsdownStaleGuardEntry[];
+  outputs: TsdownStaleGuardEntry[];
+}
+interface CheckResult {
+  fresh: boolean;
+  changes: CheckChange[];
+}
+interface CheckChange {
+  type: 'changed' | 'added' | 'removed';
+  category: 'config' | 'lockfile' | 'source' | 'output';
+  file: string;
+}
+interface TsdownStaleGuardPluginOptions {
+  /**
+   * Path to the hash file.
+   * @default 'node_modules/.cache/tsdown-stale-guard/hash.yaml'
+   */
+  hashFile?: string;
+  /**
+   * Root directory for resolving relative paths.
+   * @default process.cwd()
+   */
+  root?: string;
+  /**
+   * Whether to hash output files.
+   * @default true
+   */
+  hashOutputs?: boolean;
+}
+interface CheckOptions {
+  /**
+   * Path to the hash file.
+   * @default 'node_modules/.cache/tsdown-stale-guard/hash.yaml'
+   */
+  hashFile?: string;
+  /**
+   * Root directory for resolving relative paths.
+   * @default process.cwd()
+   */
+  root?: string;
+}
+//#endregion
+//#region src/check.d.ts
+declare function checkBuildFreshness(options?: CheckOptions): Promise<CheckResult>;
+//#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>;
+//#endregion
+//#region src/plugin.d.ts
+declare function TsdownStaleGuard(options?: TsdownStaleGuardPluginOptions): Plugin;
+//#endregion
+export { type CheckChange, type CheckOptions, type CheckResult, TsdownStaleGuard, type TsdownStaleGuardData, type TsdownStaleGuardEntry, type TsdownStaleGuardPluginOptions, checkBuildFreshness, parseHashFile, readHashFile, serializeHashFile };

package/dist/index.mjs

@@ -0,0 +1,115 @@
+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 { 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 = [
+	"pnpm-lock.yaml",
+	"yarn.lock",
+	"package-lock.json",
+	"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) {
+		for (const name of names) {
+			const candidate = join(dir, name);
+			if (existsSync(candidate)) return candidate;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+}
+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 = {}) {
+	const { hashFile: hashFilePath = DEFAULT_HASH_FILE, hashOutputs = true } = options;
+	const sourceIds = /* @__PURE__ */ new Set();
+	let root;
+	return {
+		name: "tsdown-stale-guard",
+		buildStart() {
+			root = options.root || process.cwd();
+		},
+		transform: {
+			filter: { id: { exclude: [RE_NODE_MODULES] } },
+			handler(_code, id) {
+				const cleanId = id.replace(RE_QUERY, "");
+				if (cleanId.startsWith("/") || RE_WINDOWS_DRIVE.test(cleanId)) sourceIds.add(cleanId);
+			}
+		},
+		async writeBundle(opts) {
+			const outDir = opts.dir || resolve(root, "dist");
+			const resolvedHashFile = resolve(root, hashFilePath);
+			const sources = await hashFiles([...sourceIds].filter((f) => existsSync(f)), root);
+			let outputs = [];
+			if (hashOutputs && existsSync(outDir)) {
+				const files = await readdir(outDir, {
+					recursive: true,
+					withFileTypes: true
+				});
+				const outputPaths = [];
+				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)),
+					hash
+				};
+			}
+			let lockfileEntry;
+			const lockfilePath = detectPackageLock(root);
+			if (lockfilePath) {
+				const hash = await hashFile(lockfilePath);
+				lockfileEntry = {
+					file: toForwardSlash(relative(root, lockfilePath)),
+					hash
+				};
+			}
+			await writeHashFile(resolvedHashFile, {
+				version: 1,
+				hash: computeCompositeHash([
+					...sources,
+					...outputs,
+					...config ? [config] : [],
+					...lockfileEntry ? [lockfileEntry] : []
+				]),
+				config,
+				lockfile: lockfileEntry,
+				sources,
+				outputs
+			});
+		}
+	};
+}
+function toForwardSlash(p) {
+	return p.replace(/\\/g, "/");
+}
+//#endregion
+export { TsdownStaleGuard, checkBuildFreshness, parseHashFile, readHashFile, serializeHashFile };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "tsdown-stale-guard",
+  "type": "module",
+  "version": "0.0.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antfu/tsdown-stale-guard.git"
+  },
+  "bugs": "https://github.com/antfu/tsdown-stale-guard/issues",
+  "keywords": [
+    "tsdown",
+    "build",
+    "stale",
+    "hash",
+    "freshness"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./cli": "./dist/cli.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "tsdown-stale-guard": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^8.2.0",
+    "@antfu/ni": "^30.0.0",
+    "@antfu/utils": "^9.3.0",
+    "@types/node": "^25.6.0",
+    "bumpp": "^11.0.1",
+    "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",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.8",
+    "vitest": "^4.1.4"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && pnpm run build && npx lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "dev": "tsdown --watch",
+    "lint": "eslint",
+    "release": "bumpp",
+    "start": "tsx src/index.ts",
+    "test": "vitest",
+    "typecheck": "tsc"
+  }
+}