@markii/core 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { parse } from './parse.js';
-export { toHast, isSafeUrl } from './to-hast.js';
-export { extractScripts, parseMetaAttributes, type ScriptBlock, } from './scripts.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,5 @@
 // via `@markii/react`) never has to reason about Node built-ins reachable from
 // its entry point.
 export { parse } from './parse.js';
-export { toHast, isSafeUrl } from './to-hast.js';
-export { extractScripts, parseMetaAttributes, } from './scripts.js';
+export { toHast, nodeToHast, isSafeUrl } from './to-hast.js';
+export { extractScripts, isBareAttribute, isValidScriptName, parseMetaAttributes, } from './scripts.js';

package/dist/scripts.d.ts

@@ -15,14 +15,46 @@ import type { Code, Root } from 'mdast';
  * long-script file (§8: "the block becomes a one-line reference,
  * ` ```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
+ * 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
+ * `parseMetaAttributes`'s bare-key convention of yielding `''`). Any valued
+ * spelling — `publish=true`, `publish=yes`, `publish=1`, even `publish=false`
+ * or `publish=""` — is a DIFFERENT, undefined attribute, not the one the
+ * format specifies, and is silently ignored (the block simply does not
+ * publish), matching the format's "unrecognized input degrades, never
+ * throws" rule. This is deliberately fail-closed rather than lenient:
+ * publishing "writes beyond the note" (§8), so guessing at an unrecognized
+ * spelling risks writing to the shared vault when the author didn't mean to
+ * — silently NOT publishing is always the safe wrong answer, silently
+ * publishing never is. In particular `publish=false` must never be treated
+ * as an opt-out toggle that flips a default-on behavior; there is no such
+ * toggle, only the presence or absence of the one bare form.
+ *
+ * The field is only ever set when true, so a non-publishing block's shape is
+ * byte-identical to a `ScriptBlock` from before this field existed (no
+ * `publish: false` litter). Use `Object.hasOwn`/`'publish' in block` to test
+ * for absence, not falsiness.
  */
 export interface ScriptBlock {
     name: string;
     lang: string;
     src?: string;
     code: string;
+    publish?: true;
     position?: Code['position'];
 }
+/**
+ * Whether `name` is a legal script `name` (DESIGN.md §8). 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
+ * attribute. Fully anchored (`^`…`$`), so a trailing newline or any other
+ * stray character fails the match rather than being silently tolerated.
+ */
+export declare function isValidScriptName(name: string): boolean;
 /**
  * Parses a fence `meta` string's `{...}` attribute group into a flat
  * key/value map (bare `key` with no `=value` yields `''`). Returns an empty,
@@ -40,11 +72,43 @@ export interface ScriptBlock {
  * this purpose (see its `preserveCodeMeta` plugin).
  */
 export declare function parseMetaAttributes(meta: string | null | undefined): Record<string, string>;
+/**
+ * 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:
+ * "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
+ * closed: an unrecognized spelling must never enable behavior."). Used by
+ * `extractScripts` below for `publish`, and by `@markii/react`'s `PreElement`
+ * for `open` (see `ScriptBlock.publish`'s doc comment for why the
+ * bare/valued distinction matters).
+ *
+ * `parseMetaAttributes` collapses a bare key and an explicitly-empty quoted
+ * value (`key=""`) to the same `''` result in its flat map — the right
+ * choice for its general-purpose contract, but it erases exactly the
+ * distinction a bare-only attribute needs (`{publish}` must enable
+ * publishing; `{publish=""}` must not — and likewise `{open}` vs.
+ * `{open=""}`/`{open=true}`/`{open=false}`). So this walks the same token
+ * grammar directly instead of going through that already-flattened map.
+ * Like `parseMetaAttributes`, a key repeated in the group is "last
+ * occurrence wins" (the loop keeps overwriting `bare` for each match of
+ * `key`).
+ *
+ * Exported so a renderer (e.g. `@markii/react`) that defines its own
+ * bare-only boolean fence-meta attribute reuses this exact grammar instead
+ * of duplicating (and risking drift from) the bare/valued distinction here.
+ */
+export declare function isBareAttribute(meta: string | null | undefined, key: string): boolean;
 /**
  * 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`; a code block with no meta, or
- * meta with no `name`, is ordinary code and is skipped. Pure AST
- * inspection — no execution, no I/O, no knowledge of any value store.
+ * attribute group with a non-empty `name` that also matches the script-name
+ * charset (DESIGN.md §8, `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
+ * AST inspection — no execution, no I/O, no knowledge of any value store.
  */
 export declare function extractScripts(tree: Root): ScriptBlock[];

package/dist/scripts.js

@@ -32,6 +32,28 @@ function findAttributeGroup(source) {
  * `key="quoted value"`, or `key='quoted value'`. Whitespace-separated.
  */
 const ATTRIBUTE_TOKEN = /([A-Za-z_][\w-]*)(?:=(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
+/**
+ * The full charset a script `name` may use (DESIGN.md §8). 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
+ * calls report wrong results — a real bug class. `ATTRIBUTE_TOKEN` above
+ * needs `g` because it's driven with `.exec()` in a loop and resets
+ * `lastIndex` itself each time; `isValidScriptName` has no such loop, so it
+ * gets a plain, stateless pattern instead.
+ */
+const SCRIPT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * Whether `name` is a legal script `name` (DESIGN.md §8). 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
+ * attribute. Fully anchored (`^`…`$`), so a trailing newline or any other
+ * stray character fails the match rather than being silently tolerated.
+ */
+export function isValidScriptName(name) {
+    return SCRIPT_NAME_PATTERN.test(name);
+}
 /**
  * Parses a fence `meta` string's `{...}` attribute group into a flat
  * key/value map (bare `key` with no `=value` yields `''`). Returns an empty,
@@ -65,19 +87,69 @@ export function parseMetaAttributes(meta) {
     }
     return attrs;
 }
+/**
+ * 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:
+ * "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
+ * closed: an unrecognized spelling must never enable behavior."). Used by
+ * `extractScripts` below for `publish`, and by `@markii/react`'s `PreElement`
+ * for `open` (see `ScriptBlock.publish`'s doc comment for why the
+ * bare/valued distinction matters).
+ *
+ * `parseMetaAttributes` collapses a bare key and an explicitly-empty quoted
+ * value (`key=""`) to the same `''` result in its flat map — the right
+ * choice for its general-purpose contract, but it erases exactly the
+ * distinction a bare-only attribute needs (`{publish}` must enable
+ * publishing; `{publish=""}` must not — and likewise `{open}` vs.
+ * `{open=""}`/`{open=true}`/`{open=false}`). So this walks the same token
+ * grammar directly instead of going through that already-flattened map.
+ * Like `parseMetaAttributes`, a key repeated in the group is "last
+ * occurrence wins" (the loop keeps overwriting `bare` for each match of
+ * `key`).
+ *
+ * Exported so a renderer (e.g. `@markii/react`) that defines its own
+ * bare-only boolean fence-meta attribute reuses this exact grammar instead
+ * of duplicating (and risking drift from) the bare/valued distinction here.
+ */
+export function isBareAttribute(meta, key) {
+    if (!meta)
+        return false;
+    const group = findAttributeGroup(meta);
+    if (group === undefined)
+        return false;
+    ATTRIBUTE_TOKEN.lastIndex = 0;
+    let match;
+    let bare = false;
+    while ((match = ATTRIBUTE_TOKEN.exec(group)) !== null) {
+        if (match[1] !== key)
+            continue;
+        bare =
+            match[2] === undefined &&
+                match[3] === undefined &&
+                match[4] === undefined;
+    }
+    return bare;
+}
 /**
  * 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`; a code block with no meta, or
- * meta with no `name`, is ordinary code and is skipped. Pure AST
- * inspection — no execution, no I/O, no knowledge of any value store.
+ * attribute group with a non-empty `name` that also matches the script-name
+ * charset (DESIGN.md §8, `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
+ * AST inspection — no execution, no I/O, no knowledge of any value store.
  */
 export function extractScripts(tree) {
     const blocks = [];
     visit(tree, 'code', (node) => {
         const attrs = parseMetaAttributes(node.meta);
         const name = attrs.name;
-        if (!name)
+        if (!name || !isValidScriptName(name))
             return;
         const block = {
             name,
@@ -86,6 +158,13 @@ export function extractScripts(tree) {
         };
         if (attrs.src)
             block.src = attrs.src;
+        // Bare-only, per `ScriptBlock.publish`'s doc comment and
+        // `isBareAttribute`'s: a plain `attrs.publish === ''` check can't tell
+        // `{publish}` from `{publish=""}` (both flatten to `''`), so this asks
+        // the token grammar directly instead of trusting the flattened map.
+        if (isBareAttribute(node.meta, 'publish')) {
+            block.publish = true;
+        }
         if (node.position)
             block.position = node.position;
         blocks.push(block);

package/dist/to-hast.d.ts

@@ -1,3 +1,4 @@
+import type { RootContent } from 'mdast';
 import type { Root as HastRoot } from 'hast';
 /**
  * Modelled on react-markdown's `defaultUrlTransform`, though our allowlist
@@ -38,3 +39,41 @@ export declare function isSafeUrl(url: string): boolean;
  * script marker).
  */
 export declare function toHast(text: string): HastRoot;
+/**
+ * One mdast node as this package's `parse` produces it (a member of a
+ * `Root`'s `children` array — `mdast`'s own `RootContent` union). Re-exported
+ * under this package's naming so a consumer (e.g. `@markii/react`'s
+ * `renderMarkNode`) can type a "single already-parsed node" parameter without
+ * adding its own `@types/mdast` dependency — `@markii/core` already depends
+ * on it.
+ */
+export type MarkNode = RootContent;
+/**
+ * Converts a single already-parsed mdast node (as produced by this package's
+ * `parse`, e.g. one top-level child of its `Root`) to a sanitized hast tree,
+ * running the exact SAME pipeline as `toHast` — see `createProcessor` above,
+ * the one shared plugin-list source of truth — over a synthetic mdast `root`
+ * wrapping just this node. Directive tagging, code-meta preservation, and URL
+ * sanitizing (`sanitizeUrls`) all run identically to the whole-document path;
+ * the only difference is skipping `processor.parse` (there is no text to
+ * parse — `node` is already an AST) and wrapping in a throwaway root instead
+ * of using the document's own.
+ *
+ * Pure: `node` is deep-cloned (`structuredClone` — mdast nodes are plain
+ * JSON-safe data) before the pipeline runs, so the plugins' in-place
+ * `data.hName`/`data.hProperties` mutations never touch the caller's node.
+ *
+ * Hardened: because this entry point takes an AST rather than text, the
+ * clone is also stripped of every node's `data` — the caller-controllable
+ * hast-override channel — before the pipeline runs, so a hand-built or
+ * transformed node cannot dictate the emitted tag/attributes (e.g. a
+ * `data.hName: 'script'` injection). See `stripHastOverrides`.
+ *
+ * Never throws, matching `toHast`'s and Architecture rule 3's
+ * never-throw-on-odd-input guarantee: an inline/text-level node at the root
+ * of the synthetic tree, a `code` node with malformed `meta`, or a
+ * container-directive subtree left over from an unclosed fence may all
+ * produce degraded hast (in the worst case, an empty root — `emptyHastRoot`),
+ * but the call itself cannot fail.
+ */
+export declare function nodeToHast(node: MarkNode): HastRoot;

package/dist/to-hast.js

@@ -146,6 +146,26 @@ function sanitizeUrls(tree) {
         }
     });
 }
+/**
+ * The ONE source of truth for the mdast->hast pipeline's plugin list, shared
+ * by `toHast` (whole-document) and `nodeToHast` (single-node) below —
+ * exactly one `.use()` chain exists in this module so the two entry points
+ * cannot drift apart on directive tagging, code-meta preservation, or the
+ * remark-rehype conversion itself. Building a fresh processor per call
+ * (rather than a shared module-level instance) matches `unified`'s own
+ * 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.
+ */
+function createProcessor() {
+    return unified()
+        .use(remarkParse)
+        .use(remarkDirective)
+        .use(remarkGfm)
+        .use(tagDirectiveNodes)
+        .use(preserveCodeMeta)
+        .use(remarkRehype);
+}
 /**
  * Converts Mark text straight to a sanitized hast tree: parse (mdast, with
  * directive + GFM syntax extensions) -> tag directive nodes + preserve
@@ -162,15 +182,96 @@ function sanitizeUrls(tree) {
  * script marker).
  */
 export function toHast(text) {
-    const processor = unified()
-        .use(remarkParse)
-        .use(remarkDirective)
-        .use(remarkGfm)
-        .use(tagDirectiveNodes)
-        .use(preserveCodeMeta)
-        .use(remarkRehype);
+    const processor = createProcessor();
     const mdastTree = processor.parse(text);
     const hastTree = processor.runSync(mdastTree);
     sanitizeUrls(hastTree);
     return hastTree;
 }
+/**
+ * Deletes `data` from every node in `tree`, in place.
+ *
+ * Security-relevant, and specific to the single-node path. mdast `data` is
+ * the documented channel for overriding hast output — `mdast-util-to-hast`
+ * reads `data.hName`, `data.hProperties`, and `data.hChildren` and will emit
+ * *any* tag with *any* attributes a node asks for. `toHast` can never be
+ * handed such a node: it takes TEXT and parses it itself, and
+ * `remark-parse`/`remark-directive`/`remark-gfm` never populate `data` on the
+ * nodes they produce. `nodeToHast` instead accepts an already-built AST from
+ * the caller, so without this step a node carrying
+ * `data.hName = 'script'` + `data.hProperties = { src: 'javascript:...' }`
+ * would convert to a real `<script src="javascript:...">` hast element —
+ * bypassing `sanitizeUrls` entirely, since that only guards `a[href]` and
+ * `img[src]`. Any host that transforms the AST between `parse` and rendering
+ * (or renders a node built from untrusted input) would inherit an injection
+ * path that the document path simply does not have.
+ *
+ * Deleting `data` WHOLESALE, rather than allowlisting away the three known
+ * `h*` keys, is the deliberate choice: it is fail-closed by construction (a
+ * future `mdast-util-to-hast` release that honors a fourth `data.h*` key
+ * cannot silently reopen this hole, whereas a hardcoded three-name denylist
+ * would), and it costs nothing in fidelity — since parser-produced nodes
+ * carry no `data` at all, stripping it reproduces exactly the shape the
+ * document path feeds the pipeline. The pipeline's own tagging
+ * (`tagDirectiveNodes`, `preserveCodeMeta`) runs AFTER this and repopulates
+ * `data` itself, so directives and code fences are unaffected.
+ */
+function stripHastOverrides(tree) {
+    visit(tree, (node) => {
+        if (node.data !== undefined)
+            delete node.data;
+    });
+}
+/**
+ * An empty hast root, returned by `nodeToHast` when the pipeline itself
+ * throws on odd input (Architecture rule 3's never-throw guarantee, extended
+ * to the single-node path) — degraded output, never an exception.
+ */
+function emptyHastRoot() {
+    return { type: 'root', children: [] };
+}
+/**
+ * Converts a single already-parsed mdast node (as produced by this package's
+ * `parse`, e.g. one top-level child of its `Root`) to a sanitized hast tree,
+ * running the exact SAME pipeline as `toHast` — see `createProcessor` above,
+ * the one shared plugin-list source of truth — over a synthetic mdast `root`
+ * wrapping just this node. Directive tagging, code-meta preservation, and URL
+ * sanitizing (`sanitizeUrls`) all run identically to the whole-document path;
+ * the only difference is skipping `processor.parse` (there is no text to
+ * parse — `node` is already an AST) and wrapping in a throwaway root instead
+ * of using the document's own.
+ *
+ * Pure: `node` is deep-cloned (`structuredClone` — mdast nodes are plain
+ * JSON-safe data) before the pipeline runs, so the plugins' in-place
+ * `data.hName`/`data.hProperties` mutations never touch the caller's node.
+ *
+ * Hardened: because this entry point takes an AST rather than text, the
+ * clone is also stripped of every node's `data` — the caller-controllable
+ * hast-override channel — before the pipeline runs, so a hand-built or
+ * transformed node cannot dictate the emitted tag/attributes (e.g. a
+ * `data.hName: 'script'` injection). See `stripHastOverrides`.
+ *
+ * Never throws, matching `toHast`'s and Architecture rule 3's
+ * never-throw-on-odd-input guarantee: an inline/text-level node at the root
+ * of the synthetic tree, a `code` node with malformed `meta`, or a
+ * container-directive subtree left over from an unclosed fence may all
+ * produce degraded hast (in the worst case, an empty root — `emptyHastRoot`),
+ * but the call itself cannot fail.
+ */
+export function nodeToHast(node) {
+    try {
+        const cloned = structuredClone(node);
+        const root = { type: 'root', children: [cloned] };
+        // Before the pipeline runs: drop any caller-supplied hast overrides
+        // (`data.hName`/`hProperties`/`hChildren`) so only this pipeline's own
+        // tagging can influence the hast output. See `stripHastOverrides`.
+        stripHastOverrides(root);
+        const processor = createProcessor();
+        const hastTree = processor.runSync(root);
+        sanitizeUrls(hastTree);
+        return hastTree;
+    }
+    catch {
+        return emptyHastRoot();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/core",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -51,6 +51,8 @@
     "corpus:regen": "node scripts/regen-corpus.ts"
   },
   "dependencies": {
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
     "mdast-util-directive": "^3.1.0",
     "remark-directive": "^4.0.0",
     "remark-gfm": "^4.0.1",
@@ -60,8 +62,6 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@types/hast": "^3.0.5",
-    "@types/mdast": "^4.0.4",
     "prettier": "^3.9.6"
   }
 }