@vistta/cli 1.0.1 → 1.2.0

package/classes/test-runner.js

@@ -0,0 +1,210 @@
+/**
+ * @typedef {{ only?: boolean; filter?: string }} TestRunnerOptions
+ */
+
+/**
+ * @typedef {{
+ *  name: string;
+ *  start?: number;
+ *  end?: number;
+ *  status?: "pass" | "fail";
+ *  result?: any;
+ *  error?: any;
+ * }} TestResult
+ */
+
+/**
+ * @typedef {{ only: boolean; skip: boolean; name: string; callback: () => any }} SuiteDefinition
+ */
+
+/**
+ * @typedef {{ only?: boolean; skip?: boolean; name?: string; tests: TestResult[]; time?: number }} SuiteResult
+ */
+
+/**
+ * @typedef {{
+ *  toEqual: (value: any, unit?: string) => void;
+ *  toBeLessThan: (value: any, unit?: string) => void;
+ *  toBeGreaterThan: (value: any, unit?: string) => void;
+ *  toInclude: (value: any) => void;
+ *  toMatch: (regex: string | RegExp) => void;
+ *  toThrow: (message?: string) => void;
+ * }} ExpectMatcherSet
+ */
+
+/**
+ * @typedef {ExpectMatcherSet & { not: ExpectMatcherSet }} ExpectMatchers
+ */
+
+export class TestRunner {
+  /** @type {TestRunnerOptions} */
+  #options = {};
+  /** @type {SuiteDefinition[]} */
+  #suites = [];
+  /** @type {SuiteResult[]} */
+  #results;
+  /** @type {SuiteResult | null} */
+  #active;
+  /** @type {number} */
+  #running;
+
+  /**
+   * @param {TestRunnerOptions} [options]
+   */
+  constructor(options = {}) {
+    this.#options = options;
+    this.suite = this.#suite.bind(this);
+    this.suite.only = (name, callback) => this.#suite(name, callback, { only: true });
+    this.suite.skip = (name, callback) => this.#suite(name, callback, { skip: true });
+    this.test = this.#test.bind(this);
+    this.test.only = (name, callback) => this.#test(name, callback, { only: true });
+    this.test.skip = (name, callback) => this.#test(name, callback, { skip: true });
+  }
+
+  /**
+   * @returns {Promise<SuiteResult[]>}
+   */
+  async run() {
+    this.#running = 0;
+    this.#results = [];
+    for (const suite of this.#suites) {
+      this.#active = { only: suite.only, name: suite.name, skip: suite.skip, tests: [] };
+      try {
+        await suite.callback();
+      } catch {
+        /* Do Nothing */
+      }
+      this.#results.push(this.#active);
+      this.#active = null;
+    }
+    while (this.#running > 0) await new Promise((resolve) => setTimeout(resolve, 100));
+    return this.#results;
+  }
+
+  /**
+   * @param {string} name
+   * @param {() => any} callback
+   * @param {{ only?: boolean, skip?: boolean }} options
+   * @returns {Promise<void>}
+   */
+  async #suite(name, callback, { only, skip } = {}) {
+    if (this.#active) throw new Error("Suites cannot be stacked");
+    this.#suites.push({ only, skip, name, callback });
+  }
+
+  /**
+   * @param {string} name
+   * @param {() => any | Promise<any>} callback
+   * @param {{ only?: boolean, skip?: boolean }} options
+   * @returns {Promise<void>}
+   */
+  async #test(name, callback, { only, skip } = {}) {
+    if (
+      (this.#options.filter && !name.match(new RegExp(this.#options.filter, "i"))) ||
+      (this.#options.only && !(only || this.#active?.only))
+    )
+      return;
+    const test = { name };
+    if (skip || this.#active?.skip) {
+      test.status = "skip";
+      this.#active?.tests.push(test);
+      return;
+    } else this.#running++;
+    test.start = performance();
+    if (this.#active) this.#active.tests.push(test);
+    else this.#results.push({ tests: [test], time: test.time });
+    try {
+      test.result = await callback();
+      test.status = "pass";
+      test.end = performance();
+    } catch (error) {
+      test.status = "fail";
+      test.error = error;
+      test.end = performance();
+    }
+    this.#running--;
+  }
+
+  /**
+   * @param {any} target
+   * @param {string} [label]
+   * @returns {ExpectMatchers}
+   */
+  expect(target, label) {
+    return {
+      not: {
+        toEqual: (value, unit = "") => {
+          if (target !== value) return;
+          throw new Error(`expected ${label ? label + "(" + target + ")" : target} to not equal ${value}${unit}`);
+        },
+        toBeLessThan: (value, unit = "") => {
+          if (target >= value) return;
+          throw new Error(`expected ${label ? label + "(" + target + ")" : target} to not be less than ${value}${unit}`);
+        },
+        toBeGreaterThan: (value, unit = "") => {
+          if (target <= value) return;
+          throw new Error(`expected ${label ? label + "(" + target + ")" : target} to not be greater than ${value}${unit}`);
+        },
+        toInclude: (value) => {
+          if (target.indexOf(value) === -1) return;
+          throw new Error(`expected ${label ? label + "(" + target + ")" : target} to not include ${value}`);
+        },
+        toMatch: (regex) => {
+          if (!target.match(new RegExp(regex))) return;
+          throw new Error(`expected ${label ? label + "(" + target + ")" : target} to not match ${regex}`);
+        },
+        toThrow: (message) => {
+          try {
+            target();
+          } catch (error) {
+            if (!message)
+              throw new Error(`expected ${label ? label + "()" : "function()"} to not throw, but got ${error.message}`);
+            if (error.message === message)
+              throw new Error(
+                `expected ${label ? label + "()" : "function()"} to not throw ${message}, but got ${error.message}`,
+              );
+            if (error.message.match(new RegExp(message)))
+              throw new Error(
+                `expected ${label ? label + "()" : "function()"} to not throw ${message}, but got ${error.message}`,
+              );
+            return;
+          }
+        },
+      },
+      toEqual: (value, unit = "") => {
+        if (target === value) return;
+        throw new Error(`expected ${label ? label + "(" + target + ")" : target} to equal ${value}${unit}`);
+      },
+      toBeLessThan: (value, unit = "") => {
+        if (target < value) return;
+        throw new Error(`expected ${label ? label + "(" + target + ")" : target} to be less than ${value}${unit}`);
+      },
+      toBeGreaterThan: (value, unit = "") => {
+        if (target > value) return;
+        throw new Error(`expected ${label ? label + "(" + target + ")" : target} to be greater than ${value}${unit}`);
+      },
+      toInclude: (value) => {
+        if (target.indexOf(value) > -1) return;
+        throw new Error(`expected ${label ? label + "(" + target + ")" : target} to include ${value}`);
+      },
+      toMatch: (regex) => {
+        if (target.match(new RegExp(regex))) return;
+        throw new Error(`expected ${label ? label + "(" + target + ")" : target} to match ${regex}`);
+      },
+      toThrow: (message) => {
+        try {
+          target();
+        } catch (error) {
+          if (!message) return;
+          if (error.message === message) return;
+          if (error.message.match(new RegExp(message))) return;
+          throw new Error(`expected ${label ? label + "()" : "function()"} to throw ${message}, but got ${error.message}`);
+        }
+      },
+    };
+  }
+}
+
+function performance() {
+  return globalThis.performance.now();
+}

package/commands/bundle.js

@@ -1,19 +1,20 @@
 import { resolve } from "node:path";
 import { Bundler } from "../classes/bundler.js";
 import { Runtime } from "../classes/runtime.js";
+import { parseArgs } from "../utils.js";
 import DefaultCommand from "./default.js";
 
 export default class BundlerCommand extends DefaultCommand {
-  help() {
+  async help() {
     console.print("Bundles the specified entry file");
     console.print("\nUsage:");
     console.print("vistta bundle [filename] [outdir]\tBundles the specified entry file");
   }
 
   async main(_, ...argv) {
-    let [args, options] = this.parse(argv);
+    let [args, options] = parseArgs(argv);
     if (args.length === 0) return this.help();
-    options = Object.assign({}, this.options, options, { outdir: args[1] });
+    options = Object.assign({}, process.vistta?.options?.bundler || {}, options, { outdir: args[1] });
     new Bundler(new Runtime(global.vistta)).run(resolve(process.cwd(), args[0]), options);
   }
 }

package/commands/default.js

@@ -39,7 +39,9 @@ export default class DefaultCommand extends Command {
       const modules = await (await import("../utils.js"))?.getOutdatedPackages(process.cwd());
       for (let i = 0, len = modules.length; i < len; i++) {
         const { name, current, wanted, latest } = modules[i];
-        if (current === wanted) console.print(`${COLORS.CYAN}Module "${name}" has a new version (${latest})${COLORS.RESET}`);
+        if (!current) console.print(`${COLORS.YELLOW}Module "${name}" is missing${COLORS.RESET}`);
+        else if (current === wanted)
+          console.print(`${COLORS.CYAN}Module "${name}" has a new version (${latest})${COLORS.RESET}`);
         else console.print(`${COLORS.YELLOW}Module "${name}" is outdated (${latest})${COLORS.RESET}`);
       }
     } catch {

package/commands/project.js

@@ -1,101 +1,137 @@
-import { COLORS } from "@vistta/console";
 import fs from "@vistta/fs";
-import { capitalize } from "@vistta/utils";
+import { relative } from "node:path";
 import { Command } from "../classes/command.js";
-import { getOutdatedPackages, importJSON, incrementPackageVersion } from "../utils.js";
+import { getOutdatedPackages, importJSON, incrementPackageVersion, parseArgs } from "../utils.js";
 
 const HELP = {
-  name: "outputs current project name",
-  version: "outputs the project version",
-  "version [increment]": "updates the project version",
-  outdated: "lists all outdated modules in the project",
-  patch: "updates the version of outdated modules to the latest patch version in the project",
-  "patch [module]": "updates the version of outdated module to the latest patch version in the project",
-  update: "updates the version of outdated modules to the latest version in the project",
-  "update [module]": "updates the version of outdated module to the latest version in the project",
+  name: ["name", "Print the project name."],
+  version: [
+    "version [increment|version] [prerelease-id]",
+    "Print or change the project version. Increments: major, minor, patch, premajor, preminor, prepatch, prerelease.",
+  ],
+  outdated: [
+    "outdated [dependency]",
+    "Compare installed, wanted (within the declared range), and latest dependency versions.",
+  ],
+  update: [
+    "update [dependency] [--compatible] [--dry-run]",
+    "Update dependency ranges to latest; this may include major upgrades. --compatible selects wanted versions instead.",
+  ],
+  patch: ["patch [dependency] [--dry-run]", "Alias for update --compatible. This is range-compatible, not patch-only."],
 };
 
 export default class extends Command {
-  constructor(options) {
-    super(options);
-  }
-
-  help(_, command) {
-    switch (command) {
-      case "name":
-        console.print(capitalize(HELP["name"]));
-        console.print("\nUsage:");
-        console.print("vistta project name");
-        break;
-      case "version":
-        console.print(capitalize(HELP["version"]) + " or " + HELP["version [increment]"]);
-        console.print("\nUsage:");
-        console.print("vistta project version");
-        console.print("vistta project version [increment]");
-        break;
-      case "outdated":
-        console.print(capitalize(HELP["outdated"]));
-        console.print("\nUsage:");
-        console.print("vistta project outdated");
-        break;
-      case "patch":
-        console.print(capitalize(HELP["patch"]) + " or " + HELP["patch [module]"]);
-        console.print("\nUsage:");
-        console.print("vistta project patch");
-        console.print("vistta project patch [module]");
-        break;
-      case "update":
-        console.print(capitalize(HELP["update"]) + " or " + HELP["update [module]"]);
-        console.print("\nUsage:");
-        console.print("vistta project update");
-        console.print("vistta project update [module]");
-        break;
-      default:
-        console.print("Outputs the current project name or version, or updates the version");
-        console.print("\nUsage:");
-        Object.keys(HELP).forEach((key) => console.print(`vistta project ${key}\t\t\t${HELP[key]}`));
-        break;
+  async help(_, command) {
+    if (command && !Object.hasOwn(HELP, command))
+      throw new Error(`Unknown project command "${command}". Run vistta project --help.`);
+    console.print("Project metadata and dependency maintenance\n");
+    for (const [usage, description] of command ? [HELP[command]] : Object.values(HELP)) {
+      console.print(`  vistta project ${usage}\n    ${description}\n`);
     }
+    if (!command || ["outdated", "update", "patch"].includes(command))
+      console.print(
+        "Wanted respects npm policies and dependency ranges. Updates edit package.json only; run npm install afterward.",
+      );
   }
 
   async main(_, command, ...args) {
-    console.clear();
+    if (!command || command === "help") return this.help(_, args[0]);
+    if (!Object.hasOwn(HELP, command)) return this.help(_, command);
+    const [values, options] = parseArgs(args);
+    const allowed = command === "update" ? ["compatible", "dry-run"] : command === "patch" ? ["dry-run"] : [];
+    for (const [name, value] of Object.entries(options)) {
+      if (!allowed.includes(name)) throw new Error(`Unknown option --${name} for project ${command}`);
+      if (typeof value !== "boolean") throw new Error(`--${name} must be a boolean flag`);
+    }
+    const limit = command === "name" ? 0 : command === "version" ? 2 : 1;
+    if (values.length > limit) throw new Error(`Too many arguments. Run vistta project ${command} --help.`);
     switch (command) {
       case "name":
         return console.print(process.env.PROJECT_NAME);
       case "version":
-        if (!args[0]) return console.print(process.env.PROJECT_VERSION);
+        if (!values[0]) return console.print(process.env.PROJECT_VERSION);
         return console.print(
-          await incrementPackageVersion(fs.resolve(process.env.PROJECT_PATH, "package.json"), args[0], args[1]),
+          await incrementPackageVersion(fs.resolve(process.env.PROJECT_PATH, "package.json"), values[0], values[1]),
         );
       case "outdated":
       case "patch":
       case "update":
-        return modules(command, args[0]);
+        process.exit(await dependencies(command, values[0], options));
     }
-    return this.help(_, command);
   }
 }
 
-async function modules(command, arg1) {
+async function dependencies(command, dependency, options) {
   const modules = await getOutdatedPackages(process.cwd());
-  let valid = true;
-  let update = 0;
-  for (let i = 0, len = modules.length; i < len; i++) {
-    const { name, package: packagePath, current, wanted, latest, dev } = modules[i];
-    if (command === "patch" || command === "update") {
-      if (command === "patch" && current === wanted) continue;
-      if (arg1 && name !== arg1) continue;
-      const packageObj = await importJSON(packagePath);
-      packageObj[dev ? "devDependencies" : "dependencies"][name] = "^" + (command === "patch" ? wanted : latest);
-      await fs.writeFile(packagePath, JSON.stringify(packageObj, null, 2));
-      update++;
-    } else if (current === wanted)
-      console.print(`${COLORS.CYAN}Module "${name}" has a new version (${latest})${COLORS.RESET}`);
-    else (console.print(`${COLORS.YELLOW}Module "${name}" is outdated (${latest})${COLORS.RESET}`), (valid = false));
+  const selected = modules.filter((entry) => !dependency || entry.name === dependency);
+  if (!selected.length) {
+    console.print(
+      dependency
+        ? `No outdated dependency "${dependency}" found in this scope.`
+        : "All checked dependencies are up to date.",
+    );
+    return 0;
   }
-
-  if (modules.length == 0) console.print("Everything is up to date");
-  else if (update > 0) console.print(`Updated ${update} module${update > 1 ? "s" : ""} versions in project package.`);
-  process.exit(valid ? 0 : -1);
+  if (command === "outdated") {
+    const rows = [
+      ["Dependency", "Current", "Wanted", "Latest", "Manifest", "Type"],
+      ...selected.map((entry) => [
+        entry.name,
+        entry.current || "MISSING",
+        entry.wanted || "-",
+        entry.latest || "-",
+        relative(process.cwd(), entry.package) || "package.json",
+        entry.dev ? "dev" : "prod",
+      ]),
+    ];
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    for (const row of rows)
+      console.print(
+        row
+          .map((value, column) => value.padEnd(widths[column]))
+          .join("  ")
+          .trimEnd(),
+      );
+    const compatible = selected.filter((entry) => !entry.current || entry.current !== entry.wanted).length;
+    console.print(
+      `\n${compatible} compatible update(s) or missing dependency(s); ${selected.length - compatible} latest-only update(s).`,
+    );
+    console.print("Compatible updates cause a nonzero exit status; latest-only updates are informational.");
+    return compatible ? 1 : 0;
+  }
+  const compatible = command === "patch" || options.compatible === true;
+  const changes = new Map();
+  let count = 0;
+  for (const entry of selected) {
+    const target = compatible ? entry.wanted : entry.latest;
+    if (!target || entry.current === target) continue;
+    const manifest = changes.get(entry.package) || (await importJSON(entry.package));
+    const section = entry.dev ? "devDependencies" : "dependencies";
+    const previous = manifest[section]?.[entry.name];
+    if (typeof previous !== "string") throw new Error(`Dependency "${entry.name}" is missing from ${entry.package}`);
+    const next = "^" + target;
+    if (previous === next) continue;
+    manifest[section][entry.name] = next;
+    changes.set(entry.package, manifest);
+    count++;
+    console.print(
+      `${options["dry-run"] ? "Would update" : "Update"}: ${entry.name} ${previous} -> ${next} (${relative(process.cwd(), entry.package)}, ${section})`,
+    );
+  }
+  if (!count) {
+    console.print(
+      `No ${compatible ? "compatible " : ""}dependency range changes needed. Run npm install if installed versions are behind.`,
+    );
+    return 0;
+  }
+  if (!options["dry-run"]) {
+    for (const [path, manifest] of changes) await fs.writeFile(path, JSON.stringify(manifest, null, 2) + "\n");
+  }
+  console.print(
+    `\n${options["dry-run"] ? "Would change" : "Changed"} ${count} dependency range(s) in ${changes.size} manifest(s).`,
+  );
+  console.print(
+    options["dry-run"] ? "Dry run: no files changed." : "Run npm install to update installed packages and the lockfile.",
+  );
+  return 0;
 }

package/commands/quality.js

@@ -0,0 +1,52 @@
+import { Command } from "../classes/command.js";
+import { loadProjectConfig, mergeConfig } from "../config.js";
+import { runChecks } from "../tools.js";
+import { parseArgs } from "../utils.js";
+
+export default class extends Command {
+  help() {
+    console.log(
+      "vistta check [patterns] [--fix]\nvistta lint [patterns] [--fix]\nvistta fmt [patterns] [--write]\nvistta types\nvistta config [--sources]",
+    );
+  }
+
+  async main(command, ...argv) {
+    const [patterns, options] = parseArgs(argv);
+    const allowed = command === "config" ? ["sources"] : command === "fmt" ? ["write", "check", "fix"] : ["fix"];
+    for (const [option, value] of Object.entries(options)) {
+      if (!allowed.includes(option)) throw new Error(`Unknown option --${option}`);
+      if (typeof value !== "boolean") throw new Error(`--${option} must be a boolean flag`);
+    }
+    if (["types", "config"].includes(command) && patterns.length)
+      throw new Error(`${command} does not accept file patterns`);
+    if (command === "fmt" && options.check && (options.write || options.fix))
+      throw new Error("Use either --check or --write, not both");
+    const project = loadProjectConfig();
+    if (command === "config") {
+      const defaults = {
+        cli: {
+          check: { format: true, lint: true, types: true },
+          lint: { engine: "eslint" },
+          format: { engine: "prettier" },
+        },
+      };
+      const config = mergeConfig(defaults, project.config);
+      const sources = {
+        "cli.check.format": "<default>",
+        "cli.check.lint": "<default>",
+        "cli.check.types": "<default>",
+        "cli.lint.engine": "<default>",
+        "cli.format.engine": "<default>",
+        ...project.sources,
+      };
+      console.print(JSON.stringify(options.sources ? { file: project.file, config, sources } : config, null, 2));
+      return;
+    }
+    const names =
+      command === "check"
+        ? ["format", "lint", "types"].filter((name) => project.config.cli?.check?.[name] !== false)
+        : [command === "fmt" ? "format" : command];
+    const code = await runChecks(names, project, { patterns, fix: options.fix === true || options.write === true });
+    process.exit(code);
+  }
+}

package/commands/task.js

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Command } from "../classes/command.js";
+import { loadProjectConfig } from "../config.js";
+import { planTasks, runTasks } from "../tools.js";
+
+export default class extends Command {
+  help() {
+    console.log("vistta task <name> [-- args]\nvistta run <name> [-- args] (unless overridden by a framework)");
+  }
+
+  async main(_, name, ...args) {
+    if (!name) return this.help();
+    const cwd = process.cwd();
+    const { config } = loadProjectConfig(cwd);
+    const { scripts = {} } = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
+    const commands = Object.keys(process.vistta.options.cli.commands).filter(
+      (name) => !["default", "run", "task"].includes(name),
+    );
+    const plan = planTasks(name, config.cli?.tasks, scripts, commands);
+    process.exit(await runTasks(plan, cwd, args[0] === "--" ? args.slice(1) : args));
+  }
+}