@cubing/dev-config 0.6.6 → 0.7.1

package/README.md

@@ -50,6 +50,12 @@ bun add @biomejs/biome @cubing/dev-config
 bun x @biomejs/biome check
 ```
 
+Add to a project using [`repo`](https://github.com/lgarron/repo):
+
+```shell
+repo boilerplate biome add # Or invoke using `npx repo …` / `bun x repo …`
+```
+
 ### TypeScript
 
 #### Check types
@@ -72,6 +78,12 @@ bun add --dev typescript @cubing/dev-config
 bun x tsc --noEmit --project .
 ```
 
+Add to a project using [`repo`](https://github.com/lgarron/repo):
+
+```shell
+repo boilerplate tsconfig add # Or invoke using `npx repo …` / `bun x repo …`
+```
+
 #### Build types
 
 ```jsonc
@@ -95,6 +107,12 @@ bun add --dev typescript @cubing/dev-config
 bun x tsc --project .
 ```
 
+Add to a project using [`repo`](https://github.com/lgarron/repo):
+
+```shell
+repo boilerplate tsconfig add # Or invoke using `npx repo …` / `bun x repo …`
+```
+
 #### No DOM
 
 Use the `no-dom` variant instead:
@@ -106,6 +124,12 @@ Use the `no-dom` variant instead:
 }
 ```
 
+Add to a project using [`repo`](https://github.com/lgarron/repo):
+
+```shell
+repo boilerplate tsconfig add --no-dom # Or invoke using `npx repo …` / `bun x repo …`
+```
+
 ### `es2024`
 
 The following are also available:
@@ -115,6 +139,13 @@ The following are also available:
 
 This is useful for features like `Promise.withResolvers(…)`.
 
+Add to a project using [`repo`](https://github.com/lgarron/repo):
+
+```shell
+repo boilerplate tsconfig add --module es2022 # Or invoke using `npx repo …` / `bun x repo …`
+repo boilerplate tsconfig add --no-dom --module es2022 # Or invoke using `npx repo …` / `bun x repo …`
+```
+
 ### Checking `package.json` for a project
 
 Run as follows:

package/bin/package.json/index.js

@@ -0,0 +1,580 @@
+#!/usr/bin/env -S bun run --
+import {
+  __callDispose,
+  __using
+} from "../../chunks/chunk-OZDRWEHO.js";
+
+// src/bin/package.json/index.ts
+import assert from "node:assert";
+import { constants } from "node:fs/promises";
+import { argv, exit } from "node:process";
+import { semver } from "bun";
+import { Path, ResolutionPrefix, stringifyIfPath } from "path-class";
+import { PrintableShellCommand } from "printable-shell-command";
+function categorize(v) {
+  if (Array.isArray(v)) {
+    return "array";
+  }
+  if (v === null) {
+    return "null";
+  }
+  return typeof v;
+}
+function* withOrderingMetadata(iter) {
+  let previous;
+  for (const value of iter) {
+    if (previous) {
+      yield previous[0];
+      previous = [
+        { value, previous: { value: previous[0].value }, isLast: false }
+      ];
+    } else {
+      previous = [{ value, previous: null, isLast: false }];
+    }
+  }
+  if (previous) {
+    yield { ...previous[0], isLast: true };
+  }
+}
+function traverse(breadcrumbs, options) {
+  assert(breadcrumbs.length > 0);
+  let maybeValue = [packageJSON];
+  let breadcrumbString = "";
+  for (let { value: breadcrumb, isLast } of withOrderingMetadata(breadcrumbs)) {
+    if (Array.isArray(breadcrumb)) {
+      assert(breadcrumb.length === 1);
+      assert(typeof breadcrumb[0] === "string");
+      breadcrumb = breadcrumb[0];
+      breadcrumbString += `[${JSON.stringify(breadcrumb)}]`;
+    } else if (typeof breadcrumb === "string") {
+      breadcrumbString += `.${breadcrumb}`;
+    } else {
+      breadcrumbString += `[${breadcrumb}]`;
+    }
+    if (options && "set" in options && isLast) {
+      if (!maybeValue || !["array", "object"].includes(categorize(maybeValue[0]))) {
+        throw new Error(
+          "Missing (but expected) traversal path while setting a value"
+        );
+      }
+      maybeValue[0][breadcrumb] = stringifyIfPath(options.set);
+    } else if (maybeValue && ["array", "object"].includes(categorize(maybeValue[0])) && breadcrumb in maybeValue[0]) {
+      maybeValue = [maybeValue[0][breadcrumb]];
+    } else {
+      maybeValue = null;
+    }
+  }
+  return { breadcrumbString, maybeValue };
+}
+function field(breadcrumbs, type, options) {
+  const mustBePopulatedMessage = () => options?.mustBePopulatedMessage ?? "Field must be populated.";
+  const { breadcrumbString, maybeValue } = traverse(breadcrumbs);
+  if (!maybeValue) {
+    if (options?.optional) {
+      if (!options.skipPrintingSuccess) {
+        console.log(`\u2611\uFE0F ${breadcrumbString}`);
+      }
+      return;
+    } else {
+      console.log(`\u274C ${breadcrumbString} \u2014 ${mustBePopulatedMessage()}`);
+      exitCode = 1;
+      return;
+    }
+  }
+  const [value] = maybeValue;
+  const typeArray = Array.isArray(type) ? type : [type];
+  const category = categorize(value);
+  if (typeArray.includes(category)) {
+    for (const [failureMessage, fn] of Object.entries(
+      options?.additionalChecks ?? {}
+    )) {
+      if (!fn) {
+        console.log(`\u274C ${breadcrumbString} | ${failureMessage}`);
+        exitCode = 1;
+        return;
+      }
+    }
+    if (!options?.skipPrintingSuccess) {
+      console.log(`\u2705 ${breadcrumbString}`);
+    }
+  } else {
+    if (category === "undefined") {
+      console.log(`\u274C ${breadcrumbString} \u2014 ${mustBePopulatedMessage()}.`);
+    } else if (type === "undefined") {
+      console.log(
+        `\u274C ${breadcrumbString} \u2014 Field is populated (but must not be).`
+      );
+    } else {
+      if (Array.isArray(type)) {
+        console.log(
+          `\u274C ${breadcrumbString} \u2014 Does not match an expected type: ${type.join(", ")}`
+        );
+      } else {
+        console.log(
+          `\u274C ${breadcrumbString} \u2014 Does not match expected type: ${type}`
+        );
+      }
+    }
+    exitCode = 1;
+    return;
+  }
+}
+function mustNotBePopulated(breadcrumbs) {
+  const { breadcrumbString, maybeValue } = traverse(breadcrumbs);
+  if (maybeValue) {
+    console.log(`\u274C ${breadcrumbString} \u2014 Must not be present.`);
+    exitCode = 1;
+    return;
+  }
+}
+function checkPath(breadcrumbs, options) {
+  const { breadcrumbString, maybeValue } = traverse(breadcrumbs);
+  if (!maybeValue) {
+    return;
+  }
+  const [value] = maybeValue;
+  checks.push(
+    (async () => {
+      if (typeof value !== "string") {
+        exitCode = 1;
+        return `\u274C ${breadcrumbString} \u2014 Non-string value`;
+      }
+      if (value.includes("*")) {
+        return `\u23ED\uFE0F ${breadcrumbString} \u2014 Skipping due to glob (*) \u2014 ${value}`;
+      }
+      const unresolvedPath = new Path(value);
+      if (unresolvedPath.resolutionPrefix !== options.expectPrefix) {
+        if (unresolvedPath.resolutionPrefix === ResolutionPrefix.Absolute) {
+          exitCode = 1;
+          return `\u274C ${breadcrumbString} \u2014 Incorrect resolution prefix (${unresolvedPath.resolutionPrefix}) \u2014 ${value}`;
+        } else {
+          switch (subcommand) {
+            case "check": {
+              exitCode = 1;
+              foundFixableErrors = true;
+              return `\u274C ${breadcrumbString} \u2014 Incorrect resolution prefix (${unresolvedPath.resolutionPrefix}) \u2014 \u{1F4DD} fixable! \u2014 ${value}`;
+            }
+            case "format": {
+              console.log(
+                `\u{1F4DD} \u2014 Incorrect resolution prefix (${unresolvedPath.resolutionPrefix}) \u2014 fixing! \u2014 ${value}`
+              );
+              const newPath = options.expectPrefix === ResolutionPrefix.Bare ? unresolvedPath.asBare() : unresolvedPath.asRelative();
+              traverse(breadcrumbs, { set: newPath });
+              break;
+            }
+            default:
+              throw new Error("Invalid subcommand.");
+          }
+        }
+      }
+      if (unresolvedPath.path.startsWith("../") || unresolvedPath.path === "..") {
+        exitCode = 1;
+        return `\u274C ${breadcrumbString} \u2014 Invalid traversal of parent path. \u2014 ${value}`;
+      }
+      const resolvedPath = Path.resolve(unresolvedPath, extractedRoot);
+      if (!await resolvedPath.existsAsFile()) {
+        exitCode = 1;
+        return `\u274C ${breadcrumbString} \u2014 Path must be present in the package. \u2014 ${value}`;
+      }
+      if (options.mustBeExecutable) {
+        if (!((await resolvedPath.stat()).mode ^ constants.X_OK)) {
+          return `\u274C ${breadcrumbString} \u2014 File at path must be executable. \u2014 ${value}`;
+        }
+      }
+      return `\u2705 ${breadcrumbString} \u2014 Path must be present in the package. \u2014 ${value}`;
+    })()
+  );
+}
+var _stack = [];
+try {
+  var PERMITTED_LICENSES = /* @__PURE__ */ new Set([
+    "MPL-2.0",
+    "MIT",
+    "Unlicense",
+    "GPL-3.0-or-later"
+  ]);
+  var subcommand = (() => {
+    const subcommand2 = argv[2];
+    if (!["check", "format"].includes(subcommand2)) {
+      console.error("Must specify subcommand: `check` or `format`");
+      exit(1);
+    }
+    return subcommand2;
+  })();
+  var exitCode = 0;
+  var foundFixableErrors = false;
+  var PACKAGE_JSON_PATH = new Path("./package.json");
+  console.log("Parsing `package.json`:");
+  var packageJSONString = await PACKAGE_JSON_PATH.readText();
+  var packageJSON = (() => {
+    try {
+      const packageJSON2 = JSON.parse(packageJSONString);
+      console.log("\u2705 `package.json` is valid JSON.");
+      return packageJSON2;
+    } catch {
+      console.log(
+        "\u274C `package.json` must be valid JSON (not JSONC or JSON5 or anything else)."
+      );
+      exit(1);
+    }
+  })();
+  console.log("Checking field order:");
+  var opinionatedFieldOrder = [
+    "name",
+    "version",
+    "homepage",
+    "description",
+    "author",
+    "license",
+    "repository",
+    "engines",
+    "os",
+    "cpu",
+    "type",
+    "main",
+    "types",
+    "module",
+    "browser",
+    "exports",
+    "bin",
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies",
+    "bundleDependencies",
+    "devEngines",
+    "files",
+    "scripts",
+    "keywords",
+    "@cubing/deploy",
+    "$schema"
+  ];
+  var opinionatedFields = new Set(opinionatedFieldOrder);
+  var packageJSONOrder = [];
+  for (const key in packageJSON) {
+    if (opinionatedFields.has(key)) {
+      packageJSONOrder.push(key);
+    } else {
+      console.warn(`\u26A0\uFE0F [${JSON.stringify(key)}] Unexpected field.`);
+    }
+  }
+  var packageJSONByOpinionatedOrder = [];
+  for (const field2 of opinionatedFieldOrder) {
+    if (field2 in packageJSON) {
+      packageJSONByOpinionatedOrder.push(field2);
+    }
+  }
+  try {
+    assert.deepEqual(packageJSONOrder, packageJSONByOpinionatedOrder);
+    console.log(`\u2705 Field order is good.`);
+  } catch {
+    switch (subcommand) {
+      case "check": {
+        console.log(`\u274C Found opinionated fields out of order:`);
+        console.log(`\u21A4 ${packageJSONOrder.join(", ")}`);
+        console.log("Expected:");
+        console.log(`\u21A6 ${packageJSONByOpinionatedOrder.join(", ")}`);
+        console.log(
+          "\u{1F4DD} Run with the `sort` subcommand to sort. (Additional fields will kept after the field they previously followed.)"
+        );
+        foundFixableErrors = true;
+        exitCode = 1;
+        break;
+      }
+      case "format": {
+        console.log("\u{1F4DD} Invalid field order. Formatting\u2026");
+        exitCode = 1;
+        const newKeyOrder = [];
+        for (const key of packageJSONByOpinionatedOrder) {
+          newKeyOrder.push(key);
+        }
+        for (const { value: key, previous } of withOrderingMetadata(
+          Object.keys(packageJSON)
+        )) {
+          if (newKeyOrder.includes(key)) {
+            continue;
+          }
+          if (!previous) {
+            newKeyOrder.unshift(key);
+          } else {
+            const { value: previousKey } = previous;
+            const idx = newKeyOrder.indexOf(previousKey);
+            newKeyOrder.splice(idx + 1, 0, key);
+          }
+        }
+        const newPackageJSON = {};
+        for (const key of newKeyOrder) {
+          newPackageJSON[key] = packageJSON[key];
+        }
+        packageJSON = newPackageJSON;
+        break;
+      }
+      default:
+        throw new Error("Invalid subcommand.");
+    }
+  }
+  console.log("Checking presence and type of fields:");
+  field(["name"], "string");
+  field(["version"], "string", {
+    additionalChecks: {
+      "Version must parse successfully.": (version) => semver.order(version, version) === 0
+    }
+  });
+  field(["homepage"], "string", { optional: true });
+  field(["description"], "string");
+  field(["author"], ["string", "object"]);
+  if (categorize(packageJSON["author"]) === "object") {
+    field(["author", "name"], "string");
+    field(["author", "email"], "string");
+    field(["author", "url"], "string", {
+      additionalChecks: {
+        "URL must parse.": (url) => {
+          try {
+            new URL(url);
+            return true;
+          } catch {
+            return false;
+          }
+        }
+      }
+    });
+  }
+  field(["license"], "string", {
+    additionalChecks: {
+      "Must contain a non-permitted license.": (license) => {
+        for (const licenseEntry of license.split(" OR ")) {
+          if (!PERMITTED_LICENSES.has(licenseEntry)) {
+            return false;
+          }
+        }
+        return true;
+      }
+    }
+  });
+  field(["repository"], "object");
+  field(["repository", "type"], "string");
+  var GIT_URL_PREFIX = "git+";
+  var GIT_URL_SUFFIX = ".";
+  field(["repository", "url"], "string", {
+    additionalChecks: {
+      [`URL must be prefixed with \`${GIT_URL_PREFIX}\`.`]: (url) => url.startsWith(GIT_URL_PREFIX),
+      [`URL must end with with \`.${GIT_URL_SUFFIX}\`.`]: (url) => url.endsWith(GIT_URL_SUFFIX),
+      "URL must parse.": (url) => {
+        try {
+          new URL(url.slice());
+          return true;
+        } catch {
+          return false;
+        }
+      }
+    }
+  });
+  field(["engines"], "object", { optional: true });
+  field(["os"], "array", { optional: true });
+  field(["cpu"], "array", { optional: true });
+  field(["type"], "string", {
+    additionalChecks: {
+      'Type must be `"module"`.': (type) => type === "module"
+    }
+  });
+  var mainOrTypesArePopoulated = (() => {
+    if ("main" in packageJSON || "types" in packageJSON) {
+      field(["main"], "string", {
+        mustBePopulatedMessage: 'Must be populated if "types" is populated.'
+      });
+      field(["types"], "string", {
+        mustBePopulatedMessage: 'Must be populated if "main" is populated.'
+      });
+      return true;
+    } else {
+      console.log("\u2611\uFE0F .main");
+      console.log("\u2611\uFE0F .types");
+      return false;
+    }
+  })();
+  mustNotBePopulated(["module"]);
+  mustNotBePopulated(["browser"]);
+  field(["exports"], "object", { optional: !mainOrTypesArePopoulated });
+  field(["bin"], "object", { optional: true });
+  field(["dependencies"], "object", { optional: true });
+  field(["devDependencies"], "object", { optional: true });
+  field(["optionalDependencies"], "object", { optional: true });
+  field(["peerDependencies"], "object", { optional: true });
+  field(["bundleDependencies"], "object", { optional: true });
+  field(["devEngines"], "object", { optional: true });
+  field(["files"], "array");
+  field(["scripts"], "object");
+  field(["scripts", "prepublishOnly"], "string");
+  console.log("Checking paths of binaries and exports:");
+  var tempDir = await Path.makeTempDir();
+  var tempDirDisposable = __using(_stack, {
+    [Symbol.asyncDispose]: async () => {
+      console.log("Disposing\u2026");
+      await tempDir.rm_rf();
+    }
+  }, true);
+  var extractionDir = await tempDir.join("extracted").mkdir();
+  var data = await new PrintableShellCommand("npm", [
+    "pack",
+    "--json",
+    "--ignore-scripts",
+    ["--pack-destination", tempDir]
+  ]).print().json();
+  var tgzPath = tempDir.join(data[0].filename);
+  await new PrintableShellCommand("tar", [
+    ["-C", extractionDir],
+    ["-xvzf", tgzPath]
+  ]).spawn().success;
+  var extractedRoot = extractionDir.join("package/");
+  assert(await extractedRoot.existsAsDir());
+  var checks = [];
+  checkPath(["main"], { expectPrefix: ResolutionPrefix.Relative });
+  checkPath(["types"], { expectPrefix: ResolutionPrefix.Relative });
+  checkPath(["module"], { expectPrefix: ResolutionPrefix.Relative });
+  checkPath(["browser"], { expectPrefix: ResolutionPrefix.Relative });
+  var { exports } = packageJSON;
+  if (exports) {
+    for (const [subpath, value] of Object.entries(exports)) {
+      if (!value) {
+        continue;
+      } else if (typeof value === "string") {
+        checkPath(["exports", [subpath]], {
+          expectPrefix: ResolutionPrefix.Relative
+        });
+      } else if (value === null) {
+        continue;
+      } else if (Array.isArray(value)) {
+        throw new Error(
+          "\u274C .exports \u2014 Must use an object (instead of an array)."
+        );
+      } else {
+        const keys = Object.keys(value);
+        checks.push(
+          (async () => {
+            const { breadcrumbString } = traverse(["exports", [subpath]]);
+            const fixingLines = [];
+            const orderingErrorLines = [];
+            let updateKeys = false;
+            if (keys.includes("types")) {
+              if (keys[0] !== "types") {
+                switch (subcommand) {
+                  case "check": {
+                    orderingErrorLines.push(
+                      `  \u21AA "types" must be the first export if present \u2014 \u{1F4DD} fixable!`
+                    );
+                    break;
+                  }
+                  case "format": {
+                    fixingLines.push(
+                      `  \u21AA "types" must be the first export if present \u2014 \u{1F4DD} fixing!`
+                    );
+                    keys.splice(keys.indexOf("types"), 1);
+                    keys.splice(0, 0, "types");
+                    updateKeys = true;
+                    break;
+                  }
+                  default:
+                    throw new Error("Invalid subcommand.");
+                }
+              }
+            }
+            if (keys.includes("default")) {
+              if (keys.at(-1) !== "default") {
+                switch (subcommand) {
+                  case "check": {
+                    orderingErrorLines.push(
+                      `  \u21AA "default" must be the last export if present \u2014 \u{1F4DD} fixable!`
+                    );
+                    break;
+                  }
+                  case "format": {
+                    fixingLines.push(
+                      `  \u21AA "default" must be the last export if present \u2014 \u{1F4DD} fixing!`
+                    );
+                    keys.splice(keys.indexOf("default"), 1);
+                    keys.push("default");
+                    updateKeys = true;
+                    break;
+                  }
+                  default:
+                    throw new Error("Invalid subcommand.");
+                }
+              }
+            }
+            if (updateKeys) {
+              const newConditionalExports = {};
+              for (const key of keys) {
+                newConditionalExports[key] = value[key];
+              }
+              exports[subpath] = newConditionalExports;
+            }
+            for (const key of keys) {
+              if (!["types", "import", "default"].includes(key)) {
+                orderingErrorLines.push(
+                  `  \u21AA Key must not be present: ${JSON.stringify(key)}`
+                );
+              }
+            }
+            if (orderingErrorLines.length > 0) {
+              exitCode = 1;
+              return [
+                `\u274C ${breadcrumbString} \u2014 Invalid keys:`,
+                ...orderingErrorLines
+              ].join("\n");
+            } else {
+              if (fixingLines.length > 0) {
+                return [
+                  `\u2705 ${breadcrumbString} \u2014 Fixing key ordering:`,
+                  ...fixingLines
+                ].join("\n");
+              } else {
+                return `\u2705 ${breadcrumbString} \u2014 Key set and ordering is OK.`;
+              }
+            }
+          })()
+        );
+        for (const secondaryKey of keys) {
+          checkPath(["exports", [subpath], secondaryKey], {
+            expectPrefix: ResolutionPrefix.Relative
+          });
+        }
+      }
+    }
+  }
+  var { bin } = packageJSON;
+  if (bin) {
+    for (const binEntry of Object.keys(bin)) {
+      checkPath(["bin", [binEntry]], {
+        // `npm pkg fix` prefers bare paths for `bin` entries for some reason. 🤷
+        expectPrefix: ResolutionPrefix.Bare,
+        // `npm` will technically make binary entry points executable, but we want
+        // to enforce that the unpackaged path also is. This is particularly
+        // important when the package is linked.
+        mustBeExecutable: true
+      });
+    }
+  }
+  console.log((await Promise.all(checks)).join("\n"));
+  if (subcommand === "format") {
+    console.log("\u{1F4DD} Writing formatting fixes.");
+    await PACKAGE_JSON_PATH.write(`${JSON.stringify(packageJSON, null, "  ")}
+`);
+    console.log(PACKAGE_JSON_PATH.path);
+    console.log("\u{1F4DD} Running `npm pkg fix`.");
+    await new PrintableShellCommand("npm", ["pkg", "fix"]).print({ argumentLineWrapping: "inline" }).spawn().success;
+  } else if (foundFixableErrors) {
+    console.log();
+    console.log(
+      "\u{1F4DD} Found fixable errors. Run with the `format` subcommand to fix."
+    );
+    console.log();
+  }
+  await tempDirDisposable[Symbol.asyncDispose]();
+  exit(exitCode);
+} catch (_) {
+  var _error = _, _hasError = true;
+} finally {
+  var _promise = __callDispose(_stack, _error, _hasError);
+  _promise && await _promise;
+}
+//# sourceMappingURL=index.js.map