/
definitions.ts
199 lines (184 loc) · 4.92 KB
/
definitions.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
/**
* The default registered tags
*/
export const enum DefaultTags {
todo = 'todo',
fixme = 'fixme',
}
/**
* Sometimes referred to as kind, this is usually a TODO or FIXME but can be any custom string
*/
export type Tag = string;
export interface ExtensionConfig {
/**
* The associated parser name(s) used to parse this extension
*/
parserName: string | string[];
/**
* A list of other filetypes (extensions) that might be included in this filetype (extension)
*/
includedFiles?: string[];
}
/**
* The supported extensions (filetypes) database
*/
export interface ExtensionsDb {
[extension: string]: ExtensionConfig;
}
export interface ParseConfig {
/**
* Associate the filetypes with parsers. This allows adding support for new filetypes, or overriding the config for existing ones.
*
* ```js
* {
* '.myExt1': { parserName: 'myCustomParser1' },
* '.myExt2': { parserName: 'myCustomParser2' },
* '.myExt3': { parserName: 'defaultParser' },
* }
* ```
*/
associateParser?: ExtensionsDb;
/**
* Extend or override the parsers by parserName, for example override the defaultParser or add a new parser
*
* ```js
* {
* myCustomParser1: function (parseOptions) {
* return function parse(contents, file) {
* const comments = [];
* // do something with contents
* comments.push({
* file: file,
* tag: 'TODO',
* line: 42,
* text: 'The comment text/body',
* ref: ''
* });
* return comments;
* }
* },
* myCustomParser2: function (parseOptions) {
* // etc
* },
* }
* ```
*/
customParsers?: CustomParsers;
/**
* Other tags to look for (besides todos and fixmes).
* Tags are case-insensitive and are strict matching, i.e PROD tag will match PROD but not PRODUCTS
*/
customTags?: Tag[];
/**
* The extension which identifies the filetype. Includes the dot if relevant (i.e: `.js`)
*/
extension: string;
/**
* The filename from which the content was derived from. Useful for reporting purposes
*/
filename?: string;
/**
* Whether to also parse known inline file associations (for example html in php files)
*/
withInlineFiles?: boolean;
}
export interface ParserFactoryConfig {
/**
* A list of custom tags to support
*/
customTags?: Tag[];
}
/**
* A parsed TODO (or other tag) comment
*
* ```js
* [{
* file: 'parsedFile.js',
* line: 8,
* ref: 'reference'
* tag: 'TODO',
* text: 'comment text',
* }]
* ```
*/
export interface TodoComment {
/**
* The filetype the comment originated from
*/
file: string;
/**
* The comment tag (usually TODO)
*/
tag: Tag;
/**
* Line number the comment was found in file
*/
line: number;
/**
* A possible reference used (either as prefix or postfix)
*/
ref: string;
/**
* The TODO (or other tag) text
*/
text: string;
}
/**
* receive the contents and file and return a list of parsed items
*/
export type Parser = (contents: string, file: string) => TodoComment[];
/**
* A factory to return a parser
*/
export type ParserFactory = (config: ParserFactoryConfig) => Parser;
export interface CustomParsers {
[parserName: string]: ParserFactory;
}
/**
* Report the provided items
*/
export type ReportItems = (comments: TodoComment[], config: any) => any;
export type ReporterName = string;
export type TransformComment = (file: string, line: number, ref: string, tag: Tag, text: string) => string | string[];
export type TransformHeader = (tag: Tag) => string | string[];
export interface ReporterConfig {
newLine?: string;
padding?: number;
transformComment?: TransformComment;
transformHeader?: TransformHeader;
}
export interface TransformedComments {
[tag: string]: string[];
}
export enum BuiltinReporters {
/**
* @hidden
*/
custom = 'custom',
/**
* Return a json string of the todos
*/
json = 'json',
/**
* Return a Markdown string of the todos
*/
markdown = 'markdown',
/**
* A raw reporter is the identity function for the todos
*/
raw = 'raw',
/**
* Return a table representation of the todos. Useful for CLI
*/
table = 'table',
/**
* Returns a markdown version of the todos customized for Visual Studio Code. The file names are
* transformed as URLs and the line numbers as anchors which makes them clickable when the markdown
* content produced with this reporter is opened on Visual Studio Code.
*/
vscode = 'vscode',
/**
* Return an XML string of the todos
*/
xml = 'xml',
}