devops: auto-correct links in our documentation (#1955)

Author: aslushnikov

docs/README.md

@@ -7,7 +7,7 @@
     - [Pages and frames](./core-concepts.md#pages-and-frames)
     - [Selectors](./core-concepts.md#selectors)
     - [Auto-waiting](./core-concepts.md#auto-waiting)
-    - [Node.js and browser execution contexts](./core-concepts.md#node-js-and-browser-execution-contexts)
+    - [Node.js and browser execution contexts](./core-concepts.md#nodejs-and-browser-execution-contexts)
     - [Object & element handles](./core-concepts.md#object--element-handles)
 1. [Input](./input.md)
     - [Text input](./input.md#text-input)

docs/core-concepts.md

@@ -14,14 +14,14 @@ the following primitives.
   - [Pages and frames](#pages-and-frames)
   - [Selectors](#selectors)
   - [Auto-waiting](#auto-waiting)
-  - [Node.js and browser execution contexts](#node-js-and-browser-execution-contexts)
+  - [Node.js and browser execution contexts](#nodejs-and-browser-execution-contexts)
   - [Object & element handles](#object--element-handles)
 
 <br/>
 
 ## Browser
 
-A [`Browser`](../api.md#class-browser) refers to an instance of Chromium, Firefox
+A [`Browser`](api.md#class-browser) refers to an instance of Chromium, Firefox
 or WebKit. Playwright scripts generally start with launching a browser instance
 and end with closing the browser. Browser instances can be launched in headless
 (without a GUI) or headful mode.
@@ -44,7 +44,7 @@ maximize what a single instance can do through multiple browser contexts.
 
 ## Browser contexts
 
-A [`BrowserContext`](../api.md#class-browsercontext) is an isolated incognito-alike
+A [`BrowserContext`](api.md#class-browsercontext) is an isolated incognito-alike
 session within a browser instance. Browser contexts are fast and cheap to create.
 Browser contexts can be used to parallelize isolated test executions.
 
@@ -71,13 +71,13 @@ const context = await browser.newContext({
 
 #### API reference
 
-- [class `BrowserContext`](./api.md#class-browser-context)
+- [class `BrowserContext`](./api.md#class-browsercontext)
 
 <br/>
 
 ## Pages and frames
 
-A Browser context can have multiple pages. A [`Page`](../api.md#class-page)
+A Browser context can have multiple pages. A [`Page`](api.md#class-page)
 refers to a single tab or a popup window within a browser context. It should be used to navigate to URLs and interact with the page content.
 
 ```js
@@ -104,7 +104,7 @@ console.log(page.url());
 window.location.href = 'https://example.com';
 ```
 
-A page can have one or more [Frame](../api.md#class-frame) objects attached to
+A page can have one or more [Frame](api.md#class-frame) objects attached to
 it. Each page has a main frame and page-level interactions (like `click`) are
 assumed to operate in the main frame.
 

docs/loading.md

@@ -64,7 +64,7 @@ Explicit loading handling may be required for more complicated scenarios though.
 
 ### Loading a popup
 
-When popup is opened, explicitly calling [`page.waitForLoadState()`](#pagewaitforloadstatestate-options) ensures that popup is loaded to the desired state.
+When popup is opened, explicitly calling [`page.waitForLoadState()`](api.md#pagewaitforloadstatestate-options) ensures that popup is loaded to the desired state.
 ```js
 const [ popup ] = await Promise.all([
   page.waitForEvent('popup'),
@@ -76,7 +76,7 @@ await popup.evaluate(() => window.globalVariableInitializedByOnLoadHandler);
 
 ### Unusual client-side redirects
 
-Usually, the client-side redirect happens before the `load` event, and `page.goto()` method automatically waits for the redirect. However, when redirecting from a link click or after the `load` event, it would be easier to explicitly [`waitForNavigation()`](#pagewaitfornavigationoptions) to a specific url.
+Usually, the client-side redirect happens before the `load` event, and `page.goto()` method automatically waits for the redirect. However, when redirecting from a link click or after the `load` event, it would be easier to explicitly [`waitForNavigation()`](api.md#pagewaitfornavigationoptions) to a specific url.
 ```js
 await Promise.all([
   page.waitForNavigation({ url: '**/login' }),
@@ -88,7 +88,7 @@ Notice the `Promise.all` to click and wait for navigation. Awaiting these method
 
 ### Click triggers navigation after a timeout
 
-When `onclick` handler triggers a navigation from a `setTimeout`, use an explicit [`waitForNavigation()`](#pagewaitfornavigationoptions) call as a last resort.
+When `onclick` handler triggers a navigation from a `setTimeout`, use an explicit [`waitForNavigation()`](api.md#pagewaitfornavigationoptions) call as a last resort.
 ```js
 await Promise.all([
   page.waitForNavigation(), // Waits for the next navigation.
@@ -108,7 +108,7 @@ await page.waitForFunction(() => window.amILoadedYet());
 await page.screenshot();
 ```
 
-When clicking on a button triggers some asynchronous processing, issues a couple GET requests and pushes a new history state multiple times, explicit [`waitForNavigation()`](#pagewaitfornavigationoptions) to a specific url is the most reliable option.
+When clicking on a button triggers some asynchronous processing, issues a couple GET requests and pushes a new history state multiple times, explicit [`waitForNavigation()`](api.md#pagewaitfornavigationoptions) to a specific url is the most reliable option.
 ```js
 await Promise.all([
   page.waitForNavigation({ url: '**/invoice#processed' }),

utils/doclint/Source.js

@@ -121,7 +121,8 @@ class Source {
    * @return {!Promise<!Array<!Source>>}
    */
   static async readdir(dirPath, extension = '') {
-    const filePaths = (await recursiveReadDir(dirPath)).filter(fileName => fileName.endsWith(extension));
+    extension = extension.toLowerCase();
+    const filePaths = (await recursiveReadDir(dirPath)).filter(fileName => fileName.toLowerCase().endsWith(extension));
     return Promise.all(filePaths.map(filePath => Source.readFile(filePath)));
   }
 }

utils/doclint/cli.js

@@ -18,6 +18,7 @@
 const playwright = require('../../index.js');
 const path = require('path');
 const Source = require('./Source');
+const Message = require('./Message');
 
 const {spawnSync} = require('child_process');
 
@@ -44,8 +45,8 @@ async function run() {
     const readme = await Source.readFile(path.join(PROJECT_DIR, 'README.md'));
     const contributing = await Source.readFile(path.join(PROJECT_DIR, 'CONTRIBUTING.md'));
     const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
-    const troubleshooting = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'troubleshooting.md'));
-    const mdSources = [readme, api, contributing, troubleshooting];
+    const docs = await Source.readdir(path.join(PROJECT_DIR, 'docs'), '.md');
+    const mdSources = [readme, api, contributing, ...docs];
 
     const preprocessor = require('./preprocessor');
     const browserVersions = await getBrowserVersions();
@@ -54,13 +55,15 @@ async function run() {
       chromiumVersion: browserVersions.chromium,
       firefoxVersion: browserVersions.firefox,
     })));
-    messages.push(...preprocessor.ensureInternalLinksAreValid([api]));
+    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'));
-    messages.push(...await checkPublicAPI(page, mdSources, jsSources));
+    messages.push(...await checkPublicAPI(page, [api], jsSources));
     await browser.close();
 
     for (const source of mdSources) {
@@ -126,6 +129,11 @@ async function getChromeVersion() {
   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);