@agentsfleet/orly 0.5.0

package/src/surfaces.ts

@@ -0,0 +1,89 @@
+import { isObject, JsonObject, stringArray } from "./model";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+
+const PIPE_OUTPUT = "pipe";
+const DEFAULT_BRANCHES = ["main", "master"];
+const ORIGIN_PREFIX = "origin/";
+const SURFACES_FIELD = "surfaces";
+const USER_FIELD = "user";
+const DOCS_FIELD = "docs";
+const SPEC_TREE = /^docs\/v[0-9]+\//;
+const TEST_PATH = /(^|\/)tests?\/|\.test\.|_test\.|\.spec\./;
+const MARKDOWN = /\.(md|mdx)$/;
+// One fixed source-extension set across every repo: handlers (.zig), CLI and
+// UI TypeScript, OpenAPI YAML, scripts. A fixed set keeps the check identical
+// everywhere instead of drifting per repository.
+const SOURCE_EXTENSIONS = /\.(zig|ts|tsx|js|jsx|mjs|py|rs|go|sh|sql|yaml|yml|json|toml)$/;
+
+export type SurfaceReport = {
+  changed: string[];
+  code: string[];
+  userSurface: string[];
+  docs: string[];
+};
+
+// Classify the branch diff once per inspection; every criterion reads this
+// report instead of running its own git commands.
+export function classifyBranch(root: string, surfaces: JsonObject | undefined): SurfaceReport {
+  const changed = branchDiff(root);
+  const user = surfacePrefixes(surfaces, USER_FIELD);
+  const docs = surfacePrefixes(surfaces, DOCS_FIELD);
+  return {
+    changed,
+    code: changed.filter(isCode),
+    userSurface: changed.filter((path) => isUserSurface(path, user)),
+    docs: changed.filter((path) => isDocs(path, docs)),
+  };
+}
+
+export function isCode(path: string): boolean {
+  return !MARKDOWN.test(path) && (SOURCE_EXTENSIONS.test(path) || TEST_PATH.test(path));
+}
+
+// User surface: a repository-declared prefix, a real source file, and not a test —
+// a test-only change under a user prefix must not demand a docs edit, or the
+// gate trains everyone to distrust it.
+export function isUserSurface(path: string, prefixes: string[]): boolean {
+  if (!prefixes.some((prefix) => path.startsWith(prefix))) return false;
+  return SOURCE_EXTENSIONS.test(path) && !TEST_PATH.test(path) && !MARKDOWN.test(path);
+}
+
+// Docs: a repository-declared prefix, but never the spec tree — every milestone
+// edits its own spec, so counting docs/v*/ would make the check auto-pass.
+export function isDocs(path: string, prefixes: string[]): boolean {
+  if (SPEC_TREE.test(path)) return false;
+  return prefixes.some((prefix) => path.startsWith(prefix));
+}
+
+export function branchDiff(root: string): string[] {
+  const base = defaultMergeBase(root);
+  if (!base) return [];
+  const output = gitOutput(root, ["diff", "--name-only", `${base}..HEAD`]);
+  return output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+
+export function defaultMergeBase(root: string): string {
+  for (const branch of defaultBranchCandidates(root)) {
+    const base = gitOutput(root, ["merge-base", branch, "HEAD"]);
+    if (base) return base;
+  }
+  return "";
+}
+
+function defaultBranchCandidates(root: string): string[] {
+  const candidates: string[] = [];
+  const head = gitOutput(root, ["rev-parse", "--abbrev-ref", "origin/HEAD"]);
+  if (head.startsWith(ORIGIN_PREFIX)) candidates.push(head);
+  for (const name of DEFAULT_BRANCHES) candidates.push(`${ORIGIN_PREFIX}${name}`, name);
+  return candidates;
+}
+
+function surfacePrefixes(surfaces: JsonObject | undefined, field: string): string[] {
+  if (!isObject(surfaces) || !(field in surfaces)) return [];
+  return stringArray(surfaces[field], `${SURFACES_FIELD}.${field}`);
+}
+
+function gitOutput(root: string, command: string[]): string {
+  const result = Bun.spawnSync(["git", ...command], { cwd: root, env: UNSCOPED_ENVIRONMENT, stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT });
+  return result.exitCode === 0 ? result.stdout.toString().trim() : "";
+}

package/src/validation.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+
+import { validateRelativePath } from "./validation";
+
+test("relative paths cannot escape the output root", () => {
+  const errors: string[] = [];
+
+  validateRelativePath("../outside.md", "fixture", errors);
+
+  expect(errors).toEqual(["fixture must stay below the output root: ../outside.md"]);
+});

package/src/validation.ts

@@ -0,0 +1,87 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+
+import type { JsonObject } from "./model";
+
+export function validateRelativePath(value: unknown, label: string, errors: string[]): void {
+  if (!isString(value) || value.length === 0) {
+    errors.push(`${label} must be a string`);
+    return;
+  }
+  if (isAbsolute(value) || relative(".", value).split(/[\\/]/).includes("..")) errors.push(`${label} must stay below the output root: ${value}`);
+}
+
+// Optional diff-surface prefixes a repository declares: surfaces.user (paths
+// whose change demands a docs update) and surfaces.docs (paths that count as
+// that update).
+export function validateSurfaces(label: string, value: unknown, errors: string[]): void {
+  if (value === undefined) return;
+  if (!isObject(value)) {
+    errors.push(`${label} surfaces must be an object`);
+    return;
+  }
+  for (const [field, prefixes] of Object.entries(value)) {
+    if (field !== "user" && field !== "docs") errors.push(`${label} surfaces.${field} is not a known surface`);
+    else if (!Array.isArray(prefixes) || !prefixes.every((prefix) => isString(prefix) && prefix.length > 0)) {
+      errors.push(`${label} surfaces.${field} must be an array of path prefixes`);
+    }
+  }
+}
+
+export function validateCommands(label: string, value: unknown, errors: string[]): void {
+  if (!isObject(value)) {
+    errors.push(`${label} commands must be an object`);
+    return;
+  }
+  for (const [name, invocations] of Object.entries(value)) {
+    if (!Array.isArray(invocations) || invocations.length === 0) {
+      errors.push(`${label} command ${name} must be non-empty`);
+      continue;
+    }
+    for (const invocation of invocations) if (!Array.isArray(invocation) || invocation.length === 0 || !invocation.every((argument) => isString(argument) && argument.length > 0)) errors.push(`${label} command ${name} arguments must be strings`);
+  }
+}
+
+export function validateActiveRule(
+  key: string,
+  rule: JsonObject,
+  root: string,
+  errors: string[],
+): void {
+  if (rule.decision === "mechanical") {
+    validateMechanicalRule(key, rule, root, errors);
+    return;
+  }
+  if (rule.decision === "repository") {
+    if (!isString(rule.command) || rule.command.length === 0) errors.push(`repository rule ${key} needs a command name`);
+    return;
+  }
+  if (rule.decision !== "judgment") errors.push(`rule ${key} has invalid decision ${String(rule.decision)}`);
+}
+
+function validateMechanicalRule(key: string, rule: JsonObject, root: string, errors: string[]): void {
+  if (!Array.isArray(rule.checker) || rule.checker.length === 0) errors.push(`mechanical rule ${key} needs a checker`);
+  if (!isObject(rule.fixtures)) {
+    errors.push(`mechanical rule ${key} needs fixtures`);
+    return;
+  }
+  for (const kind of ["pass", "fail"]) {
+    const fixtures = rule.fixtures[kind];
+    if (!Array.isArray(fixtures) || fixtures.length === 0) {
+      errors.push(`mechanical rule ${key} needs ${kind} fixtures`);
+      continue;
+    }
+    for (const fixture of fixtures) {
+      validateRelativePath(fixture, `rule ${key} ${kind} fixture`, errors);
+      if (isString(fixture) && !existsSync(join(root, fixture))) errors.push(`rule ${key} ${kind} fixture source is missing: ${fixture}`);
+    }
+  }
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}

package/src/verify.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from "bun:test";
+import { resolve } from "node:path";
+
+import { RulesModel } from "./model";
+import { verifyRenders } from "./verify";
+
+const ROOT = resolve(import.meta.dir, "..");
+
+test("every profile renders deterministically", async () => {
+  const checks = await verifyRenders(await RulesModel.load(ROOT));
+
+  expect(checks.filter((check) => check.name.endsWith(".idempotent")).every((check) => check.result === "pass")).toBeTrue();
+});

package/src/verify.ts

@@ -0,0 +1,59 @@
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { localSelection } from "./config";
+import { objectValue, RulesModel } from "./model";
+import { Renderer } from "./render";
+
+const PASS_RESULT = "pass";
+const FAIL_RESULT = "fail";
+
+export type VerificationCheck = {
+  name: string;
+  result: typeof PASS_RESULT | typeof FAIL_RESULT;
+  detail?: string;
+};
+
+// Two proofs: every profile renders the same bytes twice (determinism), and
+// the committed root AGENTS.md matches its render (currency). No stored
+// hashes — the render itself is the reference.
+export async function verifyRenders(model: RulesModel): Promise<VerificationCheck[]> {
+  model.validate();
+  const checks: VerificationCheck[] = [];
+  const renderer = new Renderer(model);
+  const local = await localSelection(model, model.root);
+  const everything = Object.keys(objectValue(model.registry.packs, "registry packs")).sort();
+  for (const [name, packs] of [["local", local.packs], ["all", everything]] as Array<[string, string[]]>) {
+    const first = await renderer.renderText(packs, local.commands);
+    const second = await renderer.renderText(packs, local.commands);
+    checks.push({
+      name: `render.${name}.idempotent`,
+      result: first === second ? PASS_RESULT : FAIL_RESULT,
+    });
+  }
+  const errors = await renderer.rootErrors(local.packs, local.commands);
+  checks.push({ name: "generated.root.current", result: errors.length === 0 ? PASS_RESULT : FAIL_RESULT, detail: errors.join("; ") });
+  return checks;
+}
+
+export async function writeEvidence(
+  model: RulesModel,
+  profile: string,
+  checks: VerificationCheck[],
+  languageModelResult: "pass" | "not-required",
+): Promise<string> {
+  const path = join(model.root, ".oracle/evidence.json");
+  mkdirSync(dirname(path), { recursive: true });
+  const commit = Bun.spawnSync(["git", "rev-parse", "HEAD"], { cwd: model.root, stdout: "pipe", stderr: "ignore" });
+  const evidence = {
+    schema_version: 1,
+    profile,
+    source_commit: commit.exitCode === 0 ? commit.stdout.toString().trim() : "uncommitted",
+    result: checks.every((check) => check.result === PASS_RESULT) ? PASS_RESULT : FAIL_RESULT,
+    checks,
+    llm_result: languageModelResult,
+    created_at: new Date().toISOString().replace(/\.\d{3}Z$/, "+00:00"),
+  };
+  await Bun.write(path, `${JSON.stringify(evidence, null, 2)}\n`);
+  return path;
+}