Plugin types

export type PluginOrder = 'pre' | 'post'

export interface ResolveIdOptions {
  /** The file or module that contains the import. Absent for an entry point. */
  importer?: string
  /** The namespace the importer lives in. Absent means "file". */
  namespace?: string
  /**
   * The kind of import: an entry point, a static or dynamic import, a
   * `require`, and so on. Left out when the caller does not know.
   */
  kind?: string
  /**
   * Values passed by the import's attributes or `with` clause, if any. A plugin
   * that does not care can ignore this.
   */
  with?: Record<string, string>
  /**
   * True when this question came from a plugin calling `this.resolve` rather
   * than from the engine walking an import. A plugin that rewrites imports but
   * must not answer its own questions checks this.
   */
  custom?: boolean
}

export interface ResolvedId {
  /** The resolved path. A path in the "file" namespace must be absolute. */
  id: string
  /** True to leave the import in the output rather than bundle it. */
  external?: boolean
  /**
   * True to promise the module has no side effects, so it can be dropped when
   * nothing imports from it. Only meaningful as `true`.
   */
  moduleSideEffects?: boolean
  /** A virtual filesystem the id belongs to. "file" by default. */
  namespace?: string
  /** A value carried to this module's `load`, so the two halves can pass state. */
  meta?: unknown
}

export interface LoadResult {
  /** The module's source, instead of what the file system holds. */
  code: string | Uint8Array
  /** How to interpret `code`. Defaults to `"js"`. */
  loader?: Loader
  /**
   * The directory this module's own relative imports resolve against. Left out,
   * the directory the id is in.
   */
  resolveDir?: string
  /** A value carried from the matching `resolveId`. */
  meta?: unknown
  /** Extra paths this answer depends on, so a change triggers a rebuild. */
  watchFiles?: string[]
  /** Extra directories this answer depends on. */
  watchDirs?: string[]
}

export interface SourceDescription {
  /** The transformed source. */
  code: string
  /**
   * A sourcemap for the transform, as JSON text. Optional; without one the
   * engine maps positions back to the original where it can.
   */
  map?: string | null
  /** Extra paths this transform depends on. */
  watchFiles?: string[]
  watchDirs?: string[]
}

export interface OutputChunk {
  type: 'chunk'
  /** The path the file is written to, relative to the output directory. */
  fileName: string
  /** The generated source. Mutating this changes what is written. */
  code: string
  /** True when this chunk is an entry point. */
  isEntry: boolean
  /** The exports this chunk publishes. */
  exports: string[]
  /** The module ids this chunk was built from. */
  modules: string[]
}

export interface OutputAsset {
  type: 'asset'
  /** The path the file is written to, relative to the output directory. */
  fileName: string
  /** The asset's bytes. Mutating this changes what is written. */
  source: string | Uint8Array
}

export interface OutputBundle {
  [fileName: string]: OutputChunk | OutputAsset
}

export interface NormalizedOutputOptions {
  /** The output format. */
  format: Format
  /** The output directory, when one was given. */
  dir?: string
  /** The single output file, when one was given. */
  file?: string
  /** Whether the outputs are being written to disk. */
  write: boolean
}

export type EmittedFile =
  | { type: 'asset'; name?: string; fileName?: string; source: string | Uint8Array }

export interface GuchhoLog {
  message: string
  /** The file the message blames. */
  id?: string
  /** A code for the message, for a caller filtering them. */
  code?: string
  /** A 1-based line. */
  line?: number
  /** A 0-based column. */
  column?: number
}

export interface PluginContext {
  /** This plugin's name, as declared. */
  readonly pluginName: string
  /**
   * Facts about the running build that do not come from the plugin itself.
   *
   * `guchhoVersion` is reported rather than omitted, because a plugin that
   * switches on it is otherwise reading undefined and taking the wrong branch
   * silently. `watchMode` is true when the build is a watch rebuild.
   */
  readonly meta: {
    readonly guchhoVersion: string
    readonly watchMode: boolean
  }
  /**
   * Resolves a path with the build's own rules and the same chain of plugins,
   * then hands back the answer. This is how a plugin asks where an import
   * points without claiming it. Returns `null` when nothing resolves it.
   *
   * `custom: true` is set on the question so a plugin that answers resolution
   * can tell its own question from the engine's and decline it.
   */
  resolve(
    source: string,
    importer?: string,
    options?: ResolveIdOptions
  ): Promise<ResolvedId | null>
  /**
   * Adds a file to the build's output. Returns a reference id that names the
   * file for `getFileName`, and that can be handed to another `emitFile`.
   */
  emitFile(file: EmittedFile): string
  /** The output path a reference id from `emitFile` resolves to. */
  getFileName(referenceId: string): string
  /** Reports a warning against this plugin. Does not fail the build. */
  warn(message: string | GuchhoLog): void
  /** Fails the build with this message. Never returns. */
  error(message: string | GuchhoLog): never
}

export interface Plugin {
  /** This plugin's name. Not optional: it appears in the diagnostics it causes. */
  name: string
  /** When this plugin runs relative to the others. */
  order?: PluginOrder
  /** Called once per build, before any file is read. */
  buildStart?(
    this: PluginContext,
    options: BuildOptions
  ): void | Promise<void>
  /**
   * Asked where a specifier resolves to, for every import and entry point.
   *
   * Return a `ResolvedId` or a path string to claim it, `false` to mark it
   * external, or `null` to decline.
   */
  resolveId?(
    this: PluginContext,
    source: string,
    importer: string | undefined,
    options: ResolveIdOptions
  ): ResolvedId | string | false | null | undefined | Promise<
    ResolvedId | string | false | null | undefined
  >
  /**
   * Asked for a module's contents, before the loader would read them.
   *
   * Return `LoadResult` or a source string to claim the module, or `null` to
   * let the next plugin and then the loader have it.
   */
  load?(
    this: PluginContext,
    id: string
  ): LoadResult | string | null | undefined | Promise<
    LoadResult | string | null | undefined
  >
  /**
   * Transforms a module's source after it has been loaded and before it is
   * parsed. `code` is the text the previous step produced.
   */
  transform?(
    this: PluginContext,
    code: string,
    id: string
  ): SourceDescription | string | null | undefined | Promise<
    SourceDescription | string | null | undefined
  >
  /**
   * Called at the end of the build, after every module is read. `error` is set
   * when the build failed, which makes this the place to clean up either way.
   */
  buildEnd?(
    this: PluginContext,
    error?: Error
  ): void | Promise<void>
  /**
   * Called after the output has been produced but before it is written, with a
   * bundle the hook may mutate, add to, or delete from. This is where a plugin
   * rewrites generated code or emits a sibling file.
   */
  generateBundle?(
    this: PluginContext,
    options: NormalizedOutputOptions,
    bundle: OutputBundle
  ): void | Promise<void>
  /**
   * Called after the output has been written, with the same bundle. This is
   * where a plugin reports on, or reads back, what was written.
   */
  writeBundle?(
    this: PluginContext,
    options: NormalizedOutputOptions,
    bundle: OutputBundle
  ): void | Promise<void>
  /** Called when the context is torn down - the last hook a plugin sees. */
  closeBundle?(this: PluginContext): void | Promise<void>
}