Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
/**
* 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();
}