@widgetic/dev-tools 0.3.7 → 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 CHANGED
@@ -10,6 +10,10 @@ reasons matter more than the categories.
10
10
  - **`publish-package.mjs`** (`bin/publish-package.mjs`): the laptop publish for every package. Each package's `publish-to-npm` script only calls this file. It does nothing when the latest commit already wrote the current version. Otherwise it raises the patch, publishes, commits the version files, tags the commit `v` plus the version, and pushes both. ui-sdk also releases the modules, and the tag is pushed after that release. embed-sdk also uploads its CDN file. dev-tools runs its tests before the version changes.
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
+ - **`@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.
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.
13
17
 
14
18
  ### Changed
15
19
 
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,17 @@ 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`).
31
+
32
+ A package that is new to the `Frontend/` checkouts is named in four lists that
33
+ do not know about each other: the publish walk (`lib/publish-to-npm.mjs`), the
34
+ publisher (`bin/publish-package.mjs`), the sibling layout
35
+ (`lib/frontend-layout.mjs`) and the README contract
36
+ (`lib/readme-contract.mjs`). `npm run test:lists` compares them, so a package
37
+ added to one and forgotten in another fails there, naming the file that needs
38
+ it, instead of stopping a walk part-way or being published only by hand.
27
39
 
28
40
  ## Why this is a published package
29
41
 
@@ -169,7 +181,7 @@ single place to land. `check-readme-contracts` turns that into a test:
169
181
  every adopter's sibling-source section must carry [the canonical
170
182
  sentences](lib/readme-contract.mjs), in order, with no link-era
171
183
  instructions in prose. The packages that publish to the registry (`chat`,
172
- `file-browser`) must also carry [the canonical
184
+ `file-browser`, `workflows`) must also carry [the canonical
173
185
  publish-preparation sentences](lib/readme-contract.mjs) — package the
174
186
  tarball, publish, and have every consumer refresh its lockfile in the same
175
187
  commit as its version bump. Run it as `npm run check:readme` here, or
@@ -319,6 +331,70 @@ here and a release** — not an edit in the consumer. Every entry needs a reason
319
331
  specific enough that a reviewer can check it; each one is a claim the check can
320
332
  no longer make.
321
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
+
322
398
  ## Publishing from a laptop
323
399
 
324
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.
@@ -337,7 +413,7 @@ From `dev-tools`, walk every package:
337
413
  npm run publish-all-to-npm
338
414
  ```
339
415
 
340
- The walk is `api-sdk`, `cache-layer`, `design-system`, `dev-tools`, `canvas`, `chat`, `editor`, `file-browser`, `widget-creator`, `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.
341
417
 
342
418
  ## Releasing
343
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();
@@ -22,8 +22,8 @@ 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']);
26
- const PACKAGE_PACKAGES = new Set(['canvas', 'chat', 'editor', 'file-browser', 'widget-creator']);
25
+ const BUILD_PACKAGES = new Set(['api-sdk', 'cache-layer', 'design-system', 'workflows-engine']);
26
+ const PACKAGE_PACKAGES = new Set(['canvas', 'chat', 'editor', 'file-browser', 'widget-creator', 'workflows']);
27
27
 
28
28
  /**
29
29
  * Run a command and stop the publish when it fails.
@@ -74,7 +74,12 @@ function versionCommitIsHead(version) {
74
74
  */
75
75
  function commitVersion(paths, detail) {
76
76
  const version = readVersion();
77
- const present = paths.filter((path) => existsSync(join(packageDir, path)));
77
+ // A path the repository ignores (dev-tools keeps no lockfile) cannot be added, and `git add` would stop the publish.
78
+ const present = paths.filter(
79
+ (path) =>
80
+ existsSync(join(packageDir, path)) &&
81
+ spawnSync('git', ['check-ignore', '-q', '--', path], { cwd: packageDir }).status !== 0
82
+ );
78
83
  run('git', ['add', '--', ...present]);
79
84
  run('git', ['commit', '-m', `chore: publish ${version}`, '-m', detail]);
80
85
  }
@@ -211,7 +216,8 @@ if (BUILD_PACKAGES.has(packageName)) {
211
216
  'modules/package-lock.json',
212
217
  'modules/src/composition-editor/CHANGELOG.md',
213
218
  'modules/src/file-browser/CHANGELOG.md',
214
- 'modules/src/widget-creator/CHANGELOG.md'
219
+ 'modules/src/widget-creator/CHANGELOG.md',
220
+ 'modules/src/workflows/CHANGELOG.md'
215
221
  ],
216
222
  '- Record the package patch and the modules patch that were just published'
217
223
  );
@@ -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 }[] };