@alveolus/arch 0.2.0 → 0.3.0

package/README.md

@@ -35,8 +35,14 @@ Seventeen rules, each with a page that says what it reports, why, how to fix it
 cannot see. A baseline for existing projects, `error` / `warn` / `info` levels, disable comments
 with a reason, JSON and SARIF output for the pull request.
 
+The documentation is installed with the package, for you and for a coding agent:
+`npx alveolus explain layers/no-impure-domain` prints a rule, `npx alveolus explain aggregates` a
+building block, and `npx alveolus init` writes the configuration and the instructions that tell
+Claude Code, Cursor or Codex to read them there.
+
 - [Rules](https://alveolus.dev/rules/)
 - [Getting started](https://alveolus.dev/guide/getting-started)
 - [Adopt it on an existing project](https://alveolus.dev/guide/existing-project)
+- [Coding agents](https://alveolus.dev/guide/agents)
 
 Node.js 24 or later. MIT.

package/dist/bin.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-import { t as Cli } from "./cli-P5PwH9OE.mjs";
+import { r as Cli, t as Docs } from "./docs-DsQHpTtV.mjs";
+import { fileURLToPath } from "node:url";
 //#region src/bin.ts
-const cli = new Cli(process.stdout, process.stderr, process.cwd(), process.stdout.isTTY);
+const docs = new Docs(fileURLToPath(new URL("../docs/", import.meta.url)));
+const cli = new Cli(process.stdout, process.stderr, process.cwd(), docs, process.stdout.isTTY);
 process.exitCode = await cli.run(process.argv.slice(2));
 //#endregion
 export {};

package/dist/bin.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"bin.mjs","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { Cli } from \"./cli/index.ts\";\n\nconst cli = new Cli(process.stdout, process.stderr, process.cwd(), process.stdout.isTTY);\nprocess.exitCode = await cli.run(process.argv.slice(2));\n"],"mappings":";;;AAGA,MAAM,MAAM,IAAI,IAAI,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,IAAI,GAAG,QAAQ,OAAO,KAAK;AACvF,QAAQ,WAAW,MAAM,IAAI,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC"}
+{"version":3,"file":"bin.mjs","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { fileURLToPath } from \"node:url\";\n\nimport { Cli } from \"./cli/index.ts\";\nimport { Docs } from \"./docs/index.ts\";\n\nconst docs = new Docs(fileURLToPath(new URL(\"../docs/\", import.meta.url)));\nconst cli = new Cli(process.stdout, process.stderr, process.cwd(), docs, process.stdout.isTTY);\nprocess.exitCode = await cli.run(process.argv.slice(2));\n"],"mappings":";;;;AAMA,MAAM,OAAO,IAAI,KAAK,cAAc,IAAI,IAAI,YAAY,YAAY,GAAG,CAAC,CAAC;AACzE,MAAM,MAAM,IAAI,IAAI,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,IAAI,GAAG,MAAM,QAAQ,OAAO,KAAK;AAC7F,QAAQ,WAAW,MAAM,IAAI,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC"}

package/dist/{cli-P5PwH9OE.mjs → docs-DsQHpTtV.mjs}

@@ -1,5 +1,5 @@
 import { Command, CommanderError, Option } from "commander";
-import { existsSync } from "node:fs";
+import { existsSync, globSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, matchesGlob, normalize, relative, resolve, sep } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
@@ -1997,7 +1997,9 @@ var Report = class {
 	text() {
 		const blocks = [];
 		for (const [file, violations] of this.byFile()) blocks.push(this.block(file, violations));
-		return `${[...blocks, this.summary()].join("\n\n")}\n`;
+		const parts = [...blocks, this.summary()];
+		if (blocks.length > 0) parts.push(this.colors.dim("Why, and how to fix it: npx alveolus explain <rule>"));
+		return `${parts.join("\n\n")}\n`;
 	}
 	json() {
 		const { baselined, files, stale, suppressed, violations } = this.input;
@@ -2773,18 +2775,91 @@ var TsMorphImporter = class TsMorphImporter extends Importer {
 		return offset !== "" && !offset.startsWith("..") && !isAbsolute(offset) && !offset.split(/[\\/]/).includes("node_modules");
 	}
 };
+const scaffolds = [
+	{
+		content: `import { defineConfig } from "@alveolus/arch";
+
+export default defineConfig({
+	boundedContexts: {},
+	root: "src",
+});
+`,
+		path: "alveolus.config.ts"
+	},
+	{
+		content: `---
+name: alveolus
+description: Domain-Driven Design with @alveolus/core and @alveolus/arch. Use when writing or changing a class of the domain, the application or an adapter, when a class extends an Alveolus building block, or when alveolus arch check reports a violation.
+---
+
+# Alveolus
+
+The documentation is installed with the package: read it with \`npx alveolus explain <topic>\`, not on the web. \`npx alveolus explain\` lists every topic.
+
+1. Before writing a class, read its building block: \`npx alveolus explain aggregates\`, \`entities\`, \`value-objects\`, \`domain-events\`, \`domain-errors\`, \`ports\`, \`repositories\`, \`command-handlers\`, \`query-handlers\`, \`result\`.
+2. Where a file goes and what each layer may import: \`npx alveolus explain project-layout\`.
+3. After each change, run \`npx alveolus arch check\`.
+4. On a violation, read the rule before changing the code: \`npx alveolus explain <rule>\`, with the rule id of the report, such as \`layers/no-impure-domain\`. Fix the cause: never turn a rule off, add a disable comment or edit \`alveolus.baseline.json\` by hand without asking.
+`,
+		path: ".claude/skills/alveolus/SKILL.md"
+	},
+	{
+		content: `## Alveolus
+
+This project uses Alveolus for Domain-Driven Design: the building blocks of \`@alveolus/core\` and the architecture checks of \`@alveolus/arch\`. The documentation is installed with the package: \`npx alveolus explain\` lists the topics and \`npx alveolus explain <topic>\` prints one, so do not look for it on the web. Run \`npx alveolus arch check\` after each change, and read the rule reported with \`npx alveolus explain <rule>\` before fixing. See \`.claude/skills/alveolus/SKILL.md\`.
+`,
+		marker: "npx alveolus explain",
+		path: "AGENTS.md"
+	}
+];
+//#endregion
+//#region src/init/init.ts
+var Init = class {
+	projectDir;
+	constructor(projectDir) {
+		this.projectDir = projectDir;
+	}
+	run() {
+		const written = [];
+		for (const scaffold of scaffolds) written.push({
+			outcome: this.write(scaffold),
+			path: scaffold.path
+		});
+		return written;
+	}
+	get hint() {
+		const claude = join(this.projectDir, "CLAUDE.md");
+		if (!existsSync(claude)) return;
+		return "CLAUDE.md exists: Claude Code reads it instead of AGENTS.md, so add a line with @AGENTS.md to it.";
+	}
+	write(scaffold) {
+		const path = join(this.projectDir, scaffold.path);
+		if (!existsSync(path)) {
+			mkdirSync(dirname(path), { recursive: true });
+			writeFileSync(path, scaffold.content);
+			return "created";
+		}
+		if (scaffold.marker === void 0) return "kept";
+		const existing = readFileSync(path, "utf8");
+		if (existing.includes(scaffold.marker)) return "kept";
+		writeFileSync(path, `${existing.trimEnd()}\n\n${scaffold.content}`);
+		return "appended";
+	}
+};
 //#endregion
 //#region src/cli/cli.ts
 var Cli = class {
 	stdout;
 	stderr;
 	cwd;
+	docs;
 	colored;
 	exitCode = 0;
-	constructor(stdout, stderr, cwd, colored = false) {
+	constructor(stdout, stderr, cwd, docs, colored = false) {
 		this.stdout = stdout;
 		this.stderr = stderr;
 		this.cwd = cwd;
+		this.docs = docs;
 		this.colored = colored;
 	}
 	async run(args) {
@@ -2804,8 +2879,30 @@ var Cli = class {
 		const arch = program.command("arch").description("Check the architecture of a Domain-Driven Design project");
 		this.withOptions(arch.command("check").description("Report the violations that are not in the baseline")).action((options) => this.check(options));
 		this.withOptions(arch.command("baseline").description(`Write the current violations to ${Baseline.fileName}`)).option("--allow-growth", "write the baseline even when it holds more entries than before").action((options) => this.baseline(options));
+		program.command("explain").description("Print a page of the documentation: a rule, a building block or a guide").argument("[topic]", "a rule id, a building block or a guide; without it, the list of topics").action((topic) => this.explain(topic));
+		program.command("init").description(`Write ${ConfigLoader.fileName}, and the instructions that tell a coding agent to read the documentation installed with the package`).option("--project <dir>", "project directory", ".").action((options) => this.init(options));
 		return program;
 	}
+	explain(topic) {
+		if (topic === void 0) {
+			this.stdout.write(`${this.docs.topics().join("\n")}\n`);
+			return;
+		}
+		const match = this.docs.find(topic);
+		if ("page" in match) {
+			this.stdout.write(match.page.text());
+			return;
+		}
+		const list = match.candidates.length === 0 ? "alveolus explain lists the topics." : `Did you mean ${match.candidates.join(", ")}?`;
+		this.stderr.write(`No page for ${topic}: ${list}\n`);
+		this.exitCode = 1;
+	}
+	init(options) {
+		const init = new Init(resolve(this.cwd, options.project));
+		for (const { outcome, path } of init.run()) this.stdout.write(`${outcome}  ${path}\n`);
+		this.stdout.write(`Name your bounded contexts in ${ConfigLoader.fileName}, then run alveolus arch check.\n`);
+		if (init.hint !== void 0) this.stderr.write(`${init.hint}\n`);
+	}
 	withOptions(command) {
 		return command.option("--project <dir>", "project directory", ".").option("--config <file>", "configuration file", ConfigLoader.fileName).option("--tsconfig <file>", "TypeScript configuration, tsconfig.json or the one set in the configuration file").addOption(new Option("--format <format>", "how violations are printed").choices([
 			"text",
@@ -2869,6 +2966,94 @@ var Cli = class {
 	}
 };
 //#endregion
-export { Config as a, RuleRegistry as c, AllowedPackages as d, Baseline as f, ConfigLoader as i, Rule as l, TsMorphImporter as n, Report as o, Importer as r, Checker as s, Cli as t, Architecture as u };
+//#region src/docs/page.ts
+const html = [
+	{
+		pattern: /<dt>/g,
+		text: "- "
+	},
+	{
+		pattern: /<\/dt>\s*<dd>/g,
+		text: ": "
+	},
+	{
+		pattern: /<[^>\n]+>/g,
+		text: ""
+	},
+	{
+		pattern: /^\t+- /gm,
+		text: "- "
+	},
+	{
+		pattern: /&lt;/g,
+		text: "<"
+	},
+	{
+		pattern: /&gt;/g,
+		text: ">"
+	},
+	{
+		pattern: /&amp;/g,
+		text: "&"
+	}
+];
+const frontmatter = /^---\n([\s\S]*?)\n---\n/;
+var Page = class {
+	topic;
+	source;
+	constructor(topic, source) {
+		this.topic = topic;
+		this.source = source;
+	}
+	get description() {
+		const header = frontmatter.exec(this.source)?.[1] ?? "";
+		return /^description: "?(.*?)"?$/m.exec(header)?.[1] ?? "";
+	}
+	text() {
+		let text = this.source.replace(frontmatter, "");
+		for (const { pattern, text: replacement } of html) text = text.replace(pattern, replacement);
+		return `${text.replace(/\n{3,}/g, "\n\n").trim()}\n`;
+	}
+};
+//#endregion
+//#region src/docs/docs.ts
+var Docs = class Docs {
+	dir;
+	static sections = [
+		"guide",
+		"integrations",
+		"core",
+		"rules"
+	];
+	constructor(dir) {
+		this.dir = dir;
+	}
+	topics() {
+		const topics = [];
+		for (const section of Docs.sections) for (const file of globSync("**/*.md", { cwd: join(this.dir, section) }).sort()) topics.push(this.topicOf(join(section, file)));
+		return topics.sort();
+	}
+	find(name) {
+		const wanted = name.replace(/\.md$/, "").replace(/\/$/, "").replace(/\\/g, "/");
+		const candidates = this.topics().filter((topic) => topic === wanted || topic.endsWith(`/${wanted}`));
+		const exact = candidates.find((topic) => topic === wanted);
+		if (exact !== void 0) return { page: this.read(exact) };
+		if (candidates.length === 1 && candidates[0] !== void 0) return { page: this.read(candidates[0]) };
+		return { candidates };
+	}
+	read(topic) {
+		const path = join(this.dir, ...topic.split("/"));
+		try {
+			return new Page(topic, readFileSync(`${path}.md`, "utf8"));
+		} catch {
+			return new Page(topic, readFileSync(join(path, "index.md"), "utf8"));
+		}
+	}
+	topicOf(file) {
+		return file.split(sep).join("/").replace(/\.md$/, "").replace(/\/index$/, "");
+	}
+};
+//#endregion
+export { TsMorphImporter as a, Config as c, RuleRegistry as d, Rule as f, Baseline as h, Init as i, Report as l, AllowedPackages as m, Page as n, Importer as o, Architecture as p, Cli as r, ConfigLoader as s, Docs as t, Checker as u };
 
-//# sourceMappingURL=cli-P5PwH9OE.mjs.map
+//# sourceMappingURL=docs-DsQHpTtV.mjs.map