Add build-package patch

.changeset/bright-camels-live.md

@@ -0,0 +1,7 @@
+---
+'skuba': major
+---
+
+build-package: Migrate to tsdown
+
+As part of our [migration to ESM](https://seek-oss.github.io/skuba/docs/deep-dives/esm.html), we are updating our package build process to support generating both CJS and ESM outputs, regardless of whether projects use CJS or ESM. Since our current tsc-based build does not support this, we are switching to [tsdown](https://tsdown.dev/) for package builds.

.changeset/smart-lamps-deny.md

@@ -0,0 +1,92 @@
+---
+'skuba': major
+---
+
+lint: Migrate `skuba build-package` usage to use [tsdown](https://tsdown.dev/) for building packages
+
+This patch will attempt to do a best effort migration of your `skuba build-package` usage to use [tsdown](https://tsdown.dev/) for building packages. This includes:
+
+1. Adding a `tsdown.config.mts` file to your package directories with a basic configuration
+2. Adding a `customConditions` entry to your root `tsconfig.json` file
+3. Adding `skipLibCheck` to your package `tsconfig.json` files to work around issues with type checking against `tsdown`.
+4. Updating your package `package.json` files to point to the new build outputs
+5. Removing redundant `tsconfig.build.json` files
+
+## File changes
+
+The output between what `skuba build-package` generates before and after this change will be different, so you may need to update any references to the output files in your project.
+
+For example the output for a simple `src/index.ts` file produces the following outputs:
+
+```diff
+-lib-commonjs/index.js
+-lib-es2015/index.js
+-lib-types/index.d.ts
++lib/index.cjs
++lib/index.mjs
++lib/index.d.cts
++lib/index.d.mts
+```
+
+This change may break consumers who directly access these output paths.
+
+To check if your consumers are affected, search GitHub with: `org:SEEK-Jobs content:"@seek/MY_PACKAGE/"`
+
+If needed, export those references from your package entry point to help consumers migrate to the new build outputs.
+
+Note: if you choose to remove the `unbundle: true` option from `tsdown.config.mts`, tsdown may emit bundled/chunked outputs and internal `lib/...` file paths can change between builds. Consumers should avoid importing from build output files directly, and instead import from the package entry point (or explicitly exported sub paths)
+
+## Format changes
+
+`tsdown` selects what ECMAScript target version to build for based on the `engines.node` field in your `package.json`.
+
+This means that for consumers previously relying on the `lib-es2015` output may need to update their runtime to match your package's `engines.node` field.
+
+An example changeset you may want to include for a package:
+
+````md
+---
+'my-package': major
+---
+
+Update npm package build outputs
+
+This release changes published build output paths. If you were previously importing from nested paths within the build output you will need to update imports to use the package entry point (for example, `@seek/my-package`).
+
+```diff
+-import type { SomeType } from '@seek/my-package/lib-types/...';
++import type { SomeType } from '@seek/my-package';
+```
+````
+
+## Debugging
+
+If your project utilises a `main` field which points to a `.ts` file within a monorepo setup, eg.
+
+```json
+ "main": "src/index.ts",
+```
+
+You may need to create a `moduleNameMapper` entry in your Jest config files to point to the source file, eg.
+
+```json
+{
+  "moduleNameMapper": {
+    "^@seek/my-package": "<rootDir>/packages/my-package/src/index.ts"
+  }
+}
+```
+
+This will work natively with custom conditions when we migrate to `vitest` in the future, but is required for Jest to continue working with the new build outputs.
+
+```ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  ssr: {
+    resolve: {
+      conditions: ['@seek/my-repo/source'],
+    },
+  },
+});
+```

.changeset/social-pigs-search.md

@@ -0,0 +1,5 @@
+---
+'eslint-plugin-skuba': patch
+---
+
+build: Export type declarations

docs/cli/build.md

@@ -84,37 +84,37 @@ In this example, all `*.vocab/*translations.json` files found within `src` will
 
 ## skuba build-package
 
-Compiles your project for compatibility with CommonJS and ES2015 modules.
+Compiles your project with [tsdown] to produce CJS, ESM, and type declaration outputs.
 
 This is useful for building isomorphic npm packages.
 
+`tsdown` selects what ECMAScript target version to build for based on the `engines.node` field in your `package.json`.
+
 ```shell
 skuba build-package
 
-# commonjs │ TSFILE: ...
-# commonjs │ tsc exited with code 0
-# es2015   │ TSFILE: ...
-# es2015   │ tsc exited with code 0
-# types    │ TSFILE: ...
-# types    │ tsc exited with code 0
+# ℹ entry: src/index.ts
+# ℹ target: node22.14.0
+# ℹ [CJS] lib/index.cjs
+# ℹ [CJS] lib/index.d.cts
+# ℹ [ESM] lib/index.mjs
+# ℹ [ESM] lib/index.d.mts
 ```
 
-`skuba build-package` runs operations concurrently up to your [CPU core count].
-On a resource-constrained Buildkite agent,
-you can limit this with the `--serial` flag.
-See our [Buildkite guide] for more information.
-
-To bundle additional assets alongside your package, view the [bundling assets](#bundling-assets) section above.
+Assets can be bundled by configuring the [copy] field in the `tsdown.config.mts` file. Depending on your how your application interprets asset paths, the `unbundle` option may need to be set to `true`.
 
-These files will be copied into the corresponding `lib-commonjs` and `lib-es2015` directories.
+```ts
+import { defineConfig } from 'tsdown/config';
 
-| Option     | Description                                      |
-| :--------- | :----------------------------------------------- |
-| `--serial` | Force serial execution of compilation operations |
+export default defineConfig({
+  unbundle: true,
+  copy: ['**/*.vocab/*translations.json'],
+});
+```
 
 [`skuba configure`]: ./configure.md#skuba-configure
-[buildkite guide]: ../deep-dives/buildkite.md
 [compiler option]: https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options
-[cpu core count]: https://nodejs.org/api/os.html#os_os_cpus
+[copy]: https://tsdown.dev/reference/api/Interface.UserConfig#copy
 [esbuild]: ../deep-dives/esbuild.md
 [tsc]: https://www.typescriptlang.org/docs/handbook/compiler-options.html
+[tsdown]: https://tsdown.dev/

package.json

@@ -77,6 +77,7 @@
     ]
   },
   "dependencies": {
+    "@arethetypeswrong/core": "~0.18.1",
     "@ast-grep/lang-json": "^0.0.6",
     "@ast-grep/napi": "^0.41.0",
     "@esbuild-plugins/tsconfig-paths": "^0.1.0",
@@ -115,6 +116,7 @@
     "picomatch": "^4.0.0",
     "prettier": "~3.8.0",
     "prettier-plugin-packagejson": "^3.0.0",
+    "publint": "~0.3.17",
     "read-pkg-up": "^7.0.1",
     "semantic-release": "^25.0.2",
     "simple-git": "^3.5.0",
@@ -167,6 +169,6 @@
     "entryPoint": "src/index.ts",
     "template": null,
     "type": "package",
-    "version": "14.1.0"
+    "version": "14.1.1"
   }
 }

packages/api/package.json

@@ -11,6 +11,7 @@
     "url": "git+ssh://[email protected]/seek-oss/skuba.git",
     "directory": "packages/api"
   },
+  "license": "MIT",
   "exports": {
     ".": {
       "@seek/skuba/source": "./src/index.ts",

packages/api/tsdown.config.mts

@@ -8,5 +8,10 @@ export default defineConfig({
   exports: {
     devExports: '@seek/skuba/source',
   },
-  failOnWarn: false,
+  inlineOnly: false,
+  checks: {
+    legacyCjs: false,
+  },
+  attw: true,
+  publint: true,
 });

packages/eslint-config-skuba/package.json

@@ -50,6 +50,6 @@
     "entryPoint": "index.js",
     "template": "oss-npm-package",
     "type": "package",
-    "version": "14.1.0"
+    "version": "14.1.1"
   }
 }

packages/eslint-plugin-skuba/package.json

@@ -26,10 +26,7 @@
   "module": "./lib/index.mjs",
   "types": "./lib/index.d.cts",
   "files": [
-    "lib*/**/*.d.ts",
-    "lib*/**/*.js",
-    "lib*/**/*.js.map",
-    "lib*/**/*.mjs"
+    "lib"
   ],
   "scripts": {
     "build": "tsdown",
@@ -72,6 +69,6 @@
     "entryPoint": "src/index.ts",
     "template": "oss-npm-package",
     "type": "package",
-    "version": "14.1.0"
+    "version": "14.1.1"
   }
 }

packages/eslint-plugin-skuba/tsdown.config.mts

@@ -1,11 +1,16 @@
 import { defineConfig } from 'tsdown/config';
 
 export default defineConfig({
+  dts: true,
   entry: ['src/index.ts'],
   exports: {
     devExports: '@seek/skuba/source',
   },
   format: ['cjs', 'esm'],
   outDir: 'lib',
-  failOnWarn: false,
+  checks: {
+    legacyCjs: false,
+  },
+  publint: true,
+  attw: true,
 });

packages/skuba-dive/package.json

@@ -38,6 +38,6 @@
     "entryPoint": "src/index.ts",
     "template": "oss-npm-package",
     "type": "package",
-    "version": "14.1.0"
+    "version": "14.1.1"
   }
 }