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