@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/cli/commands/validate-spec-governance.mjs

@@ -1,144 +0,0 @@
-import path from "node:path";
-
-import { localize } from "../lib/ui.mjs";
-import { buildValidatorCliReport, validateSpecTree } from "../lib/validators.mjs";
-import { loadGovernanceConfig, requireProfile } from "../lib/internal/governance/config.mjs";
-import { runCommand } from "../lib/internal/governance/runner.mjs";
-
-function parseOptions(args) {
-  const options = {
-    profile: null,
-    scope: "all",
-  };
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-
-    if (arg === "--profile") {
-      const value = args[index + 1];
-      if (!value || value.startsWith("--")) {
-        return { ok: false, error: "nimicoding validate-spec-governance refused: --profile requires a value.\n" };
-      }
-      options.profile = value;
-      index += 1;
-      continue;
-    }
-
-    if (arg === "--scope") {
-      const value = args[index + 1];
-      if (!value || value.startsWith("--")) {
-        return { ok: false, error: "nimicoding validate-spec-governance refused: --scope requires a value.\n" };
-      }
-      options.scope = value;
-      index += 1;
-      continue;
-    }
-
-    return {
-      ok: false,
-      error: `nimicoding validate-spec-governance refused: unknown option ${arg}.\n`,
-    };
-  }
-
-  return { ok: true, options };
-}
-
-function resolveScopes(scope, governanceConfig) {
-  const configuredScopes = Object.keys(governanceConfig.specGovernance.validateCommands || {});
-  if (scope === "all") {
-    return {
-      ok: true,
-      scopes: configuredScopes,
-      error: null,
-    };
-  }
-  if (!configuredScopes.includes(scope)) {
-    return {
-      ok: false,
-      scopes: [],
-      error: `nimicoding validate-spec-governance refused: unsupported --scope value ${scope}.\n`,
-    };
-  }
-  return {
-    ok: true,
-    scopes: [scope],
-    error: null,
-  };
-}
-
-export async function runValidateSpecGovernance(args) {
-  const parsed = parseOptions(args);
-  if (!parsed.ok) {
-    process.stderr.write(localize(parsed.error, parsed.error));
-    return 2;
-  }
-
-  const governance = await loadGovernanceConfig(process.cwd());
-  if (!governance.ok) {
-    process.stderr.write(localize(
-      `nimicoding validate-spec-governance refused: ${governance.reason} at ${governance.path}.\n`,
-      `nimicoding validate-spec-governance 已拒绝：${governance.path} 的治理配置不可用。\n`,
-    ));
-    return 2;
-  }
-
-  const profileCheck = requireProfile(governance.config, parsed.options.profile);
-  if (!profileCheck.ok) {
-    process.stderr.write(localize(
-      `nimicoding validate-spec-governance refused: ${profileCheck.error}.\n`,
-      `nimicoding validate-spec-governance 已拒绝：${profileCheck.error}。\n`,
-    ));
-    return 2;
-  }
-
-  const scopeResolution = resolveScopes(parsed.options.scope, governance.config);
-  if (!scopeResolution.ok) {
-    process.stderr.write(localize(scopeResolution.error, scopeResolution.error));
-    return 2;
-  }
-
-  if (parsed.options.scope === "all") {
-    if (governance.config.specGovernance.canonicalRoot !== ".nimi/spec") {
-      process.stderr.write(localize(
-        "nimicoding validate-spec-governance refused: spec_governance.canonical_root must be .nimi/spec.\n",
-        "nimicoding validate-spec-governance 已拒绝：spec_governance.canonical_root 必须为 .nimi/spec。\n",
-      ));
-      return 2;
-    }
-    const canonicalRoot = path.resolve(process.cwd(), ".nimi/spec");
-    const treeReport = await validateSpecTree(canonicalRoot, { projectRoot: process.cwd() });
-    if (!treeReport.ok) {
-      const cliReport = buildValidatorCliReport("validate-spec-tree", canonicalRoot, treeReport);
-      process.stdout.write(`${JSON.stringify(cliReport, null, 2)}\n`);
-      return 1;
-    }
-  }
-
-  let failed = false;
-  for (const scope of scopeResolution.scopes) {
-    const commands = governance.config.specGovernance.validateCommands[scope] || [];
-    if (commands.length === 0) {
-      process.stderr.write(localize(
-        `nimicoding validate-spec-governance refused: scope ${scope} is not configured in .nimi/config/governance.yaml.\n`,
-        `nimicoding validate-spec-governance 已拒绝：.nimi/config/governance.yaml 未配置 ${scope}。\n`,
-      ));
-      return 2;
-    }
-
-    for (const command of commands) {
-      const result = runCommand(command, { cwd: process.cwd() });
-      if (result.stdout) process.stdout.write(result.stdout);
-      if (result.stderr) process.stderr.write(result.stderr);
-      if (!result.ok) {
-        failed = true;
-        break;
-      }
-    }
-
-    if (failed) {
-      break;
-    }
-  }
-
-  return failed ? 1 : 0;
-}

package/cli/commands/validate-spec-tree.mjs

@@ -1,27 +0,0 @@
-import path from "node:path";
-
-import { buildValidatorCliReport, validateSpecTree } from "../lib/validators.mjs";
-import { localize } from "../lib/ui.mjs";
-
-export async function runValidateSpecTree(args) {
-  const normalized = args[0] === "--" ? args.slice(1) : args;
-  let targetRoot = ".nimi/spec";
-
-  if (normalized.length > 1) {
-    process.stderr.write(localize(
-      "nimicoding validate-spec-tree refused: expected zero or one path argument.\n",
-      "nimicoding validate-spec-tree 已拒绝：期望零个或一个路径参数。\n",
-    ));
-    return 2;
-  }
-
-  if (normalized.length === 1) {
-    targetRoot = normalized[0];
-  }
-
-  const absoluteRoot = path.resolve(process.cwd(), targetRoot);
-  const report = await validateSpecTree(absoluteRoot, { projectRoot: process.cwd() });
-  const cliReport = buildValidatorCliReport("validate-spec-tree", absoluteRoot, report);
-  process.stdout.write(`${JSON.stringify(cliReport, null, 2)}\n`);
-  return report.ok ? 0 : 1;
-}

package/cli/commands/validate-table-family.mjs

@@ -1,5 +0,0 @@
-import { runSurfaceValidatorCommand } from "./surface-validator-command.mjs";
-
-export function runValidateTableFamily(args) {
-  return runSurfaceValidatorCommand(args, "validate-table-family");
-}

package/cli/commands/validate-tracked-output-admission.mjs

@@ -1,5 +0,0 @@
-import { runSurfaceValidatorCommand } from "./surface-validator-command.mjs";
-
-export function runValidateTrackedOutputAdmission(args) {
-  return runSurfaceValidatorCommand(args, "validate-tracked-output-admission");
-}

package/cli/lib/blueprint-audit.mjs

@@ -1,363 +0,0 @@
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-import YAML from "yaml";
-
-import { loadBlueprintReference, loadSpecGenerationInputsConfig } from "./contracts.mjs";
-import { pathExists } from "./fs-helpers.mjs";
-import {
-  localize,
-  styleHeading,
-  styleLabel,
-  styleStatus,
-} from "./ui.mjs";
-
-const BLUEPRINT_AUDIT_CONTRACT_VERSION = "nimicoding.blueprint-audit.v2";
-const DEFAULT_REPORT_PATH = ".nimi/local/state/spec-generation/blueprint-equivalence-audit.json";
-
-async function collectFiles(rootPath, relativePrefix = "") {
-  const info = await pathExists(rootPath);
-  if (!info || !info.isDirectory()) {
-    return [];
-  }
-
-  const entries = await readdir(rootPath, { withFileTypes: true });
-  const collected = [];
-  for (const entry of entries) {
-    const absoluteChildPath = path.join(rootPath, entry.name);
-    const relativeChildPath = relativePrefix ? path.posix.join(relativePrefix, entry.name) : entry.name;
-    if (entry.isDirectory()) {
-      collected.push(...await collectFiles(absoluteChildPath, relativeChildPath));
-    } else if (entry.isFile()) {
-      collected.push(relativeChildPath.split(path.sep).join(path.posix.sep));
-    }
-  }
-
-  return collected.sort();
-}
-
-async function collectDomainInventory(rootPath) {
-  const info = await pathExists(rootPath);
-  if (!info || !info.isDirectory()) {
-    return {
-      domains: [],
-      hasIndex: false,
-      files: [],
-    };
-  }
-
-  const entries = await readdir(rootPath, { withFileTypes: true });
-  const domains = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-
-    const kernelPath = path.join(rootPath, entry.name, "kernel");
-    const kernelInfo = await pathExists(kernelPath);
-    if (kernelInfo?.isDirectory()) {
-      domains.push(entry.name);
-    }
-  }
-
-  const indexInfo = await pathExists(path.join(rootPath, "INDEX.md"));
-  const files = await collectFiles(rootPath);
-
-  return {
-    domains: domains.sort(),
-    hasIndex: Boolean(indexInfo?.isFile()),
-    files,
-  };
-}
-
-function categorizeBlueprintFiles(files) {
-  const kernelMarkdown = [];
-  const kernelTables = [];
-  const kernelGenerated = [];
-  const domainGuides = [];
-
-  for (const relativePath of files) {
-    if (/^([^/]+)\/kernel\/[^/]+\.md$/.test(relativePath)) {
-      kernelMarkdown.push(relativePath);
-      continue;
-    }
-
-    if (/^([^/]+)\/kernel\/tables\/.+\.(ya?ml)$/.test(relativePath)) {
-      kernelTables.push(relativePath);
-      continue;
-    }
-
-    if (/^([^/]+)\/kernel\/generated\/.+\.md$/.test(relativePath)) {
-      kernelGenerated.push(relativePath);
-      continue;
-    }
-
-    if (/^[^/]+\/[^/]+\.md$/.test(relativePath)) {
-      domainGuides.push(relativePath);
-    }
-  }
-
-  return {
-    kernelMarkdown,
-    kernelTables,
-    kernelGenerated,
-    domainGuides,
-  };
-}
-
-function compareFileSets(blueprintFiles, canonicalFiles) {
-  const canonicalSet = new Set(canonicalFiles);
-  const blueprintSet = new Set(blueprintFiles);
-
-  return {
-    present: blueprintFiles.filter((filePath) => canonicalSet.has(filePath)),
-    missing: blueprintFiles.filter((filePath) => !canonicalSet.has(filePath)),
-    extra: canonicalFiles.filter((filePath) => !blueprintSet.has(filePath)),
-  };
-}
-
-function buildSummarySection(compareResult) {
-  return {
-    present: compareResult.present.length,
-    missing: compareResult.missing.length,
-    extra: compareResult.extra.length,
-  };
-}
-
-function collectIds(value, ids = []) {
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      collectIds(entry, ids);
-    }
-    return ids;
-  }
-
-  if (value && typeof value === "object") {
-    if (typeof value.id === "string") {
-      ids.push(value.id);
-    }
-    for (const nestedValue of Object.values(value)) {
-      collectIds(nestedValue, ids);
-    }
-  }
-
-  return ids;
-}
-
-async function compareRuleIds(blueprintAbsoluteRoot, canonicalAbsoluteRoot, presentTablePaths) {
-  const files = [];
-  const aggregateMissing = new Set();
-  const aggregateExtra = new Set();
-  const parseErrors = [];
-
-  for (const relativePath of presentTablePaths) {
-    try {
-      const blueprintText = await readFile(path.join(blueprintAbsoluteRoot, relativePath), "utf8");
-      const canonicalText = await readFile(path.join(canonicalAbsoluteRoot, relativePath), "utf8");
-      const blueprintIds = Array.from(new Set(collectIds(YAML.parse(blueprintText)))).sort();
-      const canonicalIds = Array.from(new Set(collectIds(YAML.parse(canonicalText)))).sort();
-      const missingIds = blueprintIds.filter((entry) => !canonicalIds.includes(entry));
-      const extraIds = canonicalIds.filter((entry) => !blueprintIds.includes(entry));
-
-      missingIds.forEach((entry) => aggregateMissing.add(entry));
-      extraIds.forEach((entry) => aggregateExtra.add(entry));
-
-      files.push({
-        path: relativePath,
-        blueprintIds: blueprintIds.length,
-        canonicalIds: canonicalIds.length,
-        missingIds,
-        extraIds,
-      });
-    } catch (error) {
-      parseErrors.push({
-        path: relativePath,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-
-  return {
-    comparedFiles: files.length,
-    files,
-    parseErrors,
-    missingRuleIds: Array.from(aggregateMissing).sort(),
-    extraRuleIds: Array.from(aggregateExtra).sort(),
-  };
-}
-
-export async function buildBlueprintAuditPayload(projectRoot, options = {}) {
-  const blueprintReference = await loadBlueprintReference(projectRoot);
-  const specGenerationInputs = await loadSpecGenerationInputsConfig(projectRoot);
-
-  const canonicalRoot = options.canonicalRoot
-    ?? specGenerationInputs.canonicalTargetRoot
-    ?? ".nimi/spec";
-  const blueprintRoot = options.blueprintRoot
-    ?? blueprintReference.root
-    ?? specGenerationInputs.benchmarkBlueprintRoot
-    ?? null;
-
-  if (!blueprintRoot) {
-    return {
-      ok: false,
-      exitCode: 2,
-      inputError: true,
-      error: `${localize(
-        "nimicoding blueprint-audit refused: no blueprint root is declared; pass --blueprint-root or add project-local blueprint reference metadata.",
-        "nimicoding blueprint-audit 已拒绝：没有声明 blueprint root；请传入 --blueprint-root，或补充项目本地 blueprint reference 元数据。",
-      )}\n`,
-    };
-  }
-
-  const blueprintAbsoluteRoot = path.resolve(projectRoot, blueprintRoot);
-  const canonicalAbsoluteRoot = path.resolve(projectRoot, canonicalRoot);
-  const blueprintInventory = await collectDomainInventory(blueprintAbsoluteRoot);
-  const canonicalInventory = await collectDomainInventory(canonicalAbsoluteRoot);
-
-  const missingDomains = blueprintInventory.domains.filter((domainId) => !canonicalInventory.domains.includes(domainId));
-  const extraDomains = canonicalInventory.domains.filter((domainId) => !blueprintInventory.domains.includes(domainId));
-  const blueprintFiles = categorizeBlueprintFiles(blueprintInventory.files);
-  const canonicalFiles = categorizeBlueprintFiles(canonicalInventory.files);
-
-  const kernelMarkdown = compareFileSets(blueprintFiles.kernelMarkdown, canonicalFiles.kernelMarkdown);
-  const kernelTables = compareFileSets(blueprintFiles.kernelTables, canonicalFiles.kernelTables);
-  const kernelGenerated = {
-    present: [],
-    missing: [],
-    extra: [],
-  };
-  const domainGuides = compareFileSets(blueprintFiles.domainGuides, canonicalFiles.domainGuides);
-  const ruleIdPreservation = await compareRuleIds(
-    blueprintAbsoluteRoot,
-    canonicalAbsoluteRoot,
-    kernelTables.present,
-  );
-
-  const indexPresent = blueprintInventory.hasIndex ? canonicalInventory.hasIndex : true;
-  const ok = missingDomains.length === 0
-    && kernelMarkdown.missing.length === 0
-    && kernelTables.missing.length === 0
-    && domainGuides.missing.length === 0
-    && ruleIdPreservation.missingRuleIds.length === 0
-    && ruleIdPreservation.parseErrors.length === 0
-    && indexPresent;
-
-  const reportPath = path.join(projectRoot, DEFAULT_REPORT_PATH);
-  const nextSteps = [];
-  if (missingDomains.length > 0 || kernelMarkdown.missing.length > 0 || kernelTables.missing.length > 0 || !indexPresent) {
-    nextSteps.push("Resolve the missing blueprint structure under `/.nimi/spec/**` before claiming equivalence.");
-  }
-  if (domainGuides.missing.length > 0) {
-    nextSteps.push("Thin and map domain guides only after kernel coverage is in place.");
-  }
-  if (ruleIdPreservation.missingRuleIds.length > 0 || ruleIdPreservation.parseErrors.length > 0) {
-    nextSteps.push("Preserve benchmark rule IDs in canonical kernel tables before treating the canonical tree as benchmark-equivalent.");
-  }
-
-  return {
-    contractVersion: BLUEPRINT_AUDIT_CONTRACT_VERSION,
-    ok,
-    exitCode: ok ? 0 : 1,
-    projectRoot,
-    blueprintRoot,
-    canonicalRoot,
-    blueprintReference,
-    specGenerationInputs: {
-      ok: specGenerationInputs.ok,
-      mode: specGenerationInputs.mode,
-      acceptanceMode: specGenerationInputs.acceptanceMode,
-      benchmarkBlueprintRoot: specGenerationInputs.benchmarkBlueprintRoot,
-    },
-    inventory: {
-      blueprintDomains: blueprintInventory.domains,
-      canonicalDomains: canonicalInventory.domains,
-      missingDomains,
-      extraDomains,
-      indexPresent,
-    },
-    comparison: {
-      kernelMarkdown: {
-        ...buildSummarySection(kernelMarkdown),
-        missingPaths: kernelMarkdown.missing,
-      },
-      kernelTables: {
-        ...buildSummarySection(kernelTables),
-        missingPaths: kernelTables.missing,
-      },
-      kernelGenerated: {
-        ...buildSummarySection(kernelGenerated),
-        missingPaths: kernelGenerated.missing,
-      },
-      domainGuides: {
-        ...buildSummarySection(domainGuides),
-        missingPaths: domainGuides.missing,
-      },
-    },
-    structuralGaps: {
-      missingDomains,
-      missingKernelMarkdown: kernelMarkdown.missing,
-      missingKernelTables: kernelTables.missing,
-      indexMissing: !indexPresent,
-    },
-    semanticMappingGaps: {
-      ruleIdPreservation,
-    },
-    derivedViewGaps: {
-      missingKernelGenerated: kernelGenerated.missing,
-      missingDomainGuides: domainGuides.missing,
-    },
-    artifactPath: reportPath,
-    nextSteps,
-  };
-}
-
-export function formatBlueprintAuditPayload(payload) {
-  const lines = [
-    styleHeading(`nimicoding blueprint-audit: ${payload.projectRoot}`),
-    "",
-    styleLabel(localize("Summary:", "摘要：")),
-    `  - ${localize("status", "状态")}: ${styleStatus(payload.ok ? "ok" : "needs_attention")}`,
-    `  - ${localize("blueprint root", "blueprint root")}: ${payload.blueprintRoot}`,
-    `  - ${localize("canonical root", "canonical root")}: ${payload.canonicalRoot}`,
-    `  - ${localize("missing domains", "缺失域")}: ${payload.inventory.missingDomains.length}`,
-    `  - ${localize("kernel markdown missing", "缺失 kernel markdown")}: ${payload.comparison.kernelMarkdown.missing}`,
-    `  - ${localize("kernel tables missing", "缺失 kernel tables")}: ${payload.comparison.kernelTables.missing}`,
-    `  - ${localize("generated views missing", "缺失 generated 视图")}: ${payload.comparison.kernelGenerated.missing}`,
-    `  - ${localize("guide mappings missing", "缺失 guide 映射")}: ${payload.comparison.domainGuides.missing}`,
-    `  - ${localize("rule ids missing", "缺失 rule id")}: ${payload.semanticMappingGaps.ruleIdPreservation.missingRuleIds.length}`,
-    "",
-    styleLabel(localize("Coverage:", "覆盖情况：")),
-    `  - ${localize("blueprint domains", "blueprint 域")}: ${payload.inventory.blueprintDomains.length}`,
-    `  - ${localize("canonical domains", "canonical 域")}: ${payload.inventory.canonicalDomains.length}`,
-    `  - ${localize("INDEX present", "INDEX 已存在")}: ${payload.inventory.indexPresent ? "true" : "false"}`,
-  ];
-
-  if (payload.inventory.missingDomains.length > 0) {
-    lines.push(`  - ${localize("missing domain ids", "缺失域 ID")}: ${payload.inventory.missingDomains.join(", ")}`);
-  }
-
-  if (payload.semanticMappingGaps.ruleIdPreservation.missingRuleIds.length > 0) {
-    lines.push(`  - ${localize("missing rule ids", "缺失 rule id")}: ${payload.semanticMappingGaps.ruleIdPreservation.missingRuleIds.join(", ")}`);
-  }
-
-  if (payload.semanticMappingGaps.ruleIdPreservation.parseErrors.length > 0) {
-    lines.push(`  - ${localize("rule-id parse errors", "rule-id 解析错误")}: ${payload.semanticMappingGaps.ruleIdPreservation.parseErrors.length}`);
-  }
-
-  if (payload.nextSteps.length > 0) {
-    lines.push("", styleLabel(localize("Next:", "下一步：")));
-    for (const step of payload.nextSteps) {
-      lines.push(`  - ${localize(step, step)}`);
-    }
-  }
-
-  return `${lines.join("\n")}\n`;
-}
-
-export async function writeBlueprintAuditArtifact(projectRoot, payload) {
-  await mkdir(path.dirname(payload.artifactPath), { recursive: true });
-  await writeFile(payload.artifactPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-  return {
-    jsonRef: path.relative(projectRoot, payload.artifactPath).split(path.sep).join(path.posix.sep),
-  };
-}

package/cli/lib/contracts.mjs

@@ -1,21 +0,0 @@
-import {
-  loadBlueprintReference as loadBlueprintReferenceInternal,
-  loadSpecGenerationAuditContract as loadSpecGenerationAuditContractInternal,
-  loadSpecGenerationInputsConfig as loadSpecGenerationInputsConfigInternal,
-  loadSpecGenerationInputsContract as loadSpecGenerationInputsContractInternal,
-} from "./internal/contracts-loaders.mjs";
-
-export function loadSpecGenerationInputsContract(projectRoot) {
-  return loadSpecGenerationInputsContractInternal(projectRoot);
-}
-export function loadSpecGenerationAuditContract(projectRoot) {
-  return loadSpecGenerationAuditContractInternal(projectRoot);
-}
-
-export function loadSpecGenerationInputsConfig(projectRoot) {
-  return loadSpecGenerationInputsConfigInternal(projectRoot);
-}
-
-export function loadBlueprintReference(projectRoot) {
-  return loadBlueprintReferenceInternal(projectRoot);
-}

package/cli/lib/internal/contracts-loaders.mjs

@@ -1,47 +0,0 @@
-import path from "node:path";
-
-import {
-  BLUEPRINT_REFERENCE_REF,
-  SPEC_GENERATION_AUDIT_CONTRACT_REF,
-  SPEC_GENERATION_INPUTS_CONTRACT_REF,
-  SPEC_GENERATION_INPUTS_REF,
-} from "../../constants.mjs";
-import { readTextIfFile } from "../fs-helpers.mjs";
-import {
-  parseBlueprintReference,
-  parseSpecGenerationAuditContract,
-  parseSpecGenerationInputsConfig,
-  parseSpecGenerationInputsContract,
-} from "./contracts-parse.mjs";
-
-async function loadParsedYaml(projectRoot, relativePath, parse) {
-  const text = await readTextIfFile(path.join(projectRoot, relativePath));
-  return {
-    path: relativePath,
-    text,
-    ...parse(text),
-  };
-}
-export function loadSpecGenerationInputsContract(projectRoot) {
-  return loadParsedYaml(
-    projectRoot,
-    SPEC_GENERATION_INPUTS_CONTRACT_REF,
-    parseSpecGenerationInputsContract,
-  );
-}
-
-export function loadSpecGenerationAuditContract(projectRoot) {
-  return loadParsedYaml(
-    projectRoot,
-    SPEC_GENERATION_AUDIT_CONTRACT_REF,
-    parseSpecGenerationAuditContract,
-  );
-}
-
-export function loadSpecGenerationInputsConfig(projectRoot) {
-  return loadParsedYaml(projectRoot, SPEC_GENERATION_INPUTS_REF, parseSpecGenerationInputsConfig);
-}
-
-export function loadBlueprintReference(projectRoot) {
-  return loadParsedYaml(projectRoot, BLUEPRINT_REFERENCE_REF, parseBlueprintReference);
-}