An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file remark.ts
* @input Synchronous transform-only Remark plugins over the supported MDAST subset
* @output A Markdown transform that applies a validated round trip or fails closed
* @position Optional tree-shakeable compatibility adapter; never imported by Markdown
*/
import type {
MarkdownAstDataValue,
MarkdownAstExtensionNode,
MarkdownAstRoot,
} from './ast';
import {
isMarkdownPluginData,
type MarkdownTransform,
type MarkdownTransformContext,
} from './plugins/protocol';
import {isSafeMarkdownParserUrl} from './url';
/* ------------------------------------------------------------------ *
* Public mutable tree the adapted plugin observes
* ------------------------------------------------------------------ */
export interface MarkdownRemarkPoint {
line?: number;
column?: number;
offset?: number;
}
export interface MarkdownRemarkPosition {
start: MarkdownRemarkPoint;
end: MarkdownRemarkPoint;
}
export interface MarkdownRemarkNodeBase {
position?: MarkdownRemarkPosition;
data?: {[key: string]: unknown};
}
export interface MarkdownRemarkText extends MarkdownRemarkNodeBase {
type: 'text';
value: string;
}
export interface MarkdownRemarkInlineCode extends MarkdownRemarkNodeBase {
type: 'inlineCode';
value: string;
}
export interface MarkdownRemarkInlineMath extends MarkdownRemarkNodeBase {
type: 'inlineMath';
value: string;
}
export interface MarkdownRemarkBreak extends MarkdownRemarkNodeBase {
type: 'break';
}
export interface MarkdownRemarkPhrasingParent<
Type extends 'strong' | 'emphasis' | 'delete',
> extends MarkdownRemarkNodeBase {
type: Type;
children: MarkdownRemarkPhrasingContent[];
}
export interface MarkdownRemarkLink extends MarkdownRemarkNodeBase {
type: 'link';
url: string;
/** Always `null` on input; a non-empty title cannot round-trip. */
title?: string | null;
children: MarkdownRemarkPhrasingContent[];
}
export interface MarkdownRemarkImage extends MarkdownRemarkNodeBase {
type: 'image';
url: string;
/** Always `null` on input; a non-empty title cannot round-trip. */
title?: string | null;
alt: string;
}
/** Astryx-owned citation. Read-only inside the adapter. */
export interface MarkdownRemarkCitation extends MarkdownRemarkNodeBase {
type: 'citation';
sourceId: string;
}
/** Astryx-owned plugin extension node. Read-only inside the adapter. */
export interface MarkdownRemarkExtension extends MarkdownRemarkNodeBase {
type: 'extension';
plugin: string;
name: string;
display: 'inline' | 'block';
source?: string;
}
export type MarkdownRemarkPhrasingContent =
| MarkdownRemarkText
| MarkdownRemarkInlineCode
| MarkdownRemarkInlineMath
| MarkdownRemarkBreak
| MarkdownRemarkPhrasingParent<'strong'>
| MarkdownRemarkPhrasingParent<'emphasis'>
| MarkdownRemarkPhrasingParent<'delete'>
| MarkdownRemarkLink
| MarkdownRemarkImage
| MarkdownRemarkCitation
| MarkdownRemarkExtension;
export interface MarkdownRemarkHeading extends MarkdownRemarkNodeBase {
type: 'heading';
depth: 1 | 2 | 3 | 4 | 5 | 6;
children: MarkdownRemarkPhrasingContent[];
}
export interface MarkdownRemarkParagraph extends MarkdownRemarkNodeBase {
type: 'paragraph';
children: MarkdownRemarkPhrasingContent[];
}
export interface MarkdownRemarkCode extends MarkdownRemarkNodeBase {
type: 'code';
lang: string | null;
/** The authored info string after the language, `null` when absent. */
meta?: string | null;
value: string;
}
export interface MarkdownRemarkMath extends MarkdownRemarkNodeBase {
type: 'math';
value: string;
}
export interface MarkdownRemarkBlockquote extends MarkdownRemarkNodeBase {
type: 'blockquote';
children: MarkdownRemarkBlockContent[];
}
export interface MarkdownRemarkListItem extends MarkdownRemarkNodeBase {
type: 'listItem';
checked?: boolean | null;
/** Only a falsy value round-trips; Astryx has no loose-item contract. */
spread?: boolean | null;
children: MarkdownRemarkBlockContent[];
}
export interface MarkdownRemarkList extends MarkdownRemarkNodeBase {
type: 'list';
ordered: boolean;
start?: number | null;
spread?: boolean | null;
/** Astryx-preserved ordered-list marker delimiter. */
delimiter?: '.' | ')';
children: MarkdownRemarkListItem[];
}
export type MarkdownRemarkTableAlignment = 'left' | 'center' | 'right' | null;
export interface MarkdownRemarkTableCell extends MarkdownRemarkNodeBase {
type: 'tableCell';
children: MarkdownRemarkPhrasingContent[];
}
export interface MarkdownRemarkTableRow extends MarkdownRemarkNodeBase {
type: 'tableRow';
children: MarkdownRemarkTableCell[];
}
export interface MarkdownRemarkTable extends MarkdownRemarkNodeBase {
type: 'table';
align: MarkdownRemarkTableAlignment[];
children: MarkdownRemarkTableRow[];
}
export interface MarkdownRemarkThematicBreak extends MarkdownRemarkNodeBase {
type: 'thematicBreak';
}
export type MarkdownRemarkBlockContent =
| MarkdownRemarkHeading
| MarkdownRemarkParagraph
| MarkdownRemarkCode
| MarkdownRemarkMath
| MarkdownRemarkBlockquote
| MarkdownRemarkList
| MarkdownRemarkTable
| MarkdownRemarkThematicBreak
| MarkdownRemarkImage
| MarkdownRemarkExtension;
export interface MarkdownRemarkRoot extends MarkdownRemarkNodeBase {
type: 'root';
children: MarkdownRemarkBlockContent[];
}
/* ------------------------------------------------------------------ *
* Public constrained file and plugin shapes
* ------------------------------------------------------------------ */
export interface MarkdownRemarkMessage {
reason: string;
fatal: boolean;
place: unknown;
ruleId: string | null;
toString(): string;
}
/**
* The isolated per-invocation file. It exposes readonly source text, finite
* JSON-like data, and diagnostics — never processor registration, cross-run
* state, a compiler, I/O, or asynchronous completion.
*/
export interface MarkdownRemarkFile {
readonly value: string;
readonly data: {[key: string]: unknown};
readonly messages: MarkdownRemarkMessage[];
message(
reason: string | Error,
place?: unknown,
ruleId?: string,
): MarkdownRemarkMessage;
fail(reason: string | Error, place?: unknown, ruleId?: string): never;
toString(): string;
}
/**
* A Remark transformer either mutates the tree and returns nothing or returns
* a replacement root, and an attacher may legitimately return nothing at all.
* Both shapes have to stay assignable, so `void` belongs in these unions.
*/
// eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- see above
type Returned<Value> = Value | undefined | void;
export type MarkdownRemarkTransformer = (
tree: MarkdownRemarkRoot,
file: MarkdownRemarkFile,
) => Returned<MarkdownRemarkRoot>;
export type MarkdownRemarkPlugin<
Settings extends ReadonlyArray<unknown> = readonly [],
> = (...settings: Settings) => Returned<MarkdownRemarkTransformer>;
/**
* The structural shape a conventional Unified/Remark plugin already has. Its
* declared transformer may take Unified's callback parameter and may declare
* an asynchronous return union, so an existing typed plugin type-checks at the
* callsite without being rewritten. The adapter rejects an actual promise, and
* a callback-style transformer, at run time instead.
*
* Authoring a new plugin against Astryx? Annotate it with
* `MarkdownRemarkPlugin` to keep a typed tree and file.
*/
export type MarkdownRemarkCompatibleTransformer = (...args: never[]) => unknown;
export type MarkdownRemarkCompatiblePlugin<
Settings extends ReadonlyArray<unknown> = readonly [],
> = (...settings: Settings) => Returned<MarkdownRemarkCompatibleTransformer>;
/* ------------------------------------------------------------------ *
* Internal helpers
* ------------------------------------------------------------------ */
type UnknownRecord = Record<string, unknown>;
/** Links a mutable copy back to the canonical node it was copied from. */
const REMARK_ORIGIN = Symbol('astryx.markdown.remarkOrigin');
/** hast escape channels; they are raw-markup sinks, not Markdown data. */
const RAW_MARKUP_DATA_KEYS: ReadonlyArray<string> = [
'hName',
'hProperties',
'hChildren',
];
const PHRASING_TYPES = new Set([
'text',
'inlineCode',
'inlineMath',
'break',
'strong',
'emphasis',
'delete',
'link',
'image',
'citation',
]);
const BLOCK_TYPES = new Set([
'heading',
'paragraph',
'code',
'math',
'blockquote',
'list',
'table',
'thematicBreak',
'image',
]);
const PHRASING_PARENTS = new Set([
'heading',
'paragraph',
'strong',
'emphasis',
'delete',
'link',
'tableCell',
]);
const BLOCK_PARENTS = new Set(['root', 'blockquote', 'listItem']);
const FIELDS_BY_TYPE: Readonly<Record<string, ReadonlyArray<string>>> = {
root: ['children'],
paragraph: ['children'],
heading: ['depth', 'children'],
blockquote: ['children'],
strong: ['children'],
emphasis: ['children'],
delete: ['children'],
tableRow: ['children'],
tableCell: ['children'],
text: ['value'],
inlineCode: ['value'],
inlineMath: ['value'],
math: ['value'],
code: ['lang', 'meta', 'value'],
link: ['url', 'title', 'children'],
image: ['url', 'title', 'alt'],
list: ['ordered', 'start', 'spread', 'delimiter', 'children'],
listItem: ['checked', 'spread', 'children'],
table: ['align', 'children'],
thematicBreak: [],
break: [],
citation: ['sourceId'],
extension: ['plugin', 'name', 'display', 'source'],
};
/**
* MDAST node kinds Astryx recognizes by name but deliberately does not
* support. Naming them makes a rejection actionable while keeping every
* diagnostic built from adapter-owned vocabulary only.
*/
const NAMED_UNSUPPORTED_TYPES: ReadonlySet<string> = new Set([
'html',
'yaml',
'toml',
'definition',
'footnote',
'footnoteDefinition',
'footnoteReference',
'imageReference',
'linkReference',
'containerDirective',
'leafDirective',
'textDirective',
'mdxjsEsm',
'mdxFlowExpression',
'mdxTextExpression',
'mdxJsxFlowElement',
'mdxJsxTextElement',
]);
/**
* VFile keys the profile knows about and refuses. Naming them makes the
* refusal actionable while keeping diagnostics free of plugin-chosen text.
*/
const NAMED_UNSUPPORTED_FILE_KEYS: ReadonlySet<string> = new Set([
'path',
'cwd',
'history',
'basename',
'dirname',
'extname',
'stem',
'stored',
'result',
'map',
'contents',
]);
/** The one reason reported when a plugin declares the document unsupported. */
const FAILED_BY_PLUGIN = 'the plugin reported the document as unsupported';
/**
* A closed rejection.
*
* Its reason is assembled only from this module's own constants, so it can
* never carry document source, plugin-authored text, or a plugin-chosen
* identifier — see `knownType` and `knownField`.
*/
class RemarkAdapterRejection extends Error {}
/**
* The reason for each rejection this module raised, keyed by the thrown
* object.
*
* A plugin that catches one of our rejections can reach the class through
* `error.constructor` and throw a forgery, and `message` is writable on any
* Error — so neither the class nor the message is evidence. Only a throw this
* registry recorded is trusted, and its reason is read from here.
*/
const adapterReasons = new WeakMap<RemarkAdapterRejection, string>();
/**
* Sticky failure state for the run currently on the stack.
*
* Every rejection this module raises is recorded here, not only on the throw:
* a plugin can wrap any adapter call in `try`/`catch` — a prohibited file
* read, a write, a `delete`, a processor access — and carry on as if it had
* not happened. The run must still fail, so the verdict lives somewhere the
* plugin cannot reach or rewrite.
*
* Runs never overlap: the adapter is synchronous and rejects anything
* asynchronous, so a single module-level slot is the whole story.
*/
let activeRun: RunState | null = null;
interface RunState {
failed: boolean;
reason: string | null;
}
function createRunState(): RunState {
return {failed: false, reason: null};
}
function reject(reason: string): never {
if (activeRun != null && !activeRun.failed) {
activeRun.failed = true;
activeRun.reason = reason;
}
const rejection = new RemarkAdapterRejection(reason);
adapterReasons.set(rejection, reason);
throw rejection;
}
/**
* Runs `work` with `state` as the sticky failure target, restoring whatever
* was active before.
*/
function withRunState<Result>(state: RunState, work: () => Result): Result {
const previous = activeRun;
activeRun = state;
try {
return work();
} finally {
activeRun = previous;
}
}
/**
* Reports whether a value is thenable and, if it is, attaches a handler.
*
* An already-rejected promise with no handler becomes an unhandled rejection:
* it ends a Node SSR process by default, and its reason came from the plugin,
* so it would print document text the diagnostics work hard to keep out. The
* value is refused either way; attaching a handler only makes the refusal
* quiet.
*
* `then` is read exactly once. It may be a hostile getter — reading it can
* throw, or trip a guard of its own — so this never reads it a second time to
* re-ask the same question.
*/
function defuseThenable(value: unknown): boolean {
if (
(typeof value !== 'object' && typeof value !== 'function') ||
value === null
) {
return false;
}
let then: unknown;
try {
then = (value as {then?: unknown}).then;
} catch {
// A `then` accessor that throws is a thenable-shaped hostile value.
return true;
}
if (typeof then !== 'function') {
return false;
}
try {
then.call(
value,
() => {},
() => {},
);
} catch {
// A `then` that throws when called is refused all the same.
}
return true;
}
/** Echoes a node type only when it is adapter-owned vocabulary. */
function knownType(type: unknown): string {
return typeof type === 'string' &&
(Object.prototype.hasOwnProperty.call(FIELDS_BY_TYPE, type) ||
NAMED_UNSUPPORTED_TYPES.has(type))
? type
: 'unknown';
}
/**
* Echoes a file key only when it is a name this module already documents —
* the supported surface, or an unsupported VFile key the profile explicitly
* names. A plugin-chosen key is never echoed.
*/
function knownFileKey(property: string | symbol): string {
const key = typeof property === 'symbol' ? 'unknown' : property;
return FILE_SURFACE.has(key) || NAMED_UNSUPPORTED_FILE_KEYS.has(key)
? key
: 'unknown';
}
/** Echoes a field name only when it is adapter-owned vocabulary. */
function knownField(type: string, field: string): string {
return field === 'position' ||
field === 'data' ||
field === 'type' ||
RAW_MARKUP_DATA_KEYS.includes(field) ||
(FIELDS_BY_TYPE[type]?.includes(field) ?? false)
? field
: 'unknown';
}
function isPlainObject(value: unknown): value is UnknownRecord {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
return false;
}
const prototype = Object.getPrototypeOf(value);
return prototype === Object.prototype || prototype === null;
}
const POINT_FIELDS: ReadonlyArray<string> = ['line', 'column', 'offset'];
const POSITION_FIELDS: ReadonlyArray<string> = ['start', 'end'];
function samePoint(left: unknown, right: unknown): boolean {
if (!isPlainObject(left) || !isPlainObject(right)) {
return false;
}
for (const point of [left, right]) {
for (const field of Object.keys(point)) {
if (!POINT_FIELDS.includes(field)) {
return false;
}
}
}
return POINT_FIELDS.every(field => left[field] === right[field]);
}
/**
* Exact provenance equality: every line, column, and offset on both points.
* Comparing offsets alone would let a shifted line or column through, and the
* adapter must never quietly restore Core's position over a changed one.
*/
function samePosition(left: unknown, right: unknown): boolean {
if (left === undefined || right === undefined) {
return left === right;
}
if (!isPlainObject(left) || !isPlainObject(right)) {
return false;
}
for (const position of [left, right]) {
for (const field of Object.keys(position)) {
if (!POSITION_FIELDS.includes(field)) {
return false;
}
}
}
return samePoint(left.start, right.start) && samePoint(left.end, right.end);
}
function copyPoint(point: unknown): MarkdownRemarkPoint | undefined {
if (!isPlainObject(point)) {
return undefined;
}
const copy: MarkdownRemarkPoint = {};
if (typeof point.line === 'number') {
copy.line = point.line;
}
if (typeof point.column === 'number') {
copy.column = point.column;
}
if (typeof point.offset === 'number') {
copy.offset = point.offset;
}
return copy;
}
function copyPosition(position: unknown): MarkdownRemarkPosition | undefined {
if (!isPlainObject(position)) {
return undefined;
}
const start = copyPoint(position.start);
const end = copyPoint(position.end);
return start == null || end == null ? undefined : {start, end};
}
function copyData<Value>(value: Value): Value {
if (Array.isArray(value)) {
const copy: unknown[] = [];
for (const entry of value) {
copy.push(copyData(entry));
}
return copy as Value;
}
if (isPlainObject(value)) {
const copy: UnknownRecord = {};
for (const [key, nested] of Object.entries(value)) {
copy[key] = copyData(nested);
}
return copy as Value;
}
return value;
}
function sameJsonValue(left: unknown, right: unknown): boolean {
if (left === right) {
return true;
}
if (Array.isArray(left) && Array.isArray(right)) {
return (
left.length === right.length &&
left.every((item, index) => sameJsonValue(item, right[index]))
);
}
if (isPlainObject(left) && isPlainObject(right)) {
const leftKeys = Object.keys(left);
const rightKeys = Object.keys(right);
return (
leftKeys.length === rightKeys.length &&
leftKeys.every(
key => key in right && sameJsonValue(left[key], right[key]),
)
);
}
return false;
}
/* ------------------------------------------------------------------ *
* Canonical tree → fresh mutable Remark tree
* ------------------------------------------------------------------ */
interface OriginIndex {
readonly all: Set<UnknownRecord>;
}
function createOriginIndex(): OriginIndex {
return {all: new Set()};
}
function indexOrigin(node: UnknownRecord, index: OriginIndex): void {
index.all.add(node);
}
function toRemarkChildren(
children: unknown,
index: OriginIndex,
): UnknownRecord[] {
return Array.isArray(children)
? children.map(child => toRemarkNode(child as UnknownRecord, index))
: [];
}
function toRemarkNode(node: UnknownRecord, index: OriginIndex): UnknownRecord {
indexOrigin(node, index);
const copy: UnknownRecord = {type: node.type};
switch (node.type) {
case 'root':
case 'paragraph':
case 'blockquote':
case 'strong':
case 'emphasis':
case 'delete':
case 'tableRow':
case 'tableCell':
case 'listItem':
if (node.type === 'listItem' && typeof node.checked === 'boolean') {
copy.checked = node.checked;
}
copy.children = toRemarkChildren(node.children, index);
break;
case 'heading':
copy.depth = node.depth;
copy.children = toRemarkChildren(node.children, index);
break;
case 'text':
case 'inlineCode':
case 'inlineMath':
case 'math':
copy.value = node.value;
break;
case 'code':
copy.lang = node.lang ?? null;
// Astryx stores an absent info string as no key; MDAST spells it
// `null`. Both conversions translate, so authored fence metadata —
// which the semantic-fence helper reads — survives the round trip.
copy.meta = node.meta ?? null;
copy.value = node.value;
break;
case 'link':
copy.url = node.url;
copy.title = null;
copy.children = toRemarkChildren(node.children, index);
break;
case 'image':
copy.url = node.url;
copy.title = null;
copy.alt = node.alt;
break;
case 'list':
copy.ordered = node.ordered;
if (node.start !== undefined) {
copy.start = node.start;
}
if (node.spread !== undefined) {
copy.spread = node.spread;
}
if (node.delimiter !== undefined) {
copy.delimiter = node.delimiter;
}
copy.children = toRemarkChildren(node.children, index);
break;
case 'table':
copy.align = Array.isArray(node.align) ? [...node.align] : [];
copy.children = toRemarkChildren(node.children, index);
break;
case 'citation':
copy.sourceId = node.sourceId;
break;
case 'extension':
copy.plugin = node.plugin;
copy.name = node.name;
copy.display = node.display;
if (node.source !== undefined) {
copy.source = node.source;
}
break;
default:
break;
}
if (node.data !== undefined) {
copy.data = copyData(node.data);
}
const position = copyPosition(node.position);
if (position != null) {
copy.position = position;
}
// Enumerable so an immutable-style plugin that spreads a node keeps its
// provenance; symbol-keyed so it never reaches JSON, data, or rendering.
Object.defineProperty(copy, REMARK_ORIGIN, {
configurable: false,
enumerable: true,
value: node,
writable: false,
});
return copy;
}
/* ------------------------------------------------------------------ *
* Mutated Remark tree → validated canonical tree
* ------------------------------------------------------------------ */
interface BackContext {
readonly index: OriginIndex;
readonly used: Set<UnknownRecord>;
}
/**
* Resolves the canonical node a transformed node came from.
*
* Provenance travels on an enumerable symbol the adapter puts on every copy,
* so a plugin that spreads a node (`{...node}`) keeps it. Nothing else counts:
* a node that merely looks like a source node — same position, same
* discriminants, rebuilt from scratch — is a forgery, not provenance, and is
* rejected rather than matched.
*/
function resolveOrigin(
node: UnknownRecord,
type: string,
context: BackContext,
): UnknownRecord | null {
const linked = (node as {[REMARK_ORIGIN]?: unknown})[REMARK_ORIGIN];
if (linked === undefined) {
return null;
}
if (!isPlainObject(linked) || !context.index.all.has(linked)) {
reject(`a "${knownType(type)}" node carries forged provenance`);
}
if (linked.type !== type) {
reject(`a source "${knownType(linked.type)}" node cannot be retyped`);
}
if (context.used.has(linked)) {
reject(`a source "${knownType(type)}" node cannot be duplicated`);
}
context.used.add(linked);
return linked;
}
function assertKnownFields(type: string, node: UnknownRecord): void {
const allowed = FIELDS_BY_TYPE[type];
for (const key of Object.keys(node)) {
if (
key !== 'type' &&
key !== 'position' &&
key !== 'data' &&
!allowed.includes(key)
) {
reject(
`a "${knownType(type)}" node cannot carry the unsupported field "${knownField(type, key)}"`,
);
}
}
}
function convertData(
type: string,
value: unknown,
): MarkdownAstDataValue | undefined {
if (value === undefined) {
return undefined;
}
if (isPlainObject(value)) {
for (const key of RAW_MARKUP_DATA_KEYS) {
if (key in value) {
reject(
`a "${knownType(type)}" node cannot carry the raw-markup data channel "${key}"`,
);
}
}
}
if (!isMarkdownPluginData(value)) {
reject(
`a "${knownType(type)}" node's data must be finite JSON-like values`,
);
}
return copyData(value);
}
function requireString(type: string, field: string, value: unknown): string {
if (typeof value !== 'string') {
reject(
`a "${knownType(type)}" node requires a string "${knownField(type, field)}"`,
);
}
return value;
}
function requireAbsentText(type: string, field: string, value: unknown): void {
if (value !== undefined && value !== null && value !== '') {
reject(
`a "${knownType(type)}" node's "${knownField(type, field)}" has no Astryx representation`,
);
}
}
function assertPlacement(
type: string,
node: UnknownRecord,
parentType: string | null,
insideLink: boolean,
): void {
if (parentType == null) {
return;
}
if (type === 'root') {
reject('a document can only contain one root');
}
const display = type === 'extension' ? node.display : undefined;
const phrasing = PHRASING_TYPES.has(type) || display === 'inline';
const block = BLOCK_TYPES.has(type) || display === 'block';
if (
(PHRASING_PARENTS.has(parentType) && !phrasing) ||
(BLOCK_PARENTS.has(parentType) && !block) ||
(parentType === 'list' && type !== 'listItem') ||
(parentType === 'table' && type !== 'tableRow') ||
(parentType === 'tableRow' && type !== 'tableCell')
) {
reject(
`a "${knownType(type)}" node cannot be a child of a "${knownType(parentType)}" node`,
);
}
if (insideLink && type === 'link') {
reject('a link cannot be nested inside another link');
}
}
function sameCanonicalFields(
origin: UnknownRecord,
fields: UnknownRecord,
): boolean {
// Canonical nodes may carry explicitly undefined optional keys; an absent
// key and an undefined key mean the same thing.
const originKeys = Object.keys(origin).filter(
key => key !== 'type' && origin[key] !== undefined,
);
const fieldKeys = Object.keys(fields).filter(
key => fields[key] !== undefined,
);
if (originKeys.length !== fieldKeys.length) {
return false;
}
for (const key of fieldKeys) {
const next = fields[key];
const previous = origin[key];
if (next === previous) {
continue;
}
if (Array.isArray(next) && Array.isArray(previous)) {
if (
next.length !== previous.length ||
next.some((item, position) => item !== previous[position])
) {
return false;
}
continue;
}
if (!sameJsonValue(next, previous)) {
return false;
}
}
return true;
}
function buildCanonicalNode(
type: string,
fields: UnknownRecord,
origin: UnknownRecord | null,
): UnknownRecord {
if (origin != null && sameCanonicalFields(origin, fields)) {
return origin;
}
const built: UnknownRecord = {type, ...fields};
if (origin != null) {
// Carries Core's own enumerable symbol markers (source-heading identity)
// onto the replacement so Core still recognizes the node it authored.
for (const marker of Object.getOwnPropertySymbols(origin)) {
if (Object.prototype.propertyIsEnumerable.call(origin, marker)) {
Object.defineProperty(built, marker, {
configurable: false,
enumerable: true,
value: (origin as UnknownRecord & {[key: symbol]: unknown})[marker],
writable: false,
});
}
}
}
return built;
}
function fromRemarkChildren(
children: unknown,
type: string,
insideLink: boolean,
context: BackContext,
): UnknownRecord[] {
if (!Array.isArray(children)) {
reject(`a "${knownType(type)}" node requires a children array`);
}
return children.map(child =>
fromRemarkNode(child, type, insideLink || type === 'link', context),
);
}
function fromRemarkNode(
value: unknown,
parentType: string | null,
insideLink: boolean,
context: BackContext,
): UnknownRecord {
if (!isPlainObject(value)) {
reject('every transformed node must be a plain object');
}
const type = value.type;
if (typeof type !== 'string') {
reject('every transformed node requires a string type');
}
if (type === 'html') {
reject('raw HTML has no Astryx representation');
}
if (!(type in FIELDS_BY_TYPE)) {
reject(
`the node type "${knownType(type)}" is outside the supported MDAST subset`,
);
}
assertKnownFields(type, value);
assertPlacement(type, value, parentType, insideLink);
const origin = resolveOrigin(value, type, context);
if (origin == null) {
if (value.position !== undefined) {
reject(`a new "${knownType(type)}" node cannot carry a source position`);
}
} else if (!samePosition(value.position, origin.position)) {
// Covers a removed, rebuilt, offset-shifted, and line/column-shifted
// position alike. Core's position is never restored over a changed one.
reject(
`a source "${knownType(type)}" node's position must stay exactly as Core authored it`,
);
}
const fields: UnknownRecord = {};
switch (type) {
case 'root':
case 'paragraph':
case 'blockquote':
case 'strong':
case 'emphasis':
case 'delete':
case 'tableRow':
case 'tableCell':
fields.children = fromRemarkChildren(
value.children,
type,
insideLink,
context,
);
break;
case 'heading': {
const depth = value.depth;
if (
typeof depth !== 'number' ||
!Number.isInteger(depth) ||
depth < 1 ||
depth > 6
) {
reject('a heading requires a depth between 1 and 6');
}
if (origin != null && origin.depth !== depth) {
reject("a source heading's depth cannot change");
}
fields.depth = depth;
fields.children = fromRemarkChildren(
value.children,
type,
insideLink,
context,
);
break;
}
case 'listItem': {
const checked = value.checked;
if (checked !== undefined && checked !== null) {
if (typeof checked !== 'boolean') {
reject('a list item requires a boolean "checked" value');
}
fields.checked = checked;
}
if (value.spread === true) {
reject('a loose list item has no Astryx representation');
}
fields.children = fromRemarkChildren(
value.children,
type,
insideLink,
context,
);
break;
}
case 'text':
case 'inlineCode':
case 'inlineMath':
case 'math':
fields.value = requireString(type, 'value', value.value);
break;
case 'code': {
const lang = value.lang;
if (lang !== undefined && lang !== null && typeof lang !== 'string') {
reject('a code node requires a string or null "lang"');
}
const meta = value.meta;
if (meta !== undefined && meta !== null && typeof meta !== 'string') {
reject('a code node requires a string or null "meta"');
}
fields.lang = lang ?? null;
if (meta != null && meta !== '') {
fields.meta = meta;
}
fields.value = requireString(type, 'value', value.value);
break;
}
case 'link': {
const url = requireString(type, 'url', value.url);
if (!isSafeMarkdownParserUrl(url)) {
reject('a link destination was rejected by the navigation owner');
}
requireAbsentText(type, 'title', value.title);
fields.url = url;
fields.children = fromRemarkChildren(
value.children,
type,
insideLink,
context,
);
break;
}
case 'image': {
const url = requireString(type, 'url', value.url);
if (!isSafeMarkdownParserUrl(url)) {
reject('an image source was rejected by the resource owner');
}
requireAbsentText(type, 'title', value.title);
if (typeof value.alt !== 'string') {
reject('an image requires its text alternative');
}
fields.url = url;
fields.alt = value.alt;
break;
}
case 'list': {
if (typeof value.ordered !== 'boolean') {
reject('a list requires a boolean "ordered" value');
}
fields.ordered = value.ordered;
const start = value.start;
if (start !== undefined && start !== null) {
if (typeof start !== 'number' || !Number.isFinite(start)) {
reject('a list requires a finite "start" value');
}
fields.start = start;
}
if (typeof value.spread === 'boolean') {
fields.spread = value.spread;
}
const delimiter = value.delimiter;
if (delimiter !== undefined) {
if (delimiter !== '.' && delimiter !== ')') {
reject('a list requires a "." or ")" delimiter');
}
fields.delimiter = delimiter;
}
fields.children = fromRemarkChildren(
value.children,
type,
insideLink,
context,
);
break;
}
case 'table': {
const align = value.align;
if (
!Array.isArray(align) ||
!align.every(
entry =>
entry === null ||
entry === 'left' ||
entry === 'center' ||
entry === 'right',
)
) {
reject('a table requires normalized alignment values');
}
fields.align = [...align];
fields.children = fromRemarkChildren(
value.children,
type,
insideLink,
context,
);
break;
}
case 'thematicBreak':
case 'break':
break;
case 'citation':
case 'extension': {
// Astryx owns these outright: the adapter can show one to a plugin but
// never lets one be authored or edited, so every field must come back
// exactly as it went out.
const unchanged =
origin != null &&
sameJsonValue(value.data, origin.data) &&
(type === 'citation'
? value.sourceId === origin.sourceId
: value.plugin === origin.plugin &&
value.name === origin.name &&
value.display === origin.display &&
value.source === origin.source);
if (!unchanged) {
reject(
`an Astryx "${knownType(type)}" node cannot be authored or changed here`,
);
}
// Equality across every owned field proves the node round-tripped, so
// the canonical node itself stays in place.
return origin;
}
default:
reject(
`the node type "${knownType(type)}" is outside the supported MDAST subset`,
);
}
const data = convertData(type, value.data);
if (data !== undefined) {
fields.data = data;
}
if (origin != null && origin.position !== undefined) {
fields.position = origin.position;
}
const node = buildCanonicalNode(type, fields, origin);
if (type === 'table' && node !== origin) {
const rows = fields.children as UnknownRecord[];
const width = (rows[0]?.children as unknown[] | undefined)?.length ?? 0;
if (
rows.some(
row => (row.children as unknown[] | undefined)?.length !== width,
)
) {
reject('a transformed table cannot have ragged rows');
}
}
return node;
}
/* ------------------------------------------------------------------ *
* Constrained file and processor guard
* ------------------------------------------------------------------ */
function createMessage(
reason: string | Error,
place: unknown,
ruleId: string | undefined,
): MarkdownRemarkMessage {
const text = reason instanceof Error ? reason.message : reason;
return {
reason: text,
fatal: false,
place: place ?? null,
ruleId: ruleId ?? null,
toString() {
return text;
},
};
}
/**
* The documented surface of the constrained file. Everything else — `path`,
* `cwd`, `history`, `basename`, `dirname`, `extname`, `stem`, `stored`, and
* any other key — is unsupported: the adapter has no filesystem, no processor,
* and no run history to answer with.
*/
const FILE_SURFACE: ReadonlySet<string> = new Set([
'value',
'data',
'messages',
'message',
'fail',
'toString',
]);
/**
* Adapter-owned data for one invocation.
*
* It lives here rather than on the file the plugin holds, because everything
* the plugin can reach it can also rewrite — a plugin must not be able to
* fake a `fatal` message or hide one it caused. The failure verdict itself
* belongs to the run (`RunState`), which every rejection records.
*/
interface FileState {
readonly data: UnknownRecord;
}
function createConstrainedFile(source: string): {
readonly file: MarkdownRemarkFile;
readonly state: FileState;
} {
const messages: MarkdownRemarkMessage[] = [];
const state: FileState = {data: {}};
const target: MarkdownRemarkFile = {
get value() {
return source;
},
get data() {
return state.data;
},
get messages() {
return messages;
},
message(reason, place, ruleId) {
const message = createMessage(reason, place, ruleId);
messages.push(message);
return message;
},
fail(reason, place, ruleId) {
const message = createMessage(reason, place, ruleId);
message.fatal = true;
messages.push(message);
// `reject` records the verdict in run state, so a plugin that catches
// this and carries on has still declared the document unsupported and
// the run cannot succeed behind its back.
reject(FAILED_BY_PLUGIN);
},
toString() {
return source;
},
};
// Fails closed on every unsupported read and on every write. Returning
// `undefined` for `file.cwd` would let a plugin silently take a path that
// depends on a capability this profile does not have.
/* eslint-disable @typescript-eslint/promise-function-async -- these are
Proxy traps, not async work; the adapter is synchronous throughout. */
const file = new Proxy(target, {
get(_target, property, receiver) {
if (typeof property === 'symbol') {
// JS protocol (inspection, iteration, `instanceof`), not VFile
// surface. Answering `undefined` here cannot mislead a plugin.
return Reflect.get(target, property, receiver) as unknown;
}
if (!FILE_SURFACE.has(property)) {
reject(`the file has no "${knownFileKey(property)}" in this profile`);
}
return Reflect.get(target, property, receiver) as unknown;
},
set(_target, property) {
reject(
`the file's "${knownFileKey(property)}" cannot be assigned in this profile`,
);
},
defineProperty(_target, property) {
reject(
`the file's "${knownFileKey(property)}" cannot be assigned in this profile`,
);
},
deleteProperty(_target, property) {
reject(
`the file's "${knownFileKey(property)}" cannot be assigned in this profile`,
);
},
// Truthfully answers "no such capability" so a plugin that feature-detects
// can take its own graceful path instead of being rejected.
has(_target, property) {
return typeof property === 'symbol' || FILE_SURFACE.has(property);
},
ownKeys() {
return [...FILE_SURFACE];
},
getOwnPropertyDescriptor(_target, property) {
return typeof property !== 'symbol' && !FILE_SURFACE.has(property)
? undefined
: Reflect.getOwnPropertyDescriptor(target, property);
},
});
/* eslint-enable @typescript-eslint/promise-function-async */
return {file, state};
}
/**
* Stands in for Unified's processor. Any access fails closed, so parser,
* compiler, and cross-run `data()` registration cannot be mistaken for
* supported behavior.
*/
const PROCESSOR_ACCESS = 'processor registration is outside the adapter';
const processorGuard: unknown = new Proxy(Object.freeze({}), {
get() {
reject(PROCESSOR_ACCESS);
},
set() {
reject(PROCESSOR_ACCESS);
},
defineProperty() {
reject(PROCESSOR_ACCESS);
},
deleteProperty() {
reject(PROCESSOR_ACCESS);
},
apply() {
reject(PROCESSOR_ACCESS);
},
has() {
// Truthful: this stand-in offers no processor capability at all.
return false;
},
ownKeys() {
return [];
},
});
/* ------------------------------------------------------------------ *
* Public adapter
* ------------------------------------------------------------------ */
/**
* The one reason reported for a failed run.
*
* A rejection's reason is built from this module's own vocabulary, so it is
* safe to report. Anything a plugin authored — a thrown error's message, a
* `file.fail()` reason, a `file.message()` diagnostic — is not: the plugin
* read the document, so its text may quote it. Those stay on the file, which
* only the plugin sees.
*/
function describeFailure(error: unknown): string {
const reason =
error instanceof RemarkAdapterRejection
? adapterReasons.get(error)
: undefined;
return reason ?? 'the plugin threw an error';
}
/**
* Adapt one synchronous transform-only Remark plugin to a Markdown transform.
*
* The adapted plugin receives a fresh mutable copy of the canonical document
* and an isolated constrained file. Every returned or mutated tree round-trips
* through the supported MDAST subset before it becomes observable; anything
* unsupported — a parser or compiler plugin, asynchronous work, processor
* state, raw HTML, an unsupported node, a forged position, or unrepresentable
* metadata — keeps the last valid document and reports one diagnostic.
*
* Compatibility is per plugin and proven by fixtures, never inferred from a
* package name.
*
* @example
* ```
* import {createMarkdownPlugin} from '@astryxdesign/core/Markdown';
* import {createMarkdownRemarkTransform} from '@astryxdesign/core/Markdown/remark';
*
* const shouting = createMarkdownPlugin({
* name: 'shouting-headings',
* apiVersion: 1,
* transform: createMarkdownRemarkTransform(remarkShoutingHeadings),
* });
* ```
*/
export function createMarkdownRemarkTransform<
Settings extends ReadonlyArray<unknown> = readonly [],
>(
plugin: MarkdownRemarkPlugin<Settings>,
...settings: Settings
): MarkdownTransform<never>;
export function createMarkdownRemarkTransform<
Settings extends ReadonlyArray<unknown> = readonly [],
>(
plugin: MarkdownRemarkCompatiblePlugin<Settings>,
...settings: Settings
): MarkdownTransform<never>;
export function createMarkdownRemarkTransform(
plugin: MarkdownRemarkCompatiblePlugin<ReadonlyArray<unknown>>,
...settings: ReadonlyArray<unknown>
): MarkdownTransform<never> {
if (typeof plugin !== 'function') {
throw new TypeError('Markdown Remark adapter: plugin must be a function');
}
let attached = false;
let transformer: MarkdownRemarkTransformer | null = null;
let attachFailure: string | null = null;
const attach = (): void => {
attached = true;
// The attacher can touch the processor guard and catch the rejection, so
// it gets its own sticky state; a swallowed capability access is still a
// failed attach.
const attachState = createRunState();
withRunState(attachState, () => {
try {
const created = (
plugin as (this: unknown, ...args: ReadonlyArray<unknown>) => unknown
).apply(processorGuard, settings as unknown as unknown[]);
// Defuse before any verdict: an attacher that both tripped a guard
// and returned a rejected promise must not leave that promise
// unhandled just because the guard is reported instead.
const attacherIsAsync = defuseThenable(created);
if (attachState.failed) {
reject(attachState.reason ?? FAILED_BY_PLUGIN);
}
if (attacherIsAsync) {
reject('an asynchronous plugin is outside the adapter');
}
if (typeof created !== 'function') {
attachFailure =
'only a transform-only plugin returning one synchronous transformer is supported';
return;
}
if (created.length >= 3) {
attachFailure =
'a callback-style (asynchronous) transformer is outside the adapter';
return;
}
transformer = created as MarkdownRemarkTransformer;
} catch (error) {
attachFailure = describeFailure(error);
}
});
if (attachState.failed && attachFailure == null) {
attachFailure = attachState.reason;
transformer = null;
}
};
return (
document: MarkdownAstRoot<MarkdownAstExtensionNode>,
context: MarkdownTransformContext,
): MarkdownAstRoot<MarkdownAstExtensionNode> => {
if (!attached) {
attach();
}
const runner = transformer;
if (runner == null) {
context.report(`Remark adapter: ${attachFailure ?? 'the plugin failed'}`);
return document;
}
const index = createOriginIndex();
const {file, state} = createConstrainedFile(context.source);
const run = createRunState();
return withRunState(run, () => {
try {
const tree = toRemarkNode(
document as unknown as UnknownRecord,
index,
) as unknown as MarkdownRemarkRoot;
const returned = runner(tree, file);
// Defuse first, whatever else is wrong. A transformer that both
// swallowed a guard refusal and returned a rejected promise still
// gets that promise handled — the sticky verdict decides only what
// is *reported*, never whether the promise is left dangling.
const returnedIsAsync = defuseThenable(returned);
if (run.failed) {
// The plugin tripped a guard — a prohibited file key, a processor
// access, its own fail() — and swallowed the rejection. The verdict
// stands, and its original reason is the one reported.
reject(run.reason ?? FAILED_BY_PLUGIN);
}
if (returnedIsAsync) {
reject('an asynchronous transformer is outside the adapter');
}
const output = returned ?? tree;
if (!isMarkdownPluginData(state.data)) {
reject('file data must be finite JSON-like values');
}
const back: BackContext = {index, used: new Set()};
const root = fromRemarkNode(output, null, false, back);
if (root.type !== 'root') {
reject('a transformer must return the document root');
}
const children = root.children as UnknownRecord[];
if (
context.display === 'inline' &&
(children.length !== 1 || children[0]?.type !== 'paragraph')
) {
reject(
'an inline document must stay one paragraph of phrasing content',
);
}
if (run.failed) {
// Last word before the output becomes observable. A guard can fire
// after the earlier check — a hostile `then` accessor, a getter on
// a returned node — and a refusal the plugin caught must never end
// with its output accepted.
reject(run.reason ?? FAILED_BY_PLUGIN);
}
return root as unknown as MarkdownAstRoot<MarkdownAstExtensionNode>;
} catch (error) {
// Exactly one report per failed run, and never a second for the
// plugin's own messages — see `describeFailure`. The first recorded
// rejection outranks a later error, so swallowing one and throwing
// something friendlier cannot change what is reported.
context.report(
`Remark adapter: ${run.reason ?? describeFailure(error)}`,
);
return document;
}
});
};
}