step-node-agent 3.20.2 → 3.21.0

package/node_modules/npm/docs/dockhand.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const yaml = require('yaml');
+const cmark = require('cmark-gfm');
+const mdx = require('@mdx-js/mdx');
+const mkdirp = require('mkdirp');
+const jsdom = require('jsdom');
+const npm = require('../lib/npm.js')
+
+const config = require('./config.json');
+
+const docsRoot = __dirname;
+const inputRoot = path.join(docsRoot, 'content');
+const outputRoot = path.join(docsRoot, 'output');
+
+const template = fs.readFileSync('template.html').toString();
+
+const run = async function() {
+    try {
+        const navPaths = await getNavigationPaths();
+        const fsPaths = await renderFilesystemPaths();
+
+        if (!ensureNavigationComplete(navPaths, fsPaths)) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(error);
+    }
+}
+
+run();
+
+function ensureNavigationComplete(navPaths, fsPaths) {
+    const unmatchedNav = { }, unmatchedFs = { };
+
+    for (const navPath of navPaths) {
+        unmatchedNav[navPath] = true;
+    }
+
+    for (let fsPath of fsPaths) {
+        fsPath = '/' + fsPath.replace(/\.md$/, "");
+
+        if (unmatchedNav[fsPath]) {
+            delete unmatchedNav[fsPath];
+        }
+        else {
+            unmatchedFs[fsPath] = true;
+        }
+    }
+
+    const missingNav = Object.keys(unmatchedNav).sort();
+    const missingFs = Object.keys(unmatchedFs).sort()
+
+    if (missingNav.length > 0 || missingFs.length > 0) {
+        let message = "Error: documentation navigation (nav.yml) does not match filesystem.\n";
+
+        if (missingNav.length > 0) {
+            message += "\nThe following path(s) exist on disk but are not present in nav.yml:\n\n";
+
+            for (const nav of missingNav) {
+                message += `  ${nav}\n`;
+            }
+        }
+
+        if (missingNav.length > 0 && missingFs.length > 0) {
+            message += "\nThe following path(s) exist in nav.yml but are not present on disk:\n\n";
+
+            for (const fs of missingFs) {
+                message += `  ${fs}\n`;
+            }
+        }
+
+        message += "\nUpdate nav.yml to ensure that all files are listed in the appropriate place.";
+
+        console.error(message);
+
+        return false;
+    }
+
+    return true;
+}
+
+function getNavigationPaths() {
+    const navFilename = path.join(docsRoot, 'nav.yml');
+    const nav = yaml.parse(fs.readFileSync(navFilename).toString(), 'utf8');
+
+    return walkNavigation(nav);
+}
+
+function walkNavigation(entries) {
+    const paths = [ ]
+
+    for (const entry of entries) {
+        if (entry.children) {
+            paths.push(... walkNavigation(entry.children));
+        }
+        else {
+            paths.push(entry.url);
+        }
+    }
+
+    return paths;
+}
+
+async function renderFilesystemPaths() {
+    return await walkFilesystem(inputRoot);
+}
+
+async function walkFilesystem(root, dirRelative) {
+    const paths = [ ]
+
+    const dirPath = dirRelative ? path.join(root, dirRelative) : root;
+    const children = fs.readdirSync(dirPath);
+
+    for (const childFilename of children) {
+        const childRelative = dirRelative ? path.join(dirRelative, childFilename) : childFilename;
+        const childPath = path.join(root, childRelative);
+
+        if (fs.lstatSync(childPath).isDirectory()) {
+            paths.push(... await walkFilesystem(root, childRelative));
+        }
+        else {
+            await renderFile(childRelative);
+            paths.push(childRelative);
+        }
+    }
+
+    return paths;
+}
+
+async function renderFile(childPath) {
+    const inputPath = path.join(inputRoot, childPath);
+
+    if (!inputPath.match(/\.md$/)) {
+        console.log(`warning: unknown file type ${inputPath}, ignored`);
+        return;
+    }
+
+    const outputPath = path.join(outputRoot, childPath.replace(/\.md$/, '.html'));
+
+    let md = fs.readFileSync(inputPath).toString();
+    let frontmatter = { };
+
+    // Take the leading frontmatter out of the markdown
+    md = md.replace(/^---\n([\s\S]+)\n---\n/, (header, fm) => {
+        frontmatter = yaml.parse(fm, 'utf8');
+        return '';
+    });
+
+    // Replace any tokens in the source
+    md = md.replace(/@VERSION@/, npm.version);
+
+    // Render the markdown into an HTML snippet using a GFM renderer.
+    const content = cmark.renderHtmlSync(md, {
+        'smart': true,
+        'githubPreLang': true,
+        'strikethroughDoubleTilde': true,
+        'unsafe': false,
+        extensions: {
+            'table': true,
+            'strikethrough': true,
+            'tagfilter': true,
+            'autolink': true
+        }
+    });
+
+    // Test that mdx can parse this markdown file.  We don't actually
+    // use the output, it's just to ensure that the upstream docs
+    // site (docs.npmjs.com) can parse it when this file gets there.
+    try {
+        await mdx(md, { skipExport: true });
+    }
+    catch (error) {
+        throw new MarkdownError(childPath, error);
+    }
+
+    // Inject this data into the template, using a mustache-like
+    // replacement scheme.
+    const html = template.replace(/\{\{\s*([\w\.]+)\s*\}\}/g, (token, key) => {
+        switch (key) {
+            case 'content':
+                return `<div id="_content">${content}</div>`;
+            case 'path':
+                return childPath;
+            case 'url_path':
+                return encodeURI(childPath);
+
+            case 'toc':
+                return '<div id="_table_of_contents"></div>';
+
+            case 'title':
+            case 'section':
+            case 'description':
+                return frontmatter[key];
+
+            case 'config.github_repo':
+            case 'config.github_branch':
+            case 'config.github_path':
+                return config[key.replace(/^config\./, '')];
+
+            default:
+                console.log(`warning: unknown token '${token}' in ${inputPath}`);
+                return '';
+        }
+        return key;
+    });
+
+    const dom = new jsdom.JSDOM(html);
+    const document = dom.window.document;
+
+    // Rewrite relative URLs in links and image sources to be relative to
+    // this file; this is for supporting `file://` links.  HTML pages need
+    // suffix appended.
+    const links = [
+        { tag: 'a', attr: 'href', suffix: '.html' },
+        { tag: 'img', attr: 'src' }
+    ];
+
+    for (let linktype of links) {
+        for (let tag of document.querySelectorAll(linktype.tag)) {
+            let url = tag.getAttribute(linktype.attr);
+
+            if (url.startsWith('/')) {
+                const childDepth = childPath.split('/').length - 1;
+                const prefix = childDepth > 0 ? '../'.repeat(childDepth) : './';
+
+                url = url.replace(/^\//, prefix);
+
+                if (linktype.suffix) {
+                    url += linktype.suffix;
+                }
+
+                tag.setAttribute(linktype.attr, url);
+            }
+        }
+    }
+
+    // Give headers a unique id so that they can be linked within the doc
+    const headerIds = [ ];
+    for (let header of document.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+        if (header.getAttribute('id')) {
+            headerIds.push(header.getAttribute('id'));
+            continue;
+        }
+
+        const headerText = header.textContent.replace(/[A-Z]/g, x => x.toLowerCase()).replace(/ /g, '-').replace(/[^a-z0-9\-]/g, '');
+        let headerId = headerText;
+        let headerIncrement = 1;
+
+        while (document.getElementById(headerId) !== null) {
+            headerId = headerText + (++headerIncrement);
+        }
+
+        headerIds.push(headerId);
+        header.setAttribute('id', headerId);
+    }
+
+    // Walk the dom and build a table of contents
+    const toc = document.getElementById('_table_of_contents');
+
+    if (toc) {
+        toc.appendChild(generateTableOfContents(document));
+    }
+
+    // Write the final output
+    const output = dom.serialize();
+
+    mkdirp.sync(path.dirname(outputPath));
+    fs.writeFileSync(outputPath, output);
+}
+
+function generateTableOfContents(document) {
+    const headers = [ ];
+    walkHeaders(document.getElementById('_content'), headers);
+
+    let parent = null;
+
+    // The nesting depth of headers are not necessarily the header level.
+    // (eg, h1 > h3 > h5 is a depth of three even though there's an h5.)
+    const hierarchy = [ ];
+    for (let header of headers) {
+        const level = headerLevel(header);
+
+        while (hierarchy.length && hierarchy[hierarchy.length - 1].headerLevel > level) {
+            hierarchy.pop();
+        }
+
+        if (!hierarchy.length || hierarchy[hierarchy.length - 1].headerLevel < level) {
+            const newList = document.createElement('ul');
+            newList.headerLevel = level;
+
+            if (hierarchy.length) {
+                hierarchy[hierarchy.length - 1].appendChild(newList);
+            }
+
+            hierarchy.push(newList);
+        }
+
+        const element = document.createElement('li');
+
+        const link = document.createElement('a');
+        link.setAttribute('href', `#${header.getAttribute('id')}`);
+        link.innerHTML = header.innerHTML;
+        element.appendChild(link);
+
+        const list = hierarchy[hierarchy.length - 1];
+        list.appendChild(element);
+    }
+
+    return hierarchy[0];
+}
+
+function walkHeaders(element, headers) {
+    for (let child of element.childNodes) {
+        if (headerLevel(child)) {
+            headers.push(child);
+        }
+
+        walkHeaders(child, headers);
+    }
+}
+
+function headerLevel(node) {
+    const level = node.tagName ? node.tagName.match(/^[Hh]([123456])$/) : null;
+    return level ? level[1] : 0;
+}
+
+function debug(str) {
+    console.log(str);
+}
+
+class MarkdownError extends Error {
+    constructor(file, inner) {
+        super(`failed to parse ${file}`);
+        this.file = file;
+        this.inner = inner;
+    }
+}

package/node_modules/npm/docs/nav.yml

@@ -0,0 +1,236 @@
+- title: CLI Commands
+  shortName: Commands
+  url: /commands
+  children:
+  - title: npm
+    url: /commands/npm
+    description: JavaScript package manager
+  - title: npm access
+    url: /commands/npm-access
+    description: Set access level on published packages
+  - title: npm adduser
+    url: /commands/npm-adduser
+    description: Add a registry user account
+  - title: npm audit
+    url: /commands/npm-audit
+    description: Run a security audit
+  - title: npm bin
+    url: /commands/npm-bin
+    description: Display npm bin folder
+  - title: npm bugs
+    url: /commands/npm-bugs
+    description: Bugs for a package in a web browser maybe
+  - title: npm build
+    url: /commands/npm-build
+    description: Build a package
+  - title: npm bundle
+    url: /commands/npm-bundle
+    description: Removed
+  - title: npm cache
+    url: /commands/npm-cache
+    description: Manipulates packages cache
+  - title: npm ci
+    url: /commands/npm-ci
+    description: Install a project with a clean slate
+  - title: npm completion
+    url: /commands/npm-completion
+    description: Tab completion for npm
+  - title: npm config
+    url: /commands/npm-config
+    description: Manage the npm configuration files
+  - title: npm dedupe
+    url: /commands/npm-dedupe
+    description: Reduce duplication
+  - title: npm deprecate
+    url: /commands/npm-deprecate
+    description: Deprecate a version of a package
+  - title: npm dist-tag
+    url: /commands/npm-dist-tag
+    description: Modify package distribution tags
+  - title: npm docs
+    url: /commands/npm-docs
+    description: Docs for a package in a web browser maybe
+  - title: npm doctor
+    url: /commands/npm-doctor
+    description: Check your environments
+  - title: npm edit
+    url: /commands/npm-edit
+    description: Edit an installed package
+  - title: npm explore
+    url: /commands/npm-explore
+    description: Browse an installed package
+  - title: npm fund
+    url: /commands/npm-fund
+    description: Retrieve funding information
+  - title: npm help
+    url: /commands/npm-help
+    description: Search npm help documentation
+  - title: npm help-search
+    url: /commands/npm-help-search
+    description: Get help on npm
+  - title: npm hook
+    url: /commands/npm-hook
+    description: Manage registry hooks
+  - title: npm init
+    url: /commands/npm-init
+    description: Create a package.json file
+  - title: npm install
+    url: /commands/npm-install
+    description: Install a package
+  - title: npm install-ci-test
+    url: /commands/npm-install-ci-test
+    description: Install a project with a clean slate and run tests
+  - title: npm install-test
+    url: /commands/npm-install-test
+    description: Install package(s) and run tests
+  - title: npm link
+    url: /commands/npm-link
+    description: Symlink a package folder
+  - title: npm logout
+    url: /commands/npm-logout
+    description: Log out of the registry
+  - title: npm ls
+    url: /commands/npm-ls
+    description: List installed packages
+  - title: npm org
+    url: /commands/npm-org
+    description: Manage orgs
+  - title: npm outdated
+    url: /commands/npm-outdated
+    description: Check for outdated packages
+  - title: npm owner
+    url: /commands/npm-owner
+    description: Manage package owners
+  - title: npm pack
+    url: /commands/npm-pack
+    description: Create a tarball from a package
+  - title: npm ping
+    url: /commands/npm-ping
+    description: Ping npm registry
+  - title: npm prefix
+    url: /commands/npm-prefix
+    description: Display prefix
+  - title: npm profile
+    url: /commands/npm-profile
+    description: Change settings on your registry profile
+  - title: npm prune
+    url: /commands/npm-prune
+    description: Remove extraneous packages
+  - title: npm publish
+    url: /commands/npm-publish
+    description: Publish a package
+  - title: npm rebuild
+    url: /commands/npm-rebuild
+    description: Rebuild a package
+  - title: npm repo
+    url: /commands/npm-repo
+    description: Open package repository page in the browser
+  - title: npm restart
+    url: /commands/npm-restart
+    description: Restart a package
+  - title: npm root
+    url: /commands/npm-root
+    description: Display npm root
+  - title: npm run-script
+    url: /commands/npm-run-script
+    description: Run arbitrary package scripts
+  - title: npm search
+    url: /commands/npm-search
+    description: Search for packages
+  - title: npm shrinkwrap
+    url: /commands/npm-shrinkwrap
+    description: Lock down dependency versions for publication
+  - title: npm star
+    url: /commands/npm-star
+    description: Mark your favorite packages
+  - title: npm stars
+    url: /commands/npm-stars
+    description: View packages marked as favorites
+  - title: npm start
+    url: /commands/npm-start
+    description: Start a package
+  - title: npm stop
+    url: /commands/npm-stop
+    description: Stop a package
+  - title: npm team
+    url: /commands/npm-team
+    description: Manage organization teams and team memberships
+  - title: npm test
+    url: /commands/npm-test
+    description: Test a package
+  - title: npm token
+    url: /commands/npm-token
+    description: Manage your authentication tokens
+  - title: npm uninstall
+    url: /commands/npm-uninstall
+    description: Remove a package
+  - title: npm unpublish
+    url: /commands/npm-unpublish
+    description: Remove a package from the registry
+  - title: npm update
+    url: /commands/npm-update
+    description: Update a package
+  - title: npm version
+    url: /commands/npm-version
+    description: Bump a package version
+  - title: npm view
+    url: /commands/npm-view
+    description: View registry info
+  - title: npm whoami
+    url: /commands/npm-whoami
+    description: Display npm username
+
+- title: Configuring npm
+  shortName: Configuring
+  url: /configuring-npm
+  children:
+  - title: Install
+    url: /configuring-npm/install
+    description: Download and install node and npm
+  - title: Folders
+    url: /configuring-npm/folders
+    description: Folder structures used by npm
+  - title: .npmrc
+    url: /configuring-npm/npmrc
+    description: The npm config files
+  - title: package.json
+    url: /configuring-npm/package-json
+    description: Specifics of npm's package.json handling
+  - title: package-locks
+    url: /configuring-npm/package-locks
+    description: An explanation of npm lockfiles
+  - title: package-lock.json
+    url: /configuring-npm/package-lock-json
+    description: A manifestation of the manifest
+  - title: shrinkwrap.json
+    url: /configuring-npm/shrinkwrap-json
+    description: A publishable lockfile
+
+- title: Using npm
+  shortName: Using
+  url: /using-npm
+  children:
+  - title: Registry
+    url: /using-npm/registry
+    description: The JavaScript Package Registry
+  - title: Config
+    url: /using-npm/config
+    description: About npm configuration
+  - title: semver
+    url: /using-npm/semver
+    description: The semantic versioner for npm
+  - title: Scope
+    url: /using-npm/scope
+    description: Scoped packages
+  - title: Scripts
+    url: /using-npm/scripts
+    description: How npm handles the "scripts" field
+  - title: Organizations
+    url: /using-npm/orgs
+    description: Working with teams & organizations
+  - title: Developers
+    url: /using-npm/developers
+    description: Developer guide
+  - title: Removal
+    url: /using-npm/removal
+    description: Cleaning the slate