@macedon-technologies/batman 1.32.1 → 1.34.0

package/templates/app/architecture-rules/README.md

@@ -0,0 +1,97 @@
+# Architecture rules
+
+A data-driven registry of architectural constraints, enforced by
+`pnpm validate:architecture` and run as part of the pre-PR verification
+workflow (`workflows/workflow-pre-pr-verify.yaml`) before the swamp factory
+opens a PR. New rules are new entries in `rules.json`, not new code — the
+engine (`check.ts`) only needs a new case in `evaluateRule()` when a rule
+needs a genuinely new kind of check.
+
+## Rule shape
+
+Two `check.type`s are implemented: `forbidden-import` (whole-repo import-graph
+check) and `required-companion` (diff-based co-change check).
+
+```json
+{
+  "id": "unique-id",
+  "description": "What this enforces and why.",
+  "enabled": true,
+  "severity": "low" | "medium" | "high" | "critical",
+  "check": {
+    "type": "forbidden-import",
+    "from": ["glob patterns selecting files this rule inspects"],
+    "forbid": ["glob patterns those files may not import from"]
+  }
+}
+```
+
+```json
+{
+  "id": "unique-id",
+  "description": "What this enforces and why.",
+  "enabled": true,
+  "severity": "low" | "medium" | "high" | "critical",
+  "check": {
+    "type": "required-companion",
+    "from": ["glob patterns selecting changed files that trigger the requirement"],
+    "requireOneOf": ["glob patterns -- at least one CHANGED file must match one of these"],
+    "exempt": ["optional -- from-files matching these globs don't trigger the requirement"]
+  }
+}
+```
+
+`required-companion` evaluates the set of files changed in the current diff
+(`git diff --name-only --diff-filter=ACMR <baseRef>...HEAD`), not the whole
+repo tree: if any changed file matches `from` (and doesn't match `exempt`) but
+no changed file matches `requireOneOf`, that's a violation. The base ref
+defaults to `origin/main` and can be overridden with the
+`ARCHITECTURE_RULES_BASE_REF` environment variable. This means the checkout
+running `pnpm validate:architecture` must have that base ref fetched and
+resolvable (a shallow, single-branch checkout will make the check fail closed
+with an error rather than silently reporting no violations) — make sure
+whatever runs this task fetches enough history for `git diff <baseRef>...HEAD`
+to succeed.
+
+`from`/`requireOneOf`/`exempt` globs are matched against the paths `git
+diff --name-only` reports, which are relative to the git repository's
+top-level directory. This lines up with `from`'s own directory (the parent of
+`architecture-rules/`) in the common case — a single project generated at the
+repo root — but if `architecture-rules/` instead lives under a nested
+subdirectory of a larger git repo, write globs relative to the git root, not
+to that subdirectory.
+
+**`required-companion` is a coverage check, not a correctness check.** It only
+confirms that *some* changed file matches `requireOneOf` — it can't tell
+whether that change is actually related to the triggering `from` change (a
+trivial or unrelated edit to a file under `requireOneOf` satisfies the rule
+just as well as a substantive one), and it can't tell whether a given `from`
+change genuinely needed a companion at all (a pure refactor might not).
+`exempt` covers *known, glob-expressible* exceptions, but not every false
+positive is expressible as a glob — that judgment call still belongs to the
+rule author (scoping `from`/`exempt`) and the reviewer (reading the companion
+diff, not just trusting that the check passed). Also note that `main()`
+fails the whole run on *any* violation regardless of `severity` — `severity`
+is informational only, not a leniency lever — so start with a narrowly
+scoped `from` (or `enabled: false`) and widen it as the convention proves
+itself, the same guidance as for `forbidden-import`.
+
+`enabled: false` rules are skipped (reported as "deferred") rather than
+evaluated — use this for a rule you've named and described but don't yet
+have a concrete convention to check.
+
+## Current rules
+
+None yet — `rules.json` ships empty. Add rules as your domain module
+conventions solidify (e.g. an event-sourced/CQRS module layout under
+`src/domains/<name>/{commands,events,aggregates,projections}/`).
+
+## Adding a check type
+
+`forbidden-import` (whole-repo import graph) and `required-companion`
+(diff-based co-change) are the implemented `check.type`s. If a future rule
+needs a data source neither provides (e.g. "every aggregate file must have a
+matching events file", which is a repo-wide naming convention rather than
+either an import-graph or a diff check), add a new `type` value, a matching
+interface, and a case in `evaluateRule()` in `check.ts` — keep the engine
+itself generic; rule-specific knowledge belongs in `rules.json`.

package/templates/app/architecture-rules/check.ts

@@ -0,0 +1,218 @@
+/**
+ * Generic architecture-rule engine. Rules live entirely in rules.json — this
+ * file only knows how to evaluate the check "types" that rules can declare.
+ * Add a new rule by adding a rules.json entry; add a new check type by adding
+ * a case in evaluateRule().
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import rulesFile from './rules.json';
+
+interface ForbiddenImportCheck {
+  type: 'forbidden-import';
+  // Glob patterns (relative to repo root) selecting the files this rule inspects.
+  from: string[];
+  // Glob patterns (relative to repo root) that "from" files may not import from.
+  forbid: string[];
+}
+
+interface RequiredCompanionCheck {
+  type: 'required-companion';
+  // Glob patterns selecting changed files that trigger the requirement.
+  from: string[];
+  // Glob patterns -- at least one CHANGED file must match one of these.
+  requireOneOf: string[];
+  // Optional -- 'from' files matching these globs don't trigger the requirement.
+  exempt?: string[];
+}
+
+interface Rule {
+  id: string;
+  description: string;
+  enabled: boolean;
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  check: ForbiddenImportCheck | RequiredCompanionCheck;
+}
+
+interface Violation {
+  ruleId: string;
+  severity: string;
+  message: string;
+}
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const IGNORED_DIRS = new Set(['node_modules', '.git', '.swamp', 'cdk.out', 'lib', 'build', 'dist']);
+const BASE_REF = process.env.ARCHITECTURE_RULES_BASE_REF || 'origin/main';
+
+// Minimal glob -> RegExp: supports "*", "**", "**/" and literal path segments.
+// No new dependency for this — the only pattern shapes rules.json ever needs
+// are directory-prefix globs like "src/domains/*/commands/**".
+function globToRegExp(glob: string): RegExp {
+  let out = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      i++;
+      if (glob[i + 1] === '/') {
+        out += '(?:.*/)?';
+        i++;
+      } else {
+        out += '.*';
+      }
+    } else if (c === '*') {
+      out += '[^/]*';
+    } else if (c === '?') {
+      out += '[^/]';
+    } else if ('.+^${}()|[]\\'.includes(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+
+function matchesAny(relFile: string, globs: string[]): boolean {
+  return globs.some((glob) => globToRegExp(glob).test(relFile));
+}
+
+function toRepoRelative(absPath: string): string {
+  return path.relative(REPO_ROOT, absPath).split(path.sep).join('/');
+}
+
+// Files changed relative to baseRef, sourced from git rather than the whole-tree
+// walk() below -- required-companion checks care about what a PR touched, not
+// the full repo. Throws (rather than returning []) if baseRef cannot be resolved,
+// so an unfetched base ref fails the check instead of silently reporting no violations.
+function getChangedFiles(baseRef: string): string[] {
+  let output: string;
+  try {
+    output = execFileSync('git', ['diff', '--name-only', '--diff-filter=ACMR', `${baseRef}...HEAD`], {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    throw new Error(
+      `architecture-rules: failed to compute the changed-file set against base ref "${baseRef}" -- ` +
+        `is it fetched and resolvable in this checkout? (${(err as Error).message})`,
+    );
+  }
+  return output.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+}
+
+function walk(dir: string, acc: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (IGNORED_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, acc);
+    } else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+const RELATIVE_IMPORT_RE = /(?:import|export)\s+(?:[^'";]*?\bfrom\s+)?['"](\.[^'"]+)['"]/g;
+
+function findRelativeImports(source: string): string[] {
+  const specs: string[] = [];
+  RELATIVE_IMPORT_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = RELATIVE_IMPORT_RE.exec(source))) {
+    specs.push(match[1]);
+  }
+  return specs;
+}
+
+// An import spec resolves to a module, not a specific file extension, so a
+// forbid glob is checked against the bare resolved path plus its .ts/index.ts
+// variants.
+function resolvedCandidates(fromFile: string, spec: string): string[] {
+  const resolved = toRepoRelative(path.normalize(path.join(path.dirname(fromFile), spec)));
+  return [resolved, `${resolved}.ts`, `${resolved}/index.ts`];
+}
+
+function evaluateForbiddenImport(rule: Rule): Violation[] {
+  const { from, forbid } = rule.check as ForbiddenImportCheck;
+  if (from.length === 0 || forbid.length === 0) return [];
+
+  const violations: Violation[] = [];
+  for (const file of walk(REPO_ROOT)) {
+    const relFile = toRepoRelative(file);
+    if (!matchesAny(relFile, from)) continue;
+
+    const source = fs.readFileSync(file, 'utf8');
+    for (const spec of findRelativeImports(source)) {
+      const candidates = resolvedCandidates(file, spec);
+      if (candidates.some((candidate) => matchesAny(candidate, forbid))) {
+        violations.push({
+          ruleId: rule.id,
+          severity: rule.severity,
+          message: `${relFile} imports "${spec}", which resolves under a path forbidden by rule "${rule.id}"`,
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+function evaluateRequiredCompanion(rule: Rule): Violation[] {
+  const { from, requireOneOf, exempt } = rule.check as RequiredCompanionCheck;
+  if (from.length === 0 || requireOneOf.length === 0) return [];
+
+  const changedFiles = getChangedFiles(BASE_REF);
+  const triggering = changedFiles.filter(
+    (file) => matchesAny(file, from) && !(exempt && matchesAny(file, exempt)),
+  );
+  if (triggering.length === 0) return [];
+
+  const satisfied = changedFiles.some((file) => matchesAny(file, requireOneOf));
+  if (satisfied) return [];
+
+  return [
+    {
+      ruleId: rule.id,
+      severity: rule.severity,
+      message: `changed file(s) ${triggering.join(', ')} match rule "${rule.id}"'s "from" patterns, but no changed file matches its "requireOneOf" patterns`,
+    },
+  ];
+}
+
+function evaluateRule(rule: Rule): Violation[] {
+  switch (rule.check.type) {
+    case 'forbidden-import':
+      return evaluateForbiddenImport(rule);
+    case 'required-companion':
+      return evaluateRequiredCompanion(rule);
+    default:
+      throw new Error(`architecture-rules: unknown check.type "${(rule.check as { type: string }).type}" on rule "${rule.id}"`);
+  }
+}
+
+function main(): number {
+  const rules = (rulesFile as { rules: Rule[] }).rules;
+  let evaluated = 0;
+  let deferred = 0;
+  const violations: Violation[] = [];
+
+  for (const rule of rules) {
+    if (!rule.enabled) {
+      deferred++;
+      console.log(`[deferred] ${rule.id}: ${rule.description}`);
+      continue;
+    }
+    evaluated++;
+    violations.push(...evaluateRule(rule));
+  }
+
+  console.log(`\narchitecture-rules: ${evaluated} rule(s) evaluated, ${deferred} deferred, ${violations.length} violation(s)`);
+  for (const violation of violations) {
+    console.error(`  [${violation.severity}] ${violation.ruleId}: ${violation.message}`);
+  }
+
+  return violations.length > 0 ? 1 : 0;
+}
+
+process.exit(main());

package/templates/app/architecture-rules/rules.json

@@ -0,0 +1,3 @@
+{
+  "rules": []
+}

package/templates/app/architecture-rules/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": [
+    "*.ts",
+    "*.json"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/templates/app/openspec-gates/check-tasks-complete.ts

@@ -0,0 +1,44 @@
+/**
+ * Gate: fails unless every task in the named OpenSpec change's tasks.md is
+ * checked off. `openspec validate`/`openspec status` don't check this (an
+ * in-progress change is a normal, valid state) — this is the deterministic
+ * check the pre-pr pipeline needs before letting implementation proceed.
+ */
+import { execFileSync } from 'node:child_process';
+
+interface OpenSpecChangeSummary {
+  name: string;
+  completedTasks: number;
+  totalTasks: number;
+  status: string;
+}
+
+function main(): number {
+  // pnpm's `-- <args>` forwarding (and projen's receiveArgs) can pass a
+  // literal "--" through as an argv token ahead of the real argument.
+  const slug = process.argv.slice(2).find((arg) => arg !== '--');
+  if (!slug) {
+    console.error('Usage: check-tasks-complete <change-slug>');
+    return 1;
+  }
+
+  const raw = execFileSync('openspec', ['list', '--json'], { encoding: 'utf8', shell: true });
+  const { changes } = JSON.parse(raw) as { changes: OpenSpecChangeSummary[] };
+  const change = changes.find((c) => c.name === slug);
+
+  if (!change) {
+    console.error(`OpenSpec change "${slug}" not found (openspec list --json)`);
+    return 1;
+  }
+  if (change.status !== 'complete') {
+    console.error(
+      `OpenSpec change "${slug}" has incomplete tasks: ${change.completedTasks}/${change.totalTasks}`,
+    );
+    return 1;
+  }
+
+  console.log(`OpenSpec change "${slug}": all ${change.totalTasks} tasks complete`);
+  return 0;
+}
+
+process.exit(main());

package/templates/app/openspec-gates/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": [
+    "*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/templates/app/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@macedon-technologies/batman-template-app",
+  "private": true,
+  "description": "The files Batman copies into a generated project, as a working, tested app.",
+  "packageManager": "pnpm@10.33.0",
+  "scripts": {
+    "test": "tsc --noEmit -p tsconfig.json && tsc -p test/tsconfig.json && tsc -p architecture-rules && tsc -p openspec-gates && tsc -p swamp-bootstrap && jest"
+  },
+  "dependencies": {
+    "@aws-sdk/client-secrets-manager": "*",
+    "@types/aws-lambda": "*",
+    "@types/express": "*",
+    "@types/pg": "*",
+    "aws-cdk-lib": "^2.224.0",
+    "constructs": "^10.5.1",
+    "datadog-cdk-constructs-v2": "*"
+  },
+  "devDependencies": {
+    "@types/jest": "*",
+    "@types/jsonwebtoken": "*",
+    "@types/node": "^22",
+    "esbuild": "*",
+    "jest": "*",
+    "jest-junit": "^17",
+    "ts-jest": "*",
+    "ts-node": "*",
+    "typescript": "*"
+  },
+  "jest": {
+    "coverageProvider": "v8",
+    "testMatch": [
+      "<rootDir>/@(src|test)/**/*(*.)@(spec|test).ts?(x)",
+      "<rootDir>/@(src|test)/**/__tests__/**/*.ts?(x)",
+      "<rootDir>/@(projenrc)/**/*(*.)@(spec|test).ts?(x)",
+      "<rootDir>/@(projenrc)/**/__tests__/**/*.ts?(x)"
+    ],
+    "clearMocks": true,
+    "collectCoverage": true,
+    "coverageReporters": [
+      "json",
+      "lcov",
+      "clover",
+      "cobertura",
+      "text"
+    ],
+    "coverageDirectory": "coverage",
+    "coveragePathIgnorePatterns": [
+      "/node_modules/"
+    ],
+    "testPathIgnorePatterns": [
+      "/node_modules/"
+    ],
+    "watchPathIgnorePatterns": [
+      "/node_modules/"
+    ],
+    "reporters": [
+      "default",
+      [
+        "jest-junit",
+        {
+          "outputDirectory": "test-reports"
+        }
+      ]
+    ],
+    "transform": {
+      "^.+\\.[t]sx?$": [
+        "ts-jest",
+        {
+          "tsconfig": "test/tsconfig.json"
+        }
+      ]
+    }
+  }
+}