@zukhruf/nx 0.0.0-stage → 0.3.57

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @zukhruf/nx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package is the Nx part of the monorepo standard. Each workspace copied the same Nx configuration into each project. This package gives that configuration one time, in areas. Each area has its own import path, and the package has no root entry point. Lint stays in `@zukhruf/eslint`, and the Git hooks stay in `@zukhruf/git-hooks`.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Areas
+
+| Area       | Import path          | Status                                                     |
+| ---------- | -------------------- | ---------------------------------------------------------- |
+| format     | `@zukhruf/nx/format` | This README                                                |
+| test       | `@zukhruf/nx/test`   | Planned (#3328): one `node:test` target, copied in 5 repos |
+| generators | —                    | Later, when their own count is due                         |
+
+## format
+
+An Nx workspace formats its files with Prettier. The `format` area is an Nx inference plugin. It gives each project of the workspace two targets: `format`, which writes the files, and `format:check`, which only reads them. You list the plugin one time in `nx.json`. You do not copy targets into each project.
+
+## Use it
+
+You need Nx 23 or 24 and Prettier 3. `nx`, `@nx/devkit` and `prettier` are peer dependencies.
+
+Add the plugin to `plugins` in `nx.json`. Then add `format:check` to the `dependsOn` of `typecheck` that the workspace already has:
+
+```jsonc
+{
+  "plugins": ["@zukhruf/nx/format"],
+  "targetDefaults": {
+    "typecheck": {
+      "dependsOn": ["lint", "format:check", "..."],
+    },
+  },
+}
+```
+
+Keep the entries that are already in the list. A `dependsOn` array replaces the array of an earlier source, and only `"..."` keeps the dependencies that `@nx/js/typescript` gives `typecheck`.
+
+zukhruf builds this package, so it lists the plugin by path: `"plugins": ["./packages/nx/src/format/plugin.ts"]`. The package name resolves to `dist/`, and a fresh clone has no build before Nx makes the project graph.
+
+The plugin does not change `typecheck`. That target belongs to `@nx/js/typescript`, and each workspace adds its own dependencies to it, for example `^sdk`. See [ADR 0001](./docs/adr/0001-inferred-targets-not-copied-defaults.md).
+
+## Signature
+
+```ts
+// @zukhruf/nx/format
+export const createNodes: CreateNodes;
+```
+
+The plugin takes no options. The target names and the commands are the same in each of the 7 copies that this package replaces, so no option is necessary.
+
+## What each target runs
+
+| Target         | Command                          | Writes? | Cached | Inputs                                                                                                                                                                                                                    |
+| -------------- | -------------------------------- | ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `format`       | `prettier --write {projectRoot}` | yes     | no     | —                                                                                                                                                                                                                         |
+| `format:check` | `prettier --check {projectRoot}` | no      | yes    | the files of the project; the root `.prettierignore` and `.editorconfig`; the config file that Prettier finds from the workspace root; `prettier` and each Prettier plugin that the config names (`externalDependencies`) |
+
+- `format` writes. It runs only when you run it on purpose: `nx run <project>:format`. No target depends on it.
+- `format:check` only reads. It fails when a file is not formatted.
+- A project with no file that Prettier can format passes `format:check`. Prettier 3.9.9 passes a folder whose files are all ignored or of an unknown type. It stops with an error only for a folder with no file, and a project root always has a `project.json` or a `package.json`. Thus the command has no `--no-error-on-unmatched-pattern`.
+- The plugin finds the config file with `resolveConfigFile` of Prettier, as the Prettier CLI does. It can be `.prettierrc`, `prettier.config.mjs` or the `prettier` key of the root `package.json`. That file is an input, so a change to it runs the check again. The Prettier CLI also reads `.editorconfig`, so that file is an input too. When Prettier finds no config file, no config file is an input.
+
+To format only your own files, give their paths: `npx prettier --write <files>`. See [ADR 0002](./docs/adr/0002-a-check-never-writes.md).
+
+## Override a project
+
+A target in the `project.json` of a project replaces the inferred target. Nx applies the plugin first, then `targetDefaults`, then `project.json`. For example, the `infra` project of whatisgoingon formats OpenTofu files:
+
+```json
+{
+  "targets": {
+    "format": { "command": "tofu fmt -recursive" },
+    "format:check": { "command": "tofu fmt -check -recursive" }
+  }
+}
+```
+
+## Leave fixtures out
+
+The plugin gives targets only to the projects that Nx finds, by the rule and the matcher of Nx itself:
+
+- Each folder with a `project.json` is a project.
+- A folder with a `package.json` is a project only when the workspace globs of the package manager match its path, or when it has a `project.json` too. The globs are `workspaces` in the root `package.json`, `pnpm-workspace.yaml` and `lerna.json`, with their `!` negations.
+- The workspace root is a project only when it has a `project.json`, or its `package.json` has an `nx` key.
+
+Thus a fixture outside the workspace globs gets no targets, and you do not add it to `exclude`. The root files stay checked by the `Format` step of `@zukhruf/git-hooks` and by `npx prettier --check .` in CI.
+
+A fixture inside the workspace globs is a project of Nx. Use the standard `exclude` of an Nx plugin entry to give it no format targets:
+
+```json
+{
+  "plugins": [
+    {
+      "plugin": "@zukhruf/nx/format",
+      "exclude": ["packages/connectors/manifest/src/fixtures/**"]
+    }
+  ]
+}
+```
+
+context-compiler already does this for `@nx/eslint/plugin`. See [ADR 0003](./docs/adr/0003-which-roots-get-targets.md).
+
+## Migrate a workspace
+
+1. Add the plugin to `plugins` in `nx.json`.
+2. Delete the `format` and `format:check` entries from `targetDefaults`.
+3. Delete each opt-in: each `"format": {}` and each copied `format` or `format:check` target in a `project.json` or in `nx.targets` of a `package.json`. Keep a target only when it is an override.
+4. Delete `"format"` from `lint.dependsOn` and from `typecheck.dependsOn`.
+5. Add `"format:check"` to `typecheck.dependsOn`.
+
+| Workspace        | Today                                                                                        | Opt-ins to delete                  |
+| ---------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
+| zukhruf          | targetDefault `format` = `--write`; `lint` depends on `format`                               | 32 `"format": {}`                  |
+| elt              | same as zukhruf                                                                              | 69                                 |
+| context-compiler | same as zukhruf                                                                              | 27                                 |
+| text2sql         | a full `format` target in each project; `typecheck` depends on `format`                      | 75                                 |
+| factory          | targetDefaults `format` and `format:check`; `typecheck` depends on `lint` and `format:check` | 9 `nx.targets` in `package.json`   |
+| whatisgoingon    | same as factory; `infra` overrides `format` with `tofu fmt`                                  | 3, and `infra` adds `format:check` |
+| deepagents       | one stray `format` target in `packages/compaction`                                           | 1                                  |
+
+## Who uses it
+
+| Workspace        | Backlog item                    |
+| ---------------- | ------------------------------- |
+| zukhruf          | #3306 (phase 2, first consumer) |
+| elt              | #3318                           |
+| context-compiler | #3319                           |
+| factory          | #3320                           |
+| whatisgoingon    | #3321                           |
+| text2sql         | #3322                           |
+| deepagents       | #3323                           |
+
+The umbrella item is #3317.

package/dist/format/plugin.d.ts

@@ -0,0 +1,12 @@
+import { type CreateNodes } from '@nx/devkit';
+/**
+ * Gives each Nx project `format` (writes) and `format:check` (only reads,
+ * cached). Any root that a plugin returns becomes a project, and no plugin
+ * hook receives the projects that Nx found. So the plugin selects roots with
+ * the rule and the matcher of Nx's own package.json plugin: each folder with a
+ * `project.json`, and a `package.json` folder only when the package-manager
+ * workspace globs match it. It returns targets only; the default plugins name
+ * the project.
+ */
+export declare const createNodes: CreateNodes;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/format/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/format/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,YAAY,CAAC;AAOpB;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,WA4CzB,CAAC"}

package/dist/format/plugin.js

@@ -0,0 +1,73 @@
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
+import { createNodesFromFiles, readJsonFile, } from '@nx/devkit';
+import { buildPackageJsonPatterns, buildPackageJsonWorkspacesMatcher, } from '@nx/devkit/internal';
+import { resolveConfig, resolveConfigFile } from 'prettier';
+/**
+ * Gives each Nx project `format` (writes) and `format:check` (only reads,
+ * cached). Any root that a plugin returns becomes a project, and no plugin
+ * hook receives the projects that Nx found. So the plugin selects roots with
+ * the rule and the matcher of Nx's own package.json plugin: each folder with a
+ * `project.json`, and a `package.json` folder only when the package-manager
+ * workspace globs match it. It returns targets only; the default plugins name
+ * the project.
+ */
+export const createNodes = [
+    '{package.json,**/package.json,project.json,**/project.json}',
+    async (configFiles, options, context) => {
+        const projectJsonRoots = new Set(configFiles
+            .filter((file) => basename(file) === 'project.json')
+            .map((file) => dirname(file)));
+        const isInWorkspaces = buildPackageJsonWorkspacesMatcher(buildPackageJsonPatterns(context.workspaceRoot, (file) => readJsonFile(join(context.workspaceRoot, file))));
+        const rootFiles = configFiles.filter((file) => basename(file) === 'project.json'
+            ? true
+            : !projectJsonRoots.has(dirname(file)) && isInWorkspaces(file));
+        const formatCheck = {
+            command: 'prettier --check {projectRoot}',
+            cache: true,
+            inputs: [
+                'default',
+                '{workspaceRoot}/.prettierignore',
+                '{workspaceRoot}/.editorconfig',
+                ...(await prettierConfigInputs(context.workspaceRoot)),
+            ],
+        };
+        return createNodesFromFiles((file) => ({
+            projects: {
+                [dirname(file)]: {
+                    targets: {
+                        format: { command: 'prettier --write {projectRoot}' },
+                        'format:check': formatCheck,
+                    },
+                },
+            },
+        }), rootFiles, options, context);
+    },
+];
+async function prettierConfigInputs(workspaceRoot) {
+    // `resolveConfigFile` gives null when no config file exists
+    // (prettier/index.d.ts:661).
+    const file = await resolveConfigFile(join(workspaceRoot, 'package.json'));
+    if (file === null) {
+        return [{ externalDependencies: ['prettier'] }];
+    }
+    // `resolveConfig` is typed as nullable (prettier/index.d.ts:649-652), and
+    // `Options.plugins` is optional (prettier/index.d.ts:807).
+    const plugins = (await resolveConfig(file, { config: file }))?.plugins ?? [];
+    return [
+        `{workspaceRoot}/${relative(workspaceRoot, file)}`,
+        {
+            externalDependencies: [
+                'prettier',
+                ...plugins
+                    .filter((plugin) => typeof plugin === 'string' &&
+                    !plugin.startsWith('.') &&
+                    !isAbsolute(plugin))
+                    .map((plugin) => plugin
+                    .split('/')
+                    .slice(0, plugin.startsWith('@') ? 2 : 1)
+                    .join('/')),
+            ],
+        },
+    ];
+}
+//# sourceMappingURL=plugin.js.map

package/dist/format/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/format/plugin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@zukhruf/nx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.57",
+  "description": "The Nx part of the monorepo standard. Each area is a subpath. @zukhruf/nx/format is an Nx inference plugin that gives each project two targets: format, which writes the files with Prettier, and format:check, which only reads them and is cached.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/nx"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/nx#readme",
+  "keywords": [
+    "nx",
+    "nx-plugin",
+    "inference",
+    "createNodes",
+    "monorepo",
+    "prettier",
+    "format",
+    "check"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./format": {
+      "@zukhruf/source": "./src/format/plugin.ts",
+      "types": "./dist/format/plugin.d.ts",
+      "import": "./dist/format/plugin.js",
+      "default": "./dist/format/plugin.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nx/devkit": ">=23.0.0 <25.0.0",
+    "nx": ">=23.0.0 <25.0.0",
+    "prettier": "^3.0.0"
+  },
+  "devDependencies": {
+    "@zukhruf/testing": "^0.3.57"
+  }
+}