@getarbiter/cli 0.5.0

package/dist/templates/scripts/lib/agent-return-validate.mjs.ejs

@@ -0,0 +1,481 @@
+// SPDX-License-Identifier: Apache-2.0
+// Shared envelope/schema and immutable citation validation for recorder and gates.
+// Structural findings require resolvable file:line citations. No entry point or exit;
+// callers retain their own failure policy (check-fail-closed-audit SKIP_FILES).
+import { readRegularFileSync } from './run-helpers.mjs'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+/**
+ * Resolve a $ref within the root schema (only local "#/$defs/Name" refs supported).
+ * @param {string} ref
+ * @param {Record<string, unknown>} rootSchema
+ * @returns {Record<string, unknown>}
+ */
+function resolveRef(ref, rootSchema) {
+  if (!ref.startsWith('#/')) throw new Error(`Unsupported $ref: ${ref}`)
+  const parts = ref.slice(2).split('/')
+  let node = rootSchema
+  for (const part of parts) {
+    if (typeof node !== 'object' || node === null || !(part in node)) {
+      throw new Error(`Cannot resolve $ref: ${ref}`)
+    }
+    node = /** @type {Record<string, unknown>} */ (node)[part]
+  }
+  return /** @type {Record<string, unknown>} */ (node)
+}
+
+// Unsupported constraints are reported, never silently skipped (#2509).
+const ENFORCED_KEYWORDS = new Set([
+  '$ref',
+  'type',
+  'const',
+  'enum',
+  'minLength',
+  'maxLength',
+  'pattern',
+  'format',
+  'minimum',
+  'maximum',
+  'exclusiveMinimum',
+  'exclusiveMaximum',
+  'required',
+  'additionalProperties',
+  'properties',
+  'items',
+  'minItems',
+  'maxItems',
+  'uniqueItems',
+  'allOf',
+  'anyOf',
+  'oneOf',
+  'not',
+  'if',
+  'then',
+  'else',
+])
+
+/** Metadata that constrains nothing, so carries no enforcement obligation. */
+const ANNOTATION_KEYWORDS = new Set([
+  '$schema',
+  '$id',
+  '$comment',
+  'title',
+  'description',
+  'examples',
+  'default',
+  'definitions',
+  '$defs',
+  'deprecated',
+  'readOnly',
+  'writeOnly',
+])
+
+/**
+ * Keywords present on this node that the validator cannot honour. `additionalProperties`
+ * is special-cased: the `false` form is enforced, the schema form is not.
+ * @param {Record<string, unknown>} schemaNode
+ * @returns {string[]}
+ */
+function unsupportedKeywords(schemaNode) {
+  const unsupported = []
+  for (const key of Object.keys(schemaNode)) {
+    if (ANNOTATION_KEYWORDS.has(key)) continue
+    if (!ENFORCED_KEYWORDS.has(key)) {
+      unsupported.push(key)
+      continue
+    }
+    if (
+      key === 'additionalProperties' &&
+      typeof schemaNode[key] === 'object' &&
+      schemaNode[key] !== null
+    ) {
+      unsupported.push('additionalProperties (schema form)')
+    }
+  }
+  return unsupported
+}
+
+/**
+ * allOf / anyOf / oneOf / not / if-then-else. Branch failures are summarised rather than
+ * forwarded verbatim: an anyOf that fails every branch should read as one rejection, not
+ * as the union of every branch's complaints.
+ * @param {unknown} value
+ * @param {Record<string, unknown>} schemaNode
+ * @param {Record<string, unknown>} rootSchema
+ * @param {string} path
+ * @returns {string[]}
+ */
+function validateCombinators(value, schemaNode, rootSchema, path) {
+  const ctx = { value, schemaNode, rootSchema, path }
+  return [
+    ...validateAllOf(ctx),
+    ...validateAnyOf(ctx),
+    ...validateOneOf(ctx),
+    ...validateNot(ctx),
+    ...validateConditional(ctx),
+  ]
+}
+
+/**
+ * @typedef {{ value: unknown, schemaNode: Record<string, unknown>,
+ *             rootSchema: Record<string, unknown>, path: string }} CombinatorCtx
+ */
+
+/** Branch list under `key`, normalised to an array. @param {CombinatorCtx} ctx @param {string} key */
+function branchesOf(ctx, key) {
+  return /** @type {Record<string, unknown>[]} */ (
+    Array.isArray(ctx.schemaNode[key]) ? ctx.schemaNode[key] : []
+  )
+}
+
+/** Does `value` satisfy one branch? @param {CombinatorCtx} ctx @param {Record<string, unknown>} sub */
+function branchMatches(ctx, sub) {
+  return validateSchema(ctx.value, sub, ctx.rootSchema, ctx.path).length === 0
+}
+
+/** @param {CombinatorCtx} ctx @returns {string[]} */
+function validateAllOf(ctx) {
+  const errors = []
+  for (const sub of branchesOf(ctx, 'allOf')) {
+    errors.push(...validateSchema(ctx.value, sub, ctx.rootSchema, ctx.path))
+  }
+  return errors
+}
+
+/** @param {CombinatorCtx} ctx @returns {string[]} */
+function validateAnyOf(ctx) {
+  if (!('anyOf' in ctx.schemaNode)) return []
+  const branches = branchesOf(ctx, 'anyOf')
+  if (branches.some((sub) => branchMatches(ctx, sub))) return []
+  return [`${ctx.path}: value matches none of the ${branches.length} anyOf branches`]
+}
+
+/** @param {CombinatorCtx} ctx @returns {string[]} */
+function validateOneOf(ctx) {
+  if (!('oneOf' in ctx.schemaNode)) return []
+  const hits = branchesOf(ctx, 'oneOf').filter((sub) => branchMatches(ctx, sub)).length
+  if (hits === 1) return []
+  return [`${ctx.path}: value matches ${hits} oneOf branches, expected exactly 1`]
+}
+
+/** @param {CombinatorCtx} ctx @returns {string[]} */
+function validateNot(ctx) {
+  const sub = ctx.schemaNode['not']
+  if (typeof sub !== 'object' || sub === null) return []
+  if (!branchMatches(ctx, /** @type {Record<string, unknown>} */ (sub))) return []
+  return [`${ctx.path}: value must NOT match the "not" schema, but does`]
+}
+
+/** @param {CombinatorCtx} ctx @returns {string[]} */
+function validateConditional(ctx) {
+  const condition = ctx.schemaNode['if']
+  if (typeof condition !== 'object' || condition === null) return []
+  const taken = branchMatches(ctx, /** @type {Record<string, unknown>} */ (condition))
+    ? ctx.schemaNode['then']
+    : ctx.schemaNode['else']
+  if (typeof taken !== 'object' || taken === null) return []
+  return validateSchema(
+    ctx.value,
+    /** @type {Record<string, unknown>} */ (taken),
+    ctx.rootSchema,
+    ctx.path,
+  )
+}
+
+/**
+ * Array cardinality and uniqueness. Uniqueness compares by serialised form, which is
+ * adequate for the schemas in this repo (scalars and flat records).
+ * @param {unknown[]} value
+ * @param {Record<string, unknown>} schemaNode
+ * @param {string} path
+ * @returns {string[]}
+ */
+function validateArrayConstraints(value, schemaNode, path) {
+  const errors = []
+  const min = schemaNode['minItems']
+  const max = schemaNode['maxItems']
+  if (typeof min === 'number' && value.length < min) {
+    errors.push(`${path}: array length ${value.length} < minItems ${min}`)
+  }
+  if (typeof max === 'number' && value.length > max) {
+    errors.push(`${path}: array length ${value.length} > maxItems ${max}`)
+  }
+  if (schemaNode['uniqueItems'] === true) {
+    const seen = new Set(value.map((v) => JSON.stringify(v)))
+    if (seen.size !== value.length) errors.push(`${path}: array items are not unique`)
+  }
+  return errors
+}
+
+/**
+ * Exclusive numeric bounds (draft-07 numeric form). The inclusive pair is handled inline.
+ * @param {number} value
+ * @param {Record<string, unknown>} schemaNode
+ * @param {string} path
+ * @returns {string[]}
+ */
+function validateExclusiveBounds(value, schemaNode, path) {
+  const errors = []
+  const exMin = schemaNode['exclusiveMinimum']
+  const exMax = schemaNode['exclusiveMaximum']
+  if (typeof exMin === 'number' && value <= exMin) {
+    errors.push(`${path}: value ${value} <= exclusiveMinimum ${exMin}`)
+  }
+  if (typeof exMax === 'number' && value >= exMax) {
+    errors.push(`${path}: value ${value} >= exclusiveMaximum ${exMax}`)
+  }
+  return errors
+}
+
+/**
+ * JSON Schema draft-07 validator over the keyword set in `ENFORCED_KEYWORDS`:
+ * type, required, additionalProperties (false form), properties, enum, const, pattern,
+ * minLength, maxLength, minimum, maximum, exclusiveMinimum, exclusiveMaximum,
+ * format (date-time), items, minItems, maxItems, uniqueItems, allOf, anyOf, oneOf, not,
+ * if/then/else, $ref (into `definitions` or `$defs`).
+ *
+ * Any keyword outside that set is REPORTED, not skipped (#2509) — see `unsupportedKeywords`.
+ * @param {unknown} value
+ * @param {Record<string, unknown>} schemaNode
+ * @param {Record<string, unknown>} rootSchema
+ * @param {string} path
+ * @returns {string[]}
+ */
+export function validateSchema(value, schemaNode, rootSchema, path) {
+  if (schemaNode === null || typeof schemaNode !== 'object' || Array.isArray(schemaNode)) {
+    throw new Error(`${path}: schema must be an object`)
+  }
+  /** @type {string[]} */
+  const errors = []
+  for (const kw of unsupportedKeywords(schemaNode)) {
+    errors.push(`${path}: schema uses "${kw}", which this validator does not support (#2509)`)
+  }
+  errors.push(...validateCombinators(value, schemaNode, rootSchema, path))
+  if ('$ref' in schemaNode) {
+    const resolved = resolveRef(/** @type {string} */ (schemaNode['$ref']), rootSchema)
+    return validateSchema(value, resolved, rootSchema, path)
+  }
+  if ('type' in schemaNode) {
+    const expected = schemaNode['type']
+    const actual = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value
+    if (expected === 'integer') {
+      if (typeof value !== 'number' || !Number.isInteger(value)) {
+        errors.push(`${path}: expected type "integer", got "${actual}"`)
+        return errors
+      }
+    } else if (actual !== expected) {
+      errors.push(`${path}: expected type "${expected}", got "${actual}"`)
+      return errors
+    }
+  }
+  if ('const' in schemaNode && value !== schemaNode['const']) {
+    errors.push(
+      `${path}: value ${JSON.stringify(value)} !== const ${JSON.stringify(schemaNode['const'])}`,
+    )
+  }
+  if ('enum' in schemaNode && Array.isArray(schemaNode['enum'])) {
+    if (!schemaNode['enum'].includes(value)) {
+      errors.push(
+        `${path}: value ${JSON.stringify(value)} not in enum ${JSON.stringify(schemaNode['enum'])}`,
+      )
+    }
+  }
+  if (typeof value === 'string') {
+    if ('minLength' in schemaNode && typeof schemaNode['minLength'] === 'number') {
+      if (value.length < schemaNode['minLength']) {
+        errors.push(`${path}: string length ${value.length} < minLength ${schemaNode['minLength']}`)
+      }
+    }
+    if ('maxLength' in schemaNode && typeof schemaNode['maxLength'] === 'number') {
+      if (value.length > schemaNode['maxLength']) {
+        errors.push(`${path}: string length ${value.length} > maxLength ${schemaNode['maxLength']}`)
+      }
+    }
+    if ('pattern' in schemaNode && typeof schemaNode['pattern'] === 'string') {
+      if (!new RegExp(schemaNode['pattern']).test(value)) {
+        errors.push(`${path}: value "${value}" does not match pattern "${schemaNode['pattern']}"`)
+      }
+    }
+    if (schemaNode['format'] === 'date-time') {
+      if (Number.isNaN(Date.parse(value)))
+        errors.push(`${path}: value "${value}" is not a valid date-time`)
+    }
+  }
+  if (typeof value === 'number') {
+    if (
+      'minimum' in schemaNode &&
+      typeof schemaNode['minimum'] === 'number' &&
+      value < schemaNode['minimum']
+    ) {
+      errors.push(`${path}: value ${value} < minimum ${schemaNode['minimum']}`)
+    }
+    if (
+      'maximum' in schemaNode &&
+      typeof schemaNode['maximum'] === 'number' &&
+      value > schemaNode['maximum']
+    ) {
+      errors.push(`${path}: value ${value} > maximum ${schemaNode['maximum']}`)
+    }
+    errors.push(...validateExclusiveBounds(value, schemaNode, path))
+  }
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const obj = /** @type {Record<string, unknown>} */ (value)
+    if ('required' in schemaNode && Array.isArray(schemaNode['required'])) {
+      for (const req of schemaNode['required']) {
+        if (!(req in obj)) errors.push(`${path}: missing required property "${req}"`)
+      }
+    }
+    if (schemaNode['additionalProperties'] === false && 'properties' in schemaNode) {
+      const allowed = new Set(
+        Object.keys(/** @type {Record<string, unknown>} */ (schemaNode['properties'])),
+      )
+      for (const key of Object.keys(obj)) {
+        if (!allowed.has(key)) errors.push(`${path}: additional property "${key}" is not allowed`)
+      }
+    }
+    if ('properties' in schemaNode && typeof schemaNode['properties'] === 'object') {
+      const props = /** @type {Record<string, unknown>} */ (schemaNode['properties'])
+      for (const [key, propSchema] of Object.entries(props)) {
+        if (key in obj) {
+          errors.push(
+            ...validateSchema(
+              obj[key],
+              /** @type {Record<string, unknown>} */ (propSchema),
+              rootSchema,
+              `${path}.${key}`,
+            ),
+          )
+        }
+      }
+    }
+  }
+  if (Array.isArray(value)) {
+    errors.push(...validateArrayConstraints(value, schemaNode, path))
+    if (
+      'items' in schemaNode &&
+      typeof schemaNode['items'] === 'object' &&
+      schemaNode['items'] !== null
+    ) {
+      const itemSchema = /** @type {Record<string, unknown>} */ (schemaNode['items'])
+      for (let i = 0; i < value.length; i++) {
+        errors.push(...validateSchema(value[i], itemSchema, rootSchema, `${path}[${i}]`))
+      }
+    }
+  }
+  return errors
+}
+
+/**
+ * Detect whether repoRoot is inside a git work tree.
+ * @param {string} repoRoot
+ * @returns {boolean}
+ */
+function isGitRepo(repoRoot) {
+  try {
+    const out = execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 4000,
+    })
+    return out.trim() === 'true'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Resolve a literal citation at the envelope SHA; reject missing files or lines.
+ * Non-Git fixtures use the filesystem.
+ * @param {string} repoRoot
+ * @param {string} sha
+ * @param {string} file
+ * @param {number} line
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function resolveCitation(repoRoot, sha, file, line) {
+  if (isGitRepo(repoRoot)) {
+    try {
+      execFileSync('git', ['cat-file', '-e', `${sha}:${file}`], {
+        cwd: repoRoot,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 4000,
+      })
+    } catch {
+      return { ok: false, reason: `citation file "${file}" does not resolve at sha ${sha}` }
+    }
+    let content = ''
+    try {
+      content = execFileSync('git', ['show', `${sha}:${file}`], {
+        cwd: repoRoot,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 6000,
+      })
+    } catch {
+      return { ok: false, reason: `cannot read "${file}" at sha ${sha}` }
+    }
+    const lineCount = content.split('\n').length - (content.endsWith('\n') ? 1 : 0)
+    if (line > lineCount) {
+      return { ok: false, reason: `citation line ${line} > file length ${lineCount} for "${file}"` }
+    }
+    return { ok: true }
+  }
+  // Non-git fallback (fixture dirs): resolve against the filesystem.
+  const abs = resolve(repoRoot, file)
+  if (!existsSync(abs)) {
+    return { ok: false, reason: `citation file "${file}" does not resolve at repo root` }
+  }
+  const content = readRegularFileSync(abs, 'utf-8')
+  const lineCount = content.split('\n').length - (content.endsWith('\n') ? 1 : 0)
+  if (line > lineCount) {
+    return { ok: false, reason: `citation line ${line} > file length ${lineCount} for "${file}"` }
+  }
+  return { ok: true }
+}
+
+/**
+ * Enforce the M12 citation rule on a validated envelope: every structural finding MUST
+ * carry >=1 citation, and every citation must resolve.
+ * @param {Record<string, unknown>} envelopeParsed
+ * @param {string} repoRoot
+ * @param {string} envelopePath
+ * @returns {string[]}
+ */
+export function enforceCitations(envelopeParsed, repoRoot, envelopePath) {
+  /** @type {string[]} */
+  const errors = []
+  const sha = typeof envelopeParsed['sha'] === 'string' ? envelopeParsed['sha'] : 'HEAD'
+  const findings = Array.isArray(envelopeParsed['findings']) ? envelopeParsed['findings'] : []
+  for (let i = 0; i < findings.length; i++) {
+    const f = /** @type {Record<string, unknown>} */ (findings[i])
+    if (f['kind'] !== 'structural') continue
+    const citations = Array.isArray(f['citations']) ? f['citations'] : []
+    if (citations.length === 0) {
+      errors.push(`${envelopePath}: findings[${i}] is structural but has no citations (M12)`)
+      continue
+    }
+    for (let j = 0; j < citations.length; j++) {
+      const c = /** @type {Record<string, unknown>} */ (citations[j])
+      const file = typeof c['file'] === 'string' ? c['file'] : ''
+      const line = typeof c['line'] === 'number' ? c['line'] : 0
+      const r = resolveCitation(repoRoot, sha, file, line)
+      if (!r.ok) errors.push(`${envelopePath}: findings[${i}].citations[${j}] — ${r.reason}`)
+    }
+  }
+  return errors
+}
+
+/**
+ * Load and parse a JSON schema file.
+ * @param {string} schemaPath
+ * @returns {Record<string, unknown>}
+ */
+export function loadSchema(schemaPath) {
+  const abs = resolve(schemaPath)
+  if (!existsSync(abs)) throw new Error(`schema not found: ${abs}`)
+  return JSON.parse(readRegularFileSync(abs, 'utf-8'))
+}

package/dist/templates/scripts/lib/coverage-gate.mjs.ejs

@@ -0,0 +1,54 @@
+// <%= projectName %> — coverage gate predicate (#1319.8, INV-30)
+// Greenfield-aware coverage decision. A virgin project has zero executable
+// statements; enforcing a line threshold against an empty src tree would
+// false-fail the self-gate. The contract:
+//   - total.statements.total === 0           → PASS  (greenfield, nothing to cover)
+//   - total.statements.total  >  0           → enforce the threshold (line %)
+//   - summary missing / malformed / null     → FAIL  (a crashed coverage run must
+//                                                      NEVER false-green)
+// Pure + side-effect free so the gate logic is unit-testable in isolation.
+
+/**
+ * @param {unknown} summary  Parsed coverage/coverage-summary.json (v8/istanbul shape).
+ * @param {number}  threshold  Line-coverage floor (percent, 0..100).
+ * @returns {{ status: 'PASS' | 'FAIL', reason: string }}
+ */
+export function evaluateCoverageGate(summary, threshold) {
+  // No summary at all ⇒ the coverage run errored or produced no artifact. Fail
+  // closed — skipping here would mask a misconfigured/crashed coverage run.
+  if (summary == null || typeof summary !== 'object') {
+    return { status: 'FAIL', reason: 'no coverage summary (run errored or produced no artifact)' };
+  }
+  const total = summary.total;
+  const statements = total && total.statements;
+  if (
+    statements == null ||
+    typeof statements !== 'object' ||
+    typeof statements.total !== 'number'
+  ) {
+    return {
+      status: 'FAIL',
+      reason: 'malformed coverage summary (missing total.statements.total)',
+    };
+  }
+
+  // Greenfield: zero executable statements ⇒ no coverage to enforce.
+  if (statements.total === 0) {
+    return { status: 'PASS', reason: 'no executable statements (greenfield)' };
+  }
+
+  // Executable code exists ⇒ enforce the line-coverage floor.
+  const lines = (total && total.lines) || statements;
+  const pct = typeof lines.pct === 'number'
+    ? lines.pct
+    : lines.total > 0
+      ? (lines.covered / lines.total) * 100
+      : 0;
+  if (pct + 1e-9 < threshold) {
+    return {
+      status: 'FAIL',
+      reason: `line coverage ${pct.toFixed(2)}% < threshold ${threshold}%`,
+    };
+  }
+  return { status: 'PASS', reason: `line coverage ${pct.toFixed(2)}% >= threshold ${threshold}%` };
+}