Function docsHelpers

runok.cjs:237–338

()

  },

  async docsHelpers() {
    // generate documentation for helpers
    const files = fs.readdirSync('lib/helper').filter(f => path.extname(f) === '.js')

    const ignoreList = ['Polly', 'MockRequest'] // WebDriverIO won't be documented and should be removed

    const partials = fs.readdirSync('docs/webapi').filter(f => path.extname(f) === '.mustache')
    const placeholders = partials.map(file => `{{> ${path.basename(file, '.mustache')} }}`)
    const templates = partials
      .map(file => fs.readFileSync(`docs/webapi/${file}`).toString())
      .map(template =>
        template
          .replace(/^/gm, '   * ')
          .replace(/^/, '\n')
          .replace(/\s*\* /, ''),
      )

    const sharedPartials = fs.readdirSync('docs/shared').filter(f => path.extname(f) === '.mustache')
    const sharedPlaceholders = sharedPartials.map(file => `{{ ${path.basename(file, '.mustache')} }}`)
    const sharedTemplates = sharedPartials.map(file => fs.readFileSync(`docs/shared/${file}`).toString()).map(template => `\n\n\n${template}`)

    for (const file of files) {
      const name = path.basename(file, '.js')
      if (ignoreList.indexOf(name) >= 0) continue
      console.log(`Writing documentation for ${name}`)
      copy(`lib/helper/${file}`, `docs/build/${file}`)
      replaceInFile(`docs/build/${file}`, cfg => {
        for (const i in placeholders) {
          cfg.replace(placeholders[i], templates[i])
        }
        cfg.replace(/CodeceptJS.LocatorOrString\?/g, '(string | object)?')
        cfg.replace(/LocatorOrString\?/g, '(string | object)?')
        cfg.replace(/CodeceptJS.LocatorOrString/g, 'string | object')
        cfg.replace(/LocatorOrString/g, 'string | object')
        cfg.replace(/CodeceptJS.StringOrSecret/g, 'string | object')

        // Convert ESM imports to require() for JSDoc compatibility
        cfg.replace(/^import\s+([^'"`\s{]+)\s+from\s+['"`]([^'"`]+)['"`]/gm, "const $1 = require('$2')")
        cfg.replace(/^import\s*\{\s*([^}]+)\s*\}\s*from\s+['"`]([^'"`]+)['"`]/gm, (match, imports, path) => {
          // Handle destructuring imports with aliases - convert to simple require and assign
          if (imports.includes(' as ')) {
            const parts = imports.split(',').map(i => i.trim())
            const assignments = parts.map(part => {
              if (part.includes(' as ')) {
                const [original, alias] = part.split(' as ').map(s => s.trim())
                return `const ${alias} = require('${path}').${original}`
              } else {
                return `const ${part} = require('${path}').${part}`
              }
            })
            return assignments.join(';\n')
          }
          return `const { ${imports} } = require('${path}')`
        })
        cfg.replace(/^import\s+\*\s+as\s+([^'"`]+)\s+from\s+['"`]([^'"`]+)['"`]/gm, "const $1 = require('$2')")

        // Convert ESM exports to module.exports for JSDoc compatibility
        cfg.replace(/^export\s*\{\s*([^}]+)\s+as\s+default\s*\}/gm, 'module.exports = $1')