rulebookguard 0.4.0 → 0.5.1

package/README.md

@@ -13,7 +13,7 @@ It is language-agnostic: rules are Markdown, and tests in any language link to t
 
 ## Install
 
-Requires Node.js 22.23.4 or later (the `site:generate` and `site:run` commands build with Astro 7, which needs it).
+Requires Node.js 22 or later.
 
 ```sh
 npx rulebookguard lint
@@ -116,7 +116,13 @@ The Markdown body holds the full rule and its examples (Gherkin scenarios or tab
 
 ## The `@rule` tag
 
-A test links to a rule with `@rule <ID>` inside any comment, in any file matched by `testGlobs`. One comment can carry several tags.
+A test links to a rule with `@rule <ID>` anywhere in a file matched by `testGlobs`. One line can carry several tags. A comment is the usual place, but the tag is matched as text, so it also counts inside a test name or a string:
+
+```ts
+it('rejects a duplicate document @rule R-CLI-001', () => {});
+```
+
+To mention a rule in a test file without linking to it, write the id without the `@rule` prefix.
 
 TypeScript or JavaScript:
 
@@ -262,6 +268,14 @@ The rulebook is found from `--project` (default: the current directory). A comma
 
 ### `site:generate [--out <dir>] [--base <path>]`
 
+The site commands build with Astro, which lives in a separate package so that installing the linter does not download it. Install it next to `rulebookguard` (it requires Node.js 22.23.4 or later):
+
+```sh
+npm install --save-dev rulebookguard @rulebookguard/site
+```
+
+Without it, the site commands fail, exit 1, with `The site commands need the @rulebookguard/site package. Install it next to rulebookguard: npm install --save-dev @rulebookguard/site`. One-off, without installing: `npx -p rulebookguard -p @rulebookguard/site rulebookguard site:run`.
+
 Builds a read-only static site of the rulebook with [Astro Starlight](https://starlight.astro.build) into `--out` (default `site`, relative to the current directory) and prints that path. Open it from disk or publish it as is, for example on GitHub Pages; pass `--base` when it is served from a sub-path (`--base /rules`).
 
 ```sh

package/dist/cli.mjs

@@ -80,7 +80,7 @@ function render(path, rules, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.4.0";
+var version = "0.5.1";
 // src/mcp/server.ts
 function createRulesServer(projectDir) {
 	const server = new McpServer({
@@ -334,6 +334,7 @@ Commands:
   site:run [--out <dir>] [--base <path>] [--port <n>]
                                                      build the site, then serve it on 127.0.0.1 until Ctrl+C;
                                                      --port: port to serve on (default: 4321)
+                                                     site commands need @rulebookguard/site installed
 
 Exit codes: 0 success, 1 failure (lint: any error), 2 usage error.
 `;
@@ -440,7 +441,7 @@ async function dispatch(argv, io) {
 		return 0;
 	}
 	if (name === "site" || name === "site:generate" || name === "site:run") {
-		const { siteCommand } = await import("./site-BgH5724T.mjs");
+		const { siteCommand } = await import("./site-BiiOPVEe.mjs");
 		await siteCommand(io, {
 			out: values.out,
 			base: values.base,

package/dist/{site-BgH5724T.mjs → site-BiiOPVEe.mjs}

@@ -1,12 +1,9 @@
 import { a as CliError, c as openCatalog, d as scanTestTags, g as expandGlobs, n as lintCatalog, s as gitFallbackWarning, u as writeLines, y as runGit } from "./lint-C1yUeLOq.mjs";
-import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createServer } from "node:http";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 // src/site/data.ts
 const FIELD = "";
 async function siteData(catalog, onGitFallback) {
@@ -396,7 +393,7 @@ function demote(markdown) {
 	}).join("\n");
 }
 // src/commands/site.ts
-const execFileAsync = promisify(execFile);
+const SITE_PACKAGE = "@rulebookguard/site";
 /** Marks an output directory as written by `site`, so a rebuild may replace it. */
 const MARKER = ".rulebookguard-site";
 /**
@@ -408,11 +405,12 @@ async function siteCommand(io, options, until = untilInterrupted()) {
 	const fromCwd = relative(io.cwd, out);
 	const shown = fromCwd === "" ? "." : fromCwd.startsWith("..") || isAbsolute(fromCwd) ? out : fromCwd;
 	await assertReplaceable(out, shown);
+	const site = await importSitePackage([catalog.root, dirname(fileURLToPath(import.meta.url))]);
 	const language = catalog.config.language ?? "en";
 	const base = normalizeBase(options.base ?? "/");
 	const server = options.serve ? await listen(out, base, options.port ?? 4321) : void 0;
 	try {
-		await buildSite(catalog, out, language, base, io);
+		await buildSite(site, catalog, out, language, base, io);
 	} catch (error) {
 		server?.close();
 		throw error;
@@ -427,7 +425,21 @@ async function siteCommand(io, options, until = untilInterrupted()) {
 		server.closeAllConnections();
 	});
 }
-async function buildSite(catalog, out, language, base, io) {
+/** Imports the site builder from the first of `from` that resolves it. */
+async function importSitePackage(from) {
+	for (const directory of from) {
+		let entry;
+		try {
+			entry = createRequire(join(directory, "package.json")).resolve(SITE_PACKAGE);
+		} catch (error) {
+			if (error.code === "MODULE_NOT_FOUND") continue;
+			throw error;
+		}
+		return await import(pathToFileURL(entry).href);
+	}
+	throw new CliError(`The site commands need the ${SITE_PACKAGE} package. Install it next to rulebookguard: npm install --save-dev ${SITE_PACKAGE}`);
+}
+async function buildSite(site, catalog, out, language, base, io) {
 	const files = sitePages(await siteData(catalog, gitFallbackWarning(io)), {
 		language,
 		base
@@ -448,25 +460,12 @@ async function buildSite(catalog, out, language, base, io) {
 		}))
 	];
 	files.set("astro.config.mjs", astroConfig(text.title, language, base, sidebar));
-	const work = join(siteWorkRoot(), randomUUID());
 	try {
-		for (const [path, content] of files) {
-			await mkdir(dirname(join(work, path)), { recursive: true });
-			await writeFile(join(work, path), content);
-		}
-		await buildWithAstro(work);
-		await rm(out, {
-			recursive: true,
-			force: true
-		});
-		await cp(join(work, "dist"), out, { recursive: true });
-		await writeFile(join(out, MARKER), "");
-	} finally {
-		await rm(work, {
-			recursive: true,
-			force: true
-		});
+		await site.buildSite(files, out);
+	} catch (error) {
+		throw error instanceof site.SiteBuildError ? new CliError(error.message) : error;
 	}
+	await writeFile(join(out, MARKER), "");
 }
 function untilInterrupted() {
 	return new Promise((stop) => {
@@ -541,25 +540,6 @@ async function sendNotFound(out, response) {
 	const page = await readFile(join(out, "404.html")).catch(() => "Not found");
 	response.writeHead(404, { "content-type": CONTENT_TYPES[".html"] }).end(page);
 }
-/**
-* Starlight injects its routes as package specifiers that Astro resolves from the project root, so the generated
-* project must live inside the node_modules directory that holds rulebookguard's own dependencies.
-*/
-function siteWorkRoot() {
-	let directory = dirname(fileURLToPath(import.meta.url));
-	while (!isOwnPackageRoot(directory)) {
-		const parent = dirname(directory);
-		if (parent === directory) throw new Error("rulebookguard package root not found");
-		directory = parent;
-	}
-	const parent = dirname(directory);
-	const modules = basename(parent) === "node_modules" ? parent : join(directory, "node_modules");
-	return join(modules, ".rulebookguard-site");
-}
-function isOwnPackageRoot(directory) {
-	const file = join(directory, "package.json");
-	return existsSync(file) && JSON.parse(readFileSync(file, "utf8")).name === "rulebookguard";
-}
 async function assertReplaceable(out, shown) {
 	let entries;
 	try {
@@ -570,31 +550,6 @@ async function assertReplaceable(out, shown) {
 	}
 	if (entries.length > 0 && !entries.includes(MARKER)) throw new CliError(`${shown} is not empty and was not written by "rulebookguard site"; choose another --out or empty it first.`);
 }
-async function buildWithAstro(work) {
-	const astro = join(dirname(siteWorkRoot()), "astro");
-	const { bin } = JSON.parse(readFileSync(join(astro, "package.json"), "utf8"));
-	try {
-		await execFileAsync(process.execPath, [
-			join(astro, bin.astro),
-			"build",
-			"--silent"
-		], {
-			cwd: work,
-			env: {
-				...process.env,
-				ASTRO_TELEMETRY_DISABLED: "1"
-			},
-			maxBuffer: 67108864
-		});
-	} catch (error) {
-		const { stderr, stdout } = error;
-		throw new CliError(`The site build failed:\n${astroFailureDetail(`${stderr ?? ""}${stdout ?? ""}`)}`);
-	}
-}
-/** The first lines of Astro's error output, without its stack trace. */
-function astroFailureDetail(output) {
-	return output.split("\n").filter((line) => !/^\s*at /.test(line) && !/^\s*Stack trace:/.test(line)).filter((line) => line.trim() !== "").slice(0, 12).join("\n");
-}
 function astroConfig(title, language, base, sidebar) {
 	return `import starlight from '@astrojs/starlight';
 import { defineConfig } from 'astro/config';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Keep business rules as the single source of truth, bound to code and tests.",
   "homepage": "https://github.com/JuanCJR/rulebookguard#readme",
   "bugs": {
@@ -28,23 +28,29 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.3.2",
-    "@astrojs/starlight": "^0.42.6",
     "@modelcontextprotocol/server": "^2.3.1",
     "ajv": "^8.20.0",
-    "astro": "^7.3.8",
     "picomatch": "^4.0.7",
     "yaml": "^2.9.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.3.1",
+    "@rulebookguard/site": "0.5.1",
     "@types/node": "^20.19.43",
     "@types/picomatch": "^4.0.3",
     "typescript": "^7.0.2",
     "vite-plus": "^1.4.0"
   },
+  "peerDependencies": {
+    "@rulebookguard/site": "^0.5.1"
+  },
+  "peerDependenciesMeta": {
+    "@rulebookguard/site": {
+      "optional": true
+    }
+  },
   "engines": {
-    "node": ">=22.23.4"
+    "node": ">=22"
   }
 }