Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
7.0 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Vault-wide broken-link ratchet gate (context-integrity-gates, unit G).
 *
 * Measures every vault root named in `link-ratchet.json` and compares
 * the broken-link count against the committed ceiling.
 *
 * A link is broken when the READ-TIME resolution ladder cannot resolve
 * it - the same ladder the readers follow, shared from `store.ts`. The
 * narrower `target_document_id IS NULL` predicate this gate first
 * shipped with counted every basename wikilink as broken (55 of 55 rows
 * on `templates/brain-starter`), so it rose on healthy edits; the
 * definition token in the ceiling file records which rule produced a
 * number, and a ceiling written under the old one is refused rather
 * than compared. The write form
 * records what it measured; the `--check` form is the SAME code path
 * with writing disabled, so what CI detects and what the write form
 * records can never diverge - the shape `scripts/sync-version.ts`
 * establishes, and the reason both forms are gated in both workflows.
 *
 * Exit codes:
 *   0  every subject is at or below its ceiling
 *   1  a subject rose above its ceiling (`--check` only), a subject
 *      could not be measured (BOTH forms - a gate that passes without a
 *      count is the failure this exists to remove), or the ceiling file
 *      cannot be compared (foreign schema version or definition token).
 *
 * The ceiling is a MEASUREMENT, not a target: it encodes whatever link
 * rot existed when it was last written. Raising it is a deliberate,
 * reviewable line in a diff - which is why the write form records a
 * rise instead of refusing it, and why only `--check` fails on one.
 *
 * Usage:
 *   bun run link-ratchet          # measure and record
 *   bun run link-ratchet:check    # exit 1 on a rise, no writes
 */

import { readFileSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import {
  DANGLING_LINK_DEFINITION,
  LINK_RATCHET_FIX_COMMAND,
  judgeSubject,
  measureVault,
  parseCeiling,
  serializeCeiling,
  type LinkRatchetCeiling,
  type LinkRatchetVerdict,
} from "../src/core/search/link-ratchet.ts";

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");

/** Repository-relative location of the committed ceiling. */
export const CEILING_FILE = "link-ratchet.json";

const LABEL_WIDTH = 14;

export interface LinkRatchetRunOptions {
  /** Directory holding `link-ratchet.json`; subjects resolve against it. */
  readonly root: string;
  /** When true, nothing is written. Detection is unaffected. */
  readonly check: boolean;
  readonly stdout: (text: string) => void;
  readonly stderr: (text: string) => void;
}

export interface LinkRatchetRun {
  readonly exitCode: number;
  readonly verdicts: ReadonlyArray<LinkRatchetVerdict>;
}

function label(text: string): string {
  return `  ${`${text}:`.padEnd(LABEL_WIDTH)}`;
}

function describe(verdict: LinkRatchetVerdict): string {
  const m = verdict.measurement;
  if (!m.measurable) {
    return `${label("UNMEASURABLE")}${verdict.subject} (${m.reason}: ${m.detail})`;
  }
  const status = verdict.status === "level" ? "ok" : verdict.status.toUpperCase();
  return (
    `${label(status)}${verdict.subject} ` +
    `(dangling ${m.dangling} of ${m.links} link row(s), ceiling ${verdict.ceiling})`
  );
}

/**
 * Write the recorded ceiling when `write` is true. The single write
 * guard in this file: with `write` false the comparison above it has
 * already run, unchanged.
 */
function updateCeilingFile(path: string, next: LinkRatchetCeiling, write: boolean): boolean {
  const text = readFileSync(path, "utf8");
  const updated = serializeCeiling(next);
  if (updated === text) return false;
  if (write) writeFileSync(path, updated, "utf8");
  return true;
}

export async function runLinkRatchet(opts: LinkRatchetRunOptions): Promise<LinkRatchetRun> {
  const path = join(opts.root, CEILING_FILE);
  let ceiling: LinkRatchetCeiling;
  try {
    // Only the write form may read a ceiling recorded under an older
    // counting definition - it is the command the refusal names as the
    // fix, so it has to be able to re-measure and record the new one.
    ceiling = parseCeiling(readFileSync(path, "utf8"), { allowForeignDefinition: !opts.check });
  } catch (e) {
    opts.stderr(`${e instanceof Error ? e.message : String(e)}\n`);
    return { exitCode: 1, verdicts: [] };
  }

  opts.stdout(`canonical definition: ${DANGLING_LINK_DEFINITION}\n`);
  const comparable = ceiling.definition === DANGLING_LINK_DEFINITION;
  if (!comparable) {
    opts.stdout(
      `${label("redefining")}recorded under '${ceiling.definition}'; ` +
        "every subject is re-measured and the committed counts are replaced\n",
    );
  }

  // Each subject is measured in its own temporary workspace, so the
  // order of resolution cannot affect any result; reporting is in
  // committed-file order regardless.
  const verdicts: ReadonlyArray<LinkRatchetVerdict> = await Promise.all(
    ceiling.subjects.map(async (subject) =>
      judgeSubject(
        subject.path,
        subject.dangling,
        await measureVault(join(opts.root, subject.path)),
        { comparable },
      ),
    ),
  );
  for (const verdict of verdicts) opts.stdout(`${describe(verdict)}\n`);

  const risen = verdicts.filter((v) => v.status === "rise");
  const unmeasured = verdicts.filter((v) => v.status === "unmeasurable");

  // A partial recording would silently invent a ceiling for a subject
  // nobody measured, so an unmeasurable subject blocks the write too.
  if (unmeasured.length === 0) {
    const next: LinkRatchetCeiling = {
      ...ceiling,
      // What is recorded is what THIS build counted, never the token the
      // file happened to carry.
      definition: DANGLING_LINK_DEFINITION,
      subjects: verdicts.map((v) => ({
        path: v.subject,
        dangling: v.measurement.measurable ? v.measurement.dangling : v.ceiling,
      })),
    };
    if (updateCeilingFile(path, next, !opts.check) && !opts.check) {
      opts.stdout(`${label("wrote")}${CEILING_FILE}\n`);
    }
  }

  if (unmeasured.length > 0) {
    opts.stderr(
      `\n${unmeasured.length} subject(s) could not be measured; the ratchet has no count to ` +
        "compare and will not pass. Fix the subject path or the index error named above.\n",
    );
    return { exitCode: 1, verdicts };
  }
  if (opts.check && risen.length > 0) {
    opts.stderr(
      `\n${risen.length} subject(s) above ceiling; fix the broken links, or record the new ` +
        `baseline (a reviewable diff) with: ${LINK_RATCHET_FIX_COMMAND}\n`,
    );
    return { exitCode: 1, verdicts };
  }
  return { exitCode: 0, verdicts };
}

async function main(argv: ReadonlyArray<string>): Promise<number> {
  const check = argv.includes("--check");
  const run = await runLinkRatchet({
    root: ROOT,
    check,
    stdout: (text) => process.stdout.write(text),
    stderr: (text) => process.stderr.write(text),
  });
  return run.exitCode;
}

if (import.meta.main) {
  process.exit(await main(process.argv.slice(2)));
}