mmdfmt 0.1.0 → 0.2.0

package/README.md

@@ -10,8 +10,8 @@ blocks of `.md` and `.markdown` files. The rest of a Markdown file stays byte
 for byte as it is. The diagrams are formatted by
 [Prettier](https://prettier.io/) with
 [`prettier-plugin-mmd`](../prettier-plugin-mmd), the Mermaid plugin for
-Prettier, so they come out as that plugin prints them, apart from the two cases
-in [If you know Prettier](#if-you-know-prettier).
+Prettier, so they come out as that plugin prints them, apart from the cases in
+[If you know Prettier](#if-you-know-prettier).
 
 This is a third-party project, not affiliated with
 [mermaid-js](https://mermaid.js.org/). The
@@ -108,28 +108,42 @@ diagram differently.
 ## Usage
 
 ```sh
-mmdfmt --write <pattern>...
+mmdfmt --write [--check | --list-different] <pattern>...
 mmdfmt --check <pattern>...
+mmdfmt --list-different <pattern>...
 mmdfmt --stdin-filepath <path>
 ```
 
-| Option                    | What it does                                                                                 |
-| ------------------------- | -------------------------------------------------------------------------------------------- |
-| `--write`                 | Formats the files in place, and lists on standard output the ones that changed.              |
-| `--check`                 | Changes nothing. Lists on standard output the files that `--write` would change.             |
-| `--stdin-filepath <path>` | Formats standard input as if it were the file at `<path>`, and writes it to standard output. |
-| `-h`, `--help`            | Prints the usage on standard output.                                                         |
-| `-v`, `--version`         | Prints the version on standard output.                                                       |
-
-Give patterns with either `--write` or `--check`, or give `--stdin-filepath`
-alone. `--help` and `--version` only print, whatever else of this table is given
-with them. Any other combination is an error. With no argument at all, `mmdfmt`
-prints the usage on standard error and exits with `2`.
+| Option                    | What it does                                                                                  |
+| ------------------------- | --------------------------------------------------------------------------------------------- |
+| `-w`, `--write`           | Formats the files in place, and lists each file it formats on standard output, with its time. |
+| `-c`, `--check`           | Checks whether the files are formatted, and prints a summary and the files that are not.      |
+| `-l`, `--list-different`  | Changes nothing. Lists on standard output the files that `--write` would change.              |
+| `--stdin-filepath <path>` | Formats standard input as if it were the file at `<path>`, and writes it to standard output.  |
+| `-h`, `--help`            | Prints the usage on standard output.                                                          |
+| `-v`, `--version`         | Prints the version on standard output.                                                        |
+
+Give patterns with at least one of `--write`, `--check`, or `--list-different`.
+`--write` can be combined with either `--check` or `--list-different`:
+`--write --check` rewrites files and prints the check's summary and warnings;
+`--write --list-different` rewrites files and lists only the ones that changed.
+`--check` and `--list-different` cannot be combined. `--no-write`, `--no-check`,
+and `--no-list-different` turn the option off. `--stdin-filepath` takes no
+patterns, and with it `--write` writes no file. `--help` and `--version` only
+print, whatever else of this table is given with them. With no argument at all,
+`mmdfmt` prints the usage on standard error and exits with `2`.
+
+`--write` alone prints a line for each file it formats, as Prettier does: the
+name and the time that formatting it took, such as `docs/flow.mmd 12ms`,
+followed by `(unchanged)` for a file that did not change. On a terminal that
+shows colors, the name of an unchanged file is gray. To list only the files that
+changed, give `--write --list-different`. The name of a file in what `mmdfmt`
+prints is its path relative to the directory where it runs, with `/` between its
+parts also on Windows, as Prettier writes it.
 
 There are no other options: no formatting options, no configuration file of its
 own, and no option for an ignore file. An option that takes no value ignores a
-value written after `=`: `--write=false` is read as `--write`, as the argument
-library [gunshi](https://gunshi.dev) reads it.
+value written after `=`: `--write=false` is read as `--write`.
 
 When the reader of standard output goes away, as `head` does once it has its
 lines, `mmdfmt` writes no more there and says nothing, and finishes the run:
@@ -193,11 +207,30 @@ run:
 npx mmdfmt --check .
 ```
 
-When a file is not formatted, `--check` lists it on standard output and exits
-with `1`. When every file is formatted, it prints nothing and exits with `0`.
 Without the dependencies installed, `npx` would run the latest version instead
 of the pinned one.
 
+`--check` prints `Checking formatting...` on standard output, then
+`[warn] <name>` on standard error for each file that would change, and at the
+end one summary. When a file would change, the summary is on standard error, and
+the exit code is `1`:
+
+```txt
+[warn] Code style issues found in the above file. Run mmdfmt with --write to fix.
+```
+
+With more than one such file, it says `in <n> files` instead of
+`in the above file`. On a terminal that shows colors, the word `warn` is yellow.
+When no file would change, the summary is
+`All diagrams in the matched files use Prettier code style!` on standard output,
+and the exit code is `0`. `--list-different` prints only the names of the files
+that would change, on standard output, with the same exit codes.
+
+With `--write --check`, the files are rewritten, the summary is
+`[warn] Code style issues fixed in the above file.` (or `in <n> files.`), and
+the exit code is `0`. With an error, the exit code is `2`;
+[Errors and exit codes](#errors-and-exit-codes) says which summary then follows.
+
 A `.mmd` or `.mermaid` file whose diagram mermaid.js rejects fails the check
 with `2`. A diagram in Markdown that mermaid.js rejects gives only a warning,
 because a document can show a broken diagram on purpose, and `mmdfmt` has no
@@ -248,25 +281,180 @@ whether the text is a diagram or Markdown, and its directory says which
 - A path under `node_modules` or a directory of version control, or listed in
   the `.gitignore` of the directory where `mmdfmt` runs, gets its text back
   unchanged.
+- With `--check` or `--list-different`, the text is not written out: when it
+  would change, `(stdin)` goes to standard output and the exit code is `1`,
+  unless `--write` is given too; otherwise nothing is written and the exit code
+  is `0`. The position of a warning is in the text as it was read.
 - A path with another ending is an error.
 
-## Indentation
+## From a script
 
-A diagram is indented by two spaces. When an `.editorconfig` or a Prettier
-configuration applies to the file, its indentation is used: `indent_style`,
-`indent_size`, and `tab_width` of `.editorconfig`, or `useTabs` and `tabWidth`
-of a [Prettier configuration file](https://prettier.io/docs/configuration),
-found as Prettier's CLI finds them, `overrides` included. For a code block, the
-file is the Markdown file. A configuration file that cannot be read is an error.
-For example, this `.editorconfig` indents diagrams by four spaces:
+An editor extension, a language server, or another tool written for Node.js can
+format the diagrams of a file as the `mmdfmt` command does, without running it.
+(A tool that is not written for Node.js can run the command with
+[`--stdin-filepath`](#from-an-editor-or-another-tool).) Add `mmdfmt` to the
+dependencies of the tool, pinned as in [Installation](#installation), since a
+new version can format a diagram a little differently:
+
+```sh
+npm install --save-exact mmdfmt
+```
+
+It needs Node.js `^22.13.0 || >=24`. Import its functions `resolveConfig`,
+`format`, and `clearConfigCache`. Their arguments and results follow Prettier's
+functions of the same names, and each section below says where they differ. This
+formats the diagrams of `docs/notes.md`:
+
+```js
+import { readFile } from "node:fs/promises"
+import { format, resolveConfig } from "mmdfmt"
+
+const filepath = "docs/notes.md"
+const source = await readFile(filepath, "utf8")
+const config = await resolveConfig(filepath)
+const formatted = await format(source, { ...config, filepath })
+```
+
+`formatted` is the text that the command writes for `docs/notes.md`: its
+diagrams formatted, and the rest as written. Writing it to the file is up to the
+tool.
+
+### `resolveConfig(fileUrlOrPath)`
+
+`resolveConfig` finds the configuration of a file as the command finds it: the
+Prettier configuration files and the `.editorconfig` that apply to the file,
+`overrides` included (see [Configuration](#configuration)). Pass the path of the
+file or a file URL; a relative path is resolved against the current directory,
+so a language server passes an absolute path or a URL. The file itself is not
+read, and need not exist.
+
+It returns a promise of an object of Prettier options to pass to `format`, or of
+`null` when no configuration applies to the file. Spreading `null` adds nothing,
+so `{ ...config, filepath }` works in both cases. The object holds only the
+options that the configuration sets, of the eight that `mmdfmt` reads, listed in
+[Configuration](#configuration): with a configuration that sets no `tabWidth`,
+`{ tabWidth: 4, ...config, filepath }` keeps a `tabWidth` of 4. With TypeScript,
+its type is `ReadOptions`. The promise is rejected when a configuration file
+cannot be read.
+
+`resolveConfig` reads `.editorconfig` as the command does, and as Prettier's CLI
+does by default; Prettier's `resolveConfig` reads it only when it is given
+`editorconfig: true`.
+
+### `clearConfigCache()`
+
+`resolveConfig` keeps the configuration files that it has read for the life of
+the process, as Prettier's does, so a later call does not see a change to them.
+Call `clearConfigCache` when the tool learns that a Prettier configuration file
+or an `.editorconfig` has changed, for example from the editor's file watcher:
+the next call of `resolveConfig` reads the files again. It returns a promise
+that is resolved once the files are forgotten.
+
+### `format(source, options)`
+
+`format` formats a text as Prettier's `format` does, except that in Markdown it
+formats only the Mermaid code blocks and leaves the rest as written. It reads no
+file and no configuration.
+
+- `source`: the text of the file.
+- `options.filepath`: the path of the file, required. Only its ending is used:
+  the text is read as one diagram for `.mmd` and `.mermaid`, and as Markdown for
+  `.md` and `.markdown`. The file need not exist.
+- The other options: what `resolveConfig` returns for the same path, since the
+  `overrides` of a configuration apply by path. They are the eight options
+  listed in [Configuration](#configuration). For Markdown, `printWidth` is the
+  width for the whole file: a diagram in a list item or a block quote is
+  formatted to that width less the width of what stands before its lines (see
+  [Code blocks in detail](#code-blocks-in-detail)).
+- Another option, such as `parser`, `endOfLine`, or `semi`, is not an option of
+  `format`: with TypeScript it is a type error, and in JavaScript it is ignored.
+  With TypeScript, the type of the options is `FormatOptions`.
+
+It returns a promise of the formatted text. The line endings and a byte order
+mark stay as they are in the text (see
+[Code blocks in detail](#code-blocks-in-detail)).
+
+In Markdown, `format` leaves three kinds of block as written and reports none of
+them: a diagram that mermaid.js rejects, a block with a tab in its indentation
+that is read partly as the diagram, and a block whose opening fence stands on
+the line of a footnote label (see
+[Code blocks in detail](#code-blocks-in-detail)). Prettier leaves an embedded
+code block that it cannot format in the same way. To find the diagrams that
+mermaid.js rejects, parse them with [`@mmd-toolkit/parser`](../parser) or lint
+the file with [`@mmd-toolkit/eslint-plugin`](../eslint-plugin).
+
+The promise is rejected:
+
+- with the `SyntaxError` that Prettier throws for a `.mmd` or `.mermaid` text
+  that mermaid.js rejects, when it formats the text with `prettier-plugin-mmd`.
+  Its `loc.start` and `loc.end` give the `line` and the `column` where the error
+  starts and where it ends, both counted from 1. An error whose range runs on to
+  the start of a later line, such as an error at a line break, has no `loc.end`;
+- with Prettier's error, when an option has a value that Prettier refuses, such
+  as `printWidth: "wide"` (`Invalid printWidth value. …`), for a `.mmd` or
+  `.mermaid` text, and for a Markdown text with a code block whose diagram
+  `mmdfmt` formats ([Code blocks in detail](#code-blocks-in-detail)), whether or
+  not mermaid.js rejects the diagram. A Markdown text with no such block is
+  returned as it is: one with no `mermaid` or `mmd` code block, or one whose
+  `mermaid` and `mmd` blocks are all left as written, after
+  `<!-- prettier-ignore -->`, between `<!-- prettier-ignore-start -->` and
+  `<!-- prettier-ignore-end -->`, on the line of a footnote label, or with a tab
+  in their indentation read partly as the diagram;
+- with an error, when `options.filepath` does not end in `.md`, `.markdown`,
+  `.mmd`, or `.mermaid`.
+
+### Which files to format
+
+The command formats only the files that end in `.md`, `.markdown`, `.mmd`, or
+`.mermaid`, and skips a path under `node_modules` or a directory of version
+control, or a path that the `.gitignore` of the directory where it runs lists
+(see [Excluding files](#excluding-files)). `format` rejects the other endings,
+but formats the text of any other path that it is given, wherever the path is: a
+tool that should skip the same files as the command checks them before it calls
+`format`.
+
+## Configuration
+
+A diagram is indented by two spaces, and its line width is Prettier's 80. When
+an `.editorconfig` or a Prettier configuration applies to the file, `mmdfmt`
+reads eight options of it, found as Prettier's CLI finds it, `overrides`
+included: `indent_style`, `indent_size`, `tab_width`, and `max_line_length` of
+`.editorconfig`, or the options of a
+[Prettier configuration file](https://prettier.io/docs/configuration). For a
+code block, the file is the Markdown file. A configuration file that cannot be
+read is an error. For example, this `.editorconfig` indents diagrams by four
+spaces and lets a line stay up to 100 columns wide:
 
 ```ini
 [*.{md,mmd,mermaid}]
 indent_style = space
 indent_size = 4
+max_line_length = 100
 ```
 
-Nothing else of a configuration is used.
+The eight options are:
+
+- `printWidth` is the line width. It decides two things in a diagram: whether a
+  data block `@{ … }` on one line is printed on several lines, and whether the
+  colons of the tasks of a Gantt section are lined up (see
+  [Formatter options](https://mmd-toolkit.github.io/mmd-toolkit/formatter/options.html#line-width)).
+  `max_line_length = off` is no limit. In a code block in a list or a block
+  quote, `printWidth` is less the width of what `mmdfmt` writes before the lines
+  (see [Code blocks in detail](#code-blocks-in-detail)).
+- `tabWidth` and `useTabs` set the indentation of a diagram.
+- `embeddedLanguageFormatting`, `singleQuote`, `bracketSpacing`, `proseWrap`,
+  and `trailingComma` apply to the YAML frontmatter of a diagram, as they do
+  when Prettier formats it with `prettier-plugin-mmd`.
+  `embeddedLanguageFormatting: "off"` leaves the frontmatter as written.
+
+`mmdfmt` reads no other option, not even one that a later version of Prettier
+adds. The range (`rangeStart` and `rangeEnd`), `cursorOffset`, the pragma
+options (`requirePragma`, `insertPragma`, and `checkIgnorePragma`), `filepath`,
+and the options of other languages are not used. `plugins` and `parser` are not
+used either: `mmdfmt` always formats with `prettier-plugin-mmd`, so a plugin
+that the configuration names is not loaded. `endOfLine` is not used, since a
+file keeps its line endings (see
+[Code blocks in detail](#code-blocks-in-detail)).
 
 ## Errors and exit codes
 
@@ -283,27 +471,38 @@ In a `.mmd` or `.mermaid` file, it is an error. In a Markdown code block, it is
 a warning. With `--write` and `--stdin-filepath`, the position of a warning is
 in the text after formatting, where the diagrams above it may have gained or
 lost lines, so that it points at the block in what you open after the run. With
-`--check`, which writes nothing, it is in the file as it is. Lines and columns
-count from 1, and a column counts UTF-16 code units, as most editors do.
+`--check` or `--list-different` without `--write`, it is in the file as it is.
+Lines and columns count from 1, and a column counts UTF-16 code units, as most
+editors do.
 [Formatter compatibility](https://mmd-toolkit.github.io/mmd-toolkit/formatter/compatibility.html)
 explains which diagrams are rejected.
 
-| Code | Meaning                                                       |
-| ---- | ------------------------------------------------------------- |
-| `0`  | No errors, and with `--check`, every file is formatted.       |
-| `1`  | With `--check`, a file would change, and there are no errors. |
-| `2`  | An error.                                                     |
+| Code | Meaning                                                                                               |
+| ---- | ----------------------------------------------------------------------------------------------------- |
+| `0`  | No errors; with `--check` or `--list-different`, no file would change or `--write` is given.          |
+| `1`  | With `--check` or `--list-different` without `--write`, a file would change, and there are no errors. |
+| `2`  | An error.                                                                                             |
 
 An error is a rejected diagram in a `.mmd` or `.mermaid` file, a file that
 cannot be read or written, a pattern that selects no file, a configuration that
 cannot be read, or a wrong use of the options. With an error, the code is `2`
 even when a file would change.
 
+When a file cannot be formatted, such as a `.mmd` or `.mermaid` file whose
+diagram mermaid.js rejects, the summary of `--check` is
+`Error occurred when checking code style in the above file.` (or
+`in <n> files.`) on standard output. As in Prettier's `--check`, the summary
+counts only the files that cannot be formatted. A file that cannot be read, and
+a pattern that selects no file, are reported as errors, but the summary is the
+one it would be without them, also when no pattern selects any file. A file that
+cannot be written counts among the files whose issues were fixed, and `--write`
+and `--write --list-different` still list it.
+
 ## If you know Prettier
 
 The diagrams are formatted by Prettier with `prettier-plugin-mmd`, so the rules
-of the plugin apply. Two results differ from running Prettier with the plugin on
-Markdown:
+of the plugin apply. Five results differ from running Prettier with the plugin
+on Markdown and `.mmd` files:
 
 - Prettier removes the whitespace at the end of the last line of a code block,
   even where mermaid.js treats it as part of the diagram
@@ -312,10 +511,79 @@ Markdown:
 - Prettier formats a code block of Markdown, such as one marked `md`, as a
   Markdown document, and with it the diagrams in its code blocks. `mmdfmt`
   leaves every other code block as it is.
+- Prettier prints what stands before the lines of a list item or a block quote
+  itself, while `mmdfmt` keeps it as written (see
+  [Code blocks in detail](#code-blocks-in-detail)). For a list item, Prettier
+  prints the marker and aligns the content to `tabWidth`. For a block quote, it
+  prints `> ` and drops the spaces and tabs between the `>` and the fence. Where
+  the two give the content another column, the line width left for a diagram in
+  the item or the quote differs by that, and a block of one line near the width
+  can be split by one and not by the other.
+- In a list item or a block quote, Prettier lines up the colons of a Gantt
+  section without counting what stands before the lines, so a lined-up line can
+  be wider than the line width. `mmdfmt` counts it, so near the width a Gantt
+  section can be lined up by Prettier and not by `mmdfmt`, which then pads no
+  name to line the colons up: the whitespace before each colon stays as written,
+  and a line written wider than the line width stays so. `mmdfmt` still indents
+  the tasks as it does in any Gantt chart, so a colon moves along with its line
+  where the written indentation differs.
+- Prettier leaves a diagram as written under four settings.
+  `requirePragma: true` leaves a Markdown file that has no `<!-- @format -->` or
+  `<!-- @prettier -->` comment at its top, after the frontmatter if there is
+  one. `checkIgnorePragma: true` leaves a Markdown file that has a
+  `<!-- @noformat -->` or `<!-- @noprettier -->` comment there. A range that
+  does not cover the whole file leaves a Markdown file or a `.mmd` file.
+  `embeddedLanguageFormatting: "off"` leaves every code block of a Markdown
+  file. `mmdfmt` formats the diagrams under all four. It does not read the first
+  three: it decides itself which files it formats (the patterns, and
+  `.gitignore`), and it formats whole diagrams. It reads
+  `embeddedLanguageFormatting` for the frontmatter of a diagram only, which it
+  then leaves as written.
 
 The command differs from Prettier's CLI too: it does not read `.prettierignore`,
-has no `--ignore-path`, `--ignore-unknown`, or formatting options, and uses only
-the indentation of a configuration.
+has no `--ignore-path`, `--ignore-unknown`, or formatting options of its own,
+and reads the configuration for the diagrams only. A value that Prettier refuses
+for an option that `mmdfmt` does not read, such as `semi: "yes"`, is not an
+error here, while Prettier's CLI reports it.
+
+The check's success line says
+`All diagrams in the matched files use Prettier code style!`, rather than
+Prettier's `All matched files use Prettier code style!`: `mmdfmt` formats
+nothing but diagrams, so the rest of a Markdown file may not use that style. The
+warning asks you to run `mmdfmt --write`, because `prettier --write` would
+format the whole Markdown file and, without the plugin configured, would not
+format its diagrams.
+
+Prettier reads `--write=false` as false; `mmdfmt` ignores a value written after
+`=` on an option that takes no value, and reads it as `--write`. The same holds
+for `--check=false` and `--list-different=false`. Prettier also takes a `true`
+or `false` written after `--write` as its value; `mmdfmt` reads it as a pattern,
+so `mmdfmt --write false notes.md` formats `notes.md` and reports that no file
+matches `false`.
+
+`--check --list-different` is an error in both, but `mmdfmt` prints
+`mmdfmt: error: Optional argument '--check' conflicts with '--list-different'`
+and exits with `2`, as for any wrong use of the options, while Prettier prints
+`[error] Cannot use --check and --list-different together.` and exits with `1`.
+When `mmdfmt` checks which options go together, a `--no-` form counts as giving
+its option: `--no-check --list-different` is an error, as
+`--check --list-different` is. Prettier accepts `--no-check --list-different`.
+
+With `--check` or `--list-different` on standard input, Prettier exits with `0`
+for a text it cannot parse; `mmdfmt` exits with `2` for a rejected diagram, as
+everywhere else ([Errors and exit codes](#errors-and-exit-codes)). `mmdfmt`
+reports a rejected diagram of a `.mmd` or `.mermaid` file on one line with its
+position, such as `docs/flow.mmd:3:1: error: Unexpected end of text`, while
+Prettier writes `[error] docs/flow.mmd: SyntaxError: Unexpected end of text` and
+then the lines around the place, each after `[error]`. For a rejected diagram in
+a Markdown file, `mmdfmt` writes a warning on one line, such as
+`notes.md:6:1: warning: Unexpected end of text`, while Prettier writes nothing
+about it; neither treats it as an error.
+
+Prettier also colors the word `warn` yellow and the name of an unchanged file
+gray where its output is not a terminal, if the `CI` environment variable is set
+or the system is Windows. `mmdfmt` colors them only on a terminal that shows
+colors, or when `FORCE_COLOR` is set, and has no `--color` or `--no-color`.
 
 ## Code blocks in detail
 
@@ -375,6 +643,20 @@ Two kinds of block are left as written, with a warning that gives the position:
 
 A diagram that is empty or only whitespace between its fences becomes empty.
 
+The line width of a diagram in a list item or a block quote is the line width of
+the file less the width of what `mmdfmt` writes before each of its lines, the
+width being at least 1. Each character of it counts as one column, except that a
+tab reaches the next multiple of `tabWidth`, and counts for nothing where
+`tabWidth` is 0. For example, with a line width of 40, a diagram in a list item
+whose lines start with two spaces is formatted for 38 columns, and with a
+`tabWidth` of 4, a diagram in a block quote whose lines start with `>` and a tab
+is formatted for 36 columns, as the tab reaches column 4. Prettier takes off the
+width of what it prints before the lines from a data block `@{ … }` in the same
+way, but what it prints can differ from what `mmdfmt` writes (see
+[If you know Prettier](#if-you-know-prettier)). The colons of a Gantt section
+are the exception: Prettier does not count what stands before the lines when it
+lines them up (see the same section).
+
 A file keeps its line endings. Each line that `mmdfmt` writes ends as the first
 line of the file ends, or with `\n` in a file of one line, except the last,
 which ends as the last line of the diagram ended before formatting. The line
@@ -389,7 +671,7 @@ the column of an error or a warning, a line ends at `\n`, `\r\n`, or `\r`.
 ## Documentation
 
 - [Formatter options](https://mmd-toolkit.github.io/mmd-toolkit/formatter/options.html):
-  how the indentation applies to diagrams.
+  how the indentation and the line width apply to diagrams.
 - [Formatter compatibility](https://mmd-toolkit.github.io/mmd-toolkit/formatter/compatibility.html):
   rejected diagrams, differences from mermaid.js, and what the formatting
   guarantees.

package/lib/cli.d.mts

@@ -0,0 +1 @@
+export {}