@kontourai/corpus 0.0.0-bootstrap.0 → 0.8.0

package/src/cli.mjs

@@ -0,0 +1,226 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { DocsKitError, EXIT_OK, EXIT_USAGE, UsageError } from './errors.mjs';
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+export const HELP = `Corpus ${VERSION}: check, build, locate, and retrieve source-bound docs over MCP
+
+Usage: corpus <command> [options]
+
+Commands:
+  check   Run the docs gates: manifest, purpose, links, reachability, topics,
+          redirects, paths, builtOn, covers, decisions (when declared), and with
+          --base freshness and the ADR freeze
+            --root <dir>        repository root (default: .)
+            --base <git-ref>    also check freshness against the changes in <git-ref>...HEAD
+            --advisory          report stale documents as warnings and exit 0
+            --only <gates>      run only these comma-separated gates (and the manifest);
+                                a selected gate that cannot run is a usage error
+            --json              print the result as one JSON object on stdout
+  build   Run check (without freshness), render the site, write docs-bundle.json,
+          and verify every internal link of the generated site
+            --root <dir>        repository root (default: .)
+            --out <dir>         output directory, replaced on each build (default: dist-pages)
+            --base-url <url>    published site URL (default: https://kontourai.github.io/<product>/)
+  locate  Locate a quote in source-bound docs
+            --root <dir>        repository root (default: .)
+            --quote <text>      passage to locate
+            --source <path>     optionally restrict to one document
+  mcp     Serve docs bundles over stdio to MCP clients; at most one source
+            --repo <dir>        build one bundle in memory from a checkout
+            --workspace <dir>   serve every immediate subdirectory that has corpus.json
+            --hub <url>         fetch <url>/products.json and each bundle (default: https://kontourai.github.io/)
+            --bundle <file>     serve a prebuilt docs-bundle.json as is; repeat for more products
+  hub     Build the organization hub page from products.json
+            --products <file>   product list (default: products.json)
+            --out <dir>         output directory (default: dist-hub)
+  decisions check   Run only the decisions gates (records, index, and with --base
+                    the ADR freeze); needs a "decisions" block in corpus.json
+            --root <dir>        repository root (default: .)
+            --base <git-ref>    also refuse files added under decisions.adr.dir since <git-ref>
+  decisions index   Write the decisions index file, and nothing else
+            --root <dir>        repository root (default: .)
+  content impact   Map changed files to related content, including GitHub file URLs
+            --manifest <file>   relationship/review manifest (default: corpus-content.json)
+            --root <dir>        repository root (default: .)
+            --base <git-ref>    committed changes from the merge base
+            --changed-file <path>  explicit changed file; repeat instead of --base
+  content check    Check reviewed input/output bytes, resolving GitHub refs once per run
+            --manifest <file>   review manifest (default: corpus-content.json)
+            --root <dir>        repository root (default: .)
+            --checkout <owner/repo=dir>  optional local working bytes; repeat for more repos
+  init    Scaffold a v2 corpus.json from README.md and docs/**/*.md; never overwrites a
+          corpus.json, and refuses while a retired v1 docs-kit.json is present
+            --root <dir>        repository root (default: .)
+
+Options:
+  -h, --help       show this help
+  -v, --version    print the version
+
+Exit codes: 0 ok, 1 gate failure, 2 usage or configuration error.
+Manifest reference: https://github.com/kontourai/corpus#manifest-reference`;
+
+const COMMAND_OPTIONS = {
+  check: { root: { type: 'string' }, base: { type: 'string' }, advisory: { type: 'boolean' }, only: { type: 'string' }, json: { type: 'boolean' } },
+  build: { root: { type: 'string' }, out: { type: 'string' }, 'base-url': { type: 'string' } },
+  locate: { root: { type: 'string' }, quote: { type: 'string' }, source: { type: 'string' } },
+  mcp: { repo: { type: 'string' }, workspace: { type: 'string' }, hub: { type: 'string' }, bundle: { type: 'string', multiple: true } },
+  hub: { products: { type: 'string' }, out: { type: 'string' } },
+  init: { root: { type: 'string' } },
+  'decisions check': { root: { type: 'string' }, base: { type: 'string' } },
+  'decisions index': { root: { type: 'string' } },
+  'content impact': { root: { type: 'string' }, manifest: { type: 'string' }, base: { type: 'string' }, 'changed-file': { type: 'string', multiple: true } },
+  'content check': { root: { type: 'string' }, manifest: { type: 'string' }, checkout: { type: 'string', multiple: true } },
+};
+const DECISIONS_SUBCOMMANDS = ['check', 'index'];
+
+function parse(command, args) {
+  try {
+    return parseArgs({
+      args,
+      options: { ...COMMAND_OPTIONS[command], help: { type: 'boolean', short: 'h' } },
+      strict: true,
+      allowPositionals: false,
+    }).values;
+  } catch (error) {
+    throw new UsageError(`${command}: ${error.message}`);
+  }
+}
+
+function requireValue(values, name) {
+  // A `multiple` option parses to an array; every occurrence needs a value.
+  if ([values[name] ?? []].flat().some((value) => value.trim() === '')) throw new UsageError(`--${name} needs a value`);
+}
+
+/** `check --json` when the run did not reach a gate result: a usage or configuration error, or a crash. */
+function checkErrorJson(message, exitCode, { base, advisory, only }) {
+  return { schemaVersion: 1, tool: 'corpus', command: 'check', verdict: 'fail', exitCode, base, advisory, only, error: message };
+}
+
+/** Run the CLI and return the exit code. Output goes to stdout; diagnostics to stderr. */
+export async function main(argv, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const say = (text) => stdout.write(`${text}\n`);
+  const warn = (text) => stderr.write(`${text}\n`);
+  let args = argv;
+  // `npx -y github:kontourai/corpus#<sha> corpus <cmd>` runs this bin with
+  // "docs-kit" as its first argument, so tolerate one leading program name.
+  if (args[0] === 'docs-kit' || args[0] === 'corpus') args = args.slice(1);
+  let [command, ...rest] = args;
+
+  if (command === undefined) {
+    warn(HELP);
+    return EXIT_USAGE;
+  }
+  if (command === '-h' || command === '--help' || command === 'help') {
+    say(HELP);
+    return EXIT_OK;
+  }
+  if (command === '-v' || command === '--version') {
+    say(VERSION);
+    return EXIT_OK;
+  }
+
+  // `check --json`: stdout must hold one JSON object on every exit, so any
+  // failure before or outside the gates is printed as a fail object too.
+  const jsonCheck = command === 'check' && rest.includes('--json');
+  const checkRun = { base: null, advisory: false, only: null };
+  try {
+    if (command === 'decisions' || command === 'content') {
+      const [sub, ...subArgs] = rest;
+      if (sub === '-h' || sub === '--help') {
+        say(HELP);
+        return EXIT_OK;
+      }
+      const choices = command === 'content' ? ['check', 'impact'] : DECISIONS_SUBCOMMANDS;
+      if (!choices.includes(sub))
+        throw new UsageError(`${command} needs a subcommand: ${choices.join(' or ')}${sub === undefined ? '' : ` (got "${sub}")`}`);
+      command = `${command} ${sub}`;
+      rest = subArgs;
+    }
+    if (!Object.hasOwn(COMMAND_OPTIONS, command)) throw new UsageError(`unknown command "${command}"\n\n${HELP}`);
+    const values = parse(command, rest);
+    if (values.help) {
+      if (jsonCheck) throw new UsageError('--help prints text and cannot be combined with --json; run "corpus check --help"');
+      say(HELP);
+      return EXIT_OK;
+    }
+    for (const name of Object.keys(COMMAND_OPTIONS[command])) if (COMMAND_OPTIONS[command][name].type === 'string') requireValue(values, name);
+    const root = path.resolve(values.root ?? '.');
+
+    switch (command) {
+      case 'content check':
+      case 'content impact': {
+        const { runContent } = await import('./content.mjs');
+        const result = await runContent({ root, manifest: values.manifest, mode: command.split(' ')[1], base: values.base, changed: values['changed-file'], checkouts: values.checkout });
+        say(JSON.stringify(result, null, 2));
+        return result.exitCode;
+      }
+      case 'check': {
+        const { runChecks, formatCheckReport, parseOnly, checkReportJson } = await import('./check.mjs');
+        checkRun.base = values.base ?? null;
+        checkRun.advisory = Boolean(values.advisory);
+        if (values.advisory && values.base === undefined) throw new UsageError('--advisory only applies to the freshness gate; pass --base <git-ref>');
+        if (values.only !== undefined) checkRun.only = parseOnly(values.only);
+        const result = runChecks({ root, ...checkRun });
+        if (values.json) say(JSON.stringify(checkReportJson(result, checkRun), null, 2));
+        else (result.exitCode === EXIT_OK ? say : warn)(formatCheckReport(result, root));
+        return result.exitCode;
+      }
+      case 'build': {
+        const { runBuild } = await import('./build.mjs');
+        const result = runBuild({ root, out: path.resolve(values.out ?? 'dist-pages'), baseUrl: values['base-url'] });
+        (result.exitCode === EXIT_OK ? say : warn)(result.report);
+        return result.exitCode;
+      }
+      case 'locate': {
+        if (!values.quote) throw new UsageError('locate requires --quote <text>');
+        const { bundleFromCheckout } = await import('./bundle.mjs');
+        const { locateInBundle } = await import('./locate.mjs');
+        const result = locateInBundle(bundleFromCheckout(root), values.quote, { source: values.source });
+        say(JSON.stringify(result, null, 2));
+        return result.error ? 1 : EXIT_OK;
+      }
+      case 'mcp': {
+        const { runMcp } = await import('./mcp.mjs');
+        await runMcp({ repo: values.repo, workspace: values.workspace, hub: values.hub, bundle: values.bundle });
+        return EXIT_OK;
+      }
+      case 'hub': {
+        const { runHub } = await import('./hub.mjs');
+        say(runHub({ products: path.resolve(values.products ?? 'products.json'), out: path.resolve(values.out ?? 'dist-hub') }));
+        return EXIT_OK;
+      }
+      case 'decisions check': {
+        const { runDecisionChecks, formatCheckReport } = await import('./check.mjs');
+        const result = runDecisionChecks({ root, base: values.base ?? null });
+        (result.exitCode === EXIT_OK ? say : warn)(formatCheckReport(result, root, { title: 'corpus decisions check' }));
+        return result.exitCode;
+      }
+      case 'decisions index': {
+        const { loadManifest, manifestFile } = await import('./manifest.mjs');
+        const { writeDecisionIndex } = await import('./decisions.mjs');
+        // A documents entry for the index may name the file this command is about to create.
+        const manifest = loadManifest(root, { allowMissingDecisionIndex: true });
+        if (!manifest.decisions)
+          throw new UsageError(`${manifestFile(root)} has no "decisions" block; add "decisions": {} to enable the decisions gate`);
+        say(writeDecisionIndex(root, manifest.decisions));
+        return EXIT_OK;
+      }
+      case 'init': {
+        const { runInit } = await import('./init.mjs');
+        say(runInit({ root }));
+        return EXIT_OK;
+      }
+    }
+  } catch (error) {
+    const known = error instanceof DocsKitError;
+    // Not a gate result: never let an unexpected crash read as "docs failed" (1).
+    const exitCode = known ? error.exitCode : EXIT_USAGE;
+    if (jsonCheck) say(JSON.stringify(checkErrorJson(known ? error.message : `internal error: ${error?.message ?? error}`, exitCode, checkRun), null, 2));
+    warn(known ? `docs-kit: ${error.message}` : `docs-kit: internal error: ${error?.stack ?? error}`);
+    return exitCode;
+  }
+  return EXIT_USAGE;
+}

package/src/content-freshness.mjs

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { contentDigest, readContentManifest } from './content.mjs';
+import { readFileAtMergeBase } from './git.mjs';
+import { UsageError } from './errors.mjs';
+import { statInRepo } from './paths.mjs';
+
+const MANIFEST = 'corpus-content.json';
+
+function currentFile(root, entry) {
+  // Freshness stays offline: remote reviews belong to `content check`.
+  if (!entry.path || statInRepo(root, entry.path)?.kind !== 'file') return false;
+  return contentDigest(readFileSync(path.resolve(root, entry.path)), entry.pointer) === entry.sha256;
+}
+
+/** Local, newly recorded byte reviews can justify leaving covering prose unchanged. */
+export function reviewedContentDocuments(root, base, documents, changed) {
+  const approved = new Set();
+  if (!existsSync(path.resolve(root, MANIFEST))) return approved;
+  const manifest = readContentManifest(root);
+  if (!changed.includes(MANIFEST) || !manifest.reviews?.length) return approved;
+  const previousBytes = readFileAtMergeBase(root, base, MANIFEST);
+  let previous;
+  try { previous = previousBytes === null ? null : JSON.parse(previousBytes); }
+  catch { throw new UsageError('content review manifest at the merge base is not valid JSON'); }
+  const previousReviews = new Map((previous?.reviews ?? []).map((review) => [review.id, review]));
+  for (const review of manifest.reviews) {
+    if (JSON.stringify(previousReviews.get(review.id)) === JSON.stringify(review)) continue;
+    if (!review.inputs.every((entry) => currentFile(root, entry)) ||
+      !review.outputs.every((entry) => currentFile(root, entry))) continue;
+    const inputs = new Set(review.inputs.filter((entry) => entry.pointer === undefined).map((entry) => entry.path));
+    for (const { source, covered } of documents) {
+      if (covered.every((file) => inputs.has(file)) && review.outputs.some((entry) => entry.path === source && entry.pointer === undefined)) approved.add(source);
+    }
+  }
+  return approved;
+}

package/src/content.mjs

@@ -0,0 +1,222 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { UsageError } from './errors.mjs';
+import { changedFiles } from './git.mjs';
+import { repoGlobError, repoPathError } from './paths.mjs';
+
+const SHA = /^[a-f0-9]{64}$/;
+const COMMIT = /^[a-f0-9]{40}$/;
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const fail = (message) => { throw new UsageError(`content: NOT_VERIFIED: ${message}`); };
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const validPointer = (value) => typeof value === 'string' && (value === '' || value.startsWith('/')) && !/~(?:[^01]|$)/.test(value);
+function ordered(value) {
+  if (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value)))) fail('selected JSON number is outside the finite safe range');
+  if (Array.isArray(value)) return value.map(ordered);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, ordered(value[key])]));
+  return value;
+}
+
+/** Whole-file bytes, or canonical JSON for one explicitly selected value. */
+export function contentDigest(bytes, pointer) {
+  if (pointer === undefined) return hash(bytes);
+  if (!validPointer(pointer)) fail('invalid JSON Pointer');
+  let value;
+  try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { fail('selected content is not valid UTF-8 JSON'); }
+  for (const encoded of pointer === '' ? [] : pointer.slice(1).split('/')) {
+    const key = encoded.replaceAll('~1', '/').replaceAll('~0', '~');
+    if (value === null || typeof value !== 'object' || !Object.hasOwn(value, key) ||
+      (Array.isArray(value) && !/^(?:0|[1-9][0-9]*)$/.test(key))) fail(`JSON Pointer does not resolve: ${pointer}`);
+    value = value[key];
+  }
+  return hash(JSON.stringify(ordered(value)));
+}
+
+function keys(value, allowed, required, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    Object.keys(value).some((key) => !allowed.includes(key)) ||
+    required.some((key) => !Object.hasOwn(value, key))) fail(`${label}: invalid or unknown fields`);
+}
+
+/** GitHub blob URLs identify a repository, ref and file independently of checkout layout. */
+export function githubContentReference(value) {
+  let url;
+  try { url = new URL(value); } catch { fail(`invalid GitHub file URL: ${value}`); }
+  if (url.protocol !== 'https:' || url.hostname !== 'github.com' || url.port || url.username || url.password || url.search || url.hash)
+    fail(`expected a GitHub HTTPS blob URL without credentials, query or fragment: ${value}`);
+  const parts = url.pathname.slice(1).split('/').map((part) => {
+    try { return decodeURIComponent(part); } catch { fail(`invalid URL encoding: ${value}`); }
+  });
+  const [owner, repo, kind, ref, ...file] = parts;
+  const repository = `${owner}/${repo}`;
+  const source = file.join('/');
+  if (!REPO.test(repository) || kind !== 'blob' || !ref || /[\\\s?#]/.test(ref) || repoPathError(source) || source.startsWith('.git/'))
+    fail(`expected https://github.com/owner/repo/blob/ref/path: ${value}`);
+  return { repository, ref, path: source };
+}
+
+function nonemptyArray(value, label) {
+  if (!Array.isArray(value) || !value.length) fail(`${label} must be a nonempty array`);
+}
+
+function contentTarget(value) {
+  let url;
+  try { url = new URL(value); } catch { fail(`invalid content target: ${value}`); }
+  if (url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.search)
+    fail(`content targets must be HTTPS URLs without credentials or query: ${value}`);
+  if (url.hostname === 'github.com') githubContentReference(value);
+}
+
+function files(entries, label) {
+  nonemptyArray(entries, label);
+  const identities = new Set();
+  for (const entry of entries) {
+    keys(entry, ['path', 'url', 'sha256', 'revision', 'pointer'], ['sha256'], label);
+    if (Boolean(entry.path) === Boolean(entry.url) || !SHA.test(entry.sha256)) fail(`${label}: expected one path or URL and a SHA-256`);
+    if (entry.url) {
+      githubContentReference(entry.url);
+      if (!COMMIT.test(entry.revision)) fail(`${label}: remote files need the reviewed full commit revision`);
+    } else if (repoPathError(entry.path) || entry.path.startsWith('.git/') || entry.revision !== undefined) fail(`${label}: invalid local file`);
+    if (entry.pointer !== undefined && !validPointer(entry.pointer)) fail(`${label}: invalid JSON Pointer`);
+    const identity = JSON.stringify([entry.path ?? entry.url, entry.pointer ?? null]);
+    if (identities.has(identity)) fail(`${label}: duplicate file ${identity}`);
+    identities.add(identity);
+  }
+}
+
+export function readContentManifest(root, manifest = 'corpus-content.json') {
+  let raw;
+  try { raw = JSON.parse(readFileSync(path.resolve(root, manifest), 'utf8')); }
+  catch (error) { fail(`cannot read ${manifest}: ${error.message}`); }
+  keys(raw, ['schemaVersion', 'repository', 'relationships', 'reviews'], ['schemaVersion', 'repository'], 'manifest');
+  if (raw.schemaVersion !== 1 || !REPO.test(raw.repository)) fail('expected schemaVersion 1 and an owner/repo repository');
+  if (raw.relationships === undefined && raw.reviews === undefined) fail('manifest needs relationships or reviews');
+  if ((raw.relationships !== undefined && !Array.isArray(raw.relationships)) ||
+    (raw.reviews !== undefined && !Array.isArray(raw.reviews))) fail('relationships and reviews must be arrays');
+  const ids = new Set();
+  for (const relation of raw.relationships ?? []) {
+    keys(relation, ['id', 'covers', 'targets'], ['id', 'covers', 'targets'], 'relationship');
+    if (typeof relation.id !== 'string' || !relation.id || ids.has(relation.id)) fail('relationship IDs must be nonempty and unique');
+    ids.add(relation.id);
+    nonemptyArray(relation.covers, 'covers');
+    if (relation.covers.some((glob) => repoGlobError(glob))) fail(`${relation.id}: invalid covers glob`);
+    nonemptyArray(relation.targets, 'targets');
+    for (const url of relation.targets) contentTarget(url);
+  }
+  ids.clear();
+  for (const review of raw.reviews ?? []) {
+    keys(review, ['id', 'reviewedAt', 'note', 'limits', 'inputs', 'outputs'], ['id', 'reviewedAt', 'note', 'limits', 'inputs', 'outputs'], 'review');
+    if (typeof review.id !== 'string' || !review.id || ids.has(review.id)) fail('review IDs must be nonempty and unique');
+    ids.add(review.id);
+    if (typeof review.reviewedAt !== 'string' || !Number.isFinite(Date.parse(review.reviewedAt)) ||
+      typeof review.note !== 'string' || !review.note.trim() || typeof review.limits !== 'string' || !review.limits.trim()) fail(`${review.id}: date, review note and limits are required`);
+    files(review.inputs, `${review.id} inputs`);
+    files(review.outputs, `${review.id} outputs`);
+  }
+  return raw;
+}
+
+export function contentImpact(manifest, changed) {
+  if (!Array.isArray(manifest.relationships) || !manifest.relationships.length) fail('impact needs declared relationships');
+  if (!Array.isArray(changed) || changed.some((file) => repoPathError(file))) fail('changed files must be repository-relative paths');
+  return manifest.relationships.flatMap(({ id, covers, targets }) => {
+    const matches = picomatch(covers.map((glob) => glob.endsWith('/') ? `${glob}**` : glob), { dot: true });
+    const changedBy = [...new Set(changed)].filter((file) => matches(file)).sort();
+    return changedBy.length ? [{ id, targets, changedBy }] : [];
+  });
+}
+
+function localBytes(root, file) {
+  if (repoPathError(file)) fail(`invalid local path ${file}`);
+  try {
+    const base = realpathSync(root);
+    const target = realpathSync(path.resolve(base, file));
+    const within = path.relative(base, target);
+    if (within === '..' || within.startsWith(`..${path.sep}`) || path.isAbsolute(within)) fail(`file escapes checkout: ${file}`);
+    return readFileSync(target);
+  } catch (error) { fail(`cannot read ${file}: ${error.message}`); }
+}
+
+async function githubJson(endpoint) {
+  const headers = { Accept: 'application/vnd.github+json' };
+  // Credentials go only to GitHub's API, never to file URLs or redirects.
+  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  const response = await fetch(`https://api.github.com/${endpoint}`, { headers, redirect: 'error', signal: AbortSignal.timeout(20_000) });
+  if (!response.ok) fail(`GitHub lookup returned ${response.status}: ${endpoint}`);
+  return response.json();
+}
+
+function checkoutMap(values) {
+  const entries = new Map();
+  for (const value of values) {
+    const split = value.indexOf('=');
+    const repository = value.slice(0, split);
+    const directory = value.slice(split + 1);
+    if (split < 1 || !REPO.test(repository) || !directory || entries.has(repository)) fail('checkout must be a unique owner/repo=/directory mapping');
+    entries.set(repository, path.resolve(directory));
+  }
+  return entries;
+}
+
+/** Check declared byte freshness. Checkout mappings explicitly select working bytes, without network. */
+export async function checkContentReviews(root, manifest, checkouts = []) {
+  nonemptyArray(manifest.reviews, 'check reviews');
+  const local = checkoutMap(checkouts);
+  const revisions = new Map();
+  const bytes = new Map();
+  const observedRevisions = {};
+  const read = async (entry) => {
+    if (entry.path) return localBytes(root, entry.path);
+    const source = githubContentReference(entry.url);
+    if (local.has(source.repository)) {
+      observedRevisions[source.repository] = 'local working bytes (explicit checkout mapping)';
+      return localBytes(local.get(source.repository), source.path);
+    }
+    const key = `${source.repository}@${source.ref}`;
+    if (!revisions.has(key)) {
+      const result = await githubJson(`repos/${source.repository}/commits/${encodeURIComponent(source.ref)}`);
+      if (!COMMIT.test(result.sha)) fail(`GitHub returned an invalid revision for ${key}`);
+      revisions.set(key, result.sha);
+      observedRevisions[key] = result.sha;
+    }
+    const revision = revisions.get(key);
+    const fileKey = `${source.repository}@${revision}/${source.path}`;
+    if (!bytes.has(fileKey)) {
+      const result = await githubJson(`repos/${source.repository}/contents/${source.path.split('/').map(encodeURIComponent).join('/')}?ref=${revision}`);
+      if (result.type !== 'file' || result.encoding !== 'base64' || typeof result.content !== 'string') fail(`GitHub did not return file bytes for ${entry.url}`);
+      bytes.set(fileKey, Buffer.from(result.content, 'base64'));
+    }
+    return bytes.get(fileKey);
+  };
+  const failures = [];
+  for (const review of manifest.reviews) {
+    for (const [kind, entries] of [['input', review.inputs], ['output', review.outputs]]) {
+      for (const entry of entries) {
+        if (contentDigest(await read(entry), entry.pointer) !== entry.sha256) failures.push(`${review.id}: changed ${kind}: ${entry.url ?? entry.path}${entry.pointer === undefined ? '' : `#${entry.pointer}`}`);
+      }
+    }
+  }
+  return {
+    schemaVersion: 1, command: 'content check', verdict: failures.length ? 'fail' : 'pass',
+    exitCode: failures.length ? 1 : 0, failures, observedRevisions,
+    limits: 'Freshness of declared file bytes or selected JSON values only; not semantic correctness, complete dependency coverage, legal classification, release availability or deployment. Re-review claims before changing hashes.',
+  };
+}
+
+export async function runContent({ root, manifest, mode, base, changed = [], checkouts = [] }) {
+  const reviewed = readContentManifest(root, manifest);
+  if (mode === 'check') {
+    try { return await checkContentReviews(root, reviewed, checkouts); }
+    catch (error) { fail(error.message); }
+  }
+  if (base !== undefined && changed.length) fail('choose --base or --changed-file, not both');
+  if (base === undefined && !changed.length) fail('impact needs --base or --changed-file');
+  return {
+    schemaVersion: 1, command: 'content impact', verdict: 'advisory', exitCode: 0,
+    repository: reviewed.repository, surfaces: contentImpact(reviewed, base === undefined ? changed : changedFiles(root, base)),
+    limits: 'Declared relationships are review leads, not proof that claims changed or a complete dependency graph.',
+  };
+}