RFC: textlint new message format

[azu]

This is collection of proposals about new message format.
Main purpose aim to extend existing message format for new client app like editor.

Probably, we split these proposal into issues.

Feel free to comment it about these proposals.

Purpose

We want to extends message format for some reasons.

This proposal describe the reason.

• Suggestions
• Complete Error location
• MessageId and localize
• Document improvements

Suggestions

textlint first target is CI and Command line Tools.

We want to support editor like VSCode.
--fix is useful but it provide only a single suggestion.

Some rules want to provide multiple suggestions.
This proposal will near to current fix property.

Proposal:

• Add suggest property to RuleError
  • suggest should have an array of object that has id and fix and message property
• The suggest property will be into TextlintMessage
• textlint cli may does not provide fixing function the suggest at first
  • This fixing need to use id of suggestion.(ESLint does not have the id)
  • It will need new funciton in kernel to fix text with message
    • https://github.com/textlint/textlint/tree/master/packages/%40textlint/source-code-fixer has the function
    • It is already separated module

const reporter = (context) => {
    const { Syntax, RuleError, fixer, report, getSource } = context;
    return {
        [Syntax.Str](node) {
            const text = getSource(node);
            // "You fix this"
            //      ^^^
            const matchRegexp = /\bfix\b/;
            if (!matchRegexp.test(text)) {
                return;
            }
            // found "fixable" error
            const index = text.search(matchRegexp);
            const length = "fix".length;
            report(
                node,
                new RuleError("Replaced", {
                    index,
                    suggest: [
                        {
                            id: "pattern1",
                            message: "pattern 1",
                            fix: fixer.replaceTextRange([index, index + length], "fixed 1")
                        },
                        {
                            id: "pattern2",
                            message: "pattern 2",
                            fix: fixer.replaceTextRange([index, index + length], "fixed 2")
                        }
                    ]
                })
            );
        }
    };
};
export default {
    linter: reporter,
    fixer: reporter
};

Similar Works:

• ESLint
  • https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions

Improve error location

Currently, error message has only start position.
It prevents that underline actual error text.

Some editor plugin requires the full locations includes start and end.

Proposal

• Add locator function and location property
  • locator has .range([number, number) and .location({ start, end })
  • bike shading

const reporter = (context) => {
    const { Syntax, RuleError, fixer, locator, report, getSource } = context;
    return {
        [Syntax.Str](node) {
            const text = getSource(node);
            // "You fix this"
            //      ^^^
            const matchRegexp = /\bfix\b/;
            if (!matchRegexp.test(text)) {
                return;
            }
            // found "fixable" error
            const index = text.search(matchRegexp);
            const length = "fix".length;
            report(
                node,
                new RuleError("Replaced", {
                    location: locator.range([index, index + length]),
                    suggest: [
                        {
                            message: "pattern 1",
                            fix: fixer.replaceTextRange([index, index + length], "fixed 1")
                        },
                        {
                            message: "pattern 2",
                            fix: fixer.replaceTextRange([index, index + length], "fixed 2")
                        }
                    ]
                })
            );
        }
    };
};
export default {
    linter: reporter,
    fixer: reporter
};

MessageId and Localization

• Each rules can define messages
• createTranslator can use the messages
  • It is template system
  • Localization function
• the translator can be used for message on error and suggestion
  • Also, id can be omitted if the translator function is used.
  • (It may be must feature)
  • The id same with mssages key name.

export const messages = {
    MESSAGE: ({param}) => `Replace ${param}`,
    SUGGEST_MESSAGE_1: () => `pattern 1`,
    SUGGEST_MESSAGE_2: () => `pattern 2`,
}
const reporter = (context) => {
    const { Syntax, RuleError, fixer, report, getSource, createTranslator } = context;
    const t = createTranslator(messages);
    return {
        [Syntax.Str](node) {
            const text = getSource(node);
            // "You fix this"
            //      ^^^
            const matchRegexp = /\bfix\b/;
            if (!matchRegexp.test(text)) {
                return;
            }
            // found "fixable" error
            const index = text.search(matchRegexp);
            const length = "fix".length;
            report(
                node,
                new RuleError(t("MESSAGE", {param: "value"})), {
                    location: locator.range([index, index + length]),
                    suggest: [
                        {
                            /* Same
                            id: "SUGGEST_MESSAGE_1",
                            message: `pattern 1`,
                            */
                            message: t("SUGGEST_MESSAGE_1"),
                            fix: fixer.replaceTextRange([index, index + length], "fixed 1")
                        },
                        {
                            message: t("SUGGEST_MESSAGE_1"),
                            fix: fixer.replaceTextRange([index, index + length], "fixed 2")
                        }
                    ]
                })
            );
        }
    };
};
export default {
    linter: reporter,
    fixer: reporter
};

Localize message:

export const messages = {
    MESSAGE: {
      en: ({param}) => `Replace ${param}`,
      ja: ({param}) => `Replace ${param}`,
    }
}
const reporter = (context) => {
    const { Syntax, RuleError, fixer, report, getSource, locatorm, createTranslator } = context;
    const t = createTranslator(messages);
    return {
        [Syntax.Str](node) {
            const text = getSource(node);
            // "You fix this"
            //      ^^^
            const matchRegexp = /\bfix\b/;
            if (!matchRegexp.test(text)) {
                return;
            }
            // found "fixable" error
            const index = text.search(matchRegexp);
            const length = "fix".length;
            report(
                node,
                new RuleError(t("MESSAGE", {param: "value"})), {
                    location: locator.range([index, index + length]),
                    suggest: [
                        {
                            /* Same
                            id: "SUGGEST_MESSAGE_1",
                            message: `pattern 1`,
                            */
                            message: t("SUGGEST_MESSAGE_1"),
                            fix: fixer.replaceTextRange([index, index + length], "fixed 1")
                        },
                        {
                            message: t("SUGGEST_MESSAGE_1"),
                            fix: fixer.replaceTextRange([index, index + length], "fixed 2")
                        }
                    ]
                })
            );
        }
    };
};
export default {
    linter: reporter,
    fixer: reporter
};

Related Issues:

• textlint: allow to modify message for re-use rules · Issue #549 · textlint/textlint
• Localize messages support · Issue #252 · textlint/textlint

Improves Error documentation

We heard that "how to fix the error?" from textlint users.

Almost error messages does not provide the way.
Of course, some error message show it clearly.

The necessary conditions:

• The documentation should have url
• The rule should not embed the documentation text
  • It aim to improve maintancibility. e.g. avoid 404 link
• textlint user can look up if the document is needed
• The documentation should includes "how to fix" examples
  • It may be related to suggests

Proposals:

• Add docs.url and messageId to each error message
  • It is inspired by secretlint way
• Show link to {docs.url}#{MessageId}

export const messages = {
    MESSAGE: ({param}) => `Replace ${param}`,
    SUGGEST_MESSAGE_1: () => `pattern 1`,
    SUGGEST_MESSAGE_2: () => `pattern 2`,
}
const reporter = (context) => {
    const { Syntax, RuleError, fixer, report, locator, getSource, createTranslator } = context;
    const t = createTranslator(messages);
    return {
        [Syntax.Str](node) {
            const text = getSource(node);
            const matchRegexp = /\bfix\b/;
            if (!matchRegexp.test(text)) {
                return;
            }
            const index = text.search(matchRegexp);
            const length = "fix".length;
            report(
                node,
                new RuleError(t("MESSAGE", {param: "value"})), {
                    location: locator.range(index, index + length),
                    suggest: [
                        {
                            message: t("SUGGEST_MESSAGE_1"),
                            fix: fixer.replaceTextRange([index, index + length], "fixed 1")
                        },
                        {
                            message: t("SUGGEST_MESSAGE_2"),
                            fix: fixer.replaceTextRange([index, index + length], "fixed 2")
                        }
                    ]
                })
            );
        }
    };
};
export default {
    // base url
    meta: {
      docs: {
        url: "https://github.com/example/textlint-rule/README.md"
      }
    },
    linter: reporter,
    fixer: reporter
};

Similar works

• ESLint's meta.docs.url filed
  • https://eslint.org/docs/developer-guide/working-with-rules
• Secretint's docs and messages
  • https://github.com/secretlint/secretlint/blob/master/docs/secretlint-rule.md

Related Changes

• Need to update textlint-tester
• Create examples from test cases
  • https://github.com/textlint/create-textlint-rule-example should be more official tool.

Compatibility

Full backward compatible, maybe.

• location is new property
• suggest is new property
• locator is new function
• createTranslator is new function
• export meta property newly
• textlint-tester may have breaking changes, but it will cover almost compatible

[azu]

These are related.

• Suggestions
• MessageId and Localization
• Improves Error documentation

The follow can be separated proposal.

• Improve error location

[azu]

Improve error location

Create an issue #835