mdrefine 0.1.0-beta.1

package/docs/obsidian.md

@@ -0,0 +1,69 @@
+# Obsidian vaults
+
+The Obsidian profile understands wikilinks, embeds, callouts, highlights,
+comments, heading references, and block references. Its rules share the same
+lint and format engine used for ordinary Markdown.
+
+## Configure the vault
+
+Create `mdtools.config.jsonc` at the vault root:
+
+```jsonc
+{
+  "extends": ["recommended", "obsidian"],
+  "ignore": ["Templates/**"],
+}
+```
+
+Use the vault root as `--root` so the CLI can inspect `.obsidian/app.json` and
+resolve links across notes. Run these commands from a
+[built checkout](quick-start.md):
+
+```sh
+node dist/cli/main.js lint --root "/path/to/vault" --json
+node dist/cli/main.js format --root "/path/to/vault" --diff
+```
+
+## Enable source wrapping
+
+Obsidian reflow requires `"strictLineBreaks": true` in `.obsidian/app.json` so
+soft line breaks in source do not become visible line breaks in Reading view.
+Preserve the file's other settings when changing this value. The CLI checks it
+and never edits the settings file itself.
+
+If that setting is not appropriate for your vault, disable `style/wrap`. Other
+enabled rules can still run.
+
+## Choose link policies deliberately
+
+The recommended preset validates local links. To normalize verified destinations
+to vault-relative paths wrapped in angle brackets:
+
+```jsonc
+{
+  "extends": ["recommended", "obsidian"],
+  "rules": {
+    "links/path": ["warn", { "style": "root", "brackets": "angle" }],
+  },
+}
+```
+
+For example, a resolved Markdown link can become `[Note](<Folder/Note.md>)`.
+Missing or ambiguous destinations are never guessed. Unaliased wikilinks retain
+their target spelling because changing it may change their visible label. Note
+embeds remain embeds.
+
+See [link policies](configuration.md#link-policies) for relative paths,
+extension handling, and eligible Markdown/wikilink conversion. Path rewriting
+and notation conversion should be run in separate passes.
+
+## Review visible results
+
+Preview changes with `--diff`, then use `--write` to apply them. Inspect complex
+notes in Obsidian, especially when using additional plugins. The resolver does
+not reproduce every Obsidian link-resolution behavior, and unsupported syntax
+may need an ignore pattern or a
+[suppression comment](configuration.md#suppressions).
+
+Read the [current limitations](design.md#safety-boundaries) before a broad
+vault-wide formatting pass.

package/docs/plugins.md

@@ -0,0 +1,114 @@
+# Plugins and library API
+
+The public API is exported from `mdrefine`. Follow the
+[installation guide](quick-start.md) to install the npm package or build a
+checkout as a local dependency. The API is provisional until a stable release.
+
+## Library calls
+
+```ts
+import { createWorkspace, format, lint } from "mdrefine";
+
+const files = {
+  "note.md": "A *short* note with [a link](target.md).\n",
+  "target.md": "# Target\n",
+};
+const options = {
+  path: "note.md",
+  config: { extends: ["recommended", "github"] },
+  workspace: createWorkspace(files, { dialect: "github" }),
+};
+
+const diagnostics = lint(files["note.md"], options);
+const result = format(files["note.md"], options);
+// result: { output, changed, diagnostics }
+```
+
+Library calls do not read or write files. `path` and workspace keys use
+forward-slash paths relative to the workspace root. Use `null` values for
+non-Markdown attachments. Without a workspace, local target checks and path
+rewriting are unavailable. Obsidian reflow also requires an explicit
+`workspace.strictLineBreaks: true`; callers are responsible for verifying that
+renderer setting.
+
+`parse`, `range`, `textContent`, `resolveConfig`, `configSchema`, `presets`,
+`builtInRules`, `ruleRegistry`, `applyEdits`, and `semanticFingerprint` are also
+exported. `range(node)` returns `[start, end]` UTF-16 offsets into the original
+source. `configSchema` is the configuration's JSON Schema; rule-specific schemas
+live on rule objects.
+
+## Rule plugins
+
+Create `rules.mjs` beside the configuration:
+
+```js
+export default {
+  name: "local",
+  presets: {
+    recommended: { rules: { "local/initial-heading": "error" } },
+  },
+  rules: {
+    "initial-heading": {
+      description: "Require the first content block to be a heading.",
+      kind: "problem",
+      check({ document }) {
+        const first = document.tree.children.find(
+          (node) => node.type !== "yaml" && node.type !== "toml",
+        );
+        return first?.type === "heading"
+          ? []
+          : [{ start: 0, message: "Start this document with a heading." }];
+      },
+    },
+  },
+};
+```
+
+Load it with:
+
+```json
+{
+  "plugins": ["./rules.mjs"],
+  "extends": ["recommended", "local/recommended"]
+}
+```
+
+Plugin module specifiers resolve relative to the config file, including npm
+package names. Export a default plugin object. Library callers pass plugin
+objects directly through `plugins`; a string list in a library configuration
+does not perform module loading. Plugin names must be unique lowercase
+identifiers beginning with a letter, using letters, digits, and hyphens. Rule
+IDs are namespaced as `plugin-name/rule-name`; collisions are rejected.
+
+`check` receives the parsed `document`, configured `options`, and optional
+`workspace`. Return a list of findings containing `start`, optional `end`,
+`message`, and optional `edit`. A rule may declare a JSON Schema in `schema` to
+validate its options. Rules are synchronous and should not mutate the document,
+perform I/O, or retain invocation-specific state.
+
+Style rules use `kind: "style"` and can return edits of the form
+`{ start, end, text }`. Their optional `phase` is `inline` (default), `block`,
+or `document`. Problem rules use `kind: "problem"`; their edits are not applied
+by `format`. Formatting runs phases repeatedly until stable, with a limit of
+eight passes. Conflicting edits, oscillation, or a semantic change reject the
+entire document's output.
+
+Use built-in test helpers and fixture examples to verify custom style rules.
+Plugins execute within the host process and are not sandboxed. Semantic checking
+constrains the returned text, not arbitrary JavaScript behavior.
+
+## Syntax extensions
+
+An advanced plugin can provide `syntax: { micromark, mdast }`, containing
+compatible tokenizer and AST extensions from the micromark/mdast ecosystem.
+Extend the TypeScript mdast node maps for custom node types. Preserve source
+positions and expose meaningful semantic fields: the engine compares node fields
+other than `position` and `data` when checking formatting safety.
+
+This is not a general remark-transform adapter. Existing syntax extensions can
+be reused, but a remark plugin that mutates a tree must be adapted to the
+rule/edit contract. There is no custom link resolver loader in CLI plugins yet;
+library users can supply an implementation of the `Workspace` interface. Unknown
+syntax is not automatically safe merely because a parser treats it as plain
+text; use a supported dialect, an extension, an ignore pattern, or a suppression
+for application-specific constructs.

package/docs/quick-start.md

@@ -0,0 +1,101 @@
+# Quick start
+
+Get the CLI running, select a profile, and preview a formatting pass before
+writing changes.
+
+## Install the beta
+
+The CLI requires Node.js 22.12 or newer. Install the package in your document
+workspace:
+
+```sh
+npm install --save-dev --save-exact mdrefine@0.1.0-beta.1
+npx --no-install mdtools --help
+```
+
+The npm package is `mdrefine`; the executable is `mdtools`. Prereleases use the
+`beta` channel. See
+[versions and availability](releases.md#versions-and-availability) for registry
+checks and release announcements.
+
+Run the examples below from the workspace where you installed the package.
+`--no-install` prevents fetching a different package if the local executable is
+missing. Replace `/path/to/documents` with your document folder; quote paths
+containing spaces.
+
+## Install from the repository
+
+To build a checkout instead, use Node.js 22.22.2+ or 24.15.0+ and npm 10 or
+newer; Node.js 24 LTS is preferred.
+
+```sh
+git clone https://github.com/viell-dev/slop-markdown-tools.git
+cd slop-markdown-tools
+npm ci
+npm run build
+node dist/cli/main.js --help
+```
+
+From that checkout, use `node dist/cli/main.js` in place of
+`npx --no-install mdtools` in the examples below.
+
+## Choose a configuration
+
+Create `mdtools.config.jsonc` in your document folder:
+
+```jsonc
+{
+  "extends": ["recommended", "github"],
+  "ignore": ["vendor/**", "**/*.external.md"],
+}
+```
+
+The recommended preset wraps prose at **80 columns**, uses `_` for emphasis and
+`**` for strong text, ensures a final newline, and validates local links. The
+GitHub preset adds table, task marker, and alert marker rules. The configuration
+controls both linting and formatting.
+
+For CommonMark, use only `"recommended"`. For a vault, replace `"github"` with
+`"obsidian"` and follow the [Obsidian setup](obsidian.md).
+
+## Lint without writing
+
+```sh
+npx --no-install mdtools lint --root /path/to/documents
+```
+
+Lint reports diagnostics and never changes files. Add `--json` for structured
+output, or `--max-warnings 0` to make warnings fail an automated check.
+
+## Preview and apply formatting
+
+```sh
+npx --no-install mdtools format --root /path/to/documents --diff
+npx --no-install mdtools format --root /path/to/documents --write
+npx --no-install mdtools format --root /path/to/documents --check
+```
+
+Review the diff before running `--write`. The final check exits with code `1` if
+formatting changes remain. Formatting may still report lint problems that
+require a manual correction; inspect diagnostics as well as the exit code.
+
+## Adjust the rules
+
+Override a preset rule by adding a `rules` object:
+
+```jsonc
+{
+  "extends": ["recommended", "github"],
+  "rules": {
+    "style/wrap": ["warn", { "width": 100 }],
+    "style/emphasis": "off",
+  },
+}
+```
+
+This wraps at 100 columns and preserves existing emphasis delimiters. Use
+`"extends": []` to start with no enabled rules.
+
+Continue with [CLI workflows](cli.md) for automation and file selection, or
+[configuration and rules](configuration.md) for presets, links, overrides, and
+suppression comments.

package/docs/releases/0.1.0-beta.1.md

@@ -0,0 +1,39 @@
+# mdrefine 0.1.0-beta.1
+
+First public beta of Markdown Tools. npm package: `mdrefine`; executable:
+`mdtools`. Requires Node.js 22.12 or newer.
+
+## Features
+
+- Separate lint and format commands with JSON reports, diff previews, stdin,
+  check mode, and explicit file writes.
+- Configurable presets, per-file overrides, suppression comments, and custom
+  JavaScript rule and syntax plugins.
+- Source-preserving formatting for CommonMark, GitHub Markdown, and Obsidian,
+  with a default wrap width of 80 columns.
+- Local link and fragment validation, verified link path and notation changes,
+  GitHub tables and alerts, and Obsidian wikilinks, embeds, callouts, and block
+  references.
+- Obsidian paragraph reflow requires verified `strictLineBreaks: true`.
+
+## Packaging and maintenance
+
+- The package name changed from the unpublished `@viell-dev/markdown-tools`
+  checkout name to `mdrefine`. Update library imports; the `mdtools` command,
+  configuration names, and suppression directives remain unchanged.
+- Installed package checks cover the command shim, library exports, and public
+  TypeScript declarations on the supported CI platforms.
+- Manual release preparation retains a tested tarball and checksum. Publishing
+  is separately gated and uses the npm `beta` channel.
+- PR-based maintenance applies to prereleases as well as stable versions.
+- Multiline inline code is preserved during reflow instead of triggering an
+  unsafe-format rejection.
+
+## Known limits
+
+The plugin API and configuration are provisional. Ambiguous links are reported
+without guessing; unsupported syntax is preserved conservatively. Not every
+Markdown layout is normalized. Review the
+[design and limitations](https://viell-dev.github.io/slop-markdown-tools/design.html)
+before adopting the beta across a vault. This project is developed and
+maintained by agents without assumed human review.

package/docs/releases.md

@@ -0,0 +1,90 @@
+# Releases
+
+## Versions and availability
+
+These documents cover `mdrefine@0.1.0-beta.1`. The executable is `mdtools`;
+prereleases use npm's `beta` channel. Read the
+[beta.1 release notes](releases/0.1.0-beta.1.md) for changes and limitations.
+
+The registry is the source of truth for package availability:
+
+```sh
+npm view mdrefine@0.1.0-beta.1 version --registry=https://registry.npmjs.org/
+```
+
+An `E404` means the requested package or version is unavailable. A version in
+this repository or its documentation does not imply publication. Check
+[GitHub releases](https://github.com/viell-dev/slop-markdown-tools/releases) for
+release announcements and downloadable artifacts.
+
+## Prepare without publishing
+
+Use Node.js 24 and npm 10 or newer from a clean checkout:
+
+```sh
+npm ci
+npm run release:prepare
+npm publish ./artifacts/mdrefine-0.1.0-beta.1.tgz --dry-run --ignore-scripts --access public --tag beta
+```
+
+Preparation runs all checks, packs the allowlisted files, installs that exact
+tarball into a temporary consumer, exercises the installed command and library,
+and compiles a TypeScript consumer. It retains the tested tarball, file
+manifest, and SHA-256 checksum in ignored `artifacts/`. No registry upload, Git
+tag, or GitHub release occurs. Local artifacts must be regenerated after any
+change.
+
+The manual **Release** GitHub Actions workflow performs the same checks plus a
+dependency audit and uploads the artifact for 14 days. Leave `publish` false to
+prepare only. CI independently checks Linux, macOS, Windows, and Node.js 22/24.
+
+## Publication prerequisites
+
+Publication requires explicit operator authorization. Preparing a PR or artifact
+does not supply that authorization. Before the first publication:
+
+1. Merge the release PR with all required checks passing. Review the tarball
+   manifest, release notes, version, and registry name again.
+2. Arrange npm account access, verified email, and required two-factor
+   authentication. Verify the intended account with `npm whoami`. Bootstrap
+   publication may need an authenticated local publish before package settings
+   are available for trusted publishing.
+3. Configure npm's
+   [trusted publisher](https://docs.npmjs.com/trusted-publishers/) for user
+   `viell-dev`, repository `slop-markdown-tools`, workflow `release.yml`, and
+   environment `npm-release`. Allow direct `npm publish`. No long-lived npm
+   token is stored in GitHub.
+4. Restrict the GitHub `npm-release` environment to `main` and configure an
+   approval gate if an independent approver is available. Verify branch rules
+   still require PRs and the four CI checks. The workflow uses Node.js 24 and
+   checks that npm supports trusted publishing.
+5. Only after authorization and authentication setup, set repository variable
+   `NPM_PUBLISH_ENABLED` to `true`. It is disabled during preparation.
+
+## Publish an authorized beta
+
+Dispatch **Release** on `main` with the exact package version, `publish: true`,
+and the actual publishing agent's identity as `model via harness`. The workflow
+builds and checks the package again, verifies the artifact checksum, publishes
+that tarball to npm's `beta` channel with provenance, and creates a GitHub
+prerelease at the workflow's commit. Tags use exact versions without a `v`
+prefix. Stable publication deliberately needs a separate policy change; this
+workflow accepts only beta versions and never assigns npm's `latest` tag.
+
+For an authenticated first publication that cannot use OIDC yet, use the exact
+reviewed tarball with `npm publish <tarball> --ignore-scripts --access public
+--tag beta` only after authorization. Then create the matching GitHub
+prerelease at the exact source commit, attach the tarball and checksum, and use
+the reviewed notes with the actual publishing agent attribution. Complete npm
+trusted publisher setup afterward.
+
+If npm succeeds but GitHub release creation fails, do not republish or bump the
+version blindly. Verify the published package integrity against the retained
+artifact and finish only the missing GitHub step at the same commit. Published
+versions, tags, and release assets must never be overwritten; corrections use a
+new version. The workflow refuses an existing npm version or tag to make a
+partial release visible instead of silently accepting it.
+
+After publication, verify registry metadata, the `beta` dist-tag, a fresh
+installation, the GitHub release and its assets, and the documentation site. All
+subsequent changes, including prerelease maintenance, continue through PRs.

package/examples/github.jsonc

@@ -0,0 +1,7 @@
+{
+  "extends": ["recommended", "github"],
+  "rules": {
+    "style/wrap": ["warn", { "width": 80 }],
+    "links/path": ["warn", { "style": "relative", "leadingDot": true }],
+  },
+}

package/examples/obsidian.jsonc

@@ -0,0 +1,8 @@
+{
+  "extends": ["recommended", "obsidian"],
+  "ignore": ["**/*.external.md"],
+  "rules": {
+    "style/wrap": ["warn", { "width": 80 }],
+    "links/path": ["warn", { "style": "root", "brackets": "angle", "extension": "preserve" }],
+  },
+}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "mdrefine",
+  "version": "0.1.0-beta.1",
+  "description": "Configurable Markdown linting and formatting for CommonMark, GitHub, and Obsidian",
+  "type": "module",
+  "license": "MIT",
+  "author": "viell",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/viell-dev/slop-markdown-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/viell-dev/slop-markdown-tools/issues"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "mdtools": "dist/cli/main.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/*.md",
+    "docs/releases/*.md",
+    "examples",
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "pretest": "npm run build",
+    "test:package": "run-s build test:package:installed",
+    "lint": "eslint .",
+    "format": "run-s format:code format:docs",
+    "format:code": "prettier --write .",
+    "format:docs": "run-s build format:docs:write",
+    "format:docs:check": "run-s build lint:docs format:docs:verify",
+    "format:check": "run-p format:code:check format:docs:check",
+    "check": "npm-run-all --parallel typecheck lint format:check docs:build --sequential test",
+    "prepack": "npm run build",
+    "test:package:installed": "node scripts/package-smoke.mjs",
+    "format:docs:write": "node dist/cli/main.js format --write",
+    "lint:docs": "node dist/cli/main.js lint --max-warnings 0",
+    "format:docs:verify": "node dist/cli/main.js format --check",
+    "format:code:check": "prettier --check .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "release:prepare": "run-s check release:pack",
+    "release:pack": "node scripts/package-smoke.mjs --retain"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "commander": "15.0.0",
+    "diff": "9.0.0",
+    "github-slugger": "2.0.0",
+    "ignore": "7.0.9",
+    "jsonc-parser": "3.3.1",
+    "mdast-util-from-markdown": "2.0.3",
+    "mdast-util-frontmatter": "2.0.1",
+    "mdast-util-gfm": "3.1.0",
+    "mdast-util-math": "3.0.0",
+    "micromark-extension-frontmatter": "2.0.0",
+    "micromark-extension-gfm": "3.0.0",
+    "micromark-extension-math": "3.1.0",
+    "micromark-util-types": "2.0.2",
+    "minimatch": "10.2.6",
+    "string-width": "8.2.2",
+    "unist-util-visit": "5.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/mdast": "4.0.4",
+    "@types/node": "26.6.1",
+    "@types/unist": "3.0.3",
+    "eslint": "10.10.0",
+    "fast-check": "4.10.1",
+    "npm-run-all2": "9.0.3",
+    "prettier": "3.9.8",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.70.0",
+    "vitepress": "2.0.0-alpha.20",
+    "vitest": "5.0.1"
+  },
+  "homepage": "https://viell-dev.github.io/slop-markdown-tools/"
+}