mdrefine 0.2.0-rc.2 → 0.2.0

package/dist/core/types.d.ts

@@ -1,44 +1,105 @@
 import type { Root } from "mdast";
 import type { Extension as SyntaxExtension } from "micromark-util-types";
 import type { Extension as TreeExtension } from "mdast-util-from-markdown";
-import type { AnySchema } from "ajv";
+/** A dialect: the renderer whose Markdown syntax a document is read in. */
 export type Dialect = "commonmark" | "github" | "forgejo" | "gitea" | "obsidian";
-/** A dialect or one of its aliases, accepted wherever configuration names a dialect. */
+/**
+ * A dialect or one of its aliases, accepted wherever a dialect is named:
+ * `codeberg` is `forgejo`. Parsed documents and resolved configurations hold
+ * the dialect itself.
+ */
 export type DialectName = Dialect | "codeberg";
+/** How a rule's findings count: `off` disables the rule. */
 export type Severity = "off" | "warn" | "error";
-export type RuleSetting = Severity | [Severity, Record<string, unknown>];
+/**
+ * A rule's setting in a configuration: its severity, or a list of its severity
+ * and, optionally, its options, which the rule's `schema` checks.
+ */
+export type RuleSetting = Severity | readonly [Severity] | readonly [Severity, Readonly<Record<string, unknown>>];
+/**
+ * A JSON Schema of draft 7, the version that Ajv validates by default: `true`
+ * accepts every value, `false` none, and an object holds keywords such as
+ * `type` and `properties`.
+ */
+export type JsonSchema = boolean | JsonSchemaObject;
+/** A JSON Schema written as an object of keywords. */
+export interface JsonSchemaObject {
+    readonly [keyword: string]: unknown;
+}
+/** A replacement of part of a text. */
 export interface Edit {
+    /** Where the replaced text starts: an offset in UTF-16 code units, from 0. */
     start: number;
+    /** Where the replaced text ends, not included: an offset, not before `start`. */
     end: number;
+    /** The text that replaces it. */
     text: string;
 }
+/**
+ * What a rule reports. Offsets are integers into `document.source`, from 0 to
+ * its length, and `end` is not before `start`; a rule that returns anything
+ * else is skipped for the document and reported as `engine/rule-error`.
+ */
 export interface Finding {
+    /** What is wrong, in a sentence. */
     message: string;
+    /** Where the finding starts. */
     start: number;
+    /** Where it ends, not included; omitted for a finding at one position. */
     end?: number;
+    /** A style rule's correction, which `format` applies. Problem rules give none. */
     edit?: Edit;
 }
+/**
+ * A finding as `lint` and `format` report it. Its offsets, and those of its
+ * edit, count UTF-16 code units in the text given to them, byte order marks
+ * included, so that the edit applies to that text.
+ */
 export interface Diagnostic extends Finding {
+    /** The rule's ID, such as `style/wrap`, or `engine/…` for the engine's own diagnostics. */
     rule: string;
+    /** The severity that the configuration gives the rule. */
     severity: Exclude<Severity, "off">;
+    /** The line of `start`, counting from 1. */
     line: number;
+    /** The column of `start` in UTF-16 code units, counting from 1. */
     column: number;
 }
+/**
+ * A parsed document. `Document` is also the name of the browser's DOM type;
+ * a module that uses both can import this one under another name.
+ */
 export interface Document {
+    /** The text that was parsed, without the byte order marks it started with. */
     source: string;
+    /** The document's path, relative to the workspace root with forward slashes. */
     path: string;
+    /** The mdast syntax tree, whose positions are offsets into `source`. */
     tree: Root;
+    /** The dialect it was read in, never an alias. */
     dialect: Dialect;
 }
+/** Where a link leads, as `Workspace.resolve` finds it. */
 export interface LinkResolution {
     /**
+     * `resolved`: one file matches; `missing`: none does; `ambiguous`: several
+     * match and nothing decides between them; `directory`: the destination names
+     * a directory; `external`: a URL with a scheme, or one starting with `//`;
+     * `unavailable`: the destination cannot be judged from files.
      * `unreadable` means that the target could not be checked, because the
      * workspace could not read what it would have to; it is neither found nor
      * known to be missing.
      */
     status: "resolved" | "missing" | "ambiguous" | "external" | "unavailable" | "directory" | "unreadable";
+    /** The file found, as a path from the workspace root. */
     target?: string;
+    /** The part of the destination after `#`, decoded, or an empty string. */
     fragment?: string;
+    /**
+     * With status `resolved`: whether the target has the heading, block, or
+     * anchor that `fragment` names, by the rules of the dialect; `true` without
+     * a fragment.
+     */
     fragmentExists?: boolean;
     /**
      * What could not be read and limits the result. With status `unreadable` it
@@ -51,6 +112,12 @@ export interface LinkResolution {
      * for the part of an Obsidian vault that lies outside the workspace root.
      */
     unreadable?: string[];
+    /**
+     * With status `unreadable`: the symbolic link or junction inside the
+     * workspace through which the link's path leads to a place outside the
+     * workspace root, which bounds what the tool reads.
+     */
+    leavesRoot?: string;
     /**
      * With status `resolved` in the Obsidian dialect: the target's path as
      * Obsidian counts it, from the folder of the linking note's vault, when that
@@ -69,77 +136,189 @@ export interface LinkResolution {
      */
     outside?: string;
 }
+/**
+ * The files that links can reach, which `createWorkspace` builds. A host can
+ * implement it itself.
+ */
 export interface Workspace {
+    /**
+     * Where a link leads. `source` is the linking document's path, `destination`
+     * the destination as written, and `dialect` the linking document's dialect;
+     * `wiki` is true for an Obsidian wikilink or embed. An error that it throws
+     * stops `lint` and `format`.
+     */
     resolve(source: string, destination: string, dialect: Dialect, wiki?: boolean): LinkResolution;
-    /** Obsidian's strictLineBreaks setting; false prevents semantic-changing prose reflow. */
+    /**
+     * Obsidian's "Strict line breaks" setting of the vault, which is a property
+     * of the workspace: `true` when it is verified on. Obsidian notes are wrapped
+     * only then, because otherwise a single line break shows as a line break.
+     */
     strictLineBreaks?: boolean;
 }
+/** What a rule's `check` receives. */
 export interface RuleContext {
+    /** The parsed document, which the rule must not change. */
     document: Document;
-    options: Record<string, unknown>;
+    /** The rule's options from the configuration, checked against its `schema`; `{}` without. */
+    options: Readonly<Record<string, unknown>>;
+    /** The workspace that links resolve in, or undefined when the host gave none. */
     workspace?: Workspace;
 }
+/**
+ * A rule. `ruleRegistry`, and so `lint` and `format`, reject a plugin rule
+ * that does not have this shape, naming it.
+ */
 export interface Rule {
+    /** What the rule checks, in a sentence. */
     description: string;
+    /** `problem` only reports; `style` may propose edits, which `format` applies. */
     kind: "style" | "problem";
     /** Inline edits, then block layout, then document-wide whitespace. */
     phase?: "inline" | "block" | "document";
-    schema?: AnySchema;
+    /** Validates the rule's options; compiled once and reused for every document. */
+    schema?: JsonSchema;
+    /**
+     * The rule's findings for one document. A rule that throws is skipped for
+     * that document and reported as `engine/rule-error`.
+     */
     check(context: RuleContext): Finding[];
 }
+/** A plugin: rules, presets, and syntax, named with its `name` as a prefix. */
 export interface Plugin {
+    /**
+     * The prefix of its rules and presets: a lowercase identifier of letters,
+     * digits, and hyphens that starts with a letter, unique among the plugins of
+     * a run. `engine` is reserved for the engine's own diagnostics.
+     */
     name: string;
+    /** Rules by name; rule `x` of plugin `p` has the ID `p/x`. */
     rules?: Record<string, Rule>;
+    /** Presets by name; preset `x` of plugin `p` is extended as `p/x`. */
     presets?: Record<string, Config>;
+    /** A micromark syntax extension and the mdast extension that builds its nodes. */
     syntax?: {
         micromark: SyntaxExtension;
         mdast: TreeExtension;
     };
 }
+/** Settings for the documents that match one of `files`. */
 export interface Override {
-    files: string[];
-    dialect?: DialectName;
-    rules?: Record<string, RuleSetting>;
+    /** Glob patterns, matched against paths relative to the workspace root, with forward slashes. */
+    readonly files: readonly string[];
+    /** The dialect of the matching documents. */
+    readonly dialect?: DialectName;
+    /** Rule settings for the matching documents, applied after the configuration's own. */
+    readonly rules?: Readonly<Record<string, RuleSetting>>;
 }
+/** Files that links may lead to without being linted or formatted. */
 export interface ResolveOptions {
+    /** Files that `.gitignore` files exclude are link targets. Default: false. */
     gitIgnored?: boolean;
+    /** Files of nested Git repositories are link targets. Default: false. */
     nestedRepositories?: boolean;
 }
+/**
+ * A configuration, as a configuration file holds it. `configSchema` describes
+ * it, and `validateConfig` checks it.
+ */
 export interface Config {
-    resolve?: ResolveOptions;
-    extends?: string[];
+    /** The JSON Schema for editors; the tool ignores it. */
+    $schema?: string;
+    /** Files that links may lead to; see `ResolveOptions`. */
+    resolve?: Readonly<ResolveOptions>;
+    /**
+     * Presets to start from, in order: a preset name or a list of them. Without
+     * it, the configuration starts from `recommended`.
+     */
+    extends?: string | readonly string[];
     /**
      * The dialect documents are read in. When neither this setting, a preset, nor
      * a matching override names one, the caller's default dialect is assumed, and
      * `github` when the caller gives none.
      */
     dialect?: DialectName;
-    rules?: Record<string, RuleSetting>;
-    ignore?: string[];
-    overrides?: Override[];
-    plugins?: string[];
+    /** Rule settings by rule ID, applied after those of the presets. */
+    rules?: Readonly<Record<string, RuleSetting>>;
+    /** Glob patterns of documents that are never linted or formatted; they stay link targets. */
+    ignore?: readonly string[];
+    /** Settings for some documents, applied in order after the others. */
+    overrides?: readonly Override[];
+    /**
+     * Plugins to load, as files or package names. Only a configuration file
+     * loads them; the library takes plugin objects through its `plugins` option.
+     */
+    plugins?: readonly string[];
 }
+/** The settings in effect for one document, which `resolveConfig` returns. */
 export interface ResolvedConfig {
+    /** The `resolve` settings of the configuration and its presets. */
     resolve: ResolveOptions;
+    /** The dialect the document is read in, never an alias. */
     dialect: Dialect;
+    /** The setting of every rule that the configuration, its presets, or an override names. */
     rules: Record<string, RuleSetting>;
+    /** The `ignore` patterns of the configuration and its presets. */
     ignore: string[];
 }
-export interface ProcessOptions {
-    path?: string;
-    config?: Config;
-    plugins?: Plugin[];
-    workspace?: Workspace;
+/** What decides the configuration in effect for a document; see `resolveConfig`. */
+export interface ResolveConfigOptions {
+    /**
+     * The document's path, relative to the workspace root with forward slashes.
+     * It selects overrides and resolves links; `document.md` when omitted.
+     */
+    path?: string | undefined;
+    /** The configuration. Without it, the `recommended` preset applies. */
+    config?: Config | undefined;
+    /** Plugin objects, whose rules and presets the configuration can name. */
+    plugins?: readonly Plugin[] | undefined;
     /**
      * The dialect to assume when the configuration names none for the document;
      * `github` when omitted. A dialect named by the configuration, a preset, or a
-     * matching override takes precedence. The CLI passes `obsidian` when the
-     * workspace root is an Obsidian vault.
+     * matching override takes precedence. The CLI passes `obsidian` for a
+     * document inside an Obsidian vault, wherever the vault lies in the workspace.
+     */
+    defaultDialect?: DialectName | undefined;
+}
+/** The options of `lint` and `format`. */
+export interface ProcessOptions extends ResolveConfigOptions {
+    /** The files that links can reach. Without it, links are not checked or rewritten. */
+    workspace?: Workspace | undefined;
+    /**
+     * Parts of the source to lint or format, as half-open UTF-16 offsets into
+     * the text as given. Each range is widened to the complete blocks that it
+     * touches, such as paragraphs, headings, tables, and code blocks, also inside
+     * lists and block quotes, with their whole lines and the line breaks next to
+     * them, where blank lines between blocks are edited. `lint` then returns the
+     * diagnostics that start in those parts, and `format` applies only edits
+     * that lie wholly in them, so that the rest of the text stays as it is. The
+     * whole document is still parsed and checked. Omitted, the whole document is
+     * processed; an empty list processes nothing.
      */
-    defaultDialect?: DialectName;
+    ranges?: readonly SourceRange[] | undefined;
 }
+/** A part of a text, as half-open UTF-16 offsets. */
+export interface SourceRange {
+    /** Where the part starts. */
+    start: number;
+    /** Where it ends, not included. */
+    end: number;
+}
+/** What `format` returns. */
 export interface FormatResult {
+    /**
+     * The formatted text. It leaves out the edits of each rule that would change
+     * the document's meaning, reported as `engine/unsafe-format` where the
+     * meaning would first differ, and is the text as given when formatting did
+     * not settle.
+     */
     output: string;
+    /** Whether `output` differs from the text as given. */
     changed: boolean;
+    /** The findings that remain in `output`, and the engine's own diagnostics. */
     diagnostics: Diagnostic[];
+    /**
+     * With `ranges`: the parts of the output that formatting was limited to,
+     * each range widened to its blocks and moved by the edits applied in it.
+     */
+    scope?: SourceRange[];
 }

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Root } from \"mdast\";\nimport type { Extension as SyntaxExtension } from \"micromark-util-types\";\nimport type { Extension as TreeExtension } from \"mdast-util-from-markdown\";\nimport type { AnySchema } from \"ajv\";\n\nexport type Dialect = \"commonmark\" | \"github\" | \"forgejo\" | \"gitea\" | \"obsidian\";\n/** A dialect or one of its aliases, accepted wherever configuration names a dialect. */\nexport type DialectName = Dialect | \"codeberg\";\nexport type Severity = \"off\" | \"warn\" | \"error\";\nexport type RuleSetting = Severity | [Severity, Record<string, unknown>];\nexport interface Edit {\n  start: number;\n  end: number;\n  text: string;\n}\nexport interface Finding {\n  message: string;\n  start: number;\n  end?: number;\n  edit?: Edit;\n}\nexport interface Diagnostic extends Finding {\n  rule: string;\n  severity: Exclude<Severity, \"off\">;\n  line: number;\n  column: number;\n}\nexport interface Document {\n  source: string;\n  path: string;\n  tree: Root;\n  dialect: Dialect;\n}\nexport interface LinkResolution {\n  /**\n   * `unreadable` means that the target could not be checked, because the\n   * workspace could not read what it would have to; it is neither found nor\n   * known to be missing.\n   */\n  status:\n    \"resolved\" | \"missing\" | \"ambiguous\" | \"external\" | \"unavailable\" | \"directory\" | \"unreadable\";\n  target?: string;\n  fragment?: string;\n  fragmentExists?: boolean;\n  /**\n   * What could not be read and limits the result. With status `unreadable` it\n   * is the target file itself, when `target` is set and its content was needed\n   * to check the fragment, or else the directories that may hold the target.\n   * With status `resolved` the target was found among the readable files, by an\n   * Obsidian name search or in a place that Obsidian tries after one of these\n   * directories. They may hold another match, or the one Obsidian would choose,\n   * so the link must not be rewritten. An entry that starts with `..` stands\n   * for the part of an Obsidian vault that lies outside the workspace root.\n   */\n  unreadable?: string[];\n  /**\n   * With status `resolved` in the Obsidian dialect: the target's path as\n   * Obsidian counts it, from the folder of the linking note's vault, when that\n   * folder is not the workspace root and the path so differs from `target`.\n   */\n  rooted?: string;\n  /**\n   * The folder of the linking note's vault, relative to the workspace root, when\n   * an Obsidian link was resolved inside a vault that lies below the root. A\n   * path that Obsidian counts from the vault starts there, not at the root.\n   */\n  vault?: string;\n  /**\n   * With status `missing`: an existing file or folder that the link's path names\n   * outside the linking note's vault, where Obsidian does not look.\n   */\n  outside?: string;\n}\nexport interface Workspace {\n  resolve(source: string, destination: string, dialect: Dialect, wiki?: boolean): LinkResolution;\n  /** Obsidian's strictLineBreaks setting; false prevents semantic-changing prose reflow. */\n  strictLineBreaks?: boolean;\n}\nexport interface RuleContext {\n  document: Document;\n  options: Record<string, unknown>;\n  workspace?: Workspace;\n}\nexport interface Rule {\n  description: string;\n  kind: \"style\" | \"problem\";\n  /** Inline edits, then block layout, then document-wide whitespace. */\n  phase?: \"inline\" | \"block\" | \"document\";\n  schema?: AnySchema;\n  check(context: RuleContext): Finding[];\n}\nexport interface Plugin {\n  name: string;\n  rules?: Record<string, Rule>;\n  presets?: Record<string, Config>;\n  syntax?: { micromark: SyntaxExtension; mdast: TreeExtension };\n}\nexport interface Override {\n  files: string[];\n  dialect?: DialectName;\n  rules?: Record<string, RuleSetting>;\n}\nexport interface ResolveOptions {\n  gitIgnored?: boolean;\n  nestedRepositories?: boolean;\n}\nexport interface Config {\n  resolve?: ResolveOptions;\n  extends?: string[];\n  /**\n   * The dialect documents are read in. When neither this setting, a preset, nor\n   * a matching override names one, the caller's default dialect is assumed, and\n   * `github` when the caller gives none.\n   */\n  dialect?: DialectName;\n  rules?: Record<string, RuleSetting>;\n  ignore?: string[];\n  overrides?: Override[];\n  plugins?: string[];\n}\nexport interface ResolvedConfig {\n  resolve: ResolveOptions;\n  dialect: Dialect;\n  rules: Record<string, RuleSetting>;\n  ignore: string[];\n}\nexport interface ProcessOptions {\n  path?: string;\n  config?: Config;\n  plugins?: Plugin[];\n  workspace?: Workspace;\n  /**\n   * The dialect to assume when the configuration names none for the document;\n   * `github` when omitted. A dialect named by the configuration, a preset, or a\n   * matching override takes precedence. The CLI passes `obsidian` when the\n   * workspace root is an Obsidian vault.\n   */\n  defaultDialect?: DialectName;\n}\nexport interface FormatResult {\n  output: string;\n  changed: boolean;\n  diagnostics: Diagnostic[];\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Root } from \"mdast\";\nimport type { Extension as SyntaxExtension } from \"micromark-util-types\";\nimport type { Extension as TreeExtension } from \"mdast-util-from-markdown\";\n\n/** A dialect: the renderer whose Markdown syntax a document is read in. */\nexport type Dialect = \"commonmark\" | \"github\" | \"forgejo\" | \"gitea\" | \"obsidian\";\n/**\n * A dialect or one of its aliases, accepted wherever a dialect is named:\n * `codeberg` is `forgejo`. Parsed documents and resolved configurations hold\n * the dialect itself.\n */\nexport type DialectName = Dialect | \"codeberg\";\n/** How a rule's findings count: `off` disables the rule. */\nexport type Severity = \"off\" | \"warn\" | \"error\";\n/**\n * A rule's setting in a configuration: its severity, or a list of its severity\n * and, optionally, its options, which the rule's `schema` checks.\n */\nexport type RuleSetting =\n  Severity | readonly [Severity] | readonly [Severity, Readonly<Record<string, unknown>>];\n/**\n * A JSON Schema of draft 7, the version that Ajv validates by default: `true`\n * accepts every value, `false` none, and an object holds keywords such as\n * `type` and `properties`.\n */\nexport type JsonSchema = boolean | JsonSchemaObject;\n/** A JSON Schema written as an object of keywords. */\nexport interface JsonSchemaObject {\n  readonly [keyword: string]: unknown;\n}\n/** A replacement of part of a text. */\nexport interface Edit {\n  /** Where the replaced text starts: an offset in UTF-16 code units, from 0. */\n  start: number;\n  /** Where the replaced text ends, not included: an offset, not before `start`. */\n  end: number;\n  /** The text that replaces it. */\n  text: string;\n}\n/**\n * What a rule reports. Offsets are integers into `document.source`, from 0 to\n * its length, and `end` is not before `start`; a rule that returns anything\n * else is skipped for the document and reported as `engine/rule-error`.\n */\nexport interface Finding {\n  /** What is wrong, in a sentence. */\n  message: string;\n  /** Where the finding starts. */\n  start: number;\n  /** Where it ends, not included; omitted for a finding at one position. */\n  end?: number;\n  /** A style rule's correction, which `format` applies. Problem rules give none. */\n  edit?: Edit;\n}\n/**\n * A finding as `lint` and `format` report it. Its offsets, and those of its\n * edit, count UTF-16 code units in the text given to them, byte order marks\n * included, so that the edit applies to that text.\n */\nexport interface Diagnostic extends Finding {\n  /** The rule's ID, such as `style/wrap`, or `engine/…` for the engine's own diagnostics. */\n  rule: string;\n  /** The severity that the configuration gives the rule. */\n  severity: Exclude<Severity, \"off\">;\n  /** The line of `start`, counting from 1. */\n  line: number;\n  /** The column of `start` in UTF-16 code units, counting from 1. */\n  column: number;\n}\n/**\n * A parsed document. `Document` is also the name of the browser's DOM type;\n * a module that uses both can import this one under another name.\n */\nexport interface Document {\n  /** The text that was parsed, without the byte order marks it started with. */\n  source: string;\n  /** The document's path, relative to the workspace root with forward slashes. */\n  path: string;\n  /** The mdast syntax tree, whose positions are offsets into `source`. */\n  tree: Root;\n  /** The dialect it was read in, never an alias. */\n  dialect: Dialect;\n}\n/** Where a link leads, as `Workspace.resolve` finds it. */\nexport interface LinkResolution {\n  /**\n   * `resolved`: one file matches; `missing`: none does; `ambiguous`: several\n   * match and nothing decides between them; `directory`: the destination names\n   * a directory; `external`: a URL with a scheme, or one starting with `//`;\n   * `unavailable`: the destination cannot be judged from files.\n   * `unreadable` means that the target could not be checked, because the\n   * workspace could not read what it would have to; it is neither found nor\n   * known to be missing.\n   */\n  status:\n    \"resolved\" | \"missing\" | \"ambiguous\" | \"external\" | \"unavailable\" | \"directory\" | \"unreadable\";\n  /** The file found, as a path from the workspace root. */\n  target?: string;\n  /** The part of the destination after `#`, decoded, or an empty string. */\n  fragment?: string;\n  /**\n   * With status `resolved`: whether the target has the heading, block, or\n   * anchor that `fragment` names, by the rules of the dialect; `true` without\n   * a fragment.\n   */\n  fragmentExists?: boolean;\n  /**\n   * What could not be read and limits the result. With status `unreadable` it\n   * is the target file itself, when `target` is set and its content was needed\n   * to check the fragment, or else the directories that may hold the target.\n   * With status `resolved` the target was found among the readable files, by an\n   * Obsidian name search or in a place that Obsidian tries after one of these\n   * directories. They may hold another match, or the one Obsidian would choose,\n   * so the link must not be rewritten. An entry that starts with `..` stands\n   * for the part of an Obsidian vault that lies outside the workspace root.\n   */\n  unreadable?: string[];\n  /**\n   * With status `unreadable`: the symbolic link or junction inside the\n   * workspace through which the link's path leads to a place outside the\n   * workspace root, which bounds what the tool reads.\n   */\n  leavesRoot?: string;\n  /**\n   * With status `resolved` in the Obsidian dialect: the target's path as\n   * Obsidian counts it, from the folder of the linking note's vault, when that\n   * folder is not the workspace root and the path so differs from `target`.\n   */\n  rooted?: string;\n  /**\n   * The folder of the linking note's vault, relative to the workspace root, when\n   * an Obsidian link was resolved inside a vault that lies below the root. A\n   * path that Obsidian counts from the vault starts there, not at the root.\n   */\n  vault?: string;\n  /**\n   * With status `missing`: an existing file or folder that the link's path names\n   * outside the linking note's vault, where Obsidian does not look.\n   */\n  outside?: string;\n}\n/**\n * The files that links can reach, which `createWorkspace` builds. A host can\n * implement it itself.\n */\nexport interface Workspace {\n  /**\n   * Where a link leads. `source` is the linking document's path, `destination`\n   * the destination as written, and `dialect` the linking document's dialect;\n   * `wiki` is true for an Obsidian wikilink or embed. An error that it throws\n   * stops `lint` and `format`.\n   */\n  resolve(source: string, destination: string, dialect: Dialect, wiki?: boolean): LinkResolution;\n  /**\n   * Obsidian's \"Strict line breaks\" setting of the vault, which is a property\n   * of the workspace: `true` when it is verified on. Obsidian notes are wrapped\n   * only then, because otherwise a single line break shows as a line break.\n   */\n  strictLineBreaks?: boolean;\n}\n/** What a rule's `check` receives. */\nexport interface RuleContext {\n  /** The parsed document, which the rule must not change. */\n  document: Document;\n  /** The rule's options from the configuration, checked against its `schema`; `{}` without. */\n  options: Readonly<Record<string, unknown>>;\n  /** The workspace that links resolve in, or undefined when the host gave none. */\n  workspace?: Workspace;\n}\n/**\n * A rule. `ruleRegistry`, and so `lint` and `format`, reject a plugin rule\n * that does not have this shape, naming it.\n */\nexport interface Rule {\n  /** What the rule checks, in a sentence. */\n  description: string;\n  /** `problem` only reports; `style` may propose edits, which `format` applies. */\n  kind: \"style\" | \"problem\";\n  /** Inline edits, then block layout, then document-wide whitespace. */\n  phase?: \"inline\" | \"block\" | \"document\";\n  /** Validates the rule's options; compiled once and reused for every document. */\n  schema?: JsonSchema;\n  /**\n   * The rule's findings for one document. A rule that throws is skipped for\n   * that document and reported as `engine/rule-error`.\n   */\n  check(context: RuleContext): Finding[];\n}\n/** A plugin: rules, presets, and syntax, named with its `name` as a prefix. */\nexport interface Plugin {\n  /**\n   * The prefix of its rules and presets: a lowercase identifier of letters,\n   * digits, and hyphens that starts with a letter, unique among the plugins of\n   * a run. `engine` is reserved for the engine's own diagnostics.\n   */\n  name: string;\n  /** Rules by name; rule `x` of plugin `p` has the ID `p/x`. */\n  rules?: Record<string, Rule>;\n  /** Presets by name; preset `x` of plugin `p` is extended as `p/x`. */\n  presets?: Record<string, Config>;\n  /** A micromark syntax extension and the mdast extension that builds its nodes. */\n  syntax?: { micromark: SyntaxExtension; mdast: TreeExtension };\n}\n/** Settings for the documents that match one of `files`. */\nexport interface Override {\n  /** Glob patterns, matched against paths relative to the workspace root, with forward slashes. */\n  readonly files: readonly string[];\n  /** The dialect of the matching documents. */\n  readonly dialect?: DialectName;\n  /** Rule settings for the matching documents, applied after the configuration's own. */\n  readonly rules?: Readonly<Record<string, RuleSetting>>;\n}\n/** Files that links may lead to without being linted or formatted. */\nexport interface ResolveOptions {\n  /** Files that `.gitignore` files exclude are link targets. Default: false. */\n  gitIgnored?: boolean;\n  /** Files of nested Git repositories are link targets. Default: false. */\n  nestedRepositories?: boolean;\n}\n/**\n * A configuration, as a configuration file holds it. `configSchema` describes\n * it, and `validateConfig` checks it.\n */\nexport interface Config {\n  /** The JSON Schema for editors; the tool ignores it. */\n  $schema?: string;\n  /** Files that links may lead to; see `ResolveOptions`. */\n  resolve?: Readonly<ResolveOptions>;\n  /**\n   * Presets to start from, in order: a preset name or a list of them. Without\n   * it, the configuration starts from `recommended`.\n   */\n  extends?: string | readonly string[];\n  /**\n   * The dialect documents are read in. When neither this setting, a preset, nor\n   * a matching override names one, the caller's default dialect is assumed, and\n   * `github` when the caller gives none.\n   */\n  dialect?: DialectName;\n  /** Rule settings by rule ID, applied after those of the presets. */\n  rules?: Readonly<Record<string, RuleSetting>>;\n  /** Glob patterns of documents that are never linted or formatted; they stay link targets. */\n  ignore?: readonly string[];\n  /** Settings for some documents, applied in order after the others. */\n  overrides?: readonly Override[];\n  /**\n   * Plugins to load, as files or package names. Only a configuration file\n   * loads them; the library takes plugin objects through its `plugins` option.\n   */\n  plugins?: readonly string[];\n}\n/** The settings in effect for one document, which `resolveConfig` returns. */\nexport interface ResolvedConfig {\n  /** The `resolve` settings of the configuration and its presets. */\n  resolve: ResolveOptions;\n  /** The dialect the document is read in, never an alias. */\n  dialect: Dialect;\n  /** The setting of every rule that the configuration, its presets, or an override names. */\n  rules: Record<string, RuleSetting>;\n  /** The `ignore` patterns of the configuration and its presets. */\n  ignore: string[];\n}\n/** What decides the configuration in effect for a document; see `resolveConfig`. */\nexport interface ResolveConfigOptions {\n  /**\n   * The document's path, relative to the workspace root with forward slashes.\n   * It selects overrides and resolves links; `document.md` when omitted.\n   */\n  path?: string | undefined;\n  /** The configuration. Without it, the `recommended` preset applies. */\n  config?: Config | undefined;\n  /** Plugin objects, whose rules and presets the configuration can name. */\n  plugins?: readonly Plugin[] | undefined;\n  /**\n   * The dialect to assume when the configuration names none for the document;\n   * `github` when omitted. A dialect named by the configuration, a preset, or a\n   * matching override takes precedence. The CLI passes `obsidian` for a\n   * document inside an Obsidian vault, wherever the vault lies in the workspace.\n   */\n  defaultDialect?: DialectName | undefined;\n}\n/** The options of `lint` and `format`. */\nexport interface ProcessOptions extends ResolveConfigOptions {\n  /** The files that links can reach. Without it, links are not checked or rewritten. */\n  workspace?: Workspace | undefined;\n  /**\n   * Parts of the source to lint or format, as half-open UTF-16 offsets into\n   * the text as given. Each range is widened to the complete blocks that it\n   * touches, such as paragraphs, headings, tables, and code blocks, also inside\n   * lists and block quotes, with their whole lines and the line breaks next to\n   * them, where blank lines between blocks are edited. `lint` then returns the\n   * diagnostics that start in those parts, and `format` applies only edits\n   * that lie wholly in them, so that the rest of the text stays as it is. The\n   * whole document is still parsed and checked. Omitted, the whole document is\n   * processed; an empty list processes nothing.\n   */\n  ranges?: readonly SourceRange[] | undefined;\n}\n/** A part of a text, as half-open UTF-16 offsets. */\nexport interface SourceRange {\n  /** Where the part starts. */\n  start: number;\n  /** Where it ends, not included. */\n  end: number;\n}\n/** What `format` returns. */\nexport interface FormatResult {\n  /**\n   * The formatted text. It leaves out the edits of each rule that would change\n   * the document's meaning, reported as `engine/unsafe-format` where the\n   * meaning would first differ, and is the text as given when formatting did\n   * not settle.\n   */\n  output: string;\n  /** Whether `output` differs from the text as given. */\n  changed: boolean;\n  /** The findings that remain in `output`, and the engine's own diagnostics. */\n  diagnostics: Diagnostic[];\n  /**\n   * With `ranges`: the parts of the output that formatting was limited to,\n   * each range widened to its blocks and moved by the edits applied in it.\n   */\n  scope?: SourceRange[];\n}\n"]}

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { lint, format, applyEdits, semanticFingerprint, builtInRules, ruleRegist
 export { resolveConfig, validateConfig, configSchema, presets, dialects, dialectAliases, canonicalDialect, } from "./config/resolve.js";
 export { parse, range, textContent } from "./syntax/parse.js";
 export { createWorkspace } from "./workspace/index.js";
-export type { WorkspaceOptions, WorkspaceSource } from "./workspace/index.js";
+export type { LookupResult, WorkspaceOptions, WorkspaceSource } from "./workspace/index.js";
 export type * from "./core/types.js";
-export type { ObsidianLiteral } from "./syntax/obsidian.js";
+export type { ObsidianComment, ObsidianHighlight, WikiLink } from "./syntax/obsidian.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,MAAM,EACN,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,cAAc,EACd,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC","sourcesContent":["export {\n  lint,\n  format,\n  applyEdits,\n  semanticFingerprint,\n  builtInRules,\n  ruleRegistry,\n} from \"./core/engine.js\";\nexport {\n  resolveConfig,\n  validateConfig,\n  configSchema,\n  presets,\n  dialects,\n  dialectAliases,\n  canonicalDialect,\n} from \"./config/resolve.js\";\nexport { parse, range, textContent } from \"./syntax/parse.js\";\nexport { createWorkspace } from \"./workspace/index.js\";\nexport type { WorkspaceOptions, WorkspaceSource } from \"./workspace/index.js\";\nexport type * from \"./core/types.js\";\nexport type { ObsidianLiteral } from \"./syntax/obsidian.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,MAAM,EACN,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,cAAc,EACd,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC","sourcesContent":["export {\n  lint,\n  format,\n  applyEdits,\n  semanticFingerprint,\n  builtInRules,\n  ruleRegistry,\n} from \"./core/engine.js\";\nexport {\n  resolveConfig,\n  validateConfig,\n  configSchema,\n  presets,\n  dialects,\n  dialectAliases,\n  canonicalDialect,\n} from \"./config/resolve.js\";\nexport { parse, range, textContent } from \"./syntax/parse.js\";\nexport { createWorkspace } from \"./workspace/index.js\";\nexport type { LookupResult, WorkspaceOptions, WorkspaceSource } from \"./workspace/index.js\";\nexport type * from \"./core/types.js\";\nexport type { ObsidianComment, ObsidianHighlight, WikiLink } from \"./syntax/obsidian.js\";\n"]}

package/dist/node.d.ts

@@ -0,0 +1,3 @@
+export { discoverWorkspace } from "./workspace/discovery.js";
+export type { DiscoverOptions, WorkspaceDiscovery } from "./workspace/discovery.js";
+export type { Skipped } from "./workspace/files.js";

package/dist/node.js

@@ -0,0 +1,4 @@
+// `mdrefine/node`: what needs the filesystem, kept apart from the main entry,
+// which never touches it.
+export { discoverWorkspace } from "./workspace/discovery.js";
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0BAA0B;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC","sourcesContent":["// `mdrefine/node`: what needs the filesystem, kept apart from the main entry,\n// which never touches it.\nexport { discoverWorkspace } from \"./workspace/discovery.js\";\nexport type { DiscoverOptions, WorkspaceDiscovery } from \"./workspace/discovery.js\";\nexport type { Skipped } from \"./workspace/files.js\";\n"]}

package/dist/rules/blocks.d.ts

@@ -0,0 +1,34 @@
+import type { Heading, Nodes } from "mdast";
+import type { Document, Edit, Rule } from "../core/types.js";
+/**
+ * Whether a line added directly below `node`, at its own level, would become
+ * part of an HTML block or Obsidian comment that `node` ends with and that has
+ * no end marker. The parser lets such an HTML block run on through the blank
+ * lines of a list item or footnote, and through a final line ending, but a
+ * block quote ends it. An Obsidian comment runs on to the end of the document,
+ * whatever contains it.
+ */
+export declare function takesLines(node: Nodes): boolean;
+/**
+ * Whether a line ending added at the end of the document would change its
+ * last block. Besides the blocks of `takesLines`, the parser counts a last
+ * line of blank space in a code or math block that has no closing fence only
+ * when a line ending follows it.
+ */
+export declare function takesFinalLineEnding(document: Document): boolean;
+/**
+ * Whether `style/heading` writes headings of levels 1 and 2 underlined: with
+ * `setext`, or with `consistent` when the document's first heading is.
+ */
+export declare function underlinedHeadings(document: Document, style: unknown): boolean;
+/**
+ * The edit that writes the `#` heading `node`, of level 1 or 2, underlined
+ * with `===` or `---`, or undefined where its text could not stand on a line
+ * of its own as the same heading. Only headings at the start of a line of the
+ * document itself, below a blank line or at the start, are underlined:
+ * directly below text, the heading's line would continue a paragraph. On
+ * Forgejo and Gitea, a heading with a `{` keeps its form, because their
+ * attribute blocks depend on it.
+ */
+export declare function underlineEdit(document: Document, node: Heading): Edit | undefined;
+export declare const blockRules: Record<string, Rule>;