feat: add schemaName support for OpenAPI spec generation

[andrewzolotukhin]

• Introduced .schemaName() method to schema builders for naming schemas.
• Implemented SchemaRegistry to manage named schemas and prevent conflicts.
• Enhanced generateOpenApiSpec to deduplicate schemas using $ref pointers.
• Added tests for schemaName functionality and registry behavior.
• Updated documentation to reflect new schema naming and deduplication features.

Description

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactor / internal improvement

Checklist

• I've added tests for my changes
• I've run npm run lint and fixed any issues
• I've run npm run test and all tests pass
• I've added a changeset (npx changeset) if this changes package behavior

[Copilot]

Pull request overview

Adds first-class schema naming metadata to @cleverbrush/schema and wires it through @cleverbrush/server-openapi / @cleverbrush/schema-json so OpenAPI generation can deduplicate repeated schema definitions via $ref + components.schemas.

Changes:

• Introduces .schemaName(name) on all schema builders and exposes it via introspect().schemaName.
• Adds SchemaRegistry + walkSchemas() and updates generateOpenApiSpec() to emit components.schemas and $ref pointers.
• Extends toJsonSchema() with a nameResolver hook used to emit $refs, plus docs/tests/website updates.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
website/app/server-openapi/page.tsx	Website docs section describing $ref deduplication via named schemas
website/app/schema/sections/schema-name.tsx	New website docs section for .schemaName()
website/app/schema/sections/index.ts	Adds schema-name to schema docs navigation
website/app/schema/[[...slug]]/page.tsx	Registers SchemaNameSection in routing
website/app/schema-json/page.tsx	Documents nameResolver usage for $ref emission
libs/server-openapi/src/schemaRegistry.ts	Adds SchemaRegistry + walkSchemas() for collecting named schemas
libs/server-openapi/src/schemaRegistry.test.ts	Unit tests for registry behavior and schema walking
libs/server-openapi/src/schemaConverter.ts	Passes registry-backed nameResolver into toJsonSchema()
libs/server-openapi/src/index.ts	Exports registry utilities
libs/server-openapi/src/generateOpenApiSpec.ts	Pre-walks schemas, emits components.schemas, uses $ref in operations
libs/server-openapi/src/generateOpenApiSpec.test.ts	Adds tests for $ref deduplication behavior
libs/server-openapi/README.md	Documents named schema deduplication + registry utilities
libs/schema/src/builders/schemaName.test.ts	Adds runtime + type-level tests for .schemaName()
libs/schema/src/builders/SchemaBuilder.ts	Implements .schemaName() + introspect().schemaName
libs/schema/README.md	Documents .schemaName()
libs/schema-json/src/types.ts	Adds nameResolver option type/docs
libs/schema-json/src/toJsonSchema.ts	Implements nameResolver hook to emit $ref
libs/schema-json/README.md	Documents nameResolver and $ref limitations
.changeset/schema-name-ref-deduplication.md	Changeset for the feature across packages

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.