diff --git a/docs/API.md b/docs/API.md index 5cf6cddea..ceaf544a2 100644 --- a/docs/API.md +++ b/docs/API.md @@ -64,13 +64,13 @@ if (result.status !== ResultStatus.Succeeded) { > See the provided `.d.ts` TypeScript typings for full descriptions of inputs and outputs. -## Standalone API +## Standalone Lint Conversion 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. +Portions of the individual lint conversion 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. @@ -136,3 +136,59 @@ const raw = joinConfigConversionResults(summarizedConfiguration, originalConfigu const formatted = formatOutput("eslintrc.js", raw); ``` + +## Standalone Comment Conversion 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. + +The individual per-file conversion logic within `convertComments` is available as a standalone function: + +### `convertFileComments` + +Takes in a file's content and path, and returns the content with inline lint comments converted from TSLint to ESLint: + +```ts +import { convertFileComments } from "tslint-to-eslint-config"; + +// "// eslint-disable-next-line" +const newContents = convertFileComments({ + fileContent: "// tslint:disable-next-line", + filePath: "a.ts", +}); +``` + +If using this function across multiple files, pass it a `ruleCommentsCache` so it can skip some conversion calculations for a mild performance boost: + +```ts +import { convertFileComments } from "tslint-to-eslint-config"; + +const ruleCommentsCache = new Map(); + +const firstNewContents = convertFileComments({ + fileContent: "...", + filePath: "a.ts", + ruleCommentsCache, +}); + +const secondNewContents = convertFileComments({ + fileContent: "...", + filePath: "b.tsx", + ruleCommentsCache, +}); +``` + +If running alongside a lint config conversion, pass the filled out `ruleEquivalents` map for more accurate conversions of TSLint rules whose ESLint equivalents change on different arguments: + +```ts +import { convertFileComments, createESLintConfiguration } from "tslint-to-eslint-config"; + +const { ruleEquivalents } = await createESLintConfiguration(originalConfigurations); + +convertFileComments({ + fileContent: "...", + filePath: "a.ts", + ruleEquivalents, +}) +``` diff --git a/package-lock.json b/package-lock.json index ec53c1f4e..b73816951 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "tslint-to-eslint-config", - "version": "2.0.0-beta3", + "version": "2.0.0-beta4", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index a0593252c..d9d336924 100644 --- a/package.json +++ b/package.json @@ -76,5 +76,5 @@ "test:ci": "jest --coverage --maxWorkers=2", "tsc": "tsc" }, - "version": "2.0.0-beta3" + "version": "2.0.0-beta4" } diff --git a/src/api/convertFileCommentsStandalone.ts b/src/api/convertFileCommentsStandalone.ts new file mode 100644 index 000000000..4307a4f2b --- /dev/null +++ b/src/api/convertFileCommentsStandalone.ts @@ -0,0 +1,48 @@ +import { parseFileComments } from "../converters/comments/parseFileComments"; +import { replaceFileComments } from "../converters/comments/replaceFileComments"; +import { ruleConverters } from "../converters/lintConfigs/rules/ruleConverters"; + +export type ConvertFileCommentsStandaloneDependencies = { + /** + * Original content of the source file. + */ + fileContent: string; + + /** + * Absolute or relative path to the file. + * + * @remarks + * The file extension here is important, as parsing *.ts is different from *.tsx. + */ + filePath: string; + + /** + * Optional cache of comment conversions, for performance across multiple file conversions. + */ + ruleCommentsCache?: Map; + + /** + * Known rule equivalents as converted by a previous configuration. + */ + ruleEquivalents?: Map; +}; + +/** + * Replaces TSLint disable comments in source code with their ESLint equivalent. + */ +export const convertFileCommentsStandalone = ({ + fileContent, + filePath, + ruleCommentsCache = new Map(), + ruleEquivalents = new Map(), +}: ConvertFileCommentsStandaloneDependencies) => { + const comments = parseFileComments(filePath, fileContent); + + return replaceFileComments( + fileContent, + comments, + ruleConverters, + ruleCommentsCache, + ruleEquivalents, + ); +}; diff --git a/src/index.ts b/src/index.ts index 1de4fcb09..f01a6f20a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,3 +1,4 @@ +export { convertFileCommentsStandalone as convertFileComments } from "./api/convertFileCommentsStandalone"; export { convertTSLintConfigStandalone as convertTSLintConfig } from "./api/convertTSLintConfigStandalone"; export { createESLintConfigurationStandalone as createESLintConfiguration } from "./api/createESLintConfigurationStandalone"; export { findOriginalConfigurationsStandalone as findOriginalConfigurations } from "./api/findOriginalConfigurationsStandalone";