@vistta/cli 1.1.0 → 1.2.0

package/config.schema.json

@@ -0,0 +1,150 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "VISTTA project configuration",
+  "description": "VISTTA settings in tsconfig.json or jsconfig.json. Other TypeScript and framework properties are preserved.",
+  "type": "object",
+  "properties": {
+    "extends": {
+      "description": "Relative or package presets, applied from left to right before local settings.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "$ref": "#/definitions/stringList"
+        }
+      ]
+    },
+    "compilerOptions": {
+      "type": "object",
+      "description": "Compiler options used unchanged by TypeScript, with noEmit enabled for checks."
+    },
+    "include": {
+      "$ref": "#/definitions/stringList"
+    },
+    "exclude": {
+      "$ref": "#/definitions/stringList"
+    },
+    "files": {
+      "$ref": "#/definitions/stringList"
+    },
+    "cli": {
+      "$ref": "#/definitions/cli"
+    },
+    "cliOptions": {
+      "$ref": "#/definitions/cli",
+      "description": "Legacy alias. The cli block takes precedence."
+    },
+    "bundlerOptions": {
+      "type": "object"
+    }
+  },
+  "definitions": {
+    "stringList": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "cli": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "check": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "format": {
+              "type": "boolean",
+              "default": true
+            },
+            "lint": {
+              "type": "boolean",
+              "default": true
+            },
+            "types": {
+              "type": "boolean",
+              "default": true
+            }
+          }
+        },
+        "format": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "engine": {
+              "const": "prettier",
+              "default": "prettier"
+            },
+            "options": {
+              "type": "object",
+              "description": "Prettier options overriding any discovered or referenced configuration."
+            },
+            "config": {
+              "type": "string",
+              "description": "Optional module exporting Prettier options as its default export."
+            },
+            "include": {
+              "$ref": "#/definitions/stringList"
+            },
+            "exclude": {
+              "$ref": "#/definitions/stringList"
+            }
+          }
+        },
+        "lint": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "engine": {
+              "const": "eslint",
+              "default": "eslint"
+            },
+            "rules": {
+              "type": "object",
+              "description": "ESLint rules applied after the existing or referenced flat config."
+            },
+            "languageOptions": {
+              "type": "object"
+            },
+            "options": {
+              "type": "object",
+              "description": "Additional JSON-compatible ESLint flat-config properties, such as settings or files."
+            },
+            "config": {
+              "type": "string",
+              "description": "Optional module exporting an ESLint flat config or array. Replaces config-file discovery."
+            },
+            "include": {
+              "$ref": "#/definitions/stringList"
+            },
+            "exclude": {
+              "$ref": "#/definitions/stringList"
+            }
+          }
+        },
+        "tasks": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "dependsOn": {
+                "$ref": "#/definitions/stringList"
+              },
+              "script": {
+                "type": "string",
+                "description": "A script name from the current package.json. Dependencies run first."
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/index.js

@@ -6,5 +6,8 @@ export { TestRunner } from "./classes/test-runner.js";
 export { default as BundleCommand } from "./commands/bundle.js";
 export { default as DefaultCommand } from "./commands/default.js";
 export { default as ProjectCommand } from "./commands/project.js";
+export { default as QualityCommand } from "./commands/quality.js";
+export { default as TaskCommand } from "./commands/task.js";
 export { default as TestCommand } from "./commands/test.js";
+export { loadProjectConfig } from "./config.js";
 export { parseArgs } from "./utils.js";

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@vistta/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
     "./global": "./global.d.ts",
     "./config": "./tsconfig.json",
+    "./schema": "./config.schema.json",
     "./default": "./commands/default.js",
     "./bundle": "./commands/bundle.js",
     "./project": "./commands/project.js",
     "./test": "./commands/test.js",
+    "./quality": "./commands/quality.js",
+    "./task": "./commands/task.js",
     "./test-runner": "./classes/test-runner.js",
     "./loaders/bundler": "./loaders/bundler.js",
     "./loaders/file": "./loaders/file.js",
@@ -28,10 +31,11 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@vistta/console": "latest",
-    "@vistta/fs": "latest",
-    "@vistta/utils": "latest",
+    "@vistta/console": "^1.1.0",
+    "@vistta/fs": "^1.1.0",
+    "@vistta/utils": "^1.1.0",
     "esbuild": "^0.28.2",
+    "jsonc-parser": "^3.3.1",
     "semver": "^7.8.5"
   },
   "author": "Tiago Terenas Almeida",

package/register.js

@@ -33,6 +33,13 @@ const config = await importConfig({
       bundle: resolve(import.meta.dirname, "./commands/bundle.js"),
       project: resolve(import.meta.dirname, "./commands/project.js"),
       test: resolve(import.meta.dirname, "./commands/test.js"),
+      check: resolve(import.meta.dirname, "./commands/quality.js"),
+      lint: resolve(import.meta.dirname, "./commands/quality.js"),
+      fmt: resolve(import.meta.dirname, "./commands/quality.js"),
+      types: resolve(import.meta.dirname, "./commands/quality.js"),
+      config: resolve(import.meta.dirname, "./commands/quality.js"),
+      run: resolve(import.meta.dirname, "./commands/task.js"),
+      task: resolve(import.meta.dirname, "./commands/task.js"),
     },
   },
 });

package/tests/config.test.js

@@ -0,0 +1,217 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadProjectConfig } from "../config.js";
+import { planTasks, runChecks, runTasks, toolFiles } from "../tools.js";
+
+function fixture(files) {
+  const cwd = mkdtempSync(join(tmpdir(), "vistta-config-"));
+  for (const [path, content] of Object.entries(files)) {
+    mkdirSync(dirname(join(cwd, path)), { recursive: true });
+    writeFileSync(join(cwd, path), typeof content === "string" ? content : JSON.stringify(content));
+  }
+  return cwd;
+}
+
+suite("CLI configuration", async () => {
+  await test("loads JSONC, relative presets, legacy settings, arrays, and setting sources", () => {
+    const cwd = fixture({
+      "presets/base.json": {
+        compilerOptions: { checkJs: true },
+        include: ["src/**/*.js"],
+        cliOptions: { check: { format: false, lint: true }, commands: { custom: "./custom.js" } },
+        cli: { format: { options: { semi: false } } },
+      },
+      "presets/custom.js": "export default class {}",
+      "tsconfig.json":
+        '{ // comment\n "extends": "./presets/base", "include": ["app/*.js"], "cli": { "check": { "types": false }, "format": { "options": { "singleQuote": true } } }, }',
+    });
+    try {
+      const result = loadProjectConfig(cwd);
+      assert.deepEqual(result.config.cli.check, { format: false, lint: true, types: false });
+      assert.deepEqual(result.config.include, ["app/*.js"]);
+      assert.deepEqual(result.config.cli.format.options, { semi: false, singleQuote: true });
+      assert.equal(fileURLToPath(result.config.cli.commands.custom), join(cwd, "presets/custom.js"));
+      assert.equal(result.sources["cli.format.options.semi"], join(cwd, "presets/base.json"));
+      assert.equal(result.sources["cli.format.options.singleQuote"], join(cwd, "tsconfig.json"));
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  await test("supports package presets, jsconfig, and multiple ordered parents", () => {
+    const cwd = fixture({
+      "node_modules/preset/package.json": { name: "preset", exports: { "./config": "./config.json" } },
+      "node_modules/preset/config.json": { cli: { format: { options: { semi: true, singleQuote: false } } } },
+      "second.json": { cli: { format: { options: { semi: false } } } },
+      "jsconfig.json": { extends: ["preset/config", "./second.json"] },
+    });
+    try {
+      assert.deepEqual(loadProjectConfig(cwd).config.cli.format.options, { semi: false, singleQuote: false });
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  await test("rejects malformed, circular, and invalid configuration", () => {
+    const cwd = fixture({ "tsconfig.json": "{broken}" });
+    try {
+      assert.throws(() => loadProjectConfig(cwd), /Invalid configuration/);
+      writeFileSync(join(cwd, "tsconfig.json"), JSON.stringify({ extends: "./tsconfig.json" }));
+      assert.throws(() => loadProjectConfig(cwd), /Circular/);
+      for (const cli of [
+        { check: { types: "yes" } },
+        { lint: { engine: "unknown" } },
+        { format: { include: "*.js" } },
+        { tasks: { build: { dependsOn: "test" } } },
+      ]) {
+        writeFileSync(join(cwd, "tsconfig.json"), JSON.stringify({ cli }));
+        assert.throws(() => loadProjectConfig(cwd));
+      }
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  await test("resolves inherited file patterns relative to their config and excludes dependencies", () => {
+    const cwd = fixture({
+      "preset/base.json": { include: ["src/**/*.js"], exclude: ["src/ignored/**"] },
+      "tsconfig.json": { extends: "./preset/base.json" },
+      "preset/src/main.js": "export {};",
+      "preset/src/ignored/skip.js": "export {};",
+      "preset/src/node_modules/skip/index.js": "export {};",
+    });
+    try {
+      assert.deepEqual(toolFiles(loadProjectConfig(cwd), "lint", [], cwd), [join(cwd, "preset/src/main.js")]);
+      assert.deepEqual(toolFiles(loadProjectConfig(cwd), "lint", ["preset/src/ignored/*.js"], cwd), []);
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  await test("orders dependencies once, rejects cycles and missing tasks, and stops on failure", async () => {
+    const tasks = {
+      validate: { dependsOn: ["lint", "test"], script: "finish" },
+      test: { dependsOn: ["lint"], script: "unit" },
+    };
+    const plan = planTasks("validate", tasks, { unit: "node unit.js", finish: "node finish.js" });
+    assert.deepEqual(
+      plan.map((task) => task.name),
+      ["lint", "test", "validate"],
+    );
+    assert.throws(() => planTasks("bad", { bad: { dependsOn: ["bad"] } }), /Circular/);
+    assert.throws(() => planTasks("unknown"), /Unknown/);
+    assert.throws(() => planTasks("build"), /Unknown/);
+    assert.deepEqual(planTasks("build", {}, {}, ["build"]), [{ name: "build", command: "build" }]);
+    assert.throws(() => planTasks("bad", { bad: { script: "missing" } }), /Unknown package script/);
+    const calls = [];
+    assert.equal(
+      await runTasks(plan, process.cwd(), [], async (args) => {
+        calls.push(args);
+        return 2;
+      }),
+      2,
+    );
+    assert.equal(calls.length, 1);
+    calls.length = 0;
+    assert.equal(
+      await runTasks(plan, process.cwd(), ["--flag"], async (args) => {
+        calls.push(args);
+        return 0;
+      }),
+      0,
+    );
+    assert.deepEqual(calls.at(-1), ["--run", "finish", "--", "--flag"]);
+  });
+});
+
+suite("CLI tool adapters", async () => {
+  await test("formats and lints temporary files with project-local tools and checks types without emitting", async () => {
+    const root = resolve(import.meta.dirname, "../../..");
+    const cwd = fixture({
+      "package.json": { name: "fixture", type: "module" },
+      "tsconfig.json": {
+        include: ["src/*.js"],
+        compilerOptions: { allowJs: true, checkJs: true, noEmit: true, types: [], target: "ES2022" },
+        cli: {
+          lint: {
+            engine: "eslint",
+            config: "./eslint.config.mjs",
+            rules: { "no-unused-vars": "error", semi: ["error", "always"] },
+          },
+          format: { engine: "prettier", config: "./prettier.config.mjs", options: { semi: true, singleQuote: false } },
+        },
+      },
+      "src/main.js": "export const value=1",
+      "eslint.config.mjs": 'export default [{ rules: { semi: ["error", "never"] } }];',
+      "prettier.config.mjs": "export default { semi: false };",
+      "node_modules/eslint/package.json": { main: join(root, "node_modules/eslint/lib/api.js") },
+      "node_modules/prettier/package.json": { main: join(root, "node_modules/prettier/index.cjs") },
+      "node_modules/typescript/package.json": { main: join(root, "node_modules/typescript/lib/typescript.js") },
+    });
+    try {
+      const project = loadProjectConfig(cwd);
+      assert.equal(await runChecks(["format"], project, { cwd }), 1);
+      assert.equal(readFileSync(join(cwd, "src/main.js"), "utf8"), "export const value=1");
+      assert.equal(await runChecks(["format"], project, { cwd, fix: true }), 0);
+      assert.equal(readFileSync(join(cwd, "src/main.js"), "utf8"), "export const value = 1;\n");
+      assert.equal(await runChecks(["lint", "types"], project, { cwd }), 0);
+      writeFileSync(join(cwd, "src/main.js"), "const unused = 1;\nexport const value = 1;\nvalue();\n");
+      assert.equal(await runChecks(["lint", "types"], project, { cwd }), 1);
+      assert.equal(existsSync(join(cwd, "src/main.d.ts")), false);
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+});
+
+suite("CLI public commands", async () => {
+  await test("propagates check, fix, config, and task results through the executable", () => {
+    const root = resolve(import.meta.dirname, "../../..");
+    const bin = fileURLToPath(new URL("../bin.js", import.meta.url));
+    const cwd = fixture({
+      "package.json": {
+        name: "fixture",
+        scripts: { smoke: "node success.js", fail: "node failure.js", args: "node arguments.js" },
+      },
+      "tsconfig.json": {
+        files: ["main.js"],
+        cli: {
+          check: { lint: false, types: false },
+          format: { options: { semi: true } },
+          tasks: { validate: { dependsOn: ["check"], script: "smoke" } },
+        },
+      },
+      "main.js": "const value=1",
+      "success.js": "process.exit(0);",
+      "failure.js": "process.exit(7);",
+      "arguments.js": 'if (process.argv[2] !== "--help") process.exit(3); console.log("FORWARDED");',
+      "node_modules/prettier/package.json": { main: join(root, "node_modules/prettier/index.cjs") },
+    });
+    const invoke = (...args) => spawnSync(process.execPath, [bin, ...args], { cwd, encoding: "utf8" });
+    try {
+      assert.equal(invoke("check").status, 1);
+      const fixed = invoke("check", "--fix");
+      assert.equal(fixed.status, 0, fixed.stdout + fixed.stderr);
+      assert.equal(readFileSync(join(cwd, "main.js"), "utf8"), "const value = 1;\n");
+      const config = invoke("config", "--sources");
+      assert.equal(config.status, 0, config.stdout + config.stderr);
+      const effective = JSON.parse(config.stdout.slice(config.stdout.indexOf("{")));
+      assert.equal(effective.config.cli.check.lint, false);
+      assert.equal(effective.sources["cli.check.lint"], join(cwd, "tsconfig.json"));
+      const task = invoke("task", "validate");
+      assert.equal(task.status, 0, task.stdout + task.stderr);
+      assert.equal(invoke("run", "smoke").status, 0);
+      const forwarded = invoke("task", "args", "--", "--help");
+      assert.equal(forwarded.status, 0, forwarded.stdout + forwarded.stderr);
+      assert.match(forwarded.stdout, /FORWARDED/);
+      assert.notEqual(invoke("task", "fail").status, 0);
+      assert.notEqual(invoke("task", "missing").status, 0);
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+});

package/tests/index.test.js

@@ -1,4 +1,9 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { Command } from "../classes/command.js";
+import { getOutdatedPackages } from "../utils.js";
 
 suite("CLI", () => {
   let cmd;
@@ -36,3 +41,138 @@ suite("CLI", () => {
     expect(process.env["BAR"]).toEqual("baz");
   });
 });
+
+async function checkNpmReport(report, code, packages = {}, workspace = "") {
+  const dirname = mkdtempSync(join(tmpdir(), "vistta-outdated-"));
+  const npmPath = process.env.npm_execpath;
+  try {
+    writeFileSync(join(dirname, "package.json"), JSON.stringify({ name: "fixture", private: true }));
+    writeFileSync(join(dirname, "package-lock.json"), JSON.stringify({ packages }));
+    const script = join(dirname, "npm.cjs");
+    writeFileSync(
+      script,
+      [
+        "const assert = require('node:assert/strict');",
+        "assert.deepEqual(process.argv.slice(2), ['outdated', '--json', '--long', '--include=dev']);",
+        `process.stdout.write(${JSON.stringify(JSON.stringify(report))});`,
+        `process.exit(${code});`,
+      ].join("\n"),
+    );
+    process.env.npm_execpath = script;
+    const cwd = join(dirname, workspace);
+    if (workspace) {
+      mkdirSync(cwd, { recursive: true });
+      writeFileSync(join(cwd, "package.json"), JSON.stringify({ name: "workspace" }));
+    }
+    return { dirname, modules: await getOutdatedPackages(cwd) };
+  } finally {
+    if (npmPath === undefined) delete process.env.npm_execpath;
+    else process.env.npm_execpath = npmPath;
+    rmSync(dirname, { recursive: true, force: true });
+  }
+}
+
+suite("CLI outdated", async () => {
+  await test("uses npm wanted versions and preserves separate workspace consumers", async () => {
+    const { dirname, modules } = await checkNpmReport(
+      {
+        shared: [
+          { current: "1.0.0", wanted: "1.5.0", latest: "2.0.0", type: "dependencies", dependedByLocation: "packages/first" },
+          {
+            current: "1.0.0",
+            wanted: "1.0.0",
+            latest: "2.0.0",
+            type: "devDependencies",
+            dependedByLocation: "packages/second",
+          },
+        ],
+        linked: { current: "2.0.0", wanted: "1.0.0", latest: "1.0.0", type: "dependencies" },
+        peer: { current: "1.0.0", wanted: "2.0.0", latest: "2.0.0", type: "peerDependencies" },
+      },
+      1,
+      { "node_modules/linked": { link: true } },
+    );
+    assert.deepEqual(modules, [
+      {
+        name: "shared",
+        package: join(dirname, "packages/first/package.json"),
+        current: "1.0.0",
+        wanted: "1.5.0",
+        latest: "2.0.0",
+        dev: false,
+      },
+      {
+        name: "shared",
+        package: join(dirname, "packages/second/package.json"),
+        current: "1.0.0",
+        wanted: "1.0.0",
+        latest: "2.0.0",
+        dev: true,
+      },
+    ]);
+  });
+
+  await test("accepts an empty npm report", async () => {
+    const { modules } = await checkNpmReport({}, 0);
+    assert.deepEqual(modules, []);
+  });
+
+  await test("resolves workspace owners relative to the lockfile when invoked inside a package", async () => {
+    const { dirname, modules } = await checkNpmReport(
+      {
+        dependency: {
+          current: "1.0.0",
+          wanted: "1.1.0",
+          latest: "1.1.0",
+          type: "dependencies",
+          dependedByLocation: "packages/child",
+        },
+      },
+      1,
+      {},
+      "packages/child",
+    );
+    assert.equal(modules[0].package, join(dirname, "packages/child/package.json"));
+  });
+
+  await test("surfaces npm errors instead of reporting everything up to date", async () => {
+    await assert.rejects(checkNpmReport({ error: { summary: "Registry unavailable" } }, 1), /Registry unavailable/);
+  });
+
+  await test("limits package checks to their own dependency consumers", async () => {
+    const { dirname, modules } = await checkNpmReport(
+      {
+        root: { current: "1.0.0", wanted: "1.1.0", latest: "1.1.0", type: "dependencies" },
+        shared: [
+          {
+            current: "1.0.0",
+            wanted: "1.1.0",
+            latest: "1.1.0",
+            type: "devDependencies",
+            dependedByLocation: "packages/child",
+          },
+          {
+            current: "1.0.0",
+            wanted: "1.2.0",
+            latest: "1.2.0",
+            type: "dependencies",
+            dependedByLocation: "packages/sibling",
+          },
+        ],
+      },
+      1,
+      {},
+      "packages/child",
+    );
+    assert.deepEqual(modules, [
+      {
+        name: "shared",
+        package: join(dirname, "packages/child/package.json"),
+        current: "1.0.0",
+        wanted: "1.1.0",
+        latest: "1.1.0",
+        dev: true,
+      },
+    ]);
+  });
+});