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

// Tests for the shared OKF conformance checker (the cross-plugin acceptance gate).
// Self-contained: builds tiny bundles in a temp dir, so the test has no dependency
// on any sibling repo's fixtures. okf-check is run as a subprocess to capture the
// exit code (the contract). Zero npm deps. Style mirrors check-versions.test.mjs.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { checkBundle } from './okf-check.mjs';

const HERE = dirname(fileURLToPath(import.meta.url));
const CHECK = join(HERE, 'okf-check.mjs');

function tmpRoot() {
  return mkdtempSync(join(tmpdir(), 'okf-catalog-'));
}

// Run okf-check as a subprocess; capture non-zero exit (execFileSync throws then).
function runCheck(root) {
  try {
    const stdout = execFileSync('node', [CHECK, root], { encoding: 'utf8' });
    return { status: 0, stdout };
  } catch (e) {
    return { status: e.status ?? 1, stdout: `${e.stdout || ''}${e.stderr || ''}` };
  }
}

// A minimal conforming bundle: root index.md with okf_version + one fully-typed concept.
function writeValidBundle(dir) {
  writeFileSync(join(dir, 'index.md'), 'okf_version: 0.1\n\n# Bundle\n');
  writeFileSync(
    join(dir, 'profile.md'),
    '---\ntype: Profile\ntitle: User profile\ndescription: The user.\nresource: about\ntimestamp: 2026-06-29\n---\n# Profile\n',
  );
}

test('valid bundle (every concept has type:) -> exit 0, "0 files without type:"', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    const { status, stdout } = runCheck(dir);
    assert.equal(status, 0, 'a valid bundle should exit 0');
    assert.match(stdout, /0 files without type:/);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('concept file without type: -> exit != 0 + count > 0 + names the file', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    writeFileSync(
      join(dir, 'no-type.md'),
      '---\ntitle: Untyped\ndescription: A concept file missing the required type.\n---\n# Untyped\n',
    );
    const { status, stdout } = runCheck(dir);
    assert.notEqual(status, 0, 'a type-less file should exit != 0');
    assert.match(stdout, /[1-9]\d* files without type:/);
    assert.match(stdout, /no-type\.md/);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('echoes okf_version from the root index.md', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    const { stdout } = runCheck(dir);
    assert.match(stdout, /okf_version:\s*0\.1/);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('index.md is exempt from the type requirement (sub-levels included)', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    mkdirSync(join(dir, 'journal'));
    writeFileSync(join(dir, 'journal', 'index.md'), '# Journal\n'); // no frontmatter, must not fail
    const { status } = runCheck(dir);
    assert.equal(status, 0, 'index.md must not be treated as a concept file');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('checkBundle(): recommended-field gaps are warnings, not failures', () => {
  const dir = tmpRoot();
  try {
    writeFileSync(join(dir, 'index.md'), 'okf_version: 0.1\n');
    writeFileSync(join(dir, 'bare.md'), '---\ntype: Note\n---\n# Bare\n'); // type only
    const r = checkBundle(dir);
    assert.equal(r.missingType.length, 0, 'type present -> not a failure');
    assert.ok(r.warnings.length >= 1, 'missing recommended fields -> warnings');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

// --- spec §3 okf_version shape enforcement (the reservation lifted 2026-07-25) ---
// The catalog owns the SEPARATION of the two markers (§12), not the upstream value set
// (owned by Google). So the gate checks that the value is version-SHAPED — never that it
// is a version that exists upstream.

test('okf_version carrying a layout string -> exit != 0 and points at okf_layout', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    writeFileSync(join(dir, 'index.md'), 'okf_version: kb-layout-2026-06\n\n# Bundle\n');
    const { status, stdout } = runCheck(dir);
    assert.notEqual(status, 0, 'a layout snapshot in okf_version must fail the gate');
    assert.match(stdout, /okf_layout/, 'the failure must name the marker it belongs in');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('a version-shaped okf_version passes, including multi-component', () => {
  for (const value of ['0.1', '1.0', '0.1.2', '12']) {
    const dir = tmpRoot();
    try {
      writeValidBundle(dir);
      writeFileSync(join(dir, 'index.md'), `okf_version: ${value}\n\n# Bundle\n`);
      const { status } = runCheck(dir);
      assert.equal(status, 0, `"${value}" is upstream-version-shaped and must pass`);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  }
});

// Scope guard: the reservation covered the value's SHAPE. Presence is a separate §3 MUST
// that this gate still does not enforce — absent stays a non-failing echo, as before.
test('absent okf_version is unchanged by shape enforcement (still exit 0 + MISSING echo)', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    writeFileSync(join(dir, 'index.md'), '# Bundle\n'); // no marker at all
    const { status, stdout } = runCheck(dir);
    assert.equal(status, 0, 'absence must not become an error in this step');
    assert.match(stdout, /MISSING/);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('checkBundle(): the shape verdict is on the return object', () => {
  const bad = tmpRoot();
  const good = tmpRoot();
  try {
    writeValidBundle(bad);
    writeFileSync(join(bad, 'index.md'), 'okf_version: kb-layout-2026-06\n');
    assert.ok(checkBundle(bad).okfVersionError, 'layout string -> an error string');

    writeValidBundle(good);
    assert.equal(checkBundle(good).okfVersionError, null, '0.1 -> no error');
  } finally {
    rmSync(bad, { recursive: true, force: true });
    rmSync(good, { recursive: true, force: true });
  }
});

// --- spec §6 v0.3: FRONTMATTER is the canonical placement (2026-07-31 operator ruling) ---
// Upstream is unambiguous (~/repos/_okf-upstream @ 3fcbb9f, okf/SPEC.md §8:509-510 + §12:773-775):
// a bundle-root index.md MAY carry `okf_version` in a frontmatter block, and that block is the
// only place frontmatter is permitted in an index.md. This convention had said the opposite.
//
// The reader is TRANSITIONAL by design, not by omission: two marketplace emitters still write
// the body-text form (okr scripts/okf-index.mjs:204, linkedin-studio scaffold.ts:38, both measured
// 2026-07-31), and check-okf-parity compares this very value against okr's LIVE checker. A
// frontmatter-only reader would report null here and 0.1 there, splitting the parity signature on
// every body-text fixture before a single emitter had migrated. So both placements are read;
// only one is canonical.

test('§6 v0.3: okf_version in the root frontmatter block is read, and reported as frontmatter', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    writeFileSync(join(dir, 'index.md'), '---\nokf_version: 0.2\n---\n\n# Bundle\n');
    const r = checkBundle(dir);
    assert.equal(r.okfVersion, '0.2');
    assert.equal(r.okfVersionPlacement, 'frontmatter', 'the canonical placement must be reported as such');
    assert.equal(r.okfVersionError, null, 'a version-shaped value in the canonical place is not an error');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

// THE decisive case: upstream shows the key with a value in exactly one place in the whole spec
// (okf/SPEC.md:773) and the value is QUOTED — `okf_version: "0.2"`. 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. Quotes are YAML syntax, not value: unquote FIRST, then check shape. The shape rule
// itself (/^\d+(\.\d+)*$/) is unchanged and still correct.
test('§3 v0.3: a QUOTED value passes — upstream SPEC.md:773 writes okf_version: "0.2"', () => {
  for (const line of ['okf_version: "0.2"', "okf_version: '0.2'"]) {
    const dir = tmpRoot();
    try {
      writeValidBundle(dir);
      writeFileSync(join(dir, 'index.md'), `---\n${line}\n---\n\n# Bundle\n`);
      const { status, stdout } = runCheck(dir);
      assert.equal(status, 0, `${line} is upstream's own canonical form and must pass`);
      assert.match(stdout, /okf_version:\s*0\.2/, 'the echo must show the unquoted value');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  }
});

test('§3 v0.3: unquoting applies to the body-text form too, not just frontmatter', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    writeFileSync(join(dir, 'index.md'), '# Bundle\n\nokf_version: "0.2"\n');
    const { status, stdout } = runCheck(dir);
    assert.equal(status, 0, 'the quoting fix is about the value, not about where it sits');
    assert.match(stdout, /okf_version:\s*0\.2/);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('§6 v0.3: the body-text form still passes, but is reported as the pre-0.3 placement', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir); // writeValidBundle uses the body-text form
    const r = checkBundle(dir);
    assert.equal(r.okfVersion, '0.1', 'body text must keep working — okr and linkedin-studio emit it');
    assert.equal(r.okfVersionPlacement, 'body');
    assert.equal(r.okfVersionError, null, 'placement is declared, NOT enforced — it is not a failure');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('§6 v0.3: body-text placement is visible in the CLI output (declared, not enforced)', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    const { status, stdout } = runCheck(dir);
    assert.equal(status, 0, 'a note must not change the verdict');
    assert.match(stdout, /okf_version:\s*0\.1/, 'the existing echo format must survive');
    assert.match(stdout, /frontmatter/, 'the note must point at the canonical placement');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('§6 v0.3: when both placements carry a value, frontmatter wins', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    writeFileSync(join(dir, 'index.md'), '---\nokf_version: 0.2\n---\n\n# Bundle\n\nokf_version: 0.1\n');
    const r = checkBundle(dir);
    assert.equal(r.okfVersion, '0.2', 'the canonical placement is authoritative');
    assert.equal(r.okfVersionPlacement, 'frontmatter');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

// §12 ruling (2026-07-31): okf_layout stays in BODY TEXT. Upstream's carved exception is
// enumerated to ONE key ("an okf_version key", §8:509-510), so this convention's own extension
// marker stays out of the block upstream governs. Consequence for the reader: okf_layout must
// never be mistaken for okf_version, wherever either one sits.
test('§12 v0.3: okf_layout in body text is not read as okf_version', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    writeFileSync(
      join(dir, 'index.md'),
      '---\nokf_version: 0.2\n---\n\n# Bundle\n\nokf_layout: kb-layout-2026-06\n',
    );
    const { status } = runCheck(dir);
    const r = checkBundle(dir);
    assert.equal(r.okfVersion, '0.2', 'okf_layout must not shadow or corrupt okf_version');
    assert.equal(status, 0, 'the two markers coexisting is the §12 v0.3 shape, not a failure');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

// Regression guard on the quoting fix: unquoting must NOT weaken the shape rule. A layout
// snapshot that happens to be quoted is still a layout snapshot in the wrong field.
test('§3 v0.3: unquoting does not weaken the shape rule — a quoted layout string still fails', () => {
  const dir = tmpRoot();
  try {
    writeValidBundle(dir);
    writeFileSync(join(dir, 'index.md'), '---\nokf_version: "kb-layout-2026-06"\n---\n\n# Bundle\n');
    const { status, stdout } = runCheck(dir);
    assert.notEqual(status, 0, 'unquoting is about syntax, not about accepting non-versions');
    assert.match(stdout, /okf_layout/, 'the failure must still name the marker it belongs in');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});