Plugins

[bluwy]

Today, publint is a slightly opinionated linting tool that comes with a built-in set of rules for support in environments like Vite, Node, workers, etc, and suggestions to keep your package clean and correct.

The next logical step is to allow expanding what publint is today. In comparison to ESLint where it lints your source code, publint lints your built/publish code, which is an area I've not seen explored.

I'd like to work on a plugin API to enable this, and below are drafts of the idea:

Goals

• Plugins can add new rules to lint, some usecases:
  • Use the TypeScript compiler directly to validate the package, integrating https://arethetypeswrong.github.io
  • Use a different validation tool, like https://github.com/wooorm/package-exports
  • Lint files not supported by core, like raw .svelte or .ts files
  • Lint if it uses APIs from a specific environment only, maybe even run the code in the environment
  • Organizations may create "presets" so that packages work between their projects
• Plugins can report issues on other files, not just package.json
• Plugins can work in both Node and browser environments, but can choose to only work in Node if they want
  • Enable future support for using custom plugins on https://publint.dev
• Plugins have access to utilities that core uses to validate or process things
• Installing publint alone should still be all that's needed to lint the basic/standard things

Non-goals

• Pushing rules as external packages. Core should be opened to additional rules that help everyone, as long as they don't bloat the package. This helps prevent plugin hell.
• Disabling specific rules. All rules in core cannot be disabled, but plugins may add options to disable their rules. (Could be persuaded but we'll see)
• Rule documentation. This may be tackled separately in Better publint.dev #100.
• Supporting a config file (yet?).

Design

interface Plugin {
  name: string
  // Runs in parallel
  lint?: (api: LintApi) => void | Promise<void>
}

export interface LintApi {
  root: string
  pkg: PackageJson // Better-typed `package.json` object
  originalPkg: PackageJson // Better-typed `package.json` object
  files: string[] // All files packed in the tarball. Use `vfs` to load them.
  vfs: Vfs // Same as the current `vfs` option object

  // Resolve the `id` to a specific path
  resolve: Resolve

  // Report an issue
  report: (issue: Issue) => void
}

type ResolvePreset =
  | 'esm'
  | 'cjs'
  | 'types'
  | 'package-json-main'
  | 'package-json-exports'

interface Resolve {
  (
    id: string,
    importer?: string,
    options?: { preset?: ResolvePreset }
  ): Promise<ResolveResult | undefined>
}

type ResolveResult =
  | { type: 'dependency'; name: string; subpath: string }
  | { type: 'dev-dependency'; name: string; subpath: string }
  | { type: 'protocol'; path: string }
  | { type: 'file'; path: string }

/** Path to the file only */
type LocationPath = string
/** Path to file with line and column */
type LocationFileWithLineColumn = {
  path: string
  start: number | { line: number; column: number }
  end?: number | { line: number; column: number }
}
/** Path to JSON file with specific keys */
type LocationJsonWithKeys = { path: string; keys: string[] }

interface Issue {
  type: 'suggestion' | 'warning' | 'error'
  rule: string
  message: string
  location: LocationPath | LocationFileWithLineColumn | LocationJsonWithKeys
}

How to write a good plugin:

1. If you intend your plugin to work in browsers:
   1. Use api.vfs.* for any filesystem related operations.
   2. For path related utilities, consider using https://github.com/unjs/pathe
2. Use api.resolve to resolve paths instead of manual resolution, which is possible but only for non-standard cases.

Notes:

1. As plugins' lint hook run in parallel, the order of api.report between plugins may be non-deterministic. Internally, we can sort this by file, rule name, and issue message.

Examples

Suggest specifying a description:

export function descriptionPlugin(): Plugin {
  return {
    name: 'description',
    lint(api) {
      if (!api.pkg.description) {
        api.report({
          type: 'suggestion'
          rule: 'add-description'
          message: 'A description is recommended',
          location: 'package.json',
        })
      }
    }
  }
}

[bluwy]

I just found out that https://github.com/NaverPayDev/cli/tree/main/packages/publint implements a variant that applies the orgs opinionated linting errors. I'd love to validate that this new plugin API can work for their usecase too.