#!/usr/bin/env node /** * Copyright 2017 Google Inc. All rights reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ const playwright = require('../../'); const fs = require('fs'); const path = require('path'); const Source = require('./Source'); const Message = require('./Message'); const { parseMd, renderMd, parseArgument, applyTemplates } = require('./../parse_md'); const { spawnSync } = require('child_process'); const preprocessor = require('./preprocessor'); const mdBuilder = require('./check_public_api/MDBuilder'); const PROJECT_DIR = path.join(__dirname, '..', '..'); const VERSION = require(path.join(PROJECT_DIR, 'package.json')).version; const RED_COLOR = '\x1b[31m'; const YELLOW_COLOR = '\x1b[33m'; const RESET_COLOR = '\x1b[0m'; run().catch(e => { console.error(e); process.exit(1); });; async function run() { const startTime = Date.now(); const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md')); const readme = await Source.readFile(path.join(PROJECT_DIR, 'README.md')); const binReadme = await Source.readFile(path.join(PROJECT_DIR, 'bin', 'README.md')); const contributing = await Source.readFile(path.join(PROJECT_DIR, 'CONTRIBUTING.md')); const docs = await Source.readdir(path.join(PROJECT_DIR, 'docs'), '.md'); const mdSources = [readme, binReadme, api, contributing, ...docs]; /** @type {!Array} */ const messages = []; let changedFiles = false; // Produce api.md { const comment = ''; const header = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-header.md')).toString(); const body = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-body.md')).toString(); const footer = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-footer.md')).toString(); const params = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-params.md')).toString(); // Generate signatures { const nodes = applyTemplates(parseMd(body), parseMd(params)); const { outline } = mdBuilder(nodes); const signatures = outline.signatures; for (const clazz of nodes) { clazz.type = 'h3'; for (const member of clazz.children) { if (member.type !== 'h2') continue; member.type = 'h4'; let match = member.text.match(/(event|method|property|async method|): (JS|CDP|[A-Z])([^.]+)\.(.*)/); if (!match) continue; if (match[1] === 'event') { member.text = `${match[2].toLowerCase() + match[3]}.on('${match[4]}')`; continue; } if (match[1] === 'method' || match[1] === 'async method') { const args = []; const argChildren = []; const returnContainer = []; const nonArgChildren = []; const optionsContainer = []; for (const item of member.children) { if (item.type === 'li' && item.liType === 'default') { const { type } = parseArgument(item.text); if (match[1] === 'method') item.text = `returns: <${type}>`; else item.text = `returns: <[Promise]<${type}>>`; returnContainer.push(item); continue; } if (item.type !== 'h3') { nonArgChildren.push(item); continue; } if (item.text.startsWith('param:')) { const param = item.children[0]; if (item.children[1]) param.text += ' ' + item.children[1].text; if (item.children.length > 2) param.children = item.children.slice(2); args.push(parseArgument(param.text)); argChildren.push(param); } if (item.text.startsWith('option:')) { let optionsNode = optionsContainer[0]; if (!optionsNode) { optionsNode = { type: 'li', text: '`options` <[Object]>', liType: 'default', children: [], }; optionsContainer.push(optionsNode); args.push(parseArgument(optionsNode.text)); } const param = item.children[0]; if (item.children[1]) param.text += ' ' + item.children[1].text; if (item.children.length > 2) param.children = item.children.slice(2); optionsNode.children.push(param); } } if (match[1] === 'async method' && !returnContainer[0]) { returnContainer.push({ type: 'li', text: 'returns: <[Promise]>', liType: 'default' }); } if (optionsContainer[0]) optionsContainer[0].children.sort((o1, o2) => o1.text.localeCompare(o2.text)); member.children = [...argChildren, ...optionsContainer, ...returnContainer, ...nonArgChildren]; const signatureKey = match[2] + match[3] + '.' + match[4]; const methodName = match[2].toLowerCase() + match[3] + '.' + match[4]; const signature = signatures.get(signatureKey); member.text = `${methodName}(${signature})`; } if (match[1] === 'property') { member.text = `${match[2].toLowerCase() + match[3]}.${match[4]}`; continue; } } } api.setText([comment, header, renderMd(nodes, 10000), footer].join('\n')); // Generate links preprocessor.generateLinks(api, signatures, messages); } } // Documentation checks. { const browserVersions = await getBrowserVersions(); messages.push(...(await preprocessor.runCommands(mdSources, { libversion: VERSION, chromiumVersion: browserVersions.chromium, firefoxVersion: browserVersions.firefox, webkitVersion: browserVersions.webkit, }))); messages.push(...preprocessor.autocorrectInvalidLinks(PROJECT_DIR, mdSources, getRepositoryFiles())); for (const source of mdSources.filter(source => source.hasUpdatedText())) messages.push(Message.warning(`WARN: updated ${source.projectPath()}`)); const body = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-body.md')).toString(); const params = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-params.md')).toString(); const api = applyTemplates(parseMd(body), parseMd(params)); const checkPublicAPI = require('./check_public_api'); const jsSources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []); messages.push(...checkPublicAPI(api, jsSources)); for (const source of mdSources) { if (!source.hasUpdatedText()) continue; await source.save(); changedFiles = true; } } // Report results. const errors = messages.filter(message => message.type === 'error'); if (errors.length) { console.log('DocLint Failures:'); for (let i = 0; i < errors.length; ++i) { let error = errors[i].text; error = error.split('\n').join('\n '); console.log(` ${i + 1}) ${RED_COLOR}${error}${RESET_COLOR}`); } } const warnings = messages.filter(message => message.type === 'warning'); if (warnings.length) { console.log('DocLint Warnings:'); for (let i = 0; i < warnings.length; ++i) { let warning = warnings[i].text; warning = warning.split('\n').join('\n '); console.log(` ${i + 1}) ${YELLOW_COLOR}${warning}${RESET_COLOR}`); } } let clearExit = messages.length === 0; if (changedFiles) { if (clearExit) console.log(`${YELLOW_COLOR}Some files were updated.${RESET_COLOR}`); clearExit = false; } console.log(`${errors.length} failures, ${warnings.length} warnings.`); const runningTime = Date.now() - startTime; console.log(`DocLint Finished in ${runningTime / 1000} seconds`); process.exit(clearExit ? 0 : 1); } async function getBrowserVersions() { const names = ['chromium', 'firefox', 'webkit']; const browsers = await Promise.all(names.map(name => playwright[name].launch())); const result = {}; for (let i = 0; i < names.length; i++) { result[names[i]] = browsers[i].version(); } await Promise.all(browsers.map(browser => browser.close())); return result; } function getRepositoryFiles() { const out = spawnSync('git', ['ls-files'], {cwd: PROJECT_DIR}); const files = out.stdout.toString().trim().split('\n').filter(f => !f.startsWith('docs-src')); return files.map(file => path.join(PROJECT_DIR, file)); }