@sanity/plugin-kit 0.0.1-studio-v3.1

package/src/actions/verify-studio.ts

@@ -0,0 +1,55 @@
+import {getPackage} from '../npm/package'
+import log from '../util/log'
+import {readJson5File} from '../util/files'
+import {cliName, urls} from '../constants'
+import {validateImports} from '../dependencies/import-linter'
+import outdent from 'outdent'
+import chalk from 'chalk'
+import {
+  createValidator,
+  runTscMaybe,
+  VerifyFlags,
+  VerifyPackageConfig,
+} from './verify/verify-common'
+import {PackageJson, TsConfig} from './verify/types'
+import {validateSanityDependencies, validateStudioConfig} from './verify/validations'
+
+export async function verifyStudio({basePath, flags}: {basePath: string; flags: VerifyFlags}) {
+  let errors: string[] = []
+
+  const packageJson: PackageJson = await getPackage({basePath, validate: false})
+  const verifyConfig: VerifyPackageConfig = packageJson.sanityPlugin?.verifyPackage || {}
+
+  const validation = createValidator(verifyConfig, flags, errors)
+
+  const tsConfig = await readJson5File<TsConfig>({basePath, filename: 'tsconfig.json'})
+
+  await validation('studioConfig', async () => validateStudioConfig({basePath}))
+  await validation('dependencies', async () => validateSanityDependencies(packageJson))
+  await validation('eslintImports', async () => validateImports({basePath}))
+
+  if (errors.length) {
+    throw new Error(
+      outdent`
+        Detected validation issues!
+        This Sanity Studio is not completely V3 ready. Fix the issues starting from the top, or disable any checks you deem unnecessary.
+
+        More information is available here:
+        - Migration guide: ${urls.migrationGuideStudio}
+        - Reference documentation: ${urls.refDocs}
+
+        ${chalk.grey(
+          `To fail-fast on first detected issue run:\nnpx ${cliName} verify-studio --single`
+        )}
+      `.trimStart()
+    )
+  }
+
+  await runTscMaybe(verifyConfig, tsConfig)
+
+  log.success(
+    outdent`
+    No outstanding upgrade issues detected. Studio is V3 ready!
+  `.trim()
+  )
+}

package/src/actions/verify.ts

@@ -0,0 +1,328 @@
+/*
+import path from 'path'
+//@ts-expect-error missing types
+import spdxLicenseIds from 'spdx-license-ids'
+import semver from 'semver'
+
+import log from '../util/log'
+import {fileExists, readJsonFile} from '../util/files'
+import {readManifest, getReferencesPartPaths} from '../sanity/manifest'
+import {getPackage, getReferencedPaths} from '../npm/package'
+import {getPublishableFiles} from '../npm/publish'
+import {findDependencies} from '../dependencies/find'
+import {uselessFiles} from '../configs/uselessFiles'
+
+export async function verify({basePath, flags}) {
+  const pkg = await getPackage({basePath, flags})
+  const manifest = await readManifest({
+    basePath,
+    pluginName: pkg.name,
+    flags,
+    verifyCompiledParts: true,
+    verifySourceParts: true,
+  })
+
+  // Get all files intended to be published from npm
+  const publishableFiles = await getPublishableFiles(basePath)
+
+  // Errors
+  await verifyPublishableFiles({basePath, pkg, manifest, publishableFiles})
+  await verifyLicenseKey(pkg)
+  await verifyPluginConfig(basePath)
+  await verifyImports({pkg, manifest, basePath})
+
+  // Warnings
+  const hasWarnings = await warnOnUselessFiles(publishableFiles)
+
+  // Huzzah
+  log.success(
+    hasWarnings
+      ? 'Plugin has warnings, but looks good to publish!'
+      : 'Plugin looks good to publish!'
+  )
+}
+
+async function verifyPublishableFiles({pkg, manifest, basePath, publishableFiles}) {
+  // Validate that these files exists, not just that they are publishable
+  if (!(await fileExists(path.resolve(basePath, 'README.md')))) {
+    throw new Error(
+      `This plugin does not contain a README.md, which is required for Sanity plugins.`
+    )
+  }
+
+  const [hasLicense, hasLicenseMd] = await Promise.all([
+    fileExists(path.resolve(basePath, 'LICENSE')),
+    fileExists(path.resolve(basePath, 'LICENSE.md')),
+  ])
+
+  if (!hasLicense && !hasLicenseMd) {
+    throw new Error(
+      `This plugin does not contain a LICENSE-file, which is required for Sanity plugins.`
+    )
+  }
+
+  // Always, uhm... "kindly suggest", to include these files
+  const files = ['README.md']
+    // Get files from parts as well as the ones references in package.json
+    .concat(getReferencesPartPaths(manifest, basePath), getReferencedPaths(pkg, basePath))
+    // Make all paths relative to base path
+    .map((file) =>
+      path.relative(basePath, path.isAbsolute(file) ? file : path.resolve(basePath, file))
+    )
+    // Remove duplicates
+    .filter((file, index, arr) => arr.indexOf(file, index + 1) === -1)
+
+  // Verify that all explicitly referenced files are publishable
+  const unpublishable = files.filter((file) => !publishableFiles.includes(file))
+
+  // Warn with "default error" for unknowns
+  const unknowns = unpublishable.filter((item) => item !== 'README.md').map((file) => `"${file}"`)
+
+  if (unknowns.length > 0) {
+    const paths = unknowns.join(', ')
+    throw new Error(
+      `This plugin references files that are ignored from being published: ${paths}. Check .gitignore, .npmignore and/or the "files" property of package.json. See https://docs.npmjs.com/using-npm/developers.html#keeping-files-out-of-your-package for more information.`
+    )
+  }
+}
+
+function verifyLicenseKey(pkg) {
+  if (!pkg.license) {
+    throw new Error(
+      `package.json is missing "license" key: see https://docs.npmjs.com/files/package.json#license and make sure it matches your "LICENSE" file. See https://choosealicense.com/ for help on choosing a license.`
+    )
+  }
+
+  if (pkg.license !== 'UNLICENSED' && !spdxLicenseIds.includes(pkg.license)) {
+    throw new Error(
+      `package.json has an invalid "license" key: it should be either an SPDX license ID (https://spdx.org/licenses/) or "UNLICENSE". See https://docs.npmjs.com/files/package.json#license and refer to https://choosealicense.com/ for help on choosing a license.`
+    )
+  }
+}
+
+async function verifyPluginConfig(basePath) {
+  const configPath = path.join(basePath, 'config.dist.json')
+  if (!(await fileExists(configPath))) {
+    return
+  }
+
+  let config
+  try {
+    config = await readJsonFile(configPath)
+  } catch (err: any) {
+    throw new Error(`Error reading plugin config (${configPath}): ${err.message}`)
+  }
+
+  if (typeof config !== 'object' || Array.isArray(config) || !config) {
+    throw new Error(
+      `Error reading plugin config (${configPath}): must be an object, got:\n${JSON.stringify(
+        config,
+        null,
+        2
+      )}`
+    )
+  }
+}
+
+function warnOnUselessFiles(files) {
+  const warnFor = files
+    .filter(
+      (file) =>
+        uselessFiles.includes(file) ||
+        uselessFiles.some((useless) => file.startsWith(`${useless}/`))
+    )
+    .map((file) => `"${file}"`)
+    .join(', ')
+
+  if (warnFor.length === 0) {
+    return false
+  }
+
+  log.warn(
+    `This plugin is set to publish the following files, which are generally not needed in a published npm module: ${warnFor}.`
+  )
+  log.warn(
+    `Consider adding these files to an .npmignore or the package.json "files" property. See https://docs.npmjs.com/using-npm/developers.html#keeping-files-out-of-your-package for more information.`
+  )
+
+  return true
+}
+
+async function verifyImports({pkg, manifest, basePath}) {
+  // "Entry" as in... code may start here.
+  const entries = ([] as string[])
+    .concat(
+      getReferencedPaths(pkg, basePath), // From npm
+      getReferencesPartPaths(manifest, basePath) // From parts
+    )
+    // Remove duplicates
+    .filter((file, index, arr) => arr.indexOf(file, index + 1) === -1)
+    // Remove non-javascript/non-css entries
+    .filter((file) => ['.js', '.css'].includes(path.extname(file)))
+
+  const dependencies = findDependencies(entries)
+  const modules = dependencies.filter((dep) => !/^(all|part|config|sanity):/.test(dep))
+
+  await verifyNoUndeclaredDependencies(modules, pkg)
+  await verifyReactDependencies(modules, pkg)
+  await verifyUiDependencies(modules, pkg)
+  await verifyConfigParts(dependencies, pkg, basePath)
+  await verifyNoUnusedDependencies(modules, pkg)
+  await verifyNoUndeclaredParts(dependencies, pkg, manifest)
+}
+
+function verifyNoUndeclaredParts(dependencies, pkg, manifest) {
+  const parts = dependencies
+    .filter((dep) => dep.startsWith('all:') || dep.startsWith('part:'))
+    .map((part) => part.replace(/^all:/, ''))
+    .map((part) => part.replace(/\?$/, ''))
+    .filter((part) => part.startsWith(`part:${pkg.name.replace(/^sanity-plugin-/, '')}`))
+
+  const declaredParts = (manifest.parts || []).reduce(
+    (partNames, part) => [...partNames, ...[part.name, part.implements].filter(Boolean)],
+    []
+  )
+  const undeclaredParts = parts.filter((partName) => !declaredParts.includes(partName))
+
+  if (undeclaredParts.length > 0) {
+    const aPart = undeclaredParts.length > 1 ? 'parts' : 'a part'
+    const is = undeclaredParts.length > 1 ? 'are' : 'is'
+    const partList = undeclaredParts.map((part) => `"${part}"`).join(', ')
+    throw new Error(
+      `Invalid plugin: Source is using ${aPart} that ${is} not declared in "sanity.json":\n\n${partList}.`
+    )
+  }
+}
+
+function verifyNoUnusedDependencies(modules, pkg) {
+  const potentiallyUnused = Object.keys(pkg.dependencies || {}).filter(
+    (dep) => !modules.includes(dep)
+  )
+
+  if (potentiallyUnused.length > 0) {
+    const unusedNames = potentiallyUnused.map((dep) => `"${dep}"`).join(', ')
+    log.warn(`Found modules listed as dependencies which seem to be unused by code: ${unusedNames}`)
+  }
+}
+
+function verifyReactDependencies(modules, pkg) {
+  if (modules.includes('react') && 'react' in (pkg.dependencies || {})) {
+    throw new Error(
+      `Invalid plugin: "react" declared as a dependency - it should be declared as a peerDependency (package.json)`
+    )
+  }
+
+  if (modules.includes('react-dom') && 'react-dom' in (pkg.dependencies || {})) {
+    throw new Error(
+      `Invalid plugin: "react-dom" declared as a dependency - it should be declared as a peerDependency (package.json)`
+    )
+  }
+
+  if (modules.includes('prop-types') && 'prop-types' in (pkg.peerDependencies || {})) {
+    throw new Error(
+      `Invalid plugin: "prop-types" declares as peerDependency - it should be declared as a dependency (package.json)`
+    )
+  }
+}
+
+function verifyUiDependencies(modules, pkg) {
+  const peerDependencies = pkg.peerDependencies || {}
+  const dependencies = pkg.dependencies || {}
+
+  if (modules.includes('@sanity/ui') && '@sanity/ui' in peerDependencies) {
+    throw new Error(
+      `Invalid plugin: "@sanity/ui" declared as a peer dependency - it should be declared as a dependency (package.json)`
+    )
+  }
+
+  if (
+    modules.includes('@sanity/ui') &&
+    dependencies['@sanity/ui'] &&
+    semver.lt(semver.minVersion(dependencies['@sanity/ui']), '0.33.1')
+  ) {
+    throw new Error(
+      `Invalid plugin: "@sanity/ui" dependency must use version higher than or equal to 0.33.1 (package.json)`
+    )
+  }
+
+  if (modules.includes('@sanity/icons') && '@sanity/icons' in peerDependencies) {
+    throw new Error(
+      `Invalid plugin: "@sanity/icons" declared as a peer dependency - it should be declared as a dependency (package.json)`
+    )
+  }
+}
+
+async function verifyConfigParts(dependencies, pkg, basePath) {
+  const configName = `config:${pkg.name.replace(/^sanity-plugin-/, '')}`
+  if (
+    dependencies.includes(configName) &&
+    !(await fileExists(path.join(basePath, 'config.dist.json')))
+  ) {
+    throw new Error(
+      `Plugin imports plugin config (${configName}) but does not contain a "config.dist.json" file.`
+    )
+  }
+
+  const nonPluginConfigs = dependencies.filter(
+    (dep) => dep.startsWith('config:') && dep !== configName
+  )
+
+  if (nonPluginConfigs.length > 0) {
+    const configs = nonPluginConfigs.length > 1 ? 'configs' : 'config'
+    const nonPluginConfigNames = nonPluginConfigs.join(', ')
+    log.warn(
+      `Found references to external ${configs}: ${nonPluginConfigNames} - this is generally considered unsafe`
+    )
+  }
+}
+
+function verifyNoUndeclaredDependencies(modules, pkg) {
+  const undeclared = getUndeclaredDependencies(modules, pkg)
+  if (undeclared.length > 0) {
+    throw new Error(getUndeclaredDependenciesError(undeclared))
+  }
+}
+
+function getUndeclaredDependencies(modules, pkg) {
+  const deps = ([] as string[]).concat(
+    Object.keys(pkg.dependencies || {}),
+    Object.keys(pkg.peerDependencies || {})
+  )
+
+  const devDeps = Object.keys(pkg.devDependencies || {})
+
+  return modules
+    .filter((modDep) => !deps.includes(modDep))
+    .map((modDep) => ({
+      dependency: modDep,
+      isDevDep: devDeps.includes(modDep),
+    }))
+}
+
+function getUndeclaredDependenciesError(undeclared) {
+  const baseError = `Invalid plugin`
+  const moduleNames = undeclared.map((mod) => mod.dependency)
+
+  let declaredWhere = `should be declared in package.json under "dependencies" or "peerDependencies".`
+  if (moduleNames.length === 1 && moduleNames[0] === 'react') {
+    declaredWhere = `should be declared in package.json under "peerDependencies"`
+  } else if (moduleNames.includes('react')) {
+    declaredWhere = `should either be declared in package.json under "dependencies" or "peerDependencies" (react should be in "peerDependencies").`
+  }
+
+  const devDeps = undeclared.filter((dep) => dep.isDevDep).map((dep) => `  - ${dep.dependency}\n`)
+  if (devDeps.length > 0) {
+    const modules = devDeps.length > 1 ? 'modules' : 'module'
+    const depList = devDeps.join('')
+    const target = devDeps.length > 1 ? 'They' : 'It'
+    const are = devDeps.length > 1 ? 'are' : 'is'
+    return `${baseError}: Source uses ${modules} that ${are} declared in "devDependencies":\n\n${depList}\n${target} ${declaredWhere}`
+  }
+
+  const modules = undeclared.length > 1 ? 'modules' : 'module'
+  const depList = undeclared.map((dep) => `  - ${dep.dependency}\n`).join('')
+  const target = undeclared.length > 1 ? 'They' : 'It'
+  const are = undeclared.length > 1 ? 'are' : 'is'
+  return `${baseError}: Source uses ${modules} that ${are} not declared as dependencies:\n\n${depList}\n${target} ${declaredWhere}`
+}
+*/

package/src/cli.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+'use strict'
+import meow from 'meow'
+import log from './util/log'
+import commands from './cmds'
+import sharedFlags from './sharedFlags'
+import {cliName} from './constants'
+
+export async function cliEntry(argv = process.argv, autoExit = true) {
+  const cli = meow(
+    `
+	Usage
+	  $ ${cliName} [--help] [--debug] <command> [<args>]
+
+  These are common commands used in various situations:
+
+    init            Create a new Sanity plugin
+    verify-package  Check that a Sanity plugin package follows V3 conventions. Prints upgrade steps.
+    verify-studio   Check that a Sanity Studio follows V3 conventions. Prints upgrade steps.
+    link-watch      Recompiles plugin automatically on changes and runs yalc push --publish
+    version         Show the version of ${cliName} currently installed
+
+  Options
+    --silent        Do not print info and warning messages
+    --verbose       Log everything. This option conflicts with --silent
+    --debug         Print stack trace on errors
+    --version       Output the version number
+    --help          Output usage information
+
+  Examples
+    # Init a new plugin in current directory
+    $ ${cliName} init
+
+    # Init a new plugin in my-sanity-plugin directory
+    $ ${cliName} init my-sanity-plugin
+
+    # Check that a Sanity plugin package in current directory follows V3 conventions
+    $ ${cliName} verify-package
+
+    # Check that a Sanity Studio in current directory  follows V3 conventions
+    $ ${cliName} verify-studio
+`,
+    {
+      autoHelp: false,
+      flags: sharedFlags,
+      argv: argv.slice(2),
+    }
+  )
+
+  const commandName = cli.input[0]
+  if (!commandName) {
+    cli.showHelp() // Exits
+  }
+
+  if (!(commandName in commands)) {
+    console.error(`Unknown command "${commandName}"`)
+    cli.showHelp() // Exits
+  }
+
+  if (cli.flags.silent && cli.flags.verbose) {
+    log.error(`--silent and --verbose are mutually exclusive`)
+    cli.showHelp() // Exits
+  }
+
+  // Lazy-load command
+  const cmd = require(commands[commandName as keyof typeof commands]).default
+
+  try {
+    log.setVerbosity(cli.flags)
+    await cmd({argv: argv.slice(3)})
+  } catch (err: any) {
+    log.error(err instanceof TypeError || cli.flags.debug ? err.stack : err.message)
+
+    // eslint-disable-next-line no-process-exit
+    process.exit(1)
+  }
+}

package/src/cmds/index.ts

@@ -0,0 +1,9 @@
+export default {
+  init: require.resolve('./init'),
+  'link-watch': require.resolve('./link-watch'),
+  'verify-package': require.resolve('./verify-package'),
+  'verify-studio': require.resolve('./verify-studio'),
+  version: require.resolve('./version'),
+  // wont make it for initial release
+  //splat: require.resolve('./splat'),
+}

package/src/cmds/init.ts

@@ -0,0 +1,85 @@
+import path from 'path'
+import meow from 'meow'
+import log from '../util/log'
+import {init, initFlags} from '../actions/init'
+import {isEmptyish, ensureDir} from '../util/files'
+import {installDependencies, promptForPackageManager} from '../npm/manager'
+import {findStudioV3Config, hasSanityJson} from '../sanity/manifest'
+import {prompt} from '../util/prompt'
+import {cliName} from '../constants'
+
+const description = `Initialize a new Sanity plugin`
+
+const help = `
+Usage
+  $ ${cliName} init [dir] [<args>]
+
+Options
+  --no-eslint             Disables ESLint config and dependencies from being added
+  --no-prettier           Disables prettier config and dependencies from being added
+  --no-typescript         Disables typescript config and dependencies from being added
+  --no-license            Disables LICENSE + package.json license field from being added
+  --no-editorconfig       Disables .editorconfig from being added
+  --no-gitignore          Disables .gitignore from being added
+  --no-scripts            Disables scripts from being added to package.json
+  --no-install            Disables automatically running package manager install
+
+  --name [package-name]   Use the provided package-name
+  --author [name]         Use the provided author
+  --repo [url]            Use the provided repo url
+  --license [spdx]        Use the license with the given SPDX identifier
+  --force                 No promt when overwriting files
+
+Examples
+  # Initialize a new plugin in the current directory
+  $ ${cliName} init
+
+  # Initialize a plugin in the directory ~/my-plugin
+  $ ${cliName} init ~/my-plugin
+
+  # Don't add eslint or prettier
+  $ ${cliName} init --no-eslint --no-prettier
+`
+
+async function run({argv}: {argv: string[]}) {
+  const cli = meow(help, {flags: initFlags, argv, description})
+  const basePath = path.resolve(cli.input[0] || process.cwd())
+
+  const {exists, isRoot} = await hasSanityJson(basePath)
+  if (exists && isRoot) {
+    throw new Error(
+      `sanity.json has a "root" property set to true - are you trying to init into a studio instead of a plugin?`
+    )
+  }
+
+  const {v3ConfigFile} = await findStudioV3Config(basePath)
+  if (v3ConfigFile) {
+    throw new Error(
+      `${v3ConfigFile} exsists - are you trying to init into a studio instead of a plugin?`
+    )
+  }
+
+  log.info('Initializing new plugin in "%s"', basePath)
+  if (
+    !cli.flags.force &&
+    !(await isEmptyish(basePath)) &&
+    !(await prompt('Directory is not empty, proceed?', {type: 'confirm', default: false}))
+  ) {
+    log.error('Directory is not empty. Cancelled.')
+    return
+  }
+
+  await ensureDir(basePath)
+  await init({basePath, flags: cli.flags})
+  if (cli.flags.install) {
+    if (await installDependencies(await promptForPackageManager(), {cwd: basePath})) {
+      log.info('Done!')
+    } else {
+      log.error('Failed to install dependencies, try manually running `npm install`')
+    }
+  } else {
+    log.info('Dependency installation skipped.')
+  }
+}
+
+export default run

package/src/cmds/link-watch.ts

@@ -0,0 +1,51 @@
+import path from 'path'
+import meow from 'meow'
+import pkg from '../../package.json'
+import sharedFlags from '../sharedFlags'
+import {linkWatch} from '../actions/link-watch'
+
+const description = `Run the watch command and pushes any changes to yalc`
+
+const help = `
+Usage
+  $ ${pkg.binname} link-watch [<args>]
+
+Options
+  --silent      Do not print info and warning messages
+  --verbose     Log everything. This option conflicts with --silent
+  --version     Output the version number
+  --help        Output usage information
+
+Configuration
+To override the default watch command configuration, provide an override in package.json under sanityPlugin:
+{
+  "sanityPlugin": {
+    "watchCommand": "microbundle watch --format modern,esm,cjs --jsx React.createElement --jsxImportSource react --css inline",
+    "linkWatch": {
+      "folder": "lib",
+      "command": "npm run watch",
+      "extensions": "js,png,svg,gif,jpeg,css"
+    }
+  }
+}
+
+Examples
+  # Run the watch command and pushes any changes to yalc
+  $ ${pkg.binname} link-watch
+`
+
+const flags = {
+  ...sharedFlags,
+  watch: {
+    type: 'boolean',
+    default: false,
+  },
+} as const
+
+function run({argv}: {argv: string[]}) {
+  const cli = meow(help, {flags, argv, description})
+  const basePath = path.resolve(cli.input[0] || process.cwd())
+  return linkWatch({basePath})
+}
+
+export default run

package/src/cmds/splat.ts

@@ -0,0 +1,59 @@
+import path from 'path'
+import meow from 'meow'
+import pkg from '../../package.json'
+import log from '../util/log'
+import {splat} from '../actions/splat'
+import {hasSanityJson} from '../sanity/manifest'
+import sharedFlags from '../sharedFlags'
+import {initFlags} from '../actions/init'
+
+const description = `"Splat" configuration into a Sanity plugin`
+
+const help = `
+Usage
+  $ ${pkg.binname} splat [dir]  [<args>]
+
+Options
+  --no-eslint        Disables ESLint config and dependencies from being added
+  --no-prettier      Disables prettier config and dependencies from being added
+  --no-typescript    Disables typescript config and dependencies from being added
+  --no-license       Disables LICENSE + package.json license field from being added
+  --no-editorconfig  Disables .editorconfig from being added
+  --no-gitignore     Disables .gitignore from being added
+  --no-scripts       Disables scripts from being added to package.json
+  --license [spdx]   Use the license with the given SPDX identifier
+
+Examples
+  # Splat configuration into the plugin in the current directory
+  $ ${pkg.binname} splat
+
+  # Splat configuration into the plugin in ~/my-plugin
+  $ ${pkg.binname} splat ~/my-plugin
+
+  # Don't add eslint or prettier
+  $ ${pkg.binname} splat --no-eslint --no-prettier
+`
+
+async function run({argv}: {argv: string[]}) {
+  const cli = meow(help, {flags: initFlags, argv, description})
+  const basePath = path.resolve(cli.input[0] || process.cwd())
+
+  const {exists, isRoot} = await hasSanityJson(basePath)
+  if (exists && isRoot) {
+    throw new Error(
+      `sanity.json has a "root" property set to true - are you trying to splat into a studio instead of a plugin?`
+    )
+  }
+
+  if (!exists) {
+    throw new Error(
+      `sanity.json does not exist in this directory, maybe you want "${pkg.binname} init" instead?`
+    )
+  }
+
+  await splat({basePath, flags: cli.flags})
+
+  log.info('Done!')
+}
+
+export default run