@sanity/ui 4.0.0-v4.1 → 5.0.0-alpha.2

package/src/cli/styles.ts

@@ -0,0 +1,205 @@
+import {existsSync, readdirSync, readFileSync, statSync, writeFileSync} from 'node:fs'
+import {dirname, join, relative} from 'node:path'
+
+export const STYLES_SPECIFIER = '@sanity/ui/styles.css'
+const IMPORT_LINE = `import '${STYLES_SPECIFIER}'`
+// Match a real import/require of the stylesheet, not a bare mention. A
+// commented-out or string occurrence of the path must not count as "wired",
+// or doctor/init would report success when the import isn't active.
+const SPEC = String.raw`@sanity/ui/styles\.css`
+const PRESENT = new RegExp(
+  String.raw`(?:^|\n)\s*import\s+(?:[^\n'"]*\bfrom\s+)?['"]${SPEC}['"]` +
+    String.raw`|\brequire\(\s*['"]${SPEC}['"]\s*\)`,
+)
+const SOURCE_EXT = /\.[jt]sx?$|\.astro$/
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  '.next',
+  '.react-router',
+  '.git',
+  'out',
+])
+const SOURCE_ROOTS = ['src', 'app', 'pages', 'components']
+const MAX_FILES = 800
+
+export interface StylesheetInfo {
+  entry: string
+  file: string
+  exists: boolean
+  imported: boolean
+  importedIn?: string
+}
+
+export interface WireResult {
+  entry: string
+  file: string
+  imported: boolean
+  wrote: boolean
+  missing?: boolean
+  already?: boolean
+}
+
+export function hasStylesImport(content: string): boolean {
+  return PRESENT.test(content)
+}
+
+function fileImports(file: string): boolean {
+  try {
+    return hasStylesImport(readFileSync(file, 'utf8'))
+  } catch {
+    return false
+  }
+}
+
+/** Bounded recursive walk that returns the first source file importing the stylesheet. */
+function findImportInDir(root: string, budget: {count: number}): string | null {
+  const stack = [root]
+  while (stack.length > 0 && budget.count < MAX_FILES) {
+    const dir = stack.pop()
+    if (dir === undefined) break
+    let entries
+    try {
+      entries = readdirSync(dir, {withFileTypes: true})
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) stack.push(full)
+      } else if (SOURCE_EXT.test(entry.name)) {
+        budget.count++
+        if (budget.count > MAX_FILES) break
+        if (fileImports(full)) return full
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Reports whether the stylesheet is imported. The import only needs to exist
+ * once in the module graph, so beyond the prescribed entry we scan the project
+ * source roots (bounded) before reporting it missing. That catches imports
+ * placed in App.tsx, a route file, or a layout component.
+ */
+export function inspectStylesheet(cwd: string, entry: string): StylesheetInfo {
+  const file = join(cwd, entry)
+  const exists = existsSync(file)
+  if (exists && fileImports(file)) return {entry, file, exists, imported: true}
+
+  const budget = {count: 0}
+  const roots = new Set([dirname(entry), ...SOURCE_ROOTS].map((r) => join(cwd, r)))
+  for (const root of Array.from(roots)) {
+    if (!existsSync(root)) continue
+    try {
+      if (!statSync(root).isDirectory()) continue
+    } catch {
+      continue
+    }
+    const found = findImportInDir(root, budget)
+    if (found)
+      return {
+        entry,
+        file,
+        exists,
+        imported: true,
+        importedIn: relative(cwd, found),
+      }
+  }
+
+  return {entry, file, exists, imported: false}
+}
+
+function isDirective(line: string): boolean {
+  const trimmed = line.trim()
+  return /^['"]use (client|server|strict)['"];?$/.test(trimmed)
+}
+
+function isImportLine(line: string): boolean {
+  return /^\s*import\b/.test(line)
+}
+
+/**
+ * True when an import statement finishes on this line: either it ends with a
+ * `from '...'` clause or it is a bare side-effect `import '...'`. Used to find
+ * the real end of an import block so we never split a multiline import.
+ */
+function importStatementEnds(line: string): boolean {
+  const t = line.trim()
+  return /\bfrom\s*['"][^'"]+['"];?\s*$/.test(t) || /^import\s+['"][^'"]+['"];?\s*$/.test(t)
+}
+
+/** Inserts the import into a JS/TS module after any leading directive + import block. */
+function injectIntoModule(content: string): string {
+  const lines = content.split('\n')
+  let insertAt = 0
+
+  while (insertAt < lines.length) {
+    const line = lines[insertAt] ?? ''
+    if (isDirective(line) || line.trim() === '') insertAt++
+    else break
+  }
+
+  // Track the last line that closes an import statement so a multiline import
+  // (`import {\n  a,\n} from 'x'`) is treated as a single unit and we insert
+  // after its closing line, never between its lines.
+  let lastImport = -1
+  let inMultilineImport = false
+  for (let i = insertAt; i < lines.length; i++) {
+    const line = lines[i] ?? ''
+    if (inMultilineImport) {
+      if (importStatementEnds(line)) {
+        inMultilineImport = false
+        lastImport = i
+      }
+      continue
+    }
+    if (isImportLine(line)) {
+      lastImport = i
+      if (!importStatementEnds(line)) inMultilineImport = true
+    } else if (line.trim() !== '' && lastImport !== -1) {
+      break
+    }
+  }
+
+  const at = lastImport === -1 ? insertAt : lastImport + 1
+  lines.splice(at, 0, IMPORT_LINE)
+  return lines.join('\n')
+}
+
+/** Inserts the import inside an Astro frontmatter fence, creating one if absent. */
+function injectIntoAstro(content: string): string {
+  if (content.startsWith('---')) {
+    const end = content.indexOf('\n---', 3)
+    if (end !== -1) {
+      const head = content.slice(0, end)
+      const tail = content.slice(end)
+      return `${head}\n${IMPORT_LINE}${tail}`
+    }
+  }
+  return `---\n${IMPORT_LINE}\n---\n${content}`
+}
+
+export function wireStylesheet(cwd: string, entry: string, {dryRun = false} = {}): WireResult {
+  const file = join(cwd, entry)
+  if (!existsSync(file)) return {entry, file, missing: true, imported: false, wrote: false}
+
+  const content = readFileSync(file, 'utf8')
+  if (hasStylesImport(content)) {
+    return {
+      entry,
+      file,
+      missing: false,
+      imported: true,
+      wrote: false,
+      already: true,
+    }
+  }
+
+  const next = entry.endsWith('.astro') ? injectIntoAstro(content) : injectIntoModule(content)
+  if (!dryRun) writeFileSync(file, next)
+  return {entry, file, missing: false, imported: true, wrote: !dryRun}
+}

package/src/cli/test-utils.ts

@@ -0,0 +1,10 @@
+import {mkdirSync, writeFileSync} from 'node:fs'
+import {join} from 'node:path'
+
+import {PACKAGE_NAME} from './detect.js'
+
+export function writeInstalledUiVersion(dir: string, version: string): void {
+  const root = join(dir, 'node_modules', PACKAGE_NAME)
+  mkdirSync(root, {recursive: true})
+  writeFileSync(join(root, 'package.json'), JSON.stringify({name: PACKAGE_NAME, version}))
+}

package/src/cli/tsconfig.test.ts

@@ -0,0 +1,174 @@
+import {mkdtempSync, readFileSync, rmSync, writeFileSync} from 'node:fs'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+
+import {parse} from 'comment-json'
+import {afterEach, beforeEach, describe, expect, it} from 'vitest'
+
+import {planTsconfigChanges, reconcileTsconfig, resolveTargetTsconfig} from './tsconfig.js'
+import type {TsconfigChange} from './types.js'
+
+function keysChanged(changes: TsconfigChange[]): string[] {
+  return changes.map((c) => c.key).sort()
+}
+
+interface ParsedTsconfig {
+  compilerOptions?: Record<string, unknown>
+}
+
+function parseConfig(raw: string): ParsedTsconfig {
+  return parse(raw) as unknown as ParsedTsconfig
+}
+
+describe('planTsconfigChanges', () => {
+  it('reports nothing for an already-good config', () => {
+    const changes = planTsconfigChanges({
+      jsx: 'react-jsx',
+      module: 'esnext',
+      moduleResolution: 'bundler',
+      lib: ['DOM', 'DOM.Iterable', 'ES2022'],
+      skipLibCheck: true,
+    })
+    expect(changes).toEqual([])
+  })
+
+  it('fixes a classic moduleResolution and incompatible module together', () => {
+    const changes = planTsconfigChanges({
+      jsx: 'react-jsx',
+      module: 'commonjs',
+      moduleResolution: 'node',
+      lib: ['DOM', 'DOM.Iterable', 'ES2022'],
+      skipLibCheck: true,
+    })
+    expect(keysChanged(changes)).toEqual(['module', 'moduleResolution'])
+    expect(changes.find((c) => c.key === 'moduleResolution')?.to).toBe('bundler')
+    expect(changes.find((c) => c.key === 'module')?.to).toBe('esnext')
+  })
+
+  it('leaves a compatible module alone when resolution is already modern', () => {
+    const changes = planTsconfigChanges({
+      jsx: 'react-jsx',
+      module: 'commonjs',
+      moduleResolution: 'nodenext',
+      lib: ['DOM', 'DOM.Iterable', 'ES2022'],
+      skipLibCheck: true,
+    })
+    // nodenext is modern, but commonjs is not bundler-compatible; nodenext does
+    // not force the change, so module stays untouched.
+    expect(keysChanged(changes)).toEqual([])
+  })
+
+  it('does not force module when resolution is nodenext and module is missing', () => {
+    const changes = planTsconfigChanges({
+      jsx: 'react-jsx',
+      moduleResolution: 'nodenext',
+      lib: ['DOM', 'DOM.Iterable', 'ES2022'],
+      skipLibCheck: true,
+    })
+    expect(changes.find((c) => c.key === 'module')).toBeUndefined()
+  })
+
+  it('adds only missing DOM libs and keeps the existing ES baseline', () => {
+    const changes = planTsconfigChanges({
+      jsx: 'react-jsx',
+      module: 'esnext',
+      moduleResolution: 'bundler',
+      lib: ['ES2023', 'DOM'],
+      skipLibCheck: true,
+    })
+    expect(keysChanged(changes)).toEqual(['lib'])
+    const lib = changes.find((c) => c.key === 'lib')
+    expect(lib?.merge).toBe(true)
+    expect(lib?.to).toEqual(['DOM.Iterable'])
+  })
+
+  it('treats jsx and moduleResolution as load-bearing', () => {
+    const changes = planTsconfigChanges({})
+    const load = changes.filter((c) => c.load).map((c) => c.key)
+    expect(load).toContain('jsx')
+    expect(load).toContain('moduleResolution')
+  })
+})
+
+describe('reconcileTsconfig', () => {
+  let dir: string
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'sui-tsconfig-'))
+  })
+  afterEach(() => {
+    rmSync(dir, {recursive: true, force: true})
+  })
+
+  it('creates a tsconfig when none exists', () => {
+    const result = reconcileTsconfig(dir)
+    expect(result.created).toBe(true)
+    const written = parseConfig(readFileSync(join(dir, 'tsconfig.json'), 'utf8'))
+    expect(written.compilerOptions?.['jsx']).toBe('react-jsx')
+    expect(written.compilerOptions?.['moduleResolution']).toBe('bundler')
+  })
+
+  it('merges required options while preserving comments and unrelated settings', () => {
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      `{
+  // keep me
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "module": "commonjs",
+    "baseUrl": "."
+  }
+}
+`,
+    )
+    const result = reconcileTsconfig(dir)
+    expect(result.created).toBe(false)
+    const raw = readFileSync(join(dir, 'tsconfig.json'), 'utf8')
+    expect(raw).toContain('// keep me')
+    const written = parseConfig(raw)
+    expect(written.compilerOptions?.['baseUrl']).toBe('.')
+    expect(written.compilerOptions?.['moduleResolution']).toBe('bundler')
+    expect(written.compilerOptions?.['module']).toBe('esnext')
+    expect(written.compilerOptions?.['jsx']).toBe('react-jsx')
+  })
+
+  it('is idempotent: a second run makes no changes', () => {
+    reconcileTsconfig(dir)
+    const second = reconcileTsconfig(dir)
+    expect(second.changes).toEqual([])
+  })
+
+  it('targets the referenced config in a solution-style setup', () => {
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      `{"files": [], "references": [{"path": "./tsconfig.app.json"}]}\n`,
+    )
+    writeFileSync(
+      join(dir, 'tsconfig.app.json'),
+      `{"compilerOptions": {"moduleResolution": "bundler", "module": "esnext", "jsx": "react-jsx", "lib": ["ES2023", "DOM"], "skipLibCheck": true}}\n`,
+    )
+    const result = reconcileTsconfig(dir)
+    expect(result.file.endsWith('tsconfig.app.json')).toBe(true)
+    expect(keysChanged(result.changes)).toEqual(['lib'])
+  })
+
+  it('skips a referenced config without compilerOptions and picks one that has them', () => {
+    writeFileSync(
+      join(dir, 'tsconfig.json'),
+      `{"files": [], "references": [{"path": "./tsconfig.app.json"}, {"path": "./tsconfig.node.json"}]}\n`,
+    )
+    // The "app" config is preferred by name but carries no options, so it must be skipped.
+    writeFileSync(join(dir, 'tsconfig.app.json'), `{"extends": "./base.json"}\n`)
+    writeFileSync(
+      join(dir, 'tsconfig.node.json'),
+      `{"compilerOptions": {"moduleResolution": "bundler"}}\n`,
+    )
+    const target = resolveTargetTsconfig(dir)
+    expect(target.file.endsWith('tsconfig.node.json')).toBe(true)
+  })
+
+  it('treats a non-object tsconfig.json as unreadable instead of crashing', () => {
+    writeFileSync(join(dir, 'tsconfig.json'), `null\n`)
+    expect(resolveTargetTsconfig(dir).unreadable).toBe(true)
+    expect(reconcileTsconfig(dir).unreadable).toBe(true)
+  })
+})

package/src/cli/tsconfig.ts

@@ -0,0 +1,282 @@
+import {existsSync, readFileSync, writeFileSync} from 'node:fs'
+import {dirname, isAbsolute, join, resolve} from 'node:path'
+
+import {parse, stringify} from 'comment-json'
+
+import type {TsconfigChange} from './types.js'
+
+interface TsconfigDoc {
+  extends?: string | string[]
+  compilerOptions?: Record<string, unknown>
+  references?: Array<{path?: string}>
+}
+
+/** moduleResolution values that read a package `exports` map and its types. */
+const MODERN_RESOLUTIONS = new Set(['bundler', 'node16', 'nodenext'])
+/** module values compatible with moduleResolution: bundler. */
+const BUNDLER_MODULES = new Set(['esnext', 'preserve', 'es2015', 'es2020', 'es2022'])
+const VALID_JSX = new Set(['react-jsx', 'react-jsxdev', 'preserve', 'react', 'react-native'])
+
+/** DOM globals the component types reference, plus a modern JS baseline. */
+const DOM_LIBS = ['DOM', 'DOM.Iterable']
+const ES_BASELINE = 'ES2022'
+
+/**
+ * The full known-good config written when no tsconfig.json exists. Mirrors the
+ * repo's own framework apps so a fresh project type-checks predictably.
+ */
+const DEFAULT_TSCONFIG = {
+  compilerOptions: {
+    target: ES_BASELINE,
+    lib: [...DOM_LIBS, ES_BASELINE],
+    module: 'esnext',
+    moduleResolution: 'bundler',
+    jsx: 'react-jsx',
+    strict: true,
+    esModuleInterop: true,
+    skipLibCheck: true,
+    resolveJsonModule: true,
+    isolatedModules: true,
+    moduleDetection: 'force',
+  },
+  include: ['src', 'app'],
+}
+
+export interface TsconfigInspection {
+  file: string
+  exists: boolean
+  unreadable?: boolean
+  effective?: Record<string, unknown>
+  changes: TsconfigChange[]
+}
+
+export interface TsconfigResult {
+  file: string
+  created: boolean
+  changes: TsconfigChange[]
+  wrote: boolean
+  unreadable?: boolean
+}
+
+function readJsonc(file: string): TsconfigDoc {
+  const data = parse(readFileSync(file, 'utf8'))
+  // comment-json happily parses valid-but-non-object JSON (null, true, []). Treat
+  // those as unreadable so callers don't crash on later property reads.
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    throw new Error('tsconfig.json is not an object')
+  }
+  return data as unknown as TsconfigDoc
+}
+
+/**
+ * Picks the tsconfig file to edit. Solution-style configs (Vite) keep their
+ * real options in a referenced file, so we follow the first reference that
+ * actually carries compilerOptions.
+ */
+export function resolveTargetTsconfig(cwd: string): {
+  file: string
+  exists: boolean
+  unreadable?: boolean
+} {
+  const root = join(cwd, 'tsconfig.json')
+  if (!existsSync(root)) return {file: root, exists: false}
+
+  let data: TsconfigDoc
+  try {
+    data = readJsonc(root)
+  } catch {
+    return {file: root, exists: true, unreadable: true}
+  }
+
+  const hasOwnOptions = data.compilerOptions && Object.keys(data.compilerOptions).length > 0
+  if (hasOwnOptions || !Array.isArray(data.references)) {
+    return {file: root, exists: true}
+  }
+
+  const referenced = data.references
+    .map((ref) => ref.path)
+    .filter((p): p is string => typeof p === 'string')
+    .map((p) => join(cwd, p.endsWith('.json') ? p : join(p, 'tsconfig.json')))
+    .filter((p) => existsSync(p))
+
+  // Keep only references we can parse and that actually carry compilerOptions, so
+  // we never write into a reference that has none or crash on an unreadable one.
+  // Prefer an "app" config, the common Vite solution-style layout.
+  const withOptions = referenced.filter((p) => {
+    try {
+      const doc = readJsonc(p)
+      return Boolean(doc.compilerOptions && Object.keys(doc.compilerOptions).length > 0)
+    } catch {
+      return false
+    }
+  })
+
+  const appConfig = withOptions.find((p) => p.includes('app')) ?? withOptions[0]
+  return {file: appConfig ?? root, exists: true}
+}
+
+/** Merges compilerOptions across the resolvable `extends` chain (relative paths only). */
+function effectiveCompilerOptions(file: string, seen = new Set<string>()): Record<string, unknown> {
+  if (!existsSync(file) || seen.has(file)) return {}
+  seen.add(file)
+
+  let data: TsconfigDoc
+  try {
+    data = readJsonc(file)
+  } catch {
+    return {}
+  }
+
+  const base: Record<string, unknown> = {}
+  const extendsField = data.extends
+  const extendsList = Array.isArray(extendsField)
+    ? extendsField
+    : extendsField
+      ? [extendsField]
+      : []
+  for (const ext of extendsList) {
+    if (typeof ext !== 'string') continue
+    if (ext.startsWith('.') || isAbsolute(ext)) {
+      const resolved = isAbsolute(ext) ? ext : resolve(dirname(file), ext)
+      const withExt = resolved.endsWith('.json') ? resolved : `${resolved}.json`
+      Object.assign(base, effectiveCompilerOptions(withExt, seen))
+    }
+  }
+
+  return {...base, ...data.compilerOptions}
+}
+
+function libIncludes(libs: unknown, name: string): boolean {
+  if (!Array.isArray(libs)) return false
+  return libs.some((entry) => String(entry).toLowerCase() === name.toLowerCase())
+}
+
+function hasEsBaseline(libs: unknown): boolean {
+  if (!Array.isArray(libs)) return false
+  return libs.some((entry) => /^es(\d{4}|next)$/i.test(String(entry)))
+}
+
+/**
+ * Compares effective options against the minimum a project needs to consume
+ * this package and returns the changes to make. Pure: callers decide whether to
+ * apply them.
+ *
+ * Only options that actually break consumption are touched, so merging into an
+ * existing project never introduces type errors in the user's own code:
+ *   - jsx: required to compile .tsx
+ *   - moduleResolution: required to read the package exports map + its types
+ *   - module: must stay compatible with a bundler resolution
+ *   - lib: DOM/DOM.Iterable back the component element types
+ *   - skipLibCheck: only ever removes errors, safe to add
+ *
+ * `load: true` marks the load-bearing changes that doctor reports as failures.
+ */
+export function planTsconfigChanges(effective: Record<string, unknown>): TsconfigChange[] {
+  const changes: TsconfigChange[] = []
+  const opts = effective
+
+  const jsx = opts['jsx']
+  if (!jsx) changes.push({key: 'jsx', from: undefined, to: 'react-jsx', load: true})
+  else if (typeof jsx !== 'string' || !VALID_JSX.has(jsx)) {
+    changes.push({key: 'jsx', from: jsx, to: 'react-jsx', load: true})
+  }
+
+  const resolution = opts['moduleResolution']
+  const resolutionLower = typeof resolution === 'string' ? resolution.toLowerCase() : null
+  const resolutionIsModern = Boolean(resolutionLower && MODERN_RESOLUTIONS.has(resolutionLower))
+  let willSetBundler = false
+  if (!resolution) {
+    changes.push({key: 'moduleResolution', from: undefined, to: 'bundler', load: true})
+    willSetBundler = true
+  } else if (!resolutionIsModern) {
+    changes.push({key: 'moduleResolution', from: resolution, to: 'bundler', load: true})
+    willSetBundler = true
+  }
+
+  // module only matters when resolution is (or becomes) bundler, which requires
+  // esnext/preserve/es2015+. node16/nodenext pair with their own module values,
+  // so we leave those alone.
+  const resolutionWillBeBundler = willSetBundler || resolutionLower === 'bundler'
+  const module = opts['module']
+  const moduleLower = typeof module === 'string' ? module.toLowerCase() : null
+  const moduleCompatible = Boolean(moduleLower && BUNDLER_MODULES.has(moduleLower))
+  // Only enforce module when resolution is (or becomes) bundler. node16/nodenext
+  // pair with their own module values, so a missing or non-bundler module under
+  // those resolutions is left alone rather than forced to esnext (which would be
+  // an invalid combination and could change a NodeNext project's semantics).
+  if (resolutionWillBeBundler && !moduleCompatible) {
+    changes.push({key: 'module', from: module, to: 'esnext', load: true})
+  }
+
+  const lib = opts['lib']
+  if (lib === undefined) {
+    changes.push({key: 'lib', from: undefined, to: [...DOM_LIBS, ES_BASELINE], load: true})
+  } else {
+    const missing = DOM_LIBS.filter((entry) => !libIncludes(lib, entry))
+    if (!hasEsBaseline(lib)) missing.push(ES_BASELINE)
+    if (missing.length > 0) {
+      changes.push({key: 'lib', from: lib, to: missing, merge: true, load: true})
+    }
+  }
+
+  if (opts['skipLibCheck'] === undefined) {
+    changes.push({key: 'skipLibCheck', from: undefined, to: true})
+  }
+
+  return changes
+}
+
+/** Read-only: what would `init` change about tsconfig? Used by `doctor` too. */
+export function inspectTsconfig(cwd: string): TsconfigInspection {
+  const target = resolveTargetTsconfig(cwd)
+  if (!target.exists) {
+    return {file: target.file, exists: false, changes: planTsconfigChanges({})}
+  }
+  if (target.unreadable) {
+    return {file: target.file, exists: true, unreadable: true, changes: []}
+  }
+  const effective = effectiveCompilerOptions(target.file)
+  return {file: target.file, exists: true, effective, changes: planTsconfigChanges(effective)}
+}
+
+/**
+ * Applies the required options. Existing comments and unrelated settings are
+ * preserved (comment-json round-trips them). Returns what happened.
+ */
+export function reconcileTsconfig(cwd: string, {dryRun = false} = {}): TsconfigResult {
+  const target = resolveTargetTsconfig(cwd)
+
+  if (!target.exists) {
+    if (!dryRun) {
+      writeFileSync(target.file, `${JSON.stringify(DEFAULT_TSCONFIG, null, 2)}\n`)
+    }
+    return {file: target.file, created: true, changes: [], wrote: !dryRun}
+  }
+
+  if (target.unreadable) {
+    return {file: target.file, created: false, changes: [], wrote: false, unreadable: true}
+  }
+
+  const effective = effectiveCompilerOptions(target.file)
+  const changes = planTsconfigChanges(effective)
+  if (changes.length === 0) {
+    return {file: target.file, created: false, changes, wrote: false}
+  }
+
+  if (!dryRun) {
+    const doc = readJsonc(target.file)
+    const options: Record<string, unknown> = doc.compilerOptions ?? {}
+    doc.compilerOptions = options
+    for (const change of changes) {
+      if (change.merge && change.key === 'lib') {
+        const current = Array.isArray(options['lib']) ? (options['lib'] as unknown[]) : []
+        options['lib'] = [...current, ...(change.to as unknown[])]
+      } else {
+        options[change.key] = change.to
+      }
+    }
+    writeFileSync(target.file, `${stringify(doc, null, 2)}\n`)
+  }
+
+  return {file: target.file, created: false, changes, wrote: !dryRun}
+}