@nimiplatform/nimi-coding 0.1.0

package/cli/lib/internal/governance/ai/ai-structure-budget-core.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import YAML from 'yaml';
+
+function escapeRegex(input) {
+  return input.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+}
+
+function globToRegExp(glob) {
+  const normalized = glob.replace(/\\/g, '/').trim();
+  let pattern = '^';
+  for (let index = 0; index < normalized.length; index += 1) {
+    const current = normalized[index];
+    const next = normalized[index + 1];
+    if (current === '*') {
+      if (next === '*') {
+        const afterNext = normalized[index + 2];
+        if (afterNext === '/') {
+          pattern += '(?:.*/)?';
+          index += 2;
+        } else {
+          pattern += '.*';
+          index += 1;
+        }
+      } else {
+        pattern += '[^/]*';
+      }
+      continue;
+    }
+    if (current === '?') {
+      pattern += '[^/]';
+      continue;
+    }
+    pattern += escapeRegex(current);
+  }
+  pattern += '$';
+  return new RegExp(pattern);
+}
+
+function compileMatchers(patterns) {
+  return (patterns || []).map((pattern) => ({
+    pattern,
+    regex: globToRegExp(pattern),
+  }));
+}
+
+function normalizePathPrefix(input) {
+  return String(input || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\/+|\/+$/g, '');
+}
+
+function matchesAny(filePath, matchers) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const matcher of matchers) {
+    if (matcher.regex.test(normalized)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function parseDateMaybe(input) {
+  if (!input) {
+    return null;
+  }
+  if (input instanceof Date) {
+    return Number.isNaN(input.getTime()) ? null : input;
+  }
+  const parsed = new Date(String(input));
+  if (Number.isNaN(parsed.getTime())) {
+    return null;
+  }
+  return parsed;
+}
+
+function loadBudgetConfig(cwd, relativePath, inlineConfig, configPathLabel) {
+  const parsed = inlineConfig ?? (() => {
+    const configPath = path.join(cwd, relativePath);
+    if (!fs.existsSync(configPath)) {
+      throw new Error(`budget config not found: ${relativePath}`);
+    }
+    const raw = fs.readFileSync(configPath, 'utf8');
+    return YAML.parse(raw);
+  })();
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`invalid budget config format: ${relativePath}`);
+  }
+  if (!Array.isArray(parsed.rules) || parsed.rules.length === 0) {
+    throw new Error(`budget config missing rules: ${relativePath}`);
+  }
+  return {
+    configPath: configPathLabel || relativePath,
+    parsed,
+  };
+}
+
+function listTrackedFiles(cwd) {
+  const output = execSync('git ls-files -z', {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return output
+    .split('\u0000')
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+}
+
+function toSeverity(value, warningThreshold, errorThreshold) {
+  if (typeof errorThreshold === 'number' && value >= errorThreshold) {
+    return 'error';
+  }
+  if (typeof warningThreshold === 'number' && value >= warningThreshold) {
+    return 'warning';
+  }
+  return 'none';
+}
+
+function normalizeLines(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gmu, '')
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function isDisallowedForwardingShell(filePath, source, allowedBasenames) {
+  const basename = path.basename(filePath);
+  if (allowedBasenames.has(basename)) {
+    return false;
+  }
+
+  const lines = normalizeLines(source);
+  if (lines.length === 0) {
+    return false;
+  }
+
+  const tsPatterns = [
+    /^export\s+\*\s+from\s+['"].+['"];?$/u,
+    /^export\s+\*\s+as\s+\w+\s+from\s+['"].+['"];?$/u,
+    /^export\s+(type\s+)?\{[^}]+\}\s+from\s+['"].+['"];?$/u,
+  ];
+  const rustPatterns = [
+    /^mod\s+\w+;$/u,
+    /^pub\s+mod\s+\w+;$/u,
+    /^use\s+.+;$/u,
+    /^pub(\([^)]*\))?\s+use\s+.+;$/u,
+  ];
+
+  return lines.every((line) => tsPatterns.some((pattern) => pattern.test(line)) || rustPatterns.some((pattern) => pattern.test(line)));
+}
+
+function resolveRule(filePath, compiledRules) {
+  for (const rule of compiledRules) {
+    if (matchesAny(filePath, rule.matchers)) {
+      return rule;
+    }
+  }
+  return null;
+}
+
+function describeDepthSubject(filePath, depthBase) {
+  const normalizedFilePath = filePath.replace(/\\/g, '/');
+  if (!depthBase) {
+    return {
+      depthBase: '.',
+      depthSubject: normalizedFilePath,
+      depth: normalizedFilePath.split('/').length,
+    };
+  }
+
+  const normalizedBase = normalizePathPrefix(depthBase);
+  const prefix = `${normalizedBase}/`;
+  if (!normalizedFilePath.startsWith(prefix)) {
+    throw new Error(`depth_base "${normalizedBase}" does not match file "${normalizedFilePath}"`);
+  }
+
+  const depthSubject = normalizedFilePath.slice(prefix.length);
+  return {
+    depthBase: normalizedBase,
+    depthSubject,
+    depth: depthSubject ? depthSubject.split('/').length : 0,
+  };
+}
+
+function buildWaivers(waivers) {
+  return (waivers || []).map((waiver) => ({
+    ...waiver,
+    matcher: globToRegExp(String(waiver.pattern || '').trim()),
+    checks: new Set((waiver.checks || []).map((value) => String(value).trim()).filter(Boolean)),
+    hasUntil: typeof waiver.until !== 'undefined' && String(waiver.until).trim().length > 0,
+    untilDate: parseDateMaybe(waiver.until),
+  }));
+}
+
+function findWaiver(filePath, check, waivers) {
+  for (const waiver of waivers) {
+    if (!waiver.matcher.test(filePath)) {
+      continue;
+    }
+    if (waiver.checks.size > 0 && !waiver.checks.has(check)) {
+      continue;
+    }
+    return waiver;
+  }
+  return null;
+}
+
+function getWaiverDisposition(waiver) {
+  if (!waiver) {
+    return 'none';
+  }
+  if (!waiver.hasUntil) {
+    return 'active';
+  }
+  if (waiver.untilDate && waiver.untilDate.getTime() >= Date.now()) {
+    return 'active';
+  }
+  if (waiver.untilDate && waiver.untilDate.getTime() < Date.now()) {
+    return 'expired';
+  }
+  return 'none';
+}
+
+function compareRows(left, right) {
+  const severityRank = {
+    error: 2,
+    warning: 1,
+    none: 0,
+  };
+  if (severityRank[left.severity] !== severityRank[right.severity]) {
+    return severityRank[right.severity] - severityRank[left.severity];
+  }
+  if (left.check === 'depth' && right.check === 'depth' && left.depth !== right.depth) {
+    return right.depth - left.depth;
+  }
+  return left.file.localeCompare(right.file);
+}
+
+export function evaluateAiStructureBudget(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const configRelativePath = options.configRelativePath || 'config/ai/ai-structure-budget.yaml';
+  const { parsed, configPath } = loadBudgetConfig(
+    cwd,
+    configRelativePath,
+    options.config || null,
+    options.configPathLabel || null,
+  );
+  const excludeMatchers = compileMatchers(parsed.exclude || []);
+  const compiledRules = (parsed.rules || []).map((rule) => ({
+    id: String(rule.id || '').trim(),
+    warningDepth: Number(rule.warning_depth),
+    errorDepth: Number(rule.error_depth),
+    depthBase: normalizePathPrefix(rule.depth_base),
+    matchers: compileMatchers(rule.include || []),
+  }));
+  const waivers = buildWaivers(parsed.waivers || []);
+  const allowedForwardingShells = new Set((parsed.allowed_forwarding_shells || []).map((value) => String(value).trim()).filter(Boolean));
+
+  const files = listTrackedFiles(cwd);
+  const rows = [];
+  const warnings = [];
+  const errors = [];
+  const waivedErrors = [];
+  const expiredWaivers = [];
+  let analyzedFiles = 0;
+
+  for (const relativePath of files) {
+    if (matchesAny(relativePath, excludeMatchers)) {
+      continue;
+    }
+
+    const rule = resolveRule(relativePath, compiledRules);
+    if (!rule) {
+      continue;
+    }
+
+    const absolutePath = path.join(cwd, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+      continue;
+    }
+    analyzedFiles += 1;
+
+    const depthInfo = describeDepthSubject(relativePath, rule.depthBase);
+    const depth = depthInfo.depth;
+    const depthSeverity = toSeverity(depth, rule.warningDepth, rule.errorDepth);
+    if (depthSeverity !== 'none') {
+      const waiver = findWaiver(relativePath, 'depth', waivers);
+      const row = {
+        file: relativePath,
+        ruleId: rule.id,
+        check: 'depth',
+        severity: depthSeverity,
+        depth,
+        depthBase: depthInfo.depthBase,
+        depthSubject: depthInfo.depthSubject,
+        warningDepth: rule.warningDepth,
+        errorDepth: rule.errorDepth,
+        waiver,
+      };
+      rows.push(row);
+      if (depthSeverity === 'warning') {
+        warnings.push(row);
+      } else if (getWaiverDisposition(waiver) === 'active') {
+        waivedErrors.push(row);
+      } else if (getWaiverDisposition(waiver) === 'expired') {
+        expiredWaivers.push(row);
+      } else {
+        errors.push(row);
+      }
+    }
+
+    const source = fs.readFileSync(absolutePath, 'utf8');
+    if (!isDisallowedForwardingShell(relativePath, source, allowedForwardingShells)) {
+      continue;
+    }
+
+    const waiver = findWaiver(relativePath, 'forwarding_shell', waivers);
+    const row = {
+      file: relativePath,
+      ruleId: rule.id,
+      check: 'forwarding_shell',
+      severity: 'error',
+      basename: path.basename(relativePath),
+      waiver,
+    };
+    rows.push(row);
+    if (getWaiverDisposition(waiver) === 'active') {
+      waivedErrors.push(row);
+    } else if (getWaiverDisposition(waiver) === 'expired') {
+      expiredWaivers.push(row);
+    } else {
+      errors.push(row);
+    }
+  }
+
+  rows.sort(compareRows);
+  warnings.sort(compareRows);
+  errors.sort(compareRows);
+  waivedErrors.sort(compareRows);
+  expiredWaivers.sort(compareRows);
+
+  return {
+    configPath,
+    totalTrackedFiles: files.length,
+    analyzedFiles,
+    rows,
+    warnings,
+    errors,
+    waivedErrors,
+    expiredWaivers,
+  };
+}

package/cli/lib/internal/governance/ai/check-agents-freshness.mjs

@@ -0,0 +1,155 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const DEFAULT_TARGETS = [
+  { rel: "AGENTS.md", maxLines: 100 },
+  { rel: "nimi-backend/AGENTS.md", maxLines: 80 },
+  { rel: "nimi-dashboard/AGENTS.md", maxLines: 65 },
+  { rel: ".nimi/spec/AGENTS.md", maxLines: 70 },
+  { rel: "scripts/AGENTS.md", maxLines: 45 },
+  { rel: "tests/AGENTS.md", maxLines: 35 },
+];
+
+const DEFAULT_REQUIRED_SECTIONS = [
+  "## Scope",
+  "## Hard Boundaries",
+  "## Retrieval Defaults",
+  "## Verification Commands",
+];
+
+const DEFAULT_STALE_TOKENS = ["AISC-", "R-WORLD-", "R-AGENT-", "SOCIAL-013", "ECON-014"];
+
+const GENERIC_PNPM_COMMANDS = new Set([
+  "install",
+  "test",
+  "build",
+  "typecheck",
+  "lint",
+  "dev",
+  "preview",
+  "check",
+  "verify",
+  "exec",
+  "run",
+]);
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function collectKnownPnpmScripts(projectRoot) {
+  const rootPkg = readJson(path.join(projectRoot, "package.json"));
+  const scripts = new Set(Object.keys(rootPkg.scripts || {}));
+
+  for (const rel of ["nimi-backend/package.json", "nimi-dashboard/package.json"]) {
+    const abs = path.join(projectRoot, rel);
+    if (!fs.existsSync(abs)) continue;
+    const pkg = readJson(abs);
+    for (const name of Object.keys(pkg.scripts || {})) {
+      scripts.add(name);
+    }
+  }
+
+  return scripts;
+}
+
+function validatePnpmCommand(command, knownScripts, failures, relPath) {
+  const tokens = command.trim().split(/\s+/u);
+  if (tokens[0] !== "pnpm") return;
+
+  let index = 1;
+  while (tokens[index]?.startsWith("--")) {
+    index += tokens[index]?.includes("=") ? 1 : 2;
+  }
+
+  const subcommand = String(tokens[index] || "").trim();
+  if (!subcommand || GENERIC_PNPM_COMMANDS.has(subcommand) || knownScripts.has(subcommand)) {
+    return;
+  }
+
+  failures.push(`${relPath}: unknown pnpm command: ${command}`);
+}
+
+function validatePathToken(token, failures, relPath, agentsDir, projectRoot) {
+  if (token.includes(" ")) return;
+  if (!token.includes("/")) return;
+  if (
+    token.startsWith("http") ||
+    token.startsWith("@") ||
+    token.includes("*") ||
+    token.includes("{")
+  ) {
+    return;
+  }
+
+  const cleaned = token.replace(/[`,.;:()]+$/gu, "").replace(/^[(]+/u, "");
+  if (!cleaned || cleaned.startsWith("$") || cleaned.endsWith("/")) return;
+  if (cleaned.startsWith("nimi/")) return;
+
+  const absFromAgents = path.join(agentsDir, cleaned);
+  const absFromRoot = path.join(projectRoot, cleaned);
+  if (!fs.existsSync(absFromAgents) && !fs.existsSync(absFromRoot)) {
+    failures.push(`${relPath}: stale path reference: ${cleaned}`);
+  }
+}
+
+export function runAgentsFreshnessCheck(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const config = options.config || {};
+  const targets = Array.isArray(config.targets) && config.targets.length > 0
+    ? config.targets
+    : DEFAULT_TARGETS;
+  const requiredSections = Array.isArray(config.requiredSections) && config.requiredSections.length > 0
+    ? config.requiredSections
+    : DEFAULT_REQUIRED_SECTIONS;
+  const staleTokens = Array.isArray(config.staleTokens) && config.staleTokens.length > 0
+    ? config.staleTokens
+    : DEFAULT_STALE_TOKENS;
+
+  const failures = [];
+  const knownScripts = collectKnownPnpmScripts(projectRoot);
+
+  for (const target of targets) {
+    const abs = path.join(projectRoot, target.rel);
+    if (!fs.existsSync(abs)) {
+      failures.push(`missing AGENTS file: ${target.rel}`);
+      continue;
+    }
+
+    const content = fs.readFileSync(abs, "utf8");
+    const lines = content.split(/\r?\n/u);
+    if (Number(target.maxLines) > 0 && lines.length > Number(target.maxLines)) {
+      failures.push(`${target.rel}: exceeds line budget (${lines.length} > ${target.maxLines})`);
+    }
+
+    for (const section of requiredSections) {
+      if (!content.includes(section)) {
+        failures.push(`${target.rel}: missing required section ${section}`);
+      }
+    }
+
+    for (const token of staleTokens) {
+      if (content.includes(token)) {
+        failures.push(`${target.rel}: contains stale token ${token}`);
+      }
+    }
+
+    const agentsDir = path.dirname(abs);
+    const backtickTokens = content.match(/`[^`\n]+`/gu) || [];
+    for (const raw of backtickTokens) {
+      const inner = raw.slice(1, -1);
+      validatePathToken(inner, failures, target.rel, agentsDir, projectRoot);
+      validatePnpmCommand(inner, knownScripts, failures, target.rel);
+    }
+  }
+
+  if (failures.length > 0) {
+    process.stderr.write(
+      `agents freshness check failed:\n${failures.map((entry) => `- ${entry}`).join("\n")}\n`,
+    );
+    return 1;
+  }
+
+  process.stdout.write(`agents freshness check passed (${targets.length} files)\n`);
+  return 0;
+}

package/cli/lib/internal/governance/ai/check-high-risk-doc-metadata-core.mjs

@@ -0,0 +1,173 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { readYamlWithFragments } from '../shared/read-yaml-with-fragments.mjs';
+
+const DEFAULT_DOC_ROOTS = ['.local'];
+const HIGH_RISK_NAME_PATTERNS = [
+  /design/iu,
+  /audit/iu,
+  /implementation-plan/iu,
+  /architecture/iu,
+  /refactor/iu,
+  /refactory/iu,
+  /remediation-plan/iu,
+  /unification/iu,
+  /migration/iu,
+];
+const REQUIRED_METADATA_KEYS = [
+  'Spec Status',
+  'Authority Owner',
+  'Work Type',
+  'Parallel Truth',
+];
+
+function normalizeRel(filePath, repoRoot) {
+  return path.relative(repoRoot, filePath).replace(/\\/g, '/');
+}
+
+function isMarkdownFile(filePath) {
+  return filePath.endsWith('.md');
+}
+
+function shouldSkip(relPath) {
+  return relPath.includes('/archive/');
+}
+
+function isHighRiskByName(relPath, patterns = HIGH_RISK_NAME_PATTERNS) {
+  const base = path.basename(relPath);
+  return patterns.some((pattern) => pattern.test(base));
+}
+
+function readFileSafe(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function detectMetadata(content, requiredMetadataKeys = REQUIRED_METADATA_KEYS) {
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u);
+  if (frontmatterMatch) {
+    const doc = YAML.parse(frontmatterMatch[1]) || {};
+    const values = new Map([
+      ['Spec Status', String(doc?.spec_status || '').trim()],
+      ['Authority Owner', String(doc?.authority_owner || '').trim()],
+      ['Work Type', String(doc?.work_type || '').trim()],
+      ['Parallel Truth', String(doc?.parallel_truth || '').trim()],
+    ]);
+    for (const key of requiredMetadataKeys) {
+      if (!values.has(key)) {
+        values.set(key, '');
+      }
+    }
+    return values;
+  }
+  const lines = content.split(/\r?\n/u).slice(0, 20);
+  const found = new Map();
+  for (const key of requiredMetadataKeys) {
+    const prefix = `> **${key}**:`;
+    const line = lines.find((item) => item.startsWith(prefix)) || null;
+    found.set(key, line ? line.slice(prefix.length).trim() : '');
+  }
+  return found;
+}
+
+function validateMetadata(meta, requiredMetadataKeys = REQUIRED_METADATA_KEYS) {
+  const failures = [];
+  for (const key of requiredMetadataKeys) {
+    const value = meta.get(key) || '';
+    if (!value) {
+      failures.push(`missing metadata field "${key}"`);
+    }
+  }
+  const workType = meta.get('Work Type') || '';
+  if (workType && workType !== 'alignment' && workType !== 'redesign') {
+    failures.push('Work Type must be "alignment" or "redesign"');
+  }
+  const parallelTruth = meta.get('Parallel Truth') || '';
+  if (parallelTruth && parallelTruth !== 'yes' && parallelTruth !== 'no') {
+    failures.push('Parallel Truth must be "yes" or "no"');
+  }
+  const specStatus = meta.get('Spec Status') || '';
+  const validSpecStatuses = new Set([
+    'aligned',
+    'requires spec change',
+    'requires_change',
+    'preflight-required',
+  ]);
+  if (specStatus && !validSpecStatuses.has(specStatus)) {
+    failures.push('Spec Status must be one of: aligned, requires spec change, requires_change, preflight-required');
+  }
+  return failures;
+}
+
+function walkMarkdownFiles(dirPath) {
+  const results = [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const nextPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkMarkdownFiles(nextPath));
+      continue;
+    }
+    if (entry.isFile() && isMarkdownFile(nextPath)) {
+      results.push(nextPath);
+    }
+  }
+  return results;
+}
+
+export function evaluateHighRiskDocMetadata(options = {}) {
+  const repoRoot = options.repoRoot || process.cwd();
+  const docRoots = Array.isArray(options.docRoots) && options.docRoots.length > 0
+    ? options.docRoots
+    : DEFAULT_DOC_ROOTS;
+  const requiredMetadataKeys = Array.isArray(options.requiredMetadataKeys) && options.requiredMetadataKeys.length > 0
+    ? options.requiredMetadataKeys.map((value) => String(value || '').trim()).filter(Boolean)
+    : REQUIRED_METADATA_KEYS;
+  const namePatterns = Array.isArray(options.namePatterns) && options.namePatterns.length > 0
+    ? options.namePatterns.map((value) => new RegExp(String(value), 'iu'))
+    : HIGH_RISK_NAME_PATTERNS;
+  const exemptionsPath = options.exemptionsPath
+    || path.join(repoRoot, 'scripts/config/high-risk-doc-metadata-exemptions.yaml');
+  const exemptionsDoc = options.exemptPaths
+    ? { exempt_paths: options.exemptPaths }
+    : fs.existsSync(exemptionsPath)
+      ? (readYamlWithFragments(exemptionsPath) || {})
+      : {};
+  const exemptPaths = new Set(
+    (Array.isArray(exemptionsDoc?.exempt_paths) ? exemptionsDoc.exempt_paths : [])
+      .map((value) => String(value || '').trim())
+      .filter(Boolean),
+  );
+
+  const scanned = [];
+  const failures = [];
+
+  for (const rootRel of docRoots) {
+    const absRoot = path.join(repoRoot, rootRel);
+    if (!fs.existsSync(absRoot)) {
+      continue;
+    }
+    for (const filePath of walkMarkdownFiles(absRoot)) {
+      const relPath = normalizeRel(filePath, repoRoot);
+      if (shouldSkip(relPath) || !isHighRiskByName(relPath, namePatterns)) {
+        continue;
+      }
+      scanned.push(relPath);
+      if (exemptPaths.has(relPath)) {
+        continue;
+      }
+      const content = readFileSafe(filePath);
+      const meta = detectMetadata(content, requiredMetadataKeys);
+      const fileFailures = validateMetadata(meta, requiredMetadataKeys);
+      for (const failure of fileFailures) {
+        failures.push(`${relPath}: ${failure}`);
+      }
+    }
+  }
+
+  return {
+    scanned,
+    failures,
+    exemptPaths,
+  };
+}