-
Notifications
You must be signed in to change notification settings - Fork 101
Added Node API #732
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Added Node API #732
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
216a504
Added Node API
JoshuaKGoldberg 327cd65
Expanded node API
JoshuaKGoldberg f494ba1
Docs correction
JoshuaKGoldberg e012bc3
Added findReportedConfiguration and improved its docs area
JoshuaKGoldberg 1bdbe40
Lol, removed file system shenanigans
JoshuaKGoldberg c844743
Remove some export comments
JoshuaKGoldberg 9be1186
Switched debug write stream to being lazily created
JoshuaKGoldberg cfb125b
Merge branch 'main'
JoshuaKGoldberg cb19a65
rm unused vsCodeSettings file
JoshuaKGoldberg File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,138 @@ | ||
# API | ||
|
||
You can use `tslint-to-eslint-config` programmatically in your Node apps. | ||
It provides a **[`convertTSLintConfig`](#convertTSLintConfig)** function to find relevant configurations on disk and output the generated ESLint configuration. | ||
|
||
## `convertTSLintConfig` | ||
|
||
```ts | ||
import { convertTSLintConfig } from "tslint-to-eslint-config"; | ||
|
||
const result = await convertTSLintConfig(); | ||
``` | ||
|
||
Finds relevant configurations on disk and outputs the generated ESLint configuration. | ||
|
||
Optionally takes in the same settings you can provide via the CLI: | ||
|
||
* `config`: Output ESLint configuration file path _(default: `.eslintrc.js`)_. | ||
* `eslint`: Original ESLint configuration file path _(default: `.eslintrc.js`)_. | ||
* `package`: Original packages configuration file path _(default: `package.json`)_. | ||
* `prettier`: Whether to add `eslint-config-prettier` to the plugins list. | ||
* `tslint`: Original TSLint configuration file path _(default: `tslint.json`)_. | ||
* `typescript`: Original TypeScript configuration file path _(default: `tsconfig.json`)_. | ||
|
||
```ts | ||
import { convertTSLintConfig } from "tslint-to-eslint-config"; | ||
|
||
const result = await convertTSLintConfig({ | ||
config: "./path/to/output/eslintrc.js", | ||
eslint: "./path/to/input/eslintrc.js", | ||
package: "./path/to/package.json", | ||
prettier: true, // Prettier: highly recommended! | ||
tslint: "./path/to/tslint.json", | ||
typescript: "./path/to/tsconfig.json", | ||
}); | ||
``` | ||
|
||
If the TSLint configuration or any manually specified configurations fail to read from disk, the result will contain: | ||
|
||
* `complaints`: String complaints describing the errors. | ||
* `status`: `ResultStatus.ConfigurationError` (`2`). | ||
|
||
If no error is detected, the result will contain: | ||
|
||
* `data`: Resultant ESLint configuration as: | ||
* `formatted`: Stringified result per the output config path's file type. | ||
* `raw`: Plain old JavaScript object. | ||
* `status`: `ResultStatus.Succeeded` (`0`). | ||
|
||
```ts | ||
import { convertTSLintConfig, ResultStatus } from "tslint-to-eslint-config"; | ||
|
||
const result = await convertTSLintConfig({ /* ... */ }); | ||
|
||
if (result.status !== ResultStatus.Succeeded) { | ||
console.info("Oh no!"); | ||
console.error(result.complaints.join("\n")); | ||
} else { | ||
console.info("Hooray!"); | ||
console.log(result.data.formatted); | ||
console.log(result.data.raw); | ||
} | ||
``` | ||
|
||
> See the provided `.d.ts` TypeScript typings for full descriptions of inputs and outputs. | ||
|
||
## Standalone API | ||
|
||
> ⚠ This area of code is still considered experimental. | ||
> Use at your own risk. | ||
> Please file an issue on GitHub if you'd like to see changes. | ||
|
||
Portions of the individual steps within `convertTSLintConfig` are each available as exported functions as well. | ||
|
||
* **[`findOriginalConfigurations`](#findOriginalConfigurations)** takes in an object of original configuration locations and retrieves their raw and computed contents. | ||
* **[`findReportedConfiguration`](#findReportedConfiguration)** runs a config print command and parses its output as JSON. | ||
* **[`createESLintConfiguration`](#createESLintConfiguration)** creates an raw output ESLint configuration summary from those input configuration values. | ||
* `joinConfigConversionResults` turns a raw ESLint configuration summary into ESLint's configuration shape. | ||
* `formatOutput` prints that formatted output into a string per the output file extension. | ||
|
||
### `findOriginalConfigurations` | ||
|
||
Reading in from the default file locations, including `.eslintrc.js`: | ||
|
||
```ts | ||
import { findOriginalConfigurations } from "tslint-to-eslint-config"; | ||
|
||
const originalConfigurations = await findOriginalConfigurations(); | ||
``` | ||
|
||
Overriding some configuration file locations to read from: | ||
|
||
```ts | ||
import { findOriginalConfigurations } from "tslint-to-eslint-config"; | ||
|
||
const originalConfigurations = await findOriginalConfigurations({ | ||
config: "./path/to/.eslintrc.json", | ||
tslint: "./another/path/to/tslint.custom.json", | ||
}); | ||
``` | ||
|
||
#### `findReportedConfiguration` | ||
|
||
Retrieving the reported contents of a TSLint configuration: | ||
|
||
```ts | ||
import { findReportedConfiguration } from "tslint-to-eslint-config"; | ||
|
||
const full = await findReportedConfiguration("npx tslint --print-config", "./tslint.json"); | ||
``` | ||
|
||
### `createESLintConfiguration` | ||
|
||
Generating an ESLint configuration from the contents of a local `tslint.json`: | ||
|
||
```ts | ||
import { createESLintConfiguration, findReportedConfiguration } from "tslint-to-eslint-config"; | ||
|
||
const summarizedConfiguration = await createESLintConfiguration({ | ||
tslint: { | ||
full: await findReportedConfiguration("npx tslint --print-config", "./tslint.json"), | ||
raw: require("./tslint.json"), | ||
}, | ||
}); | ||
``` | ||
|
||
Using the full configuration values from disk: | ||
|
||
```ts | ||
import { createESLintConfiguration, findOriginalConfigurations } from "tslint-to-eslint-config"; | ||
|
||
const originalConfigurations = await findOriginalConfigurations(); | ||
const summarizedConfiguration = await createESLintConfiguration(originalConfigurations); | ||
|
||
const raw = joinConfigConversionResults(summarizedConfiguration, originalConfigurations.data); | ||
|
||
const formatted = formatOutput("eslintrc.js", raw); | ||
``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,64 @@ | ||
import { formatOutput } from "../converters/lintConfigs/formatting/formatOutput"; | ||
import { | ||
joinConfigConversionResults, | ||
JoinedConversionResult, | ||
} from "../converters/lintConfigs/joinConfigConversionResults"; | ||
import { | ||
ConfigurationErrorResult, | ||
LintConfigConversionSettings, | ||
ResultStatus, | ||
SucceededDataResult, | ||
} from "../types"; | ||
import { createESLintConfigurationStandalone } from "./createESLintConfigurationStandalone"; | ||
import { findOriginalConfigurationsStandalone } from "./findOriginalConfigurationsStandalone"; | ||
|
||
/** | ||
* Resultant configuration data from converting a TSLint configuration. | ||
*/ | ||
export type TSLintConversionData = { | ||
/** | ||
* Formatted configuration string per the output file's extension. | ||
*/ | ||
formatted: string; | ||
|
||
/** | ||
* Object description of the resultant configuration data. | ||
*/ | ||
raw: JoinedConversionResult; | ||
}; | ||
|
||
/** | ||
* Finds relevant configurations on disk and outputs the generated ESLint configuration. | ||
* | ||
* @param settings - Settings to find and convert configurations to an ESLint configuration. | ||
*/ | ||
export const convertTSLintConfigStandalone = async ( | ||
rawSettings: Partial<LintConfigConversionSettings> = {}, | ||
): Promise<ConfigurationErrorResult | SucceededDataResult<TSLintConversionData>> => { | ||
const settings = { | ||
...rawSettings, | ||
config: ".eslintrc.js", | ||
}; | ||
const originalConfigurations = await findOriginalConfigurationsStandalone(settings); | ||
if (originalConfigurations.status !== ResultStatus.Succeeded) { | ||
return originalConfigurations; | ||
} | ||
|
||
const summarizedConfiguration = await createESLintConfigurationStandalone( | ||
originalConfigurations.data, | ||
settings.prettier, | ||
); | ||
|
||
const output = joinConfigConversionResults( | ||
summarizedConfiguration, | ||
originalConfigurations.data, | ||
); | ||
|
||
return { | ||
data: { | ||
formatted: formatOutput(settings.config, output), | ||
raw: output, | ||
}, | ||
status: ResultStatus.Succeeded, | ||
}; | ||
}; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,49 @@ | ||
import { createESLintConfiguration } from "../converters/lintConfigs/createESLintConfiguration"; | ||
import { ESLintConfiguration } from "../input/findESLintConfiguration"; | ||
import { | ||
AllOriginalConfigurations, | ||
OriginalConfigurations, | ||
} from "../input/findOriginalConfigurations"; | ||
import { PackagesConfiguration } from "../input/findPackagesConfiguration"; | ||
import { TSLintConfiguration } from "../input/findTSLintConfiguration"; | ||
import { TypeScriptConfiguration } from "../input/findTypeScriptConfiguration"; | ||
import { createESLintConfigurationDependencies } from "./dependencies"; | ||
|
||
export type AllOriginalConfigurationsOptionally = { | ||
eslint?: Partial<OriginalConfigurations<ESLintConfiguration>>; | ||
packages?: PackagesConfiguration; | ||
tslint: Partial<OriginalConfigurations<TSLintConfiguration>>; | ||
typescript?: TypeScriptConfiguration; | ||
}; | ||
|
||
/** | ||
* Creates a raw output ESLint configuration summary from input configuration values. | ||
* | ||
* @param originalConfigurations | ||
* Any input configuration objects, including 'raw' (exact configuration file contents) | ||
* and 'full' (tool-reported computed values) for both ESLint and TSLint. | ||
* @param prettier | ||
* Whether to always consider the output configuration as extending from the Prettier | ||
* ruleset, instead of inferring it from computed rule values (recommended). | ||
*/ | ||
export const createESLintConfigurationStandalone = async ( | ||
originalConfigurations: AllOriginalConfigurations, | ||
prettier?: boolean, | ||
) => { | ||
const allOriginalConfigurations = { ...originalConfigurations }; | ||
|
||
if (allOriginalConfigurations.eslint) { | ||
allOriginalConfigurations.eslint.full ??= allOriginalConfigurations.eslint.raw; | ||
} | ||
|
||
if (allOriginalConfigurations.tslint) { | ||
allOriginalConfigurations.tslint.full ??= allOriginalConfigurations.tslint.raw; | ||
} | ||
|
||
return createESLintConfiguration( | ||
createESLintConfigurationDependencies, | ||
originalConfigurations, | ||
prettier, | ||
new Map<string, string[]>(), | ||
); | ||
}; |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.