@thebattlearena/corner 0.10.0 → 0.10.1-beta.79

package/ring/scripts/arch-gate.mjs

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+// The architecture gate: which layer may import which, checked on what a range adds. Zero-dependency.
+//
+//   node arch-gate.mjs check  <worktree> --range <A>..<B> [--json]   exit 0 clean, 1 violations,
+//                                                                       2 nothing configured
+//   node arch-gate.mjs status <worktree>                               what the repo has, and how to
+//                                                                       add what it lacks
+//
+// Two sources, both when the repo has them:
+// - ring's own scanner, from `layers` in `.claude/ring.json`: each layer has `paths` (globs) and
+//   `mayImport` (the layers it may depend on; its own is always allowed), and may `forbid` packages
+//   by regex (`"forbid": ["^@nestjs/", "^typeorm$"]` for a domain layer). Only imports on lines the
+//   range ADDS count: what was already there is debt, not this range's.
+// - the repo's dependency-cruiser, when it has a config (`.dependency-cruiser.{js,cjs,mjs,json}`) and
+//   the binary: run on the files the range changed, with the repo's known-violations baseline when
+//   it keeps one (`--ignore-known`). Its `error` rules count; warnings are reported, not counted.
+// Every violation is a finding that cites P14 (the host's rules are not the referee's decisions).
+// mask-guard runs the same check on every push to the PR branch; `judges-card open` warns when a
+// repo has neither source.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, normalize, posix } from 'node:path';
+
+import { isMain, loadConfig } from './config.mjs';
+import { globToRegExp } from './contract.mjs';
+
+const CODE = /\.(?:[cm]?[jt]sx?)$/;
+const IMPORT =
+  /(?:\bimport\s+(?:type\s+)?(?:[\w*{}\s,$]+\s+from\s+)?|\bexport\s+(?:type\s+)?[\w*{}\s,$]+\s+from\s+|\bimport\s*\(\s*|\brequire\s*\(\s*)['"]([^'"\n]+)['"]/g;
+const DEPCRUISE_CONFIGS = [
+  '.dependency-cruiser.js',
+  '.dependency-cruiser.cjs',
+  '.dependency-cruiser.mjs',
+  '.dependency-cruiser.json',
+];
+const KNOWN_VIOLATIONS = '.dependency-cruiser-known-violations.json';
+
+const git = (root, args) =>
+  execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 1 << 26,
+  });
+
+/** The module specifiers a file imports, with their line (1-based). PURE. */
+export function importSpecs(text) {
+  const out = [];
+  const lineAt = (index) => text.slice(0, index).split('\n').length;
+  for (const match of String(text).matchAll(IMPORT))
+    out.push({ spec: match[1], line: lineAt(match.index) });
+  return out;
+}
+
+/** The new-side line numbers a `git diff -U0` of one file adds. PURE. */
+export function addedLines(diff) {
+  const added = new Set();
+  for (const hunk of String(diff).matchAll(
+    /^@@ -\S+ \+(\d+)(?:,(\d+))? @@/gm,
+  )) {
+    const start = Number(hunk[1]);
+    const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
+    for (let i = 0; i < count; i += 1) added.add(start + i);
+  }
+  return added;
+}
+
+const stripJsonComments = (text) =>
+  String(text)
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:"'])\/\/.*$/gm, '$1')
+    .replace(/,(\s*[}\]])/g, '$1');
+
+/** The path aliases of a tsconfig: [{prefix, targets}] with repo-relative targets. PURE. */
+export function tsAliases(tsconfigText) {
+  try {
+    const { compilerOptions = {} } = JSON.parse(
+      stripJsonComments(tsconfigText),
+    );
+    const base = compilerOptions.baseUrl ?? '.';
+    return Object.entries(compilerOptions.paths ?? {}).map(
+      ([key, targets]) => ({
+        prefix: key.replace(/\*$/, ''),
+        exact: !key.endsWith('*'),
+        targets: targets.map((target) =>
+          posix.normalize(posix.join(base, target.replace(/\*$/, ''))),
+        ),
+      }),
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Where a specifier points inside the repo (repo-relative), or null for a package. PURE. */
+export function resolveSpec(fromFile, spec, aliases = []) {
+  if (spec.startsWith('.'))
+    return posix.normalize(posix.join(posix.dirname(fromFile), spec));
+  const alias = aliases.find(({ prefix, exact }) =>
+    exact ? spec === prefix : spec.startsWith(prefix),
+  );
+  if (!alias) return null;
+  return posix
+    .normalize(
+      `${alias.targets[0].replace(/\/$/, '')}/${spec.slice(alias.prefix.length)}`,
+    )
+    .replace(/\/$/, '');
+}
+
+/** The first layer whose globs hold `path` (a file or a module without extension), or null. PURE. */
+export function layerOf(path, layers) {
+  return (
+    layers.find(({ paths }) =>
+      paths.some((glob) => {
+        const re = globToRegExp(glob.replace(/^\.\//, ''));
+        return (
+          re.test(path) || re.test(`${path}.ts`) || re.test(`${path}/index.ts`)
+        );
+      }),
+    ) ?? null
+  );
+}
+
+/** The violations of one file's added imports. PURE. */
+export function fileViolations({ file, text, added, layers, aliases }) {
+  const from = layerOf(file, layers);
+  if (!from) return [];
+  const out = [];
+  for (const { spec, line } of importSpecs(text)) {
+    if (!added.has(line)) continue;
+    const target = resolveSpec(file, spec, aliases);
+    if (target === null) {
+      const banned = (from.forbid ?? []).find((pattern) =>
+        new RegExp(pattern).test(spec),
+      );
+      if (banned)
+        out.push({
+          file,
+          line,
+          spec,
+          from: from.name,
+          to: spec,
+          why: `the ${from.name} layer may not depend on ${spec} (forbid ${banned})`,
+        });
+      continue;
+    }
+    const to = layerOf(target, layers);
+    if (!to || to.name === from.name) continue;
+    if ((from.mayImport ?? []).includes(to.name)) continue;
+    out.push({
+      file,
+      line,
+      spec,
+      from: from.name,
+      to: to.name,
+      why: `${from.name} imports ${to.name} (${spec}); ${from.name} may import only ${(from.mayImport ?? []).join(', ') || 'itself'}`,
+    });
+  }
+  return out;
+}
+
+/** A violation as a finding line. PURE. */
+export const findingLine = (v) =>
+  `${v.file}:${v.line} — P14 — ${v.why} — ${
+    v.spec === null
+      ? 'move it into the layer its job belongs to (domain, application or infrastructure)'
+      : 'depend on a port the inner layer owns, or move the code to the layer that may import it'
+  }`;
+
+const depcruiseConfig = (root) =>
+  DEPCRUISE_CONFIGS.find((name) => existsSync(join(root, name))) ?? null;
+const depcruiseBin = (root) =>
+  [join(root, 'node_modules', '.bin', 'depcruise')].find(existsSync) ?? null;
+
+/** What the repo has for the gate, and what to add when it has nothing. */
+export function archStatus(root, config) {
+  const layers = config.layers ?? [];
+  const cruiser = depcruiseConfig(root);
+  const bin = depcruiseBin(root);
+  return {
+    layers: layers.length,
+    dependencyCruiser: Boolean(cruiser && bin),
+    dependencyCruiserConfig: cruiser,
+    dependencyCruiserBinary: Boolean(bin),
+    configured: layers.length > 0 || Boolean(cruiser && bin),
+  };
+}
+
+export const SETUP_HINT =
+  'add "layers" to .claude/ring.json (each with "name", "paths" and "mayImport"; see the ring README, «Gate de arquitectura») or a dependency-cruiser config (.dependency-cruiser.cjs) with the package installed';
+
+/** Files the layer check leaves out: tests by default (they may wire adapters on purpose). */
+export const DEFAULT_LAYERS_IGNORE = [
+  '**/*.spec.*',
+  '**/*.test.*',
+  '**/__tests__/**',
+  '**/test/**',
+];
+
+const ignored = (file, globs) =>
+  globs.some((glob) => globToRegExp(glob).test(file));
+
+function ownScan(root, range, config) {
+  const layers = config.layers ?? [];
+  if (!layers.length) return [];
+  const ignore = config.layersIgnore ?? DEFAULT_LAYERS_IGNORE;
+  const aliases = existsSync(join(root, 'tsconfig.json'))
+    ? tsAliases(readFileSync(join(root, 'tsconfig.json'), 'utf8'))
+    : [];
+  const head = range.split('..')[1] || 'HEAD';
+  const files = git(root, ['diff', '--name-only', '--diff-filter=ACMR', range])
+    .split('\n')
+    .filter(
+      (file) =>
+        CODE.test(file) && !ignored(file, ignore) && layerOf(file, layers),
+    );
+  const imports = files.flatMap((file) =>
+    fileViolations({
+      file,
+      text: git(root, ['show', `${head}:${file}`]),
+      added: addedLines(git(root, ['diff', '-U0', range, '--', file])),
+      layers,
+      aliases,
+    }),
+  );
+  const created = git(root, ['diff', '--name-only', '--diff-filter=A', range])
+    .split('\n')
+    .filter(Boolean);
+  return [...imports, ...placementViolations(created, config)];
+}
+
+/**
+ * The new files that fall in no layer although a `layersRequired` glob covers them: code that
+ * lives outside the architecture is invisible to the rest of the gate. Tests and the
+ * `layersIgnore` files are left out. PURE.
+ */
+export function placementViolations(created, config) {
+  const required = config.layersRequired ?? [];
+  if (!required.length) return [];
+  const layers = config.layers ?? [];
+  const ignore = config.layersIgnore ?? DEFAULT_LAYERS_IGNORE;
+  return created
+    .filter(
+      (file) =>
+        CODE.test(file) &&
+        !ignored(file, ignore) &&
+        required.some((glob) => globToRegExp(glob).test(file)) &&
+        !layerOf(file, layers),
+    )
+    .map((file) => ({
+      file,
+      line: 1,
+      spec: null,
+      from: null,
+      to: null,
+      why: `a new file outside the layers (${layers.map((layer) => layer.name).join(', ')}), so no dependency rule reaches it`,
+    }));
+}
+
+function cruise(root, range) {
+  const cruiser = depcruiseConfig(root);
+  const bin = depcruiseBin(root);
+  if (!cruiser || !bin) return { ran: false, errors: [], warnings: [] };
+  const files = git(root, ['diff', '--name-only', '--diff-filter=ACMR', range])
+    .split('\n')
+    .filter((file) => CODE.test(file) && existsSync(join(root, file)));
+  if (!files.length) return { ran: true, errors: [], warnings: [] };
+  const known = existsSync(join(root, KNOWN_VIOLATIONS))
+    ? ['--ignore-known', KNOWN_VIOLATIONS]
+    : [];
+  const run = spawnSync(
+    bin,
+    ['--config', cruiser, ...known, '--output-type', 'json', ...files],
+    { cwd: root, encoding: 'utf8', maxBuffer: 1 << 26 },
+  );
+  let violations = [];
+  try {
+    violations = JSON.parse(run.stdout).summary?.violations ?? [];
+  } catch {
+    return { ran: false, errors: [], warnings: [], failure: run.stderr.trim() };
+  }
+  const toFinding = (v) => ({
+    file: v.from,
+    line: 1,
+    spec: v.to,
+    from: v.rule?.name ?? 'dependency-cruiser',
+    to: v.to,
+    why: `dependency-cruiser ${v.rule?.name}: ${v.from} → ${v.to}`,
+  });
+  return {
+    ran: true,
+    errors: violations
+      .filter((v) => v.rule?.severity === 'error')
+      .map(toFinding),
+    warnings: violations
+      .filter((v) => v.rule?.severity !== 'error')
+      .map(toFinding),
+  };
+}
+
+/** The gate on a range: { status, violations, warnings, notes }. */
+export function archCheck(root, range, config) {
+  const status = archStatus(root, config);
+  if (!status.configured)
+    return { status, violations: [], warnings: [], notes: [SETUP_HINT] };
+  const own = ownScan(root, range, config);
+  const repo = cruise(root, range);
+  return {
+    status,
+    violations: [...own, ...repo.errors],
+    warnings: repo.warnings,
+    notes: repo.failure
+      ? [`dependency-cruiser did not run: ${repo.failure}`]
+      : [],
+  };
+}
+
+/**
+ * The config the gate reads for a checkout: its own `.claude/ring.json`, or, when it has none (a
+ * bout's worktree of a repo that keeps the file untracked), the main checkout's of the same repo.
+ */
+export function archConfig(root, venue = 'backend') {
+  const read = (dir) => loadConfig(dir, { contract: false, venue }).config;
+  if (existsSync(join(root, '.claude', 'ring.json'))) return read(root);
+  try {
+    const common = git(root, [
+      'rev-parse',
+      '--path-format=absolute',
+      '--git-common-dir',
+    ]).trim();
+    const main = posix.dirname(common);
+    if (main !== root && existsSync(join(main, '.claude', 'ring.json')))
+      return read(main);
+  } catch {
+    // Not a git checkout: its own config, defaults included.
+  }
+  return read(root);
+}
+
+/** The gate for a push to a bout's PR branch: { refusal } (null when it passes or is not configured). */
+export function boutArchGate(state, sha) {
+  const root = state.worktree;
+  const config = archConfig(root, state.venue ?? 'backend');
+  if (!archStatus(root, config).configured) return { refusal: null };
+  const baseRef = [`origin/${state.base}`, state.base].find((ref) => {
+    try {
+      git(root, ['rev-parse', '--verify', '-q', `${ref}^{commit}`]);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (!baseRef) return { refusal: null };
+  const base = git(root, ['merge-base', baseRef, sha]).trim();
+  const { violations } = archCheck(root, `${base}..${sha}`, config);
+  return {
+    refusal: violations.length
+      ? `${violations.length} architecture violation(s) the range adds (P14):\n${violations.map(findingLine).join('\n')}\nFix them, or take the human's decision to the hard list.`
+      : null,
+  };
+}
+
+function flags(argv) {
+  const values = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--json') values.json = true;
+    else if (argv[i].startsWith('--')) values[argv[i].slice(2)] = argv[++i];
+    else rest.push(argv[i]);
+  }
+  return { values, rest };
+}
+
+if (isMain(import.meta.url)) {
+  const [command, ...argv] = process.argv.slice(2);
+  const { values, rest } = flags(argv);
+  const root = rest[0] ? normalize(rest[0]) : process.cwd();
+  try {
+    const config = archConfig(root);
+    if (command === 'status') {
+      const status = archStatus(root, config);
+      console.log(JSON.stringify(status, null, 2));
+      if (!status.configured)
+        console.error(`arch-gate: nothing configured; ${SETUP_HINT}`);
+      process.exit(status.configured ? 0 : 2);
+    }
+    if (command !== 'check' || !values.range)
+      throw new Error(
+        'usage: arch-gate.mjs check <worktree> --range <A>..<B> [--json] | status <worktree>',
+      );
+    const result = archCheck(root, values.range, config);
+    if (values.json) console.log(JSON.stringify(result, null, 2));
+    else if (!result.status.configured)
+      console.log(`arch — NO VERIFICADO — ${SETUP_HINT}`);
+    else {
+      for (const v of result.violations) console.log(findingLine(v));
+      for (const w of result.warnings) console.log(`(warning) ${w.why}`);
+      for (const note of result.notes) console.log(`(note) ${note}`);
+      if (!result.violations.length) console.log('arch: clean');
+    }
+    process.exit(
+      !result.status.configured ? 2 : result.violations.length ? 1 : 0,
+    );
+  } catch (error) {
+    console.error(`arch-gate: ${error.message}`);
+    process.exit(3);
+  }
+}

package/ring/scripts/brief-build.mjs

@@ -0,0 +1,130 @@
+// The pure rules of a generated brief (brief.mjs is its CLI): the rules block, the excerpt of
+// decisions, the filling of a template with no placeholder left, the seal that proves the brief
+// came from the script with the rules in force, and the paths a brief may point to. Zero-dependency.
+import { createHash } from 'node:crypto';
+import { basename, isAbsolute, sep } from 'node:path';
+
+import { parseDecisionLine } from './chronicle.mjs';
+import { checklistLines } from './rule-ids.mjs';
+
+export const BRIEF_VERSION = 'v1';
+const SEAL = /^<!-- ring-brief (v\d+) (.*) -->$/;
+
+export const sha256 = (text) =>
+  `sha256:${createHash('sha256').update(text).digest('hex')}`;
+
+/**
+ * The rules every brief carries, in full and before anything else (the same text for every brief
+ * of a venue, so a model can reuse it): the architecture checklist, then each rule file. PURE.
+ */
+export function rulesBlock({ sources, entries }) {
+  const files = sources.map(
+    ({ path, text }) =>
+      `<rules file="${basename(path)}">\n${text.trim()}\n</rules>`,
+  );
+  return [
+    '# The rules in force for this bout',
+    '',
+    'Embedded in full by `brief.mjs`: these are the rules you apply and cite by id. Nothing you',
+    'remember from another bout replaces them.',
+    '',
+    '## Architecture checklist (what slips past a line-by-line review; check it first)',
+    '',
+    ...checklistLines(entries),
+    '',
+    ...files,
+  ].join('\n');
+}
+
+/**
+ * The decisions a brief carries: every foul (what must not be repeated), the ones whose text names
+ * a file of the range, and the last `last`; in ledger order, each once. PURE.
+ */
+export function decisionsExcerpt(
+  decisionsText,
+  files = [],
+  { last = 20 } = {},
+) {
+  const lines = String(decisionsText ?? '')
+    .split('\n')
+    .filter((line) => parseDecisionLine(line)?.id);
+  const names = files.map((file) => basename(file)).filter(Boolean);
+  const tail = new Set(lines.slice(-last));
+  const kept = lines.filter(
+    (line) =>
+      tail.has(line) ||
+      /\bFOUL\b/.test(line) ||
+      names.some((name) => line.includes(name)),
+  );
+  return kept.length ? kept.join('\n') : '(no decisions yet)';
+}
+
+/** The template with every `{{name}}` filled; throws naming each one left empty. PURE. */
+export function fill(template, vars) {
+  const missing = new Set();
+  const text = template.replace(/\{\{(\w+)\}\}/g, (whole, name) => {
+    const value = vars[name];
+    if (value === undefined || value === null || String(value).trim() === '') {
+      missing.add(name);
+      return whole;
+    }
+    return String(value);
+  });
+  if (missing.size)
+    throw new Error(`the brief is missing: ${[...missing].join(', ')}`);
+  return text;
+}
+
+/** The last line of a brief: what it is and the hashes that prove it. PURE. */
+export function seal(body, meta) {
+  const fields = Object.entries({ ...meta, body: sha256(body) })
+    .map(([key, value]) => `${key}=${value}`)
+    .join(' ');
+  return `${body}\n<!-- ring-brief ${BRIEF_VERSION} ${fields} -->\n`;
+}
+
+/** The seal of a brief, its body and whether the body is the one sealed; null without a seal. PURE. */
+export function readSeal(text) {
+  const lines = String(text).replace(/\n$/, '').split('\n');
+  const match = SEAL.exec(lines.at(-1) ?? '');
+  if (!match) return null;
+  const meta = Object.fromEntries(
+    match[2].split(' ').map((pair) => pair.split('=')),
+  );
+  const body = lines.slice(0, -1).join('\n');
+  return { version: match[1], meta, body, intact: sha256(body) === meta.body };
+}
+
+/**
+ * Whether a sealed brief still holds: its body untouched and its rules the ones in force now
+ * (`rulesHash`). The reason when it does not. PURE.
+ */
+export function briefStatus(text, rulesHash) {
+  const sealed = readSeal(text);
+  if (!sealed)
+    return { ok: false, reason: 'not generated by brief.mjs (no seal)' };
+  if (!sealed.intact)
+    return { ok: false, reason: 'edited by hand after it was generated' };
+  if (sealed.meta.rules && sealed.meta.rules !== rulesHash)
+    return { ok: false, reason: 'the rules changed since; generate it again' };
+  return { ok: true, meta: sealed.meta };
+}
+
+const ABSOLUTE_PATH = /(?:^|[\s`'"(])(\/[^\s`'"()]+)/g;
+
+/**
+ * The absolute paths in the referee's values that point outside the places a brief may send an
+ * agent (the repo, the worktree, the bout dir, the ring): a session scratchpad is wiped on restart,
+ * so nothing the human asked for may live there. PURE.
+ */
+export function strayPaths(vars, roots) {
+  const inside = (path) =>
+    roots.some((root) => path === root || path.startsWith(root + sep));
+  return Object.entries(vars).flatMap(([name, value]) =>
+    [...String(value ?? '').matchAll(ABSOLUTE_PATH)]
+      .map((match) => match[1].replace(/[.,;:]+$/, ''))
+      .filter((path) => isAbsolute(path))
+      .filter((path) => !inside(path))
+      .map((path) => ({ name, path })),
+  );
+}