mirror of
https://github.com/microsoft/playwright.git
synced 2024-12-15 14:11:50 +03:00
225 lines
7.9 KiB
JavaScript
Executable File
225 lines
7.9 KiB
JavaScript
Executable File
#!/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.
|
|
*/
|
|
|
|
//@ts-check
|
|
|
|
const playwright = require('../../');
|
|
const fs = require('fs');
|
|
const path = require('path');
|
|
const Source = require('./Source');
|
|
const md = require('../markdown');
|
|
const { spawnSync } = require('child_process');
|
|
const preprocessor = require('./preprocessor');
|
|
const { MDOutline } = require('./MDBuilder');
|
|
const missingDocs = require('./missingDocs');
|
|
|
|
/** @typedef {import('./Documentation').Type} Type */
|
|
/** @typedef {import('../markdown').MarkdownNode} MarkdownNode */
|
|
|
|
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<string>} */
|
|
const errors = [];
|
|
let changedFiles = false;
|
|
|
|
const header = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-header.md')).toString();
|
|
const footer = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-footer.md')).toString();
|
|
const links = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-links.md')).toString();
|
|
const outline = new MDOutline(path.join(PROJECT_DIR, 'docs-src', 'api-body.md'), path.join(PROJECT_DIR, 'docs-src', 'api-params.md'));
|
|
|
|
// Produce api.md
|
|
{
|
|
const comment = '<!-- THIS FILE IS NOW GENERATED -->';
|
|
{
|
|
const signatures = outline.signatures;
|
|
/** @type {MarkdownNode[]} */
|
|
const result = [];
|
|
for (const clazz of outline.classesArray) {
|
|
// Iterate over classes, create header node.
|
|
/** @type {MarkdownNode} */
|
|
const classNode = { type: 'h3', text: `class: ${clazz.name}` };
|
|
const match = clazz.name.match(/(JS|CDP|[A-Z])(.*)/);
|
|
const varName = match[1].toLocaleLowerCase() + match[2];
|
|
result.push(classNode);
|
|
// Append link shortcut to resolve text like [Browser]
|
|
result.push({
|
|
type: 'text',
|
|
text: `[${clazz.name}]: #class-${clazz.name.toLowerCase()} "${clazz.name}"`
|
|
});
|
|
// Append class comments
|
|
classNode.children = (clazz.spec || []).map(c => md.clone(c));
|
|
|
|
for (const member of clazz.membersArray) {
|
|
// Iterate members
|
|
/** @type {MarkdownNode} */
|
|
const memberNode = { type: 'h4', children: [] };
|
|
if (member.kind === 'event') {
|
|
memberNode.text = `${varName}.on('${member.name}')`;
|
|
} else if (member.kind === 'property') {
|
|
memberNode.text = `${varName}.${member.name}`;
|
|
} else if (member.kind === 'method') {
|
|
// Patch method signatures
|
|
const signature = signatures.get(clazz.name + '.' + member.name);
|
|
memberNode.text = `${varName}.${member.name}(${signature})`;
|
|
for (const arg of member.argsArray) {
|
|
if (arg.type)
|
|
memberNode.children.push(renderProperty(`\`${arg.name}\``, arg.type, arg.spec));
|
|
}
|
|
}
|
|
|
|
// Append type
|
|
if (member.type && member.type.name !== 'void') {
|
|
let name;
|
|
switch (member.kind) {
|
|
case 'event': name = 'type:'; break;
|
|
case 'property': name = 'type:'; break;
|
|
case 'method': name = 'returns:'; break;
|
|
}
|
|
memberNode.children.push(renderProperty(name, member.type));
|
|
}
|
|
|
|
// Append member doc
|
|
memberNode.children.push(...(member.spec || []).map(c => md.clone(c)));
|
|
classNode.children.push(memberNode);
|
|
}
|
|
}
|
|
result.push({
|
|
type: 'text',
|
|
text: links
|
|
});
|
|
api.setText([comment, header, md.render(result), footer].join('\n'));
|
|
}
|
|
}
|
|
|
|
// Documentation checks.
|
|
{
|
|
const browserVersions = await getBrowserVersions();
|
|
errors.push(...(await preprocessor.runCommands(mdSources, {
|
|
libversion: VERSION,
|
|
chromiumVersion: browserVersions.chromium,
|
|
firefoxVersion: browserVersions.firefox,
|
|
webkitVersion: browserVersions.webkit,
|
|
})));
|
|
|
|
errors.push(...preprocessor.autocorrectInvalidLinks(PROJECT_DIR, mdSources, getRepositoryFiles()));
|
|
for (const source of mdSources.filter(source => source.hasUpdatedText()))
|
|
errors.push(`WARN: updated ${source.projectPath()}`);
|
|
|
|
const jsSources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []);
|
|
errors.push(...missingDocs(outline, jsSources, path.join(PROJECT_DIR, 'src', 'client', 'api.ts')));
|
|
|
|
for (const source of mdSources) {
|
|
if (!source.hasUpdatedText())
|
|
continue;
|
|
await source.save();
|
|
changedFiles = true;
|
|
}
|
|
}
|
|
|
|
// Report results.
|
|
if (errors.length) {
|
|
for (let i = 0; i < errors.length; ++i) {
|
|
const error = errors[i].split('\n').join('\n ');
|
|
console.log(` ${i + 1}) ${RED_COLOR}${error}${RESET_COLOR}`);
|
|
}
|
|
}
|
|
let clearExit = errors.length === 0;
|
|
if (changedFiles) {
|
|
if (clearExit)
|
|
console.log(`${YELLOW_COLOR}Some files were updated.${RESET_COLOR}`);
|
|
clearExit = false;
|
|
}
|
|
console.log(`${errors.length} failures.`);
|
|
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));
|
|
}
|
|
|
|
/**
|
|
* @param {string} name
|
|
* @param {Type} type
|
|
* @param {MarkdownNode[]} [spec]
|
|
*/
|
|
function renderProperty(name, type, spec) {
|
|
let comment = '';
|
|
if (spec && spec.length)
|
|
comment = spec[0].text;
|
|
let children;
|
|
if (type.properties && type.properties.length)
|
|
children = type.properties.map(p => renderProperty(`\`${p.name}\``, p.type, p.spec))
|
|
else if (spec && spec.length > 1)
|
|
children = spec.slice(1).map(s => md.clone(s));
|
|
|
|
/** @type {MarkdownNode} */
|
|
const result = {
|
|
type: 'li',
|
|
liType: 'default',
|
|
text: `${name} <${renderType(type.name)}>${comment ? ' ' + comment : ''}`,
|
|
children
|
|
};
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* @param {string} type
|
|
*/
|
|
function renderType(type) {
|
|
if (type.includes('"'))
|
|
return type.replace(/,/g, '|').replace(/Array/, "[Array]").replace(/null/, "[null]").replace(/number/, "[number]");
|
|
const result = type.replace(/([\w]+)/g, '[$1]');
|
|
if (result === '[Promise]<[void]>')
|
|
return '[Promise]';
|
|
return result.replace(/[(]/g, '\\(').replace(/[)]/g, '\\)');
|
|
}
|