@kubb/ast 5.0.0-beta.1 → 5.0.0-beta.100

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,24 @@
 </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/types`               | Types only: all node interfaces, type aliases, visitor types                                                      |
+| `kubb/kit`                      | Re-exports the `ast` and `factory` namespaces, the way most Kubb code reaches the AST without a direct dependency |
+
+`@kubb/ast` is an internal library. Inside the Kubb ecosystem the whole surface travels on the `ast` namespace from `kubb/kit`, so plugins and generators reach it there instead of depending on this package directly. The examples below import from `@kubb/ast` for clarity; through `kubb/kit` the same calls read as `ast.walk`, `ast.factory.createSchema`, and so on.
 
 ## Node tree
 
@@ -51,10 +60,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',
@@ -79,14 +92,7 @@ const root = createRoot({
 ### Visitor
 
 ```ts
-import { walk, transform, collect } from '@kubb/ast'
-
-// Side effects
-await walk(root, {
-  schema(node) {
-    console.log(node.type)
-  },
-})
+import { collectSync, transform } from '@kubb/ast'
 
 // Immutable transformation
 const updated = transform(root, {
@@ -96,7 +102,7 @@ const updated = transform(root, {
 })
 
 // Extraction
-const types = collect<string>(root, {
+const types = collectSync<string>(root, {
   schema(node) {
     return node.type
   },
@@ -106,11 +112,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 +126,27 @@ function process(node: Node) {
 ### Refs
 
 ```ts
-import { buildRefMap, resolveRef } from '@kubb/ast'
+import { resolveRefName } from '@kubb/ast'
 
-const refMap = buildRefMap(root)
-const pet = resolveRef(refMap, 'Pet')
+resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/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 uses 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 +154,19 @@ Kubb uses an MIT-licensed open source project with its ongoing development made
   </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