Update architecture docs

Author: JoshuaKGoldberg

docs/Architecture/Editors.md

@@ -0,0 +1,13 @@
+# Editors
+
+Editor lint configurations are converted by `src/converters/editorConfigs/convertEditorConfig.ts`.
+Any setting that matches a known built-in TSLint setting will be replaced with the ESLint equivalent.
+
+For now, only VS Code editor settings are accounted for.
+Eventually this will be refactored to allow other editors such as Atom.
+
+1. An existing editor configuration is read from disk.
+2. If the existing configuration is not found or errored, nothing else needs to be done.
+3. Configuration settings are converted to their ESLint equivalents.
+4. Those ESLint equivalents are written to the configuration file.
+5. Results from converting are reported to the user.

docs/Architecture/Linters.md

@@ -1,20 +1,26 @@
 # Linters
 
-
+TSLint-to-ESLint linter configuration conversion is the first root-level converter run.
 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
+1. Raw TSLint rules are mapped to their ESLint equivalents.
+2. Those ESLint equivalents are deduplicated and relevant preset(s) detected.
+3. Those deduplicated rules and metadata are written to the output configuration file.
+4. A summary of conversion results is printed, along with any now-missing packages.
+
+## Rule Conversion
 
-### Conversion Results
+The parts of linter configurations most users focus on are the rule converters.
+Those are run by `src/converters/lintConfigs/rules/convertRules.ts`, which takes the following steps on each original TSLint rule:
 
-The overall configuration generated by steps 2-3 and printed in 4-5 contains the following information:
+1. The raw TSLint rule is converted to a standardized format.
+2. The appropriate converter is run for the rule.
+3. If the rule is missing or the conversion failed, this is marked.
+4. For each output rule equivalent given by the conversion:
+    * The output rule name is added to the TSLint rule's equivalency set.
+    * The TSLint rule's config severity is mapped to its ESLint equivalent.
+    * If this is the first time the output ESLint rule is seen, it's directly marked as converted.
+    * If not, a rule merger is run to combine it with its existing output settings.
 
 ### Rule Converters
 
@@ -42,3 +48,10 @@ It's possible that one ESLint rule will be output by multiple converters.
 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.
+
+## Package Summaries
+
+ESLint configurations are summarized based on extended ESLint and TSLint presets.
+
+- If no output rules conflict with `eslint-config-prettier`, it's added in.
+- Any ESLint rules that are configured the same as an extended preset are trimmed.

docs/Architecture/README.md

@@ -1,57 +1,26 @@
 # Architecture
 
-## CLI Architecture
+tslint-to-eslint-config is a heavily tested CLI app that uses rudimentary [dependency injection](https://wikipedia.org/wiki/Dependency_injection) to link functions together.
 
-1.  CLI usage starts in `bin/tslint-to-eslint-config`, which immediately calls `src/cli/main.ts`.
-2.  CLI settings are parsed and read in `src/cli/runCli.ts`.
-3.  Linter configuration conversion is run by `src/conversion/convertLintConfig.ts`.
-4.  Editor configuration conversion is run by `src/conversion/convertEditorConfig.ts`.
+The initial application flow starts in `bin/tslint-to-eslint-config`:
 
-## Linter Configuration Conversion
+1. `src/cli/main.ts`'s `main` is called with `process.argv` as the program arguments.
+    * This file sets up all function dependencies and bound functions that call to each other.
+2. `src/cli/runCli.ts`'s `runCli` is called with those bound dependencies and raw arguments.
 
-Within `src/conversion/convertLintConfig.ts`, the following steps occur:
+> See [Dependencies.md](./Dependencies.md) for more info on dependency bindings.
 
-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
+## CLI Runner
 
-### Conversion Results
+1. CLI options are parsed from the raw arguments into a commands object.
+2. If the version should be printed, we do that and stop execution.
+3. Any existing linter and TypeScript configurations are read from disk.
+4. Each converter is run, halting execution if it fails.
 
-The overall configuration generated by steps 2-3 and printed in 4-5 contains the following information:
+## Converters
 
-### Rule Converters
+Within that flow, there are three "root-level" converters directly called by `runCli`, in order:
 
-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.
-
-## Editor Configuration Conversion
-
-Editor lint configurations are converted by `src/editorSettings/convertEditorSettings.ts`.
-Any setting that matches a known built-in TSLint setting will be replaced with the ESLint equivalent.
+1. **[Linters.md](./Linters.md)**: Converting from an original TSLint configuration to the equivalent TSLint configuration.
+2. **[Editors.md](./Editors.md)**: Creating new IDE settings for ESLint equivalent to any existing TSLint settings.
+3. **[Comments.md](./Comments.md)**: Converting inline `tslint:disable` lint disable comments to their `eslint-disable` equivalents.

src/cli/runCli.ts

@@ -19,10 +19,14 @@ export type RunCliDependencies = {
     logger: Logger;
 };
 
+/**
+ * @see `/docs/Architecture/README.md` for documentation.
+ */
 export const runCli = async (
     dependencies: RunCliDependencies,
     rawArgv: string[],
 ): Promise<ResultStatus> => {
+    // 1. CLI options are parsed from the raw arguments into a commands object.
     const command = new Command()
         .storeOptionsAsProperties(false)
         .usage("[options] <file ...> --language [language]")
@@ -41,17 +45,20 @@ export const runCli = async (
         ...command.parse(rawArgv).opts(),
     } as TSLintToESLintSettings;
 
+    // 2. If the version should be printed, we do that and stop execution.
     if (command.opts().version) {
         dependencies.logger.stdout.write(`${version}${EOL}`);
         return ResultStatus.Succeeded;
     }
 
+    // 3. Any existing linter and TypeScript configurations are read from disk.
     const originalConfigurations = await dependencies.findOriginalConfigurations(parsedArgv);
     if (originalConfigurations.status !== ResultStatus.Succeeded) {
         logErrorResult(originalConfigurations, dependencies.logger);
         return originalConfigurations.status;
     }
 
+    // 4. Each converter is run, halting execution if it fails.
     for (const converter of dependencies.converters) {
         const result = await tryConvertConfig(converter, parsedArgv, originalConfigurations.data);
         if (result.status !== ResultStatus.Succeeded) {

src/converters/editorConfigs/convertEditorConfig.ts

@@ -22,29 +22,33 @@ export const convertEditorConfig = async (
     dependencies: ConvertEditorConfigDependencies,
     settings: TSLintToESLintSettings,
 ): Promise<ResultWithStatus> => {
-    const conversion = await dependencies.findEditorConfiguration(settings.editor);
-    if (conversion === undefined) {
+    // 1. An existing editor configuration is read from disk.
+    const configuration = await dependencies.findEditorConfiguration(settings.editor);
+
+    // 2. If the existing configuration is not found or errored, nothing else needs to be done.
+    if (configuration === undefined) {
         return {
             status: ResultStatus.Succeeded,
         };
     }
-
-    if (conversion.result instanceof Error) {
+    if (configuration.result instanceof Error) {
         return {
-            errors: [conversion.result],
+            errors: [configuration.result],
             status: ResultStatus.Failed,
         };
     }
 
+    // 3. Configuration settings are converted to their ESLint equivalents.
     const settingConversionResults = dependencies.convertEditorSettings(
-        conversion.result,
+        configuration.result,
         settings,
     );
 
+    // 4. Those ESLint equivalents are written to the configuration file.
     const fileWriteError = await dependencies.writeEditorConfigConversionResults(
-        conversion.configPath,
+        configuration.configPath,
         settingConversionResults,
-        conversion.result,
+        configuration.result,
     );
     if (fileWriteError !== undefined) {
         return {
@@ -53,6 +57,7 @@ export const convertEditorConfig = async (
         };
     }
 
+    // 5. Results from converting are reported to the user.
     dependencies.reportEditorSettingConversionResults(settingConversionResults);
 
     return {

src/converters/lintConfigs/convertLintConfig.ts

@@ -25,18 +25,21 @@ export const convertLintConfig = async (
     originalConfigurations: AllOriginalConfigurations,
     ruleEquivalents: Map<string, string[]>,
 ): Promise<ResultWithStatus> => {
+    // 1. Raw TSLint rules are mapped to their ESLint equivalents.
     const ruleConversionResults = dependencies.convertRules(
         originalConfigurations.tslint.full.rules,
         ruleEquivalents,
     );
 
+    // 2. Those ESLint equivalents are deduplicated and relevant preset(s) detected.
     const summarizedConfiguration = await dependencies.summarizePackageRules(
         originalConfigurations.eslint,
         originalConfigurations.tslint,
         ruleConversionResults,
         settings.prettier,
     );
 
+    // 3. Those deduplicated rules and metadata are written to the output configuration file.
     const fileWriteError = await dependencies.writeConfigConversionResults(
         settings.config,
         summarizedConfiguration,
@@ -49,8 +52,8 @@ export const convertLintConfig = async (
         };
     }
 
+    // 4. A summary of conversion results is printed, along with any now-missing packages.
     await dependencies.reportConfigConversionResults(settings.config, summarizedConfiguration);
-
     await dependencies.logMissingPackages(summarizedConfiguration, originalConfigurations.packages);
 
     return {

src/converters/lintConfigs/rules/convertRules.ts

@@ -21,6 +21,10 @@ export type RuleConversionResults = {
     ruleEquivalents: Map<string, string[]>;
 };
 
+/**
+ * Converts raw TSLint rules to their ESLint equivalents.
+ * @see `/docs/Architecture/Linting.md` for documentation.
+ */
 export const convertRules = (
     dependencies: ConvertRulesDependencies,
     rawTslintRules: TSLintConfigurationRules | undefined,
@@ -33,9 +37,13 @@ export const convertRules = (
 
     if (rawTslintRules !== undefined) {
         for (const [ruleName, value] of Object.entries(rawTslintRules)) {
+            // 1. The raw TSLint rule is converted to a standardized format.
             const tslintRule = formatRawTslintRule(ruleName, value);
+
+            // 2. The appropriate converter is run for the rule.
             const conversion = convertRule(tslintRule, dependencies.ruleConverters);
 
+            // 3. If the rule is missing or the conversion failed, this is marked.
             if (conversion === undefined) {
                 if (tslintRule.ruleSeverity !== "off") {
                     missing.push(tslintRule);
@@ -51,20 +59,25 @@ export const convertRules = (
 
             const equivalents = new Set<string>();
 
+            // 4. For each output rule equivalent given by the conversion:
             for (const changes of conversion.rules) {
+                // 4a. The output rule name is added to the TSLint rule's equivalency set.
                 equivalents.add(changes.ruleName);
 
+                // 4b. The TSLint rule's config severity is mapped to its ESLint equivalent.
                 const existingConversion = converted.get(changes.ruleName);
                 const newConversion = {
                     ...changes,
                     ruleSeverity: convertTSLintRuleSeverity(tslintRule.ruleSeverity),
                 };
 
+                // 4c. If this is the first time the output ESLint rule is seen, it's directly marked as converted.
                 if (existingConversion === undefined) {
                     converted.set(changes.ruleName, newConversion);
                     continue;
                 }
 
+                // 4d. If not, a rule merger is run to combine it with its existing output settings.
                 const merger = dependencies.ruleMergers.get(changes.ruleName);
                 if (merger === undefined) {
                     failed.push(ConversionError.forMerger(changes.ruleName));

src/converters/lintConfigs/rules/ruleConverters/no-banned-terms.ts

@@ -2,7 +2,7 @@ import { RuleConverter } from "../ruleConverter";
 
 export const convertNoBannedTerms: RuleConverter = () => {
     return {
-        // This is mentioned in Architecture.md as a TSLint rule with two ESLint equivalents
+        // This is mentioned in Architecture/Linters.md as a TSLint rule with two ESLint equivalents
         rules: [
             {
                 ruleName: "no-caller",

src/converters/lintConfigs/rules/ruleMergers/ban-types.ts

@@ -5,7 +5,7 @@ export const mergeBanTypes: RuleMerger = (existingOptions, newOptions) => {
         return [];
     }
 
-    // This is mentioned in Architecture.md as an ESLint rule with a merger
+    // This is mentioned in Architecture/Linters.md as an ESLint rule with a merger
     return [
         {
             types: {