Add description() metadata action and map it in the JSON Schema emitter

Downstream tool-parameter schemas need per-field descriptions to survive
AOT JSON Schema generation; until now the emitter dropped any metadata
with a "not representable" warning. description() is a pure pass-through
transformation (same runtime shape as readonly), so the compiled fast
path is unaffected, and the emitter folds it onto the accumulated schema
last-wins.

Closes #42

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PXctopVx69rLttyhKbeoVE

Author: ushironoko

.changeset/large-timers-search.md

@@ -0,0 +1,8 @@
+---
+"@tskm/core": minor
+"@tskm/compiler": patch
+---
+
+Add a `description(text)` metadata action and map it to the JSON Schema `description` keyword
+
+`description()` is a pure pass-through transformation (no runtime validation effect, same shape as `readonly`). The JSON Schema emitter now folds it onto the accumulated schema as the `description` keyword; piping it multiple times is last-wins. Per-property descriptions inside `object()` land on the property schema.

packages/compiler/src/jsonschema.ts

@@ -20,9 +20,9 @@ import { resolveWorker, runWorker, type SchemaWorkerEnvelope } from "./worker-ha
  * exported schema objects, walks them, and writes `*.schema.json`.
  *
  * Refinements that JSON Schema can express (min/max length, min/max value, integer,
- * multipleOf, email/url format, regex pattern) are mapped; `transform`/`brand` and
- * other non-representable actions are dropped with a warning. `lazy` becomes
- * `$ref`/`$defs`.
+ * multipleOf, email/url format, regex pattern, description metadata) are mapped;
+ * `transform`/`brand` and other non-representable actions are dropped with a
+ * warning. `lazy` becomes `$ref`/`$defs`.
  */
 
 export type JsonSchema = { [key: string]: unknown }
@@ -305,6 +305,11 @@ function applyItem(
         out.pattern = requirement.source
       }
       return
+    case "description":
+      if (typeof requirement === "string") {
+        out.description = requirement
+      }
+      return
     default:
       ctx.warnings.push(
         `tskm: pipe item "${String(type)}" is not representable in JSON Schema; skipped.`,

packages/compiler/test/jsonschema.test.ts

@@ -152,6 +152,67 @@ describe("schemaToJsonSchema — pipe refinements", () => {
   })
 })
 
+describe("schemaToJsonSchema — description metadata", () => {
+  const desc = (requirement: string) => ({
+    kind: "transformation",
+    type: "description",
+    requirement,
+  })
+
+  it("description on a string -> description keyword, no warning", () => {
+    const result = schemaToJsonSchema(pipe(s.string(), desc("a plain string")))
+    expect(result.schema).toEqual({ type: "string", description: "a plain string" })
+    expect(result.warnings).toEqual([])
+  })
+
+  it("description on a property lands on the property, not the parent", () => {
+    const schema = s.object({
+      id: pipe(s.string(), desc("unique identifier")),
+      name: s.string(),
+    })
+    const { schema: out } = schemaToJsonSchema(schema)
+    expect(out).toEqual({
+      type: "object",
+      properties: {
+        id: { type: "string", description: "unique identifier" },
+        name: { type: "string" },
+      },
+      required: ["id", "name"],
+      additionalProperties: false,
+    })
+  })
+
+  it("composes with constraint actions in the same pipe", () => {
+    const schema = pipe(
+      s.string(),
+      { kind: "validation", type: "min_length", requirement: 1 },
+      desc("non-empty text"),
+    )
+    expect(schemaToJsonSchema(schema).schema).toEqual({
+      type: "string",
+      minLength: 1,
+      description: "non-empty text",
+    })
+  })
+
+  it("stacks last-wins when piped multiple times", () => {
+    const schema = pipe(s.string(), desc("first"), desc("second"))
+    expect(schemaToJsonSchema(schema).schema).toEqual({
+      type: "string",
+      description: "second",
+    })
+  })
+
+  it("ignores a non-string requirement instead of emitting garbage", () => {
+    const schema = pipe(s.string(), {
+      kind: "transformation",
+      type: "description",
+      requirement: 42,
+    })
+    expect(schemaToJsonSchema(schema).schema).toEqual({ type: "string" })
+  })
+})
+
 describe("schemaToJsonSchema — lazy recursion", () => {
   it("terminates a self-referential lazy and emits $ref/$defs", () => {
     // A node referencing itself through a lazy getter — the classic recursive shape.

packages/tskm/src/actions/description.ts

@@ -0,0 +1,23 @@
+import type { OutputDataset } from "../types/dataset.ts"
+import type { BaseTransformation } from "../types/schema.ts"
+
+export interface DescriptionAction<TInput> extends BaseTransformation<TInput, TInput> {
+  readonly type: "description"
+  readonly reference: typeof description
+  readonly requirement: string
+}
+
+// @__NO_SIDE_EFFECTS__
+export function description<TInput>(requirement: string): DescriptionAction<TInput> {
+  return {
+    kind: "transformation",
+    type: "description",
+    reference: description,
+    async: false,
+    requirement,
+    "~run"(dataset) {
+      // `description` is metadata-only; the runtime value is unchanged.
+      return dataset as OutputDataset<TInput>
+    },
+  }
+}

packages/tskm/src/index.ts

@@ -4,6 +4,7 @@
 export { type Brand, type BrandAction, brand } from "./actions/brand.ts"
 export { type CheckAction, check } from "./actions/check.ts"
 export { type CheckActionAsync, checkAsync } from "./actions/checkAsync.ts"
+export { type DescriptionAction, description } from "./actions/description.ts"
 export { type EmailAction, email } from "./actions/email.ts"
 export { type IntegerAction, integer } from "./actions/integer.ts"
 export { type LengthAction, length } from "./actions/length.ts"

packages/tskm/test/actions-misc.test.ts

@@ -3,6 +3,8 @@ import {
   brand,
   check,
   checkAsync,
+  description,
+  minLength,
   number,
   parse,
   parseAsync,
@@ -238,6 +240,38 @@ describe("brand", () => {
   })
 })
 
+describe("description", () => {
+  it("builds an action with the expected static shape", () => {
+    const action = description<string>("user-visible name")
+    expect(action.kind).toBe("transformation")
+    expect(action.type).toBe("description")
+    expect(action.reference).toBe(description)
+    expect(action.async).toBe(false)
+    expect(action.requirement).toBe("user-visible name")
+  })
+
+  it("passes the runtime value through unchanged", () => {
+    const schema = pipe(string(), description<string>("a plain string"))
+    expect(parse(schema, "abc")).toBe("abc")
+  })
+
+  it("preserves the object reference produced by a prior transform", () => {
+    const obj = { a: 1 }
+    const schema = pipe(
+      string(),
+      transform(() => obj),
+      description<{ a: number }>("wrapped object"),
+    )
+    expect(parse(schema, "x")).toBe(obj)
+  })
+
+  it("composes with validations without affecting them", () => {
+    const schema = pipe(string(), minLength(2), description<string>("at least two chars"))
+    expect(parse(schema, "ab")).toBe("ab")
+    expect(safeParse(schema, "a").success).toBe(false)
+  })
+})
+
 describe("readonly", () => {
   it("builds an action with the expected static shape", () => {
     const action = readonly<string>()