@zaaxch/tailframe 1.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "1.0.0",
+	"version": "2.1.0",
 	"description": "Tailframe architecture toolkit: validates the Tailframe structure, import-boundary, and file-convention contracts. The package version is the contract version.",
 	"type": "module",
 	"bin": {

package/src/architecture.mjs

@@ -148,6 +148,10 @@ function validateStructure(root, kind, fail) {
 }
 
 function validateServiceImport(source, target, external, fail, graph) {
+	if (external === "tsyringe" && source !== "src/app/container.ts") {
+		fail(`${source} may not import tsyringe; dependency-injection framework code is confined to src/app/container.ts`);
+		return;
+	}
 	if (source === "src/server.ts" || source === "src/worker.ts") {
 		if (external) {
 			if (external !== "reflect-metadata") fail(`${source} may import only reflect-metadata and app bootstrap code, not ${external}`);

package/src/conventions.mjs

@@ -15,6 +15,11 @@ const ROUTE_NAMES_CANONICAL_DECLARATION = /\bexport\s+enum\s+RouteNames\b/;
 const ROUTE_NAMES_VALUE = /^\s*[A-Z][A-Z0-9_]*\s*=\s*["']([^"']+)["']/gm;
 const ROUTE_NAME_REFERENCE = /\bname:\s*["']([^"']+)["']/g;
 
+const camel = (kebab) => {
+	const value = kebab.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+	return value[0].toLowerCase() + value.slice(1);
+};
+
 function parseName(fileName) {
 	if (fileName.endsWith(".d.ts")) return undefined;
 	const extension = path.extname(fileName);
@@ -98,6 +103,9 @@ export function validateConventions(rootArgument, kind) {
 		const layer = remainder.split("/")[0];
 		if (kind === "service") validateServiceFile(relative, moduleName, layer, remainder, name, flag);
 		else validateUiFile(relative, moduleName, layer, name, flag);
+		if (kind === "service" && name.extension === ".ts") {
+			validateServiceSource(relative, moduleName, layer, remainder, name, fs.readFileSync(absolute, "utf8"), flag);
+		}
 
 		if (kind === "service" && name.extension === ".ts" && relative !== `${modulePath}/domain/identifiers.ts` &&
 			BRAND_PATTERN.test(fs.readFileSync(absolute, "utf8"))) {
@@ -107,10 +115,86 @@ export function validateConventions(rootArgument, kind) {
 	if (kind === "ui") {
 		validateRouteNames(root, src, flag);
 		validateCanonicalShell(root, flag);
+	} else {
+		validateServiceComposition(root, flag);
 	}
 	return violations;
 }
 
+function validateServiceSource(relative, moduleName, layer, remainder, name, source, flag) {
+	if (layer === "use-cases" && remainder.split("/")[1] !== "ports") {
+		const exportedClasses = [...source.matchAll(/^export\s+class\s+([A-Z][A-Za-z0-9]*)\b/gm)].map((match) => match[1]);
+		if (exportedClasses.length > 1) {
+			flag("G5", relative, `${relative} exports multiple classes (${exportedClasses.join(", ")}); keep one named use-case class per file`);
+		} else if (exportedClasses.length === 1 && exportedClasses[0] !== name.stem) {
+			flag("G1", relative, `${relative} must be named ${exportedClasses[0]}.ts after its exported use-case class`);
+		}
+	}
+
+	if (layer !== "http") return;
+	if (name.role === "routes" && name.subject === moduleName) {
+		const factories = [...source.matchAll(/^export\s+function\s+([A-Za-z][A-Za-z0-9]*Routes)\s*\(/gm)].map((match) => match[1]);
+		const expected = `${camel(moduleName)}Routes`;
+		if (factories.length !== 1 || factories[0] !== expected) {
+			flag("S8", relative, `${relative} must export exactly one module route factory named ${expected}`);
+		}
+		const postCount = [...source.matchAll(/\brouter\.post\s*\(/g)].length;
+		const rpcHandlerCount = [...source.matchAll(/\brpcHandler\s*\(/g)].length;
+		if (postCount > rpcHandlerCount) {
+			flag("S8", relative, `${relative} must translate every RPC POST through rpcHandler; found ${postCount} POST routes and ${rpcHandlerCount} rpcHandler calls`);
+		}
+	}
+	if (name.role === "schemas" && name.subject === moduleName) {
+		const schemas = [...source.matchAll(/^export\s+const\s+([A-Za-z][A-Za-z0-9]*)\s*=/gm)].map((match) => match[1]);
+		if (schemas.length === 0) flag("S8", relative, `${relative} must export at least one PascalCase operation schema`);
+		for (const schema of schemas) {
+			if (!PASCAL.test(schema) || !schema.endsWith("Schema")) {
+				flag("S8", relative, `${relative} exports ${schema}; operation schemas are PascalCase and end with Schema`);
+			}
+		}
+	}
+}
+
+function validateServiceComposition(root, flag) {
+	const containerRelative = "src/app/container.ts";
+	const containerFile = path.join(root, containerRelative);
+	if (!fs.existsSync(containerFile)) {
+		flag("S9", containerRelative, `${containerRelative} is required as the explicit application composition root`);
+	} else {
+		const source = fs.readFileSync(containerFile, "utf8");
+		for (const [pattern, message] of [
+			[/\bexport\s+function\s+registerDependencies\s*\(/, "must export registerDependencies"],
+			[/\bcontainer\.reset\s*\(/, "must reset the container before registration"],
+			[/\bregisterInstance\s*\(/, "must register explicit instances"]
+		]) {
+			if (!pattern.test(source)) flag("S9", containerRelative, `${containerRelative} ${message}`);
+		}
+		if (/\bregisterSingleton\s*\(|\binstanceCachingFactory\s*\(|@inject(?:able)?\b/.test(source)) {
+			flag("S9", containerRelative, `${containerRelative} must use explicit construction and instance registration, not decorators, singleton factories, or implicit resolution`);
+		}
+	}
+
+	const serverRelative = "src/app/server.ts";
+	const serverFile = path.join(root, serverRelative);
+	if (!fs.existsSync(serverFile)) {
+		flag("S9", serverRelative, `${serverRelative} is required as the HTTP application assembly`);
+	} else if (!/\bregisterDependencies\s*\(/.test(fs.readFileSync(serverFile, "utf8"))) {
+		flag("S9", serverRelative, `${serverRelative} must initialize the app-owned composition root after infrastructure connects`);
+	}
+
+	const workerRelative = "src/app/workers/startWorker.ts";
+	const workerFile = path.join(root, workerRelative);
+	if (fs.existsSync(workerFile)) {
+		const source = fs.readFileSync(workerFile, "utf8");
+		if (!/\bregisterDependencies\s*\(/.test(source)) {
+			flag("S9", workerRelative, `${workerRelative} must initialize the same app-owned composition root as the HTTP server`);
+		}
+		if (/\bprocess\.exit\s*\(/.test(source)) {
+			flag("S9", workerRelative, `${workerRelative} must return an awaitable shutdown path instead of forcing process.exit`);
+		}
+	}
+}
+
 function normalizeGeneratedSource(source) {
 	return source.replace(/\r\n/g, "\n");
 }

package/src/generate.mjs

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { loadExceptions, isExcepted } from "./exceptions.mjs";
+import { serviceHttpFiles, serviceOperationName } from "./service-templates.mjs";
+import { moduleApiSource } from "./ui-templates.mjs";
 
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
@@ -52,31 +54,124 @@ function requirePrimary(value, label) {
 	return value;
 }
 
-function operationName(moduleName, verbNoun) {
-	const moduleSuffix = pascal(moduleName);
-	if (verbNoun.endsWith(moduleSuffix) && verbNoun !== moduleSuffix) {
-		const prefix = verbNoun.slice(0, -moduleSuffix.length);
-		return prefix[0].toLowerCase() + prefix.slice(1);
+function edit(relative, update) {
+	return { relative, update };
+}
+
+function insertBefore(source, anchor, content, relative) {
+	const index = source.indexOf(anchor);
+	if (index < 0) fail(`Cannot update ${relative}: canonical insertion point was not found; normalize the file before generating`);
+	if (source.indexOf(anchor, index + anchor.length) >= 0) {
+		fail(`Cannot update ${relative}: canonical insertion point is ambiguous; normalize the file before generating`);
 	}
-	return verbNoun[0].toLowerCase() + verbNoun.slice(1);
+	return `${source.slice(0, index)}${content}${source.slice(index)}`;
 }
 
-function plan(files) {
+function plan(files, edits = []) {
 	return {
 		files,
 		write(root) {
 			const existing = Object.keys(files).filter((relative) => fs.existsSync(path.join(root, relative)));
 			if (existing.length) fail(`Refusing to overwrite existing file(s):\n${existing.map((file) => `  ${file}`).join("\n")}`);
+			const updates = edits.map(({ relative, update }) => {
+				const absolute = path.join(root, relative);
+				if (!fs.existsSync(absolute)) fail(`Cannot update missing generated composition file: ${relative}`);
+				return { relative, absolute, content: update(fs.readFileSync(absolute, "utf8")) };
+			});
 			for (const [relative, content] of Object.entries(files)) {
 				const absolute = path.join(root, relative);
 				fs.mkdirSync(path.dirname(absolute), { recursive: true });
 				fs.writeFileSync(absolute, content);
 			}
-			return Object.keys(files);
+			for (const update of updates) fs.writeFileSync(update.absolute, update.content);
+			return [...Object.keys(files), ...updates.map(({ relative }) => relative)];
 		}
 	};
 }
 
+function registerUseCaseEdit(moduleName, verbNoun) {
+	const relative = "src/app/container.ts";
+	return edit(relative, (source) => {
+		if (new RegExp(`\\b${verbNoun}\\b`).test(source)) fail(`${relative} already references ${verbNoun}`);
+		let next = insertBefore(
+			source,
+			"\nconst register =",
+			`import { ${verbNoun} } from "@/modules/${moduleName}/use-cases/${verbNoun}";\n`,
+			relative
+		);
+		next = insertBefore(next, "\n\treturn container;", `\n\tregister(${verbNoun}, new ${verbNoun}());\n`, relative);
+		return next;
+	});
+}
+
+function mountModuleRoutesEdit(moduleName, verbNoun) {
+	const relative = "src/app/routes.ts";
+	const dependency = serviceOperationName(moduleName, verbNoun);
+	const factory = `${camel(moduleName)}Routes`;
+	return edit(relative, (source) => {
+		if (new RegExp(`\\b${factory}\\b`).test(source)) fail(`${relative} already mounts ${factory}`);
+		let next = insertBefore(
+			source,
+			"\nexport function applicationRoutes",
+			`import { ${verbNoun} } from "@/modules/${moduleName}/use-cases/${verbNoun}";\nimport { ${factory} } from "@/modules/${moduleName}/http/${moduleName}.routes";\n`,
+			relative
+		);
+		next = insertBefore(
+			next,
+			"\n\treturn router;",
+			`\n\trouter.use(\n\t\t${factory}({\n\t\t\t${dependency}: container.resolve(${verbNoun})\n\t\t})\n\t);\n`,
+			relative
+		);
+		return next;
+	});
+}
+
+function extendModuleRoutesEdits(moduleName, verbNoun) {
+	const operation = serviceOperationName(moduleName, verbNoun);
+	const dependency = operation;
+	const schemasRelative = `src/modules/${moduleName}/http/${moduleName}.schemas.ts`;
+	const routesRelative = `src/modules/${moduleName}/http/${moduleName}.routes.ts`;
+	const appRoutesRelative = "src/app/routes.ts";
+	return [
+		edit(schemasRelative, (source) => {
+			if (new RegExp(`\\b${verbNoun}Schema\\b`).test(source)) fail(`${schemasRelative} already defines ${verbNoun}Schema`);
+			return `${source.trimEnd()}\n\nexport const ${verbNoun}Schema = Joi.object({}).unknown(false);\n`;
+		}),
+		edit(routesRelative, (source) => {
+			if (new RegExp(`\\b${verbNoun}\\b`).test(source)) fail(`${routesRelative} already references ${verbNoun}`);
+			let next = insertBefore(
+				source,
+				`import { rpcHandler } from "@/platform/http/rpcHandler";`,
+				`import type { ${verbNoun} } from "@/modules/${moduleName}/use-cases/${verbNoun}";\nimport { ${verbNoun}Schema } from "@/modules/${moduleName}/http/${moduleName}.schemas";\n`,
+				routesRelative
+			);
+			next = insertBefore(next, "\n}\n\nexport function", `\n\t${dependency}: ${verbNoun};`, routesRelative);
+			next = insertBefore(
+				next,
+				"\n\treturn router;",
+				`\n\trouter.post("/${moduleName}.${operation}", rpcHandler(${verbNoun}Schema, useCases.${dependency}));`,
+				routesRelative
+			);
+			return next;
+		}),
+		edit(appRoutesRelative, (source) => {
+			if (new RegExp(`\\b${verbNoun}\\b`).test(source)) fail(`${appRoutesRelative} already references ${verbNoun}`);
+			let next = insertBefore(
+				source,
+				`import { ${camel(moduleName)}Routes } from "@/modules/${moduleName}/http/${moduleName}.routes";`,
+				`import { ${verbNoun} } from "@/modules/${moduleName}/use-cases/${verbNoun}";\n`,
+				appRoutesRelative
+			);
+			const start = next.indexOf(`\t\t${camel(moduleName)}Routes({`);
+			if (start < 0) fail(`Cannot update ${appRoutesRelative}: ${camel(moduleName)}Routes mount was not found`);
+			const end = next.indexOf("\n\t\t})", start);
+			if (end < 0) fail(`Cannot update ${appRoutesRelative}: ${camel(moduleName)}Routes mount is not canonical`);
+			const before = next.slice(0, end).replace(/\n\t\t\t([^\n]+)$/, "\n\t\t\t$1,");
+			return `${before}\n\t\t\t${dependency}: container.resolve(${verbNoun})${next.slice(end)}`;
+		})
+	];
+}
+
 function useCaseFiles(moduleName, verbNoun) {
 	return {
 		[`src/modules/${moduleName}/use-cases/${verbNoun}.ts`]:
@@ -98,61 +193,27 @@ export class ${verbNoun} implements UseCase<${verbNoun}Input, ${verbNoun}Output>
 
 describe("${verbNoun}", () => {
 	it("is not implemented yet", async () => {
-		await expect(new ${verbNoun}().execute({ requestId: "test", roles: [] }, {})).rejects.toThrow();
+		await expect(new ${verbNoun}().execute({ requestId: "test" }, {})).rejects.toThrow();
 	});
 });
 `
 	};
 }
 
-function httpFiles(moduleName, verbNoun) {
-	const operation = operationName(moduleName, verbNoun);
-	const dependency = verbNoun[0].toLowerCase() + verbNoun.slice(1);
-	return {
-		[`src/modules/${moduleName}/http/${moduleName}.schemas.ts`]:
-`import Joi from "joi";
-
-export const ${verbNoun}Schema = Joi.object({}).unknown(false);
-`,
-		[`src/modules/${moduleName}/http/${moduleName}.routes.ts`]:
-`import { Router } from "express";
-import type { ${verbNoun} } from "@/modules/${moduleName}/use-cases/${verbNoun}";
-import { ${verbNoun}Schema } from "@/modules/${moduleName}/http/${moduleName}.schemas";
-import { createRequestContext } from "@/platform/http/createRequestContext";
-import { rpcResult } from "@/platform/http/rpc";
-
-export function ${camel(moduleName)}Routes(${dependency}: ${verbNoun}) {
-	const router = Router();
-	router.post("/${moduleName}.${operation}", async (req, res, next) => {
-		try {
-			const input = await ${verbNoun}Schema.validateAsync(req.body ?? {});
-			rpcResult(res, await ${dependency}.execute(await createRequestContext(req), input));
-		} catch (error) {
-			next(error);
-		}
-	});
-	return router;
-}
-`
-	};
-}
-
 const serviceSchematics = {
 	module(root, [name, verbNoun], options) {
 		requireModuleName(root, name);
 		requirePascal(verbNoun, "First use case", ["UseCases"]);
-		const files = { ...useCaseFiles(name, verbNoun), ...(options.has("--no-http") ? {} : httpFiles(name, verbNoun)) };
-		return [plan(files), [
-			`Register ${verbNoun} in src/app/container.ts`,
-			...(options.has("--no-http") ? [] : [`Mount ${camel(name)}Routes in src/app/routes.ts`]),
+		const files = { ...useCaseFiles(name, verbNoun), ...(options.has("--no-http") ? {} : serviceHttpFiles(name, verbNoun)) };
+		const edits = [registerUseCaseEdit(name, verbNoun), ...(options.has("--no-http") ? [] : [mountModuleRoutesEdit(name, verbNoun)])];
+		return [plan(files, edits), [
 			`Implement ${verbNoun}.execute and replace the placeholder test`
 		]];
 	},
 	"use-case"(root, [moduleName, verbNoun]) {
 		requireModuleName(root, moduleName);
 		requirePascal(verbNoun, "Use case", ["UseCases"]);
-		return [plan(useCaseFiles(moduleName, verbNoun)), [
-			`Register ${verbNoun} in src/app/container.ts`,
+		return [plan(useCaseFiles(moduleName, verbNoun), [registerUseCaseEdit(moduleName, verbNoun)]), [
 			`Expose it from an entry point (http route, worker, job, or cli) if the capability needs one`,
 			`Implement ${verbNoun}.execute and replace the placeholder test`
 		]];
@@ -162,8 +223,15 @@ const serviceSchematics = {
 		requirePascal(verbNoun, "Use case", ["UseCases"]);
 		if (!fs.existsSync(path.join(root, `src/modules/${moduleName}/use-cases/${verbNoun}.ts`)))
 			fail(`Use case src/modules/${moduleName}/use-cases/${verbNoun}.ts does not exist; generate it first`);
-		return [plan(httpFiles(moduleName, verbNoun)), [
-			`Mount ${camel(moduleName)}Routes in src/app/routes.ts`,
+		const schemas = path.join(root, `src/modules/${moduleName}/http/${moduleName}.schemas.ts`);
+		const routes = path.join(root, `src/modules/${moduleName}/http/${moduleName}.routes.ts`);
+		if (fs.existsSync(schemas) !== fs.existsSync(routes)) {
+			fail(`Module ${moduleName} has only one canonical HTTP file; restore both ${moduleName}.schemas.ts and ${moduleName}.routes.ts before generating`);
+		}
+		const firstHttp = !fs.existsSync(schemas);
+		return [plan(firstHttp ? serviceHttpFiles(moduleName, verbNoun) : {}, firstHttp
+			? [mountModuleRoutesEdit(moduleName, verbNoun)]
+			: extendModuleRoutesEdits(moduleName, verbNoun)), [
 			`Define the real request schema in ${moduleName}.schemas.ts`
 		]];
 	},
@@ -247,14 +315,7 @@ ${body}
 function uiArtifacts(moduleName, kindOptions) {
 	const files = {};
 	if (kindOptions.api) {
-		files[`src/modules/${moduleName}/api/${moduleName}.api.ts`] =
-`import { http } from "@/platform/http";
-import type { RpcResponse } from "@/core/rpc";
-
-export async function get${pascal(moduleName)}() {
-	return (await http.post<RpcResponse<unknown>>("${moduleName}.get")).data.result;
-}
-`;
+		files[`src/modules/${moduleName}/api/${moduleName}.api.ts`] = moduleApiSource(moduleName, pascal(moduleName));
 	}
 	if (kindOptions.view) {
 		const viewName = kindOptions.view.endsWith("View") ? kindOptions.view : `${kindOptions.view}View`;