@vodmal/vdx-cli 0.21.1 → 0.22.1

package/src/predicates.ts

@@ -12,9 +12,70 @@ import {
   readStructured,
   resolveConfigPath,
 } from './facts.ts';
+import { checkingJobs, ciSystems, ciTaskCalls, mainPushSteps, readWorkflows, shippingJobs, upstream } from './gha.ts';
+import { detectHookFrameworks } from './hooks.ts';
+import { covers, expandTasks, isVocabularyTask, projectTaskCalls } from './vocabulary.ts';
 
 type Args = Record<string, any>;
-type PredicateFn = (args: Args, ctx: Ctx) => boolean;
+
+/** A fact vdx could not read here — a CI system or a hosting it does not inspect. */
+export interface Unknown {
+  unknown: string;
+}
+export type Verdict = boolean | Unknown;
+type PredicateFn = (args: Args, ctx: Ctx) => Verdict;
+
+export function isUnknown(v: Verdict): v is Unknown {
+  return typeof v === 'object' && v !== null;
+}
+
+/**
+ * Removed from schema 0.3: each name promised more than its body checked
+ * (DL #20 of docs/tasks/vdm-gates-wiring-axis). They stay in the registry for
+ * sets of schema 0.2 only — the same tag gives the same score on any CLI — and
+ * a 0.3 set that names one does not load.
+ */
+export const REMOVED_IN_0_3 = new Set(['gh_workflow_blocks_pr', 'git_hook_installed', 'command_succeeds']);
+
+const DEFAULT_TEST_PATTERN =
+  '\\b(phpunit|pest|composer test|npm test|npm run test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|mix test|rspec|vdx test|mise run test)\\b';
+
+function testPattern(args: Args): RegExp {
+  try {
+    return new RegExp(String(args.pattern ?? DEFAULT_TEST_PATTERN));
+  } catch {
+    return new RegExp(DEFAULT_TEST_PATTERN);
+  }
+}
+
+/**
+ * Above "a CI config exists" vdx reads GitHub Actions only (DL #14). What the
+ * workflows show decides when it says yes; a no is only a no when no other CI
+ * system could say otherwise.
+ */
+function ciVerdict(ctx: Ctx, readGha: () => boolean): Verdict {
+  const systems = ciSystems(ctx);
+  if (systems.length === 0) return false;
+  if (systems.includes('gha') && readGha()) return true;
+  const others = systems.filter((s) => s !== 'gha');
+  if (others.length > 0) return { unknown: `vdx reads GitHub Actions only, not ${others.join(', ')}` };
+  return false;
+}
+
+function hookWords(args: Args): string[] {
+  return Array.isArray(args.tasks) ? args.tasks.map(String) : ['test', 'check'];
+}
+
+/** Tasks the hooks of `events` call, through the project's runner. */
+function hookTaskCalls(ctx: Ctx, events: string[]): Set<string> {
+  const out = new Set<string>();
+  for (const fw of detectHookFrameworks(ctx)) {
+    for (const e of events) {
+      for (const cmd of fw.hooks.get(e) ?? []) for (const t of projectTaskCalls(cmd, ctx)) out.add(t);
+    }
+  }
+  return out;
+}
 
 const warned = new Set<string>();
 function warnOnce(name: string) {
@@ -157,4 +218,65 @@ export const REGISTRY: Record<string, PredicateFn> = {
     warnOnce('command_succeeds');
     return false;
   },
+
+  // --- ci: the signal, read from GitHub Actions workflows (schema 0.3) ---
+
+  /** L2: tests run on a push to main/master, and their failure fails the job. */
+  gha_tests_on_push: (args, ctx) =>
+    ciVerdict(ctx, () => {
+      const re = testPattern(args);
+      return mainPushSteps(ctx).some(({ step }) => re.test(step.run!));
+    }),
+
+  /** L3: on that push CI calls the project's own tasks — each of `tasks` (or its `name:*` form). */
+  gha_runs_tasks: (args, ctx) =>
+    ciVerdict(ctx, () => {
+      const calls = [...ciTaskCalls(ctx)];
+      return hookWords(args).every((w) => calls.some((t) => isVocabularyTask(t, [w])));
+    }),
+
+  /** L4 (library): the testing job runs across a matrix. */
+  gha_test_matrix: (args, ctx) =>
+    ciVerdict(ctx, () => [...checkingJobs(ctx, testPattern(args))].some((j) => j.matrix)),
+
+  /** L4 (service): whatever CI ships on a push to main waits, via `needs:`, for a checking job. */
+  gha_ship_needs_checks: (args, ctx) =>
+    ciVerdict(ctx, () => {
+      const checking = checkingJobs(ctx, testPattern(args));
+      const shipping = readWorkflows(ctx)
+        .filter((wf) => wf.pushesMain)
+        .flatMap((wf) => shippingJobs(wf).map((job) => ({ wf, job })));
+      if (shipping.length === 0) return false;
+      return shipping.every(({ wf, job }) => [...upstream(wf, job)].some((j) => checking.has(j)));
+    }),
+
+  // --- branch-protection: only the hosting knows (schema 0.3) ---
+
+  /** L3: main takes changes only after a required check. No hosting extension yet — unknown everywhere (DL #12). */
+  branch_requires_checks: () => ({
+    unknown: 'only the hosting knows whether main is protected — vdx has no extension for it yet',
+  }),
+
+  // --- git-hygiene: the hook recognizer (schema 0.3) ---
+
+  /** L2: the repository declares hooks, and every framework it declares them with is switched on by an install step. */
+  git_hooks_arranged: (_args, ctx) => {
+    const fws = detectHookFrameworks(ctx);
+    return fws.length > 0 && fws.every((f) => f.installedBy !== null);
+  },
+
+  /** L3: pre-commit or pre-push calls a task of the vocabulary (`test`, `check`, `check:*`, `test:*`). */
+  git_hook_runs_task: (args, ctx) => {
+    const calls = [...hookTaskCalls(ctx, ['pre-commit', 'pre-push'])];
+    return calls.some((t) => isVocabularyTask(t, hookWords(args)));
+  },
+
+  /** L4: pre-push calls every vocabulary task CI calls on a push to main — a push past the hook does not fail CI on a check. */
+  git_hook_covers_ci: (args, ctx) =>
+    ciVerdict(ctx, () => {
+      const ci = [...ciTaskCalls(ctx)].filter((t) => isVocabularyTask(t, hookWords(args)));
+      if (ci.length === 0) return false;
+      const hook = expandTasks(ctx, hookTaskCalls(ctx, ['pre-push']));
+      return ci.every((t) => covers(ctx, hook, t));
+    }),
 };

package/src/report.ts

@@ -2,6 +2,7 @@ import { Marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import Table from 'cli-table3';
 import type { AuditResult } from './audit.ts';
+import { shownLevel } from './scoring.ts';
 import type { DoctorReport, CheckStatus } from './doctor.ts';
 
 const ANSI = {
@@ -43,7 +44,27 @@ export function reportMarkdown(r: AuditResult): string {
   for (const a of r.per_axis) {
     const cls = a.class === 'critical' ? '**C**' : 's';
     const drift = a.suppressed ? '— suppressed —' : `${SYMBOL[a.drift_kind] ?? ''} ${a.drift_kind}`;
-    lines.push(`| \`${a.axis_id}\` | ${cls} | ${a.achieved} | ${a.target} | ${drift} |`);
+    lines.push(`| \`${a.axis_id}\` | ${cls} | ${achievedCell(a)} | ${a.target} | ${drift} |`);
+  }
+
+  const unknown = r.per_axis.filter((a) => a.unknown);
+  if (unknown.length > 0) {
+    lines.push('');
+    lines.push(`## Not checked`);
+    lines.push('');
+    lines.push(`Counted as not met; the level stops below.`);
+    lines.push('');
+    for (const a of unknown) lines.push(`- \`${a.axis_id}\` ${a.unknown!.level}: ${a.unknown!.reason}`);
+  }
+
+  const notes = r.per_axis.filter((a) => a.note);
+  if (notes.length > 0) {
+    lines.push('');
+    lines.push(`## In this clone`);
+    lines.push('');
+    lines.push(`Not part of the level: the same repository scores the same in every clone.`);
+    lines.push('');
+    for (const a of notes) lines.push(`- \`${a.axis_id}\`: ${a.note}`);
   }
 
   if (r.overrides.length > 0) {
@@ -65,6 +86,16 @@ export function reportMarkdown(r: AuditResult): string {
   return lines.join('\n') + '\n';
 }
 
+/** `L1`, `— (L3 ?)` for an axis that asks nothing below an unchecked L3, `L1 · L2 ?`, `L2 ⚑` with a clone note. */
+function achievedCell(a: AuditResult['per_axis'][number]): string {
+  if (a.suppressed || a.drift_kind === 'excluded') return a.achieved;
+  const shown = shownLevel(a);
+  let cell = shown ?? '—';
+  if (a.unknown) cell += shown ? ` · ${a.unknown.level} ?` : ` (${a.unknown.level} ?)`;
+  if (a.note) cell += ' ⚑';
+  return cell;
+}
+
 export function reportJson(r: AuditResult): string {
   return JSON.stringify(r, null, 2);
 }

package/src/rubric.ts

@@ -1,5 +1,7 @@
 import * as fs from 'node:fs';
 import YAML from 'js-yaml';
+import { COMBINATORS, predicateNames } from './evaluator.ts';
+import { REGISTRY, REMOVED_IN_0_3 } from './predicates.ts';
 
 export type LevelName = 'L0' | 'L1' | 'L2' | 'L3' | 'L4';
 export type AxisClass = 'critical' | 'supporting';
@@ -27,10 +29,23 @@ export interface Axis {
   storage: Storage;
   default_target: LevelName;
   fact_sources?: string[];
-  levels?: Partial<Record<LevelName, { requires: Predicate }>>;
+  /**
+   * A level is either a requirement or, from schema 0.3, `not_required`: the
+   * axis asks nothing at that level (branch-protection below L3). Such a level
+   * counts as met for the overall level, and the report does not show it as
+   * an achievement.
+   */
+  levels?: Partial<Record<LevelName, { requires?: Predicate; not_required?: boolean }>>;
   stack_implementations?: Record<string, StackImpl>;
   applies_to?: string[];
   applies_when?: Predicate;
+  /**
+   * From schema 0.3: a clone check whose result `vdx audit` prints next to the
+   * axis without changing its level — `git-hooks`: are the declared hooks on
+   * in this clone. A clone property cannot be a level (the same tag would score
+   * differently per clone), and without the note only `vdx doctor` would see it.
+   */
+  clone_check?: 'git-hooks';
 }
 
 export interface Rubric {
@@ -50,16 +65,77 @@ export interface Rubric {
   axes: Axis[];
 }
 
-export function loadRubric(yamlPath: string): Rubric {
-  const text = fs.readFileSync(yamlPath, 'utf8');
+/** The newest rubric schema this CLI reads. A newer set is refused, not misread. */
+export const SUPPORTED_SCHEMA = '0.3';
+
+function schemaParts(v: string): [number, number] | null {
+  const m = String(v).match(/^(\d+)\.(\d+)$/);
+  return m ? [parseInt(m[1]!, 10), parseInt(m[2]!, 10)] : null;
+}
+
+/** -1 / 0 / 1 as `a` is older / equal / newer than `b`; null when either is not `M.m`. */
+export function compareSchema(a: string, b: string): number | null {
+  const pa = schemaParts(a);
+  const pb = schemaParts(b);
+  if (!pa || !pb) return null;
+  return pa[0] !== pb[0] ? Math.sign(pa[0] - pb[0]) : Math.sign(pa[1] - pb[1]);
+}
+
+/**
+ * Predicates a 0.3 set may not name: removed ones, and any the registry does
+ * not know. In 0.2 an unknown name is a warning at evaluation, as it was.
+ */
+function invalidPredicates(rubric: Rubric): string[] {
+  const out = new Set<string>();
+  const check = (p: unknown, where: string) => {
+    for (const name of predicateNames(p)) {
+      if ((COMBINATORS as readonly string[]).includes(name)) continue;
+      if (REMOVED_IN_0_3.has(name)) out.add(`${where}: ${name} (removed in schema 0.3)`);
+      else if (!REGISTRY[name]) out.add(`${where}: ${name} (unknown predicate)`);
+    }
+  };
+  for (const ax of rubric.axes) {
+    if (ax.applies_when !== undefined) check(ax.applies_when, `${ax.id}.applies_when`);
+    for (const [L, lvl] of Object.entries(ax.levels ?? {})) {
+      if (lvl?.requires !== undefined) check(lvl.requires, `${ax.id}.${L}`);
+    }
+    for (const [stack, impl] of Object.entries(ax.stack_implementations ?? {})) {
+      for (const f of impl.flags ?? []) check(f.predicate, `${ax.id}.${stack}.${f.id}`);
+    }
+  }
+  return [...out];
+}
+
+export function parseRubric(text: string, source: string): Rubric {
   const data = YAML.load(text) as Rubric;
   if (!data || !data.schema_version || !data.axes) {
-    throw new Error(`Invalid rubric at ${yamlPath}: missing schema_version or axes`);
+    throw new Error(`Invalid rubric at ${source}: missing schema_version or axes`);
+  }
+  const schema = String(data.schema_version);
+  const cmp = compareSchema(schema, SUPPORTED_SCHEMA);
+  if (cmp === null) {
+    throw new Error(`Invalid rubric at ${source}: schema_version "${schema}" is not of the form M.m`);
+  }
+  if (cmp > 0) {
+    throw new Error(
+      `rubric ${source} is schema ${schema}; this vdx reads up to ${SUPPORTED_SCHEMA} — ` +
+        `update vdx (npm i -g @vodmal/vdx-cli@latest)`,
+    );
   }
   // нормализуем default_target (если кто-то напишет "L4" со spaces)
   for (const ax of data.axes) {
     ax.default_target = (ax.default_target ?? 'L4') as LevelName;
     ax.storage = (ax.storage ?? 'level') as Storage;
   }
+  if (compareSchema(schema, '0.3')! >= 0) {
+    const bad = invalidPredicates(data);
+    if (bad.length > 0) {
+      throw new Error(`rubric ${source} (schema ${schema}) names predicates it may not:\n  ${bad.join('\n  ')}`);
+    }
+  }
   return data;
 }
+
+export function loadRubric(yamlPath: string): Rubric {
+  return parseRubric(fs.readFileSync(yamlPath, 'utf8'), yamlPath);
+}

package/src/scoring.ts

@@ -1,6 +1,6 @@
 import type { Axis, LevelName, Rubric } from './rubric.ts';
 import type { Ctx } from './facts.ts';
-import { evalPredicate } from './evaluator.ts';
+import { evalPredicate, evalVerdict, isUnknown } from './evaluator.ts';
 
 const LEVELS: LevelName[] = ['L1', 'L2', 'L3', 'L4'];
 
@@ -14,25 +14,65 @@ export interface AxisResult {
   achieved: LevelName;
   target: LevelName;
   drift_kind: 'aligned' | 'gap' | 'over' | 'excluded';
+  /** Levels the axis asks nothing at; counted as met in `achieved`, not shown as an achievement. */
+  not_required?: LevelName[];
+  /** The level whose requirement could not be checked, and why; the ascent stopped there. */
+  unknown?: { level: LevelName; reason: string };
+  /** A clone check printed next to the axis; does not change the level. */
+  note?: string;
+}
+
+export interface AxisEvaluation {
+  achieved: LevelName;
+  not_required?: LevelName[];
+  unknown?: { level: LevelName; reason: string };
 }
 
 export function evalAxis(axis: Axis, ctx: Ctx): LevelName {
-  if (axis.storage === 'flags') return evalAxisFlags(axis, ctx);
+  return evalAxisDetailed(axis, ctx).achieved;
+}
+
+export function evalAxisDetailed(axis: Axis, ctx: Ctx): AxisEvaluation {
+  if (axis.storage === 'flags') return { achieved: evalAxisFlags(axis, ctx) };
   return evalAxisLevels(axis, ctx);
 }
 
-function evalAxisLevels(axis: Axis, ctx: Ctx): LevelName {
+function evalAxisLevels(axis: Axis, ctx: Ctx): AxisEvaluation {
   let achieved: LevelName = 'L0';
+  const notRequired: LevelName[] = [];
+  let unknown: AxisEvaluation['unknown'];
   for (const L of LEVELS) {
     const lvl = axis.levels?.[L];
     if (!lvl) break;
-    if (evalPredicate(lvl.requires, ctx)) {
+    if (lvl.not_required === true) {
+      achieved = L;
+      notRequired.push(L);
+      continue;
+    }
+    const v = evalVerdict(lvl.requires, ctx);
+    if (v === true) {
       achieved = L;
     } else {
-      break; // delta-style: discontinuity → stop ascent
+      // delta-style: discontinuity → stop ascent; unknown is "not met", named
+      if (isUnknown(v)) unknown = { level: L, reason: v.unknown };
+      break;
     }
   }
-  return achieved;
+  return {
+    achieved,
+    ...(notRequired.length > 0 ? { not_required: notRequired } : {}),
+    ...(unknown ? { unknown } : {}),
+  };
+}
+
+/**
+ * The level a report shows: the highest met level that asked something.
+ * `null` — none did (an unprotected repo's branch-protection is not "L2").
+ */
+export function shownLevel(r: Pick<AxisResult, 'achieved' | 'not_required'>): LevelName | null {
+  let n = levelToInt(r.achieved);
+  while (n > 0 && r.not_required?.includes(`L${n}` as LevelName)) n--;
+  return n === 0 && r.not_required?.length ? null : (`L${n}` as LevelName);
 }
 
 function evalAxisFlags(axis: Axis, ctx: Ctx): LevelName {

package/src/vocabulary.ts

@@ -0,0 +1,150 @@
+/**
+ * Which project tasks a command line calls through the project's own runner
+ * (mise, vdx, composer, npm/pnpm/yarn/bun, make, just, task), and what a task
+ * calls in turn. Shared by the `ci` predicates (what CI runs) and the hook
+ * predicates (what a hook runs), so both read "the project's task" the same way.
+ */
+import { listAllTasks, readJson, readToml, type Ctx } from './facts.ts';
+
+export const LIFECYCLE_VOCABULARY = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
+
+/** npm-family options that take a value; their value is not the script name. */
+const VALUE_OPTIONS = new Set(['--prefix', '-C', '--dir', '-w', '--workspace', '--filter', '--cwd']);
+
+/** Whitespace split that keeps quoted spans together and drops the quotes. */
+function tokenize(s: string): string[] {
+  const out: string[] = [];
+  const re = /"((?:\\.|[^"\\])*)"|'([^']*)'|(\S+)/g;
+  for (const m of s.matchAll(re)) out.push(m[1] ?? m[2] ?? m[3] ?? '');
+  return out;
+}
+
+function positionalArgs(tokens: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]!;
+    if (t.startsWith('-')) {
+      if (VALUE_OPTIONS.has(t)) i++;
+      continue;
+    }
+    out.push(t);
+  }
+  return out;
+}
+
+/** Task names a shell command calls through a project runner, in order. */
+export function runnerCalls(command: string): string[] {
+  const out: string[] = [];
+  for (const raw of command.split(/&&|\|\||;|\n|\|/)) {
+    const toks = tokenize(raw.trim());
+    let i = 0;
+    // `FOO=1 npm test`, `exec npm test`, `npx --no -- vdx test`
+    while (i < toks.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i]!) || ['exec', 'time', 'command'].includes(toks[i]!))) i++;
+    const head = toks[i];
+    if (!head) continue;
+    const runner = head.split('/').pop()!;
+    const args = positionalArgs(toks.slice(i + 1));
+    const first = args[0];
+    switch (runner) {
+      case 'mise':
+        if ((first === 'run' || first === 'r') && args[1]) out.push(args[1]);
+        break;
+      case 'vdx':
+        if (first && (LIFECYCLE_VOCABULARY as readonly string[]).includes(first)) out.push(first);
+        break;
+      case 'composer':
+        if ((first === 'run-script' || first === 'run') && args[1]) out.push(args[1]);
+        else if (first) out.push(first);
+        break;
+      case 'npm':
+        if ((first === 'run' || first === 'run-script') && args[1]) out.push(args[1]);
+        else if (first === 'test' || first === 't' || first === 'tst') out.push('test');
+        break;
+      case 'pnpm':
+      case 'yarn':
+        if ((first === 'run' || first === 'run-script') && args[1]) out.push(args[1]);
+        else if (first) out.push(first);
+        break;
+      case 'bun':
+        // `bun test` is bun's own runner, not the project's script.
+        if (first === 'run' && args[1]) out.push(args[1]);
+        break;
+      case 'make':
+      case 'just':
+      case 'task':
+        if (first) out.push(first);
+        break;
+      default:
+        break;
+    }
+  }
+  return out;
+}
+
+/** Calls of tasks the project actually has (a runner word that is no task — `composer install` — is dropped). */
+export function projectTaskCalls(command: string, ctx: Ctx): string[] {
+  const tasks = listAllTasks(ctx);
+  return runnerCalls(command).filter((t) => tasks.has(t));
+}
+
+/** A name of the lifecycle vocabulary, or its namespaced form: `test`, `check:lint`. */
+export function isVocabularyTask(name: string, words: readonly string[] = ['test', 'check']): boolean {
+  return words.some((w) => name === w || name.startsWith(`${w}:`));
+}
+
+/** Tasks a task's definition calls: composer `@refs`, `npm run X` inside a script, mise `depends`/`run`. */
+export function taskChildren(ctx: Ctx, name: string): string[] {
+  const out: string[] = [];
+  const composer = readJson(ctx, 'composer.json');
+  const entry = composer?.scripts?.[name];
+  if (entry !== undefined) {
+    const list = Array.isArray(entry) ? entry : [entry];
+    for (const e of list) {
+      if (typeof e !== 'string') continue;
+      if (e.startsWith('@')) {
+        const [ref, ...rest] = e.slice(1).trim().split(/\s+/);
+        if (ref === 'composer') out.push(...runnerCalls(`composer ${rest.join(' ')}`));
+        else if (ref && ref !== 'php' && ref !== 'putenv') out.push(ref);
+      } else {
+        out.push(...runnerCalls(e));
+      }
+    }
+  }
+  const pkg = readJson(ctx, 'package.json');
+  const script = pkg?.scripts?.[name];
+  if (typeof script === 'string') out.push(...runnerCalls(script));
+  const mise = readToml(ctx, 'mise.toml');
+  const task = mise?.tasks?.[name];
+  if (task && typeof task === 'object') {
+    if (Array.isArray(task.depends)) out.push(...task.depends.filter((d: unknown): d is string => typeof d === 'string'));
+    const runs = Array.isArray(task.run) ? task.run : [task.run];
+    for (const r of runs) if (typeof r === 'string') out.push(...runnerCalls(r));
+  }
+  const tasks = listAllTasks(ctx);
+  return [...new Set(out.filter((t) => t !== name && tasks.has(t)))];
+}
+
+/** A set of task names together with everything they call, transitively. */
+export function expandTasks(ctx: Ctx, names: Iterable<string>): Set<string> {
+  const seen = new Set<string>();
+  const queue = [...names];
+  while (queue.length > 0) {
+    const t = queue.shift()!;
+    if (seen.has(t)) continue;
+    seen.add(t);
+    queue.push(...taskChildren(ctx, t));
+  }
+  return seen;
+}
+
+/**
+ * Does `have` cover task `t`: it is called itself, or every task it calls is
+ * covered (CI calls `check`, the hook calls the `check:*` it consists of).
+ */
+export function covers(ctx: Ctx, have: Set<string>, t: string, seen = new Set<string>()): boolean {
+  if (have.has(t)) return true;
+  if (seen.has(t)) return false;
+  seen.add(t);
+  const children = taskChildren(ctx, t);
+  return children.length > 0 && children.every((c) => covers(ctx, have, c, seen));
+}