@widgetic/dev-tools 0.3.8 → 0.3.9
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.
- package/CHANGELOG.md +2 -0
- package/README.md +69 -1
- package/bin/comment-console-logs.mjs +146 -0
- package/bin/publish-package.mjs +1 -1
- package/lib/comment-console-logs.d.mts +128 -0
- package/lib/comment-console-logs.mjs +609 -0
- package/lib/frontend-layout.mjs +3 -1
- package/lib/publish-to-npm.mjs +1 -0
- package/package.json +5 -3
- package/test/comment-console-logs.test.mjs +1104 -0
- package/test/frontend-layout.test.mjs +2 -1
- package/test/publish-to-npm.test.mjs +1 -0
package/CHANGELOG.md
CHANGED
|
@@ -11,6 +11,8 @@ reasons matter more than the categories.
|
|
|
11
11
|
- **`publish-all-to-npm`** (`bin/publish-all-to-npm.mjs`): walks the npm packages and runs each package's `publish-to-npm` script.
|
|
12
12
|
- The README contract no longer checks `recorder` or `__template__`. The linking tier is `embed-sdk` and `ui-sdk`. The adopter tier is the apps that compile sibling source.
|
|
13
13
|
- **`@widgetic/workflows` is a package of the walk.** `workflows` is in `PUBLISHABLE_PACKAGES` (after `widget-creator`, before `embed-sdk` and `ui-sdk`, which bundle it), in the publisher's `PACKAGE_PACKAGES`, and its module changelog (`modules/src/workflows/CHANGELOG.md`) is one of the files `publish-package.mjs` commits for ui-sdk. It is an adopter of the sibling-source README contract and a publisher of the publish-preparation one (`ADOPTER_PACKAGES`, `PUBLISH_PACKAGES`), and `SIBLING_PACKAGES` carries `workflows` so an app can alias its source in dev.
|
|
14
|
+
- **`@widgetic/workflows-engine` is a package of the walk.** It is in `PUBLISHABLE_PACKAGES` (right before `workflows`, which loads it, and before `embed-sdk` and `ui-sdk`, which bundle it), in the publisher's `BUILD_PACKAGES` (it builds with `npm run build`), and `SIBLING_PACKAGES` carries it as an entry package, so an app can alias its source in dev. It has no sibling dependencies, so it is not an adopter of the sibling-source README contract.
|
|
15
|
+
- **`comment-console-logs`** (`bin/comment-console-logs.mjs`, rules in `lib/comment-console-logs.mjs` with hand-written types): comments out `console.log`, `console.info`, `console.debug` and `console.trace` statements and keeps every one of them in the code, for a file or a directory of `.ts`, `.js`, `.mjs` and `.svelte` source. It reads the code as code (the TypeScript parser for scripts, the Svelte compiler's parser for `.svelte`, loaded from the checkout it edits or from `--resolve-from`, so neither is a dependency of this package), so a call in a string, a comment or a template literal is never mistaken for a call. A statement of its own is commented out with `// ` in front of each line after the indentation (taking the `// ` away gives it back), or between `/* */` when it shares its line with other code, and a standalone `{console.log(...)}` tag in a Svelte template becomes an HTML comment. It keeps, and reports with the reason: the body of a braceless `if`/`for`/`while`, a call that is a value (`() => console.log(x)`, `ok && console.log(x)`, `.catch(console.log)`, a tag in an attribute), a call behind an `if (DEBUG...)` switch in a script or an `{#if debugMode}` block, and a statement that cannot go in a comment without ending it (`*/` on a shared line, `-->` in a tag, a line separator character). `console.warn` and `console.error` are never touched. A call inside a statement that is commented out goes with it. Each file is read again after the change and written only when it reads as code the same way. Dry run unless told to `--write`; exit 1 when a path was not found, a file could not be read as code, or the parsers could not be loaded. `npm run test:comment-logs` (88 fixtures, also run against every TypeScript and Svelte pair the sibling checkouts have installed) fails, rather than skips, when no checkout has both parsers.
|
|
14
16
|
- **`npm run test:lists`** (`test/package-lists.test.mjs`): compares the four lists that name a package. A package in the walk but not in the publisher stops the walk part-way, after earlier packages were published; one in the publisher but not in the walk is only ever published by hand; one missing from the sibling layout throws in an app that selects it. The test fails on each, naming the file that needs the name.
|
|
15
17
|
|
|
16
18
|
### Changed
|
package/README.md
CHANGED
|
@@ -8,6 +8,7 @@ the repositories that consume it cannot drift apart.
|
|
|
8
8
|
| `check-runtime-deps` | Fails when a package's `package.json` and its published output disagree: a `dependencies` entry the output never imports (a *phantom*, install weight every consumer pays for), or an import the manifest does not declare (a *missing* dependency, which breaks a consumer's build). |
|
|
9
9
|
| `check-runtime-deps-fixtures` | Runs the fixture suite that proves the check above fails when it should. |
|
|
10
10
|
| `check-design-system-peers` | Fails when `canvas` and `file-browser` — the two peers that resolve `@widgetic/design-system` from the registry — disagree: lockfiles resolving different versions, or a lockfile that no longer matches the version the design-system checkout carries. Makes the next publish's consumer refresh land as one coordinated change instead of two drifted ones. |
|
|
11
|
+
| `comment-console-logs` | Comments out the debugging `console.log`, `console.info`, `console.debug` and `console.trace` statements of a codebase and keeps every one of them in the code. Reads the code with the TypeScript and Svelte parsers of the checkout it edits, comments out only what it can without changing what the program does, and says what it kept and why. Dry run unless told to `--write`. |
|
|
11
12
|
| `publish-all-to-npm` | Laptop fallback when GitLab has no compute minutes. Walks the npm packages and runs each package's own `publish-to-npm` script. |
|
|
12
13
|
|
|
13
14
|
It also ships two `lib/` modules with hand-written types and their own `node --test`
|
|
@@ -24,6 +25,9 @@ fixtures:
|
|
|
24
25
|
`check-design-system-peers` (with `lib/semver-lite.mjs`, the deliberately
|
|
25
26
|
tiny range test that fails closed on shapes it does not parse)
|
|
26
27
|
(`npm run test:peers`).
|
|
28
|
+
- `lib/comment-console-logs.mjs` — the rules behind `comment-console-logs`: what
|
|
29
|
+
is commented out, what is kept, and how a statement is commented out, with the
|
|
30
|
+
parsers handed in rather than depended on (`npm run test:comment-logs`).
|
|
27
31
|
|
|
28
32
|
A package that is new to the `Frontend/` checkouts is named in four lists that
|
|
29
33
|
do not know about each other: the publish walk (`lib/publish-to-npm.mjs`), the
|
|
@@ -327,6 +331,70 @@ here and a release** — not an edit in the consumer. Every entry needs a reason
|
|
|
327
331
|
specific enough that a reviewer can check it; each one is a claim the check can
|
|
328
332
|
no longer make.
|
|
329
333
|
|
|
334
|
+
## Commenting out console logs
|
|
335
|
+
|
|
336
|
+
`comment-console-logs` turns the debugging `console.log`, `console.info`,
|
|
337
|
+
`console.debug` and `console.trace` statements of a codebase into comments and
|
|
338
|
+
keeps every one of them in the code, so the console goes quiet without losing the
|
|
339
|
+
lines that explained what the code was doing. It reads the code with the parsers
|
|
340
|
+
it is built with, comments out only what it can without changing what the program
|
|
341
|
+
does, and says what it left alone and why.
|
|
342
|
+
|
|
343
|
+
```sh
|
|
344
|
+
npx comment-console-logs src # report only: no file is touched
|
|
345
|
+
npx comment-console-logs --write src # comment them out
|
|
346
|
+
npx comment-console-logs --write src/lib/App.svelte # one file
|
|
347
|
+
npx comment-console-logs --resolve-from ../site --write ../site/src # parsers from another checkout
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
Without `--write` it only reports: the same lines and the same counts, and no file
|
|
351
|
+
is touched. A path is a file or a directory. A directory is walked for `.ts`,
|
|
352
|
+
`.mts`, `.cts`, `.tsx`, `.js`, `.mjs`, `.cjs`, `.jsx` and `.svelte` files, without
|
|
353
|
+
entering `node_modules`, `dist`, `build`, `.svelte-kit`, `.output`, `coverage` or
|
|
354
|
+
`.git` (a directory named on the command line is always entered, and a link is not
|
|
355
|
+
followed). `typescript` and `svelte` are not dependencies of this package: they are
|
|
356
|
+
loaded from the current directory, or from the checkout `--resolve-from` names, so
|
|
357
|
+
the code is read with the TypeScript and the Svelte it is built with. Only the
|
|
358
|
+
parser a file needs is loaded.
|
|
359
|
+
|
|
360
|
+
What it does with each call:
|
|
361
|
+
|
|
362
|
+
| Where the call is | What happens |
|
|
363
|
+
| --- | --- |
|
|
364
|
+
| A statement of its own in a block, a file or a `case` | Commented out. A statement that begins and ends its lines gets `// ` in front of each line, after the indentation, so taking the `// ` away gives the original back (a blank line inside it gets `//`; a note after it stays). One that shares its line with other code goes between `/* ... */`. |
|
|
365
|
+
| A standalone `{console.log(...)}` tag in the markup of a Svelte file | Commented out as `<!-- {console.log(...)} -->`. |
|
|
366
|
+
| The body of a braceless `if`, `else`, `for`, `while`, `do` or a label | Kept: commenting it out would hand the next statement to the `if`. |
|
|
367
|
+
| A value: `() => console.log(x)`, `ok && console.log(x)`, `.catch(console.log)`, an argument, a `return`, a tag inside an attribute | Kept: nothing can be commented out without changing what the code returns or passes. |
|
|
368
|
+
| Behind an `if` that names a debug switch (`DEBUG...`, `isDebug...`, `debugMode`), a statement or a `{#if}` block | Kept: the switch is how the call is turned on, and commenting the call would leave a switch that does nothing. The `else` side, and a function or snippet declared inside the switch, are not behind it. |
|
|
369
|
+
| A statement that shares its line with other code and holds `*/`, a Svelte tag that holds `-->`, or a statement that holds a line separator character | Kept: none of them can be put in a comment without ending it early. |
|
|
370
|
+
| Inside a statement that is commented out | Goes with it, and is counted as "more inside them". |
|
|
371
|
+
|
|
372
|
+
`console.warn`, `console.error` and every other method are never touched: they
|
|
373
|
+
report things a partner or a developer has to see. A call written inside a string,
|
|
374
|
+
a comment or a template literal is not a call. `console[method](...)` and
|
|
375
|
+
`window.console.log(...)` are not recognised, so they are neither commented out nor
|
|
376
|
+
listed.
|
|
377
|
+
|
|
378
|
+
A file that does not parse is left alone. After the change each file is read
|
|
379
|
+
again, and it is only written when it reads as code the same way: no parse error,
|
|
380
|
+
and every call that was meant to stay is still there. A dry run does the same
|
|
381
|
+
check, so what it reports is what `--write` would do. The exit code is 0 when
|
|
382
|
+
every path was read, and 1 when a path was not found, a file could not be read as
|
|
383
|
+
code or written, the parsers could not be loaded, or the arguments were wrong.
|
|
384
|
+
|
|
385
|
+
Commenting out a log can leave a variable that only the log read, so run the
|
|
386
|
+
linter after it; an `// eslint-disable` that sat above a log stays where it was.
|
|
387
|
+
Taking the `// ` away by hand puts a statement back.
|
|
388
|
+
|
|
389
|
+
`npm run test:comment-logs` is the fixture suite. It loads `typescript` and
|
|
390
|
+
`svelte` the way the tool does: from `COMMENT_CONSOLE_LOGS_RESOLVE_FROM`, from the
|
|
391
|
+
current directory, or from any sibling checkout of this one that has both
|
|
392
|
+
installed. It fails when none has, because a skipped suite would prove nothing,
|
|
393
|
+
and it runs the same fixtures against every TypeScript and Svelte pair those
|
|
394
|
+
checkouts have. For that reason this package's own GitLab pipeline, which checks
|
|
395
|
+
dev-tools out alone, does not run it; `npm test` does, before every publish from a
|
|
396
|
+
laptop.
|
|
397
|
+
|
|
330
398
|
## Publishing from a laptop
|
|
331
399
|
|
|
332
400
|
GitLab CI on `main` remains the way a package is published. When the group has no compute minutes left, the same publish can be done from this checkout.
|
|
@@ -345,7 +413,7 @@ From `dev-tools`, walk every package:
|
|
|
345
413
|
npm run publish-all-to-npm
|
|
346
414
|
```
|
|
347
415
|
|
|
348
|
-
The walk is `api-sdk`, `cache-layer`, `design-system`, `dev-tools`, `canvas`, `chat`, `editor`, `file-browser`, `widget-creator`, `workflows`, `embed-sdk` and `ui-sdk`. `site` is not in it. These are the npm packages. The API SDK for Python, Ruby, C#, Java, PHP and Go is published from `api-gateway-service` with `scripts/publish-public-sdks.sh`, not by this walk.
|
|
416
|
+
The walk is `api-sdk`, `cache-layer`, `design-system`, `dev-tools`, `canvas`, `chat`, `editor`, `file-browser`, `widget-creator`, `workflows-engine`, `workflows`, `embed-sdk` and `ui-sdk`. `site` is not in it. These are the npm packages. The API SDK for Python, Ruby, C#, Java, PHP and Go is published from `api-gateway-service` with `scripts/publish-public-sdks.sh`, not by this walk.
|
|
349
417
|
|
|
350
418
|
## Releasing
|
|
351
419
|
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Comments out the debugging `console.log`, `console.info`, `console.debug` and `console.trace` calls of a codebase,
|
|
4
|
+
* keeps every one of them in the code, and says what it left alone and why.
|
|
5
|
+
*
|
|
6
|
+
* npx comment-console-logs [--write] [--resolve-from <dir>] <file or directory> [<file or directory> ...]
|
|
7
|
+
*
|
|
8
|
+
* Without `--write` it only reports: the same lines, the same counts, and no file is touched. With `--write` each
|
|
9
|
+
* file that changes is written back, and a file whose result does not read as code the same way is left as it was.
|
|
10
|
+
*
|
|
11
|
+
* `typescript` and `svelte` are not dependencies of this package. They are loaded from the checkout that is being
|
|
12
|
+
* edited (the current directory, or the one `--resolve-from` names), so the code is read with the parsers it is built
|
|
13
|
+
* with. A directory is walked for `.ts .mts .cts .tsx .js .mjs .cjs .jsx .svelte` files, without entering
|
|
14
|
+
* `node_modules`, `dist`, `build`, `.svelte-kit`, `.output`, `coverage` or `.git`.
|
|
15
|
+
*
|
|
16
|
+
* The rules (what is commented out, what is kept, and how) are in `lib/comment-console-logs.mjs`; this CLI reads the
|
|
17
|
+
* files, prints and sets the exit code: 0 when every file was read, 1 when a path was not found, a file could not be
|
|
18
|
+
* read as code or written, the parsers could not be loaded, or the arguments were wrong. The fixture suite that
|
|
19
|
+
* proves the rules is `test/comment-console-logs.test.mjs` (`npm run test:comment-logs` in this repo).
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import { readFileSync, writeFileSync } from 'node:fs';
|
|
23
|
+
import { resolve } from 'node:path';
|
|
24
|
+
import { parseArgs } from 'node:util';
|
|
25
|
+
|
|
26
|
+
import { collectSourceFiles, commentOutConsoleLogs, loadParsers, parsersNeededFor } from '../lib/comment-console-logs.mjs';
|
|
27
|
+
|
|
28
|
+
const LOG_PREFIX = '[comment-console-logs]';
|
|
29
|
+
|
|
30
|
+
const USAGE = `Usage: comment-console-logs [--write] [--resolve-from <dir>] <file or directory> [<file or directory> ...]
|
|
31
|
+
|
|
32
|
+
--write Write the changes. Without it, only report what would change.
|
|
33
|
+
--resolve-from <dir> Load typescript and svelte from this checkout (default: the current directory).
|
|
34
|
+
-h, --help Show this text.
|
|
35
|
+
|
|
36
|
+
Comments out console.log, console.info, console.debug and console.trace statements and keeps them in the code.
|
|
37
|
+
console.warn and console.error are never touched.`;
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* @returns {number} The exit code.
|
|
41
|
+
*/
|
|
42
|
+
function main() {
|
|
43
|
+
/** @type {ReturnType<typeof parseArgs>} */
|
|
44
|
+
let parsedArguments;
|
|
45
|
+
try {
|
|
46
|
+
parsedArguments = parseArgs({
|
|
47
|
+
args: process.argv.slice(2),
|
|
48
|
+
allowPositionals: true,
|
|
49
|
+
options: {
|
|
50
|
+
write: { type: 'boolean', default: false },
|
|
51
|
+
'resolve-from': { type: 'string' },
|
|
52
|
+
help: { type: 'boolean', short: 'h', default: false }
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
} catch (error) {
|
|
56
|
+
console.error(`${LOG_PREFIX} ${/** @type {Error} */ (error).message}\n\n${USAGE}`);
|
|
57
|
+
return 1;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
const { values, positionals } = parsedArguments;
|
|
61
|
+
if (values.help) {
|
|
62
|
+
console.log(USAGE);
|
|
63
|
+
return 0;
|
|
64
|
+
}
|
|
65
|
+
if (positionals.length === 0) {
|
|
66
|
+
console.error(`${LOG_PREFIX} no file or directory given\n\n${USAGE}`);
|
|
67
|
+
return 1;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const shouldWrite = values.write === true;
|
|
71
|
+
const resolveFromDirectory = resolve(typeof values['resolve-from'] === 'string' ? values['resolve-from'] : process.cwd());
|
|
72
|
+
let hadProblem = false;
|
|
73
|
+
|
|
74
|
+
const { files, problems } = collectSourceFiles(positionals);
|
|
75
|
+
for (const problem of problems) {
|
|
76
|
+
console.error(`${LOG_PREFIX} ${problem.path}: ${problem.reason}; skipped`);
|
|
77
|
+
hadProblem = true;
|
|
78
|
+
}
|
|
79
|
+
if (files.length === 0) {
|
|
80
|
+
console.log(`${LOG_PREFIX} no source files to read`);
|
|
81
|
+
return hadProblem ? 1 : 0;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
let parsers;
|
|
85
|
+
try {
|
|
86
|
+
parsers = loadParsers(resolveFromDirectory, parsersNeededFor(files));
|
|
87
|
+
} catch (error) {
|
|
88
|
+
console.error(`${LOG_PREFIX} ${/** @type {Error} */ (error).message}`);
|
|
89
|
+
return 1;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
console.log(shouldWrite ? `${LOG_PREFIX} writing the changes` : `${LOG_PREFIX} dry run: no file is touched (add --write to comment them out)`);
|
|
93
|
+
|
|
94
|
+
let commentedTotal = 0;
|
|
95
|
+
let commentedAlongTotal = 0;
|
|
96
|
+
let changedFiles = 0;
|
|
97
|
+
const keptLines = [];
|
|
98
|
+
|
|
99
|
+
for (const filePath of files) {
|
|
100
|
+
let sourceText;
|
|
101
|
+
try {
|
|
102
|
+
sourceText = readFileSync(filePath, 'utf8');
|
|
103
|
+
} catch (error) {
|
|
104
|
+
console.error(`${LOG_PREFIX} ${filePath}: could not be read (${/** @type {Error} */ (error).message}); skipped`);
|
|
105
|
+
hadProblem = true;
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const result = commentOutConsoleLogs(sourceText, filePath, parsers);
|
|
110
|
+
if (result.status === 'left alone') {
|
|
111
|
+
console.error(`${LOG_PREFIX} ${filePath}: ${result.reason}; left alone`);
|
|
112
|
+
hadProblem = true;
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
for (const finding of result.commented) console.log(`comment ${filePath}:${finding.line} ${finding.text}`);
|
|
117
|
+
for (const finding of result.kept) keptLines.push(`${filePath}:${finding.line} ${finding.reason} ${finding.text}`);
|
|
118
|
+
commentedTotal += result.commented.length;
|
|
119
|
+
commentedAlongTotal += result.commentedAlong;
|
|
120
|
+
|
|
121
|
+
if (result.status === 'commented') {
|
|
122
|
+
changedFiles += 1;
|
|
123
|
+
if (shouldWrite) {
|
|
124
|
+
try {
|
|
125
|
+
writeFileSync(filePath, result.updatedText);
|
|
126
|
+
} catch (error) {
|
|
127
|
+
console.error(`${LOG_PREFIX} ${filePath}: could not be written (${/** @type {Error} */ (error).message})`);
|
|
128
|
+
hadProblem = true;
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
const alongNote = commentedAlongTotal > 0 ? ` (${commentedAlongTotal} more inside them)` : '';
|
|
135
|
+
console.log(
|
|
136
|
+
`\n${shouldWrite ? 'Commented out' : 'Would comment out'}: ${commentedTotal}${alongNote} in ${changedFiles} file${changedFiles === 1 ? '' : 's'}. Kept: ${keptLines.length}.`
|
|
137
|
+
);
|
|
138
|
+
if (keptLines.length > 0) {
|
|
139
|
+
console.log('\nKept:');
|
|
140
|
+
for (const line of keptLines) console.log(` ${line}`);
|
|
141
|
+
}
|
|
142
|
+
return hadProblem ? 1 : 0;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
// Set the exit code and let the process end by itself: `process.exit` can cut a long report short when stdout is a pipe.
|
|
146
|
+
process.exitCode = main();
|
package/bin/publish-package.mjs
CHANGED
|
@@ -22,7 +22,7 @@ import { basename, join } from 'node:path';
|
|
|
22
22
|
const packageDir = process.cwd();
|
|
23
23
|
const packageName = basename(packageDir);
|
|
24
24
|
|
|
25
|
-
const BUILD_PACKAGES = new Set(['api-sdk', 'cache-layer', 'design-system']);
|
|
25
|
+
const BUILD_PACKAGES = new Set(['api-sdk', 'cache-layer', 'design-system', 'workflows-engine']);
|
|
26
26
|
const PACKAGE_PACKAGES = new Set(['canvas', 'chat', 'editor', 'file-browser', 'widget-creator', 'workflows']);
|
|
27
27
|
|
|
28
28
|
/**
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for the console-log commenter (`comment-console-logs.mjs`). Hand-written, dependency-free — same rules as
|
|
3
|
+
* `check-links.d.mts` beside it.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The loaded parsers. Neither is a dependency of this package: `loadParsers` resolves them from the checkout that is
|
|
8
|
+
* being edited.
|
|
9
|
+
*/
|
|
10
|
+
export interface Parsers {
|
|
11
|
+
/** The `typescript` module, needed for every file that is not `.svelte`. */
|
|
12
|
+
typescript?: any;
|
|
13
|
+
/** The `svelte/compiler` module, needed for `.svelte` files. */
|
|
14
|
+
svelteCompiler?: any;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** One place where the code calls `console.log` (or `info`, `debug`, `trace`) and what is done about it. */
|
|
18
|
+
export interface ConsoleFinding {
|
|
19
|
+
/** Offset of the first character of the call or statement. */
|
|
20
|
+
start: number;
|
|
21
|
+
/** Offset after its last character. */
|
|
22
|
+
end: number;
|
|
23
|
+
/** One-based line of `start`. */
|
|
24
|
+
line: number;
|
|
25
|
+
/** How the call sits in the code: a statement, a value, or a standalone tag in a Svelte template. */
|
|
26
|
+
shape: 'statement' | 'value' | 'template tag';
|
|
27
|
+
/** What the rules say to do with it. */
|
|
28
|
+
action: 'comment' | 'keep';
|
|
29
|
+
/** Why it is kept (one of `KEPT_REASONS`); absent when it is commented out. */
|
|
30
|
+
reason?: string;
|
|
31
|
+
/** The call on one line, cut at 110 characters. */
|
|
32
|
+
text: string;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** What `commentOutConsoleLogs` found and did for one file's text. */
|
|
36
|
+
export interface CommentOutResult {
|
|
37
|
+
/**
|
|
38
|
+
* `commented`: there is a new text. `unchanged`: nothing to comment out. `left alone`: the file could not be read as
|
|
39
|
+
* code, or the change did not check out.
|
|
40
|
+
*/
|
|
41
|
+
status: 'commented' | 'unchanged' | 'left alone';
|
|
42
|
+
/** Why the file was left alone. */
|
|
43
|
+
reason?: string;
|
|
44
|
+
/** The text with the statements commented out; the original text unless `status` is `commented`. */
|
|
45
|
+
updatedText: string;
|
|
46
|
+
/** The statements and tags that are commented out. */
|
|
47
|
+
commented: ConsoleFinding[];
|
|
48
|
+
/** The calls that stay as they are, each with its `reason`. */
|
|
49
|
+
kept: ConsoleFinding[];
|
|
50
|
+
/** How many more calls sat inside a commented statement (they go with it, and are not listed). */
|
|
51
|
+
commentedAlong: number;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** The edit that comments one finding out, or the reason it cannot be done without touching other code. */
|
|
55
|
+
export type PlannedEdit = { start: number; end: number; replacement: string } | { skip: string };
|
|
56
|
+
|
|
57
|
+
/** The console methods that are commented out. */
|
|
58
|
+
export declare const COMMENTED_CONSOLE_METHODS: readonly string[];
|
|
59
|
+
|
|
60
|
+
/** What a debug switch is called: a call behind an `if` that names one is kept. */
|
|
61
|
+
export declare const DEBUG_SWITCH_PATTERN: RegExp;
|
|
62
|
+
|
|
63
|
+
/** The extensions of the files the tool reads. */
|
|
64
|
+
export declare const SOURCE_FILE_EXTENSIONS: readonly string[];
|
|
65
|
+
|
|
66
|
+
/** The directories a walk does not enter. */
|
|
67
|
+
export declare const SKIPPED_DIRECTORY_NAMES: readonly string[];
|
|
68
|
+
|
|
69
|
+
/** Why a call is kept, one string per reason. */
|
|
70
|
+
export declare const KEPT_REASONS: Readonly<{
|
|
71
|
+
debugSwitch: string;
|
|
72
|
+
bracelessBody: string;
|
|
73
|
+
usedAsValue: string;
|
|
74
|
+
handedOver: string;
|
|
75
|
+
insideAttribute: string;
|
|
76
|
+
wrongPosition: string;
|
|
77
|
+
holdsCommentEnd: string;
|
|
78
|
+
holdsLineSeparator: string;
|
|
79
|
+
holdsHtmlCommentEnd: string;
|
|
80
|
+
}>;
|
|
81
|
+
|
|
82
|
+
/** Does the tool read this file by its extension? */
|
|
83
|
+
export declare function isSourceFile(filePath: string): boolean;
|
|
84
|
+
|
|
85
|
+
/** Which parsers the given files need: TypeScript for every script, the Svelte compiler for `.svelte`. */
|
|
86
|
+
export declare function parsersNeededFor(filePaths: string[]): { typescript: boolean; svelte: boolean };
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Loads `typescript` and `svelte/compiler` the way a file in `resolveFromDirectory` would. Only what is asked for is
|
|
90
|
+
* loaded. Throws, naming the packages and the directory, when one cannot be found.
|
|
91
|
+
*/
|
|
92
|
+
export declare function loadParsers(resolveFromDirectory: string, needs?: { typescript?: boolean; svelte?: boolean }): Parsers;
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Every `console.log` / `info` / `debug` / `trace` in the text, with what the rules say to do about each. Throws the
|
|
96
|
+
* Svelte compiler's error for a `.svelte` file that is not valid, and a `PARSER_NOT_LOADED` error when the parser the
|
|
97
|
+
* file needs was not handed over.
|
|
98
|
+
*/
|
|
99
|
+
export declare function findConsoleCalls(sourceText: string, filePath: string, parsers: Parsers): { findings: ConsoleFinding[]; parseErrors: number };
|
|
100
|
+
|
|
101
|
+
/** The edit that comments one finding out, or a `skip` with the reason. */
|
|
102
|
+
export declare function planEdit(sourceText: string, finding: ConsoleFinding): PlannedEdit;
|
|
103
|
+
|
|
104
|
+
/** Applies edits that do not overlap, last one first. */
|
|
105
|
+
export declare function applyEdits(sourceText: string, edits: { start: number; end: number; replacement: string }[]): string;
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Does the changed text read as code the same way: no parse error, no statement left to comment out apart from the ones
|
|
109
|
+
* that were skipped, and as many calls kept as before.
|
|
110
|
+
*/
|
|
111
|
+
export declare function checkCommentedText(
|
|
112
|
+
updatedText: string,
|
|
113
|
+
filePath: string,
|
|
114
|
+
parsers: Parsers,
|
|
115
|
+
expected: { skippedCount: number; keptCount: number }
|
|
116
|
+
): { ok: true } | { ok: false; reason: string };
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Comments out what can be commented out in one file's text, and says what it kept and why. Nothing is read or written
|
|
120
|
+
* here: the text goes in, the new text comes out.
|
|
121
|
+
*/
|
|
122
|
+
export declare function commentOutConsoleLogs(sourceText: string, filePath: string, parsers: Parsers): CommentOutResult;
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* The files to read for the paths given on the command line: a file is itself (when it is a kind of file the tool reads),
|
|
126
|
+
* a directory is every source file below it.
|
|
127
|
+
*/
|
|
128
|
+
export declare function collectSourceFiles(paths: string[]): { files: string[]; problems: { path: string; reason: string }[] };
|