redlint 6.5.2 → 6.7.0

package/CONTRIBUTING.md

@@ -0,0 +1,274 @@
+# Contributing to RedLint
+
+## Quick Reference
+
+- **No unused variables or imports** — clean them up before committing.
+- **No `t.pass('everything ok')` in tests** — every assertion must test something meaningful.
+- **100% coverage required** — checked via [`.nycrc.json`](.nycrc.json). Run `redrun coverage` to verify.
+- **Tests use [supertape](https://github.com/coderaiser/supertape)** with `stub()` for mocking.
+- **TDD is encouraged** — write a failing test first, then implement, then `redrun fix:lint coverage`.
+- **Run `redrun fix:lint coverage` before every commit** — linter must be clean, all tests green, coverage 100%.
+
+## Table of Contents
+
+- [Do / Don't](#do--dont)
+- [Workflow](#workflow)
+- [Architecture](#architecture)
+- [How to add a new converter](#how-to-add-a-new-converter)
+- [Import Map](#import-map)
+- [File Tree](#file-tree)
+- [Overrides Pattern](#overrides-pattern)
+- [Tools we use](#tools-we-use)
+
+## Do / Don't
+
+| Do                                               | Don't                                            |
+|--------------------------------------------------|------------------------------------------------|
+| Write one assertion per test                     | Use `t.pass('ok')` or `t.comment()`            |
+| Use descriptive test names                       | Use vague names like `'test1'`                 |
+| Inject deps via `overrides`                      | Import real modules inline (hard to stub)      |
+| Use early returns to flatten logic               | Nest deeply with `if/else` chains              |
+| Keep modules small, one concern per file         | Put multiple operations in one file            |
+| Use `async` for tests that `await`               | Forget `await` in async test functions         |
+| Run `redrun fix:lint coverage` before commit         | Commit red linter output                   |
+
+## Workflow
+
+Install [`redrun`](https://github.com/coderaiser/redrun) (faster than `npm run`):
+
+```sh
+bun i redrun -g
+```
+
+Every commit should pass:
+
+```sh
+redrun fix:lint     # runs putout . --fix
+redrun test         # runs all .spec.js tests
+redrun coverage     # run coverage (aim for 100%):
+```
+
+## Architecture
+
+### Worker / Direct Pattern
+
+Each filesystem operation (`scan`, `fix`, `pack`, `extract`, `convert`) has two paths:
+
+| Mode       | Function                                | Thread         |
+|------------|-----------------------------------------|----------------|
+| **Normal** | `master*()` + `slave.js`              | Web Worker       |
+| **Debug**  | Direct import (e.g. `lint()`, `convert()`) | Main thread |
+
+The debug mode is an escape hatch when workers misbehave.
+
+### Module layout
+
+- `lib/<operation>/master.js` — spawns a worker, returns a promise.
+- `lib/<operation>/slave.js` — runs inside the worker, calls the real logic.
+- `lib/<operation>/<operation>.js` — the actual implementation (imported by slave and tests).
+- `lib/<operation>/<operation>.spec.js` — tests.
+- `lib/<operation>/fixture/` — test fixtures.
+
+### Testing
+
+- Framework: [supertape](https://github.com/coderaiser/supertape)
+- Mocking: `stub()` from supertape (no external mocking library)
+- Fixtures: plain `.js` files in `fixture/` directories
+
+## How to add a new converter (e.g. `convert-json-to-yaml`)?
+
+All converters live in `lib/convert/converters/` and follow the same pattern. Adding a new one requires changes in **6 files** (1 new, 5 modified):
+
+### 1. Create the converter — `lib/convert/converters/convert-X-to-Y.js`
+
+```js
+import * as pluginFilesystem from '@putout/plugin-filesystem';
+
+const [, pluginConvertXToY] = pluginFilesystem.rules['convert-X-to-Y'];
+
+export const convertXToY = (filename) => ({
+    rules: {
+        'filesystem/convert-X-to-Y': ['on', {
+            filename,
+        }],
+    },
+    plugins: [
+        ['filesystem/convert-X-to-Y', pluginConvertXToY],
+    ],
+});
+```
+
+The `[@putout/plugin-filesystem](https://github.com/coderaiser/putout/tree/master/packages/plugin-filesystem)`
+package must already export the rule (use `[@putout/plugin-filesystem](https://github.com/coderaiser/putout/tree/master/packages/plugin-filesystem)` >= 13.2.0 for `convert-json-to-yaml`).
+
+### 2. Register menu constants — `lib/menu.js`
+
+Add a pair of exports (normal + debug):
+
+```js
+export const CONVERT_X_TO_Y = '🦏 convert x to y';
+export const CONVERT_X_TO_Y_DEBUG = '🦏 convert x to y: debug';
+```
+
+Then add `CONVERT_X_TO_Y` to the array in `isConvertChosen()` and `CONVERT_X_TO_Y_DEBUG` to the array in `isConvertChosenDebug()`.
+
+### 3. Add to converters map — `lib/convert/create-options.js`
+
+```js
+import {convertXToY} from './converters/convert-X-to-Y.js';
+
+const CONVERTERS = {
+    // ...existing...
+    [CONVERT_X_TO_Y]: convertXToY,
+    [CONVERT_X_TO_Y_DEBUG]: convertXToY,
+};
+```
+
+### 4. Add to convert menu — `lib/convert/index.js`
+
+Import `CONVERT_X_TO_Y` and add it to the `chooseConvert()` dialog array.
+
+### 5. Add to debug menu — `lib/debug.js`
+
+Import `CONVERT_X_TO_Y_DEBUG` and add it to the `debug()` dialog array.
+
+### 6. Add a test — `lib/convert/convert.spec.js`
+
+```js
+import {CONVERT_X_TO_Y} from '../menu.js';
+
+test('redlint: convert: x to y', (t) => {
+    const filesystem = stringify([
+        '/hello/world/',
+        '/hello/world/file.x',
+    ]);
+    
+    const converted = convert('file.x', CONVERT_X_TO_Y, filesystem, {
+        merge,
+        branch,
+    });
+    
+    const result = parse(converted);
+    
+    const expected = ['/hello/world/', [
+        '/hello/world/file.y',
+        'e30K',
+    ]];
+    
+    t.deepEqual(result, expected);
+    t.end();
+});
+```
+
+### 🧪 Verify
+
+```sh
+redrun fix:lint     # putout . --fix — must pass
+redrun coverage     # 100% required
+```
+
+## Import Map
+
+The project uses Node.js [`imports`](package.json) for internal aliases:
+
+```json
+{
+    "imports": {
+        "#edit": "./lib/edit/edit.js",
+        "#test": "./test/create-test.js"
+    }
+}
+```
+
+Used in `bin/redlint.js`:
+
+```js
+import {edit, editHelp} from '#edit';
+```
+
+## File Tree
+
+```
+redlint/
+├── bin/redlint.js          # CLI entry point
+├── lib/
+│   ├── convert/            # convert json↔js, rc→flat
+│   ├── edit/               # interactive filesystem editing
+│   ├── extract/            # unpack filesystem.red
+│   ├── help/               # --help output
+│   ├── lint/               # scan & fix filesystem
+│   ├── pack/               # pack to filesystem.red
+│   ├── rename/             # rename js↔jsx
+│   ├── test/               # test runner & plugins
+│   ├── view/               # view file contents
+│   ├── cli/                # version
+│   ├── choose.js           # interactive menu
+│   ├── debug.js            # debug menu
+│   ├── dialog.js           # ask for filename
+│   ├── menu.js             # menu constants & predicates
+│   ├── redlint.js          # buildTree
+│   ├── run.js              # worker runner
+│   ├── simple.js           # simple filesystem format
+│   ├── slave.js            # worker helper
+│   └── spinner.js          # CLI spinner
+├── test/                   # integration tests
+├── .nycrc.json             # coverage config (100% required)
+├── .madrun.js              # task runner scripts
+├── .putout.json            # putout rules
+└── package.json
+```
+
+## Overrides Pattern
+
+When a module calls external dependencies, accept them as optional overrides so tests can inject stubs:
+
+```js
+// run-convert.js
+export const runConvert = async (arg, filesystem, overrides = {}) => {
+    const {
+        askFilename: getFilename = askFilename,
+        convert = masterConvert,
+        isRCToFlat = isConvertRCToFlat,
+    } = overrides;
+    
+    let filename = '.eslintrc.json';
+    
+    if (!isRCToFlat(arg))
+        filename = await getFilename();
+    
+    if (filename)
+        return await convert(filename, arg, filesystem);
+};
+```
+
+Test injects stubs to verify behavior without side effects:
+
+```js
+// run-convert.spec.js
+test('redlint: run-convert: json to js: called with filename', async (t) => {
+    const convert = stub();
+    const askFilename = stub().returns('package.json');
+    const filesystem = '[]';
+    
+    await runConvert(CONVERT_JSON_TO_JS, filesystem, {
+        askFilename,
+        convert,
+    });
+    
+    t.calledWith(convert, ['package.json', CONVERT_JSON_TO_JS, filesystem]);
+    t.end();
+});
+```
+
+This pattern keeps functions pure, easy to unit test, and doesn't require any mocking framework.
+
+## Tools we use
+
+| Tool                                                  | Purpose                                              | Link                 |
+|-------------------------------------------------------|------------------------------------------------------|----------------------|
+| [redrun](https://github.com/coderaiser/redrun)        | Fast task runner (replaces `npm run`)                | `bun i redrun -g`    |
+| [madrun](https://github.com/coderaiser/madrun)        | Define tasks in `.madrun.js`                         | `redrun`             |
+| [putout](https://github.com/coderaiser/putout)        | JavaScript code transformer & linter                 | `redrun fix:lint`    |
+| [supertape](https://github.com/coderaiser/supertape)  | Test framework with built-in `stub()`                | `redrun test`        |
+| [superc8](https://github.com/coderaiser/superc8)      | coverage tool, drop-in modern  `c8` replacement                                  | `redrun coverage`    |
+| [nodemon](https://github.com/remy/nodemon)            | Watch mode for tests                                 | `redrun watch:test`  |

package/ChangeLog

@@ -1,3 +1,15 @@
+2026.06.07, v6.7.0
+
+feature:
+- 32a0dfc redlint: isKnownCommand: add
+- 68d1431 redlint: convert-json-to-yaml
+
+2026.06.06, v6.6.0
+
+feature:
+- 842206b convert: move out
+- eb2885e convert yaml to json: add
+
 2026.06.05, v6.5.2
 
 feature:
@@ -495,7 +507,7 @@ feature:
 2024.02.02, v3.11.1
 
 fix:
-- 779bf51 isConvertToJson
+- 779bf51 isConvertJSToJson
 
 feature:
 - 6edb2f7 redlint: @putout/plugin-filesystem v4.0.0

package/README.md

@@ -45,6 +45,7 @@ To scan your files use `redlint scan`:
 - ✅ [`package-json/find-file`](https://github.com/coderaiser/putout/tree/master/packages/plugin-package-json#find-file);
 - ✅ [`package-json/remove-exports-with-missing-files`](https://github.com/coderaiser/putout/tree/master/packages/plugin-package-json#remove-exports-with-missing-files);
 - ✅ [`esm/resolve-imported-file`](https://github.com/coderaiser/putout/tree/master/packages/plugin-esm#resolve-imported-file);
+- ✅ [`esm/resolve-imported-file-with-extension`](https://github.com/coderaiser/putout/tree/master/packages/plugin-esm#resolve-imported-file-with-extension);
 - ✅ [`esm/shorten-imported-file`](https://github.com/coderaiser/putout/tree/master/packages/plugin-esm#shorten-imported-file);
 - ✅ [`esm/apply-name-to-imported-file`](https://github.com/coderaiser/putout/tree/master/packages/plugin-esm#apply-name-to-imported-file);
 - ✅ [`esm/apply-namespace-to-imported-file`](https://github.com/coderaiser/putout/tree/master/packages/plugin-esm#apply-name-to-imported-file);

package/bin/redlint.js

@@ -57,6 +57,7 @@ import {
     isBundleDebug,
     isEdit,
     isView,
+    isKnownCommand,
     VIEW,
     TEST,
     isTest,
@@ -120,6 +121,11 @@ async function uiLoop(arg) {
     if (!arg)
         return;
     
+    if (!isKnownCommand(arg)) {
+        console.error(`'${arg}' is not a redlint command. See 'redlint --help'.`);
+        process.exit(1);
+    }
+    
     log('Running:');
     const spinner = ora('index filesystem').start();
     const CWD = process.cwd();

package/lib/convert/converters/convert-js-to-json.js

@@ -0,0 +1,14 @@
+import * as pluginFilesystem from '@putout/plugin-filesystem';
+
+const [, pluginConvertJsToJson] = pluginFilesystem.rules['convert-js-to-json'];
+
+export const convertJSToJson = (filename) => ({
+    rules: {
+        'filesystem/convert-js-to-json': ['on', {
+            filename,
+        }],
+    },
+    plugins: [
+        ['filesystem/convert-js-to-json', pluginConvertJsToJson],
+    ],
+});

package/lib/convert/converters/convert-json-to-js.js

@@ -0,0 +1,14 @@
+import * as pluginFilesystem from '@putout/plugin-filesystem';
+
+const [, pluginConvertJsonToJs] = pluginFilesystem.rules['convert-json-to-js'];
+
+export const convertJsonToJs = (filename) => ({
+    rules: {
+        'filesystem/convert-json-to-js': ['on', {
+            filename,
+        }],
+    },
+    plugins: [
+        ['filesystem/convert-json-to-js', pluginConvertJsonToJs],
+    ],
+});

package/lib/convert/converters/convert-json-to-yaml.js

@@ -0,0 +1,14 @@
+import * as pluginFilesystem from '@putout/plugin-filesystem';
+
+const [, pluginConvertJsonToYaml] = pluginFilesystem.rules['convert-json-to-yaml'];
+
+export const convertJsonToYaml = (filename) => ({
+    rules: {
+        'filesystem/convert-json-to-yaml': ['on', {
+            filename,
+        }],
+    },
+    plugins: [
+        ['filesystem/convert-json-to-yaml', pluginConvertJsonToYaml],
+    ],
+});

package/lib/convert/converters/convert-rc-to-flat.js

@@ -0,0 +1,12 @@
+import * as pluginESLint from '@putout/plugin-eslint';
+
+const [, pluginConvertRCToFlat] = pluginESLint.rules['convert-rc-to-flat'];
+
+export const convertRCToFlat = () => ({
+    rules: {
+        'eslint/convert-rc-to-flat': 'on',
+    },
+    plugins: [
+        ['eslint/convert-rc-to-flat', pluginConvertRCToFlat],
+    ],
+});

package/lib/convert/converters/convert-yaml-to-json.js

@@ -0,0 +1,14 @@
+import * as pluginFilesystem from '@putout/plugin-filesystem';
+
+const [, pluginConvertYamlToJson] = pluginFilesystem.rules['convert-yaml-to-json'];
+
+export const convertYamlToJson = (filename) => ({
+    rules: {
+        'filesystem/convert-yaml-to-json': ['on', {
+            filename,
+        }],
+    },
+    plugins: [
+        ['filesystem/convert-yaml-to-json', pluginConvertYamlToJson],
+    ],
+});

package/lib/convert/create-options.js

@@ -1,49 +1,37 @@
-import * as pluginFilesystem from '@putout/plugin-filesystem';
-import * as pluginESLint from '@putout/plugin-eslint';
 import {
-    isConvertToJs,
-    isConvertToJson,
-    isConvertRCToFlat,
+    CONVERT_JS_TO_JSON,
+    CONVERT_JSON_TO_JS,
+    CONVERT_JSON_TO_JS_DEBUG,
+    CONVERT_JS_TO_JSON_DEBUG,
+    CONVERT_YAML_TO_JSON,
+    CONVERT_YAML_TO_JSON_DEBUG,
+    CONVERT_JSON_TO_YAML,
+    CONVERT_JSON_TO_YAML_DEBUG,
+    CONVERT_RC_TO_FLAT,
 } from '../menu.js';
+import {convertYamlToJson} from './converters/convert-yaml-to-json.js';
+import {convertJsonToYaml} from './converters/convert-json-to-yaml.js';
+import {convertJsonToJs} from './converters/convert-json-to-js.js';
+import {convertJSToJson} from './converters/convert-js-to-json.js';
+import {convertRCToFlat} from './converters/convert-rc-to-flat.js';
 
-const [, pluginConvertJsonToJs] = pluginFilesystem.rules['convert-json-to-js'];
-const [, pluginConvertJsToJson] = pluginFilesystem.rules['convert-js-to-json'];
-const [, convertRCToFlat] = pluginESLint.rules['convert-rc-to-flat'];
+const CONVERTERS = {
+    [CONVERT_JSON_TO_JS]: convertJsonToJs,
+    [CONVERT_JSON_TO_JS_DEBUG]: convertJsonToJs,
+    [CONVERT_JS_TO_JSON]: convertJSToJson,
+    [CONVERT_JS_TO_JSON_DEBUG]: convertJSToJson,
+    [CONVERT_YAML_TO_JSON]: convertYamlToJson,
+    [CONVERT_YAML_TO_JSON_DEBUG]: convertYamlToJson,
+    [CONVERT_JSON_TO_YAML]: convertJsonToYaml,
+    [CONVERT_JSON_TO_YAML_DEBUG]: convertJsonToYaml,
+    [CONVERT_RC_TO_FLAT]: convertRCToFlat,
+};
 
 export const createOptions = (filename, type) => {
-    if (isConvertToJs(type))
-        return {
-            rules: {
-                'filesystem/convert-json-to-js': ['on', {
-                    filename,
-                }],
-            },
-            plugins: [
-                ['filesystem/convert-json-to-js', pluginConvertJsonToJs],
-            ],
-        };
-    
-    if (isConvertToJson(type))
-        return {
-            rules: {
-                'filesystem/convert-js-to-json': ['on', {
-                    filename,
-                }],
-            },
-            plugins: [
-                ['filesystem/convert-js-to-json', pluginConvertJsToJson],
-            ],
-        };
+    const converter = CONVERTERS[type];
     
-    if (isConvertRCToFlat(type))
-        return {
-            rules: {
-                'eslint/convert-rc-to-flat': 'on',
-            },
-            plugins: [
-                ['eslint/convert-rc-to-flat', convertRCToFlat],
-            ],
-        };
+    if (!converter)
+        return {};
     
-    return {};
+    return converter(filename);
 };

package/lib/convert/index.js

@@ -5,6 +5,8 @@ import {
     BACK,
     EXIT,
     CONVERT_RC_TO_FLAT,
+    CONVERT_YAML_TO_JSON,
+    CONVERT_JSON_TO_YAML,
 } from '../menu.js';
 
 export * from './convert.js';
@@ -12,6 +14,8 @@ export const chooseConvert = async () => {
     const command = await chooseDialog('Convert:', [
         CONVERT_JS_TO_JSON,
         CONVERT_JSON_TO_JS,
+        CONVERT_YAML_TO_JSON,
+        CONVERT_JSON_TO_YAML,
         CONVERT_RC_TO_FLAT,
         BACK,
         EXIT,

package/lib/debug.js

@@ -6,6 +6,8 @@ import {
     FIX_DEBUG,
     CONVERT_JS_TO_JSON_DEBUG,
     CONVERT_JSON_TO_JS_DEBUG,
+    CONVERT_YAML_TO_JSON_DEBUG,
+    CONVERT_JSON_TO_YAML_DEBUG,
     RENAME_JS_TO_JSX_DEBUG,
     BACK,
     EXIT,
@@ -21,6 +23,8 @@ export const debug = async () => {
         PACK_DEBUG,
         CONVERT_JS_TO_JSON_DEBUG,
         CONVERT_JSON_TO_JS_DEBUG,
+        CONVERT_YAML_TO_JSON_DEBUG,
+        CONVERT_JSON_TO_YAML_DEBUG,
         RENAME_JS_TO_JSX_DEBUG,
         RENAME_JS_TO_JSX_DEBUG,
         BUNDLE_DEBUG,

package/lib/menu.js

@@ -26,6 +26,12 @@ export const CONVERT_JS_TO_JSON_DEBUG = '🦏 convert js to json: debug';
 export const CONVERT_JSON_TO_JS = '🦏 convert json to js';
 export const CONVERT_JSON_TO_JS_DEBUG = '🦏 convert json to js: debug';
 
+export const CONVERT_YAML_TO_JSON = '🦏 convert yaml to json';
+export const CONVERT_YAML_TO_JSON_DEBUG = '🦏 convert yaml to json: debug';
+
+export const CONVERT_JSON_TO_YAML = '🦏 convert json to yaml';
+export const CONVERT_JSON_TO_YAML_DEBUG = '🦏 convert json to yaml: debug';
+
 export const RENAME_JS_TO_JSX = '🦏 rename js to jsx';
 export const RENAME_JS_TO_JSX_DEBUG = '🦏 rename js to jsx: debug';
 
@@ -56,16 +62,51 @@ export const isConvertChosen = (a) => {
     return [
         CONVERT_JSON_TO_JS,
         CONVERT_JS_TO_JSON,
+        CONVERT_YAML_TO_JSON,
+        CONVERT_JSON_TO_YAML,
         CONVERT_RC_TO_FLAT,
     ].includes(a);
 };
 export const isRenameToJsxChosen = (a) => a === RENAME_JS_TO_JSX;
 export const isRenameToJsChosen = (a) => a === RENAME_JSX_TO_JS;
-export const isConvertChosenDebug = (a) => a === CONVERT_JS_TO_JSON_DEBUG || a === CONVERT_JSON_TO_JS_DEBUG;
+export const isConvertChosenDebug = (a) => [
+    CONVERT_JS_TO_JSON_DEBUG,
+    CONVERT_JSON_TO_JS_DEBUG,
+    CONVERT_YAML_TO_JSON_DEBUG,
+    CONVERT_JSON_TO_YAML_DEBUG,
+].includes(a);
 
-export const isConvertToJson = (a) => a === CONVERT_JS_TO_JSON || a === CONVERT_JS_TO_JSON_DEBUG;
-export const isConvertToJs = (a) => a === CONVERT_JSON_TO_JS || a === CONVERT_JSON_TO_JS_DEBUG;
 export const isConvertRCToFlat = (a) => a === CONVERT_RC_TO_FLAT;
 
 export const isRenameToJs = (a) => a === RENAME_JS_TO_JSX || a === RENAME_JS_TO_JSX_DEBUG;
 export const isRenameToJsx = (a) => a === RENAME_JSX_TO_JS || a === RENAME_JSX_TO_JS_DEBUG;
+
+const callWith = (a) => (fn) => fn(a);
+
+export const isKnownCommand = (a) => [
+    isScan,
+    isScanDebug,
+    isFix,
+    isFixDebug,
+    isPack,
+    isPackDebug,
+    isExtract,
+    isExtractDebug,
+    isGenerate,
+    isGenerateSimple,
+    isHelp,
+    isVersion,
+    isDebug,
+    isConvert,
+    isRename,
+    isBack,
+    isExit,
+    isEdit,
+    isView,
+    isTest,
+    isBundleDebug,
+    isConvertChosen,
+    isConvertChosenDebug,
+    isRenameToJsChosen,
+    isRenameToJsxChosen,
+].some(callWith(a));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redlint",
-  "version": "6.5.2",
+  "version": "6.7.0",
   "type": "module",
   "author": "coderaiser <mnemonic.enemy@gmail.com> (https://github.com/coderaiser)",
   "description": "Lint Filesystem with 🐊Putout",
@@ -27,6 +27,8 @@
     "test:dts": "madrun test:dts",
     "watch:test": "madrun watch:test",
     "lint": "madrun lint",
+    "scan": "madrun scan",
+    "scan:fix": "madrun scan:fix",
     "fresh:lint": "madrun fresh:lint",
     "lint:fresh": "madrun lint:fresh",
     "fix:lint": "madrun fix:lint",