@sanity/agent-schema 0.0.1 → 0.0.3

package/README.md

@@ -1,14 +1,16 @@
 # @sanity/agent-schema
 
-Schema processing utilities for Sanity Agent. Parses Lexicon schemas, compresses them for LLM context, provides full JSON views for schema explorers, and navigates schema trees for validation and mutation agents.
+Schema utilities for Sanity Agent. Fetches Lexicon schemas, compresses them for LLM context windows, provides full JSON views for schema explorers, and resolves field definitions for validation and mutation agents.
 
 ## Install
 
-```bash
-pnpm add @sanity/agent-schema
+```sh
+pnpm add @sanity/agent-schema @sanity/client groq-js
 ```
 
-## Quick start
+## Getting started
+
+The most common workflow: fetch a schema, optionally enrich it with dataset stats, and compress it into text for an LLM.
 
 ```ts
 import {
@@ -17,10 +19,13 @@ import {
   compressedSchema,
 } from "@sanity/agent-schema";
 
-// 1. Fetch and parse the schema
+// 1. Fetch and parse the schema from Lexicon
+//    The `lexiconClient` should target the Lexicon API host.
+//    `descriptorId` identifies a specific schema version (typically from an application resource).
 const types = await fetchSchemaByDescriptorId(lexiconClient, descriptorId);
 
-// 2. Optionally fetch dataset stats (enriches output with counts)
+// 2. Optionally fetch dataset stats (document/reference counts)
+//    The `agentClient` should target the agent API host with `useProjectHostname: false`.
 const statsResult = await fetchDatasetStats(agentClient, {
   organizationId,
   projectId,
@@ -34,7 +39,128 @@ const text = await compressedSchema(types, {
 });
 ```
 
-## API
+The result is a compact text summary of your document types, fields, references, and counts — ready to drop into an LLM system prompt.
+
+## Usage
+
+### Compress a schema for LLM context
+
+`compressedSchema` is the main entry point for generating LLM-ready text. It accepts parsed schema types and returns a compact summary.
+
+```ts
+import { compressedSchema } from "@sanity/agent-schema";
+
+// Filter by GROQ expression
+const text = await compressedSchema(types, {
+  filter: { read: '_type in ["post", "author"]' },
+});
+
+// Filter by explicit type list
+const text = await compressedSchema(types, {
+  filter: ["post", "author"],
+});
+
+// All options
+const text = await compressedSchema(types, {
+  filter: { read: '_type == "post"', write: '_type == "draft"' },
+  datasetStats,
+  fields: { maxCount: 5, includeDescription: true },
+});
+```
+
+### Browse full schema JSON
+
+`fullSchema` returns the complete JSON structure of a type — every field, nested object, validation rule, and option. Used by schema explorer tools.
+
+```ts
+import { fullSchema } from "@sanity/agent-schema";
+
+// Get the entire type
+fullSchema(types, { type: "post" });
+// => { name: "post", type: "document", fields: [...] }
+
+// Zoom into a specific field path
+fullSchema(types, { type: "post", path: "content[].codeBlock" });
+// => { name: "codeBlock", type: "object", fields: [...] }
+```
+
+Large types automatically return a navigator object with child paths to drill into, instead of blowing up the response. Control this with `sizeThreshold` (default 200KB).
+
+### Resolve a field at a path
+
+`resolveFieldSchema` answers "what type is the value at this path?" — used by validators and mutation code.
+
+```ts
+import { resolveFieldSchema } from "@sanity/agent-schema";
+
+resolveFieldSchema("content[0].text", postSchema, allTypes);
+// => { name: "text", type: "string" }
+
+resolveFieldSchema("tags", postSchema, allTypes);
+// => { name: "tags", type: "array", of: [...] }
+
+resolveFieldSchema("nonexistent.path", postSchema, allTypes);
+// => null
+```
+
+For union arrays where the same path exists in multiple item types, use `resolveFieldSchemaAllUnions` to get all matches:
+
+```ts
+import { resolveFieldSchemaAllUnions } from "@sanity/agent-schema";
+
+resolveFieldSchemaAllUnions("content", postSchema, allTypes);
+// => [blockSchema, imageSchema, codeSchema]
+```
+
+### Process schema for custom tooling
+
+`processSchema` is the core transformation step. It categorizes types, expands inline object references, computes bidirectional reference graphs, and identifies title fields. This is what `compressedSchema` uses internally.
+
+```ts
+import { processSchema } from "@sanity/agent-schema";
+
+const { documentTypes, objectTypes } = processSchema(types, {
+  filter: ["post", "author"],
+});
+
+// documentTypes: Map<string, ProcessedDocumentType>
+// objectTypes: Map<string, ManifestSchemaType>
+
+for (const [name, doc] of documentTypes) {
+  console.log(doc.titleField); // "title"
+  console.log(doc.outgoingReferences); // ["author", "category"]
+  console.log(doc.incomingReferences); // ["comment"]
+  console.log(doc.outgoingReferencePaths); // [{ type: "author", path: "author" }]
+}
+```
+
+Use this when you need the processed data structures without the text formatting — for custom schema visualizations, reference analysis, or building infrastructure like document counters.
+
+## Architecture
+
+```
+fetchSchemaByDescriptorId()                fetchDatasetStats()
+         │                                          │
+         ▼                                          ▼
+  ManifestSchemaType[]                      DatasetStatsResult
+         │                                          │
+         ├──► compressedSchema()  ◄─────────────────┘
+         │        ──► text summary of all types
+         │
+         ├──► fullSchema()
+         │        ──► JSON subtree of one type (all fields expanded)
+         │
+         ├──► resolveFieldSchema()
+         │        ──► single field definition at a path
+         │
+         ├──► resolveFieldSchemaAllUnions()
+         │        ──► same, all union branches
+         │
+         └──► processSchema()
+                  ──► categorize types, expand fields, compute refs
+```
+
+## API reference
 
 ### Fetch
 
@@ -42,11 +168,13 @@ const text = await compressedSchema(types, {
 
 Fetches a schema from the Lexicon API and returns parsed `ManifestSchemaType[]`.
 
+The `client` should be a `@sanity/client` instance configured for the Lexicon API host. The `descriptorId` identifies a specific schema version — typically obtained from an application resource.
+
 ```ts
 const types = await fetchSchemaByDescriptorId(client, descriptorId);
 ```
 
-Enable caching with `{ cache: true }` (in-memory, 5 min TTL) or a custom adapter:
+**Caching:** Pass `{ cache: true }` for a built-in in-memory cache (5 min TTL), or provide a custom adapter:
 
 ```ts
 // Built-in memory cache
@@ -61,9 +189,16 @@ const types = await fetchSchemaByDescriptorId(client, id, {
 });
 ```
 
+| Option  | Type                     | Default  | Description                                               |
+| ------- | ------------------------ | -------- | --------------------------------------------------------- |
+| `cache` | `boolean \| SchemaCache` |          | Enable caching. `true` for in-memory, or a custom adapter |
+| `ttlMs` | `number`                 | `300000` | Cache TTL in ms (only applies to built-in memory cache)   |
+
 #### `fetchDatasetStats(client, options)`
 
-Fetches document and reference counts from the agent API. Returns `{ status: 'ready', stats }` or `{ status: 'processing' }` if still being computed.
+Fetches document and reference counts from the agent API. Returns `{ status: 'ready', stats }` or `{ status: 'processing' }` if stats are still being computed.
+
+The `client` should be configured to point at the agent API host (e.g. `api.sanity.io`) with `useProjectHostname: false`.
 
 ```ts
 const result = await fetchDatasetStats(client, {
@@ -82,28 +217,7 @@ if (result.status === "ready") {
 
 #### `compressedSchema(types, options?)`
 
-The main entry point. Takes parsed types and returns compact text for agents.
-
-The `filter` option controls which document types to include. Pass a GROQ filter (requires `groq-js` peer dep) or an explicit list of type names:
-
-```ts
-// GROQ filter — types are inferred from the expression
-await compressedSchema(types, {
-  filter: { read: '_type in ["post", "author"]' },
-});
-
-// Explicit type list
-await compressedSchema(types, {
-  filter: ["post", "author"],
-});
-
-// All options
-await compressedSchema(types, {
-  filter: { read: '_type == "post"', write: '_type == "draft"' },
-  datasetStats,
-  fields: { maxCount: 5, includeDescription: true },
-});
-```
+Generates compressed text for agent consumption. Processes the schema, applies filters, and formats the output.
 
 | Option         | Type                        | Description                                   |
 | -------------- | --------------------------- | --------------------------------------------- |
@@ -127,78 +241,76 @@ await compressedSchema(types, {
 
 #### `fullSchema(types, options)`
 
-Returns a **JSON subtree** of a schema type — everything inside it (all fields, nested objects, validation rules, options). Used by schema explorer tools to let the LLM browse type structures.
+Returns the complete JSON structure for a schema type, optionally scoped to a field path.
 
-Without `path`, you get the entire type. With `path`, you get the subtree rooted at that field — still the full structure from that point down, just scoped to a smaller starting point. This is useful because some types are huge; `path` lets you zoom in.
+Without `path`, you get the entire type. With `path`, you get the subtree rooted at that field. This is useful because some types are huge — `path` lets you zoom in without fetching the whole thing.
 
-```ts
-import { fullSchema } from "@sanity/agent-schema";
+When the output exceeds `sizeThreshold`, a navigator object is returned instead with child paths to drill into:
 
-fullSchema(types, { type: "post" });
-// Returns: { name: "post", type: "document", fields: [
-//   { name: "title", type: "string" },
-//   { name: "content", type: "array", of: [
-//     { name: "block", type: "block", marks: {...}, styles: [...], ... },
-//     { name: "codeBlock", type: "object", fields: [
-//       { name: "language", type: "string", options: { list: [...] } },
-//       { name: "code", type: "text" },
-//     ]},
-//   ]},
-//   ... every field, fully expanded ...
-// ]}
-
-// Same structure, just starting from content[].codeBlock instead of the root
-fullSchema(types, { type: "post", path: "content[].codeBlock" });
-// Returns: { name: "codeBlock", type: "object", fields: [
-//   { name: "language", type: "string", options: { list: [...] } },
-//   { name: "code", type: "text" },
-// ]}
+```ts
+// Navigator shape (returned when output is too large)
+{
+  _rawLargeNode: true,
+  name: "post",
+  type: "document",
+  children: [
+    { type: "array", path: "content[]" },
+    { type: "object", path: "metadata" },
+  ],
+  hint: "This node is large. Fetch a specific child path to drill in."
+}
 ```
 
-If the output exceeds `sizeThreshold`, a navigator object is returned instead with child paths to drill into.
-
 | Option          | Type     | Default  | Description                                           |
 | --------------- | -------- | -------- | ----------------------------------------------------- |
 | `type`          | `string` | required | Document type name to return                          |
 | `path`          | `string` |          | Field path — returns the subtree from this point down |
 | `sizeThreshold` | `number` | `200KB`  | Byte limit before returning a navigator instead       |
 
-### Navigate
+### Process
 
-#### `resolveFieldSchema(path, typeSchema, schema)`
+#### `processSchema(types, options?)`
+
+Processes raw `ManifestSchemaType[]` into categorized, enriched data structures. This is the core transformation that `compressedSchema` uses internally.
 
-Returns the **single field definition** at the end of a path. No subtree, no nested fields — just the node itself. Used by validators and mutation code that need to answer "what type is the value at this path?"
+Returns a `SchemaTypes` object:
 
 ```ts
-import { resolveFieldSchema } from "@sanity/agent-schema";
+type SchemaTypes = {
+  documentTypes: Map<string, ProcessedDocumentType>;
+  objectTypes: Map<string, ManifestSchemaType>;
+};
+```
 
-resolveFieldSchema("content[0].text", postSchema, allTypes);
-// Returns: { name: "text", type: "string" }
-//
-// Compare with fullSchema — that would return the entire content array
-// with all its item types expanded. This just tells you "it's a string."
+Each `ProcessedDocumentType` contains:
+
+| Property                 | Type               | Description                        |
+| ------------------------ | ------------------ | ---------------------------------- |
+| `name`                   | `string`           | Document type name                 |
+| `title`                  | `string?`          | Human-readable title               |
+| `description`            | `string?`          | Type description                   |
+| `deprecated`             | `object?`          | Deprecation info with reason       |
+| `titleField`             | `string`           | Best candidate for display title   |
+| `fields`                 | `ManifestField[]`  | Expanded field definitions         |
+| `outgoingReferences`     | `string[]`         | Types this document references     |
+| `incomingReferences`     | `string[]`         | Types that reference this document |
+| `outgoingReferencePaths` | `ReferenceInfo[]?` | Outgoing refs with field paths     |
+| `incomingReferencePaths` | `ReferenceInfo[]?` | Incoming refs with field paths     |
+
+| Option   | Type                        | Description                             |
+| -------- | --------------------------- | --------------------------------------- |
+| `filter` | `SchemaFilter`              | GROQ filter or `string[]` of type names |
+| `fields` | `SchemaFieldDisplayOptions` | Field display options                   |
 
-resolveFieldSchema("tags", postSchema, allTypes);
-// Returns: { name: "tags", type: "array", of: [...] }
-//
-// You get the field node, not the expanded contents of every array item.
+### Navigate
 
-resolveFieldSchema("nonexistent.path", postSchema, allTypes);
-// Returns: null
-```
+#### `resolveFieldSchema(path, typeSchema, schema)`
 
-Handles nested objects, array indices, built-in type fields (`slug.current`, `block.children`), and type references.
+Returns the single field definition at the end of a path. Handles nested objects, array indices, built-in type fields (`slug.current`, `block.children`), and type references. Returns `null` if the path doesn't resolve.
 
 #### `resolveFieldSchemaAllUnions(path, typeSchema, schema)`
 
-Same as `resolveFieldSchema`, but when the path crosses a union array, returns the field definition from **every** item type instead of just the first match.
-
-```ts
-import { resolveFieldSchemaAllUnions } from "@sanity/agent-schema";
-
-resolveFieldSchemaAllUnions("content", postSchema, allTypes);
-// Returns: [blockSchema, imageSchema, codeSchema]
-```
+Same as `resolveFieldSchema`, but when the path crosses a union array, returns the field definition from every item type instead of just the first match.
 
 #### `filterToPath(type, path, schema)`
 
@@ -221,57 +333,77 @@ toSchemaPath('content[_key=="abc"].children[0].text');
 // "content.children.text"
 ```
 
-#### Type helpers
+### Type helpers
+
+#### `isPrimitiveType(type, options?)`
+
+Returns `true` for primitive types (`string`, `number`, `boolean`, `text`, `url`, `date`, `datetime`). Pass `{ includeBlockTypes: true }` to also include `block` and `span`.
+
+#### `isBuiltInType(type)`
+
+Returns `true` for Sanity built-in types (`image`, `file`, `slug`, `geopoint`, `reference`, `block`, `span`).
+
+#### `isGenericObject(node)`
+
+Returns `true` for object-like schema nodes without a `fields` array.
+
+#### `shouldSkipType(typeName)`
+
+Returns `true` for internal types that should be excluded from processing (types matching `system.*`, `sanity.*`, `assist.*`, `media.*`, `mux.*`).
+
+### Constants
+
+#### `BUILT_IN_TYPE_FIELDS`
+
+Maps built-in type names to their implicit field definitions:
 
 ```ts
-import {
-  isPrimitiveType,
-  isBuiltInType,
-  isGenericObject,
-} from "@sanity/agent-schema";
+import { BUILT_IN_TYPE_FIELDS } from "@sanity/agent-schema";
 
-isPrimitiveType("string"); // true
-isPrimitiveType("block", { includeBlockTypes: true }); // true
-isBuiltInType("image"); // true
-isGenericObject(node); // true for object-like nodes without fields array
+BUILT_IN_TYPE_FIELDS.slug.current; // { name: "current", type: "string" }
+BUILT_IN_TYPE_FIELDS.image.asset; // { name: "asset", type: "reference" }
+BUILT_IN_TYPE_FIELDS.block.children; // { name: "children", type: "array", of: [...] }
 ```
 
-#### Constants
+Supported types: `slug`, `geopoint`, `reference`, `image`, `file`, `block`, `span`.
+
+#### `ARRAY_ITEM_SYSTEM_FIELDS`
+
+System fields present on all array items:
 
 ```ts
-import {
-  BUILT_IN_TYPE_FIELDS,
-  ARRAY_ITEM_SYSTEM_FIELDS,
-} from "@sanity/agent-schema";
+import { ARRAY_ITEM_SYSTEM_FIELDS } from "@sanity/agent-schema";
 
-BUILT_IN_TYPE_FIELDS.slug.current; // { name: "current", type: "string" }
 ARRAY_ITEM_SYSTEM_FIELDS._key; // { name: "_key", type: "string" }
+ARRAY_ITEM_SYSTEM_FIELDS._type; // { name: "_type", type: "string" }
 ```
 
-## Types
+#### `DEFAULT_LINK_ANNOTATION`
 
-| Type                        | Description                                                     |
-| --------------------------- | --------------------------------------------------------------- |
-| `ManifestSchemaType`        | A parsed schema type (document, object, array, etc.)            |
-| `ManifestField`             | A field definition (ManifestSchemaType with optional fieldset)  |
-| `DatasetStats`              | `{ documentCount?, referenceCount? }`                           |
-| `CompressedSchemaOptions`   | Options for `compressedSchema()` (filter, datasetStats, fields) |
-| `SchemaFilter`              | `{ read?, write? }` GROQ filter or `string[]` of type names     |
-| `FullSchemaOptions`         | Options for `fullSchema()`                                      |
-| `SchemaFieldDisplayOptions` | Options for field display in `compressedSchema`                 |
-| `SchemaCache`               | Cache adapter for `fetchSchemaByDescriptorId`                   |
+The default link annotation Sanity adds to Portable Text blocks when no `marks.annotations` are declared.
 
-## Architecture
+#### `SCHEMA_CONSTANTS`
 
-```
-fetchSchemaByDescriptorId()         fetchDatasetStats()
-         │                                   │
-         ▼                                   │
-  ManifestSchemaType[]                       │
-         │                                   │
-         ├──► compressedSchema()               ──► text summary of all types
-         ├──► fullSchema()                     ──► JSON subtree of one type (all fields expanded)
-         ├──► resolveFieldSchema()              ──► single field definition at a path
-         ├──► resolveFieldSchemaAllUnions()      ──► same, all union branches
-         └──► processSchema()                  ──► categorize types, expand fields, compute refs
-```
+Internal constants used by the schema processor (skip patterns, title field candidates, default limits). Exported for consumers that need to extend the defaults.
+
+## Types
+
+| Type                        | Description                                                           |
+| --------------------------- | --------------------------------------------------------------------- |
+| `ManifestSchemaType`        | A parsed schema type (document, object, array, etc.)                  |
+| `ManifestField`             | A field definition (`ManifestSchemaType` with optional `fieldset`)    |
+| `DatasetStats`              | `{ documentCount?, referenceCount? }`                                 |
+| `DatasetStatsSchema`        | Zod schema for runtime validation of `DatasetStats`                   |
+| `CompressedSchemaOptions`   | Options for `compressedSchema()`                                      |
+| `SchemaFilter`              | `{ read?, write? }` GROQ filter or `string[]` of type names           |
+| `SchemaFieldDisplayOptions` | Field display options for `compressedSchema`                          |
+| `FullSchemaOptions`         | Options for `fullSchema()`                                            |
+| `SchemaCache`               | Cache adapter for `fetchSchemaByDescriptorId`                         |
+| `FetchSchemaOptions`        | Options for `fetchSchemaByDescriptorId`                               |
+| `ProcessedDocumentType`     | A document type after processing (fields expanded, refs computed)     |
+| `SchemaTypes`               | Return type of `processSchema` (`documentTypes` + `objectTypes` Maps) |
+| `SchemaProcessorOptions`    | Options for `processSchema()`                                         |
+
+### Deprecated aliases
+
+`navigateToFieldSchema` and `navigateToFieldSchemaAllUnions` are deprecated aliases for `resolveFieldSchema` and `resolveFieldSchemaAllUnions`. They will be removed in the next minor version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/agent-schema",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Schema processing utilities for Sanity Agent",
   "keywords": [
     "sanity",
@@ -31,18 +31,10 @@
     "@sanity/client": ">=7.0.0",
     "groq-js": ">=1.0.0"
   },
-  "peerDependenciesMeta": {
-    "@sanity/client": {
-      "optional": true
-    },
-    "groq-js": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@sanity/client": "7.14.1",
     "@sanity/pkg-utils": "^10.4.1",
-    "groq-js": "^1.26.0",
+    "groq-js": "^1.28.0",
     "@types/node": "^22.19.7",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",