@cubing/dev-config 0.6.5 → 0.7.0

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.ts

@@ -41,7 +41,6 @@ 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`:");
@@ -332,7 +331,7 @@ console.log("Checking presence and type of fields:");
 field(["name"], "string");
 field(["version"], "string", {
   additionalChecks: {
-    "Version cannot be parsed.": (version: string) =>
+    "Version must parse successfully.": (version: string) =>
       semver.order(version, version) === 0,
   },
 });
@@ -398,20 +397,24 @@ field(["type"], "string", {
     'Type must be `"module"`.': (type: string) => type === "module",
   },
 });
-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.',
-  });
-} else {
-  console.log("☑️ .main");
-  console.log("☑️ .types");
-}
+const 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("☑️ .main");
+    console.log("☑️ .types");
+    return false;
+  }
+})();
 mustNotBePopulated(["module"]);
 mustNotBePopulated(["browser"]);
-field(["exports"], "object");
+field(["exports"], "object", { optional: !mainOrTypesArePopoulated });
 field(["bin"], "object", { optional: true });
 field(["dependencies"], "object", { optional: true });
 field(["devDependencies"], "object", { optional: true });
@@ -429,8 +432,11 @@ field(["scripts", "prepublishOnly"], "string");
 console.log("Checking paths of binaries and exports:");
 
 const tempDir = await Path.makeTempDir();
-await using _ = {
-  [Symbol.asyncDispose]: () => tempDir.rm_rf(),
+await using tempDirDisposable = {
+  [Symbol.asyncDispose]: async () => {
+    console.log("Disposing…");
+    await tempDir.rm_rf();
+  },
 };
 const extractionDir = await tempDir.join("extracted").mkdir();
 // TODO: is there a 100% reliable way to test against paths that *will* be packed?
@@ -514,17 +520,17 @@ function checkPath(
       // TODO: allow folders (with a required trailing slash)?
       if (!(await resolvedPath.existsAsFile())) {
         exitCode = 1;
-        return `❌ ${breadcrumbString} — Path is not present on disk. — ${value}`;
+        return `❌ ${breadcrumbString} — Path must be present in the package. — ${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} — File at path must be executable — ${value}`;
+          return `❌ ${breadcrumbString} — File at path must be executable. — ${value}`;
         }
       }
-      return `✅ ${breadcrumbString} — OK — ${value}`;
+      return `✅ ${breadcrumbString} — Path must be present in the package. — ${value}`;
     })(),
   );
 }
@@ -642,7 +648,7 @@ if (exports) {
                 ...fixingLines,
               ].join("\n");
             } else {
-              return `✅ ${breadcrumbString} — Key set and ordering is okay.`;
+              return `✅ ${breadcrumbString} — Key set and ordering is OK.`;
             }
           }
         })(),
@@ -689,4 +695,6 @@ if (subcommand === "format") {
   console.log();
 }
 
+await tempDirDisposable[Symbol.asyncDispose]();
+
 exit(exitCode);

package/lib/check-allowed-imports/checkAllowedImports.ts

@@ -0,0 +1,152 @@
+import {
+  type BuildOptions,
+  build,
+  type ImportKind,
+  type Metafile,
+  type Plugin,
+} from "esbuild";
+import { es2022Lib } from "../../src/esbuild/es2022";
+
+/**
+ * Note:
+ * - A file may be matched by any parent path scope key.
+ * - Files in a given scope key are allowed to import any other within the same scope.
+ */
+export type AllowedImports = {
+  [scope: string]: { static?: string[]; dynamic?: string[] };
+};
+
+const plugin = {
+  name: "mark-bare-imports-as-external",
+  setup(build) {
+    const filter = /^[^./]|^\.[^./]|^\.\.[^/]/; // Must not start with "/" or "./" or "../"
+    build.onResolve({ filter }, (args) => ({
+      path: args.path,
+      external: true,
+    }));
+  },
+} satisfies Plugin;
+
+export async function checkAllowedImports(
+  groups: {
+    [description: string]: {
+      entryPoints: string[];
+      allowedImports: AllowedImports;
+    };
+  },
+  options?: { overrideEsbuildOptions: BuildOptions },
+): Promise<void> {
+  let failure = false;
+
+  console.log("+ means a new file");
+  console.log("- means a valid import for that file");
+
+  for (const [description, { entryPoints, allowedImports }] of Object.entries(
+    groups,
+  )) {
+    console.log(`# ${description}`);
+    // From https://github.com/evanw/esbuild/issues/619#issuecomment-1504100390
+
+    const { metafile } = await build({
+      ...es2022Lib(),
+      entryPoints,
+      plugins: [plugin],
+      ...options?.overrideEsbuildOptions,
+      write: false,
+      metafile: true,
+    });
+
+    // Starts with the path and then keeps chopping off from the right.
+    function* pathPrefixes(path: string) {
+      const pathParts = path.split("/");
+      for (let n = pathParts.length; n > 0; n--) {
+        yield pathParts.slice(0, n).join("/");
+      }
+    }
+
+    function matchingPathPrefix(matchPrefixes: string[], path: string) {
+      for (const pathPrefix of pathPrefixes(path)) {
+        if (matchPrefixes.includes(pathPrefix)) {
+          return pathPrefix;
+        }
+      }
+      return false;
+    }
+
+    const importKindMap: Partial<Record<ImportKind, "static" | "dynamic">> = {
+      "import-statement": "static",
+      "dynamic-import": "dynamic",
+    } as const;
+
+    function checkImport(
+      sourcePath: string,
+      importInfo: {
+        path: string;
+        kind: ImportKind;
+        external?: boolean;
+        original?: string;
+      },
+      allowedImports: AllowedImports,
+    ) {
+      const importKind = importKindMap[importInfo.kind];
+      if (!importKind) {
+        throw new Error("Unexpected import kind!");
+      }
+      for (const sourcePathPrefix of pathPrefixes(sourcePath)) {
+        const matchingSourcePathPrefix = matchingPathPrefix(
+          Object.keys(allowedImports),
+          sourcePathPrefix,
+        );
+        if (matchingSourcePathPrefix) {
+          const allowedImportsForKind =
+            allowedImports[matchingSourcePathPrefix][importKind];
+          if (
+            typeof allowedImportsForKind !== "undefined" &&
+            !Array.isArray(allowedImportsForKind)
+          ) {
+            throw new Error(
+              `Expected a string list for ${importKind} imports under the scope "${matchingSourcePathPrefix}"`,
+            );
+          }
+          if (
+            matchingPathPrefix(
+              [
+                matchingSourcePathPrefix, // allow importing from any source group to itself.
+                ...(allowedImportsForKind ?? []),
+              ],
+              importInfo.path,
+            )
+          ) {
+            process.stdout.write("-");
+            return;
+          }
+        }
+      }
+      failure = true;
+      console.error(`\n❌ File has disallowed ${importKind} import:`);
+      console.error(`From file: ${sourcePath}`);
+      console.error(`Importing: ${importInfo.path}`);
+    }
+
+    async function checkImports(
+      metafile: Metafile,
+      allowedImports: AllowedImports,
+    ) {
+      for (const [filePath, importInfoList] of Object.entries(
+        metafile.inputs,
+      )) {
+        process.stdout.write("+");
+        for (const importInfo of importInfoList.imports) {
+          checkImport(filePath, importInfo, allowedImports);
+        }
+      }
+      console.log();
+    }
+
+    await checkImports(metafile, allowedImports);
+  }
+
+  if (failure) {
+    throw new Error("Failure");
+  }
+}

package/lib/check-allowed-imports/index.ts

@@ -0,0 +1,4 @@
+export {
+  type AllowedImports,
+  checkAllowedImports,
+} from "./checkAllowedImports";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubing/dev-config",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Common dev configs for projects.",
   "author": {
     "name": "Lucas Garron",
@@ -17,6 +17,9 @@
     "./esbuild/es2022": {
       "types": "./esbuild/es2022/index.d.ts",
       "import": "./esbuild/es2022/index.js"
+    },
+    "./check-allowed-imports": {
+      "default": "./lib/check-allowed-imports/index.ts"
     }
   },
   "bin": {
@@ -37,6 +40,7 @@
   "files": [
     "./biome/",
     "./esbuild/",
+    "./lib",
     "./ts/"
   ],
   "scripts": {