@zaaxch/tailframe 0.1.0 → 0.1.1

package/package.json

@@ -1,13 +1,12 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "Tailframe architecture toolkit: validates the Tailframe structure, import-boundary, and file-convention contracts. The package version is the contract version.",
 	"type": "module",
 	"bin": {
 		"tailframe": "bin/tailframe.mjs"
 	},
 	"files": [
-		"assets",
 		"bin",
 		"src"
 	],

package/src/new.mjs

@@ -33,7 +33,9 @@ const svc = `${options.name}-svc`;
 const ui = `${options.name}-ui`;
 const files = {};
 const add = (relative, content) => { files[relative] = content.endsWith("\n") ? content : `${content}\n`; };
-const architectureValidatorSource = fs.readFileSync(new URL("../assets/validate-architecture.mjs", import.meta.url), "utf8");
+// Generated repositories depend on the published toolkit rather than copying a validator, and they
+// pin the exact contract version they were generated against.
+const contractVersion = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const prettierConfig = {
 	useTabs: true,
 	tabWidth: 4,
@@ -158,6 +160,7 @@ const svcDeps = {
 };
 const svcDevDeps = {
 	"@types/cors": "^2.8.17", "@types/express": "^5.0.1", "@types/jest": "^30.0.0", "@types/node": "^22.13.14", "@types/supertest": "^7.2.1",
+	"@zaaxch/tailframe": contractVersion,
 	jest: "^30.0.0", nodemon: "^3.1.9", prettier: "3.5.3", "ts-jest": "^29.4.11", "ts-node": "^10.9.2",
 	"tsc-alias": "^1.8.16", "tsconfig-paths": "^4.2.0", typescript: "^5.8.2", supertest: "^7.2.2"
 };
@@ -169,14 +172,13 @@ add(`${svc}/package.json`, JSON.stringify({
 		...(options.worker ? { "dev:worker": "nodemon --legacy-watch --exec ts-node -r tsconfig-paths/register src/worker.ts" } : {}),
 		build: "tsc && tsc-alias", start: "node dist/server.js",
 		...(options.worker ? { worker: "node dist/worker.js" } : {}),
-		test: "npm run test:unit && npm run test:integration", "test:unit": "jest --selectProjects unit --runInBand", "test:integration": "jest --selectProjects integration --runInBand", "validate:architecture": "node scripts/validate-architecture.mjs --kind service .", format: "prettier --write src/",
+		test: "npm run test:unit && npm run test:integration", "test:unit": "jest --selectProjects unit --runInBand", "test:integration": "jest --selectProjects integration --runInBand", "validate:architecture": "tailframe validate --kind service .", format: "prettier --write src/",
 		"test:db:up": "docker compose -f docker-compose.test.yml up -d", "test:db:down": "docker compose -f docker-compose.test.yml down -v",
 		"docker:dev": "docker compose -f docker-compose.dev.yml up",
 		"docker:prod": "docker compose -f docker-compose.yml up -d",
 		"docker:push": "bash scripts/build_and_push.sh"
 	}, dependencies: svcDeps, devDependencies: svcDevDeps
 }, null, "\t"));
-add(`${svc}/scripts/validate-architecture.mjs`, architectureValidatorSource);
 add(`${svc}/tsconfig.json`, JSON.stringify({
 	compilerOptions: { target: "ES2022", module: "commonjs", rootDir: "src", outDir: "dist", strict: true, esModuleInterop: true, experimentalDecorators: true, emitDecoratorMetadata: true, baseUrl: ".", paths: { "@/*": ["src/*"] }, skipLibCheck: true },
 	include: ["src/**/*.ts"]
@@ -442,9 +444,8 @@ Run \`npm run validate:architecture\` after changing files or imports. The gener
 
 if (options.ui) {
 const uiDeps = { "@tailwindcss/vite": "^4.1.18", "@vueuse/core": "^14.3.0", axios: "^1.9.0", pinia: "^3.0.1", primevue: "^4.2.5", vue: "^3.5.13", "vue-router": "^4.5.0", ...(options.auth === "firebase" ? { firebase: "^11.0.0" } : {}) };
-const uiDevDeps = { "@tsconfig/node22": "^22.0.1", "@types/node": "^22.13.14", "@vitejs/plugin-vue": "^5.2.3", "@vue/test-utils": "^2.4.10", "@vue/tsconfig": "^0.7.0", jsdom: "^29.1.1", "npm-run-all2": "^7.0.2", prettier: "3.5.3", typescript: "~5.8.0", vite: "^6.2.4", vitest: "^4.1.7", "vue-tsc": "^2.2.8" };
-add(`${ui}/package.json`, JSON.stringify({ name: ui, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest", "validate:architecture": "node scripts/validate-architecture.mjs --kind ui .", format: "prettier --write src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
-add(`${ui}/scripts/validate-architecture.mjs`, architectureValidatorSource);
+const uiDevDeps = { "@tsconfig/node22": "^22.0.1", "@zaaxch/tailframe": contractVersion, "@types/node": "^22.13.14", "@vitejs/plugin-vue": "^5.2.3", "@vue/test-utils": "^2.4.10", "@vue/tsconfig": "^0.7.0", jsdom: "^29.1.1", "npm-run-all2": "^7.0.2", prettier: "3.5.3", typescript: "~5.8.0", vite: "^6.2.4", vitest: "^4.1.7", "vue-tsc": "^2.2.8" };
+add(`${ui}/package.json`, JSON.stringify({ name: ui, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest", "validate:architecture": "tailframe validate --kind ui .", format: "prettier --write src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
 add(`${ui}/.prettierrc.json`, JSON.stringify(prettierConfig, null, "\t"));
 add(`${ui}/tsconfig.json`, JSON.stringify({ files: [], references: [{ path: "./tsconfig.app.json" }, { path: "./tsconfig.node.json" }] }, null, "\t"));
 add(`${ui}/tsconfig.app.json`, JSON.stringify({ extends: "@vue/tsconfig/tsconfig.dom.json", include: ["env.d.ts", "src/**/*", "src/**/*.vue"], compilerOptions: { composite: true, baseUrl: ".", paths: { "@/*": ["./src/*"] } } }, null, "\t"));

package/assets/validate-architecture.mjs

@@ -1,279 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".vue"]);
-
-function toPosix(value) {
-	return value.split(path.sep).join("/");
-}
-
-function listEntries(target, kind) {
-	return fs.readdirSync(target, { withFileTypes: true })
-		.filter((entry) => kind === "directory" ? entry.isDirectory() : entry.isFile())
-		.map((entry) => entry.name)
-		.sort();
-}
-
-function walk(target) {
-	const results = [];
-	for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
-		if (["node_modules", "dist", ".git"].includes(entry.name)) continue;
-		const absolute = path.join(target, entry.name);
-		if (entry.isDirectory()) results.push(...walk(absolute));
-		else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) results.push(absolute);
-	}
-	return results;
-}
-
-function extractImports(source, relative) {
-	const code = relative.endsWith(".vue")
-		? [...source.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)].map((match) => match[1]).join("\n")
-		: source;
-	const script = code.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
-	const imports = [];
-	const staticPattern = /(?:^|[;\n])\s*(?:import|export)\s+(?:type\s+)?(?:[^"'`;]*?\s+from\s+)?["']([^"']+)["']/g;
-	const dynamicPattern = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
-	for (const pattern of [staticPattern, dynamicPattern]) {
-		for (const match of script.matchAll(pattern)) imports.push(match[1]);
-	}
-	return [...new Set(imports)];
-}
-
-function resolveInternal(relativeFile, specifier) {
-	if (specifier.startsWith("@/")) return path.posix.normalize(`src/${specifier.slice(2)}`);
-	if (!specifier.startsWith(".")) return undefined;
-	return path.posix.normalize(path.posix.join(path.posix.dirname(relativeFile), specifier));
-}
-
-function isTestFile(relative) {
-	return relative.includes("/__tests__/") || /\.(?:test|spec)\.[^.]+$/.test(relative);
-}
-
-function moduleParts(relative) {
-	const match = relative.match(/^src\/modules\/([^/]+)\/([^/]+)(?:\/(.*))?$/);
-	if (!match) return undefined;
-	return { module: match[1], layer: match[2], remainder: match[3] ?? "" };
-}
-
-function isNamedUseCase(relative, expectedModule) {
-	const target = moduleParts(relative);
-	return Boolean(
-		target &&
-		target.module === expectedModule &&
-		target.layer === "use-cases" &&
-		target.remainder &&
-		!target.remainder.includes("/") &&
-		!isTestFile(relative)
-	);
-}
-
-function validateStructure(root, kind, fail) {
-	const src = path.join(root, "src");
-	if (!fs.existsSync(src) || !fs.statSync(src).isDirectory()) {
-		fail("Missing architecture directory: src");
-		return;
-	}
-
-	const checkEntries = (relative, entryKind, allowed) => {
-		const target = path.join(root, relative);
-		if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
-			fail(`Missing architecture directory: ${relative}`);
-			return;
-		}
-		for (const name of listEntries(target, entryKind)) {
-			if (!allowed.includes(name)) fail(`Unexpected architecture ${entryKind}: ${relative}/${name}`);
-		}
-	};
-
-	if (kind === "service") {
-		checkEntries("src", "directory", ["__tests__", "app", "core", "modules", "platform"]);
-		checkEntries("src", "file", ["server.ts", "worker.ts"]);
-		checkEntries("src/app", "directory", ["__tests__", "cli", "jobs", "mcp", "scheduled-tasks", "workers"]);
-		checkEntries("src/core", "directory", []);
-	} else {
-		checkEntries("src", "directory", ["app", "core", "modules", "platform"]);
-		checkEntries("src", "file", ["main.ts"]);
-		checkEntries("src/app", "directory", ["__tests__", "components", "stores", "views"]);
-		checkEntries("src/core", "directory", []);
-	}
-
-	const platform = path.join(root, "src/platform");
-	if (!fs.existsSync(platform) || !fs.statSync(platform).isDirectory()) fail("Missing architecture directory: src/platform");
-	const modules = path.join(root, "src/modules");
-	if (!fs.existsSync(modules) || !fs.statSync(modules).isDirectory()) {
-		fail("Missing architecture directory: src/modules");
-		return;
-	}
-	const allowedModuleDirectories = kind === "service"
-		? ["__tests__", "domain", "http", "persistence", "use-cases"]
-		: ["__tests__", "api", "components", "composables", "routes", "stores", "types", "views"];
-	for (const moduleName of listEntries(modules, "directory")) {
-		if (kind === "ui" && moduleName === "theme") fail("Application theme must live under src/app, not src/modules/theme");
-		checkEntries(`src/modules/${moduleName}`, "directory", allowedModuleDirectories);
-		checkEntries(`src/modules/${moduleName}`, "file", []);
-	}
-}
-
-function validateServiceImport(source, target, external, fail, graph) {
-	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}`);
-		} else {
-			const expectedAssembly = source === "src/server.ts" ? "src/app/server" : "src/app/workers/";
-			if (!target.startsWith(expectedAssembly)) fail(`${source} may import only its matching app assembly, not ${target}`);
-		}
-		return;
-	}
-	if (source.startsWith("src/core/")) {
-		if (external || !target.startsWith("src/core/")) fail(`${source} violates core purity by importing ${external ?? target}`);
-		return;
-	}
-	if (source.startsWith("src/app/") || source.startsWith("src/__tests__/")) return;
-	if (source.startsWith("src/platform/")) {
-		if (external) return;
-		if (target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
-		if (source.startsWith("src/platform/integrations/") && /^src\/modules\/[^/]+\/use-cases\/ports\//.test(target)) return;
-		fail(`${source} may import only core, platform, or a module-owned integration port, not ${target}`);
-		return;
-	}
-
-	const sourceModule = moduleParts(source);
-	if (!sourceModule) return;
-	const moduleTest = isTestFile(source) || sourceModule.layer === "__tests__";
-	if (external) {
-		if (!moduleTest && ["domain", "use-cases"].includes(sourceModule.layer)) {
-			fail(`${source} in ${sourceModule.layer} may not import framework or vendor package ${external}`);
-		}
-		return;
-	}
-	if (target.startsWith("src/core/")) return;
-	const targetModule = moduleParts(target);
-	if (target.startsWith("src/platform/")) {
-		if (["http", "persistence"].includes(sourceModule.layer) || moduleTest) return;
-		fail(`${source} cannot import platform code from ${sourceModule.layer}`);
-		return;
-	}
-	if (target.startsWith("src/app/") || target.startsWith("src/__tests__/")) {
-		if (moduleTest) return;
-		fail(`${source} cannot import application assembly or cross-boundary test support`);
-		return;
-	}
-	if (!targetModule) {
-		fail(`${source} imports unsupported internal path ${target}`);
-		return;
-	}
-	if (targetModule.module !== sourceModule.module) {
-		if ((sourceModule.layer === "use-cases" || moduleTest) && isNamedUseCase(target, targetModule.module)) {
-			if (!moduleTest) {
-				if (!graph.has(sourceModule.module)) graph.set(sourceModule.module, new Set());
-				graph.get(sourceModule.module).add(targetModule.module);
-			}
-			return;
-		}
-		fail(`${source} may import another module only through a named use-case file, not ${target}`);
-		return;
-	}
-
-	if (moduleTest) return;
-	const allowedLayers = {
-		domain: ["domain"],
-		"use-cases": ["domain", "use-cases"],
-		http: ["domain", "http", "use-cases"],
-		persistence: ["domain", "persistence", "use-cases"]
-	}[sourceModule.layer] ?? [];
-	if (!allowedLayers.includes(targetModule.layer)) {
-		fail(`${source} in ${sourceModule.layer} cannot import its module's ${targetModule.layer} layer`);
-	}
-}
-
-function validateUiImport(source, target, external, fail) {
-	if (source === "src/main.ts") {
-		if (external || !target.startsWith("src/app/")) fail(`src/main.ts may import only app bootstrap code, not ${external ?? target}`);
-		return;
-	}
-	if (source.startsWith("src/core/")) {
-		if (external || !target.startsWith("src/core/")) fail(`${source} violates core purity by importing ${external ?? target}`);
-		return;
-	}
-	if (source.startsWith("src/app/")) return;
-	if (source.startsWith("src/platform/")) {
-		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
-		fail(`${source} may not import app or module code: ${target}`);
-		return;
-	}
-	const sourceModule = moduleParts(source);
-	if (!sourceModule || external) return;
-	if (target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
-	const targetModule = moduleParts(target);
-	if (targetModule?.module === sourceModule.module) return;
-	fail(`${source} may import only its own UI module, core, or platform, not ${target}`);
-}
-
-function detectCycles(graph, fail) {
-	const visited = new Set();
-	const active = [];
-	const activeSet = new Set();
-	const visit = (moduleName) => {
-		if (activeSet.has(moduleName)) {
-			const start = active.indexOf(moduleName);
-			fail(`Cross-module use-case dependency cycle: ${[...active.slice(start), moduleName].join(" -> ")}`);
-			return;
-		}
-		if (visited.has(moduleName)) return;
-		visited.add(moduleName);
-		active.push(moduleName);
-		activeSet.add(moduleName);
-		for (const dependency of graph.get(moduleName) ?? []) visit(dependency);
-		active.pop();
-		activeSet.delete(moduleName);
-	};
-	for (const moduleName of graph.keys()) visit(moduleName);
-}
-
-export function validateArchitecture(rootArgument, kind) {
-	const root = path.resolve(rootArgument);
-	const errors = [];
-	const fail = (message) => errors.push(message);
-	if (!["service", "ui"].includes(kind)) return [`Architecture kind must be service or ui, received ${kind ?? "nothing"}`];
-	if (!fs.existsSync(root)) return [`Architecture root does not exist: ${root}`];
-	validateStructure(root, kind, fail);
-	const src = path.join(root, "src");
-	if (!fs.existsSync(src)) return errors;
-	const graph = new Map();
-	for (const absolute of walk(src)) {
-		const relative = toPosix(path.relative(root, absolute));
-		for (const specifier of extractImports(fs.readFileSync(absolute, "utf8"), relative)) {
-			const target = resolveInternal(relative, specifier);
-			if (target && !target.startsWith("src/")) {
-				fail(`${relative} has a relative import outside src: ${specifier}`);
-				continue;
-			}
-			if (kind === "service") validateServiceImport(relative, target, target ? undefined : specifier, fail, graph);
-			else validateUiImport(relative, target, target ? undefined : specifier, fail);
-		}
-	}
-	if (kind === "service") detectCycles(graph, fail);
-	return errors;
-}
-
-function parseCli(argv) {
-	const args = [...argv];
-	let kind;
-	let root = ".";
-	while (args.length) {
-		const value = args.shift();
-		if (value === "--kind") kind = args.shift();
-		else root = value;
-	}
-	return { kind, root };
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-	const { kind, root } = parseCli(process.argv.slice(2));
-	const errors = validateArchitecture(root, kind);
-	for (const error of errors) console.error(error);
-	if (errors.length) process.exit(1);
-	console.log(`Validated ${kind} architecture: ${path.resolve(root)}`);
-}