Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

9.1 KB
Raw Blame
/**
 * Audit-framework schema snapshot generator.
 *
 * Walks the active TipTap PM schema (via `getSchema(sharedExtensions)`) and
 * the active mdast plugin chain (`ACTIVE_MDAST_PLUGINS` from
 * `src/markdown/pipeline.ts`), then writes a structured, byte-stable JSON
 * snapshot to `<core>/schema-snapshot.json`.
 *
 * The snapshot is the audit framework's source-of-truth artifact: the audit
 * framework derives its catalog from this file at
 * audit-generate time, not by importing core at runtime. This decouples the
 * standalone audit project from OK's workspace graph. This positions the same
 * JSON as the
 * language-agnostic byte contract for the future TS↔Rust port.
 *
 * Modes:
 *   default          write the snapshot to <core>/schema-snapshot.json
 *   --check          regenerate in memory; exit non-zero if it differs from
 *                    the committed file. Used by check-schema-snapshot-clean.sh
 *                    in OK's `bun run check` chain.
 *   --out <path>     override the output path (test / debug only)
 *
 * Determinism:
 *   - Nodes / marks emitted in alphabetical order by name
 *   - Attrs within each node / mark emitted in alphabetical order
 *   - ACTIVE_MDAST_PLUGINS emitted in declaration order (the actual chain order)
 *   - Default values are JSON-stringified verbatim; non-serializable values fall
 *     back to `null` with a `__nonSerializableDefault` marker so the snapshot
 *     stays self-describing
 *   - JSON output: 2-space indent + trailing newline (mirrors notices generator)
 *
 * Re-running with no source changes yields a byte-identical file.
 */

import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { argv, exit } from 'node:process';
import { fileURLToPath } from 'node:url';
import { getSchema } from '@tiptap/core';
import { sharedExtensions } from '../src/extensions/shared.ts';
import { ACTIVE_MDAST_PLUGINS } from '../src/markdown/pipeline.ts';

const SCRIPT_URL = import.meta.url;
const SCRIPT_PATH = fileURLToPath(SCRIPT_URL);
const DEFAULT_OUT = fileURLToPath(new URL('../schema-snapshot.json', SCRIPT_URL));

interface AttrSnapshot {
  hasDefault: boolean;
  default?: unknown;
  /** Marker present iff `default` could not be JSON-serialized. */
  __nonSerializableDefault?: true;
}

interface NodeSnapshot {
  attrs: Record<string, AttrSnapshot>;
  content: string;
  marks: string;
  group: string;
  inline: boolean;
  atom: boolean;
  defining: boolean;
  isolating: boolean;
}

interface MarkSnapshot {
  attrs: Record<string, AttrSnapshot>;
  excludes: string;
  group: string;
  inclusive: boolean;
  spanning: boolean;
}

interface PluginSnapshot {
  name: string;
  /** npm package version, or null when the plugin is local to OK */
  version: string | null;
  /** true iff the plugin is registered with options */
  hasOptions: boolean;
}

interface SchemaSnapshotV1 {
  version: 1;
  topNode: string;
  nodes: Record<string, NodeSnapshot>;
  marks: Record<string, MarkSnapshot>;
  activeMdastPlugins: PluginSnapshot[];
}

function captureAttr(attrSpec: unknown): AttrSnapshot {
  const spec = attrSpec as Record<string, unknown>;
  const hasDefault = 'default' in spec;
  if (!hasDefault) return { hasDefault: false };
  const value = spec.default;
  // JSON.stringify returns undefined for non-JSON-serializable values
  // (functions, symbols, BigInt). Capturing such defaults verbatim would
  // make the snapshot non-deterministic; we fall back to a marker.
  let serialized: string | undefined;
  try {
    serialized = JSON.stringify(value);
  } catch {
    return { hasDefault: true, default: null, __nonSerializableDefault: true };
  }
  if (serialized === undefined) {
    return { hasDefault: true, default: null, __nonSerializableDefault: true };
  }
  return { hasDefault: true, default: JSON.parse(serialized) as unknown };
}

function captureSchema(): {
  topNode: string;
  nodes: Record<string, NodeSnapshot>;
  marks: Record<string, MarkSnapshot>;
} {
  const schema = getSchema(sharedExtensions);
  const nodes: Record<string, NodeSnapshot> = {};
  const marks: Record<string, MarkSnapshot> = {};

  for (const nodeName of Object.keys(schema.nodes).sort()) {
    const nodeType = schema.nodes[nodeName];
    if (!nodeType) continue;
    const spec = nodeType.spec;
    const attrs: Record<string, AttrSnapshot> = {};
    for (const attrName of Object.keys(spec.attrs ?? {}).sort()) {
      const attrSpec = spec.attrs?.[attrName];
      attrs[attrName] = captureAttr(attrSpec);
    }
    nodes[nodeName] = {
      attrs,
      content: spec.content ?? '',
      marks: spec.marks ?? '',
      group: spec.group ?? '',
      inline: !!spec.inline,
      atom: !!spec.atom,
      defining: !!spec.defining,
      isolating: !!spec.isolating,
    };
  }

  for (const markName of Object.keys(schema.marks).sort()) {
    const markType = schema.marks[markName];
    if (!markType) continue;
    const spec = markType.spec;
    const attrs: Record<string, AttrSnapshot> = {};
    for (const attrName of Object.keys(spec.attrs ?? {}).sort()) {
      const attrSpec = spec.attrs?.[attrName];
      attrs[attrName] = captureAttr(attrSpec);
    }
    marks[markName] = {
      attrs,
      // `excludes: undefined` means "exclude marks of the same type" — PM
      // canonicalizes this to the mark's own name. `''` means "coexist with
      // everything" (Code mark's deliberate widening per CLAUDE.md STOP).
      excludes: typeof spec.excludes === 'string' ? spec.excludes : markName,
      group: spec.group ?? '',
      inclusive: spec.inclusive !== false,
      spanning: spec.spanning !== false,
    };
  }

  return { topNode: schema.topNodeType.name, nodes, marks };
}

function getPluginVersion(packageName: string): string | null {
  // Local plugins (e.g., callout-transformer, image-promoter) do not have
  // installable npm packages — resolution throws. Return null in that case so
  // the snapshot records the plugin's identity without a phantom version.
  //
  // Read the version by resolving the package's entry and walking up to the
  // nearest package.json whose `name` matches. A direct
  // `require('<pkg>/package.json')` is not portable: packages that restrict
  // their `exports` map (remark-parse, remark-gfm, …) do not expose
  // `./package.json`, so the subpath does not resolve under Node's resolver.
  try {
    let dir = dirname(fileURLToPath(import.meta.resolve(packageName)));
    for (;;) {
      const pkgPath = join(dir, 'package.json');
      if (existsSync(pkgPath)) {
        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as unknown;
        if (pkg && typeof pkg === 'object' && (pkg as { name?: unknown }).name === packageName) {
          const ver = (pkg as { version?: unknown }).version;
          return typeof ver === 'string' ? ver : null;
        }
      }
      const parent = dirname(dir);
      if (parent === dir) return null;
      dir = parent;
    }
  } catch {
    return null;
  }
}

function captureActivePlugins(): PluginSnapshot[] {
  return ACTIVE_MDAST_PLUGINS.map((entry) => ({
    name: entry.name,
    version: getPluginVersion(entry.name),
    hasOptions: 'options' in entry && entry.options !== undefined,
  }));
}

function buildSnapshot(): SchemaSnapshotV1 {
  const { topNode, nodes, marks } = captureSchema();
  const activeMdastPlugins = captureActivePlugins();
  return {
    version: 1,
    topNode,
    nodes,
    marks,
    activeMdastPlugins,
  };
}

function serialize(snap: SchemaSnapshotV1): string {
  return `${JSON.stringify(snap, null, 2)}\n`;
}

function parseArgs(rawArgs: readonly string[]): {
  check: boolean;
  out: string;
} {
  let check = false;
  let out = DEFAULT_OUT;
  for (let i = 0; i < rawArgs.length; i++) {
    const a = rawArgs[i];
    if (a === '--check') {
      check = true;
    } else if (a === '--out') {
      const next = rawArgs[i + 1];
      if (!next) {
        process.stderr.write('--out requires a path argument\n');
        exit(2);
      }
      out = next;
      i++;
    }
  }
  return { check, out };
}

function main(): void {
  // argv[0] = bun, argv[1] = script path, rest = user args
  const userArgs = argv.slice(2);
  const { check, out } = parseArgs(userArgs);
  const snapshot = buildSnapshot();
  const serialized = serialize(snapshot);

  if (check) {
    if (!existsSync(out)) {
      process.stderr.write(
        `❌ schema-snapshot.json missing at ${out}\n` +
          `   Run: bun run schema:dump\n` +
          `   Then: git add ${out}\n`,
      );
      exit(1);
    }
    const committed = readFileSync(out, 'utf-8');
    if (committed !== serialized) {
      process.stderr.write(
        '❌ schema-snapshot.json drifted from current schema.\n' +
          '   Re-run:  bun run schema:dump\n' +
          `   Stage:   git add ${out}\n`,
      );
      exit(1);
    }
    process.stdout.write(`schema-snapshot.json fresh ✓ (${out})\n`);
    return;
  }

  writeFileSync(out, serialized);
  process.stdout.write(`Wrote ${out}\n`);
}

// Bun runs this file directly; only execute main when invoked as the entry
// script (mirrors the notices generator's pattern). Supports import-only
// usage from tests if needed.
if (SCRIPT_PATH === fileURLToPath(`file://${argv[1] ?? ''}`)) {
  main();
}