@vodmal/vdx-cli 0.2.0

package/src/audit.ts

@@ -0,0 +1,142 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Rubric, LevelName } from './rubric.ts';
+import { findSubPackages, type Ctx } from './facts.ts';
+import type { Override, VdxManifest } from './manifest.ts';
+import { evalAxis, projectLevel, type AxisResult } from './scoring.ts';
+
+function levelToInt(L: LevelName): number {
+  return parseInt(L.slice(1), 10);
+}
+
+export interface AuditResult {
+  baseline: string;
+  stack: string;
+  achieved_level: LevelName;
+  per_axis: Array<AxisResult & { suppressed?: boolean; override_target?: LevelName }>;
+  overrides: Override[];
+  expired_overrides: string[];
+  primary_subpackage?: string;
+}
+
+/**
+ * Резолвит ctx для stack-specific осей (с `applies_to`). Источник subpackage:
+ *   1. manifest.primary_subpackage (explicit) — если папка существует.
+ *   2. findSubPackages() auto-detect — если ровно один subpackage совпадает с ctx.stack.
+ *   3. fallback на root ctx.
+ *
+ * Возвращает `{ ctx, relPath }` где relPath — относительный путь либо null
+ * (если subpackage не разрезолвился — будем использовать root).
+ */
+function resolveSubpackageCtx(
+  ctx: Ctx,
+  manifest: VdxManifest | null,
+): { ctx: Ctx; relPath: string | null } {
+  let relPath: string | null = null;
+
+  if (manifest?.primary_subpackage) {
+    const p = manifest.primary_subpackage;
+    const abs = path.join(ctx.projectRoot, p);
+    if (fs.existsSync(abs)) {
+      relPath = p;
+    } else {
+      process.stderr.write(
+        `warning: primary_subpackage "${p}" does not exist — falling back to root\n`,
+      );
+    }
+  } else {
+    const subs = findSubPackages(ctx.projectRoot);
+    const matching = subs.filter((s) => s.stack === ctx.stack);
+    if (matching.length === 1) {
+      relPath = matching[0]!.relPath;
+    }
+  }
+
+  if (!relPath) return { ctx, relPath: null };
+  return {
+    ctx: {
+      projectRoot: path.join(ctx.projectRoot, relPath),
+      stack: ctx.stack,
+      cache: new Map(),
+    },
+    relPath,
+  };
+}
+
+export function audit(
+  rubric: Rubric,
+  ctx: Ctx,
+  overrides: Override[],
+  baselineRef: string,
+  manifest: VdxManifest | null = null,
+): AuditResult {
+  const suppressed = new Set<string>();
+  const overrideByAxis = new Map<string, Override>();
+  const expired: string[] = [];
+  const today = new Date().toISOString().slice(0, 10);
+
+  for (const ov of overrides) {
+    overrideByAxis.set(ov.axis, ov);
+    if (ov.suppress) suppressed.add(ov.axis);
+    if (ov.until && ov.until < today) expired.push(ov.axis);
+  }
+
+  const { ctx: subpackageCtx, relPath: subpackagePath } = resolveSubpackageCtx(ctx, manifest);
+
+  const perAxis: AuditResult['per_axis'] = [];
+  for (const axis of rubric.axes) {
+    if (suppressed.has(axis.id)) {
+      perAxis.push({
+        axis_id: axis.id,
+        class: axis.class,
+        achieved: 'L0',
+        target: axis.default_target,
+        drift_kind: 'aligned',
+        suppressed: true,
+      });
+      continue;
+    }
+    if (axis.applies_to && !axis.applies_to.includes(ctx.stack)) {
+      perAxis.push({
+        axis_id: axis.id,
+        class: axis.class,
+        achieved: 'L0',
+        target: axis.default_target,
+        drift_kind: 'excluded',
+      });
+      continue;
+    }
+    const evalCtx = axis.applies_to ? subpackageCtx : ctx;
+    const achieved = evalAxis(axis, evalCtx);
+    const ov = overrideByAxis.get(axis.id);
+    const target = (ov?.target as LevelName) ?? axis.default_target;
+    const drift: 'aligned' | 'gap' | 'over' =
+      levelToInt(achieved) === levelToInt(target)
+        ? 'aligned'
+        : levelToInt(achieved) < levelToInt(target)
+          ? 'gap'
+          : 'over';
+    const entry: AuditResult['per_axis'][number] = {
+      axis_id: axis.id,
+      class: axis.class,
+      achieved,
+      target,
+      drift_kind: drift,
+    };
+    if (ov?.target) entry.override_target = ov.target as LevelName;
+    perAxis.push(entry);
+  }
+
+  const overall = projectLevel(perAxis, rubric, suppressed);
+
+  const result: AuditResult = {
+    baseline: baselineRef,
+    stack: ctx.stack,
+    achieved_level: overall,
+    per_axis: perAxis,
+    overrides,
+    expired_overrides: expired,
+  };
+  if (subpackagePath) result.primary_subpackage = subpackagePath;
+  return result;
+}

package/src/defaults.ts

@@ -0,0 +1,10 @@
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export const BUNDLED_RUBRIC_PATH = path.resolve(here, '..', 'rubric', 'vdx-rubric.yaml');
+
+export function resolveDefaultRubric(): string {
+  return process.env['VDX_RUBRIC'] ?? BUNDLED_RUBRIC_PATH;
+}

package/src/evaluator.ts

@@ -0,0 +1,72 @@
+import type { Predicate } from './rubric.ts';
+import type { Ctx } from './facts.ts';
+import { REGISTRY } from './predicates.ts';
+
+/**
+ * Sugar shorthand: `{ has_task: "up" }` → `{ fn: "has_task", args: { task: "up" } }`
+ * For predicates whose single primary arg has a known name.
+ */
+const SUGAR_ARG_KEY: Record<string, string> = {
+  has_task: 'task',
+  has_task_matching: 'pattern',
+  has_file: 'path',
+  package_present: 'name',
+  git_hook_installed: 'hook',
+  phpstan_level_at_least: 'n',
+};
+
+export function evalPredicate(p: Predicate, ctx: Ctx): boolean {
+  if (p === null || p === undefined) return false;
+  if (typeof p === 'boolean') return p;
+
+  if (typeof p === 'object' && !Array.isArray(p)) {
+    const obj = p as Record<string, any>;
+
+    if ('all_of' in obj) {
+      const list = obj.all_of as Predicate[];
+      return list.every((q) => evalPredicate(q, ctx));
+    }
+    if ('any_of' in obj) {
+      const list = obj.any_of as Predicate[];
+      return list.some((q) => evalPredicate(q, ctx));
+    }
+    if ('at_least_n_of' in obj) {
+      const { n, predicates } = obj.at_least_n_of as { n: number; predicates: Predicate[] };
+      let matched = 0;
+      for (const q of predicates) if (evalPredicate(q, ctx)) matched += 1;
+      return matched >= n;
+    }
+    if ('not' in obj) {
+      return !evalPredicate(obj.not, ctx);
+    }
+    if ('fn' in obj) {
+      const fn = REGISTRY[String(obj.fn)];
+      if (!fn) {
+        process.stderr.write(`warning: unknown predicate "${obj.fn}"\n`);
+        return false;
+      }
+      return fn(obj.args ?? {}, ctx);
+    }
+
+    // Sugar form: single-key object where key is a registered predicate
+    const keys = Object.keys(obj);
+    if (keys.length === 1) {
+      const key = keys[0]!;
+      const fn = REGISTRY[key];
+      if (fn) {
+        const value = obj[key];
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+          return fn(value, ctx);
+        }
+        const argKey = SUGAR_ARG_KEY[key];
+        if (argKey) {
+          return fn({ [argKey]: value }, ctx);
+        }
+        return fn({ value }, ctx);
+      }
+    }
+  }
+
+  process.stderr.write(`warning: malformed predicate ${JSON.stringify(p)}\n`);
+  return false;
+}

package/src/facts.ts

@@ -0,0 +1,262 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as TOML from 'smol-toml';
+import * as YAML from 'js-yaml';
+
+export interface Ctx {
+  projectRoot: string;
+  stack: string;
+  cache: Map<string, unknown>;
+}
+
+export function fileExists(ctx: Ctx, rel: string): boolean {
+  return fs.existsSync(path.join(ctx.projectRoot, rel));
+}
+
+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 = path.join(ctx.projectRoot, rel);
+  try {
+    const t = fs.readFileSync(abs, 'utf8');
+    ctx.cache.set(key, t);
+    return t;
+  } catch {
+    ctx.cache.set(key, null);
+    return null;
+  }
+}
+
+export function readJson(ctx: Ctx, rel: string): any {
+  const key = `json:${rel}`;
+  if (ctx.cache.has(key)) return ctx.cache.get(key);
+  const text = readText(ctx, rel);
+  if (text === null) {
+    ctx.cache.set(key, null);
+    return null;
+  }
+  try {
+    const data = JSON.parse(text);
+    ctx.cache.set(key, data);
+    return data;
+  } catch {
+    ctx.cache.set(key, null);
+    return null;
+  }
+}
+
+export function readToml(ctx: Ctx, rel: string): any {
+  const key = `toml:${rel}`;
+  if (ctx.cache.has(key)) return ctx.cache.get(key);
+  const text = readText(ctx, rel);
+  if (text === null) {
+    ctx.cache.set(key, null);
+    return null;
+  }
+  try {
+    const data = TOML.parse(text);
+    ctx.cache.set(key, data);
+    return data;
+  } catch {
+    ctx.cache.set(key, null);
+    return null;
+  }
+}
+
+export function readYaml(ctx: Ctx, rel: string): any {
+  const key = `yaml:${rel}`;
+  if (ctx.cache.has(key)) return ctx.cache.get(key);
+  const text = readText(ctx, rel);
+  if (text === null) {
+    ctx.cache.set(key, null);
+    return null;
+  }
+  try {
+    const data = YAML.load(text);
+    ctx.cache.set(key, data);
+    return data;
+  } catch {
+    ctx.cache.set(key, null);
+    return null;
+  }
+}
+
+/** Parse a structured file by extension. Returns parsed object/array or null. */
+export function readStructured(ctx: Ctx, rel: string): any {
+  const lower = rel.toLowerCase();
+  if (lower.endsWith('.json')) return readJson(ctx, rel);
+  if (lower.endsWith('.toml')) return readToml(ctx, rel);
+  if (lower.endsWith('.yaml') || lower.endsWith('.yml')) return readYaml(ctx, rel);
+  return null;
+}
+
+/**
+ * Resolve a dot-notation path inside a parsed config object.
+ * Supports plain dots only — array indices and bracket notation are not used by
+ * the current rubric. Returns `undefined` if any segment is missing.
+ */
+export function resolveConfigPath(root: unknown, jsonpath: string): unknown {
+  if (root === null || root === undefined) return undefined;
+  const parts = jsonpath.split('.');
+  let cur: any = root;
+  for (const part of parts) {
+    if (cur === null || cur === undefined) return undefined;
+    if (typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  return cur;
+}
+
+/** Aggregated task names from mise.toml, composer scripts, npm scripts, Makefile. */
+export function listAllTasks(ctx: Ctx): Set<string> {
+  const key = 'tasks:all';
+  if (ctx.cache.has(key)) return ctx.cache.get(key) as Set<string>;
+  const tasks = new Set<string>();
+
+  const miseT = readToml(ctx, 'mise.toml');
+  if (miseT?.tasks && typeof miseT.tasks === 'object') {
+    for (const k of Object.keys(miseT.tasks as object)) tasks.add(k);
+  }
+
+  const composer = readJson(ctx, 'composer.json');
+  if (composer?.scripts && typeof composer.scripts === 'object') {
+    for (const k of Object.keys(composer.scripts)) tasks.add(k);
+  }
+
+  const pkg = readJson(ctx, 'package.json');
+  if (pkg?.scripts && typeof pkg.scripts === 'object') {
+    for (const k of Object.keys(pkg.scripts)) tasks.add(k);
+  }
+
+  // monorepo-ish fallback: server/package.json (см. bookmap)
+  const serverPkg = readJson(ctx, 'server/package.json');
+  if (serverPkg?.scripts && typeof serverPkg.scripts === 'object') {
+    for (const k of Object.keys(serverPkg.scripts)) tasks.add(`server:${k}`);
+  }
+
+  const make = readText(ctx, 'Makefile');
+  if (make) {
+    const lines = make.split('\n');
+    for (const line of lines) {
+      const m = line.match(/^([a-zA-Z0-9_.\-:]+)\s*:[^=]/);
+      if (m && m[1] && !m[1].startsWith('.')) tasks.add(m[1]);
+    }
+  }
+
+  ctx.cache.set(key, tasks);
+  return tasks;
+}
+
+export function isPackagePresent(name: string, ecosystem: string, ctx: Ctx): boolean {
+  const eco = ecosystem ?? 'any';
+  if (eco === 'any' || eco === 'composer') {
+    const composer = readJson(ctx, 'composer.json');
+    if (composer) {
+      if (composer.require?.[name]) return true;
+      if (composer['require-dev']?.[name]) return true;
+    }
+  }
+  if (eco === 'any' || eco === 'npm') {
+    for (const rel of ['package.json', 'server/package.json']) {
+      const pkg = readJson(ctx, rel);
+      if (pkg) {
+        if (pkg.dependencies?.[name]) return true;
+        if (pkg.devDependencies?.[name]) return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function expandPaths(paths: string[], ctx: Ctx): string[] {
+  const out: string[] = [];
+  for (const p of paths) {
+    if (p.includes('*')) {
+      const m = p.match(/^([^*]+)\/\*\.(.+)$/);
+      if (m && m[1] && m[2]) {
+        const dir = m[1];
+        const ext = m[2];
+        const abs = path.join(ctx.projectRoot, 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 */
+        }
+      }
+    } else {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+export function readTsconfig(ctx: Ctx): any {
+  let cfg = readJson(ctx, 'tsconfig.json');
+  if (!cfg) cfg = readJson(ctx, 'server/tsconfig.json');
+  if (!cfg) return null;
+  // basic one-level `extends` resolution
+  if (cfg.extends && typeof cfg.extends === 'string' && cfg.extends.startsWith('.')) {
+    const baseRel = cfg.extends.endsWith('.json') ? cfg.extends : `${cfg.extends}.json`;
+    const base = readJson(ctx, baseRel);
+    if (base?.compilerOptions) {
+      cfg.compilerOptions = { ...base.compilerOptions, ...(cfg.compilerOptions ?? {}) };
+    }
+  }
+  return cfg;
+}
+
+const MANIFEST_TO_STACK: Array<[string, string]> = [
+  ['composer.json', 'php'],
+  ['package.json', 'node'],
+  ['go.mod', 'go'],
+  ['pyproject.toml', 'python'],
+  ['requirements.txt', 'python'],
+];
+
+function stackForDir(dir: string): string | null {
+  for (const [manifest, stack] of MANIFEST_TO_STACK) {
+    if (fs.existsSync(path.join(dir, manifest))) return stack;
+  }
+  return null;
+}
+
+const SUBPACKAGE_SCAN_IGNORE = new Set([
+  'node_modules', 'vendor', 'dist', 'build', 'out', 'target',
+  '.git', '.next', '__pycache__', '.venv', 'venv', '.cache', 'coverage',
+]);
+
+export interface SubPackage {
+  relPath: string;
+  stack: string;
+}
+
+export function findSubPackages(projectRoot: string): SubPackage[] {
+  const found: SubPackage[] = [];
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.')) continue;
+    if (SUBPACKAGE_SCAN_IGNORE.has(entry.name)) continue;
+    const stack = stackForDir(path.join(projectRoot, entry.name));
+    if (stack) found.push({ relPath: entry.name, stack });
+  }
+  return found;
+}
+
+export function autoDetectStack(projectRoot: string): string {
+  const rootStack = stackForDir(projectRoot);
+  if (rootStack) return rootStack;
+  const subs = findSubPackages(projectRoot);
+  if (subs.length === 0) return 'unknown';
+  const stacks = new Set(subs.map((s) => s.stack));
+  if (stacks.size === 1) return subs[0]!.stack;
+  return 'monorepo';
+}

package/src/index.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import * as path from 'node:path';
+import { loadRubric } from './rubric.ts';
+import { loadManifest, loadOverrides } from './manifest.ts';
+import { autoDetectStack, type Ctx } from './facts.ts';
+import { audit } from './audit.ts';
+import { reportMarkdown, reportJson } from './report.ts';
+import { planInit, writeInit, renderPlanSummary } from './init.ts';
+import { resolveDefaultRubric } from './defaults.ts';
+
+const DEFAULT_RUBRIC = resolveDefaultRubric();
+
+function usage(): never {
+  process.stderr.write(
+    `Usage:
+  vdx audit <project_path> [--rubric <path>] [--stack <stack>] [--json]
+  vdx init  <project_path> [--baseline <ref>] [--dry-run] [--force]
+`,
+  );
+  process.exit(1);
+}
+
+interface ParsedArgs {
+  cmd: string;
+  positionals: string[];
+  flags: Record<string, string | boolean>;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const cmd = argv[2] ?? '';
+  const rest = argv.slice(3);
+  const positionals: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (a.startsWith('--')) {
+      const name = a.slice(2);
+      const next = rest[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[name] = next;
+        i++;
+      } else {
+        flags[name] = true;
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { cmd, positionals, flags };
+}
+
+function cmdAudit(opts: ParsedArgs): void {
+  const projectArg = opts.positionals[0];
+  if (!projectArg) usage();
+  const projectRoot = path.resolve(projectArg);
+
+  const manifest = loadManifest(projectRoot);
+  const overrides = loadOverrides(projectRoot);
+
+  const rubricPath = (opts.flags.rubric as string) || DEFAULT_RUBRIC;
+  const rubric = loadRubric(rubricPath);
+
+  const stack =
+    (opts.flags.stack as string) || manifest?.stack || autoDetectStack(projectRoot);
+
+  const ctx: Ctx = {
+    projectRoot,
+    stack,
+    cache: new Map(),
+  };
+
+  const baselineRef = manifest?.baseline ?? `file://${rubricPath}`;
+  const result = audit(rubric, ctx, overrides, baselineRef, manifest);
+
+  if (opts.flags.json) {
+    process.stdout.write(reportJson(result) + '\n');
+  } else {
+    process.stdout.write(reportMarkdown(result));
+  }
+}
+
+function cmdInit(opts: ParsedArgs): void {
+  const projectArg = opts.positionals[0];
+  if (!projectArg) usage();
+  const projectRoot = path.resolve(projectArg);
+
+  const baselineFlag = opts.flags.baseline;
+  const baseline = typeof baselineFlag === 'string' ? baselineFlag : undefined;
+  const plan = planInit(projectRoot, baseline ? { baseline } : {});
+
+  process.stdout.write(renderPlanSummary(plan));
+
+  if (opts.flags['dry-run']) {
+    process.stderr.write('\n[dry-run] mise.toml / AGENTS.md не записаны.\n');
+    return;
+  }
+  try {
+    writeInit(plan, { force: Boolean(opts.flags.force) });
+    process.stderr.write(
+      `\n✓ Записаны:\n  ${plan.miseTomlPath}\n  ${plan.agentsMdPath}\n`,
+    );
+  } catch (e: any) {
+    process.stderr.write(`\nerror: ${e?.message ?? String(e)}\n`);
+    process.exit(2);
+  }
+}
+
+const parsed = parseArgs(process.argv);
+if (parsed.cmd === 'audit') cmdAudit(parsed);
+else if (parsed.cmd === 'init') cmdInit(parsed);
+else usage();