mdrefine 0.2.0-rc.2 → 0.2.0

package/docs/versions.md

@@ -0,0 +1,56 @@
+# Versions
+
+Version numbers follow [Semantic Versioning](https://semver.org/). Before 1.0,
+the second number plays the part of the first: a minor release such as 0.3.0 may
+change what 0.2 does, and the [changelog](changelog.md) says how, while a patch
+release such as 0.2.1 only fixes defects.
+
+## What a version number covers
+
+- the `mdtools` commands, their options, and their exit codes;
+- the [JSON report](cli.md#json-report) printed with `--json`: its fields and
+  what they mean;
+- the configuration: file names, keys, presets, dialect names, rule IDs, rule
+  options, what each of them means, and where its [JSON
+  Schema](configuration.md#json-schema) is found;
+- the library's exports from `mdrefine` and `mdrefine/node`, their TypeScript
+  types, and the plugin contract described in [library API](api.md) and
+  [plugins](plugins.md);
+- the supported Node.js versions, given by `engines` in `package.json`.
+
+These can change in any release:
+
+- the wording of messages: diagnostics, warnings, and the summary line. A script
+  should read the exit code and the JSON report, whose diagnostics carry rule
+  IDs.
+- formatting output that changes because a defect is fixed. A patch release can
+  format a document differently where the previous version damaged it, refused
+  it, or read it the wrong way, and can report findings that the defect hid.
+- speed and memory use, and the figures on the [benchmark page](benchmarks.md).
+- files of the package that the documentation does not describe.
+
+A deliberate change of what formatting produces, such as a new default, a rule
+added to a preset, or a changed option, comes in a minor release, and so does a
+higher minimum Node.js version. Pin the exact version, as the
+[installation](quick-start.md#install) does, so that you choose when such a
+change reaches your documents.
+
+## Releases and channels
+
+From 0.2.0, the first stable release, npm's `latest` tag names the newest stable
+release. Release candidates and betas are published under the tags `rc` and
+`beta` and leave `latest` alone. Only the newest release line receives fixes;
+see the [security
+policy](https://github.com/viell-dev/slop-markdown-tools/blob/main/SECURITY.md).
+This site describes the newest stable release.
+
+A version named in the repository is not necessarily published. The registry is
+the source of truth:
+
+```sh
+npm view mdrefine versions
+```
+
+Each release has a [GitHub
+release](https://github.com/viell-dev/slop-markdown-tools/releases) with the
+tested package and its checksum.

package/examples/README.md

@@ -1,25 +1,25 @@
 # Examples
 
-Working examples of configuring, running, and extending Markdown Tools. The
-[examples page](https://viell-dev.github.io/slop-markdown-tools/examples.html)
-walks through each one with its input and output. The integration tests run
-every example, so what is here matches what the tool does.
+Working examples of configuring, running, and extending mdrefine. The [examples
+page](https://viell-dev.github.io/slop-markdown-tools/examples.html) walks
+through each one with its input and output. The integration tests run every
+example, so what is here matches what the tool does.
 
 Run the commands below from a built checkout (`npm ci && npm run build`). In a
 project that installs the package, the same files are under
-`node_modules/mdrefine/examples/`, and `npx --no-install mdtools` replaces
+`node_modules/mdrefine/examples/`, and `npx mdtools` replaces
 `node dist/cli/main.js`.
 
 ## Starting configurations
 
 Copy one to the root of your documents as `mdtools.config.jsonc`.
 
-| File                               | For                                         |
-| ---------------------------------- | ------------------------------------------- |
-| [`github.jsonc`](github.jsonc)     | Repositories rendered by GitHub             |
-| [`forgejo.jsonc`](forgejo.jsonc)   | Codeberg and other Forgejo instances        |
-| [`gitea.jsonc`](gitea.jsonc)       | Gitea instances                             |
-| [`obsidian.jsonc`](obsidian.jsonc) | Obsidian vaults, with vault-root link paths |
+| File                               | For                                             |
+| ---------------------------------- | ----------------------------------------------- |
+| [`github.jsonc`](github.jsonc)     | Repositories rendered by GitHub                 |
+| [`forgejo.jsonc`](forgejo.jsonc)   | Codeberg and other Forgejo instances            |
+| [`gitea.jsonc`](gitea.jsonc)       | Gitea instances                                 |
+| [`obsidian.jsonc`](obsidian.jsonc) | Obsidian vaults, with vault-relative link paths |
 
 ## Workspaces before and after formatting
 
@@ -32,7 +32,7 @@ reports it afterwards.
   two guides for a repository on GitHub.
 - [`workspaces/obsidian-vault/`](workspaces/obsidian-vault/) is a small vault
   with wikilinks, an embed, callouts, a block reference, and an ignored template
-  folder.
+  directory.
 
 ```sh
 node dist/cli/main.js lint --root examples/workspaces/repository-docs/before
@@ -60,12 +60,15 @@ name, which works inside this repository and wherever the package is installed.
 ```sh
 node examples/library/format-string.mjs
 node examples/library/lint-folder.mjs
+node examples/library/lint-workspace.mjs
 ```
 
 [`format-string.mjs`](library/format-string.mjs) formats one string.
 [`lint-folder.mjs`](library/lint-folder.mjs) reads a folder of GitHub Markdown,
-builds the workspace that link checks need, and prints diagnostics. Without an
-argument it reads `workspaces/repository-docs/after`.
+builds the workspace that link checks need, and prints diagnostics.
+[`lint-workspace.mjs`](library/lint-workspace.mjs) does the same with
+`mdrefine/node`, which chooses the files as the CLI does. Without an argument,
+both read `workspaces/repository-docs/after`.
 
 ## Automation
 

package/examples/automation/summarize-report.mjs

@@ -4,7 +4,8 @@
 //
 // The report is one object: { version, mode, files, written }, with a `skipped`
 // list when the run left out a path it was not permitted to read. Each file has
-// a `path`, its `diagnostics`, and for `format` a `changed` flag.
+// a `path`, its `diagnostics`, and for `format` a `changed` flag; `written` lists
+// the paths of the files that `format --write` wrote.
 let input = "";
 process.stdin.setEncoding("utf8");
 for await (const chunk of process.stdin) input += chunk;
@@ -27,7 +28,9 @@ console.log(`${report.mode}: ${report.files.length} file(s), ${diagnostics} diag
 if (report.mode === "format") {
   // `changed` stays true for a file that `--write` has just formatted.
   const changed = report.files.filter((file) => file.changed).length;
-  console.log(`${changed} file(s) ${report.written ? "were formatted" : "need formatting"}`);
+  const written = report.written.length;
+  if (written) console.log(`${written} file(s) were formatted`);
+  if (!written || changed > written) console.log(`${changed - written} file(s) need formatting`);
 }
 for (const [key, entry] of [...counts].sort((a, b) => b[1].count - a[1].count)) {
   console.log(`${entry.count} ${key} in ${entry.files.size} file(s)`);

package/examples/library/lint-folder.mjs

@@ -3,7 +3,8 @@
 // The library never reads or writes files. The host reads them and hands them
 // to createWorkspace(), which is what lets rules check links between documents.
 // This script reads everything below the folder; a real host would skip folders
-// such as .git and node_modules, as the CLI does.
+// such as .git and node_modules, as the CLI does. lint-workspace.mjs leaves that
+// to discoverWorkspace() from "mdrefine/node".
 //
 //   node examples/library/lint-folder.mjs [folder]
 import { readdir, readFile } from "node:fs/promises";
@@ -17,14 +18,14 @@ const folder = path.resolve(
 const config = { extends: ["recommended", "github"] };
 
 // Workspace keys are forward-slash paths relative to the folder. A Markdown
-// file maps to its text; any other file maps to null, so that links to it
-// still resolve.
+// file, named .md or .markdown as the CLI finds them, maps to its text; any
+// other file maps to null, so that links to it still resolve.
 const files = {};
 for (const entry of await readdir(folder, { recursive: true, withFileTypes: true })) {
   if (!entry.isFile()) continue;
   const absolute = path.join(entry.parentPath, entry.name);
   const name = path.relative(folder, absolute).split(path.sep).join("/");
-  files[name] = /\.md$/i.test(name) ? await readFile(absolute, "utf8") : null;
+  files[name] = /\.(?:md|markdown)$/i.test(name) ? await readFile(absolute, "utf8") : null;
 }
 const workspace = createWorkspace(files, { dialect: "github" });
 

package/examples/library/lint-workspace.mjs

@@ -0,0 +1,32 @@
+// Lint a workspace on disk through the library, choosing files as the CLI does.
+//
+// discoverWorkspace() from "mdrefine/node" finds the files, honors .gitignore
+// files and the configuration's ignore patterns, leaves out nested
+// repositories and what it may not read, and recognizes Obsidian vaults.
+// options() then gives each document what the CLI passes to lint() and
+// format(). Configuration files are not read: pass the configuration.
+//
+//   node examples/library/lint-workspace.mjs [folder]
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { lint } from "mdrefine";
+import { discoverWorkspace } from "mdrefine/node";
+
+const root = path.resolve(
+  process.argv[2] ?? fileURLToPath(new URL("../workspaces/repository-docs/after", import.meta.url)),
+);
+const config = { extends: ["recommended", "github"] };
+
+const discovery = await discoverWorkspace({ root, config });
+for (const item of discovery.skipped) console.log(`skipped: ${item.message}`);
+let errors = 0;
+for (const name of discovery.selected) {
+  for (const item of lint(discovery.read(name), discovery.options(name))) {
+    if (item.severity === "error") errors += 1;
+    console.log(
+      `${name}:${item.line}:${item.column} ${item.severity} ${item.rule}: ${item.message}`,
+    );
+  }
+}
+console.log(`${errors} error(s) in ${discovery.selected.length} document(s)`);
+process.exitCode = errors > 0 ? 1 : 0;

package/examples/plugin/notes/release-checklist.md

@@ -4,6 +4,6 @@ Draft the announcement. TODO: add the download link.
 
 Searching the notes with `grep TODO` is not reported: code is not prose.
 
-***
+##   Before publishing
 
-Ask for a review before publishing.
+Ask for a review.

package/examples/plugin/rules.mjs

@@ -15,7 +15,7 @@ export default {
   name: "house",
   presets: {
     recommended: {
-      rules: { "house/no-placeholder": "error", "house/thematic-break": "warn" },
+      rules: { "house/no-placeholder": "error", "house/heading-space": "warn" },
     },
   },
   rules: {
@@ -57,36 +57,30 @@ export default {
         return findings;
       },
     },
-    "thematic-break": {
-      description: "Write thematic breaks as three hyphens.",
+    "heading-space": {
+      description: "Write one space between a heading's # marks and its text.",
       kind: "style",
       phase: "block",
       check({ document }) {
         const findings = [];
-        const blocks = document.tree.children;
-        // In a document whose first line is the thematic break "---", a later
-        // "---" would close it as front matter, so no break is rewritten there.
-        const opensFrontMatter =
-          blocks[0]?.type === "thematicBreak" && document.source.startsWith("---");
-        for (const [index, node] of blocks.entries()) {
-          if (node.type !== "thematicBreak") continue;
+        visit(document.tree, (node) => {
+          if (node.type !== "heading" || !node.children.length) return;
           const start = node.position.start.offset;
-          const end = node.position.end.offset;
-          if (document.source.slice(start, end) === "---") continue;
-          // "---" directly below a paragraph would turn that paragraph into a
-          // heading. Only propose the edit after a blank line, where it cannot.
-          const previous = blocks[index - 1];
-          const safe =
-            !opensFrontMatter &&
-            previous &&
-            previous.position.end.line < node.position.start.line - 1;
+          const text = node.children[0].position.start.offset;
+          const marks = document.source.slice(start, text);
+          const wanted = `${"#".repeat(node.depth)} `;
+          // Only a "#" heading starts with its marks: an underlined heading
+          // starts with its text, and so the check below leaves it alone. The
+          // parser drops the blank space before a heading's text, so changing
+          // it cannot change what the heading says.
+          if (!/^#+[ \t]+$/.test(marks) || marks === wanted) return;
           findings.push({
             start,
-            end,
-            message: "Write this thematic break as ---.",
-            ...(safe ? { edit: { start, end, text: "---" } } : {}),
+            end: text,
+            message: "Write one space after the heading's # marks.",
+            edit: { start, end: text, text: wanted },
           });
-        }
+        });
         return findings;
       },
     },

package/examples/workspaces/obsidian-vault/after/mdtools.config.jsonc

@@ -1,10 +1,10 @@
 {
-  // An Obsidian vault; this file sits at the vault root, next to .obsidian/.
+  // An Obsidian vault; this file sits at the vault's root, next to .obsidian/.
   "extends": ["recommended", "obsidian"],
   // Templates contain placeholders, not prose. They stay valid link targets.
   "ignore": ["Templates/**"],
   "rules": {
-    // Spell Markdown links as vault-root paths in angle brackets.
+    // Spell Markdown links as vault-relative paths in angle brackets.
     "links/path": ["warn", { "style": "root", "brackets": "angle" }],
   },
 }

package/examples/workspaces/obsidian-vault/before/mdtools.config.jsonc

@@ -1,10 +1,10 @@
 {
-  // An Obsidian vault; this file sits at the vault root, next to .obsidian/.
+  // An Obsidian vault; this file sits at the vault's root, next to .obsidian/.
   "extends": ["recommended", "obsidian"],
   // Templates contain placeholders, not prose. They stay valid link targets.
   "ignore": ["Templates/**"],
   "rules": {
-    // Spell Markdown links as vault-root paths in angle brackets.
+    // Spell Markdown links as vault-relative paths in angle brackets.
     "links/path": ["warn", { "style": "root", "brackets": "angle" }],
   },
 }

package/examples/workspaces/repository-docs/after/README.md

@@ -8,8 +8,8 @@ a sensor board and publishes them as a small web page that updates every minute.
 
 ## Usage
 
-Follow the [setup guide](./docs/guide.md) first, then read the
-[sensor reference](./docs/reference.md#pressure) to interpret the readings. The
+Follow the [setup guide](./docs/guide.md) first, then read the [sensor
+reference](./docs/reference.md#pressure) to interpret the readings. The
 [calibration notes](docs/calibration.md) explain how to correct a drifting
 sensor.
 

package/examples/workspaces/repository-docs/after/mdtools.config.jsonc

@@ -2,8 +2,6 @@
   // Documentation for a repository hosted on GitHub.
   "extends": ["recommended", "github"],
   "rules": {
-    // Not part of a preset: turn underlined headings into "#" headings.
-    "style/heading": "warn",
     // Write local links as ./relative paths, which editors can follow too.
     "links/path": ["warn", { "style": "relative", "leadingDot": true }],
   },

package/examples/workspaces/repository-docs/before/README.md

@@ -17,5 +17,5 @@ Follow the [setup guide](docs/guide.md) first, then read the [sensor reference](
 | Humidity | % | Yes |
 | Pressure | hPa | Since 1.2 |
 
-- [X] Publish readings every minute
-- [ ] Keep a week of history
+* [X] Publish readings every minute
+* [ ] Keep a week of history

package/examples/workspaces/repository-docs/before/docs/guide.md

@@ -3,14 +3,14 @@ Setup guide
 
 This guide takes a new board from the box to its first published reading. Allow about ten minutes, most of which is waiting for the sensors to settle.
 
-1. Connect the board over USB and wait until the status light stops blinking. A steady light means the sensors have settled and the readings can be trusted.
-2. Copy `station.toml` to the board and set the publishing interval:
+1)  Connect the board over USB and wait until the status light stops blinking. A steady light means the sensors have settled and the readings can be trusted.
+2)  Copy `station.toml` to the board and set the publishing interval:
 
-   ```toml
-   [publish]
-   interval_seconds = 60   # Lines in code blocks are never wrapped, however long they are.
-   ```
+    ~~~toml
+    [publish]
+    interval_seconds = 60   # Lines in code blocks are never wrapped, however long they are.
+    ~~~
 
-3. Open the page listed under [Usage](../README.md#usage) and check that all three readings appear.
+3)  Open the page listed under [Usage](../README.md#usage) and check that all three readings appear.
 
 Readings that look wrong are usually a unit problem; the [reference](reference.md) lists the unit of every sensor.

package/examples/workspaces/repository-docs/before/docs/reference.md

@@ -4,10 +4,12 @@
 
 Reported in degrees Celsius, rounded to one decimal place.
 
-## Humidity
+## Humidity ##
 
 Reported as relative humidity in percent.
 
+
+
 ## Pressure
 
 Reported in hectopascals. Pressure needs about two minutes after power-on before the first stable value; see the __[setup guide](guide.md)__.

package/examples/workspaces/repository-docs/before/mdtools.config.jsonc

@@ -2,8 +2,6 @@
   // Documentation for a repository hosted on GitHub.
   "extends": ["recommended", "github"],
   "rules": {
-    // Not part of a preset: turn underlined headings into "#" headings.
-    "style/heading": "warn",
     // Write local links as ./relative paths, which editors can follow too.
     "links/path": ["warn", { "style": "relative", "leadingDot": true }],
   },

package/package.json

@@ -1,7 +1,23 @@
 {
   "name": "mdrefine",
-  "version": "0.2.0-rc.2",
+  "version": "0.2.0",
   "description": "Configurable Markdown linting and formatting for CommonMark, GitHub, Forgejo, Gitea, and Obsidian",
+  "keywords": [
+    "markdown",
+    "lint",
+    "linter",
+    "format",
+    "formatter",
+    "commonmark",
+    "gfm",
+    "github",
+    "forgejo",
+    "codeberg",
+    "gitea",
+    "obsidian",
+    "mdast",
+    "micromark"
+  ],
   "type": "module",
   "license": "MIT",
   "author": "viell",
@@ -21,20 +37,28 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "rc"
+    "tag": "latest"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./config.schema.json": "./config.schema.json",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "config.schema.json",
     "docs/*.md",
-    "docs/releases/*.md",
     "examples",
     "README.md",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
     "LICENSE",
@@ -68,9 +92,12 @@
     "benchmark": "node benchmarks/run.mjs",
     "prebenchmark": "npm run build",
     "release:prepare": "run-s check release:pack",
-    "release:pack": "node scripts/package-smoke.mjs --retain"
+    "release:pack": "node scripts/package-smoke.mjs --retain",
+    "schema": "run-s build schema:write",
+    "schema:write": "node scripts/config-schema.mjs"
   },
   "dependencies": {
+    "@types/mdast": "4.0.4",
     "ajv": "8.20.0",
     "commander": "15.0.0",
     "decode-named-character-reference": "1.3.0",
@@ -93,17 +120,16 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/mdast": "4.0.4",
-    "@types/node": "26.6.4",
+    "@types/node": "22.20.5",
     "@types/unist": "3.0.3",
-    "eslint": "10.12.0",
+    "eslint": "10.13.0",
     "fast-check": "4.10.2",
     "npm-run-all2": "9.0.3",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.71.1",
+    "typescript-eslint": "8.71.2",
     "vitepress": "2.0.0-alpha.20",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "homepage": "https://viell-dev.github.io/slop-markdown-tools/"
 }