@plugjs/plug 0.0.1

package/src/plugs/coverage/report.ts

@@ -0,0 +1,337 @@
+
+import { parse } from '@babel/parser'
+import {
+  Comment, isDeclaration,
+  isExportDeclaration,
+  isFile,
+  isIfStatement,
+  isImportDeclaration,
+  isProgram, isTryStatement,
+  isTSDeclareMethod,
+  isTSTypeReference,
+  isTypeScript,
+  Node,
+  VISITOR_KEYS
+} from '@babel/types'
+import { pathToFileURL } from 'node:url'
+import { $p, Logger } from '../../log.js'
+import { AbsolutePath } from '../../paths.js'
+import { readFile } from '../../utils/asyncfs.js'
+import { CoverageAnalyser } from './analysis.js'
+
+/* ========================================================================== *
+ * EXPORTED CONSTANTS AND TYPES                                               *
+ * ========================================================================== */
+
+/**
+ * A constant indicating that coverage was skipped (is irrelevant, for e.g.
+ * comment or typescript definition nodes)
+ */
+export const COVERAGE_SKIPPED = -2
+
+/**
+ * A constant indicating that coverage was intentionally ignored because of a
+ * specific "coverage ignore ..." comment
+ */
+export const COVERAGE_IGNORED = -1
+
+/** Node coverage summary */
+export interface NodeCoverageResult {
+  /** Number of _covered_ nodes (good!) */
+  coveredNodes: number,
+  /** Number of nodes with _no coverage_ (bad!) */
+  missingNodes: number,
+  /** Number of nodes ignored by comments like `coverage ignore xxx` */
+  ignoredNodes: number,
+  /** Total number of nodes (sum of `covered`, `missing` and `ignored`) */
+  totalNodes: number,
+  /** Percentage of code coverage (covered as a % of total - ignored nodes)*/
+  coverage: number,
+}
+
+/** Per-file coverage result */
+export interface CoverageResult {
+  /** The actual code this coverage is for */
+  code: string,
+  /**
+   * Per _character_ coverage report:
+   * - `-2`: coverage skipped (comments, typescript declarations, ...)
+   * - `-1`: coverage ignored (when using `coverage ignore xxx`)
+   * - `0`: no coverage collected for this character
+   * - _any number greater than zero_: number of times this was covered
+   */
+  codeCoverage: number[],
+  /** Node coverage summary */
+  nodeCoverage: NodeCoverageResult,
+}
+
+/** Aggregation of {@link CoverageResult} over all files */
+export type CoverageResults = Record<AbsolutePath, CoverageResult>
+
+/** Our coverage report, per file */
+export interface CoverageReport {
+  results: CoverageResults,
+  nodes: NodeCoverageResult,
+}
+
+/* ========================================================================== *
+ * EXPORTED CONSTANTS AND TYPES                                               *
+ * ========================================================================== */
+
+/** Tokens for `coverage ignore xxx`, this should be self-explanatory */
+type IgnoreCoverage = 'test' | 'if' | 'else' | 'try' | 'catch' | 'finally' | 'next'
+
+/** Regular expression matching strings like `coverage ignore xxx` */
+const ignoreRegexp = /(coverage|istanbul)\s+ignore\s+(test|if|else|try|catch|finally|next)(\s|$)/g
+
+/* ========================================================================== *
+ * EXPORTED CONSTANTS AND TYPES                                               *
+ * ========================================================================== */
+
+/**
+ * Analyse coverage for the specified source files, using the data from the
+ * specified coverage files and produce a {@link CoverageReport}.
+ */
+export async function coverageReport(
+    analyser: CoverageAnalyser,
+    sourceFiles: AbsolutePath[],
+    log: Logger,
+): Promise<CoverageReport> {
+  /* Some of our results */
+  const results: CoverageResults = {}
+  const nodes: NodeCoverageResult = {
+    coveredNodes: 0,
+    missingNodes: 0,
+    ignoredNodes: 0,
+    totalNodes: 0,
+    coverage: 0,
+  }
+
+  /*
+    * Here comes the interesting part: we need to parse the original soruces,
+    * walk their ASTs and see whether each node has been covered or not.
+    * We look up every node's position, (for sitemaps, map this to the position
+    * in the resulting file) then look at the coverage.
+    */
+  for (const file of sourceFiles) {
+    /* Read up the file and parse the tree in the most liberal way possible */
+    const url = pathToFileURL(file).toString()
+    const code = await readFile(file, 'utf-8')
+
+    const tree = parse(code, {
+      allowImportExportEverywhere: true,
+      allowAwaitOutsideFunction: true,
+      allowReturnOutsideFunction: true,
+      allowSuperOutsideMethod: true,
+      allowUndeclaredExports: true,
+      attachComment: true,
+      errorRecovery: false,
+      sourceType: 'unambiguous',
+      sourceFilename: file,
+      startLine: 1,
+      startColumn: 0,
+      plugins: [ 'typescript' ],
+      strictMode: false,
+      ranges: false,
+      tokens: false,
+      createParenthesizedExpressions: true,
+    })
+
+    const codeCoverage: number[] = new Array(code.length).fill(0)
+    const nodeCoverage: NodeCoverageResult = {
+      coveredNodes: 0,
+      missingNodes: 0,
+      ignoredNodes: 0,
+      totalNodes: 0,
+      coverage: 0,
+    }
+
+    /* Set the code coverage for the specified node and (optionally) its children */
+    const setCodeCoverage = (
+        node: (Node | Comment)[] | Node | Comment | undefined | null,
+        coverage: number,
+        recursive: boolean,
+    ): void => {
+      if (! node) return
+
+      if (Array.isArray(node)) {
+        for (const n of node) setCodeCoverage(n, coverage, recursive)
+        return
+      }
+
+      if ((node.start != null) && (node.end != null)) {
+        for (let i = node.start; i < node.end; i ++) {
+          codeCoverage[i] = coverage
+        }
+      }
+
+      if (coverage == COVERAGE_IGNORED) {
+        nodeCoverage.ignoredNodes++
+      } else if (coverage === 0) {
+        nodeCoverage.missingNodes++
+      } else if (coverage > 0) {
+        nodeCoverage.coveredNodes++
+      }
+
+      if (! recursive) return
+
+      const keys = VISITOR_KEYS[node.type] || []
+      for (const key of keys) {
+        const value: Node | Node[] = (<any> node)[key]
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            setCodeCoverage(child, coverage, true)
+          }
+        } else if (value) {
+          setCodeCoverage(value, coverage, true)
+        }
+      }
+    }
+
+    /* Recursively invoke "visitNode" on the children of a given node */
+    const visitChildren = (node: Node, depth: number): void => {
+      const keys = VISITOR_KEYS[node.type] || []
+      for (const key of keys) {
+        const children: Node | null | (Node | null)[] = (<any> node)[key]
+        if (Array.isArray(children)) {
+          for (const child of children) {
+            if (child) visitNode(child, depth + 1)
+          }
+        } else if (children) {
+          visitNode(children, depth + 1)
+        }
+      }
+    }
+
+    /* Visit a node or ignore it depending on a condition */
+    const maybeIgnoreNode = (
+        condition: boolean,
+        node: Node | null | undefined,
+        depth: number,
+    ): void => {
+      if (condition) {
+        setCodeCoverage(node, COVERAGE_IGNORED, true)
+      } else if (node) {
+        visitNode(node, depth)
+      }
+    }
+
+    /* Visit a node and evaluate its coverage */
+    const visitNode = (node: Node, depth: number): void => {
+      /* See what we're doing here... */
+      log.trace('-'.padStart((depth * 2) + 1, ' '), node.type, `${node.loc?.start.line}:${node.loc?.start.column}`)
+
+      /* Root nodes (file and program) simply go to their children */
+      if (isFile(node)) return visitChildren(node, depth)
+      if (isProgram(node)) return visitChildren(node, depth)
+
+      /* Figure out if we have some "coverage ignore xxxx" in comments */
+      const ignores: IgnoreCoverage[] = []
+      for (const comment of node.leadingComments || []) {
+        for (const match of comment.value.matchAll(ignoreRegexp)) {
+          ignores.push(match[2] as IgnoreCoverage)
+        }
+      }
+
+      /* Skip this node if we have a "coverage ignore next" comment */
+      if (ignores.includes('next')) return setCodeCoverage(node, COVERAGE_IGNORED, true)
+
+      /* Typescript nodes are skipped, but children aren't in some cases */
+      if (isTypeScript(node)) {
+        if (isTSDeclareMethod(node)) return setCodeCoverage(node, COVERAGE_SKIPPED, true)
+        if (isTSTypeReference(node)) return setCodeCoverage(node, COVERAGE_SKIPPED, true)
+        if (isDeclaration(node)) return setCodeCoverage(node, COVERAGE_SKIPPED, true)
+
+        /* For things like "X as Y": the "as" node wraps the expression */
+        setCodeCoverage(node, COVERAGE_SKIPPED, false) // not recursive
+        return visitChildren(node, depth) // visit all children normally...
+      }
+
+      // Typescript "import type" or "export type" get skipped all together
+      if (isExportDeclaration(node) && (node.exportKind === 'type')) {
+        return setCodeCoverage(node, COVERAGE_SKIPPED, true)
+      }
+
+      if (isImportDeclaration(node) && (node.importKind === 'type')) {
+        return setCodeCoverage(node, COVERAGE_SKIPPED, true)
+      }
+
+      /* Ok, from here we calculate the coverage */
+      let coverage = 0
+      if (node.loc) {
+        const { line, column } = node.loc.start
+        const c = analyser.coverage(url, line, column)
+        if (c == null) log.warn(`No coverage for ${node.type} at ${$p(file)}:${line}:${column}`)
+        else coverage = c
+      }
+
+      /* Record the code coverage, and set up our variables */
+      setCodeCoverage(node, coverage, false)
+
+      /* The "if" node might have some ignores... */
+      if (isIfStatement(node)) {
+        maybeIgnoreNode(ignores.includes('test'), node.test, depth + 1)
+        maybeIgnoreNode(ignores.includes('if'), node.consequent, depth + 1)
+        maybeIgnoreNode(ignores.includes('else'), node.alternate, depth + 1)
+        return
+      }
+
+      /* The "try" node might have some ignores... */
+      if (isTryStatement(node)) {
+        maybeIgnoreNode(ignores.includes('try'), node.block, depth + 1)
+        maybeIgnoreNode(ignores.includes('catch'), node.handler, depth + 1)
+        maybeIgnoreNode(ignores.includes('finally'), node.finalizer, depth + 1)
+        return
+      }
+
+      /* All other nodes simply gets visited recursively*/
+      visitChildren(node, depth)
+    }
+
+    /* Start by setting the scope of our coverage in the code */
+    codeCoverage.fill(COVERAGE_SKIPPED) // by default, everything is skipped
+    setCodeCoverage(tree.program.directives, 0, true) // directives must be covered
+    setCodeCoverage(tree.program.body, 0, true) // program body must be covered
+
+    /* Cleanup our node statistics */
+    nodeCoverage.coveredNodes = 0
+    nodeCoverage.missingNodes = 0
+    nodeCoverage.ignoredNodes = 0
+
+    /* Visit all of the program nodes */
+    visitChildren(tree.program, -1)
+
+    /*
+      * As comments are mixed within codes (and do not get visited in the
+      * tree) we force-skip them _AFTER_ the tree is visited, otherwise (for
+      * example) a comment within a block will be shown with the coverage of
+      * the block itself.
+      */
+    // setCodeCoverage(tree.comments, COVERAGE_SKIPPED, true)
+
+    /* Update nodes coverage results */
+    updateNodeCoverageResult(nodeCoverage)
+
+    nodes.coveredNodes += nodeCoverage.coveredNodes
+    nodes.missingNodes += nodeCoverage.missingNodes
+    nodes.ignoredNodes += nodeCoverage.ignoredNodes
+    nodes.totalNodes += nodeCoverage.totalNodes
+
+    /* This file is done, add it to the report */
+    results[file] = { code, codeCoverage, nodeCoverage }
+  }
+
+  /* All done, return the report */
+  updateNodeCoverageResult(nodes)
+  return { results, nodes }
+}
+
+function updateNodeCoverageResult(result: NodeCoverageResult): void {
+  const { coveredNodes, missingNodes, ignoredNodes } = result
+  const totalNodes = result.totalNodes = coveredNodes + missingNodes + ignoredNodes
+  if (totalNodes - ignoredNodes) {
+    result.coverage = Math.floor((100 * coveredNodes) / (totalNodes - ignoredNodes))
+  } else {
+    result.coverage = 0 // No "infinity" on division by zero...
+  }
+}

package/src/plugs/coverage.ts

@@ -0,0 +1,194 @@
+import { html, initFunction } from '@plugjs/cov8-html'
+import { sep } from 'node:path'
+import { fail } from '../assert.js'
+import { Files } from '../files.js'
+import { $gry, $ms, $p, $red, $ylw, ERROR, NOTICE, WARN } from '../log.js'
+import { AbsolutePath } from '../paths.js'
+import { install, Plug } from '../pipe.js'
+import { Run } from '../run.js'
+import { createAnalyser, SourceMapBias } from './coverage/analysis.js'
+import { coverageReport, CoverageResult } from './coverage/report.js'
+
+/** Options to analyse coverage reports */
+export interface CoverageOptions {
+  /** The bias for source map analisys (defaults to `greatest_lower_bound`) */
+  sourceMapBias?: SourceMapBias
+  /** Minimum _overall_ coverage (as a percentage) */
+  minimumCoverage?: number,
+  /** Optimal _overall_ coverage (as a percentage)  */
+  optimalCoverage?: number,
+  /** Minimum _per-file_ coverage (as a percentage) */
+  minimumFileCoverage?: number,
+  /** Optimal _per-file_ coverage (as a percentage) */
+  optimalFileCoverage?: number,
+}
+
+export interface CoverageReportOptions extends CoverageOptions {
+  /** If specified, a JSON and HTML report will be written to this directory */
+  reportDir: string,
+}
+
+/**
+ * The {@link Coverage} plug type is inferred from the constructor, so this
+ * type helps to declare the correct types as we can't really infer them from
+ * `typeof Coverage`...
+ */
+type CoverageConstructor = {
+  new (coverageDir: string): Coverage<CoverageOptions>
+  new (coverageDir: string, options: CoverageOptions): Coverage<CoverageOptions>
+  new (coverageDir: string, options: CoverageReportOptions): Coverage<CoverageReportOptions>
+}
+
+/** Analyse coverage using files generated by V8/NodeJS. */
+export class Coverage<
+  T extends CoverageOptions | CoverageReportOptions,
+> implements Plug<T extends CoverageReportOptions ? Files : undefined> {
+  constructor(coverageDir: string)
+  constructor(coverageDir: string, options?: T)
+  constructor(
+      private readonly _coverageDir: string,
+      private readonly _options: Partial<CoverageReportOptions> = {},
+  ) {}
+
+  async pipe(files: Files, run: Run): Promise<T extends CoverageReportOptions ? Files : undefined> {
+    const coverageFiles = await run.find('coverage-*.json', {
+      directory: this._coverageDir,
+    })
+
+    if (coverageFiles.length === 0) {
+      fail(`No coverage files found in ${$p(coverageFiles.directory)}`)
+    }
+
+    const sourceFiles = [ ...files.absolutePaths() ]
+
+    const ms1 = Date.now()
+    const analyser = await createAnalyser(
+        sourceFiles,
+        [ ...coverageFiles.absolutePaths() ],
+        this._options.sourceMapBias || 'least_upper_bound',
+        run.log,
+    )
+    run.log.info('Parsed', coverageFiles.length, 'coverage files', $ms(Date.now() - ms1))
+
+    const ms2 = Date.now()
+    const report = await coverageReport(analyser, sourceFiles, run.log)
+    run.log.info('Analysed', sourceFiles.length, 'source files', $ms(Date.now() - ms2))
+
+    analyser.destroy()
+
+    const {
+      minimumCoverage = 50,
+      minimumFileCoverage = minimumCoverage,
+      optimalCoverage = Math.round((100 + minimumCoverage) / 2),
+      optimalFileCoverage = Math.round((100 + minimumFileCoverage) / 2),
+    } = this._options
+
+    let max = 0
+    for (const file in report) {
+      if (file.length > max) max = file.length
+    }
+
+    let maxLength = 0
+    for (const file in report.results) {
+      if (file.length > maxLength) maxLength = file.length
+    }
+
+    let fileErrors = 0
+    let fileWarnings = 0
+    const _report = run.report('Coverage report')
+
+    for (const [ _file, result ] of Object.entries(report.results)) {
+      const { coverage } = result.nodeCoverage
+      const file = _file as AbsolutePath
+
+      if (coverage < minimumFileCoverage) {
+        _report.annotate(ERROR, file, `${coverage} %`)
+        fileErrors ++
+      } else if (coverage < optimalFileCoverage) {
+        _report.annotate(WARN, file, `${coverage} %`)
+        fileWarnings ++
+      } else {
+        _report.annotate(NOTICE, file, `${coverage} %`)
+      }
+    }
+
+    if (report.nodes.coverage < minimumCoverage) {
+      const message = `${$red(`${report.nodes.coverage}%`)} does not meet minimum coverage ${$gry(`(${minimumCoverage}%)`)}`
+      _report.add({ level: ERROR, message })
+    } else if (report.nodes.coverage < optimalCoverage) {
+      const message = `${$ylw(`${report.nodes.coverage}%`)} does not meet optimal coverage ${$gry(`(${optimalCoverage}%)`)}`
+      _report.add({ level: WARN, message })
+    }
+
+    if (fileErrors) {
+      const message = `${$red(fileErrors)} files do not meet minimum file coverage ${$gry(`(${minimumFileCoverage}%)`)}`
+      _report.add({ level: ERROR, message })
+    }
+    if (fileWarnings) {
+      const message = `${$ylw(fileWarnings)} files do not meet optimal file coverage ${$gry(`(${optimalFileCoverage}%)`)}`
+      _report.add({ level: WARN, message })
+    }
+
+    /* If we don't have to write a report, pass-through the coverage files */
+    if (this._options.reportDir == null) return _report.done(false) as any
+
+    /* Create a builder to emit our reports */
+    const builder = run.files(this._options.reportDir)
+
+    /* Thresholds to inject in the report */
+    const date = new Date().toISOString()
+    const thresholds = {
+      minimumCoverage,
+      minimumFileCoverage,
+      optimalCoverage,
+      optimalFileCoverage,
+    }
+
+    /* The JSON file in the report has *absolute* file paths */
+    await builder.write('report.json', JSON.stringify({ ...report, thresholds, date }))
+
+    /* The HTML file rendering our report */
+    await builder.write('index.html', html)
+
+    /* The JSONP file (for our HTML report) has relative files and a tree */
+    const results: Record<string, CoverageResult> = {}
+    for (const [ rel, abs ] of files.pathMappings()) {
+      results[rel] = report.results[abs]
+    }
+
+    const tree: Record<string, any> = {}
+    for (const relative of Object.keys(results)) {
+      const directories = relative.split(sep)
+      const file = directories.pop()!
+
+      let node = tree
+      for (const dir of directories) {
+        node = node[dir] = node[dir] || {}
+      }
+
+      node[file] = relative
+    }
+
+    const jsonp = JSON.stringify({ ...report, results, thresholds, tree, date })
+    await builder.write('report.js', `${initFunction}(${jsonp});`)
+
+    /* Emit our coverage report */
+    _report.done(false)
+
+    /* Return emitted files */
+    return builder.build() as any
+  }
+}
+
+/* ========================================================================== *
+ * INSTALLATION                                                               *
+ * ========================================================================== */
+
+install('coverage', Coverage)
+
+declare module '../pipe.js' {
+  export interface Pipe {
+    /** Analyse coverage using files generated by V8/NodeJS. */
+    coverage: PipeExtension<CoverageConstructor>
+  }
+}

package/src/plugs/debug.ts

@@ -0,0 +1,35 @@
+import { Files } from '../files.js'
+import { $gry, $p, $und, log } from '../log.js'
+import { install, Plug } from '../pipe.js'
+import { Run } from '../run.js'
+
+/** Writes some info about the current {@link Files} being passed around. */
+export class Debug implements Plug<Files> {
+  constructor() {}
+
+  async pipe(files: Files, run: Run): Promise<Files> {
+    log.notice('Debugging', files.length, 'files')
+    log.notice('-        base dir:', $p(run.resolve('@')))
+    log.notice('-  build file dir:', $p(run.resolve('.')))
+    log.notice('-       files dir:', $p(files.directory))
+    if (files.length) {
+      const [ path, ...paths ] = files
+      log.notice('-  relative paths:', $und($gry(path)))
+      for (const p of paths) log.notice('-                :', $und($gry(p)))
+    }
+    return files
+  }
+}
+
+/* ========================================================================== *
+ * INSTALLATION                                                               *
+ * ========================================================================== */
+
+install('debug', Debug)
+
+declare module '../pipe.js' {
+  export interface Pipe {
+    /** Writes some info about the current {@link Files} being passed around. */
+    debug: PipeExtension<typeof Debug>
+  }
+}

package/src/plugs/esbuild/bundle-locals.ts

@@ -0,0 +1,33 @@
+import { Plugin } from 'esbuild'
+
+/**
+ * A simple ESBuild plugin bundling _only_ local files, and marking anything
+ * imported from `node_modules` as _external_.
+ */
+export function bundleLocals(): Plugin {
+  let disabled = false
+
+  return {
+    name: 'bundle-locals',
+
+    setup(build): void {
+      build.onStart(() => {
+        if (build.initialOptions.bundle) return
+
+        disabled = true
+        return { warnings: [ { text: 'Plugin disabled when not bundling' } ] }
+      })
+
+      /* Intercept resolution */
+      build.onResolve({ filter: /.*/ }, (args) => {
+        if (disabled) return
+
+        /* Ignore the entry points (when the file is not being imported) */
+        if (! args.importer) return null
+
+        /* Anything not starting with "."? external node module */
+        return args.path.startsWith('.') ? null : { external: true }
+      })
+    },
+  }
+}