@vodmal/vdx-cli 0.31.3 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.31.3",
+  "version": "0.32.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/src/audit.ts

@@ -137,7 +137,7 @@ export function audit(
       });
       continue;
     }
-    const { achieved, not_required, unknown } = evalAxisDetailed(axis, evalCtx);
+    const { achieved, not_required, unknown, not_met } = evalAxisDetailed(axis, evalCtx);
     const ov = overrideByAxis.get(axis.id);
     const target = (ov?.target as LevelName) ?? axis.default_target;
     const drift: 'aligned' | 'gap' | 'over' =
@@ -156,6 +156,7 @@ export function audit(
     if (ov?.target) entry.override_target = ov.target as LevelName;
     if (not_required) entry.not_required = not_required;
     if (unknown) entry.unknown = unknown;
+    if (not_met) entry.not_met = not_met;
     if (axis.clone_check) {
       const c = cloneCheck(axis.clone_check, ctx.projectRoot);
       if (c && c.status !== 'ok') entry.note = c.remedy ? `${c.message} → ${c.remedy}` : c.message;

package/src/evaluator.ts

@@ -1,6 +1,6 @@
 import type { Predicate } from './rubric.ts';
 import type { Ctx } from './facts.ts';
-import { REGISTRY, isUnknown, type Args, type Unknown, type Verdict } from './predicates.ts';
+import { REGISTRY, isFalse, isNo, isUnknown, type Args, type No, type Unknown, type Verdict } from './predicates.ts';
 import { at, isDict, list } from './narrow.ts';
 
 export { isUnknown, type Verdict };
@@ -25,6 +25,11 @@ function firstUnknown(vs: Verdict[]): Unknown | undefined {
   return vs.find(isUnknown);
 }
 
+/** Not met, with the first reason a branch gave, if one did. */
+function no(vs: Verdict[]): false | No {
+  return vs.find(isNo) ?? false;
+}
+
 /**
  * Three-valued: true, false, or unknown with the reason the fact could not be
  * read (a CI system or a hosting vdx does not inspect). Unknown never turns
@@ -40,13 +45,13 @@ export function evalVerdict(p: Predicate, ctx: Ctx): Verdict {
 
     if ('all_of' in obj) {
       const vs = list(obj['all_of']).map((q) => evalVerdict(q, ctx));
-      if (vs.some((v) => v === false)) return false;
+      if (vs.some(isFalse)) return no(vs);
       return firstUnknown(vs) ?? true;
     }
     if ('any_of' in obj) {
       const vs = list(obj['any_of']).map((q) => evalVerdict(q, ctx));
       if (vs.some((v) => v === true)) return true;
-      return firstUnknown(vs) ?? false;
+      return firstUnknown(vs) ?? no(vs);
     }
     if ('at_least_n_of' in obj) {
       const { n, predicates } = obj['at_least_n_of'] as { n: number; predicates: Predicate[] };
@@ -54,12 +59,12 @@ export function evalVerdict(p: Predicate, ctx: Ctx): Verdict {
       const matched = vs.filter((v) => v === true).length;
       if (matched >= n) return true;
       const open = vs.filter(isUnknown).length;
-      if (matched + open < n) return false;
+      if (matched + open < n) return no(vs);
       return firstUnknown(vs)!;
     }
     if ('not' in obj) {
       const v = evalVerdict(obj['not'], ctx);
-      return isUnknown(v) ? v : !v;
+      return isUnknown(v) ? v : v !== true;
     }
     if ('fn' in obj) {
       const name = String(obj['fn']);

package/src/hosting.ts

@@ -115,13 +115,25 @@ function judge(io: HostingIo, repo: string, token: string | null): Verdict {
   const refusedBranch = refusal(b, repo, token);
   if (refusedBranch) return refusedBranch;
   const classic = at(b.body, 'protection', 'required_status_checks');
-  if (at(classic, 'enforcement_level') === 'everyone' && checkCount(classic) > 0) return true;
+  const level = at(classic, 'enforcement_level');
+  const named = checkCount(classic) > 0;
+  if (level === 'everyone' && named) return true;
+  // Why not, for the report (DL #11): what classic protection lacks.
+  const classicWhy =
+    at(b.body, 'protected') !== true
+      ? `${branch} is not protected`
+      : level === 'non_admins' && named
+        ? `${branch} requires checks of everyone but admins — and an agent pushes as its owner, an admin (DL #3)`
+        : level === 'everyone'
+          ? `${branch} is protected, but names no check it requires`
+          : `${branch} is protected without required checks`;
 
   // Rulesets: a rule that requires checks, in a ruleset nobody bypasses.
   const rules = io.get(`/repos/${repo}/rules/branches/${ref}`, token);
   const refusedRules = refusal(rules, repo, token);
   if (refusedRules) return refusedRules;
   let hidden = false;
+  let bypassers = 0;
   for (const rule of list(rules.body)) {
     if (at(rule, 'type') !== 'required_status_checks') continue;
     if (list(at(rule, 'parameters', 'required_status_checks')).length === 0) continue;
@@ -130,13 +142,19 @@ function judge(io: HostingIo, repo: string, token: string | null): Verdict {
     const bypass = ruleset?.status === 200 ? at(ruleset.body, 'bypass_actors') : undefined;
     if (!Array.isArray(bypass)) hidden = true;
     else if (bypass.length === 0) return true;
+    else bypassers = Math.max(bypassers, bypass.length);
   }
   if (hidden) {
     return {
       unknown: `a ruleset requires checks on ${branch}, but GitHub shows who bypasses it only to ${token ? 'a repository admin' : 'a token; gh auth login, or GH_TOKEN'}`,
     };
   }
-  return false;
+  return {
+    no:
+      bypassers > 0
+        ? `${classicWhy}; a ruleset requires checks, but ${bypassers} actor(s) may bypass it`
+        : `${classicWhy}, and no ruleset requires checks`,
+  };
 }
 
 /**

package/src/predicates.ts

@@ -24,11 +24,24 @@ export type Args = Record<string, unknown>;
 export interface Unknown {
   unknown: string;
 }
-export type Verdict = boolean | Unknown;
+/** Not met, and why — from a predicate that knows (DL #11 of docs/tasks/hosting-extension). */
+export interface No {
+  no: string;
+}
+export type Verdict = boolean | Unknown | No;
 type PredicateFn = (args: Args, ctx: Ctx) => Verdict;
 
 export function isUnknown(v: Verdict): v is Unknown {
-  return typeof v === 'object' && v !== null;
+  return typeof v === 'object' && v !== null && 'unknown' in v;
+}
+
+export function isNo(v: Verdict): v is No {
+  return typeof v === 'object' && v !== null && 'no' in v;
+}
+
+/** Not met: `false`, or `false` with its reason. */
+export function isFalse(v: Verdict): v is false | No {
+  return v === false || isNo(v);
 }
 
 /**

package/src/report.ts

@@ -47,6 +47,14 @@ export function reportMarkdown(r: AuditResult): string {
     lines.push(`| \`${a.axis_id}\` | ${cls} | ${achievedCell(a)} | ${a.target} | ${drift} |`);
   }
 
+  const notMet = r.per_axis.filter((a) => a.not_met && !a.suppressed && a.drift_kind !== 'excluded');
+  if (notMet.length > 0) {
+    lines.push('');
+    lines.push(`## Not met`);
+    lines.push('');
+    for (const a of notMet) lines.push(`- \`${a.axis_id}\` ${a.not_met!.level}: ${a.not_met!.reason}`);
+  }
+
   const unknown = r.per_axis.filter((a) => a.unknown);
   if (unknown.length > 0) {
     lines.push('');

package/src/scoring.ts

@@ -1,6 +1,7 @@
 import type { Axis, LevelName, Rubric } from './rubric.ts';
 import type { Ctx } from './facts.ts';
 import { evalPredicate, evalVerdict, isUnknown } from './evaluator.ts';
+import { isNo } from './predicates.ts';
 
 const LEVELS: LevelName[] = ['L1', 'L2', 'L3', 'L4'];
 
@@ -18,6 +19,8 @@ export interface AxisResult {
   not_required?: LevelName[];
   /** The level whose requirement could not be checked, and why; the ascent stopped there. */
   unknown?: { level: LevelName; reason: string };
+  /** The level whose requirement is not met, and why — when the predicate knows. */
+  not_met?: { level: LevelName; reason: string };
   /** A clone check printed next to the axis; does not change the level. */
   note?: string;
 }
@@ -26,6 +29,7 @@ export interface AxisEvaluation {
   achieved: LevelName;
   not_required?: LevelName[];
   unknown?: { level: LevelName; reason: string };
+  not_met?: { level: LevelName; reason: string };
 }
 
 export function evalAxis(axis: Axis, ctx: Ctx): LevelName {
@@ -41,6 +45,7 @@ function evalAxisLevels(axis: Axis, ctx: Ctx): AxisEvaluation {
   let achieved: LevelName = 'L0';
   const notRequired: LevelName[] = [];
   let unknown: AxisEvaluation['unknown'];
+  let notMet: AxisEvaluation['not_met'];
   for (const L of LEVELS) {
     const lvl = axis.levels?.[L];
     if (!lvl) break;
@@ -55,6 +60,7 @@ function evalAxisLevels(axis: Axis, ctx: Ctx): AxisEvaluation {
     } else {
       // delta-style: discontinuity → stop ascent; unknown is "not met", named
       if (isUnknown(v)) unknown = { level: L, reason: v.unknown };
+      else if (isNo(v)) notMet = { level: L, reason: v.no };
       break;
     }
   }
@@ -62,6 +68,7 @@ function evalAxisLevels(axis: Axis, ctx: Ctx): AxisEvaluation {
     achieved,
     ...(notRequired.length > 0 ? { not_required: notRequired } : {}),
     ...(unknown ? { unknown } : {}),
+    ...(notMet ? { not_met: notMet } : {}),
   };
 }