@leyman/nx-plugin 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@leyman/nx-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Nx plugin inferring the build, test, lint and package-check targets of TypeScript ESM packages: SWC and tsc builds, Mocha or Vitest under c8, ESLint, Biome and check-package.",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "type": "module",
+  "author": "JacobLey",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JacobLey/leyman.git",
+    "directory": "leyman/nx-plugin"
+  },
+  "homepage": "https://github.com/JacobLey/leyman/tree/main/leyman/nx-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/JacobLey/leyman/issues"
+  },
+  "keywords": [
+    "nx",
+    "nx-plugin",
+    "monorepo",
+    "typescript",
+    "swc",
+    "mocha",
+    "vitest",
+    "c8",
+    "eslint",
+    "biome",
+    "targets"
+  ],
+  "sideEffects": false,
+  "executors": "./executors.json",
+  "generators": "./generators.json",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "leyman-biome-format": "./scripts/biome-format.sh",
+    "leyman-clean-dist": "./scripts/clean-dist.sh",
+    "leyman-coverage-report": "./scripts/coverage-report.sh",
+    "leyman-swc-compile": "./scripts/swc-compile.sh",
+    "leyman-sync-injected": "./scripts/sync-injected.mjs"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/tsconfig.tsbuildinfo",
+    "!dist/file-content.*",
+    "executors.json",
+    "generators.json",
+    "out",
+    "!out/.generated.json",
+    "scripts"
+  ],
+  "imports": {
+    "#internal/*": "./dist/*"
+  },
+  "dependencies": {
+    "@nx/devkit": "^23.3.1",
+    "juniper": "^2.7.0",
+    "juniper-validator": "^0.6.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4",
+    "@leyman/check-package": "^0.1.0",
+    "@leyman/configs": "^0.1.0",
+    "@leyman/eslint-config": "^0.1.0",
+    "@leyman/expect": "^0.1.0",
+    "@nx/js": "^23.3.1",
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.16.20",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.20.5",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "c8": "^12.0.0",
+    "eslint": "^10.13.0",
+    "load-populate-files": "^1.1.5",
+    "mocha": "^12.0.3",
+    "mocha-chain": "^1.1.0",
+    "nx": "^23.3.1",
+    "nx-lifecycle": "^1.2.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^5.0.3"
+  }
 }

package/scripts/biome-format.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Formatting is part of `prepare`, so it rewrites source by default.
+# In CI it only checks, failing if anything was committed unformatted.
+case "${CI:-false}" in
+    false | 0 | "") biome format --write . ;;
+    *) biome format . ;;
+esac

package/scripts/clean-dist.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# Clears ./dist before a build, but keeps what lets `tsc` skip unchanged files: its build info and the declarations.
+# `tsc` trusts the build info without checking its outputs, so a declaration deleted beside a kept build info is
+# never written again, and the build still passes. So they stay together, only while the declarations are exactly
+# those of the current sources. Any difference, such as a deleted source's leftover, clears everything.
+
+set -e
+
+if [ ! -d dist ]; then
+    exit 0
+fi
+
+expected=$(find src -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.mts' -o -name '*.cts' \) \
+    ! -name '*.d.ts' ! -name '*.d.mts' ! -name '*.d.cts' |
+    sed -E 's#^src/##; s#\.tsx?$#.d.ts#; s#\.mts$#.d.mts#; s#\.cts$#.d.cts#' | LC_ALL=C sort)
+actual=$(find dist -type f \( -name '*.d.ts' -o -name '*.d.mts' -o -name '*.d.cts' \) |
+    sed -E 's#^dist/##' | LC_ALL=C sort)
+
+if [ -f dist/tsconfig.tsbuildinfo ] && [ "$expected" = "$actual" ]; then
+    find dist -type f ! -name tsconfig.tsbuildinfo \
+        ! -name '*.d.ts' ! -name '*.d.mts' ! -name '*.d.cts' \
+        ! -name '*.d.ts.map' ! -name '*.d.mts.map' ! -name '*.d.cts.map' -delete
+else
+    rm -rf dist
+fi

package/scripts/coverage-report.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+# Checks a project's coverage from its test targets: leyman-coverage-report <c8rc> [c8 options...].
+
+set -e
+
+config_file=$1
+shift
+
+COVERAGE_DIR="$NX_WORKSPACE_ROOT/.coverage/project/$NX_TASK_TARGET_PROJECT"
+COVERAGE_TMP="$COVERAGE_DIR/report-tmp"
+
+# Each test target writes to its own sub-directory (so they can be cached independently),
+# but c8 only reads the top level of its temp directory, so flatten into a single directory.
+rm -rf "$COVERAGE_TMP"
+mkdir -p "$COVERAGE_TMP"
+find "$COVERAGE_DIR/tmp" -maxdepth 2 -name "*.json" -exec cp {} "$COVERAGE_TMP/" \;
+
+# lcov paths are from the workspace root: Coverage Gutters matches a file by the end of its path, so
+# `src/index.ts`, relative to the package, would show this package's coverage on every package's index.ts.
+c8 --temp-directory="$COVERAGE_TMP" -o "$COVERAGE_DIR/report" -c "$config_file" \
+    --reporter-options.lcovonly.projectRoot="$NX_WORKSPACE_ROOT" report --all --check-coverage --merge-async "$@"

package/scripts/swc-compile.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+
+# Compiles a directory of TypeScript with SWC: leyman-swc-compile <source> <output> <swcrc>.
+# `.mts` and `.cts` need a pass each, for their extension and module type. Starting SWC costs over 100ms,
+# and few packages have either, so those passes only run when there is a file for them.
+#
+# The target follows the oldest Node.js the package supports: the major version of `engines.node` in the current
+# directory's package.json. A floor older than the running Node.js compiles to that version's ES year, so the output
+# runs there; otherwise, or without `engines`, the target is `esnext`.
+
+set -e
+
+source_dir=$1
+output_dir=$2
+config_file=$3
+
+target=$(node -e '
+    const { readFileSync } = require("node:fs");
+    const range = JSON.parse(readFileSync("package.json", "utf8")).engines?.node;
+    const floor = Number(/^>=\s*(\d+)/v.exec(range ?? "")?.[1]);
+    // SWC has no target past es2024 yet
+    const targets = { 22: "es2024" };
+    if (range === undefined || floor >= Number(process.versions.node.split(".")[0])) {
+        console.log("esnext");
+    } else if (floor in targets) {
+        console.log(targets[floor]);
+    } else {
+        console.error(`leyman-swc-compile: no target for engines.node "${range}"; add its floor to the table`);
+        process.exit(1);
+    }
+')
+
+compile() {
+    swc "$source_dir" -d "$output_dir" --config-file "$config_file" \
+        -C "jsc.target=$target" --strip-leading-paths "$@"
+}
+
+has_files() {
+    [ -n "$(find "$source_dir" \( -name "*.$1" -o -name "*.${1}x" \) -print -quit)" ]
+}
+
+compile --only '**/*.ts?(x)'
+
+if has_files mts; then
+    compile --only '**/*.mts?(x)' --out-file-extension mjs
+fi
+
+if has_files cts; then
+    compile -C module.type=commonjs -C module.ignoreDynamic=true -C module.exportInteropAnnotation=true \
+        --only '**/*.cts?(x)' --out-file-extension cjs
+fi

package/scripts/sync-injected.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+// Workspace dependencies are injected (`injectWorkspacePackages`): each dependent gets a copy of the
+// package's published files in the virtual store, made at install time. Those copies don't follow
+// later builds, or Nx restoring `dist/` from cache, so mirror the package into them after every build.
+//
+// Declaration maps aren't published, but each copy gets one pointing back at this package's source,
+// so editors' go-to-definition opens the workspace source instead of the copied `.d.ts`.
+//
+// Never cached: dependents' cache keys hash this package's build output, so they must never run against a stale copy.
+//
+// Also writes the fields of package.json that can affect a dependent, which dependents hash in place of
+// the file, so a version bump or a new description doesn't rerun them. Inert fields are listed rather than
+// consumed ones, so a field nobody thought about still invalidates.
+
+import { execFileSync } from 'node:child_process';
+import {
+    copyFileSync,
+    mkdirSync,
+    readdirSync,
+    readFileSync,
+    rmdirSync,
+    rmSync,
+    statSync,
+    writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+
+const workspaceRoot = process.env.NX_WORKSPACE_ROOT;
+const projectRoot = process.cwd();
+
+const inertFields = new Set([
+    'author',
+    'bugs',
+    'description',
+    'devDependencies',
+    'homepage',
+    'keywords',
+    'license',
+    'repository',
+    'scripts',
+    'version',
+]);
+const packageJson = JSON.parse(readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+const surface = Object.fromEntries(
+    Object.entries(packageJson).filter(([field]) => !inertFields.has(field))
+);
+const surfacePath = path.join(
+    workspaceRoot,
+    '.package-surface',
+    process.env.NX_TASK_TARGET_PROJECT,
+    'package-surface.json'
+);
+mkdirSync(path.dirname(surfacePath), { recursive: true });
+writeFileSync(surfacePath, `${JSON.stringify(surface, null, 2)}\n`);
+
+// Exactly the files pnpm would publish, and so inject
+const { name, files } = JSON.parse(
+    // eslint-disable-next-line sonarjs/no-os-command-from-path -- Run the workspace's pnpm, like Nx itself
+    execFileSync('pnpm', ['pack', '--dry-run', '--json'], { encoding: 'utf8' })
+);
+const packed = new Set(files.map(file => file.path));
+
+// Each copy is named `<name>@file+<path>` by pnpm, with `/` replaced by `+`, plus a suffix for its resolved peers
+const prefix = `${name.replace('/', '+')}@file+${path.relative(workspaceRoot, projectRoot).replaceAll(path.sep, '+')}`;
+const virtualStore = path.join(workspaceRoot, 'node_modules', '.pnpm');
+const copies = readdirSync(virtualStore)
+    .filter(dir => dir === prefix || dir.startsWith(`${prefix}_`))
+    .map(dir => path.join(virtualStore, dir, 'node_modules', name));
+
+const isSameFile = (source, target) => {
+    try {
+        return (
+            statSync(source).size === statSync(target).size &&
+            readFileSync(source).equals(readFileSync(target))
+        );
+    } catch {
+        return false;
+    }
+};
+
+const declarationMaps = [...packed]
+    .filter(file => /\.d\.[cm]?ts$/v.test(file))
+    .map(file => `${file}.map`)
+    .filter(file => {
+        try {
+            return statSync(path.join(projectRoot, file)).isFile();
+        } catch {
+            return false;
+        }
+    });
+const expected = new Set([...packed, ...declarationMaps]);
+
+// Map sources are relative to the map, so re-resolve them from the copy back to this package
+const redirectDeclarationMap = (source, target) => {
+    const map = JSON.parse(readFileSync(source, 'utf8'));
+    const sourceDir = path.resolve(path.dirname(source), map.sourceRoot ?? '');
+    map.sourceRoot = '';
+    map.sources = map.sources.map(file =>
+        path.relative(path.dirname(target), path.resolve(sourceDir, file)).replaceAll(path.sep, '/')
+    );
+    const content = JSON.stringify(map);
+    try {
+        if (readFileSync(target, 'utf8') === content) {
+            return;
+        }
+    } catch {
+        // No map there yet: write it
+    }
+    writeFileSync(target, content);
+};
+
+for (const copy of copies) {
+    const entries = readdirSync(copy, { recursive: true, withFileTypes: true });
+    for (const entry of entries) {
+        const file = path.relative(copy, path.join(entry.parentPath, entry.name));
+        if (!entry.isDirectory() && !expected.has(file)) {
+            rmSync(path.join(copy, file));
+        }
+    }
+    // Deepest first, so a directory emptied by removing its children is removed too
+    const dirs = readdirSync(copy, { recursive: true, withFileTypes: true })
+        .filter(entry => entry.isDirectory())
+        .map(entry => path.join(entry.parentPath, entry.name))
+        .toSorted((a, b) => b.length - a.length);
+    for (const dir of dirs) {
+        if (readdirSync(dir).length === 0) {
+            rmdirSync(dir);
+        }
+    }
+    for (const file of packed) {
+        const source = path.join(projectRoot, file);
+        const target = path.join(copy, file);
+        if (isSameFile(source, target)) {
+            continue;
+        }
+        mkdirSync(path.dirname(target), { recursive: true });
+        copyFileSync(source, target);
+    }
+    for (const file of declarationMaps) {
+        redirectDeclarationMap(path.join(projectRoot, file), path.join(copy, file));
+    }
+}