mdrefine 0.1.0-beta.1

package/dist/workspace/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/workspace/files.ts"],"names":[],"mappings":"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","sourcesContent":["import { lstat, readdir, readFile, realpath, open, rename, unlink } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { randomUUID } from \"node:crypto\";\nimport ignore from \"ignore\";\nimport { minimatch } from \"minimatch\";\nimport { exists } from \"../config/load.js\";\n\nexport interface FileSet {\n  root: string;\n  files: Record<string, string | null>;\n  selected: string[];\n  strictLineBreaks?: boolean;\n}\nexport async function discover(\n  rootPath: string,\n  supplied: string[],\n  excluded: string[],\n): Promise<FileSet> {\n  const root = await realpath(rootPath);\n  const files: Record<string, string | null> = {};\n  const selected: string[] = [];\n  const requests: string[] = [];\n  for (const input of supplied.length ? supplied : [root]) {\n    const absolute = path.resolve(input);\n    if ((await lstat(absolute)).isSymbolicLink())\n      throw new Error(`Refusing symbolic-link input: ${input}`);\n    const resolved = await realpath(absolute);\n    const relative = path.relative(root, resolved).split(path.sep).join(\"/\");\n    if (relative.startsWith(\"../\") || relative === \"..\" || path.isAbsolute(relative))\n      throw new Error(`Input is outside the workspace: ${input}`);\n    requests.push(relative);\n  }\n  interface IgnoreLayer {\n    base: string;\n    matcher: ReturnType<typeof ignore>;\n  }\n  async function walk(relative: string, inherited: IgnoreLayer[]) {\n    const directory = path.join(root, relative);\n    const layers = [...inherited];\n    if (await exists(path.join(directory, \".gitignore\")))\n      layers.push({\n        base: relative,\n        matcher: ignore().add(await readFile(path.join(directory, \".gitignore\"), \"utf8\")),\n      });\n    for (const entry of await readdir(directory, { withFileTypes: true })) {\n      if (\n        [\".git\", \".obsidian\", \"node_modules\", \".npm-cache\", \"dist\", \"coverage\"].includes(\n          entry.name,\n        ) ||\n        entry.isSymbolicLink()\n      )\n        continue;\n      const name = relative ? `${relative}/${entry.name}` : entry.name;\n      if (\n        layers.some((layer) =>\n          layer.matcher.ignores(\n            name.slice(layer.base ? layer.base.length + 1 : 0) + (entry.isDirectory() ? \"/\" : \"\"),\n          ),\n        )\n      )\n        continue;\n      const full = path.join(root, name);\n      if (entry.isDirectory()) {\n        if (!(await exists(path.join(full, \".git\")))) await walk(name, layers);\n      } else if (entry.isFile()) {\n        const markdown = /\\.md$/i.test(name);\n        files[name] = markdown ? await readFile(full, \"utf8\") : null;\n        if (\n          markdown &&\n          requests.some(\n            (request) => !request || name === request || name.startsWith(`${request}/`),\n          ) &&\n          !excluded.some((pattern) => minimatch(name, pattern, { dot: true }))\n        )\n          selected.push(name);\n      }\n    }\n  }\n  await walk(\"\", []);\n  let strictLineBreaks: boolean | undefined;\n  const app = path.join(root, \".obsidian\", \"app.json\");\n  if (await exists(app)) {\n    const settings: unknown = JSON.parse(await readFile(app, \"utf8\"));\n    strictLineBreaks =\n      typeof settings === \"object\" &&\n      settings !== null &&\n      \"strictLineBreaks\" in settings &&\n      settings.strictLineBreaks === true;\n  }\n  return {\n    root,\n    files,\n    selected: selected.sort(),\n    ...(strictLineBreaks !== undefined ? { strictLineBreaks } : {}),\n  };\n}\nexport async function writeAtomic(file: string, before: string, after: string): Promise<void> {\n  const info = await lstat(file);\n  if (!info.isFile() || info.isSymbolicLink())\n    throw new Error(`Refusing non-regular file: ${file}`);\n  if ((await readFile(file, \"utf8\")) !== before)\n    throw new Error(`File changed during formatting: ${file}`);\n  const temporary = path.join(path.dirname(file), `.mdtools-${randomUUID()}.tmp`);\n  const handle = await open(temporary, \"wx\", info.mode);\n  try {\n    await handle.writeFile(after, \"utf8\");\n    await handle.chmod(info.mode);\n    await handle.sync();\n    await handle.close();\n    const current = await lstat(file);\n    if (\n      current.isSymbolicLink() ||\n      current.ino !== info.ino ||\n      (await readFile(file, \"utf8\")) !== before\n    )\n      throw new Error(`File changed before replacement: ${file}`);\n    await rename(temporary, file);\n  } finally {\n    await handle.close();\n    await unlink(temporary).catch((error: NodeJS.ErrnoException) => {\n      if (error.code !== \"ENOENT\") throw error;\n    });\n  }\n}\n"]}

package/dist/workspace/index.d.ts

@@ -0,0 +1,10 @@
+import type { Dialect, Workspace } from "../core/types.js";
+export interface WorkspaceOptions {
+    dialect?: Dialect;
+    strictLineBreaks?: boolean;
+}
+export declare function splitDestination(destination: string): {
+    path: string;
+    fragment: string;
+};
+export declare function createWorkspace(files: Record<string, string | null>, options?: WorkspaceOptions): Workspace;

package/dist/workspace/index.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import GithubSlugger from "github-slugger";
+import { visit } from "unist-util-visit";
+import { parse, textContent } from "../syntax/parse.js";
+export function splitDestination(destination) {
+    const hash = destination.indexOf("#");
+    const decode = (value) => {
+        try {
+            return decodeURIComponent(value);
+        }
+        catch {
+            return value;
+        }
+    };
+    return {
+        path: decode(hash < 0 ? destination : destination.slice(0, hash)),
+        fragment: decode(hash < 0 ? "" : destination.slice(hash + 1)),
+    };
+}
+export function createWorkspace(files, options = {}) {
+    const entries = new Map();
+    for (const [name, source] of Object.entries(files)) {
+        const entry = { headings: new Set(), slugs: new Set(), blocks: new Set() };
+        if (source !== null && /\.md$/i.test(name)) {
+            const document = parse(source, options.dialect ?? "commonmark", name);
+            const slugger = new GithubSlugger();
+            visit(document.tree, "heading", (node) => {
+                const text = textContent(node);
+                entry.headings.add(text);
+                entry.slugs.add(slugger.slug(text));
+            });
+            visit(document.tree, "text", (node) => {
+                const match = /(?:^|\s)\^([A-Za-z0-9-]+)\s*$/.exec(node.value);
+                if (match)
+                    entry.blocks.add(match[1]);
+            });
+        }
+        entries.set(name.replaceAll("\\", "/").replace(/^\.\//, ""), entry);
+    }
+    return {
+        ...(options.strictLineBreaks !== undefined
+            ? { strictLineBreaks: options.strictLineBreaks }
+            : {}),
+        resolve(source, destination, dialect) {
+            if (/^[a-z][a-z\d+.-]*:/i.test(destination) || destination.startsWith("//"))
+                return { status: "external" };
+            const parts = splitDestination(destination);
+            const targetPath = parts.path;
+            if (dialect !== "obsidian" && (targetPath.startsWith("/") || targetPath.includes("?")))
+                return { status: "unavailable" };
+            const candidates = new Set();
+            const add = (candidate) => {
+                const normalized = path.posix.normalize(candidate);
+                if (normalized.startsWith("../") || path.posix.isAbsolute(normalized))
+                    return;
+                if (entries.has(normalized))
+                    candidates.add(normalized);
+                if (dialect === "obsidian" &&
+                    !path.posix.extname(normalized) &&
+                    entries.has(`${normalized}.md`))
+                    candidates.add(`${normalized}.md`);
+            };
+            if (!targetPath)
+                add(source);
+            else if (dialect === "obsidian") {
+                if (/^\.{1,2}\//.test(targetPath))
+                    add(path.posix.join(path.posix.dirname(source), targetPath));
+                else {
+                    add(targetPath.replace(/^\//, ""));
+                    if (!targetPath.startsWith("/"))
+                        add(path.posix.join(path.posix.dirname(source), targetPath));
+                    if (candidates.size === 0) {
+                        for (const name of entries.keys()) {
+                            if (name === targetPath ||
+                                name.endsWith(`/${targetPath}`) ||
+                                name === `${targetPath}.md` ||
+                                name.endsWith(`/${targetPath}.md`))
+                                candidates.add(name);
+                        }
+                    }
+                }
+            }
+            else
+                add(path.posix.join(path.posix.dirname(source), targetPath));
+            if (candidates.size !== 1)
+                return { status: candidates.size ? "ambiguous" : "missing" };
+            const target = [...candidates][0];
+            const entry = entries.get(target);
+            const fragment = parts.fragment;
+            const fragmentExists = !fragment ||
+                (dialect === "obsidian"
+                    ? fragment.startsWith("^")
+                        ? entry.blocks.has(fragment.slice(1))
+                        : entry.headings.has(fragment)
+                    : entry.slugs.has(fragment));
+            return { status: "resolved", target, fragment, fragmentExists };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/workspace/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workspace/index.ts"],"names":[],"mappings":"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","sourcesContent":["import path from \"node:path\";\nimport GithubSlugger from \"github-slugger\";\nimport { visit } from \"unist-util-visit\";\nimport type { Dialect, LinkResolution, Workspace } from \"../core/types.js\";\nimport { parse, textContent } from \"../syntax/parse.js\";\n\ninterface Entry {\n  headings: Set<string>;\n  slugs: Set<string>;\n  blocks: Set<string>;\n}\nexport interface WorkspaceOptions {\n  dialect?: Dialect;\n  strictLineBreaks?: boolean;\n}\nexport function splitDestination(destination: string): { path: string; fragment: string } {\n  const hash = destination.indexOf(\"#\");\n  const decode = (value: string) => {\n    try {\n      return decodeURIComponent(value);\n    } catch {\n      return value;\n    }\n  };\n  return {\n    path: decode(hash < 0 ? destination : destination.slice(0, hash)),\n    fragment: decode(hash < 0 ? \"\" : destination.slice(hash + 1)),\n  };\n}\nexport function createWorkspace(\n  files: Record<string, string | null>,\n  options: WorkspaceOptions = {},\n): Workspace {\n  const entries = new Map<string, Entry>();\n  for (const [name, source] of Object.entries(files)) {\n    const entry: Entry = { headings: new Set(), slugs: new Set(), blocks: new Set() };\n    if (source !== null && /\\.md$/i.test(name)) {\n      const document = parse(source, options.dialect ?? \"commonmark\", name);\n      const slugger = new GithubSlugger();\n      visit(document.tree, \"heading\", (node) => {\n        const text = textContent(node);\n        entry.headings.add(text);\n        entry.slugs.add(slugger.slug(text));\n      });\n      visit(document.tree, \"text\", (node) => {\n        const match = /(?:^|\\s)\\^([A-Za-z0-9-]+)\\s*$/.exec(node.value);\n        if (match) entry.blocks.add(match[1]!);\n      });\n    }\n    entries.set(name.replaceAll(\"\\\\\", \"/\").replace(/^\\.\\//, \"\"), entry);\n  }\n  return {\n    ...(options.strictLineBreaks !== undefined\n      ? { strictLineBreaks: options.strictLineBreaks }\n      : {}),\n    resolve(source, destination, dialect): LinkResolution {\n      if (/^[a-z][a-z\\d+.-]*:/i.test(destination) || destination.startsWith(\"//\"))\n        return { status: \"external\" };\n      const parts = splitDestination(destination);\n      const targetPath = parts.path;\n      if (dialect !== \"obsidian\" && (targetPath.startsWith(\"/\") || targetPath.includes(\"?\")))\n        return { status: \"unavailable\" };\n      const candidates = new Set<string>();\n      const add = (candidate: string) => {\n        const normalized = path.posix.normalize(candidate);\n        if (normalized.startsWith(\"../\") || path.posix.isAbsolute(normalized)) return;\n        if (entries.has(normalized)) candidates.add(normalized);\n        if (\n          dialect === \"obsidian\" &&\n          !path.posix.extname(normalized) &&\n          entries.has(`${normalized}.md`)\n        )\n          candidates.add(`${normalized}.md`);\n      };\n      if (!targetPath) add(source);\n      else if (dialect === \"obsidian\") {\n        if (/^\\.{1,2}\\//.test(targetPath))\n          add(path.posix.join(path.posix.dirname(source), targetPath));\n        else {\n          add(targetPath.replace(/^\\//, \"\"));\n          if (!targetPath.startsWith(\"/\"))\n            add(path.posix.join(path.posix.dirname(source), targetPath));\n          if (candidates.size === 0) {\n            for (const name of entries.keys()) {\n              if (\n                name === targetPath ||\n                name.endsWith(`/${targetPath}`) ||\n                name === `${targetPath}.md` ||\n                name.endsWith(`/${targetPath}.md`)\n              )\n                candidates.add(name);\n            }\n          }\n        }\n      } else add(path.posix.join(path.posix.dirname(source), targetPath));\n      if (candidates.size !== 1) return { status: candidates.size ? \"ambiguous\" : \"missing\" };\n      const target = [...candidates][0]!;\n      const entry = entries.get(target)!;\n      const fragment = parts.fragment;\n      const fragmentExists =\n        !fragment ||\n        (dialect === \"obsidian\"\n          ? fragment.startsWith(\"^\")\n            ? entry.blocks.has(fragment.slice(1))\n            : entry.headings.has(fragment)\n          : entry.slugs.has(fragment));\n      return { status: \"resolved\", target, fragment, fragmentExists };\n    },\n  };\n}\n"]}

package/docs/cli.md

@@ -0,0 +1,71 @@
+# CLI workflows
+
+Examples use the built checkout. The installed executable is named `mdtools`;
+`node dist/cli/main.js` invokes the same CLI without a global installation.
+
+## Select files
+
+With no file arguments, commands process the workspace. Pass files or
+directories to narrow the selection while retaining the workspace for link
+resolution:
+
+```sh
+node dist/cli/main.js lint --root /path/to/documents /path/to/documents/notes/example.md
+node dist/cli/main.js format --root /path/to/documents /path/to/documents/notes --diff
+```
+
+Input paths are absolute or relative to the current working directory. The CLI
+honors `.gitignore` and configuration ignore patterns, skips symlinks and nested
+repositories, and does not expand path globs itself. See the
+[selection details](configuration.md#selection-output-and-exit-codes).
+
+## Use an explicit configuration
+
+```sh
+node dist/cli/main.js lint --root /path/to/documents --config /path/to/mdtools.config.jsonc
+node dist/cli/main.js config --root /path/to/documents explain /path/to/documents/notes/example.md
+node dist/cli/main.js rules
+```
+
+`config explain` shows the configuration resolved for a document, including path
+overrides. `rules` lists available rules. JavaScript configuration and plugins
+execute code with the caller's permissions, so load trusted code only.
+
+## Check documents in CI
+
+After installing and building the checkout, run both checks against your
+document workspace:
+
+```sh
+node dist/cli/main.js lint --root /path/to/documents --max-warnings 0
+node dist/cli/main.js format --root /path/to/documents --check
+```
+
+Lint catches enabled problem and style rules. Format checking verifies that the
+formatter would leave the selected documents unchanged. Neither command writes.
+
+## Work with agents and scripts
+
+```sh
+node dist/cli/main.js lint --root /path/to/documents --json
+node dist/cli/main.js format --root /path/to/documents --check --json
+```
+
+JSON output contains file results and diagnostics with rule IDs, severity,
+messages, and source positions. Exit code `0` means success, `1` means a lint or
+formatting check failed, and `2` means a configuration, execution, or safety
+failure. Warnings fail only when they exceed `--max-warnings`.
+
+For a formatting pass, inspect a diff, apply it with `--write`, then run the
+checks again. Report reproducible document defects using a synthetic example;
+see [contributing](contributing.md). Automatic issue reporting is not built in.
+
+## Read from stdin
+
+```sh
+node dist/cli/main.js format - --stdin-filepath notes/example.md < input.md > output.md
+```
+
+`--stdin-filepath` supplies the path used for configuration and link resolution.
+Stdin formatting writes Markdown to stdout and diagnostics to stderr unless
+`--json` is selected. It cannot be combined with `--write`.

package/docs/configuration.md

@@ -0,0 +1,171 @@
+# Configuration and rules
+
+## Loading and precedence
+
+Discovery searches upward from `--root` or the working directory for
+`mdtools.config.jsonc`, `mdtools.config.json`, or `mdtools.config.mjs`. It stops
+at a Git repository, an Obsidian vault, or the filesystem root. Multiple config
+files in one directory are an error. `--config` chooses one explicitly. The
+configuration directory is the workspace root unless `--root` overrides it.
+
+JSONC permits comments and trailing commas. JavaScript configuration exports a
+default object. JavaScript configs and plugins execute code with the caller's
+permissions; load trusted code only. Unknown configuration keys, rule IDs,
+preset names, and invalid built-in rule options are errors.
+
+Presets merge in listed order, followed by the configuration's own settings,
+followed by matching `overrides` in order. Each rule setting replaces the
+previous setting as a whole. Paths in overrides and ignores use forward slashes
+relative to the workspace root. Presets can extend other presets; cycles are
+rejected. Config files do not implicitly cascade or merge across directories.
+
+`--dialect` replaces the top-level dialect; an explicit file override still
+takes precedence. `config explain <file>` prints the resolved configuration and
+its source file.
+
+```jsonc
+{
+  "extends": ["recommended", "github"],
+  "ignore": ["generated/**"],
+  "overrides": [
+    {
+      "files": ["vault/**/*.md"],
+      "dialect": "obsidian",
+      "rules": { "style/emphasis": "off" },
+    },
+  ],
+}
+```
+
+For Obsidian reflow, use a workspace rooted at the vault so `.obsidian/app.json`
+can be inspected. Multiple vaults with independent settings should be processed
+separately.
+
+## Presets
+
+| Preset        | Dialect   | Enabled rules                                                                                  |
+| ------------- | --------- | ---------------------------------------------------------------------------------------------- |
+| `recommended` | Unchanged | Wrap at 80, `_` emphasis, `**` strong, final newline, valid links                              |
+| `github`      | GitHub    | Table alignment, lowercase completed task marker, uppercase alert marker                       |
+| `obsidian`    | Obsidian  | Table alignment, task marker, lowercase callout type, duplicate block IDs, soft-break settings |
+
+An omitted `extends` selects `recommended`. Explicit `extends` replaces that
+default, so use `["recommended", "obsidian"]` for both. `extends: []` enables
+nothing. Severity is `off`, `warn`, or `error`; supply options as
+`["warn", { ... }]`. Both `warn` and `error` style rules format when enabled.
+Problem rules report findings and never become formatting edits.
+
+## Built-in rules
+
+| Rule                          | Kind    | Options                                                   |
+| ----------------------------- | ------- | --------------------------------------------------------- |
+| `style/wrap`                  | Style   | `width`: integer 20–500, default 80                       |
+| `style/emphasis`              | Style   | `marker`: `_` (default) or `*`                            |
+| `style/strong`                | Style   | `marker`: `*` (default) or `_`                            |
+| `style/final-newline`         | Style   | None; adds a missing final newline                        |
+| `style/table`                 | Style   | None; aligns top-level GFM tables                         |
+| `style/heading`               | Style   | None; converts eligible Setext headings to ATX            |
+| `links/valid`                 | Problem | None; local files and heading/block fragments             |
+| `links/path`                  | Style   | `style`, `brackets`, `extension`, `leadingDot`; see below |
+| `links/notation`              | Style   | `style`: `markdown` or `wiki`; Obsidian only              |
+| `github/task-marker`          | Style   | None; `[X]` becomes `[x]`                                 |
+| `github/alert-marker`         | Style   | None; known GitHub alert types become uppercase           |
+| `obsidian/callout-marker`     | Style   | None; Obsidian callout types become lowercase             |
+| `obsidian/block-reference`    | Problem | None; duplicate trailing `^block-id` markers              |
+| `obsidian/strict-line-breaks` | Problem | None; report unverified/incompatible reflow settings      |
+
+## Link policies
+
+```jsonc
+{
+  "extends": ["recommended", "obsidian"],
+  "rules": {
+    "links/path": ["warn", { "style": "root", "brackets": "angle", "extension": "preserve" }],
+  },
+}
+```
+
+`style` accepts `preserve` (default), `relative`, `root`, or `shortest`. `root`
+means vault-relative, without a leading slash, and is available only for
+Obsidian. `shortest` uses the basename if it resolves uniquely, otherwise the
+vault-relative path. `leadingDot: true` prefixes ordinary relative paths with
+`./`. Filesystem absolute paths are not generated.
+
+`brackets` accepts `preserve` (default), `angle`, or `bare`. Spaces in bare
+Markdown destinations are percent-encoded. `extension` accepts `preserve`
+(default), `include`, or `omit`; omission is Obsidian specific. Fragments are
+resolved according to the dialect, separately from percent-decoded filenames.
+
+Path edits require a resolved target and valid fragment. Unaliased ordinary
+wikilinks retain their target spelling because changing it may change the
+visible label. Reference definitions are validated but their source spelling is
+currently preserved.
+
+`links/notation` converts simple explicit-label wikilinks to Markdown links and
+plain-text Markdown links to wikilinks. Titles, rich labels, unaliased
+wikilinks, and embeds are preserved. A note embed is not interchangeable with a
+Markdown image. Do not enable notation conversion and path rewriting for the
+same link in one pass: overlapping edits are reported; run those policies in
+separate passes.
+
+Network URLs are recognized but never fetched. Website-root paths and
+query-bearing destinations in CommonMark/GitHub are outside local resolution.
+Missing or ambiguous targets are reported, never guessed. The conservative
+Obsidian resolver may report ambiguity where a particular Obsidian version would
+select one candidate; shortest-name/alias resolution is not a complete clone of
+the app.
+
+## Suppressions
+
+```markdown
+<!-- mdtools-disable style/wrap -->
+
+Keep the wrapping in this region.
+
+<!-- mdtools-enable style/wrap -->
+
+<!-- mdtools-disable-next-line style/emphasis -->
+Keep *this* delimiter.
+```
+
+Omit rule names to disable all rules. A disabled region suppresses edits
+intersecting it; a paragraph spanning a disabled line is therefore preserved as
+a whole. An enable directive closes matching disabled regions; `enable` without
+names closes all. Directives inside code are ordinary code. `disable-next-line`
+targets the immediately following physical line, including a blank line; place
+it directly above the content to suppress.
+
+## Selection, output, and exit codes
+
+Commands accept explicit files/directories, or no paths to select the workspace.
+The CLI honors `.gitignore` files and configured ignore patterns. Config-ignored
+documents remain available for link resolution; Git-ignored content is not
+indexed. `.git`, `.obsidian`, `node_modules`, `.npm-cache`, `dist`, and
+`coverage` are excluded from traversal, as are nested Git repositories and
+symlinks. Explicit symlink inputs are rejected. Shell-expanded globs work; the
+CLI does not expand path globs.
+
+`lint --json` and `format --json` print a single object with `version`, `mode`,
+`files`, and `written`. Each file carries diagnostics with rule ID, severity,
+message, offsets, and one-based line/column locations. Source offsets and
+columns use JavaScript UTF-16 units; wrapping widths use display columns.
+Formatting diagnostics refer to the resulting source. `written` records whether
+the requested write phase was allowed, not how many files changed; inspect each
+file's `changed` field.
+
+`format --diff` is the default for file input. `--check`, `--diff`, and
+`--write` are mutually exclusive. `format - --stdin-filepath notes/example.md`
+reads stdin with configuration and resolution context; it cannot be used with
+`--write`.
+
+| Exit | Meaning                                                                         |
+| ---- | ------------------------------------------------------------------------------- |
+| `0`  | Completed; no errors or failed formatting check                                 |
+| `1`  | Lint errors, exceeded `--max-warnings`, or changes required by `format --check` |
+| `2`  | Configuration, execution, or formatting safety failure                          |
+
+Warnings do not fail a command unless `--max-warnings` is supplied. A successful
+formatting command can still report remaining lint problems. Inspect its exit
+code and diagnostics. An unsafe-format diagnostic blocks the complete batch's
+write phase. An I/O error during writing can leave earlier files written;
+replacement is atomic per file, not a workspace-wide transaction.

package/docs/contributing.md

@@ -0,0 +1,103 @@
+# Contributing and development
+
+This project is developed and maintained by AI agents. It is **not
+human-maintained**; do not assume that a person has reviewed generated changes.
+Issues and pull requests from people and agents are welcome.
+
+## Report a defect
+
+Include the version, command, configuration, minimal Markdown input, actual
+output, and expected rendering. A screenshot can explain a visible defect, but
+the Markdown source is needed to reproduce it. Include JSON diagnostics when
+available, and remove private content before posting examples.
+
+Use the [issue tracker](https://github.com/viell-dev/slop-markdown-tools/issues)
+for reproducible defects and feature requests. Agents should open issues only
+when their operator has authorized publishing them.
+
+Document corruption and changed rendering take priority over new style options.
+Fixes should include a synthetic regression example, preserve meaning, and
+verify that a second formatting pass leaves the output unchanged.
+
+## Pull requests and compatibility
+
+All changes to `main` require a pull request and passing CI. This includes
+prereleases, version bumps, documentation, and dependency updates. Do not push
+directly, bypass required checks, or rewrite shared history. Keep discussion
+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
+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.
+
+The beta API and configuration may change; record changes in versioned release
+notes and explain migration steps for incompatible behavior. Once published,
+versions and release tags are never replaced. Follow the
+[release procedure](releases.md) for preparation and publication. Security
+reports belong in the private channel described in
+[SECURITY.md](https://github.com/viell-dev/slop-markdown-tools/blob/main/SECURITY.md).
+
+## Develop locally
+
+Follow the [checkout setup](quick-start.md#install-from-the-repository), then:
+
+```sh
+npm run check
+npm run test:package
+```
+
+`check` runs TypeScript checks, ESLint, formatting checks, the documentation
+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
+[AGENTS.md](https://github.com/viell-dev/slop-markdown-tools/blob/main/AGENTS.md).
+
+## Write and preview documentation
+
+The site source lives in `docs/` on `main`. Edit these Markdown files directly;
+VitePress supplies navigation, local search, and rendering. The site uses
+VitePress 2 alpha because the stable 1.6 line currently retains vulnerable
+development dependencies; site builds are verified in CI. Markdown Tools formats
+and lints the site's own Markdown at its default 80-column width.
+
+```sh
+npm run format:docs
+npm run format:docs:check
+npm run docs:dev
+```
+
+To inspect the production build:
+
+```sh
+npm run docs:build
+npm run docs:preview
+```
+
+Open the URL printed by the preview server, including the
+`/slop-markdown-tools/` base path. The site build fails on unresolved internal
+page links; Markdown linting also checks local heading references.
+
+Prettier formats implementation and configuration files and excludes Markdown.
+`npm run format` runs both formatters. Synthetic fixtures under
+`tests/fixtures/` are excluded from documentation formatting.
+
+## Publish the site
+
+The Pages workflow builds the static site from `main` and deploys only
+`docs/.vitepress/dist/` as a GitHub Pages artifact. Generated output is ignored
+by Git and excluded from the npm package. There is no publishing branch to
+maintain. Pull requests build the site through CI without deploying it.
+
+GitHub Pages must use **GitHub Actions** as its publishing source. Deployment
+uses the `github-pages` environment and the workflow's short-lived token. See
+GitHub's
+[custom workflow documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)
+for deployment settings.

package/docs/design.md

@@ -0,0 +1,79 @@
+# Design and current limitations
+
+## Architecture
+
+The project uses TypeScript, Node.js, and npm. mdast/micromark provide parsing
+and syntax extensions. The formatter retains original source and applies
+source-positioned edits rather than serializing the whole AST. This allows
+disabled formatting rules and opaque constructs to retain their spelling.
+
+`src/syntax/` owns parsing and Obsidian tokens. `src/config/` owns configuration
+and plugin discovery. `src/core/` owns the shared contracts, suppression
+directives, diagnostics, and edit engine. `src/rules/` implements built-in
+rules. `src/workspace/` resolves targets and handles filesystem
+selection/writes. `src/cli/` connects those services; the public `src/index.ts`
+library has no implicit filesystem access.
+
+Lint and format use the same rule settings. A style rule checks a preferred
+representation and proposes edits. A problem rule reports defects without
+inventing repairs. Inline, block, and document phases separate operations that
+would otherwise commonly overlap. Each phase reparses its result and compares a
+semantic fingerprint, using resolved destinations for link identity. Formatting
+must converge; otherwise the original document is returned with an error
+diagnostic.
+
+## Safety boundaries
+
+The semantic fingerprint protects the supported AST model, not every
+application's rendered output. It normalizes ordinary prose whitespace and known
+callout-marker casing. It does not run Obsidian or GitHub's renderer. Syntax
+extensions require regression tests for their own meaning and source
+preservation. Tests use synthetic documents, deterministic property checks, and
+filesystem/CLI integration cases, including the list-collapse failure that
+motivated replacing heuristic reflow.
+
+Obsidian callout headers remain intact; their body paragraphs can reflow when
+supported. Highlight, comment, math, code, HTML, and front-matter contents are
+preserved. Standalone Obsidian comment blocks may span blank lines. Inline
+comments spanning multiple paragraphs are not fully modeled; suppress formatting
+around those constructs or use standalone comment blocks.
+
+The source-preserving wrapper supports ordinary paragraphs, list items, and
+blockquote containers. It preserves explicit hard-break paragraphs, lazy/unusual
+continuations it cannot safely reconstruct, and paragraphs carrying block IDs.
+Long unbreakable atoms can exceed the width. Intraword emphasis retains
+asterisks when underscores would change parsing. Formatting width is a target,
+not a license to split protected syntax.
+
+GitHub alert support normalizes known alert type markers. Footnotes, math,
+strikethrough, and autolinks are parsed, but do not each have dedicated style
+rules. Table alignment currently applies only to top-level tables and preserves
+cell contents. Embedded code formatting, metadata mutation, document generation,
+external URL fetching, and file renames are outside this release.
+
+Obsidian links resolve against indexed paths, extensionless Markdown candidates,
+and unique suffixes for internal links. Duplicate candidates remain ambiguous.
+Heading fragments use exact text; GitHub uses slugged headings including
+duplicate suffixes. Block identifiers are indexed from trailing text markers.
+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.
+
+## Maintenance priorities
+
+Prioritize reproducible document corruption and renderer disagreement over new
+style options. Add a minimal regression case before a fix; verify that disabling
+the affected rule preserves the source. Broaden dialect fixtures and resolver
+compatibility before promising complete application parity. Benchmark real
+synthetic vault sizes before adding caching or worker processes.
+
+Future changes can add richer link policies, reference-definition formatting,
+more container layout, versioned plugin contracts, and optional standalone
+distribution. Each should extend the shared configuration and edit contracts
+instead of creating a second formatter pipeline.

package/docs/index.md

@@ -0,0 +1,48 @@
+---
+layout: home
+hero:
+  name: Markdown Tools
+  text: Your Markdown. Your rules.
+  tagline: Separate lint and format commands. Shared configuration. Built for CommonMark, GitHub, and Obsidian.
+  actions:
+    - theme: brand
+      text: Quick start
+      link: /quick-start
+    - theme: alt
+      text: Explore the rules
+      link: /configuration
+features:
+  - title: Check, preview, then write
+    details: Lint without changing files, inspect formatting diffs, and write when ready. JSON diagnostics work with agents and automation.
+  - title: Format what you configure
+    details: Wrap at 80 columns by default. Choose link paths, delimiters, and dialect rules. Disabled rules preserve their syntax choices.
+  - title: Extend the shared core
+    details: Add JavaScript rules, presets, and syntax extensions. Use the same engine through the CLI or the TypeScript library.
+---
+
+## A small, reviewable workflow
+
+From a [built checkout](quick-start.md), point the CLI at your documents:
+
+```sh
+node dist/cli/main.js lint --root /path/to/documents
+node dist/cli/main.js format --root /path/to/documents --diff
+node dist/cli/main.js format --root /path/to/documents --write
+```
+
+Formatting applies edits to the original source and checks the parsed meaning
+before accepting them. See the [safety boundaries](design.md#safety-boundaries)
+for the limits of those checks.
+
+## Start with your documents
+
+- **A repository or writing folder:** follow the [quick start](quick-start.md),
+  then choose [configuration and rules](configuration.md).
+- **An Obsidian vault:** use the [vault guide](obsidian.md) for wikilinks,
+  callouts, block references, and safe prose wrapping.
+- **A custom workflow:** use [CLI workflows](cli.md) or extend the
+  [library and plugin API](plugins.md).
+
+This is an early prerelease, developed and maintained by AI agents rather than
+human maintainers. Issues and pull requests from people and agents are welcome.
+Read [how to contribute](contributing.md) before reporting a defect.