@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/harness/gates/resolve-rule.ts

@@ -0,0 +1,94 @@
+/**
+ * One `resolveRule` (OES-11.2). Code keeps computing a gate's CONDITION; what the condition costs —
+ * its severity, and whether that blocks — comes from here and nowhere else, so audit, sensors,
+ * script-check, matrix gates and journey cannot disagree about a rule (red-team #12).
+ *
+ * Two axes, never merged (takumi T5):
+ *   block vs advisory   follows severity — error|review block; warning|info|off never block
+ *   overridable or not  follows kind     — a hard rule ignores every override
+ * With no override in force the result IS the catalog row, which equals today's behavior.
+ */
+import { DecisionVisibility } from '../../decisions/decision-schema';
+import { GateKind, GateSeverity, gateRule, listRules, GateRule } from './gate-rule-catalog';
+
+export type OverrideSeverity = 'warning' | 'info' | 'off';
+export type ResolvedSeverity = GateSeverity | 'off';
+
+/** A gate-override decision that passed validation and is in force for one unit. */
+export interface ActiveOverride {
+  decisionId: string;
+  rule: string;
+  severity: OverrideSeverity;
+  scope: string;
+  reason: string;
+  visibility: DecisionVisibility;
+  by: string;
+  validFrom: string;
+  path: string;
+  /** In git HEAD? null outside git. An uncommitted override still counts here, but release refuses it (decision.in-run). */
+  committed: boolean | null;
+}
+
+export interface GateRuleContext {
+  /** rule id → the override in force for the unit being judged. */
+  overrides: ReadonlyMap<string, ActiveOverride>;
+}
+
+export const NO_OVERRIDES: GateRuleContext = Object.freeze({ overrides: new Map<string, ActiveOverride>() });
+
+export interface ResolvedRule {
+  id: string;
+  severity: ResolvedSeverity;
+  catalogSeverity: GateSeverity;
+  kind: GateKind;
+  blocking: boolean;
+  /** The decision id of the override that set `severity`, when one did. */
+  overriddenBy?: string;
+}
+
+export const isBlockingSeverity = (s: ResolvedSeverity): boolean => s === 'error' || s === 'review';
+
+/** Whether an override may apply to this rule at all (defense in depth behind validation). */
+function admissible(rule: GateRule, o: ActiveOverride | undefined): o is ActiveOverride {
+  if (!o || rule.kind === 'hard') return false;
+  return o.severity !== 'off' || rule.offAllowed;
+}
+
+export function resolveRule(id: string, ctx: GateRuleContext = NO_OVERRIDES): ResolvedRule {
+  const rule = gateRule(id);
+  const o = ctx.overrides.get(id);
+  if (!admissible(rule, o)) {
+    return { id, severity: rule.severity, catalogSeverity: rule.severity, kind: rule.kind, blocking: isBlockingSeverity(rule.severity) };
+  }
+  return { id, severity: o.severity, catalogSeverity: rule.severity, kind: rule.kind, blocking: isBlockingSeverity(o.severity), overriddenBy: o.decisionId };
+}
+
+export { listRules };
+
+/** What a gate site holds: resolve a rule whose condition it found met. */
+export interface GateRules {
+  resolve(id: string): ResolvedRule;
+}
+
+/** The catalog alone — today's behavior; the default wherever no unit context is known. */
+export const CATALOG_GATE_RULES: GateRules = Object.freeze({ resolve: (id: string) => resolveRule(id, NO_OVERRIDES) });
+
+export interface TrackedGateRules extends GateRules {
+  readonly context: GateRuleContext;
+  /** Rules whose override changed an outcome during this evaluation. */
+  triggered(): ReadonlySet<string>;
+}
+
+/** Resolve against one unit's overrides and remember which of them actually changed something. */
+export function trackGateRules(context: GateRuleContext): TrackedGateRules {
+  const fired = new Set<string>();
+  return {
+    context,
+    resolve(id: string): ResolvedRule {
+      const r = resolveRule(id, context);
+      if (r.overriddenBy) fired.add(id);
+      return r;
+    },
+    triggered: () => fired,
+  };
+}

package/src/harness/gates/unit-gate-overrides.ts

@@ -0,0 +1,99 @@
+/**
+ * The gate overrides in force for ONE unit, read from the decision layer (OES-11.2/11.3, DOS-13).
+ *
+ * Sources: `qa/decisions/` (project) and `qa/<kind>/<unit>/decisions/` (the unit). Only entries that
+ * verify against themselves are considered (readDecisions); superseded ones are out of force. Per
+ * rule the override in force is the most specific — an exact unit beats a glob — then the latest, then
+ * the higher decision id (deterministic). Each carries whether git HEAD holds it: an uncommitted one
+ * still counts (the author sees its effect), release refuses it (decision.in-run, review H1).
+ * Never throws: a bad file is a `problem`, a bad override is `rejected`.
+ */
+import * as path from 'path';
+import { isValidScope, PROJECT_SCOPE, DecisionProblem } from '../../decisions/decision-file';
+import { readDecisions, ReadDecision } from '../../decisions/read-decisions';
+import { judgeOverride } from './gate-override-validation';
+import { ActiveOverride, GateRuleContext } from './resolve-rule';
+import { computeDecisionsHash, DecisionsHashItem, problemHashItem } from './decisions-hash';
+import { committedDecisionPaths } from './in-run-decision-check';
+
+export interface OverrideIssue {
+  decisionId: string;
+  path: string;
+  rule?: string;
+  reason: string;
+  entry: ReadDecision;
+  committed: boolean | null;
+}
+
+export interface UnitGateOverrides {
+  unitScope: string | null;
+  context: GateRuleContext;
+  inForce: ActiveOverride[];
+  rejected: OverrideIssue[];
+  ineffective: OverrideIssue[];
+  /** Files in the two directories that do not verify (DOS-13.3) — reported, never skipped. */
+  problems: DecisionProblem[];
+  decisionsHash: string;
+}
+
+/** The decision scope of a unit directory (`screens/login`, `api/flows/signup`), or null. */
+export function unitScopeOfDir(projectRoot: string, unitDir: string): string | null {
+  const rel = path.relative(path.join(projectRoot, 'qa'), unitDir).split(path.sep).join('/');
+  return rel && !rel.startsWith('..') && isValidScope(rel) && rel !== PROJECT_SCOPE ? rel : null;
+}
+
+const specificity = (o: ActiveOverride, unitScope: string | null): number => (o.scope === unitScope ? 1 : 0);
+
+/** Does `a` take precedence over `b` for the same rule? valid_from is schema-checked ISO; NaN never orders. */
+function wins(a: ActiveOverride, b: ActiveOverride, unitScope: string | null): boolean {
+  const s = specificity(a, unitScope) - specificity(b, unitScope);
+  if (s !== 0) return s > 0;
+  const t = (Date.parse(a.validFrom) || 0) - (Date.parse(b.validFrom) || 0);
+  return t !== 0 ? t > 0 : a.decisionId > b.decisionId;
+}
+
+export function loadUnitGateOverrides(projectRoot: string, unitScope: string | null): UnitGateOverrides {
+  const scopes = unitScope ? [PROJECT_SCOPE, unitScope] : [PROJECT_SCOPE];
+  const entries: ReadDecision[] = [];
+  const problems: DecisionProblem[] = [];
+  for (const s of scopes) {
+    const r = readDecisions(projectRoot, s);
+    entries.push(...r.entries);
+    problems.push(...r.problems);
+  }
+  const rel = (p: string): string => path.relative(projectRoot, p).split(path.sep).join('/');
+  const hashItems: DecisionsHashItem[] = problems.map((p) => problemHashItem(projectRoot, p));
+  const byRule = new Map<string, ActiveOverride>();
+  const rejected: OverrideIssue[] = [];
+  const ineffective: OverrideIssue[] = [];
+  // HEAD membership is read once, and only when an override is in reach (two git calls).
+  let head: Set<string> | null | undefined;
+  const inHead = (p: string): boolean | null => {
+    if (head === undefined) head = committedDecisionPaths(projectRoot);
+    return head ? head.has(p) : null;
+  };
+
+  for (const e of entries.filter((x) => x.kind === 'gate-override')) {
+    const j = judgeOverride(e, unitScope);
+    if (j.status === 'irrelevant') continue;
+    const p = rel(e.path);
+    hashItems.push({ path: p, entryHash: e.entry_hash });
+    if (e.superseded_by) continue;
+    const rule = typeof e.payload?.rule === 'string' ? e.payload.rule : undefined;
+    const issue = { decisionId: e.id, path: p, rule, entry: e, committed: inHead(p) };
+    if (j.status === 'rejected') { rejected.push({ ...issue, reason: j.reason }); continue; }
+    if (j.status === 'ineffective') { ineffective.push({ ...issue, reason: j.reason }); continue; }
+    const o: ActiveOverride = { ...j.override, committed: issue.committed };
+    const current = byRule.get(o.rule);
+    if (!current || wins(o, current, unitScope)) byRule.set(o.rule, o);
+  }
+  return {
+    unitScope,
+    context: { overrides: byRule },
+    inForce: [...byRule.values()].sort((a, b) => a.rule.localeCompare(b.rule, 'en')),
+    rejected,
+    ineffective,
+    problems,
+    decisionsHash: computeDecisionsHash(hashItems),
+  };
+}