mdrefine 0.1.0-beta.1 → 0.1.0-beta.3

package/docs/contributing.md

@@ -28,8 +28,8 @@ respectful and focused on reproducible behavior; harassment and disclosure of
 private data are not acceptable. Contributions are provided under the MIT
 license.
 
-The branch policy requires the four platform checks and resolved review threads.
-It does not require approval from a second account: this project is
+The branch policy requires the three CI checks and resolved review threads. It
+does not require approval from a second account: this project is
 agent-maintained and cannot assume another maintainer is available. Request
 independent review when available, especially for file writes and release
 automation. Passing CI is not a claim of human review.
@@ -41,6 +41,77 @@ versions and release tags are never replaced. Follow the
 reports belong in the private channel described in
 [SECURITY.md](https://github.com/viell-dev/slop-markdown-tools/blob/main/SECURITY.md).
 
+## Issue and pull request labels
+
+Use one primary `Type:` label on every issue and PR, and at most one `Status:`
+label describing the current disposition or next action. The type describes what
+the item is about; a feature implementation PR also uses
+`Type: Feature Request`. For mixed historical items, choose the main purpose and
+explain separate decisions in comments. Split new requests when their parts need
+independent scope decisions. Do not add priority labels.
+
+The
+[label catalog](https://github.com/viell-dev/slop-markdown-tools/blob/main/.github/labels.json)
+is the source of truth for exact names, descriptions, and hexadecimal colors.
+Keep it, this guide, GitHub, issue templates, and Dependabot settings aligned.
+Use the GitHub UI or the existing `gh` CLI; no label-sync service is required.
+
+| Label                       | Color     | Use                                                                          |
+| --------------------------- | --------- | ---------------------------------------------------------------------------- |
+| `Type: Bug`                 | `#d73a4a` | Incorrect behavior, broken functionality, or a regression.                   |
+| `Type: Enhancement`         | `#a2eeef` | Improve an existing capability, including usability or performance.          |
+| `Type: Feature Request`     | `#0e8a16` | Add a new independently useful capability or rule.                           |
+| `Type: Maintenance`         | `#6a737d` | Dependencies, CI, releases, refactoring, or repository upkeep.               |
+| `Type: Documentation`       | `#0075ca` | Documentation, examples, or contributor instructions.                        |
+| `Type: Discussion`          | `#5319e7` | Explore a design or project direction before an actionable proposal.         |
+| `Type: Question`            | `#d876e3` | Ask how the project works or how to use it.                                  |
+| `Status: Needs Triage`      | `#ededed` | Awaiting maintainer review and a scope decision.                             |
+| `Status: Confirmed`         | `#0e8a16` | Reproduced defect or accepted actionable request; not a delivery commitment. |
+| `Status: Needs Information` | `#fbca04` | Waiting for reporter details, answers, or validation results.                |
+| `Status: Blocked`           | `#d93f0b` | Accepted work is waiting on an identified external dependency.               |
+| `Status: Can't Reproduce`   | `#fef2c0` | A documented reproduction attempt did not reproduce the report.              |
+| `Status: Duplicate`         | `#cfd3d7` | Already tracked elsewhere; link the canonical issue or PR.                   |
+| `Status: Won't Do`          | `#666666` | Declined as out of scope or unsuitable in its proposed form.                 |
+| `Good First Issue`          | `#7057ff` | A scoped, ready task with a clear approach and beginner-friendly validation. |
+| `Help Wanted`               | `#008672` | A scoped, accepted task for which outside contributions are welcome.         |
+
+Review labels whenever answering, triaging, implementing, closing, reopening, or
+otherwise updating an issue or PR:
+
+- Replace `Status: Needs Triage` after review. Use `Status: Confirmed` only for
+  a reproduced defect or an accepted request within project scope; neither
+  reproduction nor acceptance follows automatically from a report.
+- When waiting on the reporter, use `Status: Needs Information` and state what
+  evidence is needed. Use `Status: Blocked` for an identified external
+  dependency, with a link and an unblock condition. Choose the immediate next
+  action rather than stacking statuses.
+- Use `Status: Can't Reproduce` only after documenting the attempted version,
+  input, and result. An incomplete report first needs information.
+- On duplicate closure, link the canonical item and retain `Status: Duplicate`.
+  On rejection, explain the scope or suitability decision and retain
+  `Status: Won't Do`. A declined proposal can be reconsidered with new evidence.
+- On successful completion or merge, remove transient status labels and retain
+  the type. GitHub's open/closed/merged state records completion; there is no
+  redundant Done or Merged label. A closed, unmerged PR should retain its
+  applicable disposition, rather than being labeled as completed.
+- On reopening, reassess the evidence and replace the old disposition; do not
+  carry a stale rejection, duplicate, or information request forward.
+- Apply `Good First Issue` only to a ready, well-explained beginner task,
+  together with `Help Wanted`. Remove both when the item closes or is no longer
+  ready for contribution. Waiting for a reporter's private-workspace benchmark
+  is not a general help request.
+
+Colors follow familiar GitHub cues: red for defects, blue for documentation,
+green for accepted work, yellow/orange for missing information or blockers, and
+gray for neutral or declined dispositions. Names carry the meaning without
+relying on color. The unprefixed contributor labels follow
+[GitHub's label conventions](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels);
+the readiness criteria draw on the
+[Kubernetes contributor guide](https://www.kubernetes.dev/docs/guide/help-wanted/).
+The `Type:` / `Status:` grouping also appears in
+[community label catalogs](https://gist.github.com/dysfunc/fc722e865a6a960a2d9c5ecf43f5a963);
+this repository intentionally uses a smaller set.
+
 ## Develop locally
 
 Follow the [checkout setup](quick-start.md#install-from-the-repository), then:
@@ -55,9 +126,20 @@ site build, and regression/property/CLI tests. `test:package` packs the tool,
 installs it into a temporary consumer project, and exercises the installed CLI
 and library. It can require access to the npm registry.
 
-GitHub Actions verifies Linux with Node.js 22 and 24, plus macOS and Windows
-with Node.js 24. Keep changes scoped and describe remaining limitations in the
-pull request. Agent contributors should also read the repository's
+GitHub Actions runs the full `check` and dependency audit on Linux with
+Node.js 24. Linux with Node.js 22 and Windows with Node.js 24 run the build and
+tests; all three jobs verify the installed package. Linting, formatting checks,
+and documentation builds run once rather than on every platform. Superseded PR
+runs are canceled.
+
+Runtime dependencies have no OS-specific installation constraints. Development
+tooling does include native platform packages, but that alone does not justify
+repeating the full toolchain matrix. Windows coverage protects filesystem path
+handling and installed command behavior; it has already caught a path-alias
+regression. macOS is not a routine CI target.
+
+Keep changes scoped and describe remaining limitations in the pull request.
+Agent contributors should also read the repository's
 [AGENTS.md](https://github.com/viell-dev/slop-markdown-tools/blob/main/AGENTS.md).
 
 ## Write and preview documentation

package/docs/design.md

@@ -59,11 +59,34 @@ Heading nesting paths, property aliases, PDF subpaths, and every Obsidian
 plugin's syntax are not fully supported. Embeds are preserved as embeds; image
 dimensions in their aliases remain intact.
 
-All eligible Markdown is currently parsed into an in-memory workspace index.
-There is no persistent cache, watch service, editor extension, or language
-server yet. Use directory selection to scope output; indexing still needs the
-containing workspace for cross-document links. The library has a pluggable
-workspace interface for specialized hosts.
+The workspace indexes eligible paths first and parses target Markdown only when
+a fragment is checked, caching the result for that invocation. CLI discovery
+also defers reading Markdown until it is selected or needed for a fragment.
+Built-in rule-schema validators are reused across documents. A suffix lookup
+index is built on first use instead of scanning every path for each shortened
+link. There is no persistent cache, worker pool, watch service, editor
+extension, or language server yet. The library has a pluggable workspace
+interface for specialized hosts.
+
+Run `npm run build` and `node scripts/benchmark.mjs 1000` for a reproducible
+synthetic library benchmark. It reports path-index construction and lint time
+separately for 1,000 short interlinked notes; pass a different count to scale
+it. These timings exclude filesystem traversal and do not predict a particular
+vault's throughput. Measure the original workload before adding caches or
+workers.
+
+Formatting retains the current parsed document within one call, reusing it
+between phases and for final diagnostics. Every changed candidate is parsed and
+checked against the original semantic fingerprint before becoming the next
+phase's input. No-op edits still undergo range and overlap validation. This
+retains the plugin contract that rules must not mutate documents.
+
+Run `node scripts/benchmark-format.mjs 100` after building to compare 100
+formatting calls on a synthetic 4.8 KB note needing edits with 100 calls on its
+already-formatted output. It warms both cases, checks output and diagnostics,
+and prints a result hash for comparing implementations. Run several times
+without competing workloads; timings exclude discovery, I/O, CLI serialization,
+and custom plugins.
 
 ## Maintenance priorities
 

package/docs/plugins.md

@@ -26,10 +26,17 @@ const result = format(files["note.md"], options);
 
 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.
+non-Markdown attachments. A Markdown value can also be a synchronous loader
+`() => string`; `createWorkspace` calls it only when that target needs fragment
+validation, then caches its parsed heading/block index. Callers must provide a
+stable source snapshot for each workspace instance. The CLI provides its own
+per-invocation file loaders. `WorkspaceOptions.directories` can list existing
+empty directories; parent directories of file entries are inferred. Resolution
+returns `status: "directory"` for a directory instead of `"missing"`.
+
+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

package/docs/quick-start.md

@@ -9,7 +9,7 @@ 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
+npm install --save-dev --save-exact mdrefine@0.1.0-beta.3
 npx --no-install mdtools --help
 ```
 

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

@@ -0,0 +1,83 @@
+# mdrefine 0.1.0-beta.2
+
+Second public beta 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.1.0-beta.2
+```
+
+## Correctness fixes
+
+- Measure protected Markdown markers together with their preceding word before
+  wrapping, avoiding preventable line-width overflow.
+- Prefer exact Obsidian workspace-root targets before suffix matches, respect
+  explicit relative paths, and verify target identity before rewriting links.
+- Preserve compliant literal destination spelling, including `?` and `%`, and
+  escape literal percent/hash characters correctly when generating paths.
+- Recognize existing directory targets instead of reporting them as missing.
+  Obsidian receives a directory-specific diagnostic; CommonMark/GitHub links can
+  resolve to directories. Directories are not rewritten to README files.
+- Compare code-span line endings using their rendered space value while keeping
+  other code whitespace significant, allowing safe inline-code formatting.
+- Fix parsing of inline Obsidian comments spanning several physical lines.
+
+## New controls
+
+- Opt-in `style/inline-code` joins multiline code spans without changing their
+  parsed content, including spans in lists and blockquotes.
+- `style/wrap.measure: "codepoints"` counts Unicode scalar values instead of
+  display columns. Display columns remain the default.
+- `style/wrap.reportUnreflowed` and `reportUnbreakable` optionally explain
+  protected paragraphs and remaining unbreakable overflow without changing
+  formatting safety or check-mode semantics.
+- `resolve.gitIgnored` and `resolve.nestedRepositories` opt into additional link
+  targets independently of files selected for linting or writing.
+- Repeatable `--exclude <path>` omits literal files or directory subtrees from
+  processing while preserving them in the link index. Filesystem aliases are
+  canonicalized consistently, including Windows short paths.
+- Opt-in `structure/initial-heading` checks for an initial level-1 heading after
+  optional YAML/TOML front matter. It never edits content.
+
+See
+[configuration](https://viell-dev.github.io/slop-markdown-tools/configuration.html)
+and [CLI workflows](https://viell-dev.github.io/slop-markdown-tools/cli.html)
+for options, defaults, and examples.
+
+## Performance and library API
+
+Workspace indexing is path-only until a target's headings or block IDs are
+needed. Fragment parsing, suffix lookups, and built-in schema validation reuse
+cached work within their documented lifetimes; custom schema IDs stay isolated
+between calls. A synthetic benchmark is available in `scripts/benchmark.mjs` in
+the source checkout. Validation on the original large workspace remains pending
+in [#23](https://github.com/viell-dev/slop-markdown-tools/issues/23); no
+persistent index cache or worker pool is included.
+
+`createWorkspace` accepts lazy Markdown source loaders and explicit directory
+entries. Exhaustive consumers of `LinkResolution.status` must handle the new
+`"directory"` result. Consumers constructing `ResolvedConfig` directly must
+provide `resolve` (use `{}` for the defaults); `resolveConfig()` provides it for
+normal callers. See the
+[library API](https://viell-dev.github.io/slop-markdown-tools/plugins.html).
+
+## Compatibility and project scope
+
+Beta.1 configurations remain supported. The CLI name and Node.js minimum are
+unchanged; new formatting and structural controls are opt-in.
+
+For users of intermediate source checkouts, these additions were removed before
+this release: `style/wrap.keepLabelWithAtom`, `--changed`, `--staged`,
+`structure/title-matches-filename`, `structure/metadata-line`, and
+`style/accidental-marker`. Remove those settings and implement consumer-specific
+policies in plugins or wrappers. Git callers can supply explicit paths while
+retaining workspace resolution; skip the CLI invocation for an empty selection.
+These removals do not remove any published beta.1 feature.
+
+Modified-date mutation remains consumer-owned. Semantic guards, conservative
+handling of unsupported constructs, and Obsidian's verified strict-line-break
+requirement remain in force. The plugin API and configuration are provisional.
+
+Repository maintenance now includes explicit issue-scope review and a documented
+label taxonomy. Full CI runs on Linux/Node.js 24, with compatibility and
+installed-package checks on Linux/Node.js 22 and Windows/Node.js 24.

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

@@ -0,0 +1,61 @@
+# mdrefine 0.1.0-beta.3
+
+Third public beta 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.1.0-beta.3
+```
+
+## Correct wrap diagnostics
+
+Protected paragraphs now distinguish breakable prose from indivisible inline
+atoms. A hard-break paragraph whose only over-width content is a long link, code
+span, or other protected atom no longer triggers `reportUnreflowed`. That
+overflow follows `reportUnbreakable`, including when reflow is skipped. A
+paragraph containing both causes can report both when enabled.
+
+Whitespace inside protected inline nodes is not a wrapping opportunity.
+Container prefixes count toward width; hard-break markers are excluded from
+protected-line width. Both diagnostic options remain disabled by default and
+propose no edits. Protected paragraph source remains unchanged.
+
+Fixed in [PR #36](https://github.com/viell-dev/slop-markdown-tools/pull/36),
+resolving [#34](https://github.com/viell-dev/slop-markdown-tools/issues/34).
+Regression coverage includes both hard-break forms, LF/CRLF, lists, quotes, task
+items, Unicode width measurement, and Obsidian's strict-line-break gate.
+
+## Faster formatting
+
+The formatter reuses the current parsed document between phases and for final
+diagnostics. It parses each changed candidate and validates its meaning before
+accepting it. Edit-range, overlap, oscillation, and convergence checks remain in
+force; no persistent cache or worker pool is introduced.
+
+A warmed synthetic benchmark improved approximately 2.3 times for input needing
+edits and 2.6 times for already-formatted input, with identical result hashes.
+On the reporter's 8,362-document, 36 MB workspace, `format --check --json` fell
+from 314 to 121 seconds, with the same 6,960 would-change files and no remaining
+diagnostics after formatting. These are workload-specific results, not a
+throughput guarantee.
+
+Implemented in
+[PR #37](https://github.com/viell-dev/slop-markdown-tools/pull/37), resolving
+[#35](https://github.com/viell-dev/slop-markdown-tools/issues/35).
+Original-workload validation in
+[#23](https://github.com/viell-dev/slop-markdown-tools/issues/23#issuecomment-5735871369)
+also confirms the beta.2 indexing improvements and correct link diagnostics; the
+performance issue is now closed. The source checkout includes
+`scripts/benchmark-format.mjs` for reproducible formatting measurements.
+
+## Compatibility
+
+No dependency, public API, configuration-schema, or Node.js minimum changes.
+Existing beta.2 configurations remain valid. Consumers enabling wrap diagnostics
+may see findings move from `reportUnreflowed` to `reportUnbreakable`; this is
+the intentional classification correction described above.
+
+The API and configuration remain provisional. Semantic guards, conservative
+handling of unsupported constructs, and Obsidian's verified strict-line-break
+requirement remain in force. Repository agent instructions now also prohibit
+self-references in GitHub issue and PR posts.

package/docs/releases.md

@@ -2,14 +2,16 @@
 
 ## Versions and availability
 
-These documents cover `mdrefine@0.1.0-beta.1`. The executable is `mdtools`;
+These documents cover `mdrefine@0.1.0-beta.3`. 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.
+[beta.3 release notes](releases/0.1.0-beta.3.md) for changes and limitations.
+Previous releases: [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.1.0-beta.1 version --registry=https://registry.npmjs.org/
+npm view mdrefine@0.1.0-beta.3 version --registry=https://registry.npmjs.org/
 ```
 
 An `E404` means the requested package or version is unavailable. A version in
@@ -17,6 +19,12 @@ 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 initial beta was published locally under npm account `viell`. npm assigned
+both `beta` and `latest` to `0.1.0-beta.1` despite an explicit `--tag beta`;
+removing `latest` returned E400. Both tags were accepted for that release.
+Continue using `--tag beta` for subsequent betas and verify tags after
+publishing.
+
 ## Prepare without publishing
 
 Use Node.js 24 and npm 10 or newer from a clean checkout:
@@ -24,7 +32,7 @@ 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
+npm publish ./artifacts/mdrefine-0.1.0-beta.3.tgz --dry-run --ignore-scripts --access public --tag beta
 ```
 
 Preparation runs all checks, packs the allowlisted files, installs that exact
@@ -36,12 +44,15 @@ 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.
+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 operator authorization. Preparing a PR or artifact
-does not supply that authorization. Before the first publication:
+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.
@@ -56,10 +67,16 @@ does not supply that authorization. Before the first publication:
    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
+   still require PRs and the three 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.
+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 beta
 
@@ -69,7 +86,8 @@ 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.
+workflow accepts only beta versions and requests the `beta` tag. See the
+initial-publication exception above before interpreting `latest`.
 
 For an authenticated first publication that cannot use OIDC yet, use the exact
 reviewed tarball with `npm publish <tarball> --ignore-scripts --access public
@@ -85,6 +103,12 @@ 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.
+
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdrefine",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "Configurable Markdown linting and formatting for CommonMark, GitHub, and Obsidian",
   "type": "module",
   "license": "MIT",