@cubing/dev-config 0.5.0 → 0.6.1

package/README.md

@@ -114,3 +114,13 @@ The following are also available:
 - `./node_modules/@cubing/dev-config/ts/es2024-types/no-dom/tsconfig.json`
 
 This is useful for features like `Promise.withResolvers(…)`.
+
+### Checking `package.json` for a project
+
+Run as follows:
+
+```shell
+bun x --package @cubing/dev-config package.json check
+```
+
+This checks both syntax and the presence of exports (and similar).

package/bin/package.json.ts

@@ -0,0 +1,582 @@
+#!/usr/bin/env -S bun run --
+
+/** biome-ignore-all lint/complexity/useLiteralKeys: https://github.com/biomejs/biome/discussions/7404 */
+
+import assert from "node:assert";
+import { constants } from "node:fs/promises";
+import { argv, exit } from "node:process";
+import type { JSONSchemaForNPMPackageJsonFiles } from "@schemastore/package";
+import { semver } from "bun";
+import { Path, ResolutionPrefix, stringifyIfPath } from "path-class";
+import { PrintableShellCommand } from "printable-shell-command";
+
+// Licenses from https://github.com/cubing/infra?tab=readme-ov-file#conventions
+const PERMITTED_LICENSES = new Set([
+  "MPL-2.0",
+  "MIT",
+  "Unlicense",
+  "GPL-3.0-or-later",
+]);
+
+// TODO: proper CLI parsing once this gets more complicated.
+const subcommand: "check" | "format" = (() => {
+  const subcommand = argv[2];
+  if (!["check", "format"].includes(subcommand)) {
+    console.error("Must specify subcommand: `check` or `format`");
+    exit(1);
+  }
+  return subcommand as "check" | "format";
+})();
+
+let exitCode: number = 0;
+let foundFixableErrors: boolean = false;
+
+const PACKAGE_JSON_PATH = new Path("./package.json");
+
+/*
+
+Note: this checker is opinionated, and does not allow certain patterns.
+
+It also assumes certain conventions about package structure and maintenance.
+
+*/
+
+// TODO: support "format" command that corrects some things.
+// TODO: Schema validation.
+
+console.log("Parsing `package.json`:");
+const packageJSONString = await PACKAGE_JSON_PATH.readText();
+let packageJSON: JSONSchemaForNPMPackageJsonFiles = (() => {
+  try {
+    const packageJSON: JSONSchemaForNPMPackageJsonFiles =
+      JSON.parse(packageJSONString);
+    console.log("✅ `package.json` is valid JSON.");
+    return packageJSON;
+  } catch {
+    console.log(
+      "❌ `package.json` must be valid JSON (not JSONC or JSON5 or anything else).",
+    );
+    exit(1);
+  }
+})();
+
+console.log("Checking field order:");
+const 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",
+] as const;
+const opinionatedFields = new Set(opinionatedFieldOrder);
+
+const packageJSONOrder: string[] = [];
+for (const key in packageJSON) {
+  // biome-ignore lint/suspicious/noExplicitAny: Type wrangling
+  if (opinionatedFields.has(key as any)) {
+    packageJSONOrder.push(key);
+  } else {
+    console.warn(`⚠️ [${JSON.stringify(key)}] Unexpected field.`);
+  }
+}
+const packageJSONByOpinionatedOrder: string[] = [];
+for (const field of opinionatedFieldOrder) {
+  if (field in packageJSON) {
+    packageJSONByOpinionatedOrder.push(field);
+  }
+}
+
+try {
+  assert.deepEqual(packageJSONOrder, packageJSONByOpinionatedOrder);
+  console.log(`✅ Field order is good.`);
+} catch {
+  switch (subcommand) {
+    case "check": {
+      console.log(`❌ Found opinionated fields out of order:`);
+      console.log(`↤ ${packageJSONOrder.join(", ")}`);
+      console.log("Expected:");
+      console.log(`↦ ${packageJSONByOpinionatedOrder.join(", ")}`);
+      console.log(
+        "📝 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("📝 Invalid field order. Formatting…");
+      exitCode = 1;
+      const newKeyOrder: string[] = [];
+      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: JSONSchemaForNPMPackageJsonFiles = {};
+      for (const key of newKeyOrder) {
+        newPackageJSON[key] = packageJSON[key];
+      }
+      packageJSON = newPackageJSON;
+      break;
+    }
+    default:
+      throw new Error("Invalid command.") as never;
+  }
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof#description
+type TypeOfType =
+  | "undefined"
+  | "object"
+  | "boolean"
+  | "number"
+  | "bigint"
+  | "string"
+  | "symbol"
+  | "function"
+  | "object";
+type Categorization = "array" | "null" | TypeOfType;
+// biome-ignore lint/suspicious/noExplicitAny: `any` is correct.
+function categorize(v: any): Categorization {
+  if (Array.isArray(v)) {
+    return "array";
+  }
+  if (v === null) {
+    return "null";
+  }
+  return typeof v;
+}
+
+interface OrderingMetadata<T> {
+  value: T;
+  previous: { value: T } | null;
+  isLast: boolean;
+}
+function* withOrderingMetadata<T>(
+  iter: Iterable<T>,
+): Iterable<OrderingMetadata<T>> {
+  // The following functions as an `Option<T>`, even when `T` is undefined.
+  let previous: [OrderingMetadata<T>] | undefined;
+  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 };
+  }
+}
+type Breadcrumbs = (string | [string] | number)[];
+function traverse<T>(
+  breadcrumbs: Breadcrumbs,
+  options?: { set?: T },
+): {
+  breadcrumbString: string;
+  maybeValue: [T] | null;
+} {
+  assert(breadcrumbs.length > 0);
+  // biome-ignore lint/suspicious/noExplicitAny: Type wrangling
+  let maybeValue: [T | any] | null = [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]))
+      ) {
+        // This okay for now, because we currently only write to values we have read.
+        throw new Error(
+          "Missing (but expected) traversal path while setting a value",
+        ) as never;
+      }
+      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<T>(
+  breadcrumbs: Breadcrumbs,
+  type: Categorization | Categorization[],
+  options?: {
+    optional?: boolean;
+    additionalChecks?: { [requirementMessage: string]: (t: T) => boolean };
+    skipPrintingSuccess?: boolean;
+  },
+) {
+  const { breadcrumbString, maybeValue } = traverse(breadcrumbs);
+  if (!maybeValue) {
+    if (options?.optional) {
+      if (!options.skipPrintingSuccess) {
+        console.log(`☑️ ${breadcrumbString}`);
+      }
+      return;
+    } else {
+      console.log(`❌ ${breadcrumbString} — Must be present.`);
+      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(`❌ ${breadcrumbString} | ${failureMessage}`);
+        exitCode = 1;
+        return;
+      }
+    }
+    if (!options?.skipPrintingSuccess) {
+      console.log(`✅ ${breadcrumbString}`);
+    }
+  } else {
+    if (category === "undefined") {
+      console.log(`❌ ${breadcrumbString} — Must be present.`);
+    } else if (type === "undefined") {
+      console.log(`❌ ${breadcrumbString} — Present (but must not be).`);
+    } else {
+      if (Array.isArray(type)) {
+        console.log(
+          `❌ ${breadcrumbString} — Does not match an expected type: ${type.join(", ")}`,
+        );
+      } else {
+        console.log(
+          `❌ ${breadcrumbString} — Does not match expected type: ${type}`,
+        );
+      }
+    }
+    exitCode = 1;
+    return;
+  }
+}
+
+function mustNotBePresent(breadcrumbs: Breadcrumbs) {
+  const { breadcrumbString, maybeValue } = traverse(breadcrumbs);
+  if (maybeValue) {
+    console.log(`❌ ${breadcrumbString} — Must not be present.`);
+    exitCode = 1;
+    return;
+  }
+}
+
+console.log("Checking presence and type of fields:");
+
+field(["name"], "string");
+field(["version"], "string", {
+  additionalChecks: {
+    "Version cannot be parsed.": (version: string) =>
+      semver.order(version, version) === 0,
+  },
+});
+field(["homepage"], "string", { optional: true });
+field(["description"], "string");
+// TODO: format author.
+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: string) => {
+        try {
+          new URL(url);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+    },
+  });
+}
+field(["license"], "string", {
+  additionalChecks: {
+    "Must contain a non-permitted license.": (license: string) => {
+      for (const licenseEntry of license.split(" OR ")) {
+        if (!PERMITTED_LICENSES.has(licenseEntry)) {
+          return false;
+        }
+      }
+      return true;
+    },
+  },
+});
+// TODO: format repo.
+field(["repository"], "object");
+field(["repository", "type"], "string");
+const GIT_URL_PREFIX = "git+";
+const GIT_URL_SUFFIX = ".";
+field(["repository", "url"], "string", {
+  additionalChecks: {
+    [`URL must be prefixed with \`${GIT_URL_PREFIX}\`.`]: (url: string) =>
+      url.startsWith(GIT_URL_PREFIX),
+    [`URL must end with with \`.${GIT_URL_SUFFIX}\`.`]: (url: string) =>
+      url.endsWith(GIT_URL_SUFFIX),
+    "URL must parse.": (url: string) => {
+      try {
+        new URL(url.slice());
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  },
+});
+// TODO: Validate version range syntax.
+field(["engines"], "object", { optional: true });
+field(["os"], "array", { optional: true });
+field(["cpu"], "array", { optional: true });
+field(["type"], "string", {
+  additionalChecks: {
+    'Type must be `"module"`.': (type: string) => type === "module",
+  },
+});
+field(["exports"], "object");
+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 });
+// TODO: check for path resolution prefix?
+// Set to `["*"]` if needed.
+field(["files"], "array");
+field(["scripts"], "object");
+// Set to `"# no-op"` if needed.
+field(["scripts", "prepublishOnly"], "string");
+if ("main" in packageJSON || "types" in packageJSON) {
+  field(["main"], "string");
+  field(["types"], "string");
+} else {
+  console.log("☑️ .main");
+  console.log("☑️ .types");
+}
+mustNotBePresent(["module"]);
+mustNotBePresent(["browser"]);
+
+console.log("Checking paths of binaries and exports:");
+
+const tempDir = await Path.makeTempDir();
+await using _ = {
+  [Symbol.asyncDispose]: () => tempDir.rm_rf(),
+};
+const extractionDir = await tempDir.join("extracted").mkdir();
+const data: { filename: string }[] = await new PrintableShellCommand("npm", [
+  "pack",
+  "--json",
+  "--ignore-scripts",
+  ["--pack-destination", tempDir],
+]).json();
+const tgzPath = tempDir.join(data[0].filename);
+await new PrintableShellCommand("tar", [
+  ["-C", extractionDir],
+  ["-xvzf", tgzPath],
+]).spawn().success;
+
+const extractedRoot = extractionDir.join("package/");
+assert(await extractedRoot.existsAsDir());
+
+const checks: Promise<string>[] = [];
+
+// TODO: check compilability
+function checkPath(
+  breadcrumbs: Breadcrumbs,
+  options: { expectPrefix: ResolutionPrefix; mustBeExecutable?: true },
+) {
+  const { breadcrumbString, maybeValue } = traverse(breadcrumbs);
+  if (!maybeValue) {
+    return;
+  }
+  const [value] = maybeValue;
+  checks.push(
+    (async () => {
+      if (typeof value !== "string") {
+        exitCode = 1;
+        return `❌ ${breadcrumbString} — Non-string value`;
+      }
+      if (value.includes("*")) {
+        return `⏭️ ${breadcrumbString} — Skipping due to glob (*) — ${value}`;
+      }
+      const unresolvedPath = new Path(value);
+      if (unresolvedPath.resolutionPrefix !== options.expectPrefix) {
+        if (unresolvedPath.resolutionPrefix === ResolutionPrefix.Absolute) {
+          exitCode = 1;
+          return `❌ ${breadcrumbString} — Incorrect resolution prefix (${unresolvedPath.resolutionPrefix}) — ${value}`;
+        } else {
+          switch (subcommand) {
+            case "check": {
+              exitCode = 1;
+              foundFixableErrors = true;
+              return `❌ ${breadcrumbString} — Incorrect resolution prefix (${unresolvedPath.resolutionPrefix}) — 📝 fixable! — ${value}`;
+            }
+            case "format": {
+              console.log(
+                `📝 — Incorrect resolution prefix (${unresolvedPath.resolutionPrefix}) — fixing! — ${value}`,
+              );
+              // TODO: do this calculation before reporting as fixable
+              const newPath =
+                options.expectPrefix === ResolutionPrefix.Bare
+                  ? unresolvedPath.asBare()
+                  : unresolvedPath.asRelative();
+              traverse(breadcrumbs, { set: newPath });
+              break;
+            }
+            default:
+              throw new Error("Invalid command.") as never;
+          }
+        }
+      }
+      if (
+        unresolvedPath.path.startsWith("../") ||
+        unresolvedPath.path === ".."
+      ) {
+        exitCode = 1;
+        return `❌ ${breadcrumbString} — Invalid traversal of parent path. — ${value}`;
+      }
+      const resolvedPath = Path.resolve(unresolvedPath, extractedRoot);
+      // TODO: allow folders (with a required trailing slash)?
+      if (!(await resolvedPath.existsAsFile())) {
+        exitCode = 1;
+        return `❌ ${breadcrumbString} — Missing — ${value}`;
+      }
+      if (options.mustBeExecutable) {
+        if (!((await resolvedPath.stat()).mode ^ constants.X_OK)) {
+          // This is not considered fixable because the binary may be the output
+          // of a build process. In that case, the build process is responsible
+          // for marking it as executable.
+          return `❌ ${breadcrumbString} — Must be executable — ${value}`;
+        }
+      }
+      return `✅ ${breadcrumbString} — OK — ${value}`;
+    })(),
+  );
+}
+
+checkPath(["main"], { expectPrefix: ResolutionPrefix.Relative });
+checkPath(["types"], { expectPrefix: ResolutionPrefix.Relative });
+checkPath(["module"], { expectPrefix: ResolutionPrefix.Relative });
+checkPath(["browser"], { expectPrefix: ResolutionPrefix.Relative });
+
+if (packageJSON.exports) {
+  for (const [exportPath, value] of Object.entries(packageJSON.exports)) {
+    if (!value) {
+      // biome-ignore lint/complexity/noUselessContinue: Explicit control flow.
+      continue;
+    } else if (typeof value === "string") {
+      checkPath(["exports", [exportPath]], {
+        expectPrefix: ResolutionPrefix.Relative,
+      });
+    } else if (value === null) {
+      // biome-ignore lint/complexity/noUselessContinue: Explicit control flow.
+      continue;
+    } else if (Array.isArray(value)) {
+      throw new Error(
+        "❌ .exports — Must use an object (instead of an array).",
+      );
+    } else {
+      for (const secondaryKey of Object.keys(value as Record<string, string>)) {
+        checkPath(["exports", [exportPath], secondaryKey], {
+          expectPrefix: ResolutionPrefix.Relative,
+        });
+      }
+    }
+  }
+}
+
+const { bin } = packageJSON;
+if (bin) {
+  for (const binEntry of Object.keys(bin as Record<string, string>)) {
+    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("📝 Writing formatting fixes.");
+  // TODO: support trailing space in `path-class`.
+  await PACKAGE_JSON_PATH.write(`${JSON.stringify(packageJSON, null, "  ")}\n`);
+  console.log(PACKAGE_JSON_PATH.path);
+  console.log("📝 Running `npm pkg fix.");
+  await new PrintableShellCommand("npm", ["pkg", "fix"])
+    .print({ argumentLineWrapping: "inline" })
+    .spawn().success;
+} else if (foundFixableErrors) {
+  console.log();
+  console.log(
+    "📝 Found fixable errors. Run with the `format` subcommand to fix.",
+  );
+  console.log();
+}
+
+exit(exitCode);

package/package.json

@@ -1,27 +1,45 @@
 {
   "name": "@cubing/dev-config",
-  "version": "0.5.0",
-  "type": "module",
-  "dependencies": {
-    "esbuild": ">=0.25.3 && <1.0.0"
+  "version": "0.6.1",
+  "description": "Common dev configs for projects.",
+  "author": {
+    "name": "Lucas Garron",
+    "email": "code@garron.net",
+    "url": "https://garron.net/"
   },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.2",
-    "@types/bun": "^1.3.1",
-    "typescript": "^5.9.3"
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cubing/dev-config.git"
   },
+  "type": "module",
   "exports": {
     "./esbuild/es2022": {
       "types": "./esbuild/es2022/index.d.ts",
       "import": "./esbuild/es2022/index.js"
     }
   },
-  "scripts": {
-    "prepublishOnly": "make prepublishOnly"
+  "bin": {
+    "package.json": "bin/package.json.ts"
+  },
+  "dependencies": {
+    "esbuild": ">=0.25.3 && <1.0.0",
+    "path-class": ">=0.10.8",
+    "printable-shell-command": "^3.0.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@schemastore/package": "^0.0.10",
+    "@types/bun": "^1.3.5",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
   },
   "files": [
     "./biome/",
     "./esbuild/",
     "./ts/"
-  ]
+  ],
+  "scripts": {
+    "prepublishOnly": "make prepublishOnly"
+  }
 }