rulebookguard 0.5.1 → 0.7.0

package/dist/lint-DfibQDW3.mjs

@@ -0,0 +1,1042 @@
+import { access, lstat, readFile, readdir, realpath } from "node:fs/promises";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { YAMLParseError, parse } from "yaml";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import picomatch from "picomatch";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+// src/format/errors.ts
+function formatIssue(issue) {
+	return issue.field === void 0 ? `${issue.file}: ${issue.message}` : `${issue.file}: field "${issue.field}" ${issue.message}`;
+}
+var FormatError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(issues.map(formatIssue).join("\n"));
+		this.name = "FormatError";
+		this.issues = issues;
+	}
+};
+// src/format/read.ts
+async function readSource(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		throw new FormatError([{
+			file: path,
+			message: `cannot read file (${error.code ?? "unknown error"})`
+		}]);
+	}
+}
+// schemas/v1/config.schema.json
+var config_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "urn:rulebookguard:schema:v1:config",
+	title: "rulebookguard.config.yaml",
+	type: "object",
+	properties: {
+		"schema": { "const": 1 },
+		"rulesDir": {
+			"type": "string",
+			"minLength": 1,
+			"default": "docs/rules"
+		},
+		"testGlobs": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			}
+		},
+		"contextBudget": {
+			"type": "integer",
+			"minimum": 1,
+			"default": 30
+		},
+		"language": { "enum": ["en", "es"] }
+	},
+	required: ["schema", "testGlobs"],
+	additionalProperties: false
+};
+// schemas/v1/context.schema.json
+var context_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "urn:rulebookguard:schema:v1:context",
+	title: "_context.md frontmatter",
+	type: "object",
+	properties: {
+		"context": {
+			"type": "string",
+			"minLength": 1
+		},
+		"prefix": {
+			"type": "string",
+			"pattern": "^[A-Z][A-Z0-9]*$"
+		},
+		"summary": {
+			"type": "string",
+			"minLength": 1,
+			"pattern": "^[^\\r\\n]*$"
+		}
+	},
+	required: [
+		"context",
+		"prefix",
+		"summary"
+	],
+	additionalProperties: false
+};
+// schemas/v1/rule.schema.json
+var rule_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "urn:rulebookguard:schema:v1:rule",
+	title: "Rule file frontmatter",
+	type: "object",
+	$defs: { "ruleId": {
+		"type": "string",
+		"pattern": "^R-[A-Z][A-Z0-9]*-[0-9]{3}$"
+	} },
+	properties: {
+		"id": { "$ref": "#/$defs/ruleId" },
+		"context": {
+			"type": "string",
+			"minLength": 1
+		},
+		"entities": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			}
+		},
+		"status": { "enum": [
+			"proposed",
+			"active",
+			"deprecated"
+		] },
+		"supersedes": { "$ref": "#/$defs/ruleId" },
+		"anchors": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			}
+		},
+		"summary": {
+			"type": "string",
+			"minLength": 1,
+			"pattern": "^[^\\r\\n]*$"
+		}
+	},
+	required: [
+		"id",
+		"context",
+		"entities",
+		"status",
+		"anchors",
+		"summary"
+	],
+	additionalProperties: false
+};
+// src/messages.ts
+const MESSAGES = {
+	en: {
+		field: (name) => `field "${name}"`,
+		missingFrontmatter: "missing YAML frontmatter delimited by \"---\" lines",
+		unclosedFrontmatter: "frontmatter is not closed by a \"---\" line",
+		invalidYaml: (detail) => `invalid YAML: ${detail}`,
+		required: "is required",
+		notAllowed: "is not allowed",
+		oneOf: (values) => `must be one of: ${values}`,
+		equalTo: (value) => `must be equal to ${value}`,
+		singleLine: "must be a single line",
+		ofType: () => void 0,
+		minLength: () => void 0,
+		minimum: () => void 0,
+		pattern: () => void 0,
+		missingRulesDir: "directory does not exist",
+		missingContextFile: "has no _context.md",
+		contextMismatch: (name) => `must match its directory name "${name}"`,
+		fileNameMismatch: (baseName) => `must match the file name "${baseName}"`,
+		idPrefixMismatch: (prefix) => `must use the context prefix "${prefix}"`,
+		duplicateId: (first) => `duplicates the id of ${first}`,
+		catalogWarning: (count) => `warning: the catalog has ${count} format ${count === 1 ? "issue" : "issues"}; run "rulebookguard lint" to see them and to check anchors and test tags.`,
+		unknownRule: (id) => `Unknown rule id "${id}". Run "rulebookguard list" to list them.`,
+		unknownContext: (name) => `Unknown context "${name}". Run "rulebookguard contexts" to list them.`,
+		invalidStatus: (status, allowed) => `Invalid status "${status}": expected one of ${allowed}.`,
+		outsideRoot: (input, root) => `Path "${input}" is outside the rulebook root ${root}.`,
+		gitFallback: (reason) => `warning: git could not list files (${reason}); walking the directory instead.`,
+		submoduleSkipped: (submodule, reason) => `warning: could not list files of submodule "${submodule}" (${reason}); skipping it.`,
+		ruleCount: (count) => `${count} ${count === 1 ? "rule" : "rules"}`,
+		noContexts: "No contexts found. Create one with \"rulebookguard new <context>\".",
+		noRules: "No rules found.",
+		noActiveRulesFor: (path) => `No active rules anchored to ${path}.`,
+		filesMatched: (count) => `Files matched by anchors (${count}):`,
+		testsTagging: (id, count) => `Tests tagging ${id} (${count}):`,
+		none: "(none)",
+		noFreeId: (context, lastId) => `No free rule id left in context "${context}" (${lastId} is taken).`,
+		alreadyExists: (file) => `${file} already exists; nothing was written.`,
+		invalidContextName: (name) => `Invalid context name "${name}": use lowercase letters, digits, "-" or "_", starting with a letter or digit.`,
+		invalidPrefix: (prefix) => `Invalid prefix "${prefix}": use uppercase letters and digits, starting with a letter. Pass one with --prefix.`,
+		prefixTaken: (prefix, context) => `Prefix "${prefix}" is already used by context "${context}". Pass another one with --prefix.`,
+		prefixMismatch: (context, prefix, given) => `Context "${context}" already exists with prefix "${prefix}", not "${given}".`,
+		contextTemplateSummary: "TODO: one-line summary of the context.",
+		contextTemplateBody: "TODO: describe what this context covers and what it leaves out.",
+		untestedRule: (id) => `active rule ${id} has no test tagging it`,
+		unmatchedAnchor: (anchor) => `anchor "${anchor}" matches no file`,
+		unknownRuleTag: (id) => `tags ${id}, which does not exist`,
+		deprecatedRuleTag: (id) => `tags ${id}, which is deprecated`,
+		unclosedRuleTag: (id) => `@rule ${id} has no matching @endrule ${id}`,
+		unmatchedEndruleTag: (id) => `@endrule ${id} has no open @rule ${id} before it`,
+		contextOverBudget: (context, count, budget) => `context "${context}" has ${count} rules, more than the contextBudget of ${budget}`,
+		pendingImplementation: (id, base) => `rule ${id} changed since ${base} but none of the tests tagging it changed`,
+		noIssues: "No issues found.",
+		hintLabel: "hint",
+		catalogHints: {
+			schema: "fix the file as the message says; the JSON Schemas ship under rulebookguard/schemas/v1/",
+			"missing-rules-dir": "create the directory, or set rulesDir in rulebookguard.config.yaml",
+			"missing-context-file": "add a _context.md with context, prefix and summary",
+			"context-mismatch": "make the context field equal to the directory name, or move the file to the matching directory",
+			"file-name-mismatch": "rename the file after the id, or change the id",
+			"id-prefix-mismatch": "change the id to use the context prefix, or move the rule to the context that owns its prefix",
+			"duplicate-id": "give one of the rules another id; \"rulebookguard new <context>\" picks the next free one"
+		},
+		untestedRuleHint: (id) => `wrap a test in a file matched by testGlobs with "@rule ${id}" and "@endrule ${id}", or set the rule's status to proposed`,
+		unmatchedAnchorHint: "fix the glob so it matches the files that implement the rule, or remove it",
+		unknownRuleTagHint: "fix the id in the tag, or create the rule it refers to",
+		deprecatedRuleTagHint: (id, successor) => successor === void 0 ? `tag the rule that replaces ${id}, or remove the tag` : `tag ${successor}, which supersedes ${id}, instead`,
+		unclosedRuleTagHint: (id) => `add "@endrule ${id}" after the last line of the test, or close the inner regions first`,
+		unmatchedEndruleTagHint: (id) => `add "@rule ${id}" before the test, or remove the stray @endrule`,
+		contextOverBudgetHint: "split the context into smaller ones, or raise contextBudget in rulebookguard.config.yaml",
+		pendingImplementationHint: (id) => `update or add a test inside an "@rule ${id}" … "@endrule ${id}" region that covers the changed rule`,
+		lintSummary: (errors, warnings) => `${errors} ${errors === 1 ? "error" : "errors"}, ${warnings} ${warnings === 1 ? "warning" : "warnings"}`,
+		needsWorkTree: (root) => `lint --base needs a git work tree, but ${root} is not inside one.`,
+		unknownRef: (ref) => `Unknown git ref "${ref}".`,
+		cannotListChanged: (ref, reason) => `Cannot list the files changed since "${ref}": ${reason}`
+	},
+	es: {
+		field: (name) => `el campo "${name}"`,
+		missingFrontmatter: "falta el frontmatter YAML delimitado por líneas \"---\"",
+		unclosedFrontmatter: "el frontmatter no se cierra con una línea \"---\"",
+		invalidYaml: (detail) => `YAML inválido: ${detail}`,
+		required: "es obligatorio",
+		notAllowed: "no está permitido",
+		oneOf: (values) => `debe ser uno de: ${values}`,
+		equalTo: (value) => `debe ser igual a ${value}`,
+		singleLine: "debe ocupar una sola línea",
+		ofType: (type) => `debe ser de tipo ${type}`,
+		minLength: (limit) => limit === 1 ? "no puede estar vacío" : `debe tener al menos ${limit} caracteres`,
+		minimum: (limit) => `debe ser mayor o igual que ${limit}`,
+		pattern: (pattern) => `debe cumplir el patrón "${pattern}"`,
+		missingRulesDir: "el directorio no existe",
+		missingContextFile: "no tiene _context.md",
+		contextMismatch: (name) => `debe coincidir con el nombre de su directorio "${name}"`,
+		fileNameMismatch: (baseName) => `debe coincidir con el nombre del archivo "${baseName}"`,
+		idPrefixMismatch: (prefix) => `debe usar el prefijo del contexto "${prefix}"`,
+		duplicateId: (first) => `repite el id de ${first}`,
+		catalogWarning: (count) => `aviso: el catálogo tiene ${count} ${count === 1 ? "problema" : "problemas"} de formato; ejecuta "rulebookguard lint" para verlos y para revisar anchors y etiquetas de test.`,
+		unknownRule: (id) => `No existe la regla "${id}". Ejecuta "rulebookguard list" para ver las reglas.`,
+		unknownContext: (name) => `No existe el contexto "${name}". Ejecuta "rulebookguard contexts" para ver los contextos.`,
+		invalidStatus: (status, allowed) => `Estado "${status}" inválido: debe ser uno de ${allowed}.`,
+		outsideRoot: (input, root) => `La ruta "${input}" está fuera de la raíz del rulebook ${root}.`,
+		gitFallback: (reason) => `aviso: git no pudo listar los archivos (${reason}); se recorre el directorio en su lugar.`,
+		submoduleSkipped: (submodule, reason) => `aviso: no se pudieron listar los archivos del submódulo "${submodule}" (${reason}); se omite.`,
+		ruleCount: (count) => `${count} ${count === 1 ? "regla" : "reglas"}`,
+		noContexts: "No se encontraron contextos. Crea uno con \"rulebookguard new <contexto>\".",
+		noRules: "No se encontraron reglas.",
+		noActiveRulesFor: (path) => `No hay reglas activas ancladas a ${path}.`,
+		filesMatched: (count) => `Archivos que cubren los anchors (${count}):`,
+		testsTagging: (id, count) => `Tests que etiquetan ${id} (${count}):`,
+		none: "(ninguno)",
+		noFreeId: (context, lastId) => `No quedan ids libres en el contexto "${context}" (${lastId} ya existe).`,
+		alreadyExists: (file) => `${file} ya existe; no se escribió nada.`,
+		invalidContextName: (name) => `Nombre de contexto "${name}" inválido: usa minúsculas, dígitos, "-" o "_", empezando por una letra o un dígito.`,
+		invalidPrefix: (prefix) => `Prefijo "${prefix}" inválido: usa mayúsculas y dígitos, empezando por una letra. Indica uno con --prefix.`,
+		prefixTaken: (prefix, context) => `El prefijo "${prefix}" ya lo usa el contexto "${context}". Indica otro con --prefix.`,
+		prefixMismatch: (context, prefix, given) => `El contexto "${context}" ya existe con el prefijo "${prefix}", no "${given}".`,
+		contextTemplateSummary: "TODO: resumen del contexto en una línea.",
+		contextTemplateBody: "TODO: describe qué cubre este contexto y qué queda fuera.",
+		untestedRule: (id) => `la regla activa ${id} no tiene ningún test que la etiquete`,
+		unmatchedAnchor: (anchor) => `el anchor "${anchor}" no coincide con ningún archivo`,
+		unknownRuleTag: (id) => `etiqueta ${id}, que no existe`,
+		deprecatedRuleTag: (id) => `etiqueta ${id}, que está deprecada`,
+		unclosedRuleTag: (id) => `@rule ${id} no tiene su @endrule ${id}`,
+		unmatchedEndruleTag: (id) => `@endrule ${id} no tiene un @rule ${id} abierto antes`,
+		contextOverBudget: (context, count, budget) => `el contexto "${context}" tiene ${count} reglas, más que el contextBudget de ${budget}`,
+		pendingImplementation: (id, base) => `la regla ${id} cambió desde ${base} pero no cambió ninguno de los tests que la etiquetan`,
+		noIssues: "No se encontraron problemas.",
+		hintLabel: "sugerencia",
+		catalogHints: {
+			schema: "corrige el archivo según el mensaje; los JSON Schemas vienen en rulebookguard/schemas/v1/",
+			"missing-rules-dir": "crea el directorio o cambia rulesDir en rulebookguard.config.yaml",
+			"missing-context-file": "agrega un _context.md con context, prefix y summary",
+			"context-mismatch": "iguala el campo context al nombre del directorio o mueve el archivo al directorio que corresponde",
+			"file-name-mismatch": "renombra el archivo según el id o cambia el id",
+			"id-prefix-mismatch": "cambia el id para usar el prefijo del contexto o mueve la regla al contexto dueño de ese prefijo",
+			"duplicate-id": "dale otro id a una de las reglas; \"rulebookguard new <contexto>\" elige el siguiente libre"
+		},
+		untestedRuleHint: (id) => `envuelve un test de un archivo que coincida con testGlobs con "@rule ${id}" y "@endrule ${id}", o cambia el estado de la regla a proposed`,
+		unmatchedAnchorHint: "corrige el glob para que coincida con los archivos que implementan la regla, o quítalo",
+		unknownRuleTagHint: "corrige el id de la etiqueta o crea la regla a la que se refiere",
+		deprecatedRuleTagHint: (id, successor) => successor === void 0 ? `etiqueta la regla que reemplaza a ${id} o quita la etiqueta` : `etiqueta ${successor}, que reemplaza a ${id}`,
+		unclosedRuleTagHint: (id) => `agrega "@endrule ${id}" después de la última línea del test, o cierra antes las regiones internas`,
+		unmatchedEndruleTagHint: (id) => `agrega "@rule ${id}" antes del test, o quita el @endrule que sobra`,
+		contextOverBudgetHint: "divide el contexto en otros más chicos o sube contextBudget en rulebookguard.config.yaml",
+		pendingImplementationHint: (id) => `actualiza o agrega un test dentro de una región "@rule ${id}" … "@endrule ${id}" que cubra el cambio de la regla`,
+		lintSummary: (errors, warnings) => `${errors} ${errors === 1 ? "error" : "errores"}, ${warnings} ${warnings === 1 ? "aviso" : "avisos"}`,
+		needsWorkTree: (root) => `lint --base necesita un work tree de git, pero ${root} no está en uno.`,
+		unknownRef: (ref) => `La referencia de git "${ref}" no existe.`,
+		cannotListChanged: (ref, reason) => `No se pudieron listar los archivos cambiados desde "${ref}": ${reason}`
+	}
+};
+function messages(language) {
+	return MESSAGES[language ?? "en"];
+}
+// src/format/validate.ts
+const ajv = new Ajv2020({
+	allErrors: true,
+	useDefaults: true
+});
+const validators = {
+	config: ajv.compile(config_schema_default),
+	context: ajv.compile(context_schema_default),
+	rule: ajv.compile(rule_schema_default)
+};
+function validate(validator, data, file, { language } = {}) {
+	if (validator(data)) return data;
+	const text = messages(language);
+	throw new FormatError((validator.errors ?? []).map((error) => toIssue(error, file, text)));
+}
+function toIssue(error, file, text) {
+	const base = toFieldPath(error.instancePath);
+	const params = error.params;
+	const fallback = error.message ?? "is invalid";
+	switch (error.keyword) {
+		case "required": return {
+			file,
+			field: join$1(base, String(params.missingProperty)),
+			message: text.required
+		};
+		case "additionalProperties": return {
+			file,
+			field: join$1(base, String(params.additionalProperty)),
+			message: text.notAllowed
+		};
+		case "enum": return withField(file, base, text.oneOf(params.allowedValues.join(", ")));
+		case "const": return withField(file, base, text.equalTo(JSON.stringify(params.allowedValue)));
+		case "pattern":
+			if (params.pattern === "^[^\\r\\n]*$") return withField(file, base, text.singleLine);
+			return withField(file, base, text.pattern(String(params.pattern)) ?? fallback);
+		case "type": return withField(file, base, text.ofType(String(params.type)) ?? fallback);
+		case "minLength": return withField(file, base, text.minLength(Number(params.limit)) ?? fallback);
+		case "minimum": return withField(file, base, text.minimum(Number(params.limit)) ?? fallback);
+		default: return withField(file, base, fallback);
+	}
+}
+function withField(file, field, message) {
+	return field === "" ? {
+		file,
+		message
+	} : {
+		file,
+		field,
+		message
+	};
+}
+function join$1(base, key) {
+	return base === "" ? key : `${base}.${key}`;
+}
+function toFieldPath(instancePath) {
+	return instancePath.split("/").slice(1).map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~")).reduce((path, segment) => /^\d+$/.test(segment) ? `${path}[${segment}]` : join$1(path, segment), "");
+}
+// src/format/yaml.ts
+function parseYaml(source, file, { language } = {}) {
+	try {
+		return parse(source);
+	} catch (error) {
+		if (error instanceof YAMLParseError) throw new FormatError([{
+			file,
+			message: messages(language).invalidYaml(singleLine(error))
+		}]);
+		throw error;
+	}
+}
+function singleLine(error) {
+	const first = (error.message.split("\n")[0] ?? "").replace(/:\s*$/, "");
+	const position = error.linePos?.[0];
+	if (position === void 0 || / at line \d+, column \d+$/.test(first)) return first;
+	return `${first} at line ${position.line}, column ${position.col}`;
+}
+// src/format/config.ts
+const CONFIG_FILE_NAME = "rulebookguard.config.yaml";
+function parseConfig(source, file) {
+	return validate(validators.config, parseYaml(source, file), file);
+}
+async function loadConfig(path) {
+	return parseConfig(await readSource(path), path);
+}
+// src/format/frontmatter.ts
+const OPENING = /^---\r?\n/;
+const CLOSING = /^---[ \t]*(?:\r?\n|$)/m;
+function splitFrontmatter(source, file, { language } = {}) {
+	const text = messages(language);
+	const opening = OPENING.exec(source);
+	if (opening === null) throw new FormatError([{
+		file,
+		message: text.missingFrontmatter
+	}]);
+	const rest = source.slice(opening[0].length);
+	const closing = CLOSING.exec(rest);
+	if (closing === null) throw new FormatError([{
+		file,
+		message: text.unclosedFrontmatter
+	}]);
+	const yaml = rest.slice(0, closing.index);
+	const body = rest.slice(closing.index + closing[0].length).replace(/^(?:\r?\n)+/, "");
+	return {
+		data: parseYaml(yaml, file, { language }),
+		body
+	};
+}
+// src/format/context.ts
+const CONTEXT_FILE_NAME = "_context.md";
+function parseContext(source, file, { language } = {}) {
+	const { data, body } = splitFrontmatter(source, file, { language });
+	return {
+		file,
+		...validate(validators.context, data, file, { language }),
+		body
+	};
+}
+async function loadContext(path, options) {
+	return parseContext(await readSource(path), path, options);
+}
+// src/format/rule.ts
+const RULE_ID = /^R-[A-Z][A-Z0-9]*-[0-9]{3}$/;
+function isRuleId(value) {
+	return RULE_ID.test(value);
+}
+function parseRule(source, file, { language } = {}) {
+	const { data, body } = splitFrontmatter(source, file, { language });
+	return {
+		file,
+		...validate(validators.rule, data, file, { language }),
+		body
+	};
+}
+async function loadRule(path, options) {
+	return parseRule(await readSource(path), path, options);
+}
+// src/format/tag.ts
+const RULE_TAG_PATTERN = /(?<![\w@.-])@rule\s+(R-[A-Z][A-Z0-9]*-[0-9]{3})(?![\w-])/g;
+const RULE_MARKER_PATTERN = /(?<![\w@.-])@(rule|endrule)\s+(R-[A-Z][A-Z0-9]*-[0-9]{3})(?![\w-])/g;
+function findRuleTags(source) {
+	const tags = [];
+	source.split(/\r?\n/).forEach((text, index) => {
+		for (const match of text.matchAll(RULE_TAG_PATTERN)) tags.push({
+			id: match[1],
+			line: index + 1
+		});
+	});
+	return tags;
+}
+function findRuleRegions(source) {
+	const regions = [];
+	const problems = [];
+	const open = [];
+	source.split(/\r?\n/).forEach((text, index) => {
+		const line = index + 1;
+		for (const match of text.matchAll(RULE_MARKER_PATTERN)) {
+			const id = match[2];
+			if (match[1] === "rule") {
+				open.push({
+					id,
+					line
+				});
+				continue;
+			}
+			const at = open.map((tag) => tag.id).lastIndexOf(id);
+			if (at === -1) {
+				problems.push({
+					code: "unmatched-endrule-tag",
+					id,
+					line
+				});
+				continue;
+			}
+			for (const inner of open.splice(at + 1)) problems.push({
+				code: "unclosed-rule-tag",
+				...inner
+			});
+			const start = open.pop();
+			regions.push({
+				...start,
+				endLine: line
+			});
+		}
+	});
+	for (const tag of open) problems.push({
+		code: "unclosed-rule-tag",
+		...tag
+	});
+	problems.sort((a, b) => a.line - b.line);
+	return {
+		regions,
+		problems
+	};
+}
+// src/catalog/git.ts
+const execFileAsync = promisify(execFile);
+const SAFE_CONFIG = ["-c", "core.fsmonitor=false"];
+async function runGit(cwd, args) {
+	const { stdout } = await execFileAsync("git", [...SAFE_CONFIG, ...args], {
+		cwd,
+		maxBuffer: 268435456
+	});
+	return stdout;
+}
+async function gitPaths(cwd, command, args) {
+	return (await runGit(cwd, [
+		command,
+		"-z",
+		...args
+	])).split("\0").filter((path) => path !== "");
+}
+async function isInsideWorkTree(cwd) {
+	try {
+		return (await runGit(cwd, ["rev-parse", "--is-inside-work-tree"])).trim() === "true";
+	} catch {
+		return false;
+	}
+}
+async function isCommitRef(cwd, ref) {
+	if (ref.startsWith("-")) return false;
+	try {
+		await runGit(cwd, [
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			`${ref}^{commit}`
+		]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function changedSince(cwd, ref) {
+	const changed = await gitPaths(cwd, "diff", [
+		"--name-only",
+		"--relative",
+		ref,
+		"--"
+	]);
+	const untracked = await gitPaths(cwd, "ls-files", ["--others", "--exclude-standard"]);
+	return {
+		files: [.../* @__PURE__ */ new Set([...changed, ...untracked])].sort(),
+		untracked: new Set(untracked)
+	};
+}
+async function changedLines(cwd, ref, file) {
+	const diff = await runGit(cwd, [
+		"--literal-pathspecs",
+		"diff",
+		"-U0",
+		"--no-color",
+		"--no-ext-diff",
+		"--no-textconv",
+		"--relative",
+		ref,
+		"--",
+		file
+	]);
+	const spans = [];
+	for (const match of diff.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
+		const start = Number(match[1]);
+		const count = match[2] === void 0 ? 1 : Number(match[2]);
+		spans.push(count === 0 ? [start + .5, start + .5] : [start, start + count - 1]);
+	}
+	return spans;
+}
+function gitFailureReason(error) {
+	const { code, stderr, message } = error;
+	if (code === "ENOENT") return "git was not found";
+	return `${typeof stderr === "string" ? stderr : ""}\n${String(message ?? error)}`.split("\n").map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("warning:"))[0] ?? "git failed";
+}
+function isNotARepository(error) {
+	const { stderr } = error;
+	return typeof stderr === "string" && stderr.includes("not a git repository");
+}
+// src/catalog/files.ts
+const SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set([".git", "node_modules"]);
+const GITLINK_MODE = "160000";
+function toRepoPath(path) {
+	return path.replaceAll("\\", "/").replace(/^(?:\.\/)+/, "");
+}
+function createGlobMatcher(globs) {
+	if (globs.length === 0) return () => false;
+	const isMatch = picomatch(globs);
+	return (path) => isMatch(toRepoPath(path));
+}
+async function listRepoFiles(root, onGitFallback) {
+	return (await listGitFiles(root, {
+		realRoot: await realpath(root),
+		prefix: "",
+		onGitFallback
+	}) ?? await walkFiles(root)).sort();
+}
+async function expandGlobs(root, globs, onGitFallback) {
+	const isMatch = createGlobMatcher(globs);
+	return (await listRepoFiles(root, onGitFallback)).filter(isMatch);
+}
+async function listGitFiles(root, scope) {
+	let listing;
+	try {
+		listing = await listGitIndex(root);
+	} catch (error) {
+		if (isNotARepository(error)) return;
+		if (scope.prefix !== "") throw error;
+		scope.onGitFallback?.(gitFailureReason(error));
+		return;
+	}
+	if (listing === void 0) return;
+	const { files, gitlinks } = listing;
+	for (const gitlink of gitlinks) {
+		const nested = await listSubmoduleFiles(root, gitlink, scope);
+		files.push(...nested.map((file) => `${gitlink}/${file}`));
+	}
+	return files;
+}
+async function listGitIndex(root) {
+	const staged = (await gitPaths(root, "ls-files", ["--stage"])).map(parseStageEntry);
+	const others = await gitPaths(root, "ls-files", ["--others", "--exclude-standard"]);
+	const deleted = new Set(await gitPaths(root, "ls-files", ["--deleted"]));
+	const gitlinks = new Set(staged.filter(({ mode }) => mode === GITLINK_MODE).map(({ path }) => path));
+	const files = [.../* @__PURE__ */ new Set([...staged.map(({ path }) => path), ...others])].filter((file) => !deleted.has(file) && !gitlinks.has(file));
+	if (files.length === 0 && gitlinks.size === 0) return;
+	return {
+		files,
+		gitlinks: [...gitlinks]
+	};
+}
+async function listSubmoduleFiles(root, gitlink, scope) {
+	const dir = join(root, gitlink);
+	const path = `${scope.prefix}${gitlink}`;
+	try {
+		if (!await isContainedEntry(dir, scope.realRoot)) return [];
+		if (!await exists$1(join(dir, ".git"))) return await walkFiles(dir);
+		return await listGitFiles(dir, {
+			...scope,
+			prefix: `${path}/`
+		}) ?? await walkFiles(dir);
+	} catch (error) {
+		scope.onGitFallback?.(gitFailureReason(error), path);
+		return [];
+	}
+}
+async function isContainedEntry(path, realRoot) {
+	try {
+		if ((await lstat(path)).isSymbolicLink()) return false;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+	return resolvesInside(path, realRoot);
+}
+async function resolvesInside(path, realRoot) {
+	let target;
+	try {
+		target = await realpath(path);
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+	const fromRoot = relative(realRoot, target);
+	return fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+}
+function parseStageEntry(entry) {
+	const tab = entry.indexOf("	");
+	return {
+		mode: entry.slice(0, entry.indexOf(" ")),
+		path: entry.slice(tab + 1)
+	};
+}
+async function exists$1(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function walkFiles(root) {
+	const files = [];
+	await walk(root, "", files);
+	return files;
+}
+async function walk(root, prefix, files) {
+	const entries = await readdir(join(root, prefix), { withFileTypes: true });
+	for (const entry of entries) {
+		const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+		if (entry.isDirectory()) {
+			if (!SKIPPED_DIRECTORIES.has(entry.name)) await walk(root, path, files);
+		} else if (entry.isFile()) files.push(path);
+	}
+}
+// src/catalog/load.ts
+async function findRulebookRoot(start) {
+	let directory = resolve(start);
+	for (;;) {
+		if (await exists(join(directory, "rulebookguard.config.yaml"))) return directory;
+		const parent = dirname(directory);
+		if (parent === directory) return;
+		directory = parent;
+	}
+}
+async function loadCatalog(root) {
+	const config = await loadConfig(join(root, CONFIG_FILE_NAME));
+	const catalog = {
+		root,
+		config,
+		contexts: [],
+		rules: [],
+		invalidRuleIds: [],
+		issues: []
+	};
+	const rulesDir = toRepoPath(config.rulesDir).replace(/\/+$/, "");
+	const directories = await listEntries(join(root, rulesDir));
+	if (directories === void 0) {
+		catalog.issues.push({
+			code: "missing-rules-dir",
+			file: rulesDir,
+			message: messages(config.language).missingRulesDir
+		});
+		return catalog;
+	}
+	for (const entry of directories.filter((item) => item.isDirectory())) await loadContextDirectory(catalog, `${rulesDir}/${entry.name}`, entry.name);
+	catalog.issues.push(...findDuplicateIds(catalog.rules, config.language));
+	return catalog;
+}
+async function loadContextDirectory(catalog, dir, name) {
+	const files = (await listEntries(join(catalog.root, dir)) ?? []).filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => entry.name);
+	let context;
+	if (files.includes("_context.md")) {
+		context = await load(catalog, `${dir}/${CONTEXT_FILE_NAME}`, loadContext);
+		if (context !== void 0) {
+			catalog.contexts.push(context);
+			checkContextName(catalog, context, name);
+		}
+	} else catalog.issues.push({
+		code: "missing-context-file",
+		file: dir,
+		message: messages(catalog.config.language).missingContextFile
+	});
+	for (const file of files.filter((item) => item !== CONTEXT_FILE_NAME)) {
+		const rule = await load(catalog, `${dir}/${file}`, loadRule);
+		const baseName = file.slice(0, -3);
+		if (rule === void 0 && isRuleId(baseName)) catalog.invalidRuleIds.push(baseName);
+		if (rule !== void 0) {
+			catalog.rules.push(rule);
+			checkRule(catalog, rule, name, baseName, context);
+		}
+	}
+}
+async function load(catalog, file, loader) {
+	try {
+		return {
+			...await loader(join(catalog.root, file), { language: catalog.config.language }),
+			file
+		};
+	} catch (error) {
+		if (!(error instanceof FormatError)) throw error;
+		for (const issue of error.issues) catalog.issues.push({
+			code: "schema",
+			...issue,
+			file
+		});
+		return;
+	}
+}
+function checkContextName(catalog, doc, name) {
+	if (doc.context !== name) catalog.issues.push({
+		code: "context-mismatch",
+		file: doc.file,
+		field: "context",
+		message: messages(catalog.config.language).contextMismatch(name)
+	});
+}
+function checkRule(catalog, rule, directory, baseName, context) {
+	if (rule.id !== baseName) catalog.issues.push({
+		code: "file-name-mismatch",
+		file: rule.file,
+		field: "id",
+		message: messages(catalog.config.language).fileNameMismatch(baseName)
+	});
+	if (context !== void 0 && !rule.id.startsWith(`R-${context.prefix}-`)) catalog.issues.push({
+		code: "id-prefix-mismatch",
+		file: rule.file,
+		field: "id",
+		message: messages(catalog.config.language).idPrefixMismatch(context.prefix)
+	});
+	checkContextName(catalog, rule, directory);
+}
+function findDuplicateIds(rules, language) {
+	const firstFile = /* @__PURE__ */ new Map();
+	const issues = [];
+	for (const rule of rules) {
+		const first = firstFile.get(rule.id);
+		if (first === void 0) firstFile.set(rule.id, rule.file);
+		else issues.push({
+			code: "duplicate-id",
+			file: rule.file,
+			field: "id",
+			message: messages(language).duplicateId(first)
+		});
+	}
+	return issues;
+}
+async function listEntries(path) {
+	try {
+		return (await readdir(path, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+async function exists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function relativeToRoot(root, path) {
+	return toRepoPath(relative(root, path));
+}
+// src/catalog/tags.ts
+async function scanTestTags(root, testGlobs, onGitFallback) {
+	return (await scanTestRegions(root, testGlobs, onGitFallback)).tags;
+}
+async function scanTestRegions(root, testGlobs, onGitFallback) {
+	const tags = /* @__PURE__ */ new Map();
+	const regions = /* @__PURE__ */ new Map();
+	const problems = [];
+	const realRoot = await realpath(root);
+	for (const file of await expandGlobs(root, testGlobs, onGitFallback)) {
+		const path = join(root, file);
+		if (!await resolvesInside(path, realRoot)) continue;
+		const source = await readFile(path, "utf8");
+		for (const { id, line } of findRuleTags(source)) push(tags, id, {
+			file,
+			line
+		});
+		const found = findRuleRegions(source);
+		for (const { id, line, endLine } of found.regions) push(regions, id, {
+			file,
+			line,
+			endLine
+		});
+		problems.push(...found.problems.map((problem) => ({
+			...problem,
+			file
+		})));
+	}
+	return {
+		tags: sortById(tags),
+		regions: sortById(regions),
+		problems
+	};
+}
+function push(index, id, value) {
+	const values = index.get(id) ?? [];
+	values.push(value);
+	index.set(id, values);
+}
+function sortById(index) {
+	return new Map([...index].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+}
+var CliError = class extends Error {
+	exitCode;
+	constructor(message, exitCode = 1) {
+		super(message);
+		this.name = "CliError";
+		this.exitCode = exitCode;
+	}
+};
+async function requireRulebookRoot(io) {
+	const root = await findRulebookRoot(io.cwd);
+	if (root === void 0) throw new CliError(`${CONFIG_FILE_NAME} not found in ${io.cwd} or any parent directory.`);
+	return root;
+}
+async function openCatalog(io) {
+	const catalog = await loadCatalog(await requireRulebookRoot(io));
+	const count = catalog.issues.length;
+	if (count > 0) io.stderr(`${messages(catalog.config.language).catalogWarning(count)}\n`);
+	return catalog;
+}
+function findRule(catalog, id) {
+	const rule = catalog.rules.find((item) => item.id === id);
+	if (rule === void 0) throw new CliError(messages(catalog.config.language).unknownRule(id));
+	return rule;
+}
+function writeJson(io, value) {
+	io.stdout(`${JSON.stringify(value, null, 2)}\n`);
+}
+function writeLines(io, lines) {
+	io.stdout(lines.map((line) => `${line}\n`).join(""));
+}
+function gitFallbackWarning(io, language) {
+	const text = messages(language);
+	let warned = false;
+	const skipped = /* @__PURE__ */ new Set();
+	return (reason, submodule) => {
+		if (submodule !== void 0) {
+			if (!skipped.has(submodule)) {
+				skipped.add(submodule);
+				io.stderr(`${text.submoduleSkipped(submodule, reason)}\n`);
+			}
+			return;
+		}
+		if (!warned) {
+			warned = true;
+			io.stderr(`${text.gitFallback(reason)}\n`);
+		}
+	};
+}
+// src/commands/lint.ts
+async function lintCommand(io, options) {
+	const root = await requireRulebookRoot(io);
+	let catalog;
+	try {
+		catalog = await loadCatalog(root);
+	} catch (error) {
+		if (!(error instanceof FormatError)) throw error;
+		return report(io, error.issues.map((issue) => issueFinding("schema", {
+			...issue,
+			file: relativeToRoot(root, issue.file)
+		}, messages("en"))), options.json, messages("en"));
+	}
+	const text = messages(catalog.config.language);
+	const changed = options.base === void 0 ? void 0 : await changedFiles(catalog.root, options.base, text);
+	const warn = gitFallbackWarning(io, catalog.config.language);
+	const scan = await scanTestRegions(catalog.root, catalog.config.testGlobs, warn);
+	const findings = await lintCatalog(catalog, scan, warn);
+	if (options.base !== void 0 && changed !== void 0) {
+		const lines = await testLineChanges(catalog, scan, options.base, changed, text);
+		findings.push(...pendingImplementation(catalog, scan, options.base, changed.files, lines));
+	}
+	return report(io, findings, options.json, text);
+}
+function report(io, findings, json, text) {
+	const sorted = sortFindings(findings);
+	const errors = sorted.filter((finding) => finding.severity === "error").length;
+	const warnings = sorted.length - errors;
+	if (json) writeJson(io, {
+		findings: sorted,
+		errors,
+		warnings
+	});
+	else if (sorted.length === 0) writeLines(io, [text.noIssues]);
+	else writeLines(io, [...sorted.flatMap((finding) => [formatFinding(finding), `  ${text.hintLabel}: ${finding.hint}`]), text.lintSummary(errors, warnings)]);
+	return errors > 0 ? 1 : 0;
+}
+function issueFinding(code, { file, field, message }, text) {
+	return error(code, file, field === void 0 ? message : `${text.field(field)} ${message}`, text.catalogHints[code]);
+}
+async function lintCatalog(catalog, scan, onGitFallback) {
+	const { tags: tagIndex, problems } = scan ?? await scanTestRegions(catalog.root, catalog.config.testGlobs, onGitFallback);
+	const text = messages(catalog.config.language);
+	const findings = catalog.issues.map((issue) => issueFinding(issue.code, issue, text));
+	for (const { code, id, file, line } of problems) findings.push(code === "unclosed-rule-tag" ? {
+		...error(code, file, text.unclosedRuleTag(id), text.unclosedRuleTagHint(id)),
+		line
+	} : {
+		...error(code, file, text.unmatchedEndruleTag(id), text.unmatchedEndruleTagHint(id)),
+		line
+	});
+	const files = await listRepoFiles(catalog.root, onGitFallback);
+	const status = new Map(catalog.rules.map((rule) => [rule.id, rule.status]));
+	const invalid = new Set(catalog.invalidRuleIds);
+	const successors = new Map(catalog.rules.filter((rule) => rule.supersedes !== void 0 && rule.status !== "deprecated").map((rule) => [rule.supersedes, rule.id]));
+	for (const rule of catalog.rules) {
+		if (rule.status === "active" && !tagIndex.has(rule.id)) findings.push(error("untested-rule", rule.file, text.untestedRule(rule.id), text.untestedRuleHint(rule.id)));
+		for (const anchor of rule.anchors) if (!files.some(createGlobMatcher([anchor]))) findings.push(error("unmatched-anchor", rule.file, text.unmatchedAnchor(anchor), text.unmatchedAnchorHint));
+	}
+	for (const [id, locations] of tagIndex) {
+		const ruleStatus = status.get(id);
+		if (ruleStatus !== void 0 && ruleStatus !== "deprecated" || invalid.has(id)) continue;
+		for (const { file, line } of locations) findings.push(ruleStatus === void 0 ? {
+			...error("unknown-rule-tag", file, text.unknownRuleTag(id), text.unknownRuleTagHint),
+			line
+		} : {
+			...error("deprecated-rule-tag", file, text.deprecatedRuleTag(id), text.deprecatedRuleTagHint(id, successors.get(id))),
+			line
+		});
+	}
+	const budget = catalog.config.contextBudget;
+	for (const context of catalog.contexts) {
+		const count = catalog.rules.filter((rule) => rule.context === context.context).length;
+		if (count > budget) findings.push({
+			severity: "warning",
+			code: "context-over-budget",
+			file: context.file,
+			message: text.contextOverBudget(context.context, count, budget),
+			hint: text.contextOverBudgetHint
+		});
+	}
+	return findings;
+}
+function pendingImplementation(catalog, scan, base, changed, lines) {
+	const text = messages(catalog.config.language);
+	return changedActiveRules(catalog, scan, changed).filter((rule) => !(scan.regions.get(rule.id) ?? []).some((region) => (lines.get(region.file) ?? []).some(([start, end]) => start <= region.endLine && end >= region.line))).map((rule) => error("pending-implementation", rule.file, text.pendingImplementation(rule.id, base), text.pendingImplementationHint(rule.id)));
+}
+function changedActiveRules(catalog, scan, changed) {
+	const changedSet = new Set(changed);
+	return catalog.rules.filter((rule) => rule.status === "active" && changedSet.has(rule.file) && (scan.tags.get(rule.id) ?? []).length > 0);
+}
+async function testLineChanges(catalog, scan, base, changed, text) {
+	const changedSet = new Set(changed.files);
+	const files = new Set(changedActiveRules(catalog, scan, changed.files).flatMap((rule) => scan.regions.get(rule.id) ?? []).map((region) => region.file).filter((file) => changedSet.has(file)));
+	const lines = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		if (changed.untracked.has(file)) {
+			lines.set(file, [[1, Number.POSITIVE_INFINITY]]);
+			continue;
+		}
+		try {
+			lines.set(file, await changedLines(catalog.root, base, file));
+		} catch (error) {
+			throw new CliError(text.cannotListChanged(base, gitFailureReason(error)));
+		}
+	}
+	return lines;
+}
+async function changedFiles(root, base, text) {
+	if (!await isInsideWorkTree(root)) throw new CliError(text.needsWorkTree(root));
+	if (!await isCommitRef(root, base)) throw new CliError(text.unknownRef(base));
+	try {
+		return await changedSince(root, base);
+	} catch (error) {
+		throw new CliError(text.cannotListChanged(base, gitFailureReason(error)));
+	}
+}
+function formatFinding(finding) {
+	const location = finding.line === void 0 ? finding.file : `${finding.file}:${finding.line}`;
+	return `${finding.severity} ${finding.code} ${location} ${finding.message}`;
+}
+function error(code, file, message, hint) {
+	return {
+		severity: "error",
+		code,
+		file,
+		message,
+		hint
+	};
+}
+function sortFindings(findings) {
+	return [...findings].sort((a, b) => compare(a.file, b.file) || (a.line ?? 0) - (b.line ?? 0) || compare(a.code, b.code));
+}
+function compare(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+export { parseContext as A, findRuleRegions as C, parseRule as D, loadRule as E, messages as F, FormatError as I, formatIssue as L, CONFIG_FILE_NAME as M, loadConfig as N, CONTEXT_FILE_NAME as O, parseConfig as P, RULE_TAG_PATTERN as S, isRuleId as T, expandGlobs as _, CliError as a, runGit as b, openCatalog as c, scanTestRegions as d, scanTestTags as f, createGlobMatcher as g, relativeToRoot as h, pendingImplementation as i, splitFrontmatter as j, loadContext as k, writeJson as l, loadCatalog as m, lintCatalog as n, findRule as o, findRulebookRoot as p, lintCommand as r, gitFallbackWarning as s, formatFinding as t, writeLines as u, listRepoFiles as v, findRuleTags as w, RULE_MARKER_PATTERN as x, toRepoPath as y };