playwright/utils/doclint/cli.js

214 lines
7.7 KiB
JavaScript
Raw Normal View History

2019-11-19 05:18:28 +03:00
#!/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('../../');
2020-12-03 00:50:10 +03:00
const fs = require('fs');
2019-11-19 05:18:28 +03:00
const path = require('path');
2020-12-03 00:50:10 +03:00
const os = require('os');
2019-11-19 05:18:28 +03:00
const Source = require('./Source');
const Message = require('./Message');
const { renderMdTemplate, parseMd, renderMd, parseArgument } = require('./../parse_md');
const { spawnSync } = require('child_process');
const preprocessor = require('./preprocessor');
2019-11-19 05:18:28 +03:00
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);
});;
2019-11-19 05:18:28 +03:00
async function run() {
const startTime = Date.now();
const onlyBrowserVersions = process.argv.includes('--only-browser-versions');
2019-11-19 05:18:28 +03:00
/** @type {!Array<!Message>} */
const messages = [];
let changedFiles = false;
2020-12-03 00:50:10 +03:00
// Produce api.md
const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
2020-12-03 00:50:10 +03:00
{
const comment = '<!-- THIS FILE IS NOW GENERATED -->';
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();
let params = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-params.md')).toString();
params = renderMdTemplate(params, params);
// Generate signatures
{
const nodes = parseMd(renderMdTemplate(body, params));
const signatures = new Map();
let h4;
let args;
const flush = () => {
if (h4 && !['page.accessibility', 'page.mouse', 'page.keyboard', 'page.coverage', 'page.touchscreen'].includes(h4.h4)) {
const tokens = [];
let hasOptional = false;
for (const arg of args) {
const optional = arg.name === 'options' || arg.text.includes('Optional');
if (tokens.length) {
if (optional && !hasOptional)
tokens.push(`[, ${arg.name}`);
else
tokens.push(`, ${arg.name}`);
} else {
if (optional && !hasOptional)
tokens.push(`[${arg.name}`);
else
tokens.push(`${arg.name}`);
}
hasOptional = hasOptional || optional;
}
if (hasOptional)
tokens.push(']');
const signature = tokens.join('');
signatures.set(h4.h4, signature);
h4.h4 = `${h4.h4}(${signature})`;
}
h4 = null;
args = null;
};
for (const node of nodes) {
if (node.h1 || node.h2 || node.h3 || node.h4)
flush();
if (node.h4) {
h4 = node.h4.startsWith('event:') ? null : node;
args = node.h4.startsWith('event:') ? null : [];
continue;
}
if (args && node.li && node.liType === 'default' && !node.li.startsWith('returns')) {
args.push(parseArgument(node.li));
}
}
api.setText([comment, header, renderMd(nodes), footer].join('\n'));
// Generate links
preprocessor.generateLinks(api, signatures, messages);
}
2020-12-03 00:50:10 +03:00
}
2019-11-19 05:18:28 +03:00
// Documentation checks.
{
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];
2019-11-19 05:18:28 +03:00
const browserVersions = await getBrowserVersions();
messages.push(...(await preprocessor.runCommands(mdSources, {
libversion: VERSION,
chromiumVersion: browserVersions.chromium,
firefoxVersion: browserVersions.firefox,
onlyBrowserVersions,
})));
if (!onlyBrowserVersions) {
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 browser = await playwright.chromium.launch();
const page = await browser.newPage();
const checkPublicAPI = require('./check_public_api');
const jsSources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []);
messages.push(...await checkPublicAPI(page, [api], jsSources));
await browser.close();
}
2019-11-19 05:18:28 +03:00
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 || onlyBrowserVersions ? 0 : 1);
2019-11-19 05:18:28 +03:00
}
async function getBrowserVersions() {
const [chromium, firefox] = await Promise.all([
getChromeVersion(),
getFirefoxVersion(),
])
return {
chromium,
firefox,
};
}
async function getChromeVersion() {
if (os.platform() === 'win32' || os.platform() === 'cygwin') {
const browser = await playwright.chromium.launch();
const page = await browser.newPage();
const userAgent = await page.evaluate('navigator.userAgent');
const [type] = userAgent.split(' ').filter(str => str.includes('Chrome'));
await browser.close();
return type.split('/')[1];
}
const version = spawnSync(playwright.chromium.executablePath(), ['--version'], undefined).stdout.toString();
return version.trim().split(' ').pop();
}
function getRepositoryFiles() {
const out = spawnSync('git', ['ls-files'], {cwd: PROJECT_DIR});
return out.stdout.toString().trim().split('\n').map(file => path.join(PROJECT_DIR, file));
}
async function getFirefoxVersion() {
const isWin = os.platform() === 'win32' || os.platform() === 'cygwin';
const out = spawnSync(playwright.firefox.executablePath(), [isWin ? '/version' : '--version'], undefined);
const version = out.stdout.toString();
return version.trim().split(' ').pop();
}