@ticket-gate/engine 0.0.0-stage → 0.1.0-rc.1

package/graph/load-time.mjs

@@ -0,0 +1,309 @@
+/**
+ * Load-time code. A module's top-level statement either only declares something
+ * (inert: a function, a literal table, an import) or does work when the module is evaluated
+ * (a call, a `new`, a template with a substitution). Evaluating a module happens on every
+ * page that imports it, so a changed load-time statement can break any spec.
+ *
+ * When in doubt a statement is load-time code.
+ * Dependency-free Node ESM plus `typescript` (a root devDependency).
+ */
+
+import { lazyTs } from './typescript.mjs';
+
+const ts = lazyTs();
+const K = new Proxy({}, { get: (_, key) => ts.SyntaxKind[key] });
+
+/** @typedef {{ text: string, loadTime: boolean }} Unit */
+
+let printerInstance = null;
+const printer = {
+  printNode: (...a) =>
+    (printerInstance ??= ts.createPrinter({ removeComments: true })).printNode(
+      ...a,
+    ),
+};
+
+const scriptKind = (fileName) =>
+  fileName.endsWith('.tsx')
+    ? ts.ScriptKind.TSX
+    : fileName.endsWith('.ts') || fileName.endsWith('.mts')
+      ? ts.ScriptKind.TS
+      : ts.ScriptKind.JS;
+
+const parse = (source, fileName) =>
+  ts.createSourceFile(
+    fileName,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKind(fileName),
+  );
+
+const hasModifier = (node, kind) =>
+  ts.canHaveModifiers(node) &&
+  (ts.getModifiers(node) ?? []).some((m) => m.kind === kind);
+
+/** interface, type alias, `declare ...`, `import type`, `export type ... from`: no runtime form. */
+function isTypeOnlyStatement(st) {
+  if (ts.isInterfaceDeclaration(st) || ts.isTypeAliasDeclaration(st))
+    return true;
+  if (hasModifier(st, K.DeclareKeyword)) return true;
+  if (ts.isImportDeclaration(st)) return st.importClause?.isTypeOnly === true;
+  if (ts.isExportDeclaration(st)) return st.isTypeOnly;
+  if (ts.isImportEqualsDeclaration(st)) return st.isTypeOnly;
+  return false;
+}
+
+const unwrap = (e) => {
+  let x = e;
+  while (
+    ts.isAsExpression(x) ||
+    ts.isSatisfiesExpression(x) ||
+    ts.isNonNullExpression(x) ||
+    ts.isTypeAssertionExpression(x) ||
+    ts.isParenthesizedExpression(x)
+  )
+    x = x.expression;
+  return x;
+};
+
+const staticName = (name) =>
+  name !== undefined && !ts.isComputedPropertyName(name);
+
+/** Every identifier a binding name (identifier or nested pattern) declares. */
+function bindingNames(name, names) {
+  if (ts.isIdentifier(name)) names.add(name.text);
+  else
+    for (const el of name.elements)
+      if (ts.isBindingElement(el)) bindingNames(el.name, names);
+}
+
+/** Names the module declares itself at the top level (not imports): `extends` of one is load-time. */
+function localNames(sf) {
+  const names = new Set();
+  for (const st of sf.statements) {
+    if (ts.isVariableStatement(st)) {
+      for (const d of st.declarationList.declarations) {
+        bindingNames(d.name, names);
+      }
+    } else if (
+      (ts.isClassDeclaration(st) ||
+        ts.isFunctionDeclaration(st) ||
+        ts.isEnumDeclaration(st)) &&
+      st.name
+    )
+      names.add(st.name.text);
+  }
+  return names;
+}
+
+function classInert(cls, locals) {
+  if (ts.canHaveDecorators(cls) && (ts.getDecorators(cls) ?? []).length > 0)
+    return false;
+  for (const h of cls.heritageClauses ?? []) {
+    if (h.token !== K.ExtendsKeyword) continue;
+    for (const t of h.types) {
+      const e = t.expression;
+      if (!ts.isIdentifier(e) || locals.has(e.text)) return false;
+    }
+  }
+  for (const m of cls.members) {
+    if (ts.canHaveDecorators(m) && (ts.getDecorators(m) ?? []).length > 0)
+      return false;
+    if (ts.isClassStaticBlockDeclaration(m)) return false;
+    if (m.name && ts.isComputedPropertyName(m.name)) return false;
+    if (
+      ts.isPropertyDeclaration(m) &&
+      hasModifier(m, K.StaticKeyword) &&
+      m.initializer
+    )
+      return false;
+  }
+  return true;
+}
+
+const isNumericOperand = (e) => ts.isNumericLiteral(e) || ts.isBigIntLiteral(e);
+
+/** true = proved inert (evaluating it does no work and reads no other module's state). */
+function exprInert(node, locals) {
+  const e = unwrap(node);
+  switch (e.kind) {
+    case K.StringLiteral:
+    case K.NumericLiteral:
+    case K.BigIntLiteral:
+    case K.NoSubstitutionTemplateLiteral:
+    case K.RegularExpressionLiteral:
+    case K.TrueKeyword:
+    case K.FalseKeyword:
+    case K.NullKeyword:
+    case K.ArrowFunction:
+    case K.FunctionExpression:
+      return true;
+    case K.PrefixUnaryExpression:
+      return (
+        (e.operator === K.MinusToken || e.operator === K.PlusToken) &&
+        isNumericOperand(e.operand)
+      );
+    case K.ClassExpression:
+      return classInert(e, locals);
+    case K.ArrayLiteralExpression:
+      return e.elements.every(
+        (x) => ts.isOmittedExpression(x) || exprInert(x, locals),
+      );
+    case K.ObjectLiteralExpression:
+      return e.properties.every((p) => {
+        if (ts.isPropertyAssignment(p))
+          return staticName(p.name) && exprInert(p.initializer, locals);
+        if (
+          ts.isMethodDeclaration(p) ||
+          ts.isGetAccessorDeclaration(p) ||
+          ts.isSetAccessorDeclaration(p)
+        )
+          return staticName(p.name);
+        return false;
+      });
+    case K.CallExpression: {
+      const c = e.expression;
+      return (
+        ts.isPropertyAccessExpression(c) &&
+        ts.isIdentifier(c.expression) &&
+        c.expression.text === 'Object' &&
+        c.name.text === 'freeze' &&
+        e.arguments.every((a) => exprInert(a, locals))
+      );
+    }
+    default:
+      return false; // fact 2: an expression not proved inert
+  }
+}
+
+function enumInert(en, locals) {
+  return en.members.every(
+    (m) =>
+      !m.initializer ||
+      (exprInert(m.initializer, locals) &&
+        !ts.isArrowFunction(unwrap(m.initializer)) &&
+        !ts.isFunctionExpression(unwrap(m.initializer))),
+  );
+}
+
+/** true = load-time code. */
+function statementLoadTime(st, locals) {
+  if (
+    ts.isImportDeclaration(st) ||
+    ts.isExportDeclaration(st) ||
+    ts.isImportEqualsDeclaration(st) ||
+    ts.isFunctionDeclaration(st) ||
+    ts.isEmptyStatement(st)
+  )
+    return false;
+  if (ts.isClassDeclaration(st)) return !classInert(st, locals);
+  if (ts.isEnumDeclaration(st)) return !enumInert(st, locals);
+  if (ts.isExpressionStatement(st)) return !ts.isStringLiteral(st.expression); // a directive is inert
+  if (ts.isVariableStatement(st)) {
+    const list = st.declarationList;
+    // `await using` and `using` share the Const bit; only a plain `const` can be inert
+    if ((list.flags & ts.NodeFlags.BlockScoped) !== ts.NodeFlags.Const)
+      return true;
+    return !list.declarations.every(
+      (d) =>
+        ts.isIdentifier(d.name) &&
+        d.initializer !== undefined &&
+        exprInert(d.initializer, locals),
+    );
+  }
+  return true; // fact 2: a statement not proved inert is load-time code
+}
+
+/**
+ * Statement units in order. Text is the comment-free printed statement, so comment-only and
+ * whitespace-only edits are no change. Type-only statements yield no unit.
+ * @returns {Unit[]}
+ */
+export function loadTimeUnits(source, fileName = 'x.ts') {
+  const sf = parse(source, fileName);
+  const locals = localNames(sf);
+  const units = [];
+  for (const st of sf.statements.filter((x) => !isTypeOnlyStatement(x))) {
+    units.push({
+      text: printer.printNode(ts.EmitHint.Unspecified, st, sf),
+      loadTime: statementLoadTime(st, locals),
+    });
+  }
+  return units;
+}
+
+export function hasLoadTimeCode(source, fileName = 'x.ts') {
+  return loadTimeUnits(source, fileName).some((u) => u.loadTime);
+}
+
+/** Texts keyed with their occurrence index, so duplicates keep their identity. */
+function keyed(units) {
+  const seen = new Map();
+  return units.map((u) => {
+    const n = seen.get(u.text) ?? 0;
+    seen.set(u.text, n + 1);
+    return `${n}\0${u.text}`;
+  });
+}
+
+/** The units both sides hold, in base order, differ in order from head order. */
+function orderChanged(b, h) {
+  const bk = keyed(b);
+  const hk = keyed(h);
+  const inHead = new Set(hk);
+  const inBase = new Set(bk);
+  const commonB = bk.filter((k) => inHead.has(k));
+  const commonH = hk.filter((k) => inBase.has(k));
+  return commonB.some((k, i) => k !== commonH[i]);
+}
+
+/**
+ * R4: did a load-time statement get added, removed, edited, or reordered?
+ * base === null: the file is new, every load-time unit is added. head === null: removed,
+ * which is not a hit here (F3 names edits and added imports only).
+ */
+export function loadTimeChanged(base, head, fileName = 'x.ts') {
+  if (head === null) return false;
+  const b = base === null ? [] : loadTimeUnits(base, fileName);
+  const h = loadTimeUnits(head, fileName);
+  const bl = b.filter((u) => u.loadTime).map((u) => u.text);
+  const hl = h.filter((u) => u.loadTime).map((u) => u.text);
+  if (bl.length !== hl.length || bl.some((t, i) => t !== hl[i])) return true;
+  const anyLoadTime = hl.length > 0;
+  if (anyLoadTime && orderChanged(b, h)) return true;
+  return false;
+}
+
+/** Module specifiers evaluated when the file loads (type-only statements add none). */
+export function evaluationSpecs(source, fileName = 'x.ts') {
+  const sf = parse(source, fileName);
+  const out = new Set();
+  const calls = (node) => {
+    if (
+      ts.isCallExpression(node) &&
+      (node.expression.kind === K.ImportKeyword ||
+        (ts.isIdentifier(node.expression) &&
+          node.expression.text === 'require')) &&
+      node.arguments.length > 0 &&
+      (ts.isStringLiteral(node.arguments[0]) ||
+        ts.isNoSubstitutionTemplateLiteral(node.arguments[0]))
+    )
+      out.add(node.arguments[0].text);
+    ts.forEachChild(node, calls);
+  };
+  for (const st of sf.statements) {
+    if (isTypeOnlyStatement(st)) continue;
+    if (ts.isImportDeclaration(st) || ts.isExportDeclaration(st)) {
+      if (st.moduleSpecifier && ts.isStringLiteral(st.moduleSpecifier))
+        out.add(st.moduleSpecifier.text);
+    } else if (
+      ts.isImportEqualsDeclaration(st) &&
+      ts.isExternalModuleReference(st.moduleReference) &&
+      ts.isStringLiteral(st.moduleReference.expression)
+    )
+      out.add(st.moduleReference.expression.text);
+    calls(st);
+  }
+  return [...out];
+}

package/graph/typescript.mjs

@@ -0,0 +1,28 @@
+/**
+ * `typescript` is the project's, resolved at call time from `from` (the project
+ * root), never imported statically by the engine. Dependency-free Node ESM.
+ */
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+import { SelectionConfigError } from '../selection/define.mjs';
+
+const cache = new Map();
+
+export function typescript(from = process.cwd()) {
+  if (cache.has(from)) return cache.get(from);
+  let mod;
+  try {
+    mod = createRequire(join(from, 'package.json'))('typescript');
+  } catch {
+    throw new SelectionConfigError(
+      `typescript is not resolvable from ${from}: install it there as a devDependency`,
+    );
+  }
+  cache.set(from, mod);
+  return mod;
+}
+
+/** A module-level `ts` that resolves on first property read, so nothing loads at import time. */
+export const lazyTs = () =>
+  new Proxy({}, { get: (_, key) => typescript()[key] });

package/hooks/pre-tool-use.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// PreToolUse hook for Claude Code: agents may push a feature branch and open
+// or edit its PR, but never rewrite shared history or land code. Denied:
+//   - `git push` with a force flag (-f, --force, --force-with-lease,
+//     --force-if-includes), a `+refspec`, --mirror, --all, --prune or a delete
+//     (-d, --delete, `:branch`);
+//   - `git push` whose refspec targets main or master, or a bare `git push`
+//     while main or master is checked out;
+//   - `gh pr merge|close`, `gh repo sync`, and a writing `gh api` call;
+//   - MCP git_push (it bypasses the refspec checks; push from Bash instead).
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { isMain } from '../is-main.mjs';
+
+// Start of a command: line start or a shell separator, then optional sudo / command.
+const PREFIX =
+  String.raw`(?:^|&&|\|\||;|\||` +
+  '`' +
+  String.raw`|\$\(|\n)\s*(?:sudo\s+)?(?:command\s+)?`;
+const SEPARATOR = /&&|\|\||;|\||\n/;
+
+const GIT_PUSH = new RegExp(
+  PREFIX + String.raw`git(?:\s+-[^\s]+(?:\s+[^\s-][^\s]*)?)*\s+push\b`,
+  'gi',
+);
+const GH_WRITE = new RegExp(
+  PREFIX +
+    String.raw`gh(?:\s+-[^\s]+(?:\s+[^\s-][^\s]*)?)*\s+(?:pr\s+(?:merge|close)|repo\s+sync)\b`,
+  'i',
+);
+const GH_API = new RegExp(
+  PREFIX + String.raw`gh(?:\s+-[^\s]+(?:\s+[^\s-][^\s]*)?)*\s+api\b`,
+  'gi',
+);
+// An explicit write method, or field / input flags, which make `gh api` default to POST.
+const GH_API_WRITE =
+  /(?:-X|--method)[\s=]*['"]?(?:POST|PUT|PATCH|DELETE)\b|\s(?:-f|-F|--field|--raw-field|--input)(?=[\s=]|$)/i;
+const MCP_PUSH_TOOLS = new Set(['git_push', 'git push']);
+
+const PUSH_DENY_FLAG =
+  /^(?:-f|--force|--force-with-lease(?:=.*)?|--force-if-includes|--mirror|--all|--prune|-d|--delete)$/;
+// Short-flag clusters such as -uf or -fu carry a force too.
+const SHORT_CLUSTER_FORCE = /^-[a-z]*[fd][a-z]*$/i;
+
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Matches a protected branch name, literally, with or without refs/heads/. */
+export function protectedPattern(names) {
+  return new RegExp(
+    String.raw`^(?:refs\/heads\/)?(?:${names.map(escapeRegExp).join('|')})$`,
+  );
+}
+
+// Only for callers that pass no guard (unit tests); the hook always loads the config.
+const DEFAULT_GUARD = { protected: protectedPattern(['main', 'master']) };
+
+// A broken gate.config.mjs must deny every push and gh pr/repo/api call, never allow.
+const FAIL_CLOSED = [
+  new RegExp(
+    PREFIX + String.raw`git(?:\s+-[^\s]+(?:\s+[^\s-][^\s]*)?)*\s+push\b`,
+    'i',
+  ),
+  new RegExp(
+    PREFIX +
+      String.raw`gh(?:\s+-[^\s]+(?:\s+[^\s-][^\s]*)?)*\s+(?:pr|repo|api)\b`,
+    'i',
+  ),
+];
+
+/** Why a push / gh command is denied because the config could not be read, or null. */
+export function failClosedDenial(command, error) {
+  if (!FAIL_CLOSED.some((re) => re.test(command))) return null;
+  return `gate.config.mjs is unusable (${error}); fix the key it names, or print the command for the user to run`;
+}
+
+/** The push guard from gate.config.mjs: { protected } or { error }. Never throws. */
+export async function loadPushGuard() {
+  try {
+    const { loadGateConfig } = await import('../config.mjs');
+    const config = await loadGateConfig();
+    return { protected: protectedPattern(config.pushGuard.protected) };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+const allow = () => process.exit(0);
+const deny = (why) => {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: `Blocked by the ticket-gate push guard: ${why}. Agents may push a feature branch and open or edit its PR; they never force-push, delete a remote branch, push to main or master, merge or close a PR, sync a repo or make a writing gh api call. Do not retry another way; print the exact command for the user to run.`,
+      },
+    }),
+  );
+  process.exit(0);
+};
+
+/** This command's own arguments after the match: stop at the next separator. */
+const argsAfter = (command, end) =>
+  command.slice(end).split(SEPARATOR)[0].trim().split(/\s+/).filter(Boolean);
+
+/** The branch checked out in the hook's working directory, or '' when unknown. */
+function currentBranch() {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+/** Why this `git push` argument list is denied, or null when it is allowed. */
+export function pushDenial(args, branch, guard = DEFAULT_GUARD) {
+  const positional = [];
+  for (const a of args) {
+    if (
+      PUSH_DENY_FLAG.test(a) ||
+      (!a.startsWith('--') && SHORT_CLUSTER_FORCE.test(a))
+    )
+      return `git push ${a}`;
+    if (a.startsWith('-')) continue;
+    positional.push(a.replace(/^['"]|['"]$/g, ''));
+  }
+  // positional[0] is the remote; the rest are refspecs.
+  const refspecs = positional.slice(1);
+  for (const r of refspecs) {
+    if (r.startsWith('+')) return `force refspec ${r}`;
+    if (r.startsWith(':')) return `delete refspec ${r}`;
+    const dst = r.includes(':') ? r.slice(r.indexOf(':') + 1) : r;
+    if (
+      guard.protected.test(dst) ||
+      (dst === 'HEAD' && guard.protected.test(branch))
+    )
+      return `push to ${dst === 'HEAD' ? branch : dst}`;
+  }
+  if (refspecs.length === 0 && guard.protected.test(branch))
+    return `bare git push while ${branch} is checked out`;
+  return null;
+}
+
+/** Why `command` is denied, or null when it is allowed. */
+export function commandDenial(
+  command,
+  branch = currentBranch(),
+  guard = DEFAULT_GUARD,
+) {
+  if (guard.error) return failClosedDenial(command, guard.error);
+  for (const m of command.matchAll(GIT_PUSH)) {
+    const why = pushDenial(
+      argsAfter(command, m.index + m[0].length),
+      branch,
+      guard,
+    );
+    if (why) return why;
+  }
+  if (GH_WRITE.test(command)) return 'gh pr merge/close or gh repo sync';
+  for (const m of command.matchAll(GH_API)) {
+    const rest = command.slice(m.index + m[0].length).split(SEPARATOR)[0];
+    if (GH_API_WRITE.test(rest)) return 'a writing gh api call';
+  }
+  return null;
+}
+
+export async function main() {
+  let raw = '';
+  try {
+    raw = readFileSync(0, 'utf8');
+  } catch {
+    allow();
+  }
+  if (!raw.trim()) allow();
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    deny('unreadable hook payload');
+  }
+  if (!payload || typeof payload !== 'object') deny('unreadable hook payload');
+
+  const tool = String(
+    payload.tool_name ?? payload.toolName ?? payload.tool ?? '',
+  ).toLowerCase();
+  if (
+    MCP_PUSH_TOOLS.has(tool) ||
+    tool.endsWith('/git_push') ||
+    tool.endsWith(':git_push') ||
+    tool.endsWith('__git_push')
+  )
+    deny('MCP git_push (push from Bash so the refspec checks apply)');
+
+  const input = payload.tool_input;
+  let command = '';
+  if (input && typeof input === 'object') {
+    for (const key of ['command', 'cmd', 'script']) {
+      if (typeof input[key] === 'string') {
+        command = input[key];
+        break;
+      }
+    }
+  }
+  const why = commandDenial(command, currentBranch(), await loadPushGuard());
+  if (why) deny(why);
+  allow();
+}
+
+if (isMain(import.meta.url)) await main();