@kubb/ast 5.0.0-beta.7 → 5.0.0-beta.71

package/LICENSE

@@ -1,14 +1,21 @@
-Copyright (c) 2026 Stijn Van Hulle
-
-This repository contains software under two licenses:
+MIT License
 
-1. Most of the code in this repository is licensed under the
-   MIT License — see licenses/LICENSE-MIT for the full license text.
+Copyright (c) 2026 Stijn Van Hulle
 
-2. The following components are licensed under the
-   GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
-   — see licenses/LICENSE-AGPL-3.0 for the full license text:
+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:
 
-   - packages/agent (published as @kubb/agent)
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-Each package's own LICENSE file or package.json specifies its applicable license.
+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,17 +1,16 @@
 <div align="center">
-  <h1>@kubb/ast</h1>
   <a href="https://kubb.dev" target="_blank" rel="noopener noreferrer">
-    <img width="180" src="https://raw.githubusercontent.com/kubb-labs/kubb/main/assets/logo.png" alt="Kubb logo">
+    <img src="https://kubb.dev/og.png" alt="Kubb banner">
   </a>
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![Coverage][coverage-src]][coverage-href]
+[![Stars][stars-src]][stars-href]
 [![License][license-src]][license-href]
-[![Sponsors][sponsors-src]][sponsors-href]
+[![Node][node-src]][node-href]
 
 <h4>
-<a href="https://kubb.dev/" target="_blank">Documentation</a>
+<a href="https://kubb.dev" target="_blank">Documentation</a>
 <span> · </span>
 <a href="https://github.com/kubb-labs/kubb/issues/" target="_blank">Report Bug</a>
 <span> · </span>
@@ -19,14 +18,23 @@
 </h4>
 </div>
 
-Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, factory functions, and type guards used across codegen plugins.
+<br />
+
+# @kubb/ast
+
+### Spec-agnostic AST layer for Kubb
+
+Defines the node tree, visitor pattern, factory functions, and type guards used across every Kubb code generation plugin.
 
 ## Imports
 
-| Path              | Contents                                                            |
-| ----------------- | ------------------------------------------------------------------- |
-| `@kubb/ast`       | Runtime: factory functions, guards, visitor, ref helpers, constants |
-| `@kubb/ast/types` | Types only: all node interfaces, type aliases, visitor types        |
+| Path                            | Contents                                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `@kubb/ast`                     | Runtime: node definitions, guards, visitor, macro engine, constants                      |
+| `ast.factory` (via `@kubb/ast`) | Node constructors (`createSchema`, `createFile`, and friends), the `ts.factory` analogue |
+| `@kubb/ast/macros`              | Built-in macro presets: `macroDiscriminatorEnum`, `macroSimplifyUnion`, `macroEnumName`  |
+| `@kubb/ast/types`               | Types only: all node interfaces, type aliases, visitor types                             |
+| `@kubb/ast/utils`               | Spec-agnostic string and identifier helpers, ref helpers                                 |
 
 ## Node tree
 
@@ -51,10 +59,14 @@ SchemaNode (discriminated union)
 
 ### Factory
 
+Constructors are available as `ast.factory` from `@kubb/ast`, mirroring `ts.factory.createX`.
+
 ```ts
-import { createRoot, createOperation, createSchema, createProperty } from '@kubb/ast'
+import { ast } from '@kubb/ast'
+
+const { createInput, createSchema, createProperty } = ast.factory
 
-const root = createRoot({
+const root = createInput({
   schemas: [
     createSchema({
       name: 'Pet',
@@ -106,11 +118,11 @@ const types = collect<string>(root, {
 ### Guards
 
 ```ts
-import { isSchemaNode, narrowSchema } from '@kubb/ast'
+import { narrowSchema, schemaDef } from '@kubb/ast'
 import type { Node } from '@kubb/ast/types'
 
 function process(node: Node) {
-  if (isSchemaNode(node)) {
+  if (schemaDef.is(node)) {
     const obj = narrowSchema(node, 'object')
     obj?.properties?.forEach((p) => console.log(p.name))
   }
@@ -120,17 +132,27 @@ function process(node: Node) {
 ### Refs
 
 ```ts
-import { buildRefMap, resolveRef } from '@kubb/ast'
+import { extractRefName } from '@kubb/ast/utils'
 
-const refMap = buildRefMap(root)
-const pet = resolveRef(refMap, 'Pet')
+extractRefName('#/components/schemas/Pet') // 'Pet'
 ```
 
+## Adding a node
+
+Adding a node touches three files. The barrels and visitor tables derive the rest.
+
+1. Define the node in its own `src/nodes/*.ts` file. Call `defineNode` and export the resulting `fooDef`, the `createFoo` constructor, and the node's type.
+2. Add `fooDef` to the `nodeDefs` array in `src/registry.ts`.
+3. Re-export `createFoo` from `src/factory.ts`.
+
+Everything else follows from there. `@kubb/ast/types` picks up the node type through `export type *`, the `@kubb/ast` barrel picks up `fooDef` through `export * from './registry.ts'`, and the visitor tables (`VISITOR_KEYS`, `VISITOR_KEY_BY_KIND`, `nodeRebuilders`) come from the def's `children`, `visitorKey`, and `rebuild` fields. `registry.test.ts` fails when a def has no matching `factory.create*`, so missing wiring is caught in CI.
+
 ## Supporting Kubb
 
-Kubb is an MIT-licensed open source project with its ongoing development made possible entirely by the support of Sponsors. If you would like to become a sponsor, please consider:
+Kubb is an open source project, and its development is funded entirely by sponsors. If you would like to become a sponsor, please consider:
 
 - [Become a Sponsor on GitHub](https://github.com/sponsors/stijnvanhulle)
+- [See sponsorship tiers and our sponsors](https://kubb.dev/sponsors)
 
 <p align="center">
   <a href="https://github.com/sponsors/stijnvanhulle">
@@ -138,15 +160,19 @@ Kubb is an MIT-licensed open source project with its ongoing development made po
   </a>
 </p>
 
+## License
+
+[MIT](https://github.com/kubb-labs/kubb/blob/main/licenses/LICENSE-MIT)
+
 <!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/@kubb/ast?flat&colorA=18181B&colorB=f58517
-[npm-version-href]: https://npmjs.com/package/@kubb/ast
-[npm-downloads-src]: https://img.shields.io/npm/dm/@kubb/ast?flat&colorA=18181B&colorB=f58517
-[npm-downloads-href]: https://npmjs.com/package/@kubb/ast
-[license-src]: https://img.shields.io/github/license/kubb-labs/kubb.svg?flat&colorA=18181B&colorB=f58517
+[npm-version-src]: https://shieldcn.dev/npm/v/@kubb/ast.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[npm-version-href]: https://npmx.dev/package/@kubb/ast
+[npm-downloads-src]: https://shieldcn.dev/npm/dm/@kubb/ast.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[npm-downloads-href]: https://npmx.dev/package/@kubb/ast
+[stars-src]: https://shieldcn.dev/github/stars/kubb-labs/kubb.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[stars-href]: https://github.com/kubb-labs/kubb
+[license-src]: https://shieldcn.dev/npm/license/@kubb/ast.svg?variant=secondary&size=xs&theme=zinc
 [license-href]: https://github.com/kubb-labs/kubb/blob/main/LICENSE
-[coverage-src]: https://img.shields.io/codecov/c/github/kubb-labs/kubb?style=flat&colorA=18181B&colorB=f58517
-[coverage-href]: https://www.npmjs.com/package/@kubb/ast
-[sponsors-src]: https://img.shields.io/github/sponsors/stijnvanhulle?style=flat&colorA=18181B&colorB=f58517
-[sponsors-href]: https://github.com/sponsors/stijnvanhulle/
+[node-src]: https://shieldcn.dev/npm/node/@kubb/ast.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[node-href]: https://npmx.dev/package/@kubb/ast

package/dist/defineMacro-5Dvct8k_.cjs

@@ -0,0 +1,114 @@
+const require_visitor = require("./visitor-CQdSiClY.cjs");
+//#region src/defineMacro.ts
+/**
+* Sort weight for an `enforce` hint. `pre` sorts before unmarked items and `post` after, so a plain
+* list keeps its authored order.
+*/
+function enforceWeight(enforce) {
+	if (enforce === "pre") return 0;
+	if (enforce === "post") return 2;
+	return 1;
+}
+/**
+* Types a macro for inference and a single construction site, mirroring `definePlugin`.
+* Adds no runtime behavior.
+*
+* @example
+* ```ts
+* const macroUntagged = defineMacro({
+*   name: 'untagged',
+*   operation(node) {
+*     return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }
+*   },
+* })
+* ```
+*/
+function defineMacro(macro) {
+	return macro;
+}
+/**
+* Runs every macro's callback for one node kind in order, chaining the result so each macro sees
+* the previous macro's output. Returns `undefined` when nothing changed, so `transform` keeps the
+* original reference (structural sharing).
+*/
+function chain({ macros, key, node, context }) {
+	let current = node;
+	for (const macro of macros) {
+		const callback = macro[key];
+		if (!callback) continue;
+		if (macro.when && !macro.when(current)) continue;
+		const next = callback(current, context);
+		if (next != null) current = next;
+	}
+	return current === node ? void 0 : current;
+}
+/**
+* Folds an ordered list of macros into a single {@link Visitor} that `transform` (and the per-plugin
+* transform layer in `@kubb/core`) can run. Macros are stable-sorted by `enforce`, then applied
+* sequentially per node so later macros see earlier output. This differs from a plain visitor, which
+* has no names, ordering, or composition.
+*
+* @example
+* ```ts
+* const visitor = composeMacros([macroSimplifyUnion, macroDiscriminatorEnum])
+* const next = transform(root, visitor)
+* ```
+*/
+function composeMacros(macros) {
+	const ordered = [...macros].sort((a, b) => enforceWeight(a.enforce) - enforceWeight(b.enforce));
+	const visitor = {};
+	for (const key of require_visitor.visitorKeys) {
+		if (!ordered.some((macro) => typeof macro[key] === "function")) continue;
+		const callback = (node, context) => chain({
+			macros: ordered,
+			key,
+			node,
+			context
+		});
+		visitor[key] = callback;
+	}
+	return visitor;
+}
+/**
+* Runs a list of macros over a node tree and returns the rewritten tree. Keeps `transform`'s
+* structural sharing, so an empty or no-op macro list returns the same reference. Pass
+* `depth: 'shallow'` to rewrite the root node only.
+*
+* @example
+* ```ts
+* const next = applyMacros(root, [macroIntegerToString])
+* ```
+*
+* @example Apply to the root node only
+* ```ts
+* const named = applyMacros(node, [macroEnumName({ parentName, propName, enumSuffix })], { depth: 'shallow' })
+* ```
+*/
+function applyMacros(root, macros, options) {
+	if (macros.length === 0) return root;
+	return require_visitor.transform(root, {
+		...composeMacros(macros),
+		...options
+	});
+}
+//#endregion
+Object.defineProperty(exports, "applyMacros", {
+	enumerable: true,
+	get: function() {
+		return applyMacros;
+	}
+});
+Object.defineProperty(exports, "composeMacros", {
+	enumerable: true,
+	get: function() {
+		return composeMacros;
+	}
+});
+Object.defineProperty(exports, "defineMacro", {
+	enumerable: true,
+	get: function() {
+		return defineMacro;
+	}
+});
+
+//# sourceMappingURL=defineMacro-5Dvct8k_.cjs.map

package/dist/defineMacro-5Dvct8k_.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineMacro-5Dvct8k_.cjs","names":["visitorKeys","transform"],"sources":["../src/defineMacro.ts"],"sourcesContent":["import type { VisitorDepth } from './constants.ts'\nimport type { VisitorKey } from './defineNode.ts'\nimport { visitorKeys } from './defineNode.ts'\nimport type { Node } from './nodes/index.ts'\nimport type { Visitor, VisitorContext } from './visitor.ts'\nimport { transform } from './visitor.ts'\n\n/**\n * Ordering hint shared by macros and plugins. `pre` runs before unmarked items, `post` after,\n * and `undefined` keeps declaration order.\n */\nexport type Enforce = 'pre' | 'post'\n\n/**\n * Sort weight for an `enforce` hint. `pre` sorts before unmarked items and `post` after, so a plain\n * list keeps its authored order.\n */\nfunction enforceWeight(enforce?: Enforce): number {\n  if (enforce === 'pre') return 0\n  if (enforce === 'post') return 2\n  return 1\n}\n\n/**\n * A named, composable transform over the Kubb AST. It carries the same per-kind callbacks as a\n * {@link Visitor} (`schema`, `operation`, …), plus a `name`, an optional `enforce` order, and an\n * optional `when` gate. Macros run on the shared AST, so the same macro works across every adapter\n * and output target. Exports follow the `macro<Name>` convention, mirroring plugins (`pluginTs`).\n */\nexport type Macro = Visitor & {\n  /**\n   * Macro identifier used to tell macros apart, for example `'simplify-union'`.\n   */\n  name: string\n  /**\n   * Ordering hint. `pre` macros run before unmarked macros, `post` macros run after.\n   * Ordering within a bucket follows list order.\n   */\n  enforce?: Enforce\n  /**\n   * Gate checked against the current node before any callback runs. When it returns `false`\n   * the macro is skipped for that node.\n   */\n  when?: (node: Node) => boolean\n}\n\n/**\n * Types a macro for inference and a single construction site, mirroring `definePlugin`.\n * Adds no runtime behavior.\n *\n * @example\n * ```ts\n * const macroUntagged = defineMacro({\n *   name: 'untagged',\n *   operation(node) {\n *     return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }\n *   },\n * })\n * ```\n */\nexport function defineMacro(macro: Macro): Macro {\n  return macro\n}\n\ntype MacroCallback = (node: Node, context: VisitorContext) => Node | null | undefined\n\ntype ChainProps = {\n  macros: ReadonlyArray<Macro>\n  key: VisitorKey\n  node: Node\n  context: VisitorContext\n}\n\n/**\n * Runs every macro's callback for one node kind in order, chaining the result so each macro sees\n * the previous macro's output. Returns `undefined` when nothing changed, so `transform` keeps the\n * original reference (structural sharing).\n */\nfunction chain({ macros, key, node, context }: ChainProps): Node | undefined {\n  let current = node\n\n  for (const macro of macros) {\n    const callback = macro[key] as MacroCallback | undefined\n    if (!callback) continue\n    if (macro.when && !macro.when(current)) continue\n\n    const next = callback(current, context)\n    if (next != null) current = next\n  }\n\n  return current === node ? undefined : current\n}\n\n/**\n * Folds an ordered list of macros into a single {@link Visitor} that `transform` (and the per-plugin\n * transform layer in `@kubb/core`) can run. Macros are stable-sorted by `enforce`, then applied\n * sequentially per node so later macros see earlier output. This differs from a plain visitor, which\n * has no names, ordering, or composition.\n *\n * @example\n * ```ts\n * const visitor = composeMacros([macroSimplifyUnion, macroDiscriminatorEnum])\n * const next = transform(root, visitor)\n * ```\n */\nexport function composeMacros(macros: ReadonlyArray<Macro>): Visitor {\n  const ordered = [...macros].sort((a, b) => enforceWeight(a.enforce) - enforceWeight(b.enforce))\n\n  const visitor: Visitor = {}\n  for (const key of visitorKeys) {\n    if (!ordered.some((macro) => typeof macro[key] === 'function')) continue\n\n    const callback = (node: Node, context: VisitorContext) => chain({ macros: ordered, key, node, context })\n    ;(visitor as Record<VisitorKey, MacroCallback>)[key] = callback\n  }\n\n  return visitor\n}\n\n/**\n * Runs a list of macros over a node tree and returns the rewritten tree. Keeps `transform`'s\n * structural sharing, so an empty or no-op macro list returns the same reference. Pass\n * `depth: 'shallow'` to rewrite the root node only.\n *\n * @example\n * ```ts\n * const next = applyMacros(root, [macroIntegerToString])\n * ```\n *\n * @example Apply to the root node only\n * ```ts\n * const named = applyMacros(node, [macroEnumName({ parentName, propName, enumSuffix })], { depth: 'shallow' })\n * ```\n */\nexport function applyMacros<TNode extends Node>(root: TNode, macros: ReadonlyArray<Macro>, options?: { depth?: VisitorDepth }): TNode {\n  if (macros.length === 0) return root\n\n  return transform(root, { ...composeMacros(macros), ...options }) as TNode\n}\n"],"mappings":";;;;;;AAiBA,SAAS,cAAc,SAA2B;CAChD,IAAI,YAAY,OAAO,OAAO;CAC9B,IAAI,YAAY,QAAQ,OAAO;CAC/B,OAAO;AACT;;;;;;;;;;;;;;;AAuCA,SAAgB,YAAY,OAAqB;CAC/C,OAAO;AACT;;;;;;AAgBA,SAAS,MAAM,EAAE,QAAQ,KAAK,MAAM,WAAyC;CAC3E,IAAI,UAAU;CAEd,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,WAAW,MAAM;EACvB,IAAI,CAAC,UAAU;EACf,IAAI,MAAM,QAAQ,CAAC,MAAM,KAAK,OAAO,GAAG;EAExC,MAAM,OAAO,SAAS,SAAS,OAAO;EACtC,IAAI,QAAQ,MAAM,UAAU;CAC9B;CAEA,OAAO,YAAY,OAAO,KAAA,IAAY;AACxC;;;;;;;;;;;;;AAcA,SAAgB,cAAc,QAAuC;CACnE,MAAM,UAAU,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,GAAG,MAAM,cAAc,EAAE,OAAO,IAAI,cAAc,EAAE,OAAO,CAAC;CAE9F,MAAM,UAAmB,CAAC;CAC1B,KAAK,MAAM,OAAOA,gBAAAA,aAAa;EAC7B,IAAI,CAAC,QAAQ,MAAM,UAAU,OAAO,MAAM,SAAS,UAAU,GAAG;EAEhE,MAAM,YAAY,MAAY,YAA4B,MAAM;GAAE,QAAQ;GAAS;GAAK;GAAM;EAAQ,CAAC;EACtG,QAA+C,OAAO;CACzD;CAEA,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,SAAgB,YAAgC,MAAa,QAA8B,SAA2C;CACpI,IAAI,OAAO,WAAW,GAAG,OAAO;CAEhC,OAAOC,gBAAAA,UAAU,MAAM;EAAE,GAAG,cAAc,MAAM;EAAG,GAAG;CAAQ,CAAC;AACjE"}