ktg-plugin-marketplace/scripts/okf-check.mjs

#!/usr/bin/env node
// okf-check.mjs — shared OKF-compatible second-brain conformance checker.
//
// The single cross-plugin acceptance gate for the convention in
// docs/okf-second-brain/spec.md. Validates one bundle root against the minimal
// contract (spec §3):
//   - every concept file (.md except index.md) MUST carry `type:` in frontmatter;
//     >= 1 file without type -> exit 1, count + names the files; 0 -> exit 0.
//   - recommended fields (resource/title/description/timestamp) -> WARNING, not error.
//   - the bundle-root index.md's `okf_version` is echoed for human comparison
//     (no auto-fetch — offline by design), and its VALUE must be version-shaped:
//     a plugin's own layout revision belongs in `okf_layout` (§12). Shape only —
//     the upstream value set is Google's, not this convention's. Absence is still
//     echoed, not failed.
//
// Provenance: lifted from okr/scripts/okf-check.mjs (the de-facto reference
// implementation; spec §7) at c06e4d7 (2026-06-29), with English output + a vendored
// frontmatter reader so the catalog copy is self-contained. okr has since hardened its
// checker (skip innboks/dot-dirs + scoped checkBundle @ 3b45be7; BOM/CRLF normalization
// @ 482effb); this copy has NOT, so it has DIVERGED and is not verdict-identical with
// okr's current checker. Parity is a gate's output over a corpus, not a claim in this
// header — see docs/okf-second-brain/log.md. Run per bundle root.
// Zero npm dependencies (node: builtins).

import { readdirSync, readFileSync, existsSync } from 'node:fs';
import { join, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import { parseFrontmatter } from './okf-frontmatter.mjs';

const RECOMMENDED = ['resource', 'title', 'description', 'timestamp'];

// All concept files (.md except index.md) under root, recursively.
function walkConcepts(root) {
  const out = [];
  const walk = (dir) => {
    for (const e of readdirSync(dir, { withFileTypes: true })) {
      const p = join(dir, e.name);
      if (e.isDirectory()) walk(p);
      else if (e.isFile() && e.name.endsWith('.md') && e.name !== 'index.md') out.push(p);
    }
  };
  walk(root);
  return out;
}

// Read the root's okf_version (markdown text in index.md, not frontmatter). null if absent.
function rootOkfVersion(root) {
  const idx = join(root, 'index.md');
  if (!existsSync(idx)) return null;
  const m = readFileSync(idx, 'utf8').match(/^okf_version:\s*(.+)$/m);
  return m ? m[1].trim() : null;
}

// spec §3: the value is the upstream OKF version ALONE; a plugin's own layout revision
// belongs in `okf_layout` (§12). This checks only that the value is version-SHAPED — it is
// deliberately NOT a claim about which upstream versions exist, because that value set is
// owned by Google (§12), not by this convention. Absence is a separate §3 MUST and stays
// unenforced here (echoed as MISSING). null when there is nothing to complain about.
const UPSTREAM_VERSION_SHAPE = /^\d+(\.\d+)*$/;
function okfVersionShapeError(value) {
  if (value === null || UPSTREAM_VERSION_SHAPE.test(value)) return null;
  return `root index.md: okf_version "${value}" is not upstream-version-shaped; `
    + "a plugin's own layout revision belongs in okf_layout (spec §12)";
}

export function checkBundle(root) {
  const concepts = walkConcepts(root);
  const missingType = [];
  const warnings = [];
  for (const f of concepts) {
    const { get } = parseFrontmatter(readFileSync(f, 'utf8'));
    const rel = relative(root, f);
    if (!get('type')) {
      missingType.push(rel);
      continue;
    }
    for (const field of RECOMMENDED) {
      if (!get(field)) warnings.push(`${rel}: missing recommended field "${field}"`);
    }
  }
  const okfVersion = rootOkfVersion(root);
  return {
    scanned: concepts.length,
    missingType,
    warnings,
    okfVersion,
    okfVersionError: okfVersionShapeError(okfVersion),
  };
}

// --- CLI ---
const isMain = process.argv[1]
  && fileURLToPath(import.meta.url) === process.argv[1];
if (isMain) {
  const root = process.argv[2];
  if (!root) {
    process.stderr.write('Usage: node okf-check.mjs <bundle-root>\n');
    process.exit(2);
  }
  if (!existsSync(root)) {
    process.stderr.write(`Bundle root does not exist: ${root}\n`);
    process.exit(2);
  }
  const r = checkBundle(root);
  const out = [];
  out.push(`OKF check: ${root}`);
  out.push(`  Concept files scanned: ${r.scanned}`);
  out.push(`  ${r.missingType.length} files without type:`);
  for (const f of r.missingType) out.push(`    - ${f}`);
  out.push(`  okf_version: ${r.okfVersion || 'MISSING (root index without okf_version)'}`);
  if (r.okfVersionError) out.push(`    - ${r.okfVersionError}`);
  out.push(`  Warnings (recommended fields): ${r.warnings.length}`);
  for (const w of r.warnings) out.push(`    ! ${w}`);
  const failures = [];
  if (r.missingType.length > 0) failures.push(`${r.missingType.length} file(s) missing type:`);
  if (r.okfVersionError) failures.push('okf_version is not upstream-version-shaped');
  out.push(failures.length === 0 ? 'OK: valid OKF bundle' : `FAIL: ${failures.join('; ')}`);
  process.stdout.write(`${out.join('\n')}\n`);
  process.exit(failures.length === 0 ? 0 : 1);
}