@vodmal/vdx-cli 0.27.0 → 0.29.0

package/README.md

@@ -112,6 +112,13 @@ By default the bundled `rubric/vdx-rubric.yaml` is used (a mirror of canonical
 [vdx-rubric-vodmal](https://github.com/VoDmAl/vdx-rubric-vodmal) at the time of
 each CLI release). Override via `--rubric <path>` or the env var `VDX_RUBRIC`.
 
+`branch-protection` is the one axis the files cannot answer: `vdx audit` asks
+GitHub whether the default branch of `origin` takes changes only after a check
+required of everyone, admins included. A public repo needs no token; a private
+one takes it from `GH_TOKEN`, `GITHUB_TOKEN` or `gh auth token`. Another
+hosting, no network or no token where one is needed leave the axis unknown,
+with the reason in the report; `VDX_OFFLINE=1` does not ask at all.
+
 ## Dev
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.27.0",
+  "version": "0.29.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/rubric/vdx-rubric.yaml

@@ -11,7 +11,7 @@ schema_version: "0.3"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "1.4.2"
+  version: "1.5.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"
@@ -470,6 +470,10 @@ axes:
 
   - id: observability
     class: supporting
+    # v1.5.0: логгер, Sentry и релиз в Sentry — у процесса, который работает и
+    # падает без человека. Библиотека и CLI (lib-intent) пишут в stderr и код
+    # выхода — у них ось excluded. Определение lib-intent — в lifecycle-interface.L3.
+    applies_when: { not: *lib_intent }
     storage: level
     default_target: L4
     fact_sources: [composer.json, package.json, .github/workflows/]
@@ -526,6 +530,9 @@ axes:
   - id: mock-infra
     class: supporting
     applies_to: [php, node, go, python]
+    # v1.5.0: mock-сервер и проверка, что моков нет в проде, — у сервиса с
+    # зависимостями. У библиотеки и CLI (lib-intent) ось excluded.
+    applies_when: { not: *lib_intent }
     storage: level
     default_target: L4
     fact_sources: [composer.json, package.json, docker-compose.yml, mock-server/]

package/src/facts.ts

@@ -16,12 +16,43 @@ export interface Ctx {
   fallbackRoot?: string;
 }
 
-/** Absolute path of `rel`: here, else in `fallbackRoot` when it is there. */
-function locate(ctx: Ctx, rel: string): string {
-  const here = path.join(ctx.projectRoot, rel);
-  if (ctx.fallbackRoot === undefined || fs.existsSync(here)) return here;
-  const there = path.join(ctx.fallbackRoot, rel);
-  return fs.existsSync(there) ? there : here;
+/** Names in `dir`, read once per context; none when it cannot be read. */
+function entries(ctx: Ctx, dir: string): string[] {
+  const key = `dir:${dir}`;
+  let names = ctx.cache.get(key) as string[] | undefined;
+  if (!names) {
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      names = [];
+    }
+    ctx.cache.set(key, names);
+  }
+  return names;
+}
+
+/**
+ * `rel` under `root`, each segment in the case it is written. APFS and NTFS find a file
+ * under any case and ext4 does not: `tests/Fixtures` was there on a Mac that has only
+ * `tests/fixtures`, and the same project got another level on Linux.
+ */
+function existsAsWritten(ctx: Ctx, root: string, rel: string): boolean {
+  let dir = root;
+  for (const name of path.normalize(rel).split(path.sep)) {
+    if (name === '' || name === '.') continue;
+    if (name !== '..' && !entries(ctx, dir).includes(name)) return false;
+    dir = path.join(dir, name);
+  }
+  return fs.existsSync(dir);
+}
+
+/** Absolute path of `rel`: here, else in `fallbackRoot`; null when in neither. */
+function locate(ctx: Ctx, rel: string): string | null {
+  if (existsAsWritten(ctx, ctx.projectRoot, rel)) return path.join(ctx.projectRoot, rel);
+  if (ctx.fallbackRoot !== undefined && existsAsWritten(ctx, ctx.fallbackRoot, rel)) {
+    return path.join(ctx.fallbackRoot, rel);
+  }
+  return null;
 }
 
 /** The same directory without the fallback: a project's tasks are the ones its own runner sees. */
@@ -36,13 +67,17 @@ function ownCtx(ctx: Ctx): Ctx {
 }
 
 export function fileExists(ctx: Ctx, rel: string): boolean {
-  return fs.existsSync(locate(ctx, rel));
+  return locate(ctx, rel) !== null;
 }
 
 export function readText(ctx: Ctx, rel: string): string | null {
   const key = `file:${rel}`;
   if (ctx.cache.has(key)) return ctx.cache.get(key) as string | null;
   const abs = locate(ctx, rel);
+  if (abs === null) {
+    ctx.cache.set(key, null);
+    return null;
+  }
   try {
     const t = fs.readFileSync(abs, 'utf8');
     ctx.cache.set(key, t);
@@ -183,13 +218,9 @@ export function expandPaths(paths: string[], ctx: Ctx): string[] {
         const dir = m[1];
         const ext = m[2];
         const abs = locate(ctx, dir);
-        try {
-          const files = fs.readdirSync(abs);
-          for (const f of files) {
-            if (f.endsWith('.' + ext)) out.push(path.join(dir, f));
-          }
-        } catch {
-          /* dir missing — silent */
+        // A missing dir lists nothing.
+        for (const f of abs === null ? [] : entries(ctx, abs)) {
+          if (f.endsWith('.' + ext)) out.push(path.join(dir, f));
         }
       }
     } else {

package/src/hosting.ts

@@ -0,0 +1,168 @@
+import { execFileSync } from 'node:child_process';
+import { remoteParts } from './author.ts';
+import type { Ctx } from './facts.ts';
+import { at, errorMessage, list, str } from './narrow.ts';
+import type { Unknown, Verdict } from './predicates.ts';
+
+/** One answer of the GitHub API: its status and its body, parsed (null when not JSON). */
+export interface Answer {
+  status: number;
+  body: unknown;
+}
+
+/** What the check needs from outside — the machine's own below, recorded answers in the tests. */
+export interface HostingIo {
+  env: NodeJS.ProcessEnv;
+  /** `git <args>` in the project, trimmed; null when git fails. */
+  git: (args: string[]) => string | null;
+  /** The token `gh` keeps; null without gh or a login. */
+  ghToken: () => string | null;
+  /** GET of an api.github.com path. Throws when no answer came at all. */
+  get: (apiPath: string, token: string | null) => Answer;
+}
+
+// A child node runs the request: the audit is synchronous and fetch is not
+// (DL #6 of docs/tasks/hosting-extension). The token travels in its
+// environment, not its arguments — those are visible in ps.
+const GET = `
+const headers = { accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'user-agent': 'vdx' };
+if (process.env.VDX_GITHUB_TOKEN) headers.authorization = 'Bearer ' + process.env.VDX_GITHUB_TOKEN;
+try {
+  const r = await fetch(process.argv[1], { headers, signal: AbortSignal.timeout(8000) });
+  process.stdout.write(JSON.stringify({ status: r.status, text: await r.text() }));
+} catch (e) {
+  process.stdout.write(JSON.stringify({ error: String(e?.cause?.code ?? e?.cause?.message ?? e?.message ?? e) }));
+}
+`;
+
+function get(apiPath: string, token: string | null): Answer {
+  const env = { ...process.env };
+  delete env.VDX_GITHUB_TOKEN;
+  if (token) env.VDX_GITHUB_TOKEN = token;
+  const out: unknown = JSON.parse(
+    execFileSync(process.execPath, ['--input-type=module', '-e', GET, `https://api.github.com${apiPath}`], {
+      encoding: 'utf8',
+      env,
+      timeout: 10_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }),
+  );
+  const error = str(at(out, 'error'));
+  if (error !== undefined) throw new Error(error);
+  const status = at(out, 'status');
+  if (typeof status !== 'number') throw new Error('no status in the answer');
+  let body: unknown = null;
+  try {
+    body = JSON.parse(str(at(out, 'text')) ?? '');
+  } catch {
+    // not JSON: the status says enough
+  }
+  return { status, body };
+}
+
+function machineIo(root: string): HostingIo {
+  const run = (cmd: string, args: string[]): string | null => {
+    try {
+      return (
+        execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5_000 }).trim() ||
+        null
+      );
+    } catch {
+      return null;
+    }
+  };
+  return {
+    env: process.env,
+    git: (args) => run('git', ['--no-optional-locks', '-C', root, ...args]),
+    ghToken: () => run('gh', ['auth', 'token']),
+    get,
+  };
+}
+
+/** A refusal of the API as the reason the answer is unknown; null for a 200. */
+function refusal(a: Answer, repo: string, token: string | null): Unknown | null {
+  if (a.status === 200) return null;
+  const message = str(at(a.body, 'message')) ?? '';
+  if ((a.status === 403 || a.status === 429) && message.startsWith('API rate limit exceeded')) {
+    return {
+      unknown: `GitHub's rate limit is spent${token ? '' : ' — 60 requests an hour without a token; gh auth login, or GH_TOKEN'}`,
+    };
+  }
+  if (a.status === 404 && !token) {
+    return { unknown: `GitHub does not show ${repo} without a token — private? gh auth login, or GH_TOKEN` };
+  }
+  return { unknown: `GitHub answered ${a.status} for ${repo}${message ? `: ${message}` : ''}` };
+}
+
+/** Checks a required-status-checks setting names: `checks`, else the older `contexts`. */
+function checkCount(setting: unknown): number {
+  return Math.max(list(at(setting, 'checks')).length, list(at(setting, 'contexts')).length);
+}
+
+function judge(io: HostingIo, repo: string, token: string | null): Verdict {
+  let branch = io.git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])?.replace(/^origin\//, '');
+  if (!branch) {
+    const r = io.get(`/repos/${repo}`, token);
+    const refused = refusal(r, repo, token);
+    if (refused) return refused;
+    branch = str(at(r.body, 'default_branch'));
+    if (!branch) return { unknown: `GitHub names no default branch for ${repo}` };
+  }
+  const ref = encodeURIComponent(branch);
+
+  // Classic protection: the checks are required of everyone, admins too (DL #3).
+  const b = io.get(`/repos/${repo}/branches/${ref}`, token);
+  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;
+
+  // 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;
+  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;
+    const id = at(rule, 'ruleset_id');
+    const ruleset = typeof id === 'number' ? io.get(`/repos/${repo}/rulesets/${id}`, token) : null;
+    const bypass = ruleset?.status === 200 ? at(ruleset.body, 'bypass_actors') : undefined;
+    if (!Array.isArray(bypass)) hidden = true;
+    else if (bypass.length === 0) return true;
+  }
+  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;
+}
+
+/**
+ * Whether the default branch on the hosting of `origin` takes changes only after a check
+ * required of everyone. GitHub only; what vdx cannot ask is unknown, with the reason.
+ */
+export function branchRequiresChecks(ctx: Ctx, io: HostingIo = machineIo(ctx.projectRoot)): Verdict {
+  const key = 'hosting:branch-requires-checks';
+  if (ctx.cache.has(key)) return ctx.cache.get(key) as Verdict;
+  const verdict = ask(io);
+  ctx.cache.set(key, verdict);
+  return verdict;
+}
+
+function ask(io: HostingIo): Verdict {
+  if (io.env.VDX_OFFLINE) return { unknown: 'VDX_OFFLINE is set — the hosting was not asked' };
+  const url = io.git(['remote', 'get-url', 'origin']);
+  if (!url) return { unknown: 'no origin remote — the hosting is not known' };
+  const { host, path: repo } = remoteParts(url);
+  // The host only: a URL can carry a token.
+  if (host !== 'github.com')
+    return { unknown: `origin is on ${host || 'a host vdx cannot tell'} — vdx reads GitHub only` };
+  const token = io.env.GH_TOKEN || io.env.GITHUB_TOKEN || io.ghToken();
+  try {
+    return judge(io, repo, token);
+  } catch (e) {
+    return { unknown: `GitHub did not answer: ${errorMessage(e)}` };
+  }
+}

package/src/index.ts

@@ -125,6 +125,9 @@ const COMMANDS: Record<string, CommandSpec> = {
     usage: 'vdx audit [project_path] [--rubric <path>] [--stack <stack>] [--format=ansi|markdown|json] [--json]',
     help: `Scores the project (default: cwd) against the rubric and prints the report.
 Reads only. The rubric is the bundled one unless --rubric or $VDX_RUBRIC names another.
+For branch-protection it asks GitHub whether the default branch of origin requires
+a check, with a token from $GH_TOKEN, $GITHUB_TOKEN or gh when there is one;
+VDX_OFFLINE=1 does not ask, and the axis says unknown.
 `,
     bools: ['json'],
     values: ['rubric', 'stack', 'format'],

package/src/init.ts

@@ -6,7 +6,7 @@ import { at } from './narrow.ts';
 export const STANDARD_VERBS = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
 export type Verb = (typeof STANDARD_VERBS)[number];
 
-export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v1.4.2';
+export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v1.5.0';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
   up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],

package/src/predicates.ts

@@ -14,6 +14,7 @@ import {
 } from './facts.ts';
 import { checkingJobs, ciSystems, ciTaskCalls, mainPushSteps, readWorkflows, shippingJobs, upstream } from './gha.ts';
 import { detectHookFrameworks } from './hooks.ts';
+import { branchRequiresChecks } from './hosting.ts';
 import { covers, expandTasks, isVocabularyTask, projectTaskCalls } from './vocabulary.ts';
 import { at, isStringList, str } from './narrow.ts';
 
@@ -248,10 +249,8 @@ export const REGISTRY: Record<string, PredicateFn> = {
 
   // --- 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',
-  }),
+  /** L3: the default branch takes changes only after a check required of everyone — asked of GitHub (docs/tasks/hosting-extension). */
+  branch_requires_checks: (_args, ctx) => branchRequiresChecks(ctx),
 
   // --- git-hygiene: the hook recognizer (schema 0.3) ---