@markii/core 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { parse } from './parse.js';
+export { parse, isRecognizedTextDirective } 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

@@ -4,7 +4,7 @@
 // subpath instead of here so a browser bundler consuming `@markii/core` (e.g.
 // via `@markii/react`) never has to reason about Node built-ins reachable from
 // its entry point.
-export { parse } from './parse.js';
+export { parse, isRecognizedTextDirective } 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

@@ -27,3 +27,22 @@ import type { Root } from 'mdast';
  * format-defined key (`uses`) off that raw text for the simple list forms.
  */
 export declare function parse(text: string): Root;
+/**
+ * The word-start DEMOTION rule (GitHub issue #43): whether an already
+ * tokenized text directive (`remark-directive` has already decided a run
+ * of text looks like `:name[...]`) should be KEPT as a directive or
+ * demoted back to plain text, per `demoteInvalidTextDirectives` above.
+ *
+ * This is scoped narrowly on purpose: it is not the rule that decides
+ * where a directive starts. That decision, and the colon-run and bracket
+ * grammar (how many colons open which directive form, what counts as a
+ * closing bracket), live entirely in `remark-directive` upstream and are
+ * not exposed here. This function only answers the one question this
+ * module adds on top: given a text directive `remark-directive` already
+ * found, does its name start with a letter, and does its colon sit at a
+ * word start? A third-party tokenizer (a Lezer grammar, for instance) that
+ * adopts this predicate gets parity on that one word-start rule and
+ * nothing more — it still needs its own colon-run and bracket handling to
+ * match `remark-directive`'s grammar.
+ */
+export declare function isRecognizedTextDirective(name: string, colonOffset: number, source: string): boolean;

package/dist/parse.js

@@ -94,7 +94,25 @@ function demoteInvalidTextDirectives(tree, source) {
 const STARTS_WITH_LETTER = /^[A-Za-z]/;
 /** ASCII letter-or-digit check for the character immediately before the colon. */
 const IS_WORD_CHARACTER = /[A-Za-z0-9]/;
-function isRecognizedTextDirective(name, colonOffset, source) {
+/**
+ * The word-start DEMOTION rule (GitHub issue #43): whether an already
+ * tokenized text directive (`remark-directive` has already decided a run
+ * of text looks like `:name[...]`) should be KEPT as a directive or
+ * demoted back to plain text, per `demoteInvalidTextDirectives` above.
+ *
+ * This is scoped narrowly on purpose: it is not the rule that decides
+ * where a directive starts. That decision, and the colon-run and bracket
+ * grammar (how many colons open which directive form, what counts as a
+ * closing bracket), live entirely in `remark-directive` upstream and are
+ * not exposed here. This function only answers the one question this
+ * module adds on top: given a text directive `remark-directive` already
+ * found, does its name start with a letter, and does its colon sit at a
+ * word start? A third-party tokenizer (a Lezer grammar, for instance) that
+ * adopts this predicate gets parity on that one word-start rule and
+ * nothing more — it still needs its own colon-run and bracket handling to
+ * match `remark-directive`'s grammar.
+ */
+export function isRecognizedTextDirective(name, colonOffset, source) {
     if (!STARTS_WITH_LETTER.test(name))
         return false;
     if (colonOffset === 0)

package/dist/scripts.d.ts

@@ -16,6 +16,22 @@ 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).
  *
+ * `permissions`, when present, is the script fence's own declared list of
+ * hostnames (` ```lua {name=gh permissions=api.github.com}` `, or
+ * comma-separated for more than one:
+ * `permissions=api.github.com,api.weather.com`). It is DISPLAY-ONLY: a
+ * grant prompt may show it next to the hosts a static scan actually finds
+ * ("declares: ..."), and a mismatch between the two is a diagnostics line,
+ * mirroring how a bundle manifest's `permissions.net` is already
+ * display-only against the same scan
+ * (`@markii/host`'s `script-requirements.ts`). It is NEVER an input to
+ * what gets granted — the literal-URL closure scan stays the only source
+ * of truth for that. Absent for a script with no `permissions` attribute
+ * at all; an empty comma-separated list (`permissions=`, or a value with
+ * no non-empty segment) is treated the same as absent, not as "declares
+ * nothing", since the format's script names are lowercase-hostname-shaped
+ * text with no way to write an empty entry on purpose.
+ *
  * `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
@@ -44,6 +60,8 @@ export interface ScriptBlock {
     src?: string;
     code: string;
     publish?: true;
+    /** See `permissions`'s doc comment above. Omitted, never an empty array, when the fence declares none. */
+    permissions?: string[];
     position?: Code['position'];
 }
 /**

package/dist/scripts.js

@@ -134,6 +134,25 @@ export function isBareAttribute(meta, key) {
     }
     return bare;
 }
+/**
+ * Splits a script fence's `permissions` attribute value into a list of
+ * declared hostnames: comma-separated, each segment trimmed and
+ * lowercased (matching `@markii/host`'s `manifestNetHosts` case-folding
+ * for the bundle-manifest equivalent, so the two declared-vs-scanned
+ * comparisons stay on the same footing), empty segments dropped. Returns
+ * `undefined` for a missing/empty attribute or one with no non-empty
+ * segment, per `ScriptBlock.permissions`'s doc comment — never an empty
+ * array.
+ */
+function parsePermissions(raw) {
+    if (!raw)
+        return undefined;
+    const hosts = raw
+        .split(',')
+        .map((host) => host.trim().toLowerCase())
+        .filter((host) => host.length > 0);
+    return hosts.length > 0 ? hosts : undefined;
+}
 /**
  * Walks a parsed mdast `Root` and returns every script block, in document
  * order. A `code` node is a script iff its `meta` carries a `{...}`
@@ -158,6 +177,9 @@ export function extractScripts(tree) {
         };
         if (attrs.src)
             block.src = attrs.src;
+        const permissions = parsePermissions(attrs.permissions);
+        if (permissions)
+            block.permissions = permissions;
         // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/core",
-  "version": "0.13.0",
+  "version": "0.14.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",