mdrefine 0.2.0-rc.2 → 0.2.0

package/dist/core/directives.js

@@ -1,5 +1,16 @@
 import { walk } from "../syntax/walk.js";
 import { range } from "../syntax/parse.js";
+/** The directive that an HTML node's value holds, if it is one. */
+export function directive(value) {
+    const match = /^<!--\s*mdtools-(disable-next-line|disable|enable)(?:\s+([^]*?))?\s*-->$/.exec(value.trim());
+    if (!match)
+        return undefined;
+    const names = match[2]
+        ?.trim()
+        .split(/[\s,]+/)
+        .filter(Boolean) ?? ["*"];
+    return { kind: match[1], rules: new Set(names.length ? names : ["*"]) };
+}
 /** Directives are recognized only in parsed HTML comments, never in code examples. */
 export function suppressions(document) {
     // Directives can only appear in HTML comments containing this prefix.
@@ -8,23 +19,24 @@ export function suppressions(document) {
     const intervals = [];
     const active = new Map();
     walk(document.tree, "html", (node) => {
-        const match = /^<!--\s*mdtools-(disable-next-line|disable|enable)(?:\s+([^]*?))?\s*-->$/.exec(node.value.trim());
-        if (!match)
+        const found = directive(node.value);
+        if (!found)
             return;
-        const names = match[2]
-            ?.trim()
-            .split(/[\s,]+/)
-            .filter(Boolean) ?? ["*"];
-        const rules = new Set(names.length ? names : ["*"]);
+        const { rules } = found;
         const [start, end] = range(node);
-        if (match[1] === "disable-next-line") {
-            const next = document.source.indexOf("\n", end);
-            if (next < 0)
+        if (found.kind === "disable-next-line") {
+            // The line after the directive's own, whichever of CommonMark's line endings ends each.
+            const lineBreak = /\r\n|\r|\n/g;
+            lineBreak.lastIndex = end;
+            const first = lineBreak.exec(document.source);
+            if (!first)
                 return;
-            const last = document.source.indexOf("\n", next + 1);
-            intervals.push({ start: next + 1, end: last < 0 ? document.source.length : last, rules });
+            const next = first.index + first[0].length;
+            lineBreak.lastIndex = next;
+            const last = lineBreak.exec(document.source);
+            intervals.push({ start: next, end: last ? last.index : document.source.length, rules });
         }
-        else if (match[1] === "disable") {
+        else if (found.kind === "disable") {
             for (const rule of rules)
                 if (!active.has(rule))
                     active.set(rule, end);

package/dist/core/directives.js.map

@@ -1 +1 @@
-{"version":3,"file":"directives.js","sourceRoot":"","sources":["../../src/core/directives.ts"],"names":[],"mappings":"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","sourcesContent":["import { walk } from \"../syntax/walk.js\";\nimport type { Document, Finding } from \"./types.js\";\nimport { range } from \"../syntax/parse.js\";\n\n/** Directives are recognized only in parsed HTML comments, never in code examples. */\nexport function suppressions(document: Document): (rule: string, finding: Finding) => boolean {\n  // Directives can only appear in HTML comments containing this prefix.\n  if (!document.source.includes(\"mdtools-\")) return () => false;\n  const intervals: { start: number; end: number; rules: Set<string> }[] = [];\n  const active = new Map<string, number>();\n  walk(document.tree, \"html\", (node) => {\n    const match = /^<!--\\s*mdtools-(disable-next-line|disable|enable)(?:\\s+([^]*?))?\\s*-->$/.exec(\n      node.value.trim(),\n    );\n    if (!match) return;\n    const names = match[2]\n      ?.trim()\n      .split(/[\\s,]+/)\n      .filter(Boolean) ?? [\"*\"];\n    const rules = new Set(names.length ? names : [\"*\"]);\n    const [start, end] = range(node);\n    if (match[1] === \"disable-next-line\") {\n      const next = document.source.indexOf(\"\\n\", end);\n      if (next < 0) return;\n      const last = document.source.indexOf(\"\\n\", next + 1);\n      intervals.push({ start: next + 1, end: last < 0 ? document.source.length : last, rules });\n    } else if (match[1] === \"disable\") {\n      for (const rule of rules) if (!active.has(rule)) active.set(rule, end);\n    } else {\n      for (const rule of rules.has(\"*\") ? active.keys() : rules) {\n        const from = active.get(rule);\n        if (from !== undefined) intervals.push({ start: from, end: start, rules: new Set([rule]) });\n        active.delete(rule);\n      }\n    }\n  });\n  for (const [rule, start] of active)\n    intervals.push({ start, end: document.source.length, rules: new Set([rule]) });\n  return (rule, finding) =>\n    intervals.some((interval) => {\n      const start = finding.edit?.start ?? finding.start;\n      const end = finding.edit?.end ?? finding.end ?? finding.start;\n      return (\n        (interval.rules.has(\"*\") || interval.rules.has(rule)) &&\n        start <= interval.end &&\n        end >= interval.start\n      );\n    });\n}\n"]}
+{"version":3,"file":"directives.js","sourceRoot":"","sources":["../../src/core/directives.ts"],"names":[],"mappings":"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","sourcesContent":["import { walk } from \"../syntax/walk.js\";\nimport type { Document, Finding } from \"./types.js\";\nimport { range } from \"../syntax/parse.js\";\n\n/** A suppression directive and the rules it names, `*` for all of them. */\nexport interface Directive {\n  kind: \"disable-next-line\" | \"disable\" | \"enable\";\n  rules: Set<string>;\n}\n/** The directive that an HTML node's value holds, if it is one. */\nexport function directive(value: string): Directive | undefined {\n  const match = /^<!--\\s*mdtools-(disable-next-line|disable|enable)(?:\\s+([^]*?))?\\s*-->$/.exec(\n    value.trim(),\n  );\n  if (!match) return undefined;\n  const names = match[2]\n    ?.trim()\n    .split(/[\\s,]+/)\n    .filter(Boolean) ?? [\"*\"];\n  return { kind: match[1] as Directive[\"kind\"], rules: new Set(names.length ? names : [\"*\"]) };\n}\n/** Directives are recognized only in parsed HTML comments, never in code examples. */\nexport function suppressions(document: Document): (rule: string, finding: Finding) => boolean {\n  // Directives can only appear in HTML comments containing this prefix.\n  if (!document.source.includes(\"mdtools-\")) return () => false;\n  const intervals: { start: number; end: number; rules: Set<string> }[] = [];\n  const active = new Map<string, number>();\n  walk(document.tree, \"html\", (node) => {\n    const found = directive(node.value);\n    if (!found) return;\n    const { rules } = found;\n    const [start, end] = range(node);\n    if (found.kind === \"disable-next-line\") {\n      // The line after the directive's own, whichever of CommonMark's line endings ends each.\n      const lineBreak = /\\r\\n|\\r|\\n/g;\n      lineBreak.lastIndex = end;\n      const first = lineBreak.exec(document.source);\n      if (!first) return;\n      const next = first.index + first[0].length;\n      lineBreak.lastIndex = next;\n      const last = lineBreak.exec(document.source);\n      intervals.push({ start: next, end: last ? last.index : document.source.length, rules });\n    } else if (found.kind === \"disable\") {\n      for (const rule of rules) if (!active.has(rule)) active.set(rule, end);\n    } else {\n      for (const rule of rules.has(\"*\") ? active.keys() : rules) {\n        const from = active.get(rule);\n        if (from !== undefined) intervals.push({ start: from, end: start, rules: new Set([rule]) });\n        active.delete(rule);\n      }\n    }\n  });\n  for (const [rule, start] of active)\n    intervals.push({ start, end: document.source.length, rules: new Set([rule]) });\n  return (rule, finding) =>\n    intervals.some((interval) => {\n      const start = finding.edit?.start ?? finding.start;\n      const end = finding.edit?.end ?? finding.end ?? finding.start;\n      return (\n        (interval.rules.has(\"*\") || interval.rules.has(rule)) &&\n        start <= interval.end &&\n        end >= interval.start\n      );\n    });\n}\n"]}

package/dist/core/engine.d.ts

@@ -1,8 +1,46 @@
 import type { Diagnostic, Document, Edit, FormatResult, Plugin, ProcessOptions, Rule, Workspace } from "./types.js";
-export declare const builtInRules: Record<string, Rule>;
-export declare function ruleRegistry(plugins?: Plugin[]): Record<string, Rule>;
+/**
+ * The built-in rules by rule ID. The table and the rules in it are frozen, so
+ * that no caller can change what another one runs.
+ */
+export declare const builtInRules: Readonly<Record<string, Readonly<Rule>>>;
+/**
+ * The prefix of the engine's own diagnostics, such as `engine/rule-error`. A
+ * plugin of this name could report findings that pass for the engine's, which
+ * concern the whole document and make the CLI exit with code 2.
+ */
+export declare const reservedPluginName = "engine";
+/**
+ * The built-in rules and those of `plugins`, by rule ID, in a new table. A
+ * plugin name that is invalid, reserved, or used twice, a rule ID that exists
+ * already, and a plugin rule that does not have the shape of a `Rule` are
+ * errors that name them.
+ */
+export declare function ruleRegistry(plugins?: readonly Plugin[]): Record<string, Readonly<Rule>>;
+/**
+ * The diagnostics of the enabled rules for `source`, sorted by position. A rule
+ * that fails is skipped and reported as `engine/rule-error`. An invalid
+ * configuration, an unknown rule, invalid rule options, an invalid plugin, and
+ * an error that the workspace throws are thrown.
+ */
 export declare function lint(source: string, options?: ProcessOptions): Diagnostic[];
-export declare function applyEdits(source: string, edits: Edit[]): string;
-/** Compare semantic trees, with link identity supplied by the selected renderer's resolver. */
+/**
+ * `source` with `edits` applied, which are `{ start, end, text }` replacements
+ * at UTF-16 offsets into it. Repeats of one edit count once; an edit outside
+ * the source, or one that overlaps another, is an error.
+ */
+export declare function applyEdits(source: string, edits: readonly Edit[]): string;
+/**
+ * The meaning of a parsed document as text, which `format` compares before and
+ * after edits to refuse a change of meaning: its syntax tree without positions,
+ * with runs of whitespace in text alike, and with each link's destination as
+ * the workspace resolves it, so that two spellings of one target are the same.
+ */
 export declare function semanticFingerprint(document: Document, workspace?: Workspace): string;
+/**
+ * Format a document: apply the edits of the enabled style rules, in passes
+ * until nothing changes, leaving out the edits of a rule that would change the
+ * document's meaning. Byte order marks that it starts with stay in the output
+ * and are not part of what the rules see. Errors are thrown as by `lint`.
+ */
 export declare function format(source: string, options?: ProcessOptions): FormatResult;