prettier-plugin-mmd 0.0.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,172 @@
1
+ import { Comment, Node, Range, Root } from "@mmd-toolkit/parser";
2
+ import { AstPath, Doc, Parser, ParserOptions, Plugin, Printer, SupportLanguage } from "prettier";
3
+ //#region src/printers/source.d.ts
4
+ /**
5
+ * A comment as the printers read it: its kind, its range, and its mark. A
6
+ * comment that a comment line cuts is one comment here, over the range of all
7
+ * its parts (see `joinCommentFragments`).
8
+ */
9
+ interface TriviaComment {
10
+ readonly type: "Comment";
11
+ readonly range: Range;
12
+ readonly mark: Comment["mark"];
13
+ }
14
+ /**
15
+ * A directive as the printers read it: its kind and its range, which takes
16
+ * the whitespace after a directive that is not closed when that holds a
17
+ * U+2028 or U+2029 (see `extendDirective`).
18
+ */
19
+ interface TriviaDirective {
20
+ readonly type: "Directive";
21
+ readonly range: Range;
22
+ }
23
+ /**
24
+ * A comment or a directive: text that belongs to no node, which the printers
25
+ * print as written between the things they print (ast.md, Tokens, and
26
+ * Comments, directives, and frontmatter). They are the printers' own records,
27
+ * not the tokens and comments of the parser: the range of a directive or of a
28
+ * joined comment is not the range of the parser's token or comment, so a
29
+ * parser's token with another range would give a `value` and a `loc` that no
30
+ * longer fit.
31
+ */
32
+ type Trivia = TriviaComment | TriviaDirective;
33
+ /**
34
+ * What a diagram printer reads besides the tree: the source text, the root
35
+ * with its lists, and the comments and directives merged in source order.
36
+ */
37
+ interface Source {
38
+ readonly text: string;
39
+ readonly root: Root;
40
+ /**
41
+ * `Root.comments` and the `Directive` tokens of `Root.tokens`, merged in
42
+ * source order. The directives are taken from the tokens, not from
43
+ * `Root.directives`: the tokens hold exactly the directives that lie
44
+ * outside the tokens and comments, with the same ranges, so every scan of
45
+ * the text reads one list of what it covers.
46
+ */
47
+ readonly trivia: readonly Trivia[];
48
+ /**
49
+ * The offsets of the `;` that the line rule ignores (common.md, The
50
+ * `style` and `classDef` lines): the `IgnoredSemicolon` tokens of the
51
+ * tree. A `;` that lies in a comment is no token, and is read with the
52
+ * comment.
53
+ */
54
+ readonly ignoredSemicolons: ReadonlySet<number>;
55
+ /**
56
+ * The comment regions that join lines (see `JoiningRegion`), in source
57
+ * order.
58
+ */
59
+ readonly joiningRegions: readonly JoiningRegion[];
60
+ /**
61
+ * The offsets of the line feeds that mermaid.js does not read as line
62
+ * ends, so that the lines they end go on: the line feeds that the joining
63
+ * regions remove, and the ones in the whitespace after a directive that is
64
+ * not closed. Whitespace at the end of the text, with nothing after it to
65
+ * join, removes none.
66
+ */
67
+ readonly removedLineFeeds: ReadonlySet<number>;
68
+ /**
69
+ * Whether the gap reader takes a U+2028 or a U+2029 that ends a diagram
70
+ * comment as the break of a line (see `readGapElement`): the lexers of
71
+ * mindmap and ishikawa end the comment at the end of its line segment, and
72
+ * the text after it is a new line (diagrams/mindmap.md and
73
+ * diagrams/ishikawa.md, Comments). A kanban board ends its comments there
74
+ * too, but its printer keeps the separator as written in the gaps it keeps
75
+ * (`BlockRules.keptGapEnd`), so the flag is false. In the other diagram
76
+ * types the comment runs to the line feed, and a U+2028 or U+2029 after it is
77
+ * whitespace to be printed as such.
78
+ */
79
+ readonly commentsEndAtLineSeparators: boolean;
80
+ }
81
+ /**
82
+ * A comment region that joins lines. mermaid.js removes every comment region
83
+ * from the text before it reads it: a comment line `%%` with the
84
+ * whitespace-only lines and directives before it, and the line terminator
85
+ * that ends it (common.md, Comment). When the region starts right after a
86
+ * U+2028 or U+2029, or right where a region that joins ends, the text before
87
+ * it and the text after it become one line. Only a comment with the mark `%%`
88
+ * makes a region: a `#` comment is read by the lexer of its diagram.
89
+ */
90
+ interface JoiningRegion {
91
+ /** The comment line of the region. */
92
+ readonly comment: Comment;
93
+ /** Where the region starts: after the earliest comment start before the comment. */
94
+ readonly start: number;
95
+ /** Where the region ends: after the line terminator of the comment, if there is one. */
96
+ readonly end: number;
97
+ /** Whether anything but whitespace follows the region, to be joined to what comes before. */
98
+ readonly hasTextAfter: boolean;
99
+ }
100
+ //#endregion
101
+ //#region src/printers/root.d.ts
102
+ /**
103
+ * A diagram's constraint on the completed layout, before it is applied.
104
+ * The callback defers ordinary layout construction when the source must stay
105
+ * whole, so that the plan also owns that choice.
106
+ */
107
+ type RootTextPlan = (print: () => Doc, frontmatterEnd: number, frontmatterDoc: Doc | undefined) => Doc;
108
+ //#endregion
109
+ //#region src/printers/index.d.ts
110
+ /** Diagram-specific constraints on the source and the complete root layout. */
111
+ interface DiagramTextRules {
112
+ readonly keepsCommentLines: boolean;
113
+ /**
114
+ * The diagram printer prints the text as written, so nothing before the body
115
+ * is formatted either: the text before it is kept as `keepsPrefix` keeps it,
116
+ * the frontmatter is not formatted as YAML, and a document embedded in
117
+ * Markdown is declined, because Prettier strips the trailing line breaks of
118
+ * every embedded document.
119
+ */
120
+ readonly printsAsWritten?: boolean;
121
+ readonly keepsPrefix?: (source: Source) => boolean;
122
+ readonly plan?: (source: Source, options: ParserOptions<MermaidAst>) => RootTextPlan;
123
+ }
124
+ /**
125
+ * Prints one diagram type. It is called for the diagram body and for every
126
+ * node below it, and recurses with `print`. What stands before the body is
127
+ * printed by `printRoot`, the same for every diagram type; the diagram
128
+ * printer prints from the body to the end of the text, including the line
129
+ * break at its end, because only it knows what its last line holds.
130
+ */
131
+ type DiagramPrinter = (path: AstPath<MermaidAst>, options: ParserOptions<MermaidAst>, print: (path: AstPath<MermaidAst>) => Doc, source: Source) => Doc;
132
+ //#endregion
133
+ //#region src/parser.d.ts
134
+ /**
135
+ * A document whose diagram type has a printer. Prettier walks from this node
136
+ * into `root`, the tree the parser returned.
137
+ *
138
+ * This departs from Prettier's usual shape, where the parser's tree is the
139
+ * top node, for two reasons:
140
+ *
141
+ * - The wrapper carries what is decided once while parsing: the printer of
142
+ * the diagram type, and the printing context (`source`).
143
+ * - It keeps `Root.comments` away from Prettier's own comment handling.
144
+ * Prettier reads a `comments` array on the top node, attaches each comment
145
+ * to a node, and throws for every comment that no printer printed that
146
+ * way. The diagram printers do not use that mechanism: they print
147
+ * comments and directives from the source between the things they print,
148
+ * because a directive can lie inside a name or touch a token without
149
+ * whitespace, and a comment can lie inside a statement written over
150
+ * several lines, where attaching them to nodes would move them.
151
+ */
152
+ interface FormattedDocument {
153
+ readonly type: "FormattedDocument";
154
+ readonly range: Range;
155
+ readonly root: Root;
156
+ /** The printer of the diagram type, chosen once while parsing. */
157
+ readonly printDiagram: DiagramPrinter;
158
+ /** The source text with the tree, for the printers. */
159
+ readonly source: Source;
160
+ /** Constraints selected with the diagram printer, when it needs them. */
161
+ readonly textRules: DiagramTextRules | undefined;
162
+ }
163
+ /** Every node Prettier walks through. */
164
+ type MermaidAst = FormattedDocument | Node;
165
+ //#endregion
166
+ //#region src/index.d.ts
167
+ export declare const languages: SupportLanguage[];
168
+ export declare const parsers: Record<string, Parser<MermaidAst>>;
169
+ export declare const printers: Record<string, Printer<MermaidAst>>;
170
+ declare const plugin: Plugin<MermaidAst>;
171
+ //#endregion
172
+ export { type FormattedDocument, type MermaidAst, plugin as default };