@sanity/pkg-utils 1.0.0

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@sanity/pkg-utils",
+  "version": "1.0.0",
+  "author": "Sanity.io <hello@sanity.io>",
+  "license": "MIT",
+  "description": "Simple utilities for modern npm packages.",
+  "keywords": [
+    "sanity-io",
+    "sanity",
+    "npm",
+    "package",
+    "utilities",
+    "build",
+    "bundling"
+  ],
+  "source": "./src/index.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "pkg-utils": "./bin/pkg-utils"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "node -r esbuild-register src/cli.ts build --extract --tsconfig tsconfig.dist.json",
+    "format": "prettier --write --cache --ignore-unknown .",
+    "lint": "eslint . --ext .cjs,.js,.ts",
+    "prebuild": "rimraf dist",
+    "prepublishOnly": "pnpm run build",
+    "release": "semantic-release",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@microsoft/api-extractor": "^7.29.5",
+    "@microsoft/tsdoc-config": "^0.16.1",
+    "@rollup/plugin-commonjs": "^22.0.2",
+    "@rollup/plugin-json": "^4.1.0",
+    "@rollup/plugin-node-resolve": "^13.3.0",
+    "@sanity/tsdoc-to-portable-text": "^0.4.1",
+    "cac": "^6.7.12",
+    "chalk": "^4.1.2",
+    "esbuild": "^0.15.5",
+    "esbuild-register": "^3.3.3",
+    "jsonc-parser": "^3.1.0",
+    "mkdirp": "^1.0.4",
+    "pkg-up": "^3.1.0",
+    "rimraf": "^3.0.2",
+    "rollup": "^2.78.1",
+    "rollup-plugin-esbuild": "^4.9.3"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^17.0.3",
+    "@commitlint/config-conventional": "^17.0.3",
+    "@sanity/semantic-release-preset": "^2.0.0",
+    "@types/cpx": "^1.5.2",
+    "@types/mkdirp": "^1.0.2",
+    "@types/node": "^18.7.13",
+    "@types/rimraf": "^3.0.2",
+    "@types/tmp": "^0.2.3",
+    "@typescript-eslint/eslint-plugin": "^5.35.1",
+    "@typescript-eslint/parser": "^5.35.1",
+    "commitizen": "^4.2.5",
+    "cpx": "^1.5.0",
+    "eslint": "^8.23.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "husky": "^8.0.1",
+    "lint-staged": "^12.5.0",
+    "prettier": "^2.7.1",
+    "semantic-release": "^19.0.5",
+    "tmp": "^0.2.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.7.4",
+    "vitest": "^0.22.1"
+  },
+  "peerDependencies": {
+    "typescript": "^4.7"
+  },
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "lint-staged": {
+    "*": [
+      "prettier --write --cache --ignore-unknown"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/sanity-io/pkg-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sanity-io/pkg-utils/issues"
+  },
+  "homepage": "https://github.com/sanity-io/pkg-utils#readme"
+}

package/src/build/_parseTasks.ts

@@ -0,0 +1,85 @@
+import path from 'path'
+import {PackageSubPathExportEntry} from '../core'
+import {_BuildContext} from './_types'
+import {_RollupTask, _BuildTask, _DtsTask} from './tasks'
+
+/**
+ * @internal
+ */
+export function _parseTasks(ctx: _BuildContext): _BuildTask[] {
+  const {pkg} = ctx
+
+  const entries = Object.entries(ctx.exports || {}).map(
+    ([path, entry]) => ({path, ...entry} as PackageSubPathExportEntry & {path: string})
+  )
+
+  const dtsTasks: Record<string, _DtsTask> = {}
+  const rollupTasks: Record<string, _RollupTask> = {}
+
+  // Parse `dts` tasks
+  for (const entry of entries) {
+    const exportId = path.join(pkg.name, entry.path)
+
+    if (entry.types) {
+      if (!dtsTasks[exportId]) {
+        dtsTasks[exportId] = {
+          type: 'dts',
+          exportId,
+          exportPath: entry.path === '.' ? './index' : entry.path,
+          source: entry.source,
+          output: entry.types,
+        }
+      }
+    }
+  }
+
+  // Parse `rollup` tasks
+  for (const entry of entries) {
+    const format: ('commonjs' | 'esm')[] = []
+    const target: string[] = []
+
+    if (entry.require) {
+      format.push('commonjs')
+    }
+
+    if (entry.default) {
+      format.push('esm')
+    }
+
+    if (entry.runtime === 'node') {
+      target.push('node12')
+    }
+
+    if (entry.runtime === 'web') {
+      target.push('chrome104')
+    }
+
+    for (const f of format) {
+      const buildId = `${entry.runtime}:${f}:${target.join(',')}`
+
+      if (!rollupTasks[buildId]) {
+        rollupTasks[buildId] = {
+          type: 'rollup',
+          buildId,
+          entries: [entry],
+          runtime: entry.runtime,
+          format: f,
+          target,
+        }
+      } else {
+        rollupTasks[buildId].entries.push(entry)
+      }
+    }
+  }
+
+  const tasks: _BuildTask[] = [...Object.values(dtsTasks), ...Object.values(rollupTasks)]
+
+  if (ctx.extract && pkg.types) {
+    tasks.push({
+      type: 'extract',
+      mainEntryPointPath: pkg.types,
+    })
+  }
+
+  return tasks
+}

package/src/build/_types.ts

@@ -0,0 +1,25 @@
+import {PackageExports, PkgConfigOptions, _PackageJSON} from '../core'
+
+/**
+ * @internal
+ */
+export interface _BuildFile {
+  type: 'asset' | 'chunk' | 'types'
+  path: string
+}
+
+/**
+ * @internal
+ */
+export interface _BuildContext {
+  config?: PkgConfigOptions
+  cwd: string
+  exports: PackageExports | undefined
+  external: string[]
+  extract: boolean
+  files: _BuildFile[]
+  dist: string
+  pkg: _PackageJSON
+  src: string
+  tsconfig?: string
+}

package/src/build/build.ts

@@ -0,0 +1,87 @@
+/* eslint-disable no-console */
+
+import path from 'path'
+import chalk from 'chalk'
+import {PackageExports, _loadConfig, _loadPkg, _parseExports, _resolveConfigProperty} from '../core'
+import {_parseTasks} from './_parseTasks'
+import {_BuildContext} from './_types'
+import {_dtsTask, _extractTask, _rollupTask} from './tasks'
+
+/**
+ * @public
+ */
+export async function build(options: {
+  cwd: string
+  extract?: boolean
+  tsconfig?: string
+}): Promise<void> {
+  const {cwd, extract = false, tsconfig = 'tsconfig.json'} = options
+  const pkg = await _loadPkg({cwd})
+  const config = await _loadConfig({cwd})
+
+  // if (!config) {
+  //   console.log('no configuration found')
+  //   return
+  // }
+
+  const parsedExports = _parseExports(pkg).reduce<PackageExports>((acc, x) => {
+    const {path: exportPath, ...exportEntry} = x
+
+    return {...acc, [exportPath]: exportEntry}
+  }, {})
+
+  const exports = config?.exports
+    ? _resolveConfigProperty(config.exports, parsedExports)
+    : parsedExports
+
+  const initialExternal = [
+    ...(pkg.dependencies ? Object.keys(pkg.dependencies) : []),
+    ...(pkg.peerDependencies ? Object.keys(pkg.peerDependencies) : []),
+  ]
+
+  const external = config?.external
+    ? _resolveConfigProperty(config.external, initialExternal)
+    : initialExternal
+
+  const srcPath = path.resolve(cwd, config?.src || 'src')
+  const distPath = path.resolve(cwd, config?.dist || 'dist')
+
+  const context: _BuildContext = {
+    config,
+    cwd,
+    exports,
+    extract,
+    files: [],
+    external,
+    dist: path.relative(cwd, distPath),
+    pkg,
+    src: path.relative(cwd, srcPath),
+    tsconfig,
+  }
+
+  console.log(chalk.gray('cwd       '), context.cwd)
+  // console.log('external ', context.external)
+  console.log(chalk.gray('src       '), context.src)
+  console.log(chalk.gray('dist      '), context.dist)
+  console.log(chalk.gray('tsconfig  '), context.tsconfig)
+
+  if (exports) {
+    const buildTasks = _parseTasks(context)
+
+    for (const task of buildTasks) {
+      if (task.type === 'dts') {
+        await _dtsTask(context, task)
+      }
+
+      if (task.type === 'extract') {
+        await _extractTask(context, task)
+      }
+
+      if (task.type === 'rollup') {
+        await _rollupTask(context, task)
+      }
+    }
+  } else {
+    throw new Error('no exports')
+  }
+}

package/src/build/index.ts

@@ -0,0 +1,2 @@
+export * from './_types'
+export * from './build'

package/src/build/tasks/_types.ts

@@ -0,0 +1,8 @@
+import {_DtsTask} from './dts'
+import {_ExtractTask} from './extract'
+import {_RollupTask} from './rollup'
+
+/**
+ * @internal
+ */
+export type _BuildTask = _DtsTask | _ExtractTask | _RollupTask

package/src/build/tasks/dts/_buildTypes.ts

@@ -0,0 +1,62 @@
+/* eslint-disable no-console */
+
+import path from 'path'
+import ts from 'typescript'
+import {_loadTSConfig} from './_loadTSConfig'
+
+export const formatHost: ts.FormatDiagnosticsHost = {
+  getCurrentDirectory: () => ts.sys.getCurrentDirectory(),
+  getNewLine: () => ts.sys.newLine,
+  getCanonicalFileName: ts.sys.useCaseSensitiveFileNames ? (f) => f : (f) => f.toLowerCase(),
+}
+
+/**
+ * @internal
+ */
+export async function _buildTypes(options: {
+  cwd: string
+  outDir: string
+  sourcePath: string
+  tsconfigPath: string
+}): Promise<{path: string}> {
+  const {cwd, outDir, sourcePath, tsconfigPath} = options
+
+  const config = await _loadTSConfig({cwd, tsconfigPath})
+
+  const compilerOptions: ts.CompilerOptions = {
+    ...config.options,
+    emitDeclarationOnly: true,
+    outDir,
+  }
+
+  const program = ts.createProgram([path.resolve(cwd, sourcePath)], compilerOptions)
+
+  const emitResult = program.emit()
+
+  const allDiagnostics = ts.getPreEmitDiagnostics(program).concat(emitResult.diagnostics)
+
+  allDiagnostics.forEach((diagnostic) => {
+    if (diagnostic.file) {
+      const {line, character} = ts.getLineAndCharacterOfPosition(diagnostic.file, diagnostic.start!)
+      const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')
+
+      console.log(`${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`)
+    } else {
+      console.log(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
+    }
+  })
+
+  if (emitResult.emitSkipped) {
+    const errors = allDiagnostics.filter((diag) => diag.category === ts.DiagnosticCategory.Error)
+
+    if (errors.length) {
+      console.error(ts.formatDiagnostics(errors, formatHost))
+
+      throw new Error('failed to compile')
+    }
+  }
+
+  return {
+    path: path.resolve(outDir, sourcePath.replace(/\.ts$/, '.d.ts')),
+  }
+}

package/src/build/tasks/dts/_createApiExtractorConfig.ts

@@ -0,0 +1,88 @@
+import path from 'path'
+import {ExtractorLogLevel, IConfigFile, IExtractorMessagesConfig} from '@microsoft/api-extractor'
+
+export const DEFAULT_MESSAGES_CONFIG: IExtractorMessagesConfig = {
+  compilerMessageReporting: {
+    default: {
+      logLevel: 'warning' as ExtractorLogLevel,
+    },
+  },
+
+  extractorMessageReporting: {
+    default: {
+      logLevel: 'warning' as ExtractorLogLevel,
+      addToApiReportFile: false,
+    },
+
+    // 'ae-extra-release-tag': {
+    //   logLevel: 'error' as ExtractorLogLevel,
+    //   addToApiReportFile: false
+    // },
+
+    // 'ae-forgotten-export': {
+    //   logLevel: 'error' as ExtractorLogLevel,
+    //   addToApiReportFile: false
+    // }
+  },
+
+  tsdocMessageReporting: {
+    default: {
+      logLevel: 'warning' as ExtractorLogLevel,
+      addToApiReportFile: false,
+    },
+
+    // 'tsdoc-link-tag-unescaped-text': {
+    //   logLevel: 'warning' as ExtractorLogLevel,
+    //   addToApiReportFile: false
+    // },
+
+    // 'tsdoc-unsupported-tag': {
+    //   logLevel: 'none' as ExtractorLogLevel,
+    //   addToApiReportFile: false
+    // },
+
+    // 'tsdoc-undefined-tag': {
+    //   logLevel: 'none' as ExtractorLogLevel,
+    //   addToApiReportFile: false
+    // }
+  },
+}
+
+export function _createApiExtractorConfig(options: {
+  exportPath: string
+  projectPath: string
+  sourcePath: string
+  tsconfigPath: string
+  distPath: string
+}): IConfigFile {
+  const {exportPath, projectPath, sourcePath, tsconfigPath, distPath} = options
+
+  return {
+    apiReport: {
+      enabled: false,
+      reportFileName: '<unscopedPackageName>.api.md',
+      // reportFileName: path.resolve(distPath, `${exportPath}.api.md`)
+    },
+    // bundledPackages: [],
+    compiler: {
+      tsconfigFilePath: tsconfigPath,
+    },
+    docModel: {
+      enabled: false,
+      // apiJsonFilePath: '<unscopedPackageName>.api.json'
+      apiJsonFilePath: path.resolve(distPath, `${exportPath}.api.json`),
+    },
+    dtsRollup: {
+      enabled: true,
+      untrimmedFilePath: path.resolve(distPath, `${exportPath}.d.ts`),
+      // betaTrimmedFilePath: path.resolve(distPath, `${exportPath}-beta.d.ts`),
+      // publicTrimmedFilePath: path.resolve(distPath, `${exportPath}-public.d.ts`)
+    },
+    tsdocMetadata: {
+      enabled: false,
+    },
+    messages: DEFAULT_MESSAGES_CONFIG,
+    mainEntryPointFilePath: sourcePath,
+    projectFolder: projectPath,
+  }
+}

package/src/build/tasks/dts/_createTSDocConfig.ts

@@ -0,0 +1,57 @@
+import {readFile} from 'fs/promises'
+import {TSDocConfigFile} from '@microsoft/tsdoc-config'
+import {parse} from 'jsonc-parser'
+
+/**
+ * @public
+ */
+export interface TSDocCustomTag {
+  name: string
+  syntaxKind: 'block' | 'modifier'
+  allowMultiple?: boolean
+}
+
+/**
+ * @internal
+ */
+export async function _createTSDocConfig(opts: {
+  customTags: TSDocCustomTag[]
+}): Promise<TSDocConfigFile | undefined> {
+  const {customTags} = opts
+
+  if (customTags.length === 0) {
+    return undefined
+  }
+
+  const tsDocBaseBuf = await readFile(
+    require.resolve('@microsoft/api-extractor/extends/tsdoc-base.json')
+  )
+
+  // Include the definitions that are required for API Extractor
+  // extends: ['@microsoft/api-extractor/extends/tsdoc-base.json'],
+  const tsDocBaseConfig = parse(tsDocBaseBuf.toString())
+
+  // Define custom tags and specify how they should be parsed
+  const tagDefinitions = (tsDocBaseConfig.tagDefinitions || []).concat(
+    customTags.map((t) => ({
+      tagName: `@${t.name}`,
+      syntaxKind: t.syntaxKind,
+      allowMultiple: t.allowMultiple,
+    }))
+  )
+
+  // Indicate that custom tags are supported by your tooling.
+  // (Without this, warnings may be reported saying that a tag is unsupported.)
+  const supportForTags = {...tsDocBaseConfig.supportForTags}
+
+  for (const customTag of customTags) {
+    supportForTags[`@${customTag.name}`] = true
+  }
+
+  return TSDocConfigFile.loadFromObject({
+    ...tsDocBaseConfig,
+    noStandardTags: false,
+    tagDefinitions,
+    supportForTags,
+  })
+}

package/src/build/tasks/dts/_extractTypes.ts

@@ -0,0 +1,101 @@
+import path from 'path'
+import {
+  Extractor,
+  ExtractorConfig,
+  ExtractorMessage,
+  ExtractorResult,
+} from '@microsoft/api-extractor'
+import chalk from 'chalk'
+import {_BuildFile} from '../../_types'
+import {_createApiExtractorConfig} from './_createApiExtractorConfig'
+import {_createTSDocConfig} from './_createTSDocConfig'
+
+export async function _extractTypes(options: {
+  cwd: string
+  distPath: string
+  // exportId: string
+  exportPath: string
+  files: _BuildFile[]
+  projectPath: string
+  quiet?: boolean
+  sourcePath: string
+  tsconfigPath: string
+}): Promise<{extractorResult: ExtractorResult; messages: ExtractorMessage[]}> {
+  const {cwd, distPath, exportPath, files, projectPath, quiet, sourcePath, tsconfigPath} = options
+
+  const tsdocConfigFile = await _createTSDocConfig({
+    customTags: [],
+  })
+
+  const extractorConfig: ExtractorConfig = ExtractorConfig.prepare({
+    configObject: _createApiExtractorConfig({
+      exportPath,
+      projectPath,
+      sourcePath,
+      distPath,
+      tsconfigPath,
+    }),
+    configObjectFullPath: undefined,
+    tsdocConfigFile,
+    packageJsonFullPath: path.resolve(projectPath, 'package.json'),
+  })
+
+  const messages: ExtractorMessage[] = []
+
+  // Invoke API Extractor
+  const extractorResult = Extractor.invoke(extractorConfig, {
+    // Equivalent to the "--local" command-line parameter
+    localBuild: true,
+    // Equivalent to the "--verbose" command-line parameter
+    showVerboseMessages: true,
+    // handle messages
+    messageCallback(message: ExtractorMessage) {
+      messages.push(message)
+      message.handled = true
+    },
+  })
+
+  if (!quiet) {
+    const warnings: ExtractorMessage[] = messages.filter((msg) => msg.logLevel === 'warning')
+
+    for (const msg of warnings) {
+      const sourceFilePath = msg.sourceFilePath && path.relative(cwd, msg.sourceFilePath)
+
+      // eslint-disable-next-line no-console
+      console.log(
+        [
+          `${chalk.cyan(sourceFilePath || '?')}`,
+          `:${chalk.yellow(msg.sourceFileLine)}:${chalk.yellow(msg.sourceFileColumn)}`,
+          ` - ${chalk.yellow('warning')} ${chalk.gray(msg.messageId)}\n`,
+          msg.text,
+          '\n',
+        ].join('')
+      )
+    }
+  }
+
+  const errors: ExtractorMessage[] = messages.filter((msg) => msg.logLevel === 'error')
+
+  for (const msg of errors) {
+    const sourceFilePath = msg.sourceFilePath && path.relative(cwd, msg.sourceFilePath)
+
+    // eslint-disable-next-line no-console
+    console.log(
+      [
+        `${chalk.cyan(sourceFilePath || '?')}`,
+        `:${chalk.yellow(msg.sourceFileLine)}:${chalk.yellow(msg.sourceFileColumn)}`,
+        ` - ${chalk.red('error')} ${chalk.gray(msg.messageId)}\n`,
+        msg.text,
+        '\n',
+      ].join('')
+    )
+  }
+
+  // Add to `files` in context
+  files.push({
+    type: 'types',
+    path: path.resolve(distPath, `${exportPath}.d.ts`),
+  })
+
+  return {extractorResult, messages}
+}

package/src/build/tasks/dts/_loadTSConfig.ts

@@ -0,0 +1,18 @@
+import ts from 'typescript'
+
+export async function _loadTSConfig(options: {
+  cwd: string
+  tsconfigPath: string
+}): Promise<ts.ParsedCommandLine> {
+  const {cwd, tsconfigPath} = options
+
+  const configPath = ts.findConfigFile(cwd, ts.sys.fileExists, tsconfigPath)
+
+  if (!configPath) {
+    throw new Error(`could not find a valid '${tsconfigPath}'`)
+  }
+
+  const configFile = ts.readConfigFile(configPath, ts.sys.readFile)
+
+  return ts.parseJsonConfigFileContent(configFile.config, ts.sys, cwd)
+}