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. The value is unquoted before the shape check (spec 0.3):
//     quotes are YAML syntax, and upstream's own example is quoted.
//   - PLACEMENT (spec §6, 0.3): frontmatter is canonical, body text is the pre-0.3
//     form. Both are read; which one was found is reported as `okfVersionPlacement`
//     and noted in the output. Declared, not enforced — see rootOkfVersion() for
//     why enforcing it here would red the parity gate.
//
// 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';

// Recommended fields (spec §4) — WARNINGS, never failures. The list is chosen by the bundle
// root's own okf_version, because upstream retired one of them.
//
// okf/SPEC.md §13.1:802-805 (read at 3fcbb9f, 2026-07-31): "`timestamp` is superseded by
// `generated.at`" — one of v0.2's two deliberate breaking changes — and :804 lets a consumer
// "fall back to a legacy `timestamp` when `generated` is absent". A flat, version-unconditional
// list cannot serve both: it either nags a correct v0.2 bundle about a retired field, or goes
// silent about a field v0.1 still wants. So: pick by version, and let ABSENCE mean the legacy
// floor (absence is echoed, never failed — §3 — so it still needs a defined list).
//
// `generated` is read by the same FLAT reader as every other key, so it sees upstream's own
// flow form (`generated: { by, at }`, SPEC.md:236/371) as one string — present is all this axis
// asks. A block-style `generated:` with the pair on following lines would read as absent and
// warn. That is a known limit of the vendored reader, not a rule of this convention.
const RECOMMENDED_V01 = ['resource', 'title', 'description', 'timestamp'];
const RECOMMENDED_V02 = ['resource', 'title', 'description', 'generated'];
const GENERATED_AT_FLOOR = '0.2';

// 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;
}

// Strip one matched pair of surrounding quotes. YAML quotes are SYNTAX, not value — upstream's
// only example of the key with a value writes `okf_version: "0.2"` (okf/SPEC.md:773), and the
// pre-0.3 gate ran the shape regex on the raw captured string, saw the quote characters, and
// failed upstream's own canonical example. Unquote FIRST, then check shape; the shape rule itself
// is unchanged and still rejects everything it rejected before.
function unquote(value) {
  const m = value.match(/^(["'])([\s\S]*)\1$/);
  return m ? m[2] : value;
}

// Read the bundle-root's okf_version. Returns { value, placement }; value is null when no marker.
//
// spec §6 (v0.3): the CANONICAL placement is the root index.md's FRONTMATTER block — upstream's
// single carved exception to "index files contain no frontmatter" (okf/SPEC.md §8:509-510 +
// §12:773-775, read at 3fcbb9f). This convention previously said the opposite.
//
// The pre-0.3 body-text form is still READ and still passes. That is deliberate, not leftover:
// ONE marketplace emitter still writes it (okr scripts/okf-index.mjs:204 — body text, emitted
// after the `# heading` line with no `---` delimiters; measured 2026-08-02 at okr d634385), and
// check-okf-parity compares this very value against okr's LIVE checker. Reading frontmatter alone
// would report null here and 0.1 there, splitting the parity signature on every body-text bundle.
// So placement is DECLARED, not enforced: the gate reports which form it found and moves on.
// linkedin-studio was the second emitter; it migrated to root frontmatter at its bc47c18
// (scaffold.ts, measured 2026-08-02). The fallback becomes removable only once okr migrates too.
//
// okf_layout is deliberately NOT read here. §12 (v0.3) keeps it in body text, because upstream's
// exception is enumerated to ONE key ("an okf_version key"); this convention's own extension
// marker stays out of the block upstream governs.
function rootOkfVersion(root) {
  const idx = join(root, 'index.md');
  if (!existsSync(idx)) return { value: null, placement: null };
  const content = readFileSync(idx, 'utf8');

  const fromFrontmatter = parseFrontmatter(content).get('okf_version');
  if (fromFrontmatter !== null) {
    return { value: unquote(fromFrontmatter), placement: 'frontmatter' };
  }

  const m = content.match(/^okf_version:\s*(.+)$/m);
  return m ? { value: unquote(m[1].trim()), placement: 'body' } : { value: null, placement: 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)";
}

// Is `value` at least `floor`, comparing version COMPONENTS? okf_version is version-SHAPED
// (UPSTREAM_VERSION_SHAPE), which is not the same thing as a decimal number: parseFloat('0.10')
// is 0.1 and would sort 0.10 BEFORE 0.2, handing a newer bundle the retired field. A value that
// is not version-shaped is not ordered at all — it already carries okfVersionError, and the
// caller falls back to the legacy floor rather than guessing.
function isAtLeast(value, floor) {
  if (value === null || !UPSTREAM_VERSION_SHAPE.test(value)) return false;
  const a = value.split('.').map(Number);
  const b = floor.split('.').map(Number);
  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
    const x = a[i] ?? 0;
    const y = b[i] ?? 0;
    if (x !== y) return x > y;
  }
  return true;
}

export function recommendedFor(okfVersion) {
  return isAtLeast(okfVersion, GENERATED_AT_FLOOR) ? RECOMMENDED_V02 : RECOMMENDED_V01;
}

export function checkBundle(root) {
  const concepts = walkConcepts(root);
  const missingType = [];
  const warnings = [];
  // Read the root marker BEFORE the concept loop: it selects which recommended list applies.
  const { value: okfVersion, placement: okfVersionPlacement } = rootOkfVersion(root);
  const RECOMMENDED = recommendedFor(okfVersion);
  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}"`);
    }
  }
  return {
    scanned: concepts.length,
    missingType,
    warnings,
    okfVersion,
    okfVersionPlacement,
    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.okfVersionPlacement === 'body') {
    out.push('    note: pre-0.3 body-text placement; spec §6 canonical is the root index.md '
      + 'frontmatter block. Read and accepted — not a failure.');
  }
  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);
}