@nimiplatform/nimi-coding 0.4.0 → 0.6.0

package/cli/commands/code.mjs

@@ -0,0 +1,225 @@
+import { Buffer } from "node:buffer";
+import { queryCodeAuthority, CodeAuthorityFailure } from "../lib/code/authority-annotations.mjs";
+import {
+  completedCodeAuthorityResponse,
+  MIN_CODE_AUTHORITY_BYTES,
+  refusedCodeAuthorityResponse,
+  renderCodeAuthorityResponse,
+  serializeCodeAuthorityResponse,
+} from "../lib/code/authority-annotation-response.mjs";
+import { contextForTypeScript, CodeContextFailure } from "../lib/code/context.mjs";
+import {
+  MIN_CODE_CONTEXT_BYTES,
+  refusedCodeResponse,
+  renderContextResponse,
+  serializeCodeResponse,
+} from "../lib/code/response.mjs";
+
+export const CODE_CONTEXT_USAGE = "nimicoding code context <repo-relative-.ts-or-.tsx-path> --repo <exact-git-worktree-root> --symbol <top-level-identifier> --tsconfig <repo-relative-tsconfig> --max-bytes <integer>=512";
+export const CODE_AUTHORITY_USAGE = "nimicoding code authority --repo <exact-git-worktree-root> (--authority <exact-id>|--source <repo-relative-.ts-.tsx-or-.go-path>|--audit) --max-files <integer> --max-bytes <integer>=512";
+export const CODE_COMMAND_USAGE = [CODE_CONTEXT_USAGE, CODE_AUTHORITY_USAGE];
+
+const GLOBAL_FLAG_OPTIONS = new Set(["--color", "--no-color"]);
+const CODE_OPTIONS = new Set(["--repo", "--symbol", "--tsconfig", "--max-bytes"]);
+const CODE_AUTHORITY_VALUE_OPTIONS = new Set(["--repo", "--authority", "--source", "--max-files", "--max-bytes"]);
+const SUPPORTED_LANGUAGES = new Set(["en", "zh"]);
+
+function writeResponse(response) {
+  process.stdout.write(serializeCodeResponse(response));
+}
+
+function writeRefusal(code, message, exitCode) {
+  writeResponse(refusedCodeResponse(code, message));
+  return exitCode;
+}
+
+function writeAuthorityResponse(response) {
+  process.stdout.write(serializeCodeAuthorityResponse(response));
+}
+
+function writeAuthorityRefusal(code, message, exitCode) {
+  writeAuthorityResponse(refusedCodeAuthorityResponse(code, message));
+  return exitCode;
+}
+
+export function classifyCodeInvocation(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (GLOBAL_FLAG_OPTIONS.has(argument) || argument.startsWith("--lang=")) continue;
+    if (argument === "--lang") {
+      const value = args[index + 1];
+      if (value !== undefined && !value.startsWith("--")) index += 1;
+      continue;
+    }
+    return argument === "code" ? index : null;
+  }
+  return null;
+}
+
+function parseLeadingGlobals(args, commandIndex) {
+  for (let index = 0; index < commandIndex; index += 1) {
+    const argument = args[index];
+    if (GLOBAL_FLAG_OPTIONS.has(argument)) continue;
+    if (argument.startsWith("--lang=")) {
+      if (!SUPPORTED_LANGUAGES.has(argument.slice("--lang=".length))) return false;
+      continue;
+    }
+    if (argument === "--lang") {
+      const value = args[index + 1];
+      if (!SUPPORTED_LANGUAGES.has(value)) return false;
+      index += 1;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+function parseContextArguments(args) {
+  if (args[0] !== "context") return null;
+  const positional = [];
+  const options = new Map();
+  for (let index = 1; index < args.length; index += 1) {
+    const argument = args[index];
+    if (GLOBAL_FLAG_OPTIONS.has(argument)) continue;
+    if (argument.startsWith("--lang=")) {
+      if (!SUPPORTED_LANGUAGES.has(argument.slice("--lang=".length))) return null;
+      continue;
+    }
+    if (argument === "--lang") {
+      const value = args[index + 1];
+      if (!SUPPORTED_LANGUAGES.has(value)) return null;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--")) {
+      if (!CODE_OPTIONS.has(argument) || options.has(argument)) return null;
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) return null;
+      options.set(argument, value);
+      index += 1;
+      continue;
+    }
+    positional.push(argument);
+  }
+  if (positional.length !== 1 || options.size !== CODE_OPTIONS.size) return null;
+  const maxBytesText = options.get("--max-bytes");
+  if (!/^(?:0|[1-9][0-9]*)$/u.test(maxBytesText)) return null;
+  const maxBytes = Number(maxBytesText);
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < MIN_CODE_CONTEXT_BYTES) return null;
+  const symbol = options.get("--symbol");
+  if (!/^[$_\p{ID_Start}][$_\u200C\u200D\p{ID_Continue}]*$/u.test(symbol)) return null;
+  return {
+    source: positional[0],
+    repository: options.get("--repo"),
+    symbol,
+    tsconfig: options.get("--tsconfig"),
+    maxBytes,
+  };
+}
+
+function parseAuthorityArguments(args) {
+  if (args[0] !== "authority") return null;
+  const options = new Map();
+  let audit = false;
+  for (let index = 1; index < args.length; index += 1) {
+    const argument = args[index];
+    if (GLOBAL_FLAG_OPTIONS.has(argument)) continue;
+    if (argument.startsWith("--lang=")) {
+      if (!SUPPORTED_LANGUAGES.has(argument.slice("--lang=".length))) return null;
+      continue;
+    }
+    if (argument === "--lang") {
+      const value = args[index + 1];
+      if (!SUPPORTED_LANGUAGES.has(value)) return null;
+      index += 1;
+      continue;
+    }
+    if (argument === "--audit") {
+      if (audit) return null;
+      audit = true;
+      continue;
+    }
+    if (!CODE_AUTHORITY_VALUE_OPTIONS.has(argument) || options.has(argument)) return null;
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) return null;
+    options.set(argument, value);
+    index += 1;
+  }
+  if (!options.has("--repo") || !options.has("--max-files") || !options.has("--max-bytes")) return null;
+  const selectors = Number(options.has("--authority")) + Number(options.has("--source")) + Number(audit);
+  if (selectors !== 1) return null;
+  const maxFilesText = options.get("--max-files");
+  const maxBytesText = options.get("--max-bytes");
+  if (!/^[1-9][0-9]*$/u.test(maxFilesText) || !/^(?:0|[1-9][0-9]*)$/u.test(maxBytesText)) return null;
+  const maxFiles = Number(maxFilesText);
+  const maxBytes = Number(maxBytesText);
+  if (!Number.isSafeInteger(maxFiles) || !Number.isSafeInteger(maxBytes) || maxBytes < MIN_CODE_AUTHORITY_BYTES) return null;
+  const selector = options.has("--authority")
+    ? { kind: "authority", id: options.get("--authority") }
+    : options.has("--source")
+      ? { kind: "source", path: options.get("--source") }
+      : { kind: "audit" };
+  return { repository: options.get("--repo"), selector, maxFiles, maxBytes };
+}
+
+async function runAuthorityInvocation(args) {
+  const parsed = parseAuthorityArguments(args);
+  if (parsed === null) return writeAuthorityRefusal("CODE_USAGE", "invalid code authority command arguments", 2);
+  try {
+    const result = await queryCodeAuthority(parsed);
+    const response = completedCodeAuthorityResponse(result);
+    const rendered = renderCodeAuthorityResponse(response, parsed.maxBytes);
+    if (rendered === null) {
+      const refusal = serializeCodeAuthorityResponse(refusedCodeAuthorityResponse(
+        "CODE_AUTHORITY_OUTPUT_BUDGET",
+        "max-bytes cannot contain the complete code authority response",
+      ));
+      if (Buffer.byteLength(refusal, "utf8") > parsed.maxBytes) {
+        throw new Error("minimum code authority response budget cannot contain its refusal envelope");
+      }
+      process.stdout.write(refusal);
+      return 1;
+    }
+    process.stdout.write(rendered);
+    return response.status === "findings" ? 1 : 0;
+  } catch (error) {
+    if (error instanceof CodeAuthorityFailure) {
+      return writeAuthorityRefusal(error.code, error.message, error.exitCode);
+    }
+    return writeAuthorityRefusal("CODE_AUTHORITY_INTERNAL", "code authority query failed unexpectedly", 2);
+  }
+}
+
+export async function runCodeInvocation(args, commandIndex) {
+  const operation = args[commandIndex + 1];
+  if (!parseLeadingGlobals(args, commandIndex)) {
+    return operation === "authority"
+      ? writeAuthorityRefusal("CODE_USAGE", "invalid code authority command arguments", 2)
+      : writeRefusal("CODE_USAGE", "invalid code command arguments", 2);
+  }
+  if (operation === "authority") return runAuthorityInvocation(args.slice(commandIndex + 1));
+  const parsed = parseContextArguments(args.slice(commandIndex + 1));
+  if (parsed === null) return writeRefusal("CODE_USAGE", "invalid code command arguments", 2);
+  try {
+    const { maxBytes, ...request } = parsed;
+    const { scope, projection } = await contextForTypeScript(request);
+    const rendered = renderContextResponse({ scope, projection, maxBytes });
+    if (rendered === null) {
+      const response = serializeCodeResponse(refusedCodeResponse(
+        "CODE_OUTPUT_BUDGET",
+        "max-bytes cannot contain the mandatory code context response",
+      ));
+      if (Buffer.byteLength(response, "utf8") > maxBytes) {
+        throw new Error("minimum code response budget cannot contain its refusal envelope");
+      }
+      process.stdout.write(response);
+      return 1;
+    }
+    process.stdout.write(rendered.text);
+    return 0;
+  } catch (error) {
+    if (error instanceof CodeContextFailure) return writeRefusal(error.code, error.message, 2);
+    return writeRefusal("CODE_INTERNAL", "code context failed unexpectedly", 2);
+  }
+}

package/cli/commands/start.mjs

@@ -1,5 +1,6 @@
 import path from "node:path";
 
+import { PROJECT_LOCAL_CLI_INVOCATION } from "../constants.mjs";
 import {
   integrateEntrypoints,
   pathExists,
@@ -65,8 +66,8 @@ export async function runStart(args) {
     entrypoints,
     next: [
       "Author project-owned canonical authority under .nimi/spec using only *.authority.yaml or *.authority.md.",
-      "Run nimicoding authority fmt on each changed authority file.",
-      "Run nimicoding authority check .nimi/spec on the complete canonical root.",
+      `Run ${PROJECT_LOCAL_CLI_INVOCATION} authority fmt on each changed authority file.`,
+      `Run ${PROJECT_LOCAL_CLI_INVOCATION} authority check .nimi/spec on the complete canonical root.`,
     ],
   };
 

package/cli/constants.mjs

@@ -1,5 +1,6 @@
-export const VERSION = "0.4.0";
+export const VERSION = "0.6.0";
 export const PACKAGE_NAME = "@nimiplatform/nimi-coding";
+export const PROJECT_LOCAL_CLI_INVOCATION = "pnpm exec nimicoding";
 export const LOCAL_GITIGNORE_ENTRIES = [".nimi/local/"];
 export const AUTHORITY_GITATTRIBUTES_ENTRIES = [
   "*.authority.yaml text eol=lf",

package/cli/dev/check-authority-surface.mjs

@@ -12,12 +12,18 @@ import { fileURLToPath } from "node:url";
 
 import YAML from "yaml";
 
+import { AUTHORITY_COMMAND_USAGE } from "../commands/authority.mjs";
 import { PNPM_BUILTIN_SUBCOMMANDS } from "../lib/authority/anchors.mjs";
-import { AUTHORING_SURFACE, AUTHORITY_SURFACE, REPOSITORY_BOUND_COMMANDS } from "../lib/authority/surface.mjs";
+import {
+  AUTHORING_SURFACE,
+  AUTHORITY_SURFACE,
+  ENFORCED_AUTHORITY_COMMANDS,
+} from "../lib/authority/surface.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 const CONTRACT_FILES = {
+  audit: "spec/authority-audit.yaml",
   anchors: "spec/authority-anchors.yaml",
   consumers: "spec/authority-consumers.yaml",
   terms: "spec/authority-terms.yaml",
@@ -42,7 +48,7 @@ export function checkAuthoritySurface(root = packageRoot) {
   const failures = [];
   const contractIds = new Map();
 
-  for (const command of REPOSITORY_BOUND_COMMANDS) {
+  for (const command of ENFORCED_AUTHORITY_COMMANDS) {
     const relative = CONTRACT_FILES[command];
     if (relative === undefined) {
       failures.push(`command ${command} is in the enforced surface but has no product contract file`);
@@ -109,6 +115,13 @@ export function checkAuthoritySurface(root = packageRoot) {
         `${command} command line flags ${JSON.stringify(commandFlags)} != declared surface ${JSON.stringify(surfaceFlags)}`,
       );
     }
+    const usagePrefix = `nimicoding authority ${command} `;
+    const helpUsages = AUTHORITY_COMMAND_USAGE.filter((usage) => usage.startsWith(usagePrefix));
+    if (helpUsages.length !== 1 || helpUsages[0] !== contract.command) {
+      failures.push(
+        `${command} help usage ${JSON.stringify(helpUsages)} != contract command ${JSON.stringify(contract.command)}`,
+      );
+    }
   }
 
   // fmt and the source schema: the authoring contract has to describe the
@@ -135,10 +148,6 @@ export function checkAuthoritySurface(root = packageRoot) {
     if (authoring.fields?.format !== source.format) {
       failures.push(`authoring format ${authoring.fields?.format} != source schema format ${source.format}`);
     }
-    const authoringMigration = authoring.fields?.migration_inputs?.format;
-    if (authoringMigration !== source.migration_inputs?.format) {
-      failures.push(`migration input format: authoring ${authoringMigration} != source schema ${source.migration_inputs?.format}`);
-    }
     if (!sameSet(authoring.profiles?.yaml?.container_fields ?? [], source.yaml_document?.allowed_fields ?? [])) {
       failures.push(
         `container fields: authoring ${JSON.stringify(sorted(authoring.profiles?.yaml?.container_fields ?? []))} `
@@ -152,7 +161,7 @@ export function checkAuthoritySurface(root = packageRoot) {
 
   // The other direction: a contract that no enforced command claims.
   for (const [command, relative] of Object.entries(CONTRACT_FILES)) {
-    if (!REPOSITORY_BOUND_COMMANDS.includes(command)) {
+    if (!ENFORCED_AUTHORITY_COMMANDS.includes(command)) {
       failures.push(`${relative} declares command ${command}, which the enforced surface does not admit`);
     }
   }
@@ -168,6 +177,6 @@ if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith
   for (const failure of failures) process.stderr.write(`authority-surface: ${failure}\n`);
   if (failures.length > 0) process.exit(1);
   process.stdout.write(
-    `authority-surface: ${REPOSITORY_BOUND_COMMANDS.length} repository-bound commands match their product contracts\n`,
+    `authority-surface: ${ENFORCED_AUTHORITY_COMMANDS.length} public command surfaces match their product contracts\n`,
   );
 }

package/cli/dev/check-product-conformance.mjs

@@ -335,18 +335,6 @@ function createClassification(contracts) {
   return leaves;
 }
 
-function addAuthoringClassification(leaves, authoring) {
-  const values = authoring?.commands?.check?.require_format?.admitted_values;
-  if (!Array.isArray(values) || values.length === 0) throw new Error("authoring contract declares no admitted check formats");
-  values.forEach((value, index) => leaves.set(`authoring:commands.check.require_format.admitted_values[${index}]`, {
-    contract: "authoring",
-    path: `commands.check.require_format.admitted_values[${index}]`,
-    value,
-    status: "unmapped",
-    details: [],
-  }));
-}
-
 function classify(leaves, contract, leafPath, matches, detail) {
   const leaf = leaves.get(`${contract}:${leafPath}`);
   if (!leaf) throw new Error(`behavioural check names no classified leaf: ${contract}:${leafPath}`);
@@ -431,7 +419,7 @@ async function exerciseParserSurface(cliPath, fixture, contracts, leaves) {
   return validReports;
 }
 
-async function exerciseRequiredCombinations(cliPath, fixture, contracts, authoring, leaves) {
+async function exerciseRequiredCombinations(cliPath, fixture, contracts, leaves) {
   const codeWithoutTerm = await runCli(cliPath, fixture.root, [
     ...requiredArgs("terms", fixture).filter((entry) => entry !== "--json"),
     "--code", "--json",
@@ -442,20 +430,6 @@ async function exerciseRequiredCombinations(cliPath, fixture, contracts, authori
     classify(leaves, "terms", leafPath, refusedCode, `required --code/--term combination exited ${codeWithoutTerm.code}`);
   }
 
-  const admitted = authoring.commands.check.require_format.admitted_values;
-  const invalidFormat = await runCli(cliPath, fixture.root, [
-    "authority", "check", fixture.spec, "--require-format", "nimicoding.authority/invalid", "--json",
-  ]);
-  const formatRefusal = invalidFormat.code === 2
-    && invalidFormat.stdout === ""
-    && admitted.every((format) => invalidFormat.stderr.includes(format));
-  admitted.forEach((_, index) => classify(
-    leaves,
-    "authoring",
-    `commands.check.require_format.admitted_values[${index}]`,
-    formatRefusal,
-    `invalid --require-format exited ${invalidFormat.code} and named admitted formats`,
-  ));
 }
 
 async function independentFixtureOracle(fixture) {
@@ -479,7 +453,7 @@ async function independentFixtureOracle(fixture) {
     units: 3,
     files: 6,
     refs: 2,
-    terms: 2,
+    terms: 5,
     sets: 2,
     consumersInputBytes: nonCorpusBytes,
     termsInputBytes: authorityBytes + nonCorpusBytes,
@@ -682,7 +656,7 @@ async function exerciseCoreClosure(cliPath, fixture, contracts, leaves, validRep
     consumers: validReports.consumers.report?.summary?.filesScanned === 6
       && validReports.consumers.report?.summary?.references === 2,
     terms: validReports.terms.report?.summary?.units === 3
-      && validReports.terms.report?.summary?.distinctTerms === 2,
+      && validReports.terms.report?.summary?.distinctTerms === 5,
     "closed-sets": validReports["closed-sets"].report?.summary?.sets?.total === 2,
   };
   for (const command of Object.keys(contracts)) {
@@ -841,13 +815,11 @@ async function runConformanceLane({ contractDirectory, cliPath, lane }) {
   for (const [command, file] of Object.entries(PRODUCT_CONTRACTS)) {
     contracts[command] = YAML.parse(await readFile(path.join(contractDirectory, file), "utf8"));
   }
-  const authoring = YAML.parse(await readFile(path.join(contractDirectory, "authority-authoring.yaml"), "utf8"));
   const leaves = createClassification(contracts);
-  addAuthoringClassification(leaves, authoring);
   const fixture = await createRepositoryFixture();
   try {
     const validReports = await exerciseParserSurface(cliPath, fixture, contracts, leaves);
-    await exerciseRequiredCombinations(cliPath, fixture, contracts, authoring, leaves);
+    await exerciseRequiredCombinations(cliPath, fixture, contracts, leaves);
     await exerciseCompleteAndBudgets(cliPath, fixture, contracts, leaves, validReports);
     await exerciseGrammar(cliPath, fixture, leaves, validReports);
     await addAnchorFinding(fixture);

package/cli/dev/run-cli-smoke.mjs

@@ -1,9 +1,11 @@
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 const cliPath = path.join(repoRoot, "bin", "nimicoding.mjs");
+const packageVersion = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
 
 for (const args of [["--help"], ["--version"]]) {
   const result = spawnSync(process.execPath, [cliPath, ...args], {
@@ -21,4 +23,8 @@ for (const args of [["--help"], ["--version"]]) {
     process.stderr.write(`${args.join(" ")} smoke exited with ${result.status ?? "unknown"}\n`);
     process.exit(result.status ?? 1);
   }
+  if (args[0] === "--version" && result.stdout !== `${packageVersion}\n`) {
+    process.stderr.write(`--version returned ${JSON.stringify(result.stdout)}; expected ${JSON.stringify(`${packageVersion}\n`)}\n`);
+    process.exit(1);
+  }
 }

package/cli/help.mjs

@@ -1,6 +1,7 @@
 import { VERSION } from "./constants.mjs";
 import { AUTHORITY_ANCHOR_GRAMMAR_HELP } from "./lib/authority/anchors.mjs";
 import { AUTHORITY_COMMAND_USAGE } from "./commands/authority.mjs";
+import { CODE_COMMAND_USAGE } from "./commands/code.mjs";
 import { localize, styleCommand, styleHeading, styleMuted } from "./lib/ui.mjs";
 
 export function helpText() {
@@ -8,11 +9,11 @@ export function helpText() {
     // The authority list comes from the command module itself so help and the
     // parser cannot describe different surfaces.
     ...AUTHORITY_COMMAND_USAGE,
+    ...CODE_COMMAND_USAGE,
     "nimicoding start [--yes]",
     "nimicoding sync [--apply|--check|--dry-run] [--json]",
     "nimicoding clear [--yes]",
     "nimicoding doctor [--verbose|--json]",
-    "nimicoding validate-ai-governance --profile <profile-id> --scope <all|agents-freshness|context-budget|structure-budget|high-risk-doc-metadata>  # optional L3 repository governance",
   ];
   return [
     styleHeading(`nimicoding ${VERSION}`),
@@ -25,8 +26,12 @@ export function helpText() {
     AUTHORITY_ANCHOR_GRAMMAR_HELP,
     "",
     styleMuted(localize(
-      "Nimi Coding provides canonical authority methodology, formatting, compiler primitives, and deterministic gates. The optional L3 repository-governance command is not authority admission. AI task planning and execution belong to the host.",
-      "Nimi Coding 提供 canonical authority 方法论、格式化、编译器原语与确定性 gate。可选 L3 repository-governance 命令不属于 authority admission；AI 任务规划与执行由宿主负责。",
+      "Nimi Coding provides canonical authority products, bounded read-only TypeScript context, and explicit code-authority marker lookup. AI task planning, editing, verification, and execution belong to the host.",
+      "Nimi Coding 提供 canonical authority 产品、有界只读的 TypeScript context，以及显式 code-authority marker 查询。AI 任务规划、编辑、验证与执行由宿主负责。",
+    )),
+    styleMuted(localize(
+      "Code queries read tracked current-filesystem source; unsaved editor buffers, conformance claims, and unannotated implementation semantics are outside v1.",
+      "Code 查询读取 Git tracked 的当前文件系统源码；未保存的编辑器 buffer、conformance 声明和未标注实现语义不属于 v1。",
     )),
     "",
   ].join("\n");

package/cli/index.mjs

@@ -1,9 +1,9 @@
 import { runAuthority } from "./commands/authority.mjs";
 import { runClear } from "./commands/clear.mjs";
+import { classifyCodeInvocation, runCodeInvocation } from "./commands/code.mjs";
 import { runDoctor } from "./commands/doctor.mjs";
 import { runStart } from "./commands/start.mjs";
 import { runSync } from "./commands/sync.mjs";
-import { runValidateAiGovernance } from "./commands/validate-ai-governance.mjs";
 import { helpText } from "./help.mjs";
 import { VERSION } from "./constants.mjs";
 import { configureCliUi, localize, parseGlobalUiOptions } from "./lib/ui.mjs";
@@ -14,10 +14,11 @@ const COMMANDS = {
   sync: runSync,
   clear: runClear,
   doctor: runDoctor,
-  "validate-ai-governance": runValidateAiGovernance,
 };
 
 export async function runCli(args) {
+  const codeCommandIndex = classifyCodeInvocation(args);
+  if (codeCommandIndex !== null) return runCodeInvocation(args, codeCommandIndex);
   const parsedUi = parseGlobalUiOptions(args);
   if (!parsedUi.ok) {
     process.stderr.write(parsedUi.error);