rulebookguard 0.5.1 → 0.7.0

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { M as FormatError, N as formatIssue, a as CliError, c as openCatalog, d as scanTestTags, f as findRulebookRoot, g as expandGlobs, l as writeJson, o as findRule, p as loadCatalog, r as lintCommand, s as gitFallbackWarning, u as writeLines, v as toRepoPath } from "./lint-C1yUeLOq.mjs";
-import { t as rulesForPath } from "./anchors-BFJCm1NU.mjs";
-import { readdir, writeFile } from "node:fs/promises";
+import { F as messages, I as FormatError, L as formatIssue, O as CONTEXT_FILE_NAME, _ as expandGlobs, a as CliError, c as openCatalog, f as scanTestTags, l as writeJson, m as loadCatalog, o as findRule, p as findRulebookRoot, r as lintCommand, s as gitFallbackWarning, u as writeLines, y as toRepoPath } from "./lint-DfibQDW3.mjs";
+import { t as rulesForPath } from "./anchors-C2j9c5MI.mjs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
@@ -80,7 +80,7 @@ function render(path, rules, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.5.1";
+var version = "0.7.0";
 // src/mcp/server.ts
 function createRulesServer(projectDir) {
 	const server = new McpServer({
@@ -136,24 +136,71 @@ async function mcpCommand(io, project) {
 }
 // src/commands/new.ts
 const MAX_NUMBER = 999;
-async function newCommand(catalog, io, name) {
+const CONTEXT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+const PREFIX = /^[A-Z][A-Z0-9]*$/;
+async function newCommand(catalog, io, name, prefix) {
+	const text = messages(catalog.config.language);
 	const context = catalog.contexts.find((item) => item.context === name);
-	if (context === void 0) throw new CliError(`Unknown context "${name}". Run "rulebookguard contexts" to list them.`);
+	if (context !== void 0) {
+		if (prefix !== void 0 && prefix !== context.prefix) throw new CliError(text.prefixMismatch(name, context.prefix, prefix));
+		writeLines(io, [await writeNextRule(catalog, context, text)]);
+		return;
+	}
+	const created = await createContext(catalog, name, prefix, text);
+	try {
+		writeLines(io, [created.file, await writeNextRule(catalog, created, text)]);
+	} catch (error) {
+		await rm(join(catalog.root, created.file), { force: true });
+		throw error;
+	}
+}
+async function createContext(catalog, name, option, text) {
+	if (!CONTEXT_NAME.test(name)) throw new CliError(text.invalidContextName(name));
+	const prefix = option ?? name.replace(/[^a-z0-9]/g, "").slice(0, 3).toUpperCase();
+	if (!PREFIX.test(prefix)) throw new CliError(text.invalidPrefix(prefix));
+	const owner = catalog.contexts.find((item) => item.prefix === prefix);
+	if (owner !== void 0) throw new CliError(text.prefixTaken(prefix, owner.context));
+	const directory = `${toRepoPath(catalog.config.rulesDir).replace(/\/+$/, "")}/${name}`;
+	const file = `${directory}/${CONTEXT_FILE_NAME}`;
+	await mkdir(join(catalog.root, directory), { recursive: true });
+	await writeNew(catalog, file, contextTemplate(name, prefix, text), text);
+	return {
+		file,
+		context: name,
+		prefix,
+		summary: "",
+		body: ""
+	};
+}
+async function writeNextRule(catalog, context, text) {
 	const directory = context.file.slice(0, context.file.lastIndexOf("/"));
 	const idPattern = new RegExp(`^R-${context.prefix}-([0-9]{3})$`);
 	const fileNames = (await readdir(join(catalog.root, directory))).filter((file) => file.endsWith(".md")).map((file) => file.slice(0, -3));
 	const taken = [...catalog.rules.map((rule) => rule.id), ...fileNames].map((id) => idPattern.exec(id)?.[1]).filter((digits) => digits !== void 0).map(Number);
 	const last = Math.max(0, ...taken);
-	if (last >= MAX_NUMBER) throw new CliError(`No free rule id left in context "${name}" (R-${context.prefix}-${MAX_NUMBER} is taken).`);
+	if (last >= MAX_NUMBER) throw new CliError(text.noFreeId(context.context, `R-${context.prefix}-${MAX_NUMBER}`));
 	const id = `R-${context.prefix}-${String(last + 1).padStart(3, "0")}`;
 	const file = `${directory}/${id}.md`;
+	await writeNew(catalog, file, ruleTemplate(id, context.context, catalog.config.language ?? "en"), text);
+	return file;
+}
+async function writeNew(catalog, file, content, text) {
 	try {
-		await writeFile(join(catalog.root, file), template(id, context.context, catalog.config.language ?? "en"), { flag: "wx" });
+		await writeFile(join(catalog.root, file), content, { flag: "wx" });
 	} catch (error) {
-		if (error.code === "EEXIST") throw new CliError(`${file} already exists; nothing was written.`);
+		if (error.code === "EEXIST") throw new CliError(text.alreadyExists(file));
 		throw error;
 	}
-	writeLines(io, [file]);
+}
+function contextTemplate(name, prefix, text) {
+	return `---
+context: ${name}
+prefix: ${prefix}
+summary: '${text.contextTemplateSummary}'
+---
+
+${text.contextTemplateBody}
+`;
 }
 const TEMPLATE_TEXT = {
 	en: {
@@ -176,7 +223,7 @@ Escenario: TODO
   Entonces TODO`
 	}
 };
-function template(id, context, language) {
+function ruleTemplate(id, context, language) {
 	const text = TEMPLATE_TEXT[language];
 	return `---
 id: ${id}
@@ -214,17 +261,26 @@ function contextsCommand(catalog, io, json) {
 		writeJson(io, { contexts });
 		return;
 	}
-	writeLines(io, contexts.map((item) => `${item.context} (${item.prefix}, ${item.rules} ${item.rules === 1 ? "rule" : "rules"}): ${item.summary}`));
+	if (contexts.length === 0) {
+		writeLines(io, [messages(catalog.config.language).noContexts]);
+		return;
+	}
+	writeLines(io, contexts.map((item) => `${item.context} (${item.prefix}, ${messages(catalog.config.language).ruleCount(item.rules)}): ${item.summary}`));
 }
 function listCommand(catalog, io, options) {
 	const { context, status } = options;
-	if (status !== void 0 && !RULE_STATUSES.includes(status)) throw new CliError(`Invalid status "${status}": expected one of ${RULE_STATUSES.join(", ")}.`, 2);
-	if (context !== void 0 && !catalog.contexts.some((item) => item.context === context)) throw new CliError(`Unknown context "${context}". Run "rulebookguard contexts" to list them.`);
+	const text = messages(catalog.config.language);
+	if (status !== void 0 && !RULE_STATUSES.includes(status)) throw new CliError(text.invalidStatus(status, RULE_STATUSES.join(", ")), 2);
+	if (context !== void 0 && !catalog.contexts.some((item) => item.context === context)) throw new CliError(text.unknownContext(context));
 	const rules = sortById(catalog.rules).filter((rule) => context === void 0 || rule.context === context).filter((rule) => status === void 0 || rule.status === status).map(toSummary);
 	if (options.json) {
 		writeJson(io, { rules });
 		return;
 	}
+	if (rules.length === 0) {
+		writeLines(io, [text.noRules]);
+		return;
+	}
 	writeLines(io, rules.map((rule) => `${rule.id} [${rule.status}] ${rule.summary}`));
 }
 function showCommand(catalog, io, id, json) {
@@ -240,19 +296,22 @@ function showCommand(catalog, io, id, json) {
 		} });
 		return;
 	}
+	const none = messages(catalog.config.language).none;
 	const header = [
 		`${rule.id}: ${rule.summary}`,
 		`context: ${rule.context}`,
 		`status: ${rule.status}`,
-		`entities: ${rule.entities.join(", ")}`,
-		`anchors: ${rule.anchors.join(", ")}`,
+		`entities: ${rule.entities.length === 0 ? none : rule.entities.join(", ")}`,
+		"anchors:",
+		...indent(rule.anchors, none),
 		...rule.supersedes === void 0 ? [] : [`supersedes: ${rule.supersedes}`],
 		`file: ${rule.file}`
 	];
 	io.stdout(`${header.join("\n")}\n\n${rule.body}`);
 }
 function forCommand(catalog, io, input, json) {
-	const path = toRootPath(catalog.root, resolve(io.cwd, input), input);
+	const text = messages(catalog.config.language);
+	const path = toRootPath(catalog, resolve(io.cwd, input), input);
 	const rules = rulesForPath(catalog.rules, path).filter((rule) => rule.status === "active").map((rule) => ({
 		...toSummary(rule),
 		file: rule.file
@@ -265,14 +324,15 @@ function forCommand(catalog, io, input, json) {
 		return;
 	}
 	if (rules.length === 0) {
-		writeLines(io, [`No active rules anchored to ${path}.`]);
+		writeLines(io, [text.noActiveRulesFor(path)]);
 		return;
 	}
 	writeLines(io, rules.map((rule) => `${rule.id} (${rule.context}): ${rule.summary}`));
 }
 async function impactCommand(catalog, io, id, json) {
 	const rule = findRule(catalog, id);
-	const warn = gitFallbackWarning(io);
+	const text = messages(catalog.config.language);
+	const warn = gitFallbackWarning(io, catalog.config.language);
 	const files = await expandGlobs(catalog.root, rule.anchors, warn);
 	const tests = (await scanTestTags(catalog.root, catalog.config.testGlobs, warn)).get(id) ?? [];
 	if (json) {
@@ -285,15 +345,15 @@ async function impactCommand(catalog, io, id, json) {
 	}
 	writeLines(io, [
 		`${rule.id}: ${rule.summary}`,
-		`Files matched by anchors (${files.length}):`,
-		...indent(files),
-		`Tests tagging ${rule.id} (${tests.length}):`,
-		...indent(tests.map((test) => `${test.file}:${test.line}`))
+		text.filesMatched(files.length),
+		...indent(files, text.none),
+		text.testsTagging(rule.id, tests.length),
+		...indent(tests.map((test) => `${test.file}:${test.line}`), text.none)
 	]);
 }
-function toRootPath(root, absolute, input) {
-	const path = toRepoPath(relative(root, absolute));
-	if (path === "" || path === ".." || path.startsWith("../") || isAbsolute(path)) throw new CliError(`Path "${input}" is outside the rulebook root ${root}.`);
+function toRootPath(catalog, absolute, input) {
+	const path = toRepoPath(relative(catalog.root, absolute));
+	if (path === "" || path === ".." || path.startsWith("../") || isAbsolute(path)) throw new CliError(messages(catalog.config.language).outsideRoot(input, catalog.root));
 	return path;
 }
 function toSummary(rule) {
@@ -304,8 +364,8 @@ function toSummary(rule) {
 		summary: rule.summary
 	};
 }
-function indent(lines) {
-	return lines.length === 0 ? ["  (none)"] : lines.map((line) => `  ${line}`);
+function indent(lines, none) {
+	return lines.length === 0 ? [`  ${none}`] : lines.map((line) => `  ${line}`);
 }
 function sortById(rules) {
 	return [...rules].sort((a, b) => compare(a.id, b.id));
@@ -322,11 +382,14 @@ Commands:
   show <id> [--json]                                 L2: the full rule
   for <path> [--json]                                active rules anchored to a path
   impact <id> [--json]                               files matched by a rule's anchors and tests tagging it
-  new <context>                                      scaffold the next free rule id as a proposed rule
+  new <context> [--prefix <P>]                       scaffold the next free rule id as a proposed rule;
+                                                     creates the context first when it does not exist,
+                                                     --prefix: its id prefix (default: first 3 letters)
   lint [--base <ref>] [--json]                       check the catalog, anchors and test tags;
                                                      --base: rules changed since <ref> need a changed test
-  hook                                               Claude Code PreToolUse hook: reads the event on stdin
-                                                     and prints the rules anchored to the edited file
+  hook                                               Claude Code hook for PreToolUse and PostToolUse: reads
+                                                     the event on stdin and prints the rules anchored to
+                                                     the file of the tool (Read, Edit, Write...)
   mcp [--project <dir>]                              MCP server over stdio with rules_for and rules_show;
                                                      --project: directory to find the rulebook from (default: cwd)
   site:generate [--out <dir>] [--base <path>]        build the read-only static site of the rulebook (alias: site);
@@ -372,9 +435,9 @@ const COMMANDS = {
 		options: JSON_OPTION
 	},
 	new: {
-		usage: "rulebookguard new <context>",
+		usage: "rulebookguard new <context> [--prefix <P>]",
 		argument: "context",
-		options: {}
+		options: { prefix: { type: "string" } }
 	},
 	hook: {
 		usage: "rulebookguard hook",
@@ -416,7 +479,7 @@ async function runCli(argv, io) {
 			return error.exitCode;
 		}
 		if (error instanceof FormatError) {
-			io.stderr(`${error.issues.map(formatIssue).join("\n")}\n`);
+			io.stderr(`${error.issues.map((issue) => formatIssue(issue)).join("\n")}\n`);
 			return 1;
 		}
 		throw error;
@@ -441,7 +504,7 @@ async function dispatch(argv, io) {
 		return 0;
 	}
 	if (name === "site" || name === "site:generate" || name === "site:run") {
-		const { siteCommand } = await import("./site-BiiOPVEe.mjs");
+		const { siteCommand } = await import("./site-DmY5YVte.mjs");
 		await siteCommand(io, {
 			out: values.out,
 			base: values.base,
@@ -475,7 +538,7 @@ async function dispatch(argv, io) {
 		case "impact":
 			await impactCommand(catalog, io, argument, json);
 			break;
-		case "new": await newCommand(catalog, io, argument);
+		case "new": await newCommand(catalog, io, argument, values.prefix);
 	}
 	return 0;
 }

package/dist/index.d.mts

@@ -1,5 +1,9 @@
 type RuleStatus = "proposed" | "active" | "deprecated";
 type RuleLanguage = "en" | "es";
+interface ParseOptions {
+  /** Language of the issue messages; `en` when unset. */
+  language?: RuleLanguage | undefined;
+}
 interface RulebookConfig {
   schema: 1;
   rulesDir: string;
@@ -34,8 +38,8 @@ export declare const CONFIG_FILE_NAME = "rulebookguard.config.yaml";
 export declare function parseConfig(source: string, file: string): RulebookConfig;
 export declare function loadConfig(path: string): Promise<RulebookConfig>;
 export declare const CONTEXT_FILE_NAME = "_context.md";
-export declare function parseContext(source: string, file: string): ContextDoc;
-export declare function loadContext(path: string): Promise<ContextDoc>;
+export declare function parseContext(source: string, file: string, { language }?: ParseOptions): ContextDoc;
+export declare function loadContext(path: string, options?: ParseOptions): Promise<ContextDoc>;
 interface FormatIssue {
   file: string;
   field?: string;
@@ -50,16 +54,29 @@ interface Frontmatter {
   data: unknown;
   body: string;
 }
-export declare function splitFrontmatter(source: string, file: string): Frontmatter;
+export declare function splitFrontmatter(source: string, file: string, { language }?: ParseOptions): Frontmatter;
 export declare function isRuleId(value: string): boolean;
-export declare function parseRule(source: string, file: string): RuleDoc;
-export declare function loadRule(path: string): Promise<RuleDoc>;
+export declare function parseRule(source: string, file: string, { language }?: ParseOptions): RuleDoc;
+export declare function loadRule(path: string, options?: ParseOptions): Promise<RuleDoc>;
 interface RuleTag {
   id: string;
   line: number;
 }
+interface RuleRegion extends RuleTag {
+  endLine: number;
+}
+type RuleTagProblemCode = "unclosed-rule-tag" | "unmatched-endrule-tag";
+interface RuleTagProblem extends RuleTag {
+  code: RuleTagProblemCode;
+}
+interface RuleRegions {
+  regions: RuleRegion[];
+  problems: RuleTagProblem[];
+}
 export declare const RULE_TAG_PATTERN: RegExp;
+export declare const RULE_MARKER_PATTERN: RegExp;
 export declare function findRuleTags(source: string): RuleTag[];
+export declare function findRuleRegions(source: string): RuleRegions;
 export declare function rulesForPath(rules: RuleDoc[], path: string): RuleDoc[];
 export declare function toRepoPath(path: string): string;
 export declare function createGlobMatcher(globs: string[]): (path: string) => boolean;
@@ -89,8 +106,22 @@ interface TagLocation {
   file: string;
   line: number;
 }
+interface TagRegion extends TagLocation {
+  endLine: number;
+}
+interface TagProblem extends TagLocation {
+  code: RuleTagProblemCode;
+  id: string;
+}
 type TagIndex = Map<string, TagLocation[]>;
+type RegionIndex = Map<string, TagRegion[]>;
+interface TagScan {
+  tags: TagIndex;
+  regions: RegionIndex;
+  problems: TagProblem[];
+}
 export declare function scanTestTags(root: string, testGlobs: string[], onGitFallback?: GitFallbackListener): Promise<TagIndex>;
+export declare function scanTestRegions(root: string, testGlobs: string[], onGitFallback?: GitFallbackListener): Promise<TagScan>;
 interface ContextsJson {
   contexts: {
     context: string;
@@ -129,6 +160,8 @@ interface ImpactJson {
   files: string[];
   tests: TagLocation[];
 }
+/** Changed spans in the working tree; a pure deletion sits between two lines, as `n + 0.5`. */
+type LineSpan = [start: number, end: number];
 type LintSeverity = "error" | "warning";
 interface LintFinding {
   severity: LintSeverity;
@@ -136,6 +169,8 @@ interface LintFinding {
   file: string;
   line?: number;
   message: string;
+  /** One line on how to fix the finding. */
+  hint: string;
 }
 interface LintJson {
   findings: LintFinding[];
@@ -146,7 +181,7 @@ interface LintOptions {
   base?: string | undefined;
   json: boolean;
 }
-export declare function lintCatalog(catalog: Catalog, tags?: TagIndex, onGitFallback?: GitFallbackListener): Promise<LintFinding[]>;
-export declare function pendingImplementation(catalog: Catalog, tags: TagIndex, base: string, changed: string[]): LintFinding[];
+export declare function lintCatalog(catalog: Catalog, scan?: TagScan, onGitFallback?: GitFallbackListener): Promise<LintFinding[]>;
+export declare function pendingImplementation(catalog: Catalog, scan: TagScan, base: string, changed: string[], lines: Map<string, LineSpan[]>): LintFinding[];
 export declare function formatFinding(finding: LintFinding): string;
-export type { Catalog, CatalogIssue, CatalogIssueCode, ContextDoc, ContextFrontmatter, ContextsJson, ForJson, FormatIssue, Frontmatter, GitFallbackListener, ImpactJson, LintFinding, LintJson, LintOptions, LintSeverity, ListJson, RuleDoc, RuleFrontmatter, RuleLanguage, RuleStatus, RuleSummaryJson, RuleTag, RulebookConfig, ShowJson, TagIndex, TagLocation };
+export type { Catalog, CatalogIssue, CatalogIssueCode, ContextDoc, ContextFrontmatter, ContextsJson, ForJson, FormatIssue, Frontmatter, GitFallbackListener, ImpactJson, LintFinding, LintJson, LintOptions, LintSeverity, ListJson, ParseOptions, RegionIndex, RuleDoc, RuleFrontmatter, RuleLanguage, RuleRegion, RuleRegions, RuleStatus, RuleSummaryJson, RuleTag, RuleTagProblem, RuleTagProblemCode, RulebookConfig, ShowJson, TagIndex, TagLocation, TagProblem, TagRegion, TagScan };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { A as loadConfig, C as loadRule, D as parseContext, E as loadContext, M as FormatError, N as formatIssue, O as splitFrontmatter, S as isRuleId, T as CONTEXT_FILE_NAME, _ as listRepoFiles, b as RULE_TAG_PATTERN, d as scanTestTags, f as findRulebookRoot, g as expandGlobs, h as createGlobMatcher, i as pendingImplementation, j as parseConfig, k as CONFIG_FILE_NAME, m as relativeToRoot, n as lintCatalog, p as loadCatalog, t as formatFinding, v as toRepoPath, w as parseRule, x as findRuleTags } from "./lint-C1yUeLOq.mjs";
-import { t as rulesForPath } from "./anchors-BFJCm1NU.mjs";
-export { CONFIG_FILE_NAME, CONTEXT_FILE_NAME, FormatError, RULE_TAG_PATTERN, createGlobMatcher, expandGlobs, findRuleTags, findRulebookRoot, formatFinding, formatIssue, isRuleId, lintCatalog, listRepoFiles, loadCatalog, loadConfig, loadContext, loadRule, parseConfig, parseContext, parseRule, pendingImplementation, relativeToRoot, rulesForPath, scanTestTags, splitFrontmatter, toRepoPath };
+import { A as parseContext, C as findRuleRegions, D as parseRule, E as loadRule, I as FormatError, L as formatIssue, M as CONFIG_FILE_NAME, N as loadConfig, O as CONTEXT_FILE_NAME, P as parseConfig, S as RULE_TAG_PATTERN, T as isRuleId, _ as expandGlobs, d as scanTestRegions, f as scanTestTags, g as createGlobMatcher, h as relativeToRoot, i as pendingImplementation, j as splitFrontmatter, k as loadContext, m as loadCatalog, n as lintCatalog, p as findRulebookRoot, t as formatFinding, v as listRepoFiles, w as findRuleTags, x as RULE_MARKER_PATTERN, y as toRepoPath } from "./lint-DfibQDW3.mjs";
+import { t as rulesForPath } from "./anchors-C2j9c5MI.mjs";
+export { CONFIG_FILE_NAME, CONTEXT_FILE_NAME, FormatError, RULE_MARKER_PATTERN, RULE_TAG_PATTERN, createGlobMatcher, expandGlobs, findRuleRegions, findRuleTags, findRulebookRoot, formatFinding, formatIssue, isRuleId, lintCatalog, listRepoFiles, loadCatalog, loadConfig, loadContext, loadRule, parseConfig, parseContext, parseRule, pendingImplementation, relativeToRoot, rulesForPath, scanTestRegions, scanTestTags, splitFrontmatter, toRepoPath };