@leyman/nx-plugin 0.0.0-stage → 0.1.0

package/dist/lib/targets.js

@@ -0,0 +1,266 @@
+const nodeVersion = {
+    runtime: 'node --version'
+};
+const declarationExtensions = [
+    'd.ts',
+    'd.mts',
+    'd.cts'
+];
+const builtExtensions = [
+    'js',
+    'mjs',
+    'cjs',
+    ...declarationExtensions,
+    'wasm'
+];
+const quote = (argument)=>{
+    if (/^[\w%+,\-.\/:=@\{\}]+$/v.test(argument)) {
+        return argument;
+    }
+    const escaped = argument.replaceAll("'", String.raw`'\''`);
+    return `'${escaped}'`;
+};
+const projectName = '{projectName}';
+const workspaceRoot = '{workspaceRoot}';
+const tsc = '${TSC:-tsc}';
+export const namedInputs = (options)=>{
+    const own = {
+        'dependency-files': [
+            '{projectRoot}/executors.json',
+            '{projectRoot}/*.(c|m)?js',
+            '{projectRoot}/*.d.(c|m)?ts',
+            '{projectRoot}/data/**/*',
+            '{projectRoot}/out/**/*'
+        ],
+        'package-files': [
+            '{projectRoot}/package.json',
+            'dependency-files'
+        ],
+        'eslint-input': [
+            '{projectRoot}/eslint.config.js'
+        ],
+        'ts-source': [
+            nodeVersion,
+            ...options.inputs.configs,
+            ...options.inputs.tools,
+            '{projectRoot}/package.json',
+            '{projectRoot}/tsconfig.json',
+            '{projectRoot}/src/**/*',
+            {
+                externalDependencies: []
+            }
+        ],
+        'dependency-builds': [
+            {
+                dependentTasksOutputFiles: '**/package-surface.json',
+                transitive: true
+            },
+            ...builtExtensions.map((extension)=>({
+                    dependentTasksOutputFiles: `**/dist/**/*.${extension}`,
+                    transitive: true
+                }))
+        ],
+        'test-source': [
+            'ts-source',
+            '{projectRoot}/test/**/*',
+            'package-files',
+            'dependency-builds'
+        ]
+    };
+    return Object.fromEntries(Object.entries(own).map(([name, inputs])=>[
+            name,
+            [
+                ...inputs,
+                ...options.namedInputs[name]
+            ]
+        ]));
+};
+const runCommands = (commands, options = {})=>({
+        executor: 'nx:run-commands',
+        options: {
+            commands,
+            ...options,
+            color: true,
+            cwd: '{projectRoot}'
+        }
+    });
+const scriptFiles = {
+    'biome-format': 'biome-format.sh',
+    'clean-dist': 'clean-dist.sh',
+    'coverage-report': 'coverage-report.sh',
+    'swc-compile': 'swc-compile.sh',
+    'sync-injected': 'sync-injected.mjs'
+};
+const coverageDirectory = `$NX_WORKSPACE_ROOT/.coverage/project/${projectName}/tmp`;
+const testTarget = (kind, command)=>({
+        ...runCommands([
+            `rm -rf ${coverageDirectory}/${kind} && NODE_OPTIONS=--enable-source-maps c8 --temp-directory=${coverageDirectory}/${kind} --src=$NX_WORKSPACE_ROOT --clean=false --reporter=none ${command}`
+        ], {
+            parallel: true
+        }),
+        cache: true,
+        inputs: [
+            'test-source',
+            '^dependency-files'
+        ],
+        outputs: [
+            `${workspaceRoot}/.coverage/project/${projectName}/tmp/${kind}`
+        ]
+    });
+export const targetConfigurations = (options)=>{
+    const { checkPackage, configs, coverage, scripts } = options;
+    const script = (name)=>scripts === undefined ? `leyman-${name}` : `${scripts}/${scriptFiles[name]}`;
+    const thresholds = [
+        'branches',
+        'functions',
+        'lines',
+        'statements'
+    ].map((metric)=>{
+        const threshold = coverage[metric];
+        return threshold === undefined ? '' : ` --${metric} ${threshold}`;
+    }).join('');
+    const checkPackageFlags = [
+        ...checkPackage.profile === undefined ? [] : [
+            ` --profile ${checkPackage.profile}`
+        ],
+        ...checkPackage.floorTsconfig === false ? [] : [
+            ` --floor-tsconfig ${quote(checkPackage.floorTsconfig)}`
+        ]
+    ].join('');
+    return {
+        biome: {
+            ...runCommands([
+                script('biome-format')
+            ]),
+            configurations: {
+                check: {
+                    commands: [
+                        'biome format .'
+                    ]
+                }
+            },
+            cache: false
+        },
+        eslint: {
+            executor: 'nx:run-commands',
+            options: {
+                commands: [
+                    '{projectRoot}/node_modules/.bin/eslint {projectRoot} --color'
+                ],
+                color: true
+            },
+            configurations: {
+                fix: {
+                    fix: true
+                }
+            },
+            cache: true,
+            inputs: [
+                'eslint-input',
+                'ts-source',
+                '{projectRoot}/test/**/*',
+                'package-files',
+                'dependency-builds',
+                '^dependency-files'
+            ],
+            outputs: []
+        },
+        'check-package': {
+            ...runCommands([
+                `check-package${checkPackageFlags}`
+            ]),
+            cache: true,
+            inputs: [
+                nodeVersion,
+                '{projectRoot}/**/*',
+                '!{projectRoot}/CHANGELOG.md',
+                '!{projectRoot}/eslint.config.js',
+                '!{projectRoot}/test/**/*',
+                '{workspaceRoot}/.gitignore',
+                'dependency-builds',
+                ...checkPackage.inputs
+            ],
+            outputs: []
+        },
+        'update-ts-references': {
+            executor: 'nx:noop',
+            syncGenerators: [
+                "@nx/js:typescript-sync"
+            ],
+            cache: true,
+            inputs: [
+                '{projectRoot}/package.json',
+                '{projectRoot}/tsconfig.json'
+            ],
+            outputs: [
+                '{projectRoot}/tsconfig.json'
+            ]
+        },
+        tsc: {
+            ...runCommands([
+                script('clean-dist'),
+                `${script('swc-compile')} ./src ./dist ${quote(configs.swc)}`,
+                tsc
+            ], {
+                parallel: false
+            }),
+            cache: true,
+            inputs: [
+                'ts-source',
+                'dependency-builds',
+                '^dependency-files'
+            ],
+            outputs: [
+                '{projectRoot}/dist'
+            ]
+        },
+        'tsc-test': {
+            ...runCommands([
+                'rm -rf ./dist-test',
+                `${script('swc-compile')} ./test ./dist-test ${quote(configs.swc)}`,
+                `${tsc} -p ./test`
+            ], {
+                parallel: false
+            }),
+            cache: true,
+            inputs: [
+                'test-source',
+                '^dependency-files'
+            ],
+            outputs: [
+                '{projectRoot}/dist-test'
+            ]
+        },
+        'mocha-unit-test': testTarget('unit', 'mocha --recursive "$PWD/dist-test/unit/**/*.spec.*js"'),
+        'mocha-integration-test': testTarget('integration', 'mocha --timeout 10000 --recursive "$PWD/dist-test/integration/**/*.spec.*js"'),
+        'vitest-unit-test': testTarget('unit', `vitest run --config ${quote(configs.vitest)} --root .`),
+        'coverage-report': {
+            ...runCommands([
+                `${script('coverage-report')} ${quote(configs.c8)}${thresholds}`
+            ]),
+            cache: true,
+            inputs: [
+                nodeVersion,
+                'ts-source',
+                {
+                    dependentTasksOutputFiles: '.coverage/project/**/*.json',
+                    transitive: true
+                }
+            ],
+            outputs: [
+                '{workspaceRoot}/.coverage/project/{projectName}/report'
+            ]
+        },
+        'sync-injected': {
+            ...runCommands([
+                script('sync-injected')
+            ]),
+            cache: false,
+            outputs: [
+                '{workspaceRoot}/.package-surface/{projectName}/package-surface.json'
+            ]
+        }
+    };
+};
+
+//# sourceMappingURL=targets.js.map

package/dist/lib/versions.d.ts

@@ -0,0 +1,42 @@
+import type { Tree } from '@nx/devkit';
+type Dependencies = Readonly<Record<string, string>>;
+/**
+ * Where a generator finds the version of a dependency it adds.
+ */
+export interface WorkspaceVersions {
+    /**
+     * Names of the workspace's own packages.
+     */
+    readonly packages: ReadonlySet<string>;
+    /**
+     * Each pnpm catalog, by name, with `default` for `catalog:`.
+     */
+    readonly catalogs: Readonly<Record<string, Dependencies>>;
+    /**
+     * A range a workspace package already depends on each package by.
+     */
+    readonly ranges: ReadonlyMap<string, string>;
+    /**
+     * Versions this plugin was published with, as a last resort.
+     */
+    readonly fallback: Dependencies;
+}
+/**
+ * Reads the workspace's packages, pnpm catalogs and dependency ranges, for {@link resolveVersion}.
+ *
+ * @param tree - Nx's view of the files
+ * @returns the sources `resolveVersion` picks from
+ */
+export declare const readWorkspaceVersions: (tree: Tree) => Promise<WorkspaceVersions>;
+/**
+ * The range to depend on a package by: `workspace:^` for one of the workspace's own, else `catalog:` from the default
+ * catalog, else a range another workspace package uses, else the version this plugin was published with.
+ *
+ * @param name - the package
+ * @param versions - from {@link readWorkspaceVersions}
+ * @returns the range, as `package.json` writes it
+ * @throws {Error} when nothing has a version of the package
+ */
+export declare const resolveVersion: (name: string, versions: WorkspaceVersions) => string;
+export {};
+//# sourceMappingURL=versions.d.ts.map

package/dist/lib/versions.js

@@ -0,0 +1,65 @@
+import { readFile } from 'node:fs/promises';
+import { getProjects, joinPathFragments, readJson } from '@nx/devkit';
+import { parse } from 'yaml';
+const isProtocol = (range)=>/^(?:catalog|workspace):/v.test(range);
+const ownVersions = async ()=>{
+    const path = new URL(import.meta.resolve('@leyman/nx-plugin/package.json'));
+    const { name, version, devDependencies = {} } = JSON.parse(await readFile(path, 'utf8'));
+    return {
+        ...Object.fromEntries(Object.entries(devDependencies).filter(([, range])=>!isProtocol(range))),
+        [name]: `^${version}`
+    };
+};
+export const readWorkspaceVersions = async (tree)=>{
+    const packages = new Set();
+    const ranges = new Map();
+    for (const { root } of getProjects(tree).values()){
+        const path = joinPathFragments(root, 'package.json');
+        if (!tree.exists(path)) {
+            continue;
+        }
+        const packageJson = readJson(tree, path);
+        if (packageJson.name !== undefined) {
+            packages.add(packageJson.name);
+        }
+        const entries = [
+            packageJson.dependencies,
+            packageJson.devDependencies,
+            packageJson.optionalDependencies,
+            packageJson.peerDependencies
+        ].flatMap((field)=>field === undefined ? [] : Object.entries(field));
+        for (const [name, range] of entries){
+            if (!ranges.has(name) && !range.startsWith('workspace:')) {
+                ranges.set(name, range);
+            }
+        }
+    }
+    const workspaceYaml = tree.read('pnpm-workspace.yaml', 'utf8');
+    const { catalog, catalogs } = workspaceYaml === null ? {} : parse(workspaceYaml) ?? {};
+    return {
+        packages,
+        ranges,
+        catalogs: {
+            ...catalogs,
+            ...catalog !== undefined && {
+                default: catalog
+            }
+        },
+        fallback: await ownVersions()
+    };
+};
+export const resolveVersion = (name, versions)=>{
+    if (versions.packages.has(name)) {
+        return 'workspace:^';
+    }
+    if (versions.catalogs.default?.[name] !== undefined) {
+        return 'catalog:';
+    }
+    const range = versions.ranges.get(name) ?? versions.fallback[name];
+    if (range === undefined) {
+        throw new Error(`No version of ${name} in the workspace: add it to the pnpm catalog or to a package first`);
+    }
+    return range;
+};
+
+//# sourceMappingURL=versions.js.map

package/executors.json

@@ -0,0 +1,9 @@
+{
+  "executors": {
+    "targets": {
+      "implementation": "./dist/executors/targets.js",
+      "schema": "./out/executors/targets/schema.json",
+      "description": "Writes the plugin's named inputs and target defaults into nx.json, and the targets each project gets into its project.json."
+    }
+  }
+}

package/generators.json

@@ -0,0 +1,14 @@
+{
+  "generators": {
+    "init": {
+      "factory": "./dist/generators/init.js",
+      "schema": "./out/generators/init/schema.json",
+      "description": "Sets an Nx workspace up for the plugin: nx.json, root devDependencies, the Biome config, pnpm injection and the principles skill."
+    },
+    "package": {
+      "factory": "./dist/generators/package.js",
+      "schema": "./out/generators/package/schema.json",
+      "description": "Adds a TypeScript ESM package, with a project.json declaring the targets the plugin infers."
+    }
+  }
+}

package/out/executors/targets/schema.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "outputCapture": "direct-nodejs",
+  "cli": "nx",
+  "type": "object",
+  "title": "targets",
+  "description": "Writes the plugin's named inputs and target defaults into nx.json, and the targets each project gets into its project.json",
+  "additionalProperties": false,
+  "properties": {
+    "config": {
+      "type": "string",
+      "description": "Path of the file holding the plugin options, relative to the workspace root"
+    },
+    "check": {
+      "type": "boolean",
+      "description": "Fail rather than write when a file is out of date. Defaults to true in CI"
+    }
+  },
+  "required": [
+    "config"
+  ]
+}

package/out/generators/init/schema.json

@@ -0,0 +1,25 @@
+{
+  "cli": "nx",
+  "type": "object",
+  "title": "init",
+  "description": "Sets an Nx workspace up for the plugin: nx.json, root devDependencies, the Biome config, pnpm injection and the principles skill",
+  "additionalProperties": false,
+  "properties": {
+    "lifecycle": {
+      "type": "boolean",
+      "default": true,
+      "description": "Wire the targets' order with nx-lifecycle"
+    },
+    "skill": {
+      "type": "boolean",
+      "default": true,
+      "description": "Write a .claude/skills/principles/SKILL.md pointing coding agents at the principles behind the setup"
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "default": false,
+      "description": "Don't install dependencies afterwards"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema"
+}

package/out/generators/package/schema.json

@@ -0,0 +1,79 @@
+{
+  "cli": "nx",
+  "type": "object",
+  "title": "package",
+  "description": "Adds a TypeScript ESM package, with a project.json declaring the targets the plugin infers",
+  "additionalProperties": false,
+  "properties": {
+    "directory": {
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "Which directory should the package go in?",
+      "type": "string",
+      "description": "Where the package goes, relative to the workspace root"
+    },
+    "name": {
+      "type": "string",
+      "description": "Name of the package. Defaults to the directory's last segment"
+    },
+    "description": {
+      "x-prompt": "What does the package do?",
+      "type": "string",
+      "description": "Description, for package.json and the README"
+    },
+    "published": {
+      "type": "boolean",
+      "default": false,
+      "description": "Published to npm, rather than private"
+    },
+    "floor": {
+      "type": "integer",
+      "default": 22,
+      "description": "Major of the oldest Node.js a published package supports"
+    },
+    "test": {
+      "default": "mocha",
+      "description": "Test runner, or none",
+      "enum": [
+        "mocha",
+        "vitest",
+        "none"
+      ]
+    },
+    "repository": {
+      "type": "string",
+      "description": "URL of the workspace's GitHub repository, for a published package's repository, homepage and bugs"
+    },
+    "author": {
+      "type": "string",
+      "description": "author of package.json"
+    },
+    "license": {
+      "type": "string",
+      "description": "license of package.json. A published package also gets a copy of the workspace's LICENSE"
+    },
+    "devDependencies": {
+      "type": "array",
+      "description": "More packages to add to devDependencies",
+      "items": {
+        "type": "string"
+      }
+    },
+    "config": {
+      "type": "string",
+      "description": "File of the plugin options, relative to the workspace root, for a workspace running the targets executor. Defaults to the options in nx.json"
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "default": false,
+      "description": "Don't install dependencies afterwards"
+    }
+  },
+  "required": [
+    "directory",
+    "description"
+  ],
+  "$schema": "https://json-schema.org/draft/2020-12/schema"
+}