Fix tsc again; start on docs

Author: JoshuaKGoldberg

docs/Architecture/Comments.md

@@ -0,0 +1,22 @@
+# Comments
+
+Comment conversions in `src/converters/comments/convertComments.ts` are the last root-level converter to be run.
+The `ruleEquivalents` map it receives is filled out with the rule equivalents from earlier converters, i.e. lint rule converters.
+
+In general, its flow is:
+
+1. If no comments are requested to be converted, immediately report it out and mark this as passed.
+2. Create the list of include and possibly exclude globs to search on.
+3. Search for files matching those globs to have their comments converted.
+4. Convert comments in the contents of each file, storing equivalents in a cache.
+5. Report out the results of converting the unique globbed file paths.
+
+## File Manipulations
+
+Source files are parsed into TypeScript files by `src/comments/parseFileComments.ts`, which then extracts their comment nodes.
+Those comments are parsed for TSLint rule disable or enable comments.
+
+Comments that match will be rewritten in their their file to their new ESLint rule equivalent in `src/comments/replaceFileComments.ts`, as determined by:
+
+1. First, if the `ruleEquivalents` cache received from configuration convertion has the TSLint rule's ESLint equivalents listed, those are used.
+2. Failing that, a comment-specific `ruleCommentsCache` is populated with rules converted ad-hoc with no arguments.

docs/Architecture/Linters.md

@@ -0,0 +1,44 @@
+# Linters
+
+
+Within `src/converters/lintConfigs/convertLintConfig.ts`, the following steps occur:
+
+1. Existing configurations are read from disk
+2. TSLint rules are converted into their ESLint configurations
+3. ESLint configurations are summarized based on extended ESLint and TSLint presets
+    - 3a. If no output rules conflict with `eslint-config-prettier`, it's added in
+    - 3b. Any ESLint rules that are configured the same as an extended preset are trimmed
+4. The summarized configuration is written to the output config file
+5. Files to transform comments in have source text rewritten using the cached rule conversion results
+6. A summary of the results is printed to the user's console
+
+### Conversion Results
+
+The overall configuration generated by steps 2-3 and printed in 4-5 contains the following information:
+
+### Rule Converters
+
+Each TSLint rule should output at least one ESLint rule as the equivalent.
+"Converters" for TSLint rules are located in `src/rules/converters/`, and keyed under their names by the map in `src/rules/converters.ts`.
+
+Each converter for a TSLint rule takes an arguments object for the rule, and returns an array of objects containing:
+
+-   `rules`: At least one equivalent ESLint rule and options
+-   `notices`: Any extra info that should be printed after conversion
+-   `plugins`: Any plugins that should now be installed if not already
+
+The `rules` output is an array of objects containing:
+
+-   `ruleName`: Equivalent ESLint rule name that should be enabled
+-   `ruleArguments`: Any arguments for that ESLint rule
+
+Multiple objects must be supported because some general-use TSLint rules can only be represented by two or more ESLint rules.
+For example, TSLint's `no-banned-terms` is represented by ESLint's `no-caller` and `no-eval`.
+
+### Rule Mergers
+
+It's possible that one ESLint rule will be output by multiple converters.
+"Mergers" for those ESLint rules should take in two configurations to the same rule and output the equivalent single configuration.
+These are located in `src/rules/mergers/`, and keyed under their names by the map in `src/rules/mergers.ts`.
+
+For example, `@typescript-eslint/ban-types` spreads both arguments' `types` members into one large `types` object.

docs/Architecture/Linting.md

@@ -51,17 +51,6 @@ These are located in `src/rules/mergers/`, and keyed under their names by the ma
 
 For example, `@typescript-eslint/ban-types` spreads both arguments' `types` members into one large `types` object.
 
-## Comment Conversion
-
-Comments are converted after rule conversion by `src/comments/convertComments.ts`.
-Source files are parsed into TypeScript files by `src/comments/parseFileComments.ts`, which then extracts their comment nodes.
-Those comments are parsed for TSLint rule disable or enable comments.
-
-Comments that match will be rewritten in their their file to their new ESLint rule equivalent in `src/comments/replaceFileComments.ts`, as determined by:
-
-1. First, if the `ruleEquivalents` cache received from configuration convertion has the TSLint rule's ESLint equivalents listed, those are used.
-2. Failing that, a comment-specific `ruleCommentsCache` is populated with rules converted ad-hoc with no arguments.
-
 ## Editor Configuration Conversion
 
 Editor lint configurations are converted by `src/editorSettings/convertEditorSettings.ts`.

docs/Architecture/README.md

@@ -7,19 +7,9 @@ import { nativeImporter } from "../adapters/nativeImporter";
 import { processLogger } from "../adapters/processLogger";
 import { bind } from "../binding";
 import {
-    findEditorConfiguration,
-    FindEditorConfigurationDependencies,
-} from "../input/findEditorConfiguration";
-import { findESLintConfiguration } from "../input/findESLintConfiguration";
-import {
-    findOriginalConfigurations,
-    FindOriginalConfigurationsDependencies,
-} from "../input/findOriginalConfigurations";
-import { findPackagesConfiguration } from "../input/findPackagesConfiguration";
-import { findTSLintConfiguration } from "../input/findTSLintConfiguration";
-import { findTypeScriptConfiguration } from "../input/findTypeScriptConfiguration";
-import { importer, ImporterDependencies } from "../input/importer";
-import { mergeLintConfigurations } from "../input/mergeLintConfigurations";
+    collectCommentFileNames,
+    CollectCommentFileNamesDependencies,
+} from "../comments/collectCommentFileNames";
 import {
     ReportCommentResultsDependencies,
     reportCommentResults,
@@ -81,9 +71,23 @@ import { writeEditorConfigConversionResults } from "../converters/lintConfigs/wr
 import { addPrettierExtensions } from "../converters/lintConfigs/summarization/prettier/addPrettierExtensions";
 import { removeExtendsDuplicatedRules } from "../converters/lintConfigs/pruning/removeExtendsDuplicatedRules";
 import {
-    collectCommentFileNames,
-    CollectCommentFileNamesDependencies,
-} from "../comments/collectCommentFileNames";
+    ExtractGlobPathsDependencies,
+    extractGlobPaths,
+} from "../converters/comments/extractGlobPaths";
+import {
+    findEditorConfiguration,
+    FindEditorConfigurationDependencies,
+} from "../input/findEditorConfiguration";
+import { findESLintConfiguration } from "../input/findESLintConfiguration";
+import {
+    findOriginalConfigurations,
+    FindOriginalConfigurationsDependencies,
+} from "../input/findOriginalConfigurations";
+import { findPackagesConfiguration } from "../input/findPackagesConfiguration";
+import { findTSLintConfiguration } from "../input/findTSLintConfiguration";
+import { findTypeScriptConfiguration } from "../input/findTypeScriptConfiguration";
+import { importer, ImporterDependencies } from "../input/importer";
+import { mergeLintConfigurations } from "../input/mergeLintConfigurations";
 
 const convertFileCommentsDependencies: ConvertFileCommentsDependencies = {
     converters: ruleConverters,
@@ -133,10 +137,14 @@ const collectCommentFileNamesDependencies: CollectCommentFileNamesDependencies =
     findTypeScriptConfiguration: bind(findTypeScriptConfiguration, findConfigurationDependencies),
 };
 
+const extractGlobPathsDependencies: ExtractGlobPathsDependencies = {
+    globAsync,
+};
+
 const convertCommentsDependencies: ConvertCommentsDependencies = {
     collectCommentFileNames: bind(collectCommentFileNames, collectCommentFileNamesDependencies),
     convertFileComments: bind(convertFileComments, convertFileCommentsDependencies),
-    globAsync,
+    extractGlobPaths: bind(extractGlobPaths, extractGlobPathsDependencies),
     reportCommentResults: bind(reportCommentResults, reportCommentResultsDependencies),
 };
 

src/cli/main.ts

@@ -65,6 +65,7 @@ export const convertComments = async (
         };
     }
 
+    // 5. Report out the results of converting the unique globbed file paths.
     dependencies.reportCommentResults(uniqueGlobbedFilePaths);
 
     return {