@alveolus/arch 0.2.0 → 0.4.0

package/README.md

@@ -14,6 +14,11 @@ import { defineConfig } from "@alveolus/arch";
 
 export default defineConfig({
 	boundedContexts: { catalog: "catalog", notifications: "notifications", ordering: "ordering" },
+	contextMap: {
+		catalog: { consumes: [] },
+		notifications: { consumes: ["ordering"] },
+		ordering: { consumes: ["catalog"] },
+	},
 	root: "src",
 	subdomains: { core: ["catalog", "ordering"], generic: ["notifications"] },
 });
@@ -35,8 +40,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-DcFgskuN.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-DcFgskuN.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";
@@ -839,24 +839,22 @@ var Architecture = class {
 };
 //#endregion
 //#region src/architecture/context-map.ts
-var ContextMap = class ContextMap {
+var ContextMap = class {
 	upstreams;
 	constructor(upstreams) {
 		this.upstreams = upstreams;
 	}
-	static ofEdges(edges) {
-		const upstreams = {};
-		for (const { from, to } of edges) {
-			const known = upstreams[from] ?? [];
-			if (!known.includes(to)) upstreams[from] = [...known, to];
-		}
-		return new ContextMap(upstreams);
-	}
 	get contexts() {
-		const names = new Set(Object.keys(this.upstreams));
+		return Object.keys(this.upstreams);
+	}
+	get consumed() {
+		const names = /* @__PURE__ */ new Set();
 		for (const targets of Object.values(this.upstreams)) for (const target of targets) names.add(target);
 		return [...names];
 	}
+	selfConsumers() {
+		return this.contexts.filter((context) => this.allows(context, context));
+	}
 	allows(from, to) {
 		return (this.upstreams[from] ?? []).includes(to);
 	}
@@ -868,9 +866,6 @@ var ContextMap = class ContextMap {
 			if (found !== void 0) return found;
 		}
 	}
-	cycleThrough(from, to) {
-		return this.reaches(to, from, /* @__PURE__ */ new Set());
-	}
 	cycleFrom(context, path, visiting, done) {
 		if (done.has(context)) return;
 		if (visiting.has(context)) return [...path.slice(path.indexOf(context)), context];
@@ -882,12 +877,6 @@ var ContextMap = class ContextMap {
 		visiting.delete(context);
 		done.add(context);
 	}
-	reaches(from, target, seen) {
-		if (from === target) return true;
-		if (seen.has(from)) return false;
-		seen.add(from);
-		return (this.upstreams[from] ?? []).some((upstream) => this.reaches(upstream, target, seen));
-	}
 };
 //#endregion
 //#region src/rules/framework/wording.ts
@@ -1374,23 +1363,13 @@ var NoLeakyHostServiceRule = class extends ClassRule {
 var NoUnmappedContextRule = class extends Rule {
 	meta = {
 		contexts: "every",
-		description: "A bounded context consuming one the context map does not allow, or two contexts that depend on each other.",
+		description: "A bounded context consuming one the context map does not allow.",
 		id: "strategic/no-unmapped-context",
-		messages: {
-			cycle: "{from} consumes {to}, which consumes {from} back: two contexts that depend on each other can no longer change alone; declare a contextMap and reverse one dependency.",
-			unmapped: "{from} consumes {to}, which the context map does not allow: add {to} to contextMap.{from}, or reverse the dependency."
-		}
+		messages: { unmapped: "{from} consumes {to}, which the context map does not allow: reverse the dependency, or if {from} really is downstream of {to}, add {to} to contextMap.{from}.consumes." }
 	};
 	check(architecture) {
-		const consumptions = this.consumptionsIn(architecture);
-		const declared = architecture.contextMap;
 		const findings = [];
-		if (declared !== void 0) {
-			for (const consumption of consumptions) if (!declared.allows(consumption.from, consumption.to)) findings.push(this.consumptionFinding(consumption, "unmapped"));
-			return findings;
-		}
-		const observed = ContextMap.ofEdges(consumptions);
-		for (const consumption of consumptions) if (observed.cycleThrough(consumption.from, consumption.to)) findings.push(this.consumptionFinding(consumption, "cycle"));
+		for (const consumption of this.consumptionsIn(architecture)) if (!architecture.contextMap.allows(consumption.from, consumption.to)) findings.push(this.consumptionFinding(consumption));
 		return findings;
 	}
 	consumptionsIn(architecture) {
@@ -1411,9 +1390,9 @@ var NoUnmappedContextRule = class extends Rule {
 		}
 		return consumptions;
 	}
-	consumptionFinding(consumption, messageId) {
+	consumptionFinding(consumption) {
 		const { dependency, file, from, to } = consumption;
-		return this.finding(file, dependency.line, dependency.label, messageId, {
+		return this.finding(file, dependency.line, dependency.label, "unmapped", {
 			from,
 			to
 		});
@@ -1997,7 +1976,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;
@@ -2116,7 +2097,7 @@ var Config = class {
 		this.applicationDependencies = this.domainDependencies.with(new AllowedPackages(config.applicationDependencies));
 		this.ignored = [...testFiles, ...config.ignore ?? []];
 		this.extraFolders = config.layout?.extraFolders ?? {};
-		this.contextMap = config.contextMap === void 0 ? void 0 : this.validContextMap(config.contextMap, Object.keys(config.boundedContexts));
+		this.contextMap = this.validContextMap(config.contextMap, Object.keys(config.boundedContexts));
 		this.rules = config.rules;
 		const sharedKernel = config.sharedKernel ?? "shared-kernel";
 		this.contextFolders = [...this.classifiedContexts(config.subdomains ?? {}, config.boundedContexts), {
@@ -2150,10 +2131,16 @@ var Config = class {
 		if (unclassified.length > 0) throw new Error(`boundedContexts declares ${unclassified.join(", ")}, which subdomains does not classify: list each context under subdomains.core, subdomains.supporting or subdomains.generic.`);
 		return folders;
 	}
-	validContextMap(upstreams, contexts) {
+	validContextMap(relations, contexts) {
+		const upstreams = {};
+		for (const [name, { consumes }] of Object.entries(relations)) upstreams[name] = consumes;
 		const map = new ContextMap(upstreams);
-		const unknown = map.contexts.filter((name) => !contexts.includes(name));
+		const unknown = [.../* @__PURE__ */ new Set([...map.contexts, ...map.consumed])].filter((name) => !contexts.includes(name));
 		if (unknown.length > 0) throw new Error(`contextMap names ${unknown.join(", ")}, which boundedContexts does not declare.`);
+		const unlisted = contexts.filter((name) => !map.contexts.includes(name));
+		if (unlisted.length > 0) throw new Error(`contextMap does not list ${unlisted.join(", ")}: every bounded context lists the contexts it consumes, consumes: [] when none.`);
+		const selfConsumers = map.selfConsumers();
+		if (selfConsumers.length > 0) throw new Error(`contextMap lists ${selfConsumers.join(", ")} as consuming itself: a context consumes other contexts only.`);
 		const cycle = map.cycle();
 		if (cycle !== void 0) throw new Error(`contextMap has a cycle: ${cycle.join(" → ")}. Two contexts that depend on each other can no longer change alone: reverse one dependency.`);
 		return map;
@@ -2180,7 +2167,7 @@ const schema = z.strictObject({
 	applicationDependencies: packageDependencies.exactOptional(),
 	boundedContexts: z.record(z.string(), z.string()),
 	compositionRoot: z.string().exactOptional(),
-	contextMap: z.record(z.string(), z.array(z.string())).exactOptional(),
+	contextMap: z.record(z.string(), z.strictObject({ consumes: z.array(z.string()) })),
 	domainDependencies: packageDependencies.exactOptional(),
 	ignore: z.array(z.string()).exactOptional(),
 	layout: z.strictObject({ extraFolders: z.strictObject({
@@ -2773,18 +2760,92 @@ 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: {},
+	contextMap: {},
+	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, add a context to \`contextMap\` 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 +2865,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 +2952,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-DcFgskuN.mjs.map