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

// --- §13.1 (upstream v0.2): `timestamp` is superseded by `generated.at` ---
// okf/SPEC.md:802-805 @ 3fcbb9f, read 2026-07-31. The supersession is one of v0.2's two
// deliberate BREAKING changes (§13.1), and :804 explicitly lets a consumer "fall back to a
// legacy `timestamp` when `generated` is absent". A flat, version-unconditional RECOMMENDED
// list cannot be right for both versions at once: it either nags a correct v0.2 bundle about a
// retired field, or goes silent about a field v0.1 still wants. So the list is chosen by the
// bundle root's own okf_version.
//
// Measured when written: every fixture in both corpora and both live emitters (okr,
// linkedin-studio) still write 0.1, so this changes no verdict today. It is written now
// because the upstream reading is fresh and pinned to a frozen commit.

// A concept carrying every v0.1 recommended field except the one under test.
function conceptMissing(field) {
  const fm = { type: 'Note', title: 'T', description: 'D', resource: 'about' };
  if (field !== 'timestamp') fm.timestamp = '2026-06-29';
  if (field !== 'generated') fm.generated = '{ by: human:ktg, at: 2026-06-29T00:00:00Z }';
  const body = Object.entries(fm).map(([k, v]) => `${k}: ${v}`).join('\n');
  return `---\n${body}\n---\n# Concept\n`;
}

function warnsAbout(dir, versionLine, field) {
  writeFileSync(join(dir, 'index.md'), `${versionLine}\n\n# Bundle\n`);
  writeFileSync(join(dir, 'c.md'), conceptMissing(field));
  return checkBundle(dir).warnings.some((w) => w.includes(`"${field}"`));
}

test('§13.1: a v0.1 bundle still wants `timestamp` (the legacy fallback of :804)', () => {
  const dir = tmpRoot();
  try {
    assert.ok(warnsAbout(dir, 'okf_version: 0.1', 'timestamp'), 'v0.1 keeps the legacy field');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('§13.1: a v0.2 bundle is NOT nagged about the retired `timestamp`', () => {
  const dir = tmpRoot();
  try {
    assert.equal(
      warnsAbout(dir, '---\nokf_version: "0.2"\n---', 'timestamp'),
      false,
      'a v0.2 bundle recording generated.at is correct, not deficient',
    );
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('§13.1: a v0.2 bundle wants `generated` in its place', () => {
  const dir = tmpRoot();
  try {
    assert.ok(warnsAbout(dir, '---\nokf_version: "0.2"\n---', 'generated'), 'v0.2 wants generated');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('§13.1: an ABSENT okf_version falls back to the v0.1 floor, not the v0.2 list', () => {
  const dir = tmpRoot();
  try {
    // Absence is echoed, never failed (§3) — so it must still get a defined recommended list.
    assert.ok(warnsAbout(dir, '# Bundle only', 'timestamp'), 'no marker -> legacy floor');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

// Regression guard on the comparison itself. okf_version is version-SHAPED (^\d+(\.\d+)*$),
// so it is NOT a decimal number: parseFloat('0.10') is 0.1, which would sort 0.10 BEFORE 0.2
// and hand a newer bundle the retired field. Compare component-wise or not at all.
test('§13.1: 0.10 is NEWER than 0.2 — the version compare is not parseFloat', () => {
  const dir = tmpRoot();
  try {
    assert.equal(
      warnsAbout(dir, 'okf_version: 0.10', 'timestamp'),
      false,
      '0.10 > 0.2, so the retired field must not be demanded',
    );
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

// --- §4.1 vs §5: a nested key is not the top-level key of the same name ---
// okf/SPEC.md @ 3fcbb9f, measured 2026-08-01. The spec names `resource`, `sources[].resource`,
// `executor.resource`, and `attester.resource` as DISTINCT fields (:467-469): top-level
// `resource` is the URI of the asset a concept DESCRIBES (:196), `sources[].resource` is the
// material it DERIVES FROM (:302). `sources` entries carry their own `title`/`type` too.
//
// The reader's key regex was `^\s*<key>:` with the m flag — indentation-agnostic, so a
// block-form nested entry satisfied the top-level lookup. Measured before the fix: a concept
// with NO top-level `type` and a `sources[].type` reported "0 files without type: / OK",
// i.e. a false negative on §4.1's ONLY always-required field. `untyped` is in the parity
// signature (check-okf-parity.mjs:73-76) and okr vendors the same regex, so both impls were
// blind identically and the parity gate stayed green while both were wrong.
//
// Flow-form (`sources: [{ id: s1, resource: fixture }]`) never had the bug — the nested key is
// mid-line, so `^` cannot match it. Only block form did.

const NESTED_SOURCES = 'sources:\n  - id: s1\n    resource: https://example.com/schema\n    title: GA4 schema\n    description: derived-from, not described-by\n    type: Reference\n';

test('§4.1: a nested sources[].type does NOT satisfy the required top-level type', () => {
  const dir = tmpRoot();
  try {
    writeFileSync(join(dir, 'index.md'), 'okf_version: 0.1\n\n# Bundle\n');
    writeFileSync(join(dir, 'c.md'), `---\ntitle: T\n${NESTED_SOURCES}---\n# Concept\n`);
    assert.deepEqual(checkBundle(dir).missingType, ['c.md'], 'type is required AT TOP LEVEL');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test('§4.1: nested sources[] keys do NOT satisfy the recommended top-level fields', () => {
  const dir = tmpRoot();
  try {
    writeFileSync(join(dir, 'index.md'), 'okf_version: 0.1\n\n# Bundle\n');
    writeFileSync(join(dir, 'c.md'), `---\ntype: Note\ntimestamp: 2026-06-29\n${NESTED_SOURCES}---\n# Concept\n`);
    const warned = checkBundle(dir).warnings.join('\n');
    for (const field of ['resource', 'title', 'description']) {
      assert.ok(warned.includes(`"${field}"`), `${field} is absent at top level, so it must warn`);
    }
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

// The fix anchors the key to column 0. Guard the documented flow-form behaviour it must not
// disturb: a top-level `generated: { by, at }` is one line starting at column 0 -> present.
test('§4.1: anchoring does not break the top-level flow-form value', () => {
  const dir = tmpRoot();
  try {
    writeFileSync(join(dir, 'index.md'), '---\nokf_version: "0.2"\n---\n\n# Bundle\n');
    writeFileSync(
      join(dir, 'c.md'),
      '---\ntype: Note\ntitle: T\ndescription: D\nresource: about\n' +
        'generated: { by: human:ktg, at: 2026-06-29T00:00:00Z }\n---\n# Concept\n',
    );
    assert.deepEqual(checkBundle(dir).warnings, [], 'every recommended field is present at top level');
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});