rulebookguard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Carlos Jimenez
+
+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

@@ -1,3 +1,308 @@
-# Temporary Holding Version
+# rulebookguard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Keep business rules as the single source of truth, readable by humans and AI, and bound to the code and tests that implement them.
+
+Business rules usually end up scattered across code, tickets and people's memory. Neither a developer's memory nor an AI model's reading of the code is deterministic. `rulebookguard` keeps each rule in its own small Markdown file, links it to the code it governs (anchors) and to the tests that prove it (`@rule` tags), and fails CI when they drift apart.
+
+- **Atomic rules.** One file per rule, with YAML frontmatter validated against a versioned JSON Schema.
+- **Progressive disclosure.** Contexts map (L0), `id + summary` per context (L1), the full rule (L2), so neither people nor AI models have to read the whole catalog.
+- **Inverse index.** Given a file path, list the active rules anchored to it. Deterministic glob matching, no embeddings.
+- **Linter.** Untested rules, tags pointing at missing or deprecated rules, dead anchors, invalid files, and rules changed without a test change.
+
+It is language-agnostic: rules are Markdown, and tests in any language link to them through a comment.
+
+## Install
+
+Requires Node.js 22 or later.
+
+```sh
+npx rulebookguard lint
+```
+
+Or add it to a project:
+
+```sh
+npm install --save-dev rulebookguard
+```
+
+## Configuration
+
+Put `rulebookguard.config.yaml` at the repository root. Commands find it by walking up from the current directory, and every path in the catalog is relative to the directory that holds it.
+
+```yaml
+schema: 1
+rulesDir: docs/rules # default: docs/rules
+testGlobs: # required: files scanned for @rule tags
+  - 'src/**/*.test.ts'
+  - 'tests/**/test_*.py'
+contextBudget: 30 # default: 30; lint warns when a context holds more rules
+```
+
+`schema` and `testGlobs` are required (`testGlobs: []` is valid but finds no tags). Unknown fields are rejected. The JSON Schemas ship with the package under `rulebookguard/schemas/v1/`.
+
+Inside a git work tree, files are listed with `git ls-files --cached --others --exclude-standard`, so anything in `.gitignore` (`dist/`, `coverage/`, caches) is never matched by anchors or test globs; files inside submodules are listed too. A submodule path that is a symlink, or that resolves outside the rulebook root, is skipped. A test file that is a symlink is scanned for `@rule` tags only when its target lies inside the rulebook root. If one submodule cannot be listed, commands print `warning: could not list files of submodule "<path>" (<reason>); skipping it.` and keep the rest of the git listing. Outside git, or when the rulebook root itself is git-ignored, the whole tree is walked, skipping only `.git` and `node_modules`. If git fails (for example, git is missing from `PATH` or the repository has dubious ownership), commands print one warning on stderr and walk the tree instead.
+
+## Catalog layout
+
+Rules are grouped by context, one directory per context:
+
+```text
+docs/rules/
+  clients/
+    _context.md       # the context: name, id prefix, summary
+    R-CLI-001.md      # one rule per file, named after its id
+    R-CLI-002.md
+  billing/
+    _context.md
+    R-BIL-001.md
+```
+
+`_context.md`:
+
+```markdown
+---
+context: clients
+prefix: CLI
+summary: Customers that receive installation services.
+---
+
+The clients context owns customer identity and contact data.
+```
+
+The `context` field must match the directory name, and every rule id in the directory must start with `R-<prefix>-`.
+
+## Rule file format
+
+````markdown
+---
+id: R-CLI-001
+context: clients
+entities: [Client]
+status: active
+supersedes: R-CLI-000
+anchors:
+  - 'src/clients/**/*.ts'
+  - 'src/api/clients.controller.ts'
+summary: A client document number is unique per country.
+---
+
+# Unique document number
+
+Two clients in the same country cannot share a document number.
+The check ignores letter case and leading zeros.
+
+```gherkin
+Scenario: Duplicate document in the same country
+  Given a client with document "00123" in "VE"
+  When another client is created with document "123" in "VE"
+  Then the creation is rejected with "document already registered"
+```
+````
+
+| Field        | Required | Meaning                                                          |
+| ------------ | -------- | ---------------------------------------------------------------- |
+| `id`         | yes      | `R-<PREFIX>-<NNN>`, three digits, unique, equal to the file name |
+| `context`    | yes      | the context directory the rule lives in                          |
+| `entities`   | yes      | domain entities the rule talks about                             |
+| `status`     | yes      | `proposed`, `active` or `deprecated`                             |
+| `supersedes` | no       | id of the rule this one replaces                                 |
+| `anchors`    | yes      | repo-relative globs of the code that implements the rule         |
+| `summary`    | yes      | one line; this is what `list` shows                              |
+
+The Markdown body holds the full rule and its examples (Gherkin scenarios or tables). Rules do not list their tests: the link lives only in the tests, through `@rule` tags.
+
+## 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.
+
+TypeScript or JavaScript:
+
+```ts
+// @rule R-CLI-001
+it('rejects a duplicate document in the same country', () => {
+  /* ... */
+});
+```
+
+Go:
+
+```go
+// @rule R-CLI-001 @rule R-BIL-001
+func TestCreateClient(t *testing.T) {}
+```
+
+Python:
+
+```python
+# @rule R-CLI-001
+def test_duplicate_document():
+    ...
+```
+
+Java or Kotlin:
+
+```java
+/** @rule R-CLI-001 */
+@Test
+void rejectsDuplicateDocument() {}
+```
+
+SQL:
+
+```sql
+-- @rule R-BIL-002
+SELECT count(*) FROM invoices WHERE number IS NULL;
+```
+
+## Commands
+
+`rulebookguard --help` prints the command list. Exit codes: `0` success, `1` failure (unknown id or context, missing config, lint errors, git errors), `2` usage error (unknown command or option, missing or extra argument).
+
+The read commands (`contexts`, `list`, `show`, `for`, `impact`) accept `--json` for machine consumers. When the catalog has problems they still run, and print one warning on stderr pointing at `lint`.
+
+### `contexts` (L0)
+
+```sh
+$ rulebookguard contexts
+billing (BIL, 2 rules): Invoices and taxes charged to clients.
+clients (CLI, 3 rules): Customers that receive installation services.
+```
+
+### `list [--context <c>] [--status <s>]` (L1)
+
+```sh
+$ rulebookguard list --context clients --status active
+R-CLI-001 [active] A client document number is unique per country.
+```
+
+Exits 1 for an unknown context and 2 for an invalid status.
+
+### `show <id>` (L2)
+
+```sh
+$ rulebookguard show R-CLI-001
+R-CLI-001: A client document number is unique per country.
+context: clients
+status: active
+entities: Client
+anchors: src/clients/**/*.ts, src/api/clients.controller.ts
+supersedes: R-CLI-000
+file: docs/rules/clients/R-CLI-001.md
+
+# Unique document number
+...
+```
+
+Exits 1 for an unknown id.
+
+### `for <path>`
+
+Active rules whose anchors match a path, relative to the current directory. This is what an editor hook or an AI agent asks before touching a file.
+
+```sh
+$ rulebookguard for src/clients/create.ts
+R-CLI-001 (clients): A client document number is unique per country.
+```
+
+Exits 1 when the path is outside the rulebook root.
+
+### `impact <id>`
+
+Files matched by a rule's anchors and the tests tagging it.
+
+```sh
+$ rulebookguard impact R-CLI-001
+R-CLI-001: A client document number is unique per country.
+Files matched by anchors (2):
+  src/clients/create.ts
+  src/clients/update.ts
+Tests tagging R-CLI-001 (1):
+  src/clients/create.test.ts:12
+```
+
+Exits 1 for an unknown id.
+
+### `new <context>`
+
+Scaffolds the next free id of a context as a `proposed` rule and prints its path. Ids are never reused, and an existing file is never overwritten.
+
+```sh
+$ rulebookguard new clients
+docs/rules/clients/R-CLI-004.md
+```
+
+Exits 1 for an unknown context or when the context has no free id left.
+
+### `lint [--base <ref>] [--json]`
+
+Checks the whole catalog. Each finding is printed as `<severity> <code> <file>[:line] <message>`, followed by a count.
+
+| Severity | Code                     | Meaning                                                          |
+| -------- | ------------------------ | ---------------------------------------------------------------- |
+| error    | `untested-rule`          | an active rule has no test tagging it                            |
+| error    | `unknown-rule-tag`       | a test tags a rule id that does not exist                        |
+| error    | `deprecated-rule-tag`    | a test tags a deprecated rule                                    |
+| error    | `unmatched-anchor`       | an anchor glob matches no file                                   |
+| error    | `schema`                 | a config, context or rule file breaks the JSON Schema            |
+| error    | `duplicate-id`           | two rule files share an id                                       |
+| error    | `file-name-mismatch`     | a rule file is not named `<id>.md`                               |
+| error    | `id-prefix-mismatch`     | a rule id does not use its context prefix                        |
+| error    | `context-mismatch`       | a `context` field does not match its directory                   |
+| error    | `missing-context-file`   | a context directory has no `_context.md`                         |
+| error    | `missing-rules-dir`      | `rulesDir` does not exist                                        |
+| error    | `pending-implementation` | with `--base`: an active rule changed, but none of its tests did |
+| warning  | `context-over-budget`    | a context holds more rules than `contextBudget`                  |
+
+```sh
+$ rulebookguard lint
+error untested-rule docs/rules/billing/R-BIL-002.md active rule R-BIL-002 has no test tagging it
+warning context-over-budget docs/rules/clients/_context.md context "clients" has 31 rules, more than the contextBudget of 30
+1 error, 1 warning
+```
+
+Exits 1 when there is any error, and 0 when there are only warnings or nothing at all (`No issues found.`). An invalid `rulebookguard.config.yaml` is reported as `schema` findings too; tags of a rule file that fails the schema are not reported again as `unknown-rule-tag`.
+
+With `--base <ref>`, lint also compares `<ref>` with the working tree (`git diff --name-only <ref>` plus untracked files, so uncommitted work counts). A rule whose file changed must come with a change in at least one test that tags it, otherwise it is reported as `pending-implementation`; an active rule that no test tags at all is reported only as `untested-rule`. Only rules whose status is `active` after the change are checked: new active rules are checked, `proposed` and `deprecated` rules are not. Outside a git work tree, with a ref git cannot resolve, or when git fails while listing the changes, lint fails with exit code 1.
+
+```sh
+$ rulebookguard lint --base origin/main
+error pending-implementation docs/rules/clients/R-CLI-001.md rule R-CLI-001 changed since origin/main but none of the tests tagging it changed
+1 error, 0 warnings
+```
+
+`--json` prints `{ "findings": [{ "severity", "code", "file", "line"?, "message" }], "errors", "warnings" }`.
+
+## CI recipe
+
+Run the linter on every pull request, comparing against the main branch. The full history is needed so that `origin/main` exists.
+
+```yaml
+name: rules
+on: pull_request
+
+jobs:
+  rulebookguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0
+      - run: npx --yes rulebookguard@0.1.0 lint --base origin/main
+```
+
+Pin the version, or add rulebookguard as a dev dependency and run it from the lockfile, so a new release never changes CI results by itself.
+
+## Releasing
+
+Releases are published to npm from GitHub Actions with [trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored and every version carries a provenance attestation. To release, bump `version` in `package.json`, merge it to `main`, then push a matching tag:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `Release` workflow fails without publishing when the tag does not match the package version, or when `vp check`, `vp test` or `vp pack` fails.
+
+## License
+
+MIT

package/dist/cli.d.mts

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

package/dist/cli.mjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+import { M as FormatError, N as formatIssue, _ as expandGlobs, a as CliError, c as openCatalog, d as scanTestTags, h as rulesForPath, l as writeJson, o as findRule, r as lintCommand, s as gitFallbackWarning, u as writeLines, y as toRepoPath } from "./lint-V-Uw5ueZ.mjs";
+import { readdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+// src/commands/new.ts
+const MAX_NUMBER = 999;
+async function newCommand(catalog, io, name) {
+	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.`);
+	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).`);
+	const id = `R-${context.prefix}-${String(last + 1).padStart(3, "0")}`;
+	const file = `${directory}/${id}.md`;
+	try {
+		await writeFile(join(catalog.root, file), template(id, context.context), { flag: "wx" });
+	} catch (error) {
+		if (error.code === "EEXIST") throw new CliError(`${file} already exists; nothing was written.`);
+		throw error;
+	}
+	writeLines(io, [file]);
+}
+function template(id, context) {
+	return `---
+id: ${id}
+context: ${context}
+entities: []
+status: proposed
+anchors: []
+summary: 'TODO: one-line summary of the rule.'
+---
+
+# TODO: rule title
+
+TODO: state the rule in full, then add examples as Gherkin scenarios or tables.
+
+\`\`\`gherkin
+Scenario: TODO
+  Given TODO
+  When TODO
+  Then TODO
+\`\`\`
+`;
+}
+// src/commands/read.ts
+const RULE_STATUSES = [
+	"proposed",
+	"active",
+	"deprecated"
+];
+function contextsCommand(catalog, io, json) {
+	const contexts = [...catalog.contexts].sort((a, b) => compare(a.context, b.context)).map(({ context, prefix, summary, file }) => ({
+		context,
+		prefix,
+		summary,
+		rules: catalog.rules.filter((rule) => rule.context === context).length,
+		file
+	}));
+	if (json) {
+		writeJson(io, { contexts });
+		return;
+	}
+	writeLines(io, contexts.map((item) => `${item.context} (${item.prefix}, ${item.rules} ${item.rules === 1 ? "rule" : "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 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;
+	}
+	writeLines(io, rules.map((rule) => `${rule.id} [${rule.status}] ${rule.summary}`));
+}
+function showCommand(catalog, io, id, json) {
+	const rule = findRule(catalog, id);
+	if (json) {
+		writeJson(io, { rule: {
+			...toSummary(rule),
+			entities: rule.entities,
+			anchors: rule.anchors,
+			supersedes: rule.supersedes ?? null,
+			file: rule.file,
+			body: rule.body
+		} });
+		return;
+	}
+	const header = [
+		`${rule.id}: ${rule.summary}`,
+		`context: ${rule.context}`,
+		`status: ${rule.status}`,
+		`entities: ${rule.entities.join(", ")}`,
+		`anchors: ${rule.anchors.join(", ")}`,
+		...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 rules = rulesForPath(catalog.rules, path).filter((rule) => rule.status === "active").map((rule) => ({
+		...toSummary(rule),
+		file: rule.file
+	}));
+	if (json) {
+		writeJson(io, {
+			path,
+			rules
+		});
+		return;
+	}
+	if (rules.length === 0) {
+		writeLines(io, [`No active rules anchored to ${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 files = await expandGlobs(catalog.root, rule.anchors, warn);
+	const tests = (await scanTestTags(catalog.root, catalog.config.testGlobs, warn)).get(id) ?? [];
+	if (json) {
+		writeJson(io, {
+			id,
+			files,
+			tests
+		});
+		return;
+	}
+	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}`))
+	]);
+}
+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}.`);
+	return path;
+}
+function toSummary(rule) {
+	return {
+		id: rule.id,
+		context: rule.context,
+		status: rule.status,
+		summary: rule.summary
+	};
+}
+function indent(lines) {
+	return lines.length === 0 ? ["  (none)"] : lines.map((line) => `  ${line}`);
+}
+function sortById(rules) {
+	return [...rules].sort((a, b) => compare(a.id, b.id));
+}
+function compare(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+// src/commands/run.ts
+const USAGE = `Usage: rulebookguard <command> [options]
+
+Commands:
+  contexts [--json]                                  L0: list the contexts
+  list [--context <c>] [--status <s>] [--json]       L1: id and summary of each rule
+  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
+  lint [--base <ref>] [--json]                       check the catalog, anchors and test tags;
+                                                     --base: rules changed since <ref> need a changed test
+
+Exit codes: 0 success, 1 failure (lint: any error), 2 usage error.
+`;
+const JSON_OPTION = { json: { type: "boolean" } };
+const COMMANDS = {
+	contexts: {
+		usage: "rulebookguard contexts [--json]",
+		options: JSON_OPTION
+	},
+	list: {
+		usage: "rulebookguard list [--context <c>] [--status <s>] [--json]",
+		options: {
+			...JSON_OPTION,
+			context: { type: "string" },
+			status: { type: "string" }
+		}
+	},
+	show: {
+		usage: "rulebookguard show <id> [--json]",
+		argument: "id",
+		options: JSON_OPTION
+	},
+	for: {
+		usage: "rulebookguard for <path> [--json]",
+		argument: "path",
+		options: JSON_OPTION
+	},
+	impact: {
+		usage: "rulebookguard impact <id> [--json]",
+		argument: "id",
+		options: JSON_OPTION
+	},
+	new: {
+		usage: "rulebookguard new <context>",
+		argument: "context",
+		options: {}
+	},
+	lint: {
+		usage: "rulebookguard lint [--base <ref>] [--json]",
+		options: {
+			...JSON_OPTION,
+			base: { type: "string" }
+		}
+	}
+};
+async function runCli(argv, io) {
+	try {
+		return await dispatch(argv, io);
+	} catch (error) {
+		if (error instanceof CliError) {
+			io.stderr(`${error.message}\n`);
+			return error.exitCode;
+		}
+		if (error instanceof FormatError) {
+			io.stderr(`${error.issues.map(formatIssue).join("\n")}\n`);
+			return 1;
+		}
+		throw error;
+	}
+}
+async function dispatch(argv, io) {
+	const [name, ...rest] = argv;
+	if (name === void 0 || name === "--help" || name === "-h" || name === "help") {
+		io.stdout(USAGE);
+		return 0;
+	}
+	const spec = COMMANDS[name];
+	if (spec === void 0) throw new CliError(`Unknown command "${name}".\n${USAGE.trimEnd()}`, 2);
+	const { values, argument } = parse(spec, rest);
+	const json = values.json === true;
+	if (name === "lint") return lintCommand(io, {
+		base: values.base,
+		json
+	});
+	const catalog = await openCatalog(io);
+	switch (name) {
+		case "contexts":
+			contextsCommand(catalog, io, json);
+			break;
+		case "list":
+			listCommand(catalog, io, {
+				context: values.context,
+				status: values.status,
+				json
+			});
+			break;
+		case "show":
+			showCommand(catalog, io, argument, json);
+			break;
+		case "for":
+			forCommand(catalog, io, argument, json);
+			break;
+		case "impact":
+			await impactCommand(catalog, io, argument, json);
+			break;
+		case "new": await newCommand(catalog, io, argument);
+	}
+	return 0;
+}
+function parse(spec, args) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args,
+			options: spec.options,
+			allowPositionals: true,
+			strict: true
+		});
+	} catch (error) {
+		throw new CliError(`${error.message}\nUsage: ${spec.usage}`, 2);
+	}
+	const expected = spec.argument === void 0 ? 0 : 1;
+	if (parsed.positionals.length < expected) throw new CliError(`Missing argument <${spec.argument}>. Usage: ${spec.usage}`, 2);
+	if (parsed.positionals.length > expected) throw new CliError(`Unexpected argument "${parsed.positionals[expected]}". Usage: ${spec.usage}`, 2);
+	return {
+		values: parsed.values,
+		argument: parsed.positionals[0] ?? ""
+	};
+}
+// src/cli.ts
+process.exitCode = await runCli(process.argv.slice(2), {
+	cwd: process.cwd(),
+	stdout: (text) => process.stdout.write(text),
+	stderr: (text) => process.stderr.write(text)
+});
+export {};