@markii/core 0.2.0 → 0.3.0

package/dist/corpus.js

@@ -3,7 +3,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
  * The language-agnostic conformance corpus: `*.mk.md` inputs plus
- * expected-AST `*.json` siblings, living at the repo root (see DESIGN.md
+ * expected-AST `*.json` siblings, living at the repo root (see docs/spec.md
  * §13). This module is deliberately parser-agnostic — it only
  * loads/compares corpus data — so it's usable from any package's tests (or
  * a future non-JS implementation's tooling), not just `@markii/core`'s own

package/dist/frontmatter.d.ts

@@ -0,0 +1,50 @@
+import type { Root } from 'mdast';
+/**
+ * A document's leading YAML frontmatter block, as far as this package cares
+ * about it: the raw text between the `---` fences, plus the one
+ * format-defined key (`uses`) when it is written in one of the two simple
+ * list forms this module understands.
+ *
+ * `raw` is the block's exact source text, unparsed — a host that genuinely
+ * needs arbitrary YAML metadata (its own `title`, `tags`, ...) brings its own
+ * YAML parser and reads this string. `@markii/core` deliberately does not:
+ * see `readUses` below.
+ */
+export interface Frontmatter {
+    /** The raw YAML text between the `---` fences (no fences, no trailing newline). */
+    raw: string;
+    /**
+     * Pack names from a `uses:` list written in one of the two supported
+     * forms, or `undefined` when the key is absent, is written in any other
+     * shape, or contains anything that is not a plain name. An empty list
+     * (`uses: []`) is `[]` — "declared, and it names no packs" — which is
+     * distinguishable from `undefined` ("no usable declaration").
+     */
+    uses?: string[];
+}
+/**
+ * The document's leading YAML frontmatter, or `undefined` when it has none.
+ *
+ * Accepts either the source text or an already-parsed tree, so a caller that
+ * has parsed the document already (the common case for a renderer) pays no
+ * second parse. Recognition is the PARSER's, not this module's: frontmatter
+ * is whatever `parse` produced as a leading `yaml` node, so the accessor and
+ * the renderer can never disagree about whether a `---` block at the top of
+ * a file was metadata or a thematic break.
+ *
+ * Never throws — `uses` simply degrades to `undefined` for anything beyond
+ * the two list forms `readUses` documents. A tree that did not come from
+ * this package's `parse` (a host that transforms the AST, or hand-builds
+ * one) is treated the same way: a leading node that merely CLAIMS to be
+ * `yaml` without carrying string content is no frontmatter at all, rather
+ * than a `raw.split` on a number.
+ */
+export declare function extractFrontmatter(source: string | Root): Frontmatter | undefined;
+/**
+ * Convenience wrapper over `extractFrontmatter`: just the `uses` list, or
+ * `undefined` when the document has no frontmatter, no `uses:` key, or a
+ * `uses:` value outside the two supported list forms. `uses` semantics
+ * (surfacing "pack not installed" in a host's UI) live with the host — this
+ * is only the reader.
+ */
+export declare function extractFrontmatterUses(source: string | Root): string[] | undefined;

package/dist/frontmatter.js

@@ -0,0 +1,178 @@
+import { parse } from './parse.js';
+/**
+ * The one format-defined frontmatter key (docs/format.md, docs/packs.md), as
+ * a top-level `uses:` line: the key at column 0 (so a `uses:` nested under
+ * some other mapping is deliberately invisible to this reader), optional
+ * spacing, then whatever follows the colon on the same line.
+ */
+const USES_LINE = /^uses[ \t]*:(.*)$/;
+/** One block-sequence item line: `- name`, capturing its indent and value. */
+const LIST_ITEM_LINE = /^([ \t]*)-[ \t]+(.*)$/;
+/**
+ * What a pack name may look like once quotes are stripped. Intentionally
+ * narrow: alphanumerics, `-`, `_`, `.` only (docs/packs.md — a namespace is
+ * a plain word, joined to a component name with `-` or `_`). Anything else —
+ * whitespace, `:`, `#`, brackets, braces, commas, a stray quote — means the
+ * value is not the simple scalar this reader claims to understand, so the
+ * whole list degrades to `undefined` rather than being half-read.
+ *
+ * A name like `__proto__` or `constructor` passes, and that is deliberate:
+ * this reader returns STRINGS in an array, never object keys, so a
+ * prototype-flavored name is ordinary data here. The registry lookups that
+ * eventually consume such a name are themselves null-prototype and
+ * `Object.hasOwn`-guarded (`@markii/react`'s `registry.ts`), which is where
+ * that class of defense belongs — not in a name filter that would have to
+ * guess every hostile spelling.
+ */
+const PACK_NAME = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+/**
+ * Reads one flow-sequence or block-sequence item: trims it, strips ONE pair
+ * of matching surrounding quotes (`'a'` / `"a"` — YAML's two quoting styles,
+ * used here only to unwrap a name, never to interpret escapes), and returns
+ * it only if what remains is a plain pack name. Returns `undefined` for
+ * anything else, including an opening quote with no matching close.
+ */
+function readItem(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return undefined;
+    const quote = trimmed[0];
+    let value = trimmed;
+    if (quote === '"' || quote === "'") {
+        if (trimmed.length < 2 || !trimmed.endsWith(quote))
+            return undefined;
+        value = trimmed.slice(1, -1);
+    }
+    return PACK_NAME.test(value) ? value : undefined;
+}
+/** Maps `readItem` over every raw item, failing the WHOLE list if any item fails. */
+function readItems(rawItems) {
+    const values = [];
+    for (const rawItem of rawItems) {
+        const value = readItem(rawItem);
+        if (value === undefined)
+            return undefined;
+        values.push(value);
+    }
+    return values;
+}
+/**
+ * Reads the flow form — `uses: [a, b]` — from the text that follows the
+ * colon. The text must be exactly a bracketed sequence: a trailing comment
+ * (`uses: [a] # note`) or any other suffix is NOT this form and yields
+ * `undefined`, since recognizing it would mean tokenizing YAML rather than
+ * matching one fixed shape. `[]` yields the empty list.
+ */
+function readFlowSequence(text) {
+    if (!text.startsWith('[') || !text.endsWith(']'))
+        return undefined;
+    const inner = text.slice(1, -1).trim();
+    if (inner === '')
+        return [];
+    return readItems(inner.split(','));
+}
+/**
+ * Reads the block form — a bare `uses:` followed by `- name` lines — from
+ * the lines after the key. Items must be contiguous (the first line that is
+ * not an item ends the sequence, blank lines included) and share one indent,
+ * which is what keeps a differently-indented continuation of some richer
+ * YAML structure from being mistaken for a flat list. No items, or a
+ * ragged/uneven sequence, yields `undefined`.
+ */
+function readBlockSequence(lines, start) {
+    const rawItems = [];
+    let indent;
+    for (const line of lines.slice(start)) {
+        const match = LIST_ITEM_LINE.exec(line);
+        const [, lineIndent, item] = match ?? [];
+        if (lineIndent === undefined || item === undefined)
+            break;
+        if (indent === undefined)
+            indent = lineIndent;
+        else if (lineIndent !== indent)
+            return undefined;
+        rawItems.push(item);
+    }
+    return rawItems.length > 0 ? readItems(rawItems) : undefined;
+}
+/**
+ * The hand-rolled `uses:` reader — the whole reason `@markii/core` needs no
+ * YAML library, exactly as `@markii/bundle`'s `manifest.ts` needs no schema
+ * library. It recognizes TWO shapes and nothing else:
+ *
+ * ```yaml
+ * uses: [ana, gh]      # flow sequence
+ * uses:                # block sequence
+ *   - ana
+ *   - gh
+ * ```
+ *
+ * quotes and surrounding whitespace tolerated in both. Every other input —
+ * a `uses:` holding a scalar or a nested mapping, a duplicated `uses:` key,
+ * an indented (non-top-level) `uses:`, a value this reader cannot recognize,
+ * or frontmatter that is not valid YAML at all — returns `undefined`. It
+ * NEVER throws and never returns a partially-read list: `uses` is an
+ * informative hint (docs/packs.md — "this note uses pack `ana`, which is not
+ * installed"), so "I could not read this" and "there is nothing here" are
+ * the same, harmless answer, while a half-read list would produce a wrong
+ * warning about packs the note never named.
+ */
+function readUses(raw) {
+    const lines = raw.split(/\r?\n/);
+    let keyIndex = -1;
+    let rest = '';
+    for (const [index, line] of lines.entries()) {
+        const [, value] = USES_LINE.exec(line) ?? [];
+        if (value === undefined)
+            continue;
+        // A second top-level `uses:` makes the document ambiguous (YAML itself
+        // rejects duplicate keys); refuse to guess which one was meant.
+        if (keyIndex !== -1)
+            return undefined;
+        keyIndex = index;
+        rest = value;
+    }
+    if (keyIndex === -1)
+        return undefined;
+    const inline = rest.trim();
+    return inline === ''
+        ? readBlockSequence(lines, keyIndex + 1)
+        : readFlowSequence(inline);
+}
+/**
+ * The document's leading YAML frontmatter, or `undefined` when it has none.
+ *
+ * Accepts either the source text or an already-parsed tree, so a caller that
+ * has parsed the document already (the common case for a renderer) pays no
+ * second parse. Recognition is the PARSER's, not this module's: frontmatter
+ * is whatever `parse` produced as a leading `yaml` node, so the accessor and
+ * the renderer can never disagree about whether a `---` block at the top of
+ * a file was metadata or a thematic break.
+ *
+ * Never throws — `uses` simply degrades to `undefined` for anything beyond
+ * the two list forms `readUses` documents. A tree that did not come from
+ * this package's `parse` (a host that transforms the AST, or hand-builds
+ * one) is treated the same way: a leading node that merely CLAIMS to be
+ * `yaml` without carrying string content is no frontmatter at all, rather
+ * than a `raw.split` on a number.
+ */
+export function extractFrontmatter(source) {
+    const tree = typeof source === 'string' ? parse(source) : source;
+    const first = tree.children[0];
+    if (first?.type !== 'yaml' || typeof first.value !== 'string') {
+        return undefined;
+    }
+    const raw = first.value;
+    const uses = readUses(raw);
+    return uses === undefined ? { raw } : { raw, uses };
+}
+/**
+ * Convenience wrapper over `extractFrontmatter`: just the `uses` list, or
+ * `undefined` when the document has no frontmatter, no `uses:` key, or a
+ * `uses:` value outside the two supported list forms. `uses` semantics
+ * (surfacing "pack not installed" in a host's UI) live with the host — this
+ * is only the reader.
+ */
+export function extractFrontmatterUses(source) {
+    return extractFrontmatter(source)?.uses;
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { parse } from './parse.js';
+export { extractFrontmatter, extractFrontmatterUses, type Frontmatter, } from './frontmatter.js';
 export { toHast, nodeToHast, isSafeUrl, type MarkNode } from './to-hast.js';
 export { extractScripts, isBareAttribute, isValidScriptName, parseMetaAttributes, type ScriptBlock, } from './scripts.js';

package/dist/index.js

@@ -5,5 +5,6 @@
 // via `@markii/react`) never has to reason about Node built-ins reachable from
 // its entry point.
 export { parse } from './parse.js';
+export { extractFrontmatter, extractFrontmatterUses, } from './frontmatter.js';
 export { toHast, nodeToHast, isSafeUrl } from './to-hast.js';
 export { extractScripts, isBareAttribute, isValidScriptName, parseMetaAttributes, } from './scripts.js';

package/dist/parse.d.ts

@@ -2,6 +2,7 @@ import type { Root } from 'mdast';
 /**
  * Parses Mark text into an mdast AST. CommonMark plus GitHub-Flavored
  * Markdown (`remark-gfm`: tables, task lists, strikethrough, autolinks) plus
+ * optional leading YAML frontmatter (`remark-frontmatter`) plus
  * the generic directive grammar (`remark-directive`) — nothing more. GFM and
  * directives are independent micromark syntax extensions (GFM extends the
  * table / list-item / inline grammar; directives add their own `:`/`::`/`:::`
@@ -13,5 +14,16 @@ import type { Root } from 'mdast';
  * and children; interpreting a name is the renderer's job; GFM nodes are
  * standard mdast — `table`, `listItem.checked`, `delete` — needing no
  * component/registry coupling at all).
+ *
+ * Frontmatter is the YAML preset only (`---` fences; the TOML `+++` form is
+ * deliberately not enabled) and, per micromark's frontmatter extension, is
+ * recognized ONLY as the very first construct of the document. Everywhere
+ * else `---` keeps its ordinary CommonMark meaning — a thematic break, or a
+ * setext heading underline — and an unterminated opening `---` degrades to
+ * exactly that too, never to an error (conformance fixtures 19-23). The
+ * resulting `yaml` node carries the raw block text and nothing more: this
+ * module does not interpret YAML, and `@markii/core` depends on no YAML
+ * library. `frontmatter.ts`'s hand-rolled accessor reads the one
+ * format-defined key (`uses`) off that raw text for the simple list forms.
  */
 export declare function parse(text: string): Root;

package/dist/parse.js

@@ -1,10 +1,12 @@
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkDirective from 'remark-directive';
+import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 /**
  * Parses Mark text into an mdast AST. CommonMark plus GitHub-Flavored
  * Markdown (`remark-gfm`: tables, task lists, strikethrough, autolinks) plus
+ * optional leading YAML frontmatter (`remark-frontmatter`) plus
  * the generic directive grammar (`remark-directive`) — nothing more. GFM and
  * directives are independent micromark syntax extensions (GFM extends the
  * table / list-item / inline grammar; directives add their own `:`/`::`/`:::`
@@ -16,10 +18,22 @@ import remarkGfm from 'remark-gfm';
  * and children; interpreting a name is the renderer's job; GFM nodes are
  * standard mdast — `table`, `listItem.checked`, `delete` — needing no
  * component/registry coupling at all).
+ *
+ * Frontmatter is the YAML preset only (`---` fences; the TOML `+++` form is
+ * deliberately not enabled) and, per micromark's frontmatter extension, is
+ * recognized ONLY as the very first construct of the document. Everywhere
+ * else `---` keeps its ordinary CommonMark meaning — a thematic break, or a
+ * setext heading underline — and an unterminated opening `---` degrades to
+ * exactly that too, never to an error (conformance fixtures 19-23). The
+ * resulting `yaml` node carries the raw block text and nothing more: this
+ * module does not interpret YAML, and `@markii/core` depends on no YAML
+ * library. `frontmatter.ts`'s hand-rolled accessor reads the one
+ * format-defined key (`uses`) off that raw text for the simple list forms.
  */
 export function parse(text) {
     const processor = unified()
         .use(remarkParse)
+        .use(remarkFrontmatter)
         .use(remarkDirective)
         .use(remarkGfm);
     return processor.parse(text);

package/dist/scripts.d.ts

@@ -1,6 +1,6 @@
 import type { Code, Root } from 'mdast';
 /**
- * Slice 1 of the scripting-usability layer (DESIGN.md §8): this module only
+ * Slice 1 of the scripting-usability layer (docs/scripting.md): this module only
  * *reads* script blocks out of an already-parsed AST — it never executes
  * anything, imports no Lua/wasmoon, and knows nothing about a value store.
  * A script block is, at the parse layer, an ordinary fenced code block (see
@@ -16,7 +16,7 @@ import type { Code, Root } from 'mdast';
  * ` ```lua {src=scripts/etl.lua name=stars}` ` with an empty body"); `code`
  * is still the fence's own body (empty for a `src=` reference).
  *
- * `publish`, when present, is always `true` — DESIGN.md §8: "**Publishing is
+ * `publish`, when present, is always `true` — docs/scripting.md: "**Publishing is
  * declarative**: the bare `publish` attribute on the script fence, no API to
  * call." "Bare" is load-bearing: it is set ONLY when the fence spells the
  * key with no `=value` at all (` ```lua {name=gh publish}` `, per
@@ -47,7 +47,7 @@ export interface ScriptBlock {
     position?: Code['position'];
 }
 /**
- * Whether `name` is a legal script `name` (DESIGN.md §8). Dots are
+ * Whether `name` is a legal script `name` (docs/scripting.md). Dots are
  * deliberately excluded from the charset — `data=`/`:value[]` read a dot in
  * a name as path traversal (`repo.stars` means "field `stars` of value
  * `repo`"), which would make a dotted *script* name unreachable from either
@@ -76,7 +76,7 @@ export declare function parseMetaAttributes(meta: string | null | undefined): Re
  * Whether `key` appears in `meta`'s `{...}` attribute group written
  * genuinely bare (`key` with no `=value` at all — none of the three value
  * alternatives in `ATTRIBUTE_TOKEN` matched). This is the ONE shared
- * mechanism for a bare-only boolean fence-meta attribute (DESIGN.md §8:
+ * mechanism for a bare-only boolean fence-meta attribute (docs/scripting.md:
  * "Boolean fence-meta attributes (`publish`, the reference renderer's
  * `open`) are bare-only: writing any value — `publish=true` no less than
  * `publish=false` — is not the boolean form and counts as absent. Fail
@@ -105,7 +105,7 @@ export declare function isBareAttribute(meta: string | null | undefined, key: st
  * Walks a parsed mdast `Root` and returns every script block, in document
  * order. A `code` node is a script iff its `meta` carries a `{...}`
  * attribute group with a non-empty `name` that also matches the script-name
- * charset (DESIGN.md §8, `isValidScriptName`); a code block with no meta,
+ * charset (docs/scripting.md, `isValidScriptName`); a code block with no meta,
  * meta with no `name`, or a `name` outside the charset (e.g. a dotted
  * `repo.stars`) is ordinary code and is skipped — same display-only
  * degradation either way, never an error and never a console message. Pure

package/dist/scripts.js

@@ -33,7 +33,7 @@ function findAttributeGroup(source) {
  */
 const ATTRIBUTE_TOKEN = /([A-Za-z_][\w-]*)(?:=(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
 /**
- * The full charset a script `name` may use (DESIGN.md §8). Deliberately NOT
+ * The full charset a script `name` may use (docs/scripting.md). Deliberately NOT
  * `g`-flagged: a `g`-flagged `RegExp` carries `lastIndex` state across
  * `.test()` calls (the exec-loop cursor from a previous match survives to
  * the next call on the same instance), which silently makes alternating
@@ -44,7 +44,7 @@ const ATTRIBUTE_TOKEN = /([A-Za-z_][\w-]*)(?:=(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
  */
 const SCRIPT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 /**
- * Whether `name` is a legal script `name` (DESIGN.md §8). Dots are
+ * Whether `name` is a legal script `name` (docs/scripting.md). Dots are
  * deliberately excluded from the charset — `data=`/`:value[]` read a dot in
  * a name as path traversal (`repo.stars` means "field `stars` of value
  * `repo`"), which would make a dotted *script* name unreachable from either
@@ -91,7 +91,7 @@ export function parseMetaAttributes(meta) {
  * Whether `key` appears in `meta`'s `{...}` attribute group written
  * genuinely bare (`key` with no `=value` at all — none of the three value
  * alternatives in `ATTRIBUTE_TOKEN` matched). This is the ONE shared
- * mechanism for a bare-only boolean fence-meta attribute (DESIGN.md §8:
+ * mechanism for a bare-only boolean fence-meta attribute (docs/scripting.md:
  * "Boolean fence-meta attributes (`publish`, the reference renderer's
  * `open`) are bare-only: writing any value — `publish=true` no less than
  * `publish=false` — is not the boolean form and counts as absent. Fail
@@ -138,7 +138,7 @@ export function isBareAttribute(meta, key) {
  * Walks a parsed mdast `Root` and returns every script block, in document
  * order. A `code` node is a script iff its `meta` carries a `{...}`
  * attribute group with a non-empty `name` that also matches the script-name
- * charset (DESIGN.md §8, `isValidScriptName`); a code block with no meta,
+ * charset (docs/scripting.md, `isValidScriptName`); a code block with no meta,
  * meta with no `name`, or a `name` outside the charset (e.g. a dotted
  * `repo.stars`) is ordinary code and is skipped — same display-only
  * degradation either way, never an error and never a console message. Pure

package/dist/to-hast.js

@@ -1,6 +1,7 @@
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkDirective from 'remark-directive';
+import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkRehype from 'remark-rehype';
 import { visit } from 'unist-util-visit';
@@ -156,10 +157,21 @@ function sanitizeUrls(tree) {
  * immutable-processor model (`.use()` returns a new processor) and keeps
  * each call's `.parse`/`.runSync` free of any state left over from a
  * previous call.
+ *
+ * The plugin list mirrors `parse.ts` exactly (frontmatter, directives, GFM),
+ * so what `parse` accepts and what this pipeline renders can never disagree
+ * about the grammar. Frontmatter needs no tagging step of its own: a leading
+ * `---` block becomes an mdast `yaml` node, and `mdast-util-to-hast`'s
+ * default handler for `yaml` is its `ignore` handler, so the block is
+ * DROPPED from the hast tree rather than leaking into the rendered document
+ * as text (pinned by `to-hast.test.ts`, since that drop is a rendering
+ * guarantee of the format, not an incidental upstream default). Metadata is
+ * read from the AST via `frontmatter.ts`, never rendered.
  */
 function createProcessor() {
     return unified()
         .use(remarkParse)
+        .use(remarkFrontmatter)
         .use(remarkDirective)
         .use(remarkGfm)
         .use(tagDirectiveNodes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic reference parser for Mark (.mk.md): CommonMark + directives to mdast, and mdast to a sanitized hast tree. Zero React dependency.",
   "keywords": [
     "markdown",
@@ -55,6 +55,7 @@
     "@types/mdast": "^4.0.4",
     "mdast-util-directive": "^3.1.0",
     "remark-directive": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",