mdrefine 0.2.0-rc.2 → 0.2.0

package/docs/releases/0.2.0-rc.1.md

@@ -1,141 +0,0 @@
-# mdrefine 0.2.0-rc.1
-
-First release candidate of the 0.2 feature release of Markdown Tools. npm
-package: `mdrefine`; executable: `mdtools`. Requires Node.js 22.12 or newer.
-Upgrade with:
-
-```sh
-npm install --save-dev --save-exact mdrefine@0.2.0-rc.1
-```
-
-Changes below are relative to `0.1.0-rc.1`. Release candidates use npm's `rc`
-channel, and `latest` follows the newest prerelease until the first stable
-release.
-
-## Forgejo, Codeberg, and Gitea support
-
-New `forgejo` and `gitea` dialects and presets support documents hosted on those
-forges. `codeberg` is an alias for `forgejo`, accepted in configuration,
-presets, overrides, and `--dialect`; rules and plugins receive the canonical
-name `forgejo`. Gitea is a separate dialect because its heading anchors and
-emphasis behavior differ from Forgejo's. Example configurations are included in
-`examples/forgejo.jsonc` and `examples/gitea.jsonc`
-([PR #73](https://github.com/viell-dev/slop-markdown-tools/pull/73) and
-[PR #79](https://github.com/viell-dev/slop-markdown-tools/pull/79)).
-
-Both presets enable `github/alert-marker`, which normalizes known alert types
-such as `[!note]` to `[!NOTE]`, along with task-marker and table formatting.
-
-Both dialects protect definition lists, backslash-delimited math, and shortlinks
-from formatting that would change how they render. One-line `\(...\)` math and
-`[[...]]` shortlinks stay together; paragraphs with display-math lines,
-definition descriptions, or pairs spanning lines are left unreflowed. Inline
-rules also preserve backslash math. Gitea additionally protects its `_.py`
-emphasis exception, so formatting does not turn literal `__init__.py` into bold
-text. Shortlinks are preserved, not resolved as links. On instances configured
-to render soft line breaks as hard breaks, disable `style/wrap`.
-
-## More accurate fragment validation
-
-`links/valid` now follows the renderer's heading and HTML-anchor behavior:
-
-- Forgejo and Gitea recognize trailing heading attributes such as
-  `## Install {#setup}`. A custom `id` replaces the generated anchor; class-only
-  blocks are left out of the generated text
-  ([PR #86](https://github.com/viell-dev/slop-markdown-tools/pull/86)).
-- Forgejo and Gitea before 1.26 generate anchors from the heading's last text
-  line as written, including emphasis markers and link destinations. Gitea 1.26
-  and later use the rendered text of all its lines. The Gitea dialect accepts
-  both generations' anchors
-  ([PR #100](https://github.com/viell-dev/slop-markdown-tools/pull/100) and
-  [PR #108](https://github.com/viell-dev/slop-markdown-tools/pull/108)).
-- Inline HTML in Markdown headings contributes text without ordinary tags and
-  comments on GitHub and newer Gitea, while tags filtered into visible text
-  still contribute to the anchor
-  ([PR #85](https://github.com/viell-dev/slop-markdown-tools/pull/85) and
-  [PR #108](https://github.com/viell-dev/slop-markdown-tools/pull/108)).
-- Explicit HTML anchors, the `id` of an element and the `name` of an `<a>`, are
-  recognized on GitHub, Forgejo, and Gitea. HTML comments, code, and raw-text
-  contents such as `<script>` and `<textarea>` do not create anchors
-  ([PR #104](https://github.com/viell-dev/slop-markdown-tools/pull/104)).
-- Headings written as HTML (`<h2>Title</h2>`) get generated anchors on GitHub
-  and Gitea 1.26 and later. GitHub numbers repeated HTML and Markdown headings
-  together; newer Gitea does not number them, and an HTML heading with its own
-  `id` gets no generated anchor
-  ([PR #105](https://github.com/viell-dev/slop-markdown-tools/pull/105)).
-- Fragments with one leading `user-content-` prefix are accepted on GitHub,
-  Forgejo, and Gitea. GitHub also matches fragments without regard to case;
-  Forgejo and Gitea remain case-sensitive. CommonMark follows GitHub's anchor
-  rules; Obsidian keeps its existing behavior
-  ([PR #103](https://github.com/viell-dev/slop-markdown-tools/pull/103) and
-  [PR #106](https://github.com/viell-dev/slop-markdown-tools/pull/106)).
-
-Correct fragments previously reported as missing can now resolve, allowing
-`links/path` to rewrite their paths. Links to anchors that the renderer does not
-generate can now be reported as missing.
-
-## Preserve heading attributes and anchors
-
-On Forgejo and Gitea, formatting now keeps heading attribute blocks intact and
-preserves anchors derived from a heading's source. Marker and path rules leave
-the last text line unchanged unless a custom `id` makes its generated anchor
-irrelevant; attribute text itself remains protected. Multiline code spans and
-Setext-to-ATX conversions also preserve attribute interpretation. The semantic
-safety check refuses edits from any rule or plugin that change a heading's
-attribute block or move its generated anchors
-([PR #99](https://github.com/viell-dev/slop-markdown-tools/pull/99) and
-[PR #101](https://github.com/viell-dev/slop-markdown-tools/pull/101)).
-
-The new `forgejo/heading-id` problem rule reports non-text heading IDs such as
-`{id=5}`. Such IDs can make Forgejo and older Gitea fail to render the document;
-newer Gitea renders the heading without an anchor. The `forgejo`, `codeberg`,
-and `gitea` presets enable the rule as an error. It suggests quoting the value
-and proposes no edit
-([PR #107](https://github.com/viell-dev/slop-markdown-tools/pull/107)).
-
-## Parsing and performance
-
-GFM documents containing URLs found only by GitHub's later autolink transform,
-such as `[www.example.com]`, no longer fail formatting with
-`Missing source position for text`. Literal autolinks now come from the syntax
-extension alone. Built-in formatting is unchanged, but plugins inspecting link
-nodes no longer see those transform-only autolinks; ordinary URL and email
-autolinks remain available
-([PR #73](https://github.com/viell-dev/slop-markdown-tools/pull/73)).
-
-The workspace now computes and caches target anchors only for the dialects
-needed by fragment checks. GitHub and Obsidian workspaces avoid the extra parse
-for Forgejo/Gitea heading attributes and their unused anchor calculations;
-fragment-validation results are unchanged
-([PR #109](https://github.com/viell-dev/slop-markdown-tools/pull/109)).
-
-## Compatibility and verification
-
-Existing `0.1.0-rc.1` configurations remain accepted, and the Node.js minimum is
-unchanged. The public `Dialect` type adds `forgejo` and `gitea`; `DialectName`
-also accepts `codeberg` for configuration input. The library adds `dialects`,
-`dialectAliases`, and `canonicalDialect` exports. Hosts and plugins with
-exhaustive dialect handling should include the new canonical names. The API and
-configuration remain provisional until the first stable release.
-
-`Config.dialect` and `Override.dialect` now use `DialectName`, so hosts that
-pass raw configuration values to an API requiring `Dialect` must canonicalize
-them with `canonicalDialect()` first. `resolveConfig()` already returns a
-canonical dialect. The configuration schema accepts the new names and alias.
-
-The Gitea dialect covers 1.21 and later and accepts anchors from both sides of
-the 1.26 renderer change; it does not guarantee that a fragment accepted for one
-version exists on every version. Heading attribute blocks follow the rules used
-by Forgejo 16 and Gitea 1.26 and later. Older Gitea attribute forms, attribute
-values nested more than 64 levels, and some raw-text, footnote, and character
-reference cases remain unmodeled. See [design and limitations](../design.md) for
-the detailed boundaries.
-
-Runtime dependencies now include `ignore@7.0.12`, `micromark-util-types@2.0.3`,
-and `string-width@8.3.0`; `decode-named-character-reference@1.3.0` is a direct
-dependency for HTML heading text. Development tools have also been updated.
-Regression coverage now includes the new dialects, renderer-specific anchors,
-preserved heading attributes, HTML tokenization, and dialect-specific lazy
-indexing. The wrapping performance test has a longer timeout to tolerate slow
-Windows CI runners; its linear-growth assertion is unchanged
-([PR #84](https://github.com/viell-dev/slop-markdown-tools/pull/84)).

package/docs/releases/0.2.0-rc.2.md

@@ -1,225 +0,0 @@
-# mdrefine 0.2.0-rc.2
-
-Second release candidate of the 0.2 feature release of Markdown Tools. npm
-package: `mdrefine`; executable: `mdtools`. Requires Node.js 22.12 or newer.
-Upgrade with:
-
-```sh
-npm install --save-dev --save-exact mdrefine@0.2.0-rc.2
-```
-
-Changes below are relative to `0.2.0-rc.1`. Release candidates use npm's `rc`
-channel, and `latest` follows the newest prerelease until the first stable
-release.
-
-## Check before upgrading
-
-Most of this release makes the tool more careful, but five changes can alter
-what an existing setup does:
-
-- **The dialect assumed when none is named.** A workspace without a
-  configuration file, or with one that names no dialect, was read as CommonMark.
-  It is now read as GitHub Markdown, and documents inside an Obsidian vault as
-  Obsidian notes. Name `"dialect": "commonmark"` to keep the old reading.
-- **What counts as `$` math.** Two sums of money in a paragraph are no longer
-  taken for a formula. Text that was left alone because of that is now wrapped
-  and restyled like other prose.
-- **Messages on stderr.** The `lint` summary, the messages for paths and
-  configuration files that cannot be used, and the messages for plugins that
-  cannot be loaded are worded differently. Exit codes and `--json` output keep
-  their meaning; a script should read those.
-- **Plugin packages with two entries.** A plugin package that declares both an
-  `import` and a `require` entry is now loaded through `import`.
-- **Library hosts.** A source loader given to `createWorkspace` can be called
-  more than once for the same file, and link resolutions have a new status and
-  new fields. See [compatibility](#compatibility-and-verification).
-
-A configuration that names its dialect, as the documentation has always
-recommended, formats and lints the same documents as before. On a large
-real-world Obsidian vault of several thousand notes, `0.2.0-rc.1` and this
-version gave the same result for every file.
-
-## A safer reading when no dialect is named
-
-In CommonMark a table, or a run of footnote definitions, is an ordinary
-paragraph, so formatting without a configuration joined their lines, and in a
-vault it joined lines that Obsidian shows separately and could break a wikilink
-in two. When nothing names a dialect, the tool now assumes `github`, whose
-syntax the Forgejo, Gitea, and Obsidian dialects build on, and `obsidian` for a
-document inside a vault
-([PR #130](https://github.com/viell-dev/slop-markdown-tools/pull/130)).
-
-Only the dialect is assumed. The rules of the `github` and `obsidian` presets
-still need the preset. Library callers get `github` as the default of `lint`,
-`format`, `resolveConfig`, and `createWorkspace`, and can pass `defaultDialect`
-to say what to assume without overriding a dialect that the configuration names.
-
-## Obsidian vaults wherever they are
-
-A vault is recognized by its `.obsidian` folder, and a document belongs to the
-nearest vault at or above its own folder
-([PR #138](https://github.com/viell-dev/slop-markdown-tools/pull/138)):
-
-- A vault in a folder of a larger workspace, such as `docs/vault/` in a
-  repository, is read in the Obsidian dialect while the documents around it stay
-  GitHub Markdown.
-- A folder of a vault used as the workspace root finds the vault above it.
-- A repository checked out inside a vault is not read as the vault's notes.
-- Whether paragraphs may be reflowed is read from each vault's own
-  `.obsidian/app.json`, so vaults with different "Strict line breaks" settings
-  can share a workspace.
-
-Links follow the vault as well. In a vault below the workspace root, an Obsidian
-link reaches only the vault's files, by paths counted from the vault's folder,
-and `links/path` writes `"style": "root"` paths from there. A path that leads
-out of the vault to an existing file is reported as
-`Local target is outside the vault`
-([PR #146](https://github.com/viell-dev/slop-markdown-tools/pull/146)).
-
-When the workspace root is only a folder of a vault, the tool no longer takes
-the folder for the whole vault. `0.2.0-rc.1` could shorten a link with
-`"style": "shortest"` until it named a different note, and called every note
-outside the folder missing. A link whose target the rest of the vault could
-hold, or outdo, is now left as written and reported as
-`Local target could not be checked`; explicit relative paths are still certain
-and rewritten
-([PR #147](https://github.com/viell-dev/slop-markdown-tools/pull/147)).
-
-Two things that stopped every command now do not: a file named `.obsidian`,
-which is ignored, and an `.obsidian/app.json` that is not valid JSON, which
-leaves the line-break setting unverified with a warning.
-
-## Paths that cannot be read
-
-A directory that the system does not permit the tool to read no longer stops the
-run. It is skipped with one warning, the rest of the workspace is processed, and
-a link into it is reported as `Local target could not be checked`, not as
-missing. A selected document that cannot be read is reported with an
-`engine/unreadable-file` error for that file; the others are processed, nothing
-is written, and the exit code is `2`. With `--json`, skipped paths are listed
-under `skipped`
-([PR #133](https://github.com/viell-dev/slop-markdown-tools/pull/133)).
-
-## Dollar math follows the renderer
-
-Text between two `$` signs was read as math in every dialect but CommonMark, so
-a sentence such as `Costs $5 *per* item and $6 *per* box.` had part of its text
-exempt from style rules, and a paragraph with two amounts far apart could not be
-wrapped between them. Each dialect now applies the conditions that its renderer
-was observed to apply
-([PR #150](https://github.com/viell-dev/slop-markdown-tools/pull/150) and
-[PR #164](https://github.com/viell-dev/slop-markdown-tools/pull/164)):
-
-- On GitHub, Forgejo, and Gitea, the opening `$` may not follow a letter or
-  digit, and the next `$` may not be followed by a letter, a digit, or `_`.
-  GitHub also wants a single `$` to touch its formula.
-- In Obsidian, the opening `$` may not be followed by a space, and a `$` closes
-  the formula only if no space stands before it and no digit follows it.
-  Obsidian's Reading view and Live Preview differ in two cases; the tool follows
-  the one that shows more as a formula.
-
-`From $5 to 10$` is a formula to all four renderers and stays one for the tool.
-Display math is unchanged everywhere. The conditions come from about 150 cases
-rendered by the renderers themselves, which are now part of the tests.
-
-## Plugins
-
-- A plugin named as a package is resolved the way Node.js resolves an `import`
-  written in the configuration file, with a fallback to its CommonJS rules. A
-  package that declares only an `import` entry now loads
-  ([PR #125](https://github.com/viell-dev/slop-markdown-tools/pull/125)).
-- Conditions set when Node.js is started, with `--conditions` or `--no-addons`
-  on its command line or in `NODE_OPTIONS`, apply to that lookup
-  ([PR #144](https://github.com/viell-dev/slop-markdown-tools/pull/144)).
-- A plugin that cannot be loaded is reported as
-  `Cannot load plugin "NAME" named in FILE: REASON`, and one without a usable
-  default export as `Invalid plugin "NAME" named in FILE`. A plugin named by a
-  path where no file is gets the reason `no file at PATH`.
-- The configuration reference describes the `plugins` key, and the plugin guide
-  describes how a rule resolves a link: the call, the statuses, and the fields
-  of the result
-  ([PR #158](https://github.com/viell-dev/slop-markdown-tools/pull/158)).
-
-## Clearer messages
-
-- `lint` ends with a count of what it reported, as in
-  `3 file(s) linted; 1 error(s), 2 warning(s).` It used to end with
-  `0 would change`, whatever it found.
-- A path given on the command line that does not exist, is of the wrong kind, or
-  may not be read is answered in the tool's words, such as
-  `Workspace root does not exist: …`, `Configuration file cannot be read: …`,
-  `Input does not exist: …`, or `Excluded path cannot be read: …`, where the
-  system's raw message used to appear.
-- An error in a configuration file names the file
-  ([PR #143](https://github.com/viell-dev/slop-markdown-tools/pull/143)).
-
-## Memory, speed, and installation size
-
-- The link index keeps the anchors of each linked document, not its parsed form.
-  Linting a large real-world vault needed about half the memory
-  ([PR #135](https://github.com/viell-dev/slop-markdown-tools/pull/135)).
-- For the Obsidian dialect, the tables for finding a note by name held about 1.6
-  kB for every file of the workspace, attachments included. They now hold about
-  70 bytes per file
-  ([PR #149](https://github.com/viell-dev/slop-markdown-tools/pull/149)).
-- The package no longer installs KaTeX, which the tool never used: 4.6 MB less
-  on disk, a faster start, and no KaTeX advisory in a consumer's `npm audit`.
-  The math tokenizer is now the project's own, adapted from
-  `micromark-extension-math`; its license notice ships as `THIRD_PARTY_NOTICES`
-  ([PR #150](https://github.com/viell-dev/slop-markdown-tools/pull/150)).
-- A document that is one very long list parses in about half the time, through
-  an update of the syntax-tree builder
-  ([PR #155](https://github.com/viell-dev/slop-markdown-tools/pull/155)).
-
-The [benchmark page](../benchmarks.md) has new reference results and states two
-limits of the parser that were measured for this release: one document needs
-about 70 to 130 times its size in memory while it is parsed, and a single
-paragraph of 100 kB or more that is full of inline constructs parses slowly.
-
-## Examples, benchmarks, and documentation
-
-The package now ships working examples: starting configurations, workspaces
-before and after formatting, a plugin, and library scripts, described on the
-[examples page](../examples.md). `npm run benchmark` measures the tool on
-generated documents. The tests are split into a unit suite and an integration
-suite that runs the built command line on real files and checks the examples and
-the documentation against the tool
-([PR #111](https://github.com/viell-dev/slop-markdown-tools/pull/111)). Code
-blocks on the documentation site fit 80 columns
-([PR #129](https://github.com/viell-dev/slop-markdown-tools/pull/129)).
-
-## Compatibility and verification
-
-Existing `0.2.0-rc.1` configurations remain accepted, and the Node.js minimum is
-unchanged. The API and configuration remain provisional until the first stable
-release.
-
-For library hosts:
-
-- `lint`, `format`, and `resolveConfig` accept `defaultDialect`. `resolveConfig`
-  takes it as its fourth argument.
-- `WorkspaceOptions` adds `unreadable`, `vaults`, and `rootInVault`.
-- `LinkResolution` adds the status `unreadable` and the fields `unreadable`,
-  `vault`, `rooted`, and `outside`. A rule must not rewrite a resolved link
-  whose `unreadable` field is set; the built-in rules do not, and the engine
-  refuses an edit that respells such a link.
-- A Markdown source given as a loader function can be called again when a later
-  link to the same file is checked for a dialect with different anchors. It was
-  called at most once before. Loaders must return the same text each time.
-- A loader that throws an error with the code `EACCES` or `EPERM` marks the file
-  as unreadable instead of failing the run.
-
-Runtime dependencies: `import-meta-resolve@4.2.0`,
-`micromark-factory-space@2.1.0`, and `micromark-util-character@2.1.1` are new
-direct dependencies; `micromark-extension-math` is gone, and with it `katex`;
-`mdast-util-from-markdown` is `2.1.0`. Development tools have also been updated.
-
-Known limits that this release documents and does not remove: GitHub accepts an
-escaped `\$` as the start of a formula and the tool does not; a workspace root
-inside a vault cannot check links to notes outside it; and the two parser limits
-named above. See [design and limitations](../design.md) for the detailed
-boundaries.
-
-The release was checked with 902 automated tests on Linux and Windows, with the
-installed package on all three CI targets, and by comparing reports before and
-after on a large real-world vault.

package/docs/releases.md

@@ -1,144 +0,0 @@
-# Releases
-
-## Versions and availability
-
-These documents cover `mdrefine@0.2.0-rc.2`. The executable is `mdtools`;
-prereleases use the npm channel named after their prerelease identifier, `rc`
-for release candidates and `beta` for betas. Read the
-[0.2.0-rc.2 release notes](releases/0.2.0-rc.2.md) for changes and limitations.
-Previous releases: [0.2.0-rc.1](releases/0.2.0-rc.1.md),
-[0.1.0-rc.1](releases/0.1.0-rc.1.md), [beta.4](releases/0.1.0-beta.4.md),
-[beta.3](releases/0.1.0-beta.3.md), [beta.2](releases/0.1.0-beta.2.md), and
-[beta.1](releases/0.1.0-beta.1.md).
-
-The registry is the source of truth for package availability:
-
-```sh
-npm view mdrefine@0.2.0-rc.2 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.
-
-The npm package is published under account `viell`. Until the first stable
-release, `latest` points to the newest prerelease of any kind, alongside its
-channel tag such as `rc` or `beta`, so default installations receive fixes. Once
-a stable release exists, `latest` follows stable releases and prerelease channel
-tags remain separate.
-
-## 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.2.0-rc.2.tgz --dry-run --ignore-scripts --access public --tag rc
-```
-
-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 runs full checks on Linux/Node.js 24, compatibility tests on
-Linux/Node.js 22 and Windows/Node.js 24, and installed-package checks on all
-three targets.
-
-## Publication prerequisites
-
-Publication requires explicit authorization from the repository owner for each
-release. Preparing a PR or artifact does not supply that authorization. For
-subsequent releases, verify these prerequisites rather than repeating the
-completed bootstrap:
-
-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 three CI checks. The workflow uses Node.js 24 and
-   checks that npm supports trusted publishing.
-5. Repository variable `NPM_PUBLISH_ENABLED` is `true` after verified trusted
-   publisher setup. This enables the workflow's capability; it does not
-   authorize a release. Preparation uses `publish: false` regardless of this
-   variable's value.
-
-Trusted-publisher settings were verified on 2026-09-18. The first release used
-local authentication and has no OIDC provenance. For workflow releases, verify
-the publication job and the registry provenance attestations after each release.
-
-## Publish an authorized prerelease
-
-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 the npm channel matching its prerelease identifier (`rc` or
-`beta`) 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 and
-rc versions and derives the channel tag from the version. Complete the npm tag
-synchronization below before reporting a pre-stable release complete.
-
-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.
-
-GitHub enforces immutability for future releases and their assets. Attach all
-assets before publishing a release. The existing beta.1 release predates that
-setting, so its assets are not retroactively locked; its version tag remains
-protected by the repository ruleset. Do not replace its assets or recreate the
-release to change that history.
-
-## Synchronize npm tags before the first stable release
-
-After each authorized prerelease publication, wait for npm processing to finish
-and verify that the channel tag (`rc` today) points to the expected version.
-Until the first stable release, move `latest` to that same version using an
-authenticated local npm session. For the current release candidate:
-
-```sh
-npm_config_cache="$PWD/.npm-cache" npm dist-tag add mdrefine@0.2.0-rc.2 latest
-npm_config_cache="$PWD/.npm-cache" npm dist-tag ls mdrefine
-```
-
-Use the exact newly published version on future releases. npm's
-[OIDC authentication](https://docs.npmjs.com/trusted-publishers/) supports
-publication, but does not authenticate `dist-tag` updates. The Release workflow
-records this required follow-up in its summary; complete browser authentication
-locally if npm requests it. Keep the waiting command alive and never put
-authentication secrets in chat or repository files.
-
-Tag synchronization is part of an authorized prerelease. It does not publish
-another version or change package contents. If promotion fails, retry only the
-tag update after resolving authentication; never rerun publication. Stop
-promoting prereleases to `latest` when the first stable release is published.
-
-Verify both tags, a fresh default installation, the GitHub release and its
-assets, registry provenance, and the documentation site before reporting the
-release complete. All subsequent changes, including prerelease maintenance,
-continue through PRs.

package/docs/testing.md

@@ -1,93 +0,0 @@
-# Testing
-
-The tests are split by what they exercise. Unit tests call the library's source
-directly. Integration tests run the built command-line tool and library the way
-a consumer does: as a separate process, against real files.
-
-```sh
-npm test                    # build, then run both suites
-npm run test:unit           # library behavior only; needs no build
-npm run test:integration    # build, then the CLI, examples, and documentation
-npm run test:package        # pack, install into a temporary project, and use it
-```
-
-The two suites run one after the other, never at the same time: integration
-tests start many processes, and that load would make the time limits of a few
-unit tests unreliable. `npm run check` runs both suites after the type, lint,
-formatting, and documentation-site checks. GitHub Actions runs them on Linux
-with Node.js 22 and 24 and on Windows with Node.js 24.
-
-## Unit tests
-
-`tests/unit/` imports from `src/` and touches neither the filesystem nor other
-processes. A test formats or lints a string and checks the result, usually
-together with the contracts every formatting change must keep: the output is
-stable when formatted again, the parsed meaning is unchanged, and disabling the
-rule leaves the source as written.
-
-| File                   | Covers                                                                                                                          |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `engine.test.ts`       | Edit application, formatting phases, safety checks, configuration, plugins                                                      |
-| `rules.test.ts`        | Each built-in style and problem rule, per dialect                                                                               |
-| `wrap.test.ts`         | Prose wrapping, including property-based tests and a linear-time check                                                          |
-| `callout-wrap.test.ts` | Wrapping inside Obsidian callouts                                                                                               |
-| `links.test.ts`        | Link and fragment resolution for every dialect, including generated anchors and unreadable paths                                |
-| `structure.test.ts`    | Document structure rules                                                                                                        |
-| `math.test.ts`         | Where dollar math begins and ends in each dialect, compared with what GitHub, Forgejo, and Gitea rendered (`math-renderers.ts`) |
-
-A defect in how a rule reads or rewrites Markdown belongs here, as the smallest
-synthetic document that shows it.
-
-## Integration tests
-
-`tests/integration/` runs `dist/cli/main.js` as a child process in temporary
-workspaces, and runs the files under `examples/` and `benchmarks/` as they are.
-These tests catch what unit tests cannot: file discovery, configuration loading,
-exit codes, output streams, line endings and file names on disk, and
-documentation that no longer matches the tool.
-
-| File                 | Covers                                                                                                              |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `cli.test.ts`        | Commands, flags, exit codes, discovery, ignore rules, the assumed dialect, and write safeguards                     |
-| `workflows.test.ts`  | Whole tasks: mixed-dialect workspaces, CRLF files, non-ASCII paths, JSON reports, plugin loading                    |
-| `examples.test.ts`   | Every example: configurations load, `before/` formats into `after/`, scripts print what is shown                    |
-| `docs.test.ts`       | Documentation against the code: rule and preset tables, configuration snippets, the examples page, code block width |
-| `benchmarks.test.ts` | The benchmark suite runs, and its synthetic documents format cleanly                                                |
-
-`support.ts` holds the shared helpers: `fixture()` writes a temporary workspace
-that is removed after the test, `copyOf()` copies a folder of the repository
-somewhere a test may write, and `run()` starts the CLI. `restrict()` takes a
-path's permissions away until the test ends. Tests that need an unreadable path
-are skipped on Windows and for the root user, where permissions cannot be taken
-away; `links.test.ts` covers the library's part everywhere, by telling the
-workspace which paths are unreadable.
-
-A defect in how the tool behaves as a program belongs here: which files it
-selects, what it prints, what it writes, and how it exits.
-
-## Installed package check
-
-`npm run test:package` packs the package, installs the tarball into a temporary
-project, and then runs the installed `mdtools` command, imports the library,
-runs a shipped example, and compiles a TypeScript consumer against the published
-types. It can need access to the npm registry, so it is separate from
-`npm test`.
-
-## Known defects
-
-A test marked `it.fails` reproduces a confirmed defect that is not fixed yet. It
-passes while the defect exists and fails once the defect is gone, which is the
-signal to remove the marker. Each one has a comment describing the defect and
-naming its issue. There are currently none.
-
-## Speed
-
-The benchmark is not a test and never fails on a slow result, because shared CI
-machines vary too much for a time limit on ordinary input to be reliable.
-`benchmarks.test.ts` only checks that it still runs. See
-[benchmarks](benchmarks.md) for the measurements and how to read them.
-
-A few unit tests do guard against one kind of slowness: an algorithm whose cost
-grows faster than its input. They give an unusual input, such as thousands of
-unclosed tags, a generous time limit, or compare the time for two input sizes.
-Add such a test with the fix when a defect of that kind is found.