diff --git a/README.md b/README.md index 2e2c7916..9a969c62 100644 --- a/README.md +++ b/README.md @@ -659,9 +659,9 @@ Standard completion callback. Type: `Object` -Call `result.toString()` for convenience or see below for an example of the -structure of the `result` object. Passing the value `true` to `toString()` -uses rule aliases (ex: `no-hard-tabs`) instead of names (ex: `MD010`). +Map of input file/string to errors within. + +See [the Usage section](#usage) for an example of the structure of this object. ### Config @@ -837,7 +837,7 @@ console.log(getVersion()); ## Usage -Invoke `lint` and use the `result` object's `toString` method: +Invoke `lint` as an asynchronous call: ```javascript import { lint as lintAsync } from "markdownlint/async"; @@ -852,34 +852,21 @@ const options = { lintAsync(options, function callback(error, results) { if (!error && results) { - console.log(results.toString()); + console.dir(results, { "colors": true, "depth": null }); } }); ``` -Output: - -```text -bad.string: 3: MD010/no-hard-tabs Hard tabs [Column: 19] -bad.string: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.string"] -bad.string: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This string fails some rules."] -bad.string: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.string"] -bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17] -bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"] -bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails some rules."] -bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"] -``` - Or as a synchronous call: ```javascript import { lint as lintSync } from "markdownlint/sync"; const results = lintSync(options); -console.log(results.toString()); +console.dir(results, { "colors": true, "depth": null }); ``` -To examine the `result` object directly via a `Promise`-based call: +Or as a `Promise`-based call: ```javascript import { lint as lintPromise } from "markdownlint/promise"; @@ -888,7 +875,7 @@ const results = await lintPromise(options); console.dir(results, { "colors": true, "depth": null }); ``` -Output: +All of which output something like: ```json { @@ -900,28 +887,32 @@ Output: "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md010.md", "errorDetail": "Column: 17", "errorContext": null, - "errorRange": [ 17, 1 ] }, + "errorRange": [ 17, 1 ], + "fixInfo": { "editColumn": 17, "deleteCount": 1, "insertText": ' ' } } { "lineNumber": 1, "ruleNames": [ "MD018", "no-missing-space-atx" ], "ruleDescription": "No space after hash on atx style heading", "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md018.md", "errorDetail": null, "errorContext": "#bad.md", - "errorRange": [ 1, 2 ] }, + "errorRange": [ 1, 2 ], + "fixInfo": { "editColumn": 2, "insertText": ' ' } } { "lineNumber": 3, "ruleNames": [ "MD018", "no-missing-space-atx" ], "ruleDescription": "No space after hash on atx style heading", "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md018.md", "errorDetail": null, "errorContext": "#This file fails\tsome rules.", - "errorRange": [ 1, 2 ] }, + "errorRange": [ 1, 2 ], + "fixInfo": { "editColumn": 2, "insertText": ' ' } } { "lineNumber": 1, "ruleNames": [ "MD041", "first-line-heading", "first-line-h1" ], "ruleDescription": "First line in a file should be a top-level heading", "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md041.md", "errorDetail": null, "errorContext": "#bad.md", - "errorRange": null } + "errorRange": null, + "fixInfo": null } ] } ``` @@ -957,7 +948,7 @@ const options = { } }; -const results = globalThis.markdownlint.lintSync(options).toString(); +const results = globalThis.markdownlint.lintSync(options); ``` ## Examples diff --git a/example/standalone.mjs b/example/standalone.mjs index 2614e14b..866d0a8b 100644 --- a/example/standalone.mjs +++ b/example/standalone.mjs @@ -18,18 +18,18 @@ const options = { if (true) { - // Makes a synchronous call, uses result.toString for pretty formatting + // Makes a synchronous call const results = lintSync(options); - console.log(results.toString()); + console.dir(results, { "colors": true, "depth": null }); } if (true) { - // Makes an asynchronous call, uses result.toString for pretty formatting + // Makes an asynchronous call lintAsync(options, function callback(error, results) { if (!error && results) { - console.log(results.toString()); + console.dir(results, { "colors": true, "depth": null }); } }); @@ -37,7 +37,7 @@ if (true) { if (true) { - // Makes a Promise-based asynchronous call, displays the result object directly + // Makes a Promise-based asynchronous call const results = await lintPromise(options); console.dir(results, { "colors": true, "depth": null }); diff --git a/example/typescript/type-check.ts b/example/typescript/type-check.ts index 5abc47f0..4bc3e04c 100644 --- a/example/typescript/type-check.ts +++ b/example/typescript/type-check.ts @@ -171,13 +171,15 @@ lintAsync(options, assertLintResultsCallback); assertLintResultsCallback(null, await lintPromise(options)); })(); +const needsFixing = "# Heading\n"; + assert.equal( applyFix( - "# Fixing\n", + needsFixing, { - "insertText": "Head", - "editColumn": 3, - "deleteCount": 3 + "insertText": " ", + "editColumn": 2, + "deleteCount": 2 }, "\n" ), @@ -186,17 +188,12 @@ assert.equal( assert.equal( applyFixes( - "# Fixing\n", - [ - { - "lineNumber": 1, - "fixInfo": { - "insertText": "Head", - "editColumn": 3, - "deleteCount": 3 - } + needsFixing, + lintSync({ + "strings": { + needsFixing } - ] + })["needsFixing"] ), "# Heading\n" ); diff --git a/lib/exports.d.mts b/lib/exports.d.mts index afac5561..ebffe920 100644 --- a/lib/exports.d.mts +++ b/lib/exports.d.mts @@ -3,6 +3,7 @@ export type Configuration = import("./markdownlint.mjs").Configuration; export type ConfigurationParser = import("./markdownlint.mjs").ConfigurationParser; export type ConfigurationStrict = import("./markdownlint.mjs").ConfigurationStrict; export type FixInfo = import("./markdownlint.mjs").FixInfo; +export type FixInfoNormalized = import("./markdownlint.mjs").FixInfoNormalized; export type LintCallback = import("./markdownlint.mjs").LintCallback; export type LintContentCallback = import("./markdownlint.mjs").LintContentCallback; export type LintError = import("./markdownlint.mjs").LintError; @@ -23,7 +24,6 @@ export type RuleConfiguration = import("./markdownlint.mjs").RuleConfiguration; export type RuleFunction = import("./markdownlint.mjs").RuleFunction; export type RuleOnError = import("./markdownlint.mjs").RuleOnError; export type RuleOnErrorFixInfo = import("./markdownlint.mjs").RuleOnErrorFixInfo; -export type RuleOnErrorFixInfoNormalized = import("./markdownlint.mjs").RuleOnErrorFixInfoNormalized; export type RuleOnErrorInfo = import("./markdownlint.mjs").RuleOnErrorInfo; export type RuleParams = import("./markdownlint.mjs").RuleParams; export { applyFix, applyFixes, formatLintError, getVersion, parseLintErrorString } from "./markdownlint.mjs"; diff --git a/lib/exports.mjs b/lib/exports.mjs index d96ab78b..dd6551cd 100644 --- a/lib/exports.mjs +++ b/lib/exports.mjs @@ -7,6 +7,7 @@ export { resolveModule } from "./resolve-module.cjs"; /** @typedef {import("./markdownlint.mjs").ConfigurationParser} ConfigurationParser */ /** @typedef {import("./markdownlint.mjs").ConfigurationStrict} ConfigurationStrict */ /** @typedef {import("./markdownlint.mjs").FixInfo} FixInfo */ +/** @typedef {import("./markdownlint.mjs").FixInfoNormalized} FixInfoNormalized */ /** @typedef {import("./markdownlint.mjs").LintCallback} LintCallback */ /** @typedef {import("./markdownlint.mjs").LintContentCallback} LintContentCallback */ /** @typedef {import("./markdownlint.mjs").LintError} LintError */ @@ -27,6 +28,5 @@ export { resolveModule } from "./resolve-module.cjs"; /** @typedef {import("./markdownlint.mjs").RuleFunction} RuleFunction */ /** @typedef {import("./markdownlint.mjs").RuleOnError} RuleOnError */ /** @typedef {import("./markdownlint.mjs").RuleOnErrorFixInfo} RuleOnErrorFixInfo */ -/** @typedef {import("./markdownlint.mjs").RuleOnErrorFixInfoNormalized} RuleOnErrorFixInfoNormalized */ /** @typedef {import("./markdownlint.mjs").RuleOnErrorInfo} RuleOnErrorInfo */ /** @typedef {import("./markdownlint.mjs").RuleParams} RuleParams */ diff --git a/lib/markdownlint.d.mts b/lib/markdownlint.d.mts index 8a6df4d6..ce8715bf 100644 --- a/lib/markdownlint.d.mts +++ b/lib/markdownlint.d.mts @@ -63,19 +63,19 @@ export function readConfigSync(file: string, parsers?: ConfigurationParser[], fs * Applies the specified fix to a Markdown content line. * * @param {string} line Line of Markdown content. - * @param {RuleOnErrorFixInfo} fixInfo RuleOnErrorFixInfo instance. + * @param {FixInfo} fixInfo FixInfo instance. * @param {string} [lineEnding] Line ending to use. * @returns {string | null} Fixed content or null if deleted. */ -export function applyFix(line: string, fixInfo: RuleOnErrorFixInfo, lineEnding?: string): string | null; +export function applyFix(line: string, fixInfo: FixInfo, lineEnding?: string): string | null; /** * Applies as many of the specified fixes as possible to Markdown content. * * @param {string} input Lines of Markdown content. - * @param {RuleOnErrorInfo[]} errors RuleOnErrorInfo instances. + * @param {LintError[]} errors LintError instances. * @returns {string} Fixed content. */ -export function applyFixes(input: string, errors: RuleOnErrorInfo[]): string; +export function applyFixes(input: string, errors: LintError[]): string; /** * TBD * @@ -335,27 +335,6 @@ export type RuleOnErrorFixInfo = { */ insertText?: string; }; -/** - * RuleOnErrorInfo with all optional properties present. - */ -export type RuleOnErrorFixInfoNormalized = { - /** - * Line number (1-based). - */ - lineNumber: number; - /** - * Column of the fix (1-based). - */ - editColumn: number; - /** - * Count of characters to delete. - */ - deleteCount: number; - /** - * Text to insert (after deleting). - */ - insertText: string; -}; /** * Rule definition. */ @@ -521,6 +500,27 @@ export type FixInfo = { */ insertText?: string; }; +/** + * FixInfo with all optional properties present. + */ +export type FixInfoNormalized = { + /** + * Line number (1-based). + */ + lineNumber: number; + /** + * Column of the fix (1-based). + */ + editColumn: number; + /** + * Count of characters to delete. + */ + deleteCount: number; + /** + * Text to insert (after deleting). + */ + insertText: string; +}; /** * Called with the result of linting a string or document. */ diff --git a/lib/markdownlint.mjs b/lib/markdownlint.mjs index d3cee171..105a473f 100644 --- a/lib/markdownlint.mjs +++ b/lib/markdownlint.mjs @@ -1195,9 +1195,9 @@ export function readConfigSync(file, parsers, fs) { /** * Normalizes the fields of a RuleOnErrorFixInfo instance. * - * @param {RuleOnErrorFixInfo} fixInfo RuleOnErrorFixInfo instance. + * @param {FixInfo} fixInfo RuleOnErrorFixInfo instance. * @param {number} [lineNumber] Line number. - * @returns {RuleOnErrorFixInfoNormalized} Normalized RuleOnErrorFixInfo instance. + * @returns {FixInfoNormalized} Normalized RuleOnErrorFixInfo instance. */ function normalizeFixInfo(fixInfo, lineNumber = 0) { return { @@ -1212,7 +1212,7 @@ function normalizeFixInfo(fixInfo, lineNumber = 0) { * Applies the specified fix to a Markdown content line. * * @param {string} line Line of Markdown content. - * @param {RuleOnErrorFixInfo} fixInfo RuleOnErrorFixInfo instance. + * @param {FixInfo} fixInfo FixInfo instance. * @param {string} [lineEnding] Line ending to use. * @returns {string | null} Fixed content or null if deleted. */ @@ -1228,7 +1228,7 @@ export function applyFix(line, fixInfo, lineEnding = "\n") { * Applies as many of the specified fixes as possible to Markdown content. * * @param {string} input Lines of Markdown content. - * @param {RuleOnErrorInfo[]} errors RuleOnErrorInfo instances. + * @param {LintError[]} errors LintError instances. * @returns {string} Fixed content. */ export function applyFixes(input, errors) { @@ -1463,16 +1463,6 @@ export function getVersion() { * @property {string} [insertText] Text to insert (after deleting). */ -/** - * RuleOnErrorInfo with all optional properties present. - * - * @typedef {Object} RuleOnErrorFixInfoNormalized - * @property {number} lineNumber Line number (1-based). - * @property {number} editColumn Column of the fix (1-based). - * @property {number} deleteCount Count of characters to delete. - * @property {string} insertText Text to insert (after deleting). - */ - /** * Rule definition. * @@ -1561,6 +1551,16 @@ export function getVersion() { * @property {string} [insertText] Text to insert (after deleting). */ +/** + * FixInfo with all optional properties present. + * + * @typedef {Object} FixInfoNormalized + * @property {number} lineNumber Line number (1-based). + * @property {number} editColumn Column of the fix (1-based). + * @property {number} deleteCount Count of characters to delete. + * @property {string} insertText Text to insert (after deleting). + */ + /** * Called with the result of linting a string or document. *