@leyman/nx-plugin 0.0.0-stage → 0.1.0

package/dist/lib/projects.js

@@ -0,0 +1,44 @@
+import { access, readFile } from 'node:fs/promises';
+import Path from 'node:path';
+import { inferencePaths } from './infer.js';
+export const readJson = async (path)=>JSON.parse(await readFile(path, 'utf8'));
+const isPresent = async (path)=>{
+    try {
+        await access(path);
+        return true;
+    } catch  {
+        return false;
+    }
+};
+const readJsonIfPresent = async (path)=>await isPresent(path) ? readJson(path) : undefined;
+export const loadProjects = async (workspaceRoot, roots)=>{
+    const loaded = await Promise.all(roots.map(async (root)=>{
+        const projectRoot = Path.join(workspaceRoot, root);
+        const [projectJson, packageJson, present] = await Promise.all([
+            readJsonIfPresent(Path.join(projectRoot, 'project.json')),
+            readJsonIfPresent(Path.join(projectRoot, 'package.json')),
+            Promise.all(inferencePaths.map(async (path)=>isPresent(Path.join(projectRoot, path))))
+        ]);
+        return {
+            root: root.replaceAll(Path.sep, '/'),
+            present: new Set(inferencePaths.filter((_path, i)=>present[i] === true)),
+            projectJson: projectJson,
+            packageJson: packageJson
+        };
+    }));
+    const dependencies = new Set(loaded.flatMap(({ packageJson })=>[
+            packageJson?.dependencies,
+            packageJson?.devDependencies,
+            packageJson?.optionalDependencies,
+            packageJson?.peerDependencies
+        ].flatMap((field)=>Object.keys(field ?? {}))));
+    return loaded.map(({ packageJson, present, projectJson, root })=>({
+            packageJson,
+            projectJson,
+            root,
+            isDependency: packageJson?.name !== undefined && dependencies.has(packageJson.name),
+            has: (path)=>present.has(path)
+        }));
+};
+
+//# sourceMappingURL=projects.js.map

package/dist/lib/schema.d.ts

@@ -0,0 +1,83 @@
+import type { NxPluginOptions } from './options.js';
+/**
+ * JSON schema of the options, for `nx.json` or the file the `targets` executor reads.
+ */
+export declare const optionsJsonSchema: import("juniper").JsonSchema<{
+    targets?: {
+        [x: string]: false | {
+            name?: string;
+            include?: string[];
+            exclude?: string[];
+        } | undefined;
+    };
+    configs?: {
+        swc?: string;
+        c8?: string;
+        vitest?: string;
+    };
+    scripts?: string;
+    coverage?: {
+        branches?: number;
+        functions?: number;
+        lines?: number;
+        statements?: number;
+    };
+    checkPackage?: {
+        profile?: "esm-only" | "node16" | "strict";
+        floorTsconfig?: string | false;
+        inputs?: ((string | import("juniper").EmptyObject) & (string | import("juniper").EmptyObject | undefined))[];
+    };
+    inputs?: {
+        configs?: ((string | import("juniper").EmptyObject) & (string | import("juniper").EmptyObject | undefined))[];
+        tools?: ((string | import("juniper").EmptyObject) & (string | import("juniper").EmptyObject | undefined))[];
+    };
+    namedInputs?: {
+        [x: string]: ((string | import("juniper").EmptyObject) & (string | import("juniper").EmptyObject | undefined))[] | undefined;
+    };
+    $schema?: string;
+}>;
+/**
+ * JSON schema of the `targets` executor's options.
+ */
+export declare const executorJsonSchema: import("juniper").JsonSchema<{
+    config: string;
+    check?: boolean;
+}>;
+/**
+ * Major of the oldest Node.js a package the `package` generator adds supports, unless told otherwise.
+ */
+export declare const defaultFloor = 22;
+/**
+ * JSON schema of the `package` generator's options.
+ */
+export declare const packageGeneratorJsonSchema: import("juniper").JsonSchema<{
+    directory: string;
+    name?: string;
+    description: string;
+    published?: boolean;
+    floor?: number;
+    test?: string;
+    repository?: string;
+    author?: string;
+    license?: string;
+    devDependencies?: string[];
+    config?: string;
+    skipInstall?: boolean;
+}>;
+/**
+ * JSON schema of the `init` generator's options.
+ */
+export declare const initGeneratorJsonSchema: import("juniper").JsonSchema<{
+    lifecycle?: boolean;
+    skill?: boolean;
+    skipInstall?: boolean;
+}>;
+/**
+ * Asserts the plugin options are valid, with each problem in the error's message.
+ *
+ * @param options - the options, from `nx.json` or a file
+ * @param where - where they are from, for the message
+ * @throws {Error} naming each invalid option
+ */
+export declare const assertOptions: (options: unknown, where: string) => asserts options is NxPluginOptions;
+//# sourceMappingURL=schema.d.ts.map

package/dist/lib/schema.js

@@ -0,0 +1,255 @@
+import { arraySchema, booleanSchema, enumSchema, mergeSchema, numberSchema, objectSchema, stringSchema } from 'juniper';
+import { makeValidator } from 'juniper-validator';
+import { namedInputNames, targetNames } from './options.js';
+const inputsSchema = arraySchema(mergeSchema().oneOf([
+    stringSchema({
+        description: 'A file pattern, or the name of a named input'
+    }),
+    objectSchema({
+        description: 'An input object, such as `{ "externalDependencies": ["pkg"] }`'
+    })
+]));
+const rootsSchema = arraySchema(stringSchema({
+    description: 'Root of a project, e.g. `packages/a`'
+}));
+const targetSchema = mergeSchema().oneOf([
+    enumSchema({
+        enum: [
+            false
+        ],
+        description: 'Infer the target nowhere'
+    }),
+    objectSchema({
+        properties: {
+            name: stringSchema({
+                description: "Name of the target. Defaults to the target's own"
+            }),
+            include: rootsSchema.description('Projects that get the target whatever their files'),
+            exclude: rootsSchema.description('Projects that never get the target')
+        },
+        additionalProperties: false
+    })
+]);
+const maxPercent = 100;
+const percentSchema = numberSchema({
+    minimum: 0,
+    maximum: maxPercent
+});
+const optionsProperties = {
+    targets: objectSchema({
+        description: "Each target's options, or `false` to infer it nowhere",
+        properties: Object.fromEntries(targetNames.map((name)=>[
+                name,
+                targetSchema
+            ])),
+        additionalProperties: false
+    }),
+    configs: objectSchema({
+        description: 'Paths of the shared configs, relative to each project',
+        properties: {
+            swc: stringSchema({
+                default: 'node_modules/@leyman/configs/swcrc.jsonc'
+            }),
+            c8: stringSchema({
+                default: 'node_modules/@leyman/configs/c8rc.json'
+            }),
+            vitest: stringSchema({
+                default: 'node_modules/@leyman/configs/vitest.config.js'
+            })
+        },
+        additionalProperties: false
+    }),
+    scripts: stringSchema({
+        description: "Directory to run the plugin's scripts from, instead of the package's bins (`leyman-swc-compile`...)"
+    }),
+    coverage: objectSchema({
+        description: "Coverage thresholds `coverage-report` passes to c8, over the c8 config's",
+        properties: {
+            branches: percentSchema,
+            functions: percentSchema,
+            lines: percentSchema,
+            statements: percentSchema
+        },
+        additionalProperties: false
+    }),
+    checkPackage: objectSchema({
+        description: 'Options of `check-package`',
+        properties: {
+            profile: enumSchema({
+                enum: [
+                    'esm-only',
+                    'node16',
+                    'strict'
+                ],
+                description: 'The module resolutions every entry point must work under'
+            }),
+            floorTsconfig: mergeSchema().oneOf([
+                stringSchema({
+                    description: "The config a package's `tsconfig.json` must extend, with `{major}` for its support floor",
+                    default: '@leyman/configs/tsconfig.node-{major}.json'
+                }),
+                enumSchema({
+                    enum: [
+                        false
+                    ],
+                    description: 'Not checked'
+                })
+            ]),
+            inputs: inputsSchema.description('What a change of check-package itself is hashed by')
+        },
+        additionalProperties: false
+    }),
+    inputs: objectSchema({
+        description: 'What changes of the shared tools are hashed by',
+        properties: {
+            configs: inputsSchema.description('The shared configs, for every target that reads one'),
+            tools: inputsSchema.description("This plugin's scripts, for every target that runs one")
+        },
+        additionalProperties: false
+    }),
+    namedInputs: objectSchema({
+        description: 'Inputs added to the end of each named input, such as a file the tests read',
+        properties: Object.fromEntries(namedInputNames.map((name)=>[
+                name,
+                inputsSchema
+            ])),
+        additionalProperties: false
+    })
+};
+const optionsSchema = objectSchema({
+    title: '@leyman/nx-plugin',
+    description: 'Infers the targets of TypeScript ESM packages',
+    properties: optionsProperties,
+    additionalProperties: false
+});
+export const optionsJsonSchema = optionsSchema.properties({
+    $schema: stringSchema({
+        description: 'Path or URL of this JSON schema'
+    })
+}).toJSON({
+    schema: true
+});
+const executorSchema = objectSchema({
+    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",
+    properties: {
+        config: stringSchema({
+            description: 'Path of the file holding the plugin options, relative to the workspace root'
+        }),
+        check: booleanSchema({
+            description: 'Fail rather than write when a file is out of date. Defaults to true in CI'
+        })
+    },
+    required: [
+        'config'
+    ],
+    additionalProperties: false
+});
+export const executorJsonSchema = executorSchema.metadata({
+    version: 1,
+    outputCapture: 'direct-nodejs',
+    cli: 'nx'
+}).toJSON();
+export const defaultFloor = 22;
+const packageGeneratorSchema = objectSchema({
+    title: 'package',
+    description: 'Adds a TypeScript ESM package, with a project.json declaring the targets the plugin infers',
+    properties: {
+        directory: stringSchema({
+            description: 'Where the package goes, relative to the workspace root'
+        }).metadata({
+            $default: {
+                $source: 'argv',
+                index: 0
+            },
+            'x-prompt': 'Which directory should the package go in?'
+        }),
+        name: stringSchema({
+            description: "Name of the package. Defaults to the directory's last segment"
+        }),
+        description: stringSchema({
+            description: "Description, for package.json and the README"
+        }).metadata('x-prompt', 'What does the package do?'),
+        published: booleanSchema({
+            description: 'Published to npm, rather than private',
+            default: false
+        }),
+        floor: numberSchema({
+            type: 'integer',
+            description: 'Major of the oldest Node.js a published package supports',
+            default: defaultFloor
+        }),
+        test: enumSchema({
+            enum: [
+                'mocha',
+                'vitest',
+                'none'
+            ],
+            description: 'Test runner, or none',
+            default: 'mocha'
+        }),
+        repository: stringSchema({
+            description: "URL of the workspace's GitHub repository, for a published package's repository, homepage and bugs"
+        }),
+        author: stringSchema({
+            description: 'author of package.json'
+        }),
+        license: stringSchema({
+            description: "license of package.json. A published package also gets a copy of the workspace's LICENSE"
+        }),
+        devDependencies: arraySchema(stringSchema()).description('More packages to add to devDependencies'),
+        config: stringSchema({
+            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: booleanSchema({
+            description: "Don't install dependencies afterwards",
+            default: false
+        })
+    },
+    required: [
+        'directory',
+        "description"
+    ],
+    additionalProperties: false
+});
+export const packageGeneratorJsonSchema = packageGeneratorSchema.metadata('cli', 'nx').toJSON({
+    schema: true
+});
+const initGeneratorSchema = objectSchema({
+    title: 'init',
+    description: 'Sets an Nx workspace up for the plugin: nx.json, root devDependencies, the Biome config, pnpm injection and the principles skill',
+    properties: {
+        lifecycle: booleanSchema({
+            description: "Wire the targets' order with nx-lifecycle",
+            default: true
+        }),
+        skill: booleanSchema({
+            description: 'Write a .claude/skills/principles/SKILL.md pointing coding agents at the principles behind the setup',
+            default: true
+        }),
+        skipInstall: booleanSchema({
+            description: "Don't install dependencies afterwards",
+            default: false
+        })
+    },
+    additionalProperties: false
+});
+export const initGeneratorJsonSchema = initGeneratorSchema.metadata('cli', 'nx').toJSON({
+    schema: true
+});
+const optionsValidator = makeValidator(optionsJsonSchema);
+export const assertOptions = (options, where)=>{
+    const { issues } = optionsValidator.validate(options);
+    if (issues === undefined) {
+        return;
+    }
+    throw new Error([
+        `Invalid @leyman/nx-plugin options in ${where}:`,
+        ...issues.map(({ message, path = [] })=>{
+            const at = path.map((key)=>`/${String(key)}`).join('');
+            return `- options${at} ${message}`;
+        })
+    ].join('\n'));
+};
+
+//# sourceMappingURL=schema.js.map

package/dist/lib/sync.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A project of the workspace, as Nx knows it.
+ */
+export interface WorkspaceProject {
+    readonly name: string;
+    /**
+     * Relative to the workspace root.
+     */
+    readonly root: string;
+}
+/**
+ * Writes the plugin's named inputs and target defaults into `nx.json`, and the targets each project gets into its
+ * `project.json`, for a workspace that runs the plugin's targets without loading it as a plugin.
+ *
+ * @param params - what to update, and how
+ * @param params.root - the workspace root
+ * @param params.projects - every project of the workspace
+ * @param params.options - plugin options, not yet validated
+ * @param params.optionsSource - where the options are from, for errors
+ * @param params.check - fail rather than write when a file is out of date
+ * @returns the path of each file written, or that would be
+ * @rejects {Error} when the options are invalid, or a file is out of date in `check` mode
+ */
+export declare const syncTargets: ({ root, projects, options, optionsSource, check, }: {
+    root: string;
+    projects: readonly WorkspaceProject[];
+    options: unknown;
+    optionsSource: string;
+    check: boolean;
+}) => Promise<string[]>;
+//# sourceMappingURL=sync.d.ts.map

package/dist/lib/sync.js

@@ -0,0 +1,109 @@
+import { writeFile } from 'node:fs/promises';
+import Path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { inferTargets } from './infer.js';
+import { namedInputNames, resolveOptions, targetNames } from './options.js';
+import { loadProjects, readJson } from './projects.js';
+import { assertOptions } from './schema.js';
+import { namedInputs, targetConfigurations } from './targets.js';
+const updateKeys = (object, updates, place = (_key, keys)=>keys.at(-1))=>{
+    const keys = Object.keys(object);
+    for (const [key, value] of updates){
+        if (value === undefined || keys.includes(key)) {
+            continue;
+        }
+        const after = place(key, keys);
+        keys.splice(after === undefined ? 0 : keys.indexOf(after) + 1, 0, key);
+    }
+    const entries = keys.map((key)=>[
+            key,
+            updates.has(key) ? updates.get(key) : object[key]
+        ]);
+    return Object.fromEntries(entries.filter(([, value])=>value !== undefined));
+};
+const updateNxJson = (nxJson, options)=>{
+    const inputs = namedInputs(options);
+    const configurations = targetConfigurations(options);
+    const targetDefaults = nxJson.targetDefaults ?? {};
+    const defaults = new Map();
+    for (const target of targetNames){
+        const targetOptions = options.targets[target];
+        if (targetOptions === false) {
+            continue;
+        }
+        const { dependsOn } = targetDefaults[targetOptions.name] ?? {};
+        defaults.set(targetOptions.name, {
+            ...configurations[target],
+            ...dependsOn !== undefined && {
+                dependsOn
+            }
+        });
+    }
+    const ownNamedInputs = new Map(namedInputNames.map((name)=>[
+            name,
+            inputs[name]
+        ]));
+    return updateKeys(nxJson, new Map([
+        [
+            'namedInputs',
+            updateKeys(nxJson.namedInputs ?? {}, ownNamedInputs)
+        ],
+        [
+            'targetDefaults',
+            updateKeys(targetDefaults, defaults)
+        ]
+    ]));
+};
+const updateProjectJson = (projectJson, inferred, options)=>{
+    const targets = projectJson.targets ?? {};
+    const names = targetNames.map((target)=>{
+        const targetOptions = options.targets[target];
+        return targetOptions === false ? target : targetOptions.name;
+    });
+    const updates = new Map();
+    for (const [i, target] of targetNames.entries()){
+        const name = names[i];
+        const current = targets[name];
+        if (inferred.includes(target)) {
+            updates.set(name, current ?? {});
+        } else if (isDeepStrictEqual(current, {})) {
+            updates.set(name, undefined);
+        }
+    }
+    return updateKeys(projectJson, new Map([
+        [
+            'targets',
+            updateKeys(targets, updates, (key, keys)=>names.slice(0, names.indexOf(key)).findLast((name)=>keys.includes(name)))
+        ]
+    ]));
+};
+export const syncTargets = async ({ root, projects, options, optionsSource, check })=>{
+    assertOptions(options, optionsSource);
+    const resolved = resolveOptions(options);
+    const loaded = await loadProjects(root, projects.map((project)=>project.root));
+    const nxJsonPath = Path.join(root, 'nx.json');
+    const nxJson = await readJson(nxJsonPath);
+    const files = [
+        {
+            path: nxJsonPath,
+            current: nxJson,
+            updated: updateNxJson(nxJson, resolved)
+        },
+        ...loaded.filter((project)=>project.projectJson !== undefined).map((project)=>({
+                path: Path.join(root, project.root, 'project.json'),
+                current: project.projectJson,
+                updated: updateProjectJson(project.projectJson, inferTargets(project, resolved), resolved)
+            }))
+    ];
+    const outdated = files.filter(({ current, updated })=>JSON.stringify(current) !== JSON.stringify(updated));
+    if (check && outdated.length > 0) {
+        throw new Error([
+            'Not up to date with @leyman/nx-plugin; run its targets executor:',
+            ...outdated.map(({ path })=>`- ${Path.relative(root, path)}`)
+        ].join('\n'));
+    }
+    await Promise.all(outdated.map(async ({ path, updated })=>writeFile(path, `${JSON.stringify(updated, null, 2)}\n`)));
+    return outdated.map(({ path })=>path);
+};
+
+//# sourceMappingURL=sync.js.map

package/dist/lib/targets.d.ts

@@ -0,0 +1,17 @@
+import type { TargetConfiguration } from '@nx/devkit';
+import type { Input, NamedInputName, ResolvedOptions, TargetName } from './options.js';
+/**
+ * The named inputs the targets use.
+ *
+ * @param options - resolved options
+ * @returns each named input
+ */
+export declare const namedInputs: (options: ResolvedOptions) => Record<NamedInputName, Input[]>;
+/**
+ * How each target runs, without when: the lifecycle's `dependsOn` is nx-lifecycle's to add.
+ *
+ * @param options - resolved options
+ * @returns each target's configuration, by the target's own name
+ */
+export declare const targetConfigurations: (options: ResolvedOptions) => Record<TargetName, TargetConfiguration>;
+//# sourceMappingURL=targets.d.ts.map