puppeteer/utils/doclint/cli.js

129 lines
4.3 KiB
JavaScript
Raw Normal View History

#!/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 puppeteer = require('../..');
const path = require('path');
const Source = require('./Source');
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();
async function run() {
const startTime = Date.now();
/** @type {!Array<!Message>} */
const messages = [];
let changedFiles = false;
// Documentation checks.
feat(TypeScript): move DeviceDescriptors to TS (#5595) This commit moves `src/DeviceDescriptors` to be authored in TypeScript. This file was chosen due to its simplicity so that we can focus on getting a mixed JS/TS codebase playing nicely before migrating the more complex files. The file itself was a bit odd: although the array of devices was exported via `module.exports` that was never referenced by any consumers; each device was also exported via `module.exports[name] = device` and that is how it's consumed. The Puppeteer docs suggest using it like so: ```js puppeteer.devices['iPhone 6'] ``` So instead of exporting the array and then setting a bunch of properties on that, we instead define the array and export an object of keys where each key is a device. This is a breaking change (see the footer for details). Rather than export an object I'd much rather export a Map, but that would be a larger breaking change and I'm keen to avoid those for the time being. Note that we have to use special TypeScript specific syntax for the export that enables it to work in a CommonJS codebase [1] but again I'd rather this than move to ESM at this time. TypeScript still outputs CommonJS into `lib/` as you would expect. BREAKING CHANGE: We no longer export an array of devices, so any users relying on doing: ```js puppeter.devices.forEach(...) ``` …will now see a breakage. The fix is to use `Object.{keys/entries/values}` to iterate instead. [1]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
2020-04-14 09:55:29 +00:00
const readme = await Source.readFile(path.join(PROJECT_DIR, 'README.md'));
2020-05-07 10:54:55 +00:00
const contributing = await Source.readFile(
path.join(PROJECT_DIR, 'CONTRIBUTING.md')
);
feat(TypeScript): move DeviceDescriptors to TS (#5595) This commit moves `src/DeviceDescriptors` to be authored in TypeScript. This file was chosen due to its simplicity so that we can focus on getting a mixed JS/TS codebase playing nicely before migrating the more complex files. The file itself was a bit odd: although the array of devices was exported via `module.exports` that was never referenced by any consumers; each device was also exported via `module.exports[name] = device` and that is how it's consumed. The Puppeteer docs suggest using it like so: ```js puppeteer.devices['iPhone 6'] ``` So instead of exporting the array and then setting a bunch of properties on that, we instead define the array and export an object of keys where each key is a device. This is a breaking change (see the footer for details). Rather than export an object I'd much rather export a Map, but that would be a larger breaking change and I'm keen to avoid those for the time being. Note that we have to use special TypeScript specific syntax for the export that enables it to work in a CommonJS codebase [1] but again I'd rather this than move to ESM at this time. TypeScript still outputs CommonJS into `lib/` as you would expect. BREAKING CHANGE: We no longer export an array of devices, so any users relying on doing: ```js puppeter.devices.forEach(...) ``` …will now see a breakage. The fix is to use `Object.{keys/entries/values}` to iterate instead. [1]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
2020-04-14 09:55:29 +00:00
const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
2020-05-07 10:54:55 +00:00
const troubleshooting = await Source.readFile(
path.join(PROJECT_DIR, 'docs', 'troubleshooting.md')
);
feat(TypeScript): move DeviceDescriptors to TS (#5595) This commit moves `src/DeviceDescriptors` to be authored in TypeScript. This file was chosen due to its simplicity so that we can focus on getting a mixed JS/TS codebase playing nicely before migrating the more complex files. The file itself was a bit odd: although the array of devices was exported via `module.exports` that was never referenced by any consumers; each device was also exported via `module.exports[name] = device` and that is how it's consumed. The Puppeteer docs suggest using it like so: ```js puppeteer.devices['iPhone 6'] ``` So instead of exporting the array and then setting a bunch of properties on that, we instead define the array and export an object of keys where each key is a device. This is a breaking change (see the footer for details). Rather than export an object I'd much rather export a Map, but that would be a larger breaking change and I'm keen to avoid those for the time being. Note that we have to use special TypeScript specific syntax for the export that enables it to work in a CommonJS codebase [1] but again I'd rather this than move to ESM at this time. TypeScript still outputs CommonJS into `lib/` as you would expect. BREAKING CHANGE: We no longer export an array of devices, so any users relying on doing: ```js puppeter.devices.forEach(...) ``` …will now see a breakage. The fix is to use `Object.{keys/entries/values}` to iterate instead. [1]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
2020-04-14 09:55:29 +00:00
const mdSources = [readme, api, troubleshooting, contributing];
feat(TypeScript): move DeviceDescriptors to TS (#5595) This commit moves `src/DeviceDescriptors` to be authored in TypeScript. This file was chosen due to its simplicity so that we can focus on getting a mixed JS/TS codebase playing nicely before migrating the more complex files. The file itself was a bit odd: although the array of devices was exported via `module.exports` that was never referenced by any consumers; each device was also exported via `module.exports[name] = device` and that is how it's consumed. The Puppeteer docs suggest using it like so: ```js puppeteer.devices['iPhone 6'] ``` So instead of exporting the array and then setting a bunch of properties on that, we instead define the array and export an object of keys where each key is a device. This is a breaking change (see the footer for details). Rather than export an object I'd much rather export a Map, but that would be a larger breaking change and I'm keen to avoid those for the time being. Note that we have to use special TypeScript specific syntax for the export that enables it to work in a CommonJS codebase [1] but again I'd rather this than move to ESM at this time. TypeScript still outputs CommonJS into `lib/` as you would expect. BREAKING CHANGE: We no longer export an array of devices, so any users relying on doing: ```js puppeter.devices.forEach(...) ``` …will now see a breakage. The fix is to use `Object.{keys/entries/values}` to iterate instead. [1]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
2020-04-14 09:55:29 +00:00
const preprocessor = require('./preprocessor');
2020-05-07 10:54:55 +00:00
messages.push(...(await preprocessor.runCommands(mdSources, VERSION)));
messages.push(
...(await preprocessor.ensureReleasedAPILinks([readme], VERSION))
);
feat(TypeScript): move DeviceDescriptors to TS (#5595) This commit moves `src/DeviceDescriptors` to be authored in TypeScript. This file was chosen due to its simplicity so that we can focus on getting a mixed JS/TS codebase playing nicely before migrating the more complex files. The file itself was a bit odd: although the array of devices was exported via `module.exports` that was never referenced by any consumers; each device was also exported via `module.exports[name] = device` and that is how it's consumed. The Puppeteer docs suggest using it like so: ```js puppeteer.devices['iPhone 6'] ``` So instead of exporting the array and then setting a bunch of properties on that, we instead define the array and export an object of keys where each key is a device. This is a breaking change (see the footer for details). Rather than export an object I'd much rather export a Map, but that would be a larger breaking change and I'm keen to avoid those for the time being. Note that we have to use special TypeScript specific syntax for the export that enables it to work in a CommonJS codebase [1] but again I'd rather this than move to ESM at this time. TypeScript still outputs CommonJS into `lib/` as you would expect. BREAKING CHANGE: We no longer export an array of devices, so any users relying on doing: ```js puppeter.devices.forEach(...) ``` …will now see a breakage. The fix is to use `Object.{keys/entries/values}` to iterate instead. [1]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
2020-04-14 09:55:29 +00:00
const browser = await puppeteer.launch();
const page = await browser.newPage();
const checkPublicAPI = require('./check_public_api');
const tsSources = [
/* Source.readdir doesn't deal with nested directories well.
* Rather than invest time here when we're going to remove this Doc tooling soon
* we'll just list the directories manually.
*/
...(await Source.readdir(path.join(PROJECT_DIR, 'src'), 'ts')),
...(await Source.readdir(path.join(PROJECT_DIR, 'src', 'common'), 'ts')),
...(await Source.readdir(path.join(PROJECT_DIR, 'src', 'node'), 'ts')),
];
2020-05-07 10:54:55 +00:00
const tsSourcesNoDefinitions = tsSources.filter(
(source) => !source.filePath().endsWith('.d.ts')
);
const jsSources = [
...(await Source.readdir(path.join(PROJECT_DIR, 'lib'))),
chore(agnostic): ship CJS and ESM builds (#6095) * chore(agnostic): ship CJS and ESM builds For our work to enable Puppeteer in other environments (e.g. a browser) we need to ship an ESM build. This commit changes our config to ship to `lib/cjs` and `lib/esm` accordingly. The majority of our code stays the same, with one small fix for the CJS build to ensure that we ship a version that lets you `require('puppeteer')` rather than have to `require('puppeteer').default`. We do this with the `cjs-entry.js` which is what the `main` field in our `package.json` points to. We also swap to `read-pkg-up` to find the `package.json` file. This is because the folder structure of `lib/` does not match `src/` now we ship to `cjs` and `esm`, so you cannot rely on exact paths. This module works up from the file to find the nearest `package.json` so it will always find Puppeteer's `package.json`. Note that we *do not* point any users to the ESM build. We happen to ship those files so people who know about them can get at them but it's not expected (nor will we actively support) that people will rely on them. The CommonJS build is considered our main build. We may make breaking changes to the structure of the ESM build which we will do without requiring new major versions. For example the ESM build currently ships all files that the CJS build does, but given we are working on the ESM build being able to run in the browser this may change over time. Long term once the Node versions catch up we can ditch CJS and ship exclusively ESM but we are not there yet.
2020-06-25 13:24:46 +00:00
...(await Source.readdir(path.join(PROJECT_DIR, 'lib', 'cjs'))),
...(await Source.readdir(
path.join(PROJECT_DIR, 'lib', 'cjs', 'puppeteer', 'common')
)),
...(await Source.readdir(
path.join(PROJECT_DIR, 'lib', 'cjs', 'puppeteer', 'node')
)),
];
const allSrcCode = [...jsSources, ...tsSourcesNoDefinitions];
2020-05-07 10:54:55 +00:00
messages.push(...(await checkPublicAPI(page, mdSources, allSrcCode)));
feat(TypeScript): move DeviceDescriptors to TS (#5595) This commit moves `src/DeviceDescriptors` to be authored in TypeScript. This file was chosen due to its simplicity so that we can focus on getting a mixed JS/TS codebase playing nicely before migrating the more complex files. The file itself was a bit odd: although the array of devices was exported via `module.exports` that was never referenced by any consumers; each device was also exported via `module.exports[name] = device` and that is how it's consumed. The Puppeteer docs suggest using it like so: ```js puppeteer.devices['iPhone 6'] ``` So instead of exporting the array and then setting a bunch of properties on that, we instead define the array and export an object of keys where each key is a device. This is a breaking change (see the footer for details). Rather than export an object I'd much rather export a Map, but that would be a larger breaking change and I'm keen to avoid those for the time being. Note that we have to use special TypeScript specific syntax for the export that enables it to work in a CommonJS codebase [1] but again I'd rather this than move to ESM at this time. TypeScript still outputs CommonJS into `lib/` as you would expect. BREAKING CHANGE: We no longer export an array of devices, so any users relying on doing: ```js puppeter.devices.forEach(...) ``` …will now see a breakage. The fix is to use `Object.{keys/entries/values}` to iterate instead. [1]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
2020-04-14 09:55:29 +00:00
await browser.close();
feat(TypeScript): move DeviceDescriptors to TS (#5595) This commit moves `src/DeviceDescriptors` to be authored in TypeScript. This file was chosen due to its simplicity so that we can focus on getting a mixed JS/TS codebase playing nicely before migrating the more complex files. The file itself was a bit odd: although the array of devices was exported via `module.exports` that was never referenced by any consumers; each device was also exported via `module.exports[name] = device` and that is how it's consumed. The Puppeteer docs suggest using it like so: ```js puppeteer.devices['iPhone 6'] ``` So instead of exporting the array and then setting a bunch of properties on that, we instead define the array and export an object of keys where each key is a device. This is a breaking change (see the footer for details). Rather than export an object I'd much rather export a Map, but that would be a larger breaking change and I'm keen to avoid those for the time being. Note that we have to use special TypeScript specific syntax for the export that enables it to work in a CommonJS codebase [1] but again I'd rather this than move to ESM at this time. TypeScript still outputs CommonJS into `lib/` as you would expect. BREAKING CHANGE: We no longer export an array of devices, so any users relying on doing: ```js puppeter.devices.forEach(...) ``` …will now see a breakage. The fix is to use `Object.{keys/entries/values}` to iterate instead. [1]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
2020-04-14 09:55:29 +00:00
for (const source of mdSources) {
2020-05-07 10:54:55 +00:00
if (!source.hasUpdatedText()) continue;
feat(TypeScript): move DeviceDescriptors to TS (#5595) This commit moves `src/DeviceDescriptors` to be authored in TypeScript. This file was chosen due to its simplicity so that we can focus on getting a mixed JS/TS codebase playing nicely before migrating the more complex files. The file itself was a bit odd: although the array of devices was exported via `module.exports` that was never referenced by any consumers; each device was also exported via `module.exports[name] = device` and that is how it's consumed. The Puppeteer docs suggest using it like so: ```js puppeteer.devices['iPhone 6'] ``` So instead of exporting the array and then setting a bunch of properties on that, we instead define the array and export an object of keys where each key is a device. This is a breaking change (see the footer for details). Rather than export an object I'd much rather export a Map, but that would be a larger breaking change and I'm keen to avoid those for the time being. Note that we have to use special TypeScript specific syntax for the export that enables it to work in a CommonJS codebase [1] but again I'd rather this than move to ESM at this time. TypeScript still outputs CommonJS into `lib/` as you would expect. BREAKING CHANGE: We no longer export an array of devices, so any users relying on doing: ```js puppeter.devices.forEach(...) ``` …will now see a breakage. The fix is to use `Object.{keys/entries/values}` to iterate instead. [1]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
2020-04-14 09:55:29 +00:00
await source.save();
changedFiles = true;
}
// Report results.
2020-05-07 10:54:55 +00:00
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}`);
}
}
2020-05-07 10:54:55 +00:00
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.`);
if (!clearExit && !process.env.TRAVIS)
2020-05-07 10:54:55 +00:00
console.log(
'\nIs your lib/ directory up to date? You might need to `npm run tsc`.\n'
);
const runningTime = Date.now() - startTime;
console.log(`DocLint Finished in ${runningTime / 1000} seconds`);
process.exit(clearExit ? 0 : 1);
}