feat(schema:extract): moving latest updates to schema extract command by mttdnt · Pull Request #425 · sanity-io/cli

mttdnt · 2026-02-17T19:14:54Z

Description

Watch mode: Added --watch and --watch-patterns flags with debouncing and concurrency control
CLI config support: Added schemaExtraction config in sanity.cli.ts with proper fallback chain (flags → config →
defaults)
- Supports: enforceRequiredFields, path, watchPatterns, workspace
Fixed --enforce-required-fields flag: Removed default to support undefined for proper config fallback
Help URLs: Validation errors now show documentation links when available
Updated error message: Multi-workspace error now mentions both --workspace flag and schemaExtraction.workspace
config
Tests: Added unit tests for getExtractOptions fallback logic

Example Config

export default defineCliConfig({
schemaExtraction: {
enforceRequiredFields: true,
path: 'dist',
workspace: 'production',
},
})

What to review

All migrated functionality matches functionality from original CLI
Used similar watcher setup as packages/@sanity/cli/src/actions/build/writeSanityRuntime.ts, this includes returning the close functionality so tests can stop the watcher without mocking
Moved all extract options to packages/@sanity/cli/src/actions/schema/getExtractOptions.ts including resolving of any paths in an effort to reduce duplication

Testing

Added test cases for watch mode and for schema extraction options

linear · 2026-02-17T19:14:58Z

SDK-742 schema extract: Missing watch mode, config support, and other features from original CLI

Overview

The schema extract command in the new CLI is missing several critical features from the original CLI implementation. This issue tracks the gaps identified through a systematic comparison.

Critical Issues (Must Fix)

1. Missing Watch Mode (`--watch` and `--watch-patterns` flags)

Impact: Breaks development workflows - users cannot auto-extract schema on file changes.

Original Implementation:

--watch flag enables watch mode
--watch-patterns accepts custom glob patterns
Default patterns: sanity.config.{js,jsx,ts,tsx,mjs}, schema*/**/*.{js,jsx,ts,tsx,mjs}
Debounced file change detection with concurrency control
Graceful shutdown handling (SIGINT/SIGTERM)

Files to Migrate:

packages/sanity/original-cli/src/actions/schema/watchExtract.ts (watch implementation)
packages/sanity/original-cli/src/actions/schema/schemaExtractorApi.ts (extraction runner)

Action Required:

Add --watch boolean flag to ExtractSchemaCommand
Add --watch-patterns string array flag to ExtractSchemaCommand
Migrate watch functionality using chokidar
Implement createExtractionRunner for concurrency control
Implement createSchemaWatcher for file watching
Add tests for watch mode functionality

2. Missing CLI Config Support (`schemaExtraction` configuration)

Impact: Users must specify flags every time instead of setting defaults in config file.

Original Implementation:

Reads from sanity.cli.ts/sanity.cli.js via schemaExtraction property
Supported config options:
- workspace: default workspace name
- path: default output path
- enforceRequiredFields: default enforcement setting
- watchPatterns: default watch patterns

References:

Original types: packages/sanity/original-cli/src/types.ts:382-408
Config merging logic: packages/sanity/original-cli/src/actions/schema/extractAction.ts:38-57

Action Required:

Add schemaExtraction config type to new CLI types
Update extract action to accept cliConfig from command context
Implement fallback logic: CLI flags → config file → defaults
Update error messages to reference config options
Add tests for config file fallback behavior

3. Missing Telemetry

Impact: No visibility into CLI usage patterns for this command.

Original Implementation:

Tracks schema extraction events with statistics:
- schemaAllTypesCount
- schemaDocumentTypesCount
- schemaTypesCount
- enforceRequiredFields
- schemaFormat
Tracks watch mode events with:
- Duration
- Extraction count

Files to Migrate:

packages/sanity/original-cli/src/actions/schema/extractSchema.telemetry.ts

Action Required:

Create telemetry trace definitions (similar to extractSchema.telemetry.ts)
Implement telemetry in extract action (remove TODO comment)
Add watch mode telemetry tracking (once watch mode is implemented)
Add tests to verify telemetry is emitted

Breaking Changes

4. Output Path Handling Difference

Impact: Breaks existing scripts/workflows that specify custom filenames.

Original Behavior:

--path /custom/path.json → writes to /custom/path.json
The flag is treated as the full output path including filename

New Behavior:

--path /custom → writes to /custom/schema.json
The flag is treated as a directory, and schema.json is always appended

Action Required:

Change --path to accept full output path (not just directory)
Update flag description to clarify expected behavior
Remove hardcoded FILENAME constant append logic
Match original CLI behavior exactly

Moderate Issues (Should Fix)

5. Missing Schema Validation Error Display

Impact: Poor error messages when schema validation fails.

Original Implementation:

113 lines of sophisticated validation formatting in formatSchemaValidation.ts
Groups errors by schema type (e.g., post, author)
Sorts by severity (errors before warnings)
Human-readable paths (e.g., [image].caption vs raw segments)
Help URLs when available
Color-coded output for TTY

Files to Migrate:

packages/sanity/original-cli/src/actions/schema/formatSchemaValidation.ts

Action Required:

Migrate formatSchemaValidation.ts to new CLI
Detect SchemaError from sanity package
Extract validation info and format before throwing
Add tests for validation error formatting

6. Missing Worker Thread Isolation

Impact: Schema loading issues can crash main CLI process; worse memory management.

Original Implementation:

Runs extraction in separate worker thread (threads/extractSchema.cjs)
Benefits: process isolation, better memory management, cleaner separation

New Implementation:

Runs directly in main thread

Action Required:

Evaluate if worker thread isolation is necessary
If yes: Create worker thread implementation similar to threads/extractSchema.ts
If no: Document the design decision

Minor Issues (Consider Addressing)

7. Error Message Formatting

The error message for multiple workspaces doesn't mention the schemaExtraction.workspace config option (expected until config support is added).

Action Required:

Update error message once config support is implemented

8. Missing Examples in Help Text

The new CLI only has one example vs. multiple in the original (watch mode examples are missing).

Action Required:

Add additional examples once watch mode is implemented

Test Coverage Gaps

New CLI has tests for:

Help output
Basic extraction
--enforce-required-fields flag
--path flag
Invalid format error

Missing test scenarios:

Watch mode tests (pending feature implementation)
Config file fallback tests (pending feature implementation)
Validation error formatting tests
Multiple workspace handling tests
Schema statistics/telemetry tests

Implementation Priority

Priority 1 (Must Fix - Breaks User Workflows)

Implement watch mode (--watch and --watch-patterns)
Add CLI config support for schemaExtraction settings
Fix output path handling to match original behavior

Priority 2 (Should Fix - Impacts User Experience)

Add telemetry tracking
Implement schema validation error formatting
Consider worker thread isolation (or document why not needed)

Priority 3 (Consider - Polish)

Update error messages to reference config options
Add more examples to help text

Reference Files

Original CLI (reference only):

Commands: packages/sanity/original-cli/src/commands/schema/extractSchemaCommand.ts
Actions: packages/sanity/original-cli/src/actions/schema/extractAction.ts
Telemetry: packages/sanity/original-cli/src/actions/schema/extractSchema.telemetry.ts
Watch: packages/sanity/original-cli/src/actions/schema/watchExtract.ts
Extractor API: packages/sanity/original-cli/src/actions/schema/schemaExtractorApi.ts
Validation Formatter: packages/sanity/original-cli/src/actions/schema/formatSchemaValidation.ts
Worker Thread: packages/sanity/original-cli/src/threads/extractSchema.ts
Types: packages/sanity/original-cli/src/types.ts (schemaExtraction config)

New CLI (to be updated):

Command: packages/sanity/cli/src/commands/schema/extract.ts
Action: packages/sanity/cli/src/actions/schema/extract.ts
Tests: packages/sanity/cli/src/commands/schema/__tests__/extract.test.ts

Notes

The full comparison report was generated by the cli-migration-diff-analyzer agent (ID: acc433f)
This issue covers 8 identified differences with 3 critical gaps
Watch mode is the most commonly requested missing feature

claude · 2026-02-17T19:15:12Z

Claude finished @mttdnt's task in 1m 55s —— View job

PR Review Complete

Read repository guidelines
Review existing reviewer comments
Review implementation files
Check test coverage and quality
Identify issues and provide feedback

Issues Found

1. Schema config validation missing (line 69, schemas.ts)

The cliConfigSchema in schemas.ts was updated but reviewer notes it should have additional validation added (binoy14's comment). The schema validation already exists at lines 69-76, so this comment may be resolved, but verify if additional validation is needed.

2. Watcher exits process in watch mode (line 137, extractSchemaWatcher.ts)

In extractSchemaWatcher.ts:137, non-validation errors call output.error(err.message, {exit: 1}) which exits the process. In watch mode, the watcher should continue running after errors, not exit. This breaks the watch functionality on non-validation errors.

Fix: Remove {exit: 1} or don't call output.error with exit in watch context:

} else if (err instanceof Error) {
  output.error(err.message)  // Remove {exit: 1}
}

3. Unnecessary await in extract.ts (line 76)

Reviewer binoy14 correctly notes the return extractSchema() at line 76 doesn't need await since it's a direct return.

Fix: Remove await as suggested in review comment.

4. Test duplication question (extractSchemaWatcher.test.ts)

Reviewer binoy14 questions if the watcher test is needed since extract test already calls the function. The watcher test is valuable - it tests error handling paths (validation errors, fatal errors, close functionality) that the extract test doesn't cover. Keep the test.

5. Lodash-es usage can be replaced (watchExtractSchema.ts:2)

The mean and once imports from lodash-es at line 2 could be replaced with native JS:

mean() can be array.reduce((a, b) => a + b, 0) / array.length || 0
once() can be a simple boolean flag

While lodash-es is already a dependency, minimizing its usage is better for bundle size. However, this is minor since the functions are only used once.

6. Missing test for glob pattern resolution (getExtractOptions.test.ts)

Tests cover flag/config fallback but don't test the path resolution logic. The outputPath combines pathFlag with schema.json, but there's no test verifying this produces correct absolute paths for edge cases (e.g., absolute paths, relative paths, missing paths).

Add test case:

test('should resolve absolute paths correctly', () => {
  const result = getExtractOptions({
    flags: {path: '/absolute/path', ...otherFlags},
    projectRoot: mockProjectRoot,
    schemaExtraction: undefined,
  })
  expect(result.outputPath).toBe('/absolute/path/schema.json')
})

Summary

Critical issue: Watch mode exits on non-validation errors (issue #2). Other issues are minor improvements and one reviewer suggestion to implement.

github-actions · 2026-02-17T21:01:30Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	77.02%	7042 / 9142
🔵	Statements	76.53%	7253 / 9477
🔵	Functions	73.46%	1196 / 1628
🔵	Branches	63.53%	3242 / 5103

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/@sanity/cli-core/src/config/cli/schemas.ts	100%	100%	100%	100%
packages/@sanity/cli/src/actions/schema/extractSchema.ts	95.45%	84.61%	100%	95.45%	67
packages/@sanity/cli/src/actions/schema/extractSchemaWatcher.ts	66.03%	52.63%	44.44%	66.03%	67-83, 154, 159, 168-171, 175
packages/@sanity/cli/src/actions/schema/formatSchemaValidation.ts	95.83%	82.85%	100%	100%	51, 52
packages/@sanity/cli/src/actions/schema/getExtractOptions.ts	100%	92.85%	100%	100%
packages/@sanity/cli/src/actions/schema/runSchemaExtraction.ts	100%	100%	100%	100%
packages/@sanity/cli/src/actions/schema/watchExtractSchema.ts	96.29%	50%	100%	96.29%	48
packages/@sanity/cli/src/commands/schema/extract.ts	100%	100%	100%	100%
packages/@sanity/cli/src/telemetry/extractSchema.telemetry.ts	100%	100%	100%	100%
packages/@sanity/cli/src/util/getWorkspace.ts	100%	100%	100%	100%

Generated in workflow #2204 for commit 59a6f87 by the Vitest Coverage Report Action

… file

mttdnt · 2026-02-17T22:53:49Z

Just want to call out one thing from the Claude is reporting 'Output Path Handling Difference', this was fixed by @laurenashpole in #190, but it seems like it will be a breaking change in the new CLI.

binoy14

Small nitpick changes and questions on the PR.

Note: the PR title needs to follow conventional commit. We probably should add a github action to enforce this

binoy14 · 2026-02-18T04:57:36Z

+  /**
+   * Configuration for schema extraction (`sanity schema extract`)
+   */
+  schemaExtraction?: {


Also need to update cliConfigSchema in schemas.ts

mttdnt added 4 commits February 16, 2026 15:11

feat(schema:extract): watch mode for extraction

9ce571a

feat(schema:extract): tests for watch mode

21c5b64

feat(schema:extract): adding schema extraction properties to cli config

ab4e62c

feat(schema:extract): schema validation updates

e9e6242

feat(schema:extract): fixing tests and claude review

2a24d4c

mttdnt added 2 commits February 17, 2026 16:06

feat(schema:extract): other tiny claude revisions

c348d86

feat(schema:extract): moving some reusable extraction logic to shared…

dbd5a94

… file

mttdnt marked this pull request as ready for review February 17, 2026 22:14

mttdnt requested a review from a team as a code owner February 17, 2026 22:14

mttdnt requested review from binoy14 and somerandomdude and removed request for a team February 17, 2026 22:14

binoy14 requested changes Feb 18, 2026

View reviewed changes

mttdnt changed the title ~~Sdk 742/feature/moving watch schema extraction~~ feat(schema:extract): moving latest updates to schema extract command Feb 18, 2026

binoy14 requested a review from kbrabrand February 18, 2026 15:24

chore(schema:extract): pr comments

59a6f87

mttdnt requested a review from binoy14 February 18, 2026 17:26

binoy14 approved these changes Feb 18, 2026

View reviewed changes

rexxars merged commit b4f55ef into main Feb 18, 2026
33 checks passed

rexxars deleted the sdk-742/feature/moving-watch-schema-extraction branch February 18, 2026 20:49

squiggler-legacy Bot mentioned this pull request Feb 18, 2026

chore: release main #430

Merged

This was referenced Mar 6, 2026

chore: release main #556

Merged

chore: release main #592

Merged

Conversation

mttdnt commented Feb 17, 2026

Description

What to review

Testing

Uh oh!

linear Bot commented Feb 17, 2026

Overview

Critical Issues (Must Fix)

1. Missing Watch Mode (--watch and --watch-patterns flags)

2. Missing CLI Config Support (schemaExtraction configuration)

3. Missing Telemetry

Breaking Changes

4. Output Path Handling Difference

Moderate Issues (Should Fix)

5. Missing Schema Validation Error Display

6. Missing Worker Thread Isolation

Minor Issues (Consider Addressing)

7. Error Message Formatting

8. Missing Examples in Help Text

Test Coverage Gaps

Implementation Priority

Priority 1 (Must Fix - Breaks User Workflows)

Priority 2 (Should Fix - Impacts User Experience)

Priority 3 (Consider - Polish)

Reference Files

Notes

Uh oh!

claude Bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Complete

Issues Found

1. Schema config validation missing (line 69, schemas.ts)

2. Watcher exits process in watch mode (line 137, extractSchemaWatcher.ts)

3. Unnecessary await in extract.ts (line 76)

4. Test duplication question (extractSchemaWatcher.test.ts)

5. Lodash-es usage can be replaced (watchExtractSchema.ts:2)

6. Missing test for glob pattern resolution (getExtractOptions.test.ts)

Summary

Uh oh!

github-actions Bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

mttdnt commented Feb 17, 2026

Uh oh!

binoy14 left a comment

Choose a reason for hiding this comment

Uh oh!

binoy14 Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

1. Missing Watch Mode (`--watch` and `--watch-patterns` flags)

2. Missing CLI Config Support (`schemaExtraction` configuration)

claude Bot commented Feb 17, 2026 •

edited

Loading

github-actions Bot commented Feb 17, 2026 •

edited

Loading