feat(textlint): add deprecation warning to old APIs (#1312)

* fix(textlint): add deprecation warning to old APIs

`TextLintCore`, `TextFixEngine`, `TextLintEngine`, and `textlint` API is deprecated

* refactor(examples): Use new APIs

* refactor(examples): Use new APIs

* refactor(examples): Use new APIs

* chore: update lock

* update message

* test: add deprecated label to tests

* test: add deprecated label to tests

* test: use TextilntCoreCompat instead of TextlintCore

* refactor: remove unneeded test

* test: move to kernel

* remove unused

* comment

* import

* feat: add @textlint/legacy-textlint-core

* Update packages/@textlint/legacy-textlint-core/tsconfig.json+2

* remove unused test

* fix: test

* docs: update readme

* Update package-lock.json

* test: should not use DEPRECATED module

* test: fix tests

docs/use-as-modules.md

@@ -123,9 +123,9 @@ Both engine
 - Return an array of `TextLintResult` or `TextLintFixResult`
   - actually, return a Promise like `Promise<TextLintResult[]>`
 
-### [Deprecated] Core
+### [Deprecated] `TextlintCore`
 
-textlint's core
+You can use `@textlint/legacy-textlint-core` package instead of `TextlintCore`.
 
 - Accept configuration as object.
 - Handle a **single** file or text string.

examples/use-as-module/.textlintrc.json

@@ -0,0 +1,5 @@
+{
+  "rules": {
+    "no-todo": true
+  }
+}

examples/use-as-module/README.md

@@ -6,4 +6,4 @@
 
 ## How to report Error
 
-Modify this README file and add `TODO` string.
+Modify this README file and add `TODO` string.

examples/use-as-module/index.mjs

@@ -0,0 +1,28 @@
+// LICENSE : MIT
+import { createLinter, loadTextlintrc, loadLinterFormatter } from "textlint";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function lintFile(filePath) {
+    // descriptor is a structure object for linter
+    // It includes rules, plugins, and options
+    const descriptor = await loadTextlintrc({
+        configFilePath: path.join(__dirname, ".textlintrc.json")
+    });
+    const linter = createLinter({
+        descriptor
+    });
+    const results = await linter.lintFiles([filePath]);
+    // textlint has two types formatter sets for linter and fixer
+    const formatter = await loadLinterFormatter({ formatterName: "stylish" });
+    const output = formatter.format(results);
+    console.log(output);
+}
+
+lintFile(__dirname + "/README.md").catch(function(error) {
+    console.error(error);
+    process.exit(1);
+});

examples/use-as-module/package.json

@@ -4,9 +4,9 @@
     "private": true,
     "license": "MIT",
     "author": "azu",
-    "main": "index.js",
+    "main": "index.mjs",
     "scripts": {
-        "test": "node index.js",
+        "test": "node index.mjs",
         "test:ci": "npm test"
     },
     "dependencies": {

examples/use-as-ts-module/.textlintrc.json

@@ -0,0 +1,5 @@
+{
+  "rules": {
+    "no-todo": true
+  }
+}

examples/use-as-ts-module/README.md

@@ -30,13 +30,5 @@ no-todo: Found TODO: 'TODO: This line should fail as well'
     7. - This line should fail!
          ^
 
-no-exclamation-question-mark: Disallow to use "!".
-/.../textlint/examples/use-as-ts-module/fixtures/failure.md:7:24
-                              v
-    6. - TODO: This line should fail as well
-    7. - This line should fail!
-    8. - `TODO`: This line should not
-                              ^
-
-✖ 3 problems (3 errors, 0 warnings)
+✖ 2 problems (2 errors, 0 warnings)
 ```

examples/use-as-ts-module/package.json

@@ -1,34 +1,31 @@
 {
-    "name": "textlint-example-use-as-ts-module",
-    "version": "13.4.1",
-    "private": true,
-    "license": "MIT",
-    "author": "0x6b",
-    "main": "lib/src/index.js",
-    "scripts": {
-        "prebuild": "npm-run-all clean",
-        "build": "tsc -b",
-        "clean": "rimraf lib/ module/",
-        "pretest": "npm-run-all build",
-        "test": "node lib/src/index.js fixtures/success.md",
-        "test:ci": "npm test"
-    },
-    "dependencies": {
-        "textlint": "^13.4.1",
-        "textlint-rule-no-exclamation-question-mark": "^1.0.2",
-        "textlint-rule-no-todo": "^2.0.1"
-    },
-    "devDependencies": {
-        "@types/node": "^18.7.16",
-        "npm-run-all": "^4.1.5",
-        "rimraf": "^3.0.2",
-        "typescript": "~4.9.4"
-    },
-    "files": [
-        "bin/",
-        "lib/",
-        "module/",
-        "src/",
-        "!*.tsbuildinfo"
-    ]
+  "name": "textlint-example-use-as-ts-module",
+  "version": "13.4.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "author": "0x6b",
+  "main": "lib/src/index.js",
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "tsc --build --clean",
+    "test": "npm run build && node lib/src/index.js fixtures/success.md",
+    "fail:test": "npm run build && node lib/src/index.js fixtures/failure.md",
+    "test:ci": "npm test"
+  },
+  "dependencies": {
+    "textlint": "^13.4.1",
+    "textlint-rule-no-todo": "^2.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^18.7.16",
+    "typescript": "~4.9.4"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "module/",
+    "src/",
+    "!*.tsbuildinfo"
+  ]
 }

examples/use-as-ts-module/src/index.ts

@@ -1,31 +1,28 @@
 // LICENSE : MIT
-"use strict";
-import { argv, cwd, exit } from "process";
-import { resolve } from "path";
-import { TextLintEngine } from "textlint";
-import { TextlintResult } from "@textlint/kernel";
+import { createLinter, loadTextlintrc, loadLinterFormatter } from "textlint";
+import path from "node:path";
+import { parseArgs } from "node:util";
 
-const [, , filename] = argv;
-
-function lintFile(filePath: string) {
-    const filePathList = [resolve(cwd(), filePath)];
-
-    const engine = new TextLintEngine({
-        rules: ["no-todo", "no-exclamation-question-mark"],
-        formatterName: "pretty-error",
-        color: false
+async function lintFile(filePaths: string[]) {
+    // descriptor is a structure object for linter
+    // It includes rules, plugins, and options
+    const descriptor = await loadTextlintrc({
+        configFilePath: path.join(process.cwd(), ".textlintrc.json")
     });
-
-    return engine.executeOnFiles(filePathList).then(function (results: TextlintResult[]) {
-        if (engine.isErrorResults(results)) {
-            console.log(engine.formatResults(results));
-        } else {
-            console.log("All Passed!");
-        }
+    const linter = createLinter({
+        descriptor
     });
+    const results = await linter.lintFiles(filePaths);
+    // textlint has two types formatter sets for linter and fixer
+    const formatter = await loadLinterFormatter({ formatterName: "stylish" });
+    const output = formatter.format(results);
+    console.log(output);
 }
 
-lintFile(filename).catch(function (error: TextlintResult) {
+const { positionals } = parseArgs({
+    allowPositionals: true
+});
+lintFile(positionals).catch(function (error) {
     console.error(error);
-    exit(1);
+    process.exit(1);
 });

examples/use-as-ts-module/tsconfig.json

@@ -1,7 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    "outDir": "lib"
+    "outDir": "lib",
+    "module": "ESNext"
   },
   "references": [
     {