Skip to content

feat(schema): Schema.toTypeScript codegen; named Parameters + propertyMeta - #207

Merged
krisnye merged 3 commits into
mainfrom
krisnye/service-schema-to-typescript
Oct 5, 2026
Merged

krisnye merged 3 commits into
mainfrom
krisnye/service-schema-to-typescript

Conversation

@krisnye

@krisnye krisnye commented Sep 25, 2026 •

Copy link
Copy Markdown
Collaborator

This PR carries two independent changes on the branch.


1. Schema.toTypeScript codegen + named parameters + propertyMeta

Adds Schema.toTypeScript(schema, name) — a runtime generator that turns a service Schema into TypeScript type declarations, the source-text counterpart of the type-level Schema.ToType.

Generator

  • Emits an interface for object schemas, a type alias otherwise; mirrors ToType (deep-readonly by default, mutable opts out). Output carries no export keyword.
  • Recurses the whole tree (properties, array items, oneOf/allOf/anyOf, function signatures, observe/promise/generator values).
  • Deduplicates repeated object shapes: a shape used more than once (or as a length-≥2 tuple element) is pre-declared once as a named interface and referenced by name; singletons stay inlined. Name source: title → referencing property key → generated Shape<n> (collisions get a numeric suffix).
  • Emits descriptions as // comments above declarations, properties, and function parameters. A property comment that merely repeats the referenced type's own comment is suppressed.

Schema changes

  • BREAKING: signature.parameters is now readonly Parameter[] ({ name, description?, schema }) instead of bare Schema[], so an argument's name and docs are known independently of its type. ToType derives the call signature positionally from parameter.schema.
  • Adds Schema.propertyMeta ({ [key]: PropertyMeta }, PropertyMeta { description? }) for per-property field docs that stay independent of a shared/by-reference property type. Pure metadata — does not affect ToType, stripped from structural-shape identity. Parameter/PropertyMeta exported from @adobe/data/schema.

Migration: data-rpc runtime readers (register-service, synthesize-service) map parameters → p.schema (helpers stay on Schema[]); all function-schema fixtures across data, data-rpc, data-rpc-iframe migrated to named parameters. agentic-service action parameters are a separate concept and unchanged.


2. @adobe/data-ai installer: write managed notice as AGENTS.md by default

The installer dropped a CLAUDE.md "do-not-edit" notice into both managed bundle folders (.claude/rules/adobe-data-ai/, .agents/skills/adobe-data-ai/). On Claude Code 2.1.286, any CLAUDE.md in the tree switches the project into CLAUDE.md mode and suppresses AGENTS.md discovery project-wide — so a repo migrating to AGENTS.md (e.g. to share instructions between Claude Code and Copilot) silently loses all instructions.

Fix (bin/cli.mjs noticeFilename): name the notice for the repo's convention — AGENTS.md by default (the cross-agent standard, also read by Claude Code), CLAUDE.md only for a repo that is still CLAUDE.md-only. An AGENTS.md repo (or greenfield) never receives a data-ai CLAUDE.md. Bundle folders are wipe-and-recopied each install, so existing repos self-heal on their next install. Adds test/install.test.mjs (4 integration tests) and documents the behavior in the README.


Testing

  • New generator suite (45 tests) + data-ai install suite (4 tests). data-rpc 48/48, data schema + async-data-service 468/468.
  • Full monorepo pnpm run lint + pnpm run typecheck clean (only pre-existing dist/assembly artifact errors remain, unrelated).
  • Version bumped v0.10.19 → v0.10.20.

Related PRs

N/A

krisnye and others added 3 commits September 25, 2026 09:56
…yMeta

Add Schema.toTypeScript(schema, name) generating TS declarations (interface
for objects) that mirror ToType: recurses, hoists repeated object shapes to
named interfaces, and emits descriptions as comments.

BREAKING: signature.parameters is now readonly Parameter[] ({ name,
description?, schema }) so argument names/docs are known independently of the
type. Adds Schema.propertyMeta for per-property field docs independent of a
shared property type. ToType and the data-rpc runtime updated; all fixtures
migrated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The installer dropped a CLAUDE.md "do-not-edit" notice into both managed
bundle folders. On Claude Code 2.1.286 any CLAUDE.md in the tree switches
the project into CLAUDE.md mode and suppresses AGENTS.md discovery
project-wide, so a repo that uses AGENTS.md loses all instructions.

Name the notice for the repo's convention instead: AGENTS.md by default
(also read by Claude Code), CLAUDE.md only for a CLAUDE.md-only repo. An
AGENTS.md repo never receives a data-ai CLAUDE.md. Adds install tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…a-to-typescript

# Conflicts:
#	package.json
#	packages/data-ai/.claude-plugin/plugin.json
#	packages/data-ai/package.json
#	packages/data-gpu/package.json
#	packages/data-lit/package.json
#	packages/data-persistence/package.json
#	packages/data-react/package.json
#	packages/data-rpc/package.json
#	packages/data-solid/package.json
#	packages/data-sync/package.json
#	packages/data-testing/package.json
#	packages/data/package.json
@krisnye
krisnye merged commit d932d4e into main Oct 5, 2026
3 checks passed
@krisnye
krisnye deleted the krisnye/service-schema-to-typescript branch October 5, 2026 17:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant