@yarnpkg/plugin-essentials 3.2.0-rc.2 → 3.2.0-rc.6

package/lib/commands/explain.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '@yarnpkg/cli';
+import { Configuration } from '@yarnpkg/core';
+export declare function getErrorCodeDetails(configuration: Configuration): Promise<Map<string, string>>;
+export default class ExplainCommand extends BaseCommand {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    code: string | undefined;
+    json: boolean;
+    execute(): Promise<void>;
+}

package/lib/commands/explain.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getErrorCodeDetails = void 0;
+const tslib_1 = require("tslib");
+const cli_1 = require("@yarnpkg/cli");
+const core_1 = require("@yarnpkg/core");
+const clipanion_1 = require("clipanion");
+const t = (0, tslib_1.__importStar)(require("typanion"));
+const version_1 = require("./set/version");
+function getCodeName(code) {
+    return core_1.MessageName[(0, core_1.parseMessageName)(code)];
+}
+const ERROR_CODE_DOC_REGEXP = /## (?<code>YN[0-9]{4}) - `(?<name>[A-Z_]+)`\n\n(?<details>(?:.(?!##))+)/gs;
+async function getErrorCodeDetails(configuration) {
+    const version = core_1.miscUtils.isTaggedYarnVersion(core_1.YarnVersion)
+        ? core_1.YarnVersion
+        : await (0, version_1.resolveTag)(configuration, `canary`);
+    const errorCodesUrl = `https://repo.yarnpkg.com/${version}/packages/gatsby/content/advanced/error-codes.md`;
+    const raw = await core_1.httpUtils.get(errorCodesUrl, { configuration });
+    return new Map(Array.from(raw.toString().matchAll(ERROR_CODE_DOC_REGEXP), ({ groups }) => {
+        if (!groups)
+            throw new Error(`Assertion failed: Expected the match to have been successful`);
+        const expectedName = getCodeName(groups.code);
+        if (groups.name !== expectedName)
+            throw new Error(`Assertion failed: Invalid error code data: Expected "${groups.name}" to be named "${expectedName}"`);
+        return [groups.code, groups.details];
+    }));
+}
+exports.getErrorCodeDetails = getErrorCodeDetails;
+// eslint-disable-next-line arca/no-default-export
+class ExplainCommand extends cli_1.BaseCommand {
+    constructor() {
+        super(...arguments);
+        this.code = clipanion_1.Option.String({
+            required: false,
+            validator: t.applyCascade(t.isString(), [
+                t.matchesRegExp(/^YN[0-9]{4}$/),
+            ]),
+        });
+        this.json = clipanion_1.Option.Boolean(`--json`, false, {
+            description: `Format the output as an NDJSON stream`,
+        });
+    }
+    async execute() {
+        const configuration = await core_1.Configuration.find(this.context.cwd, this.context.plugins);
+        if (typeof this.code !== `undefined`) {
+            const name = getCodeName(this.code);
+            const prettyName = core_1.formatUtils.pretty(configuration, name, core_1.formatUtils.Type.CODE);
+            const header = this.cli.format().header(`${this.code} - ${prettyName}`);
+            const errorCodeDetails = await getErrorCodeDetails(configuration);
+            const details = errorCodeDetails.get(this.code);
+            const content = typeof details !== `undefined`
+                ? core_1.formatUtils.jsonOrPretty(this.json, configuration, core_1.formatUtils.tuple(core_1.formatUtils.Type.MARKDOWN, {
+                    text: details,
+                    format: this.cli.format(),
+                    paragraphs: true,
+                }))
+                : `This error code does not have a description.\n\nYou can help us by editing this page on GitHub 🙂:\n${core_1.formatUtils.jsonOrPretty(this.json, configuration, core_1.formatUtils.tuple(core_1.formatUtils.Type.URL, `https://github.com/yarnpkg/berry/blob/master/packages/gatsby/content/advanced/error-codes.md`))}\n`;
+            if (this.json) {
+                this.context.stdout.write(`${JSON.stringify({ code: this.code, name, details: content })}\n`);
+            }
+            else {
+                this.context.stdout.write(`${header}\n\n${content}\n`);
+            }
+        }
+        else {
+            const tree = {
+                children: core_1.miscUtils.mapAndFilter(Object.entries(core_1.MessageName), ([key, value]) => {
+                    if (Number.isNaN(Number(key)))
+                        return core_1.miscUtils.mapAndFilter.skip;
+                    return {
+                        label: (0, core_1.stringifyMessageName)(Number(key)),
+                        value: core_1.formatUtils.tuple(core_1.formatUtils.Type.CODE, value),
+                    };
+                }),
+            };
+            core_1.treeUtils.emitTree(tree, { configuration, stdout: this.context.stdout, json: this.json });
+        }
+    }
+}
+exports.default = ExplainCommand;
+ExplainCommand.paths = [
+    [`explain`],
+];
+ExplainCommand.usage = clipanion_1.Command.Usage({
+    description: `explain an error code`,
+    details: `
+      When the code argument is specified, this command prints its name and its details.
+
+      When used without arguments, this command lists all error codes and their names.
+    `,
+    examples: [[
+            `Explain an error code`,
+            `$0 explain YN0006`,
+        ], [
+            `List all error codes`,
+            `$0 explain`,
+        ]],
+});

package/lib/commands/set/version.js

@@ -165,8 +165,10 @@ async function setVersion(configuration, bundleVersion, bundleBuffer, { report }
             yarnPath: projectPath,
         });
         const manifest = (await core_1.Manifest.tryFind(projectCwd)) || new core_1.Manifest();
-        if (bundleVersion && core_2.miscUtils.isTaggedYarnVersion(bundleVersion))
-            manifest.packageManager = `yarn@${bundleVersion}`;
+        manifest.packageManager = `yarn@${bundleVersion && core_2.miscUtils.isTaggedYarnVersion(bundleVersion)
+            ? bundleVersion
+            // If the version isn't tagged, we use the latest stable version as the wrapper
+            : await resolveTag(configuration, `stable`)}`;
         const data = {};
         manifest.exportTo(data);
         const path = fslib_1.ppath.join(projectCwd, core_1.Manifest.fileName);

package/lib/index.d.ts

@@ -4,9 +4,36 @@ import * as dedupeUtils from './dedupeUtils';
 import * as suggestUtils from './suggestUtils';
 export { dedupeUtils, suggestUtils, };
 export interface Hooks {
+    /**
+     * Called when a new dependency is added to a workspace. Note that this hook
+     * is only called by the CLI commands like `yarn add` - manually adding the
+     * dependencies into the manifest and running `yarn install` won't trigger
+     * it.
+     */
     afterWorkspaceDependencyAddition?: (workspace: Workspace, target: suggestUtils.Target, descriptor: Descriptor, strategies: Array<suggestUtils.Strategy>) => Promise<void>;
+    /**
+     * Called when a dependency range is replaced inside a workspace. Note that
+     * this hook is only called by the CLI commands like `yarn add` - manually
+     * updating the dependencies from the manifest and running `yarn install`
+     * won't trigger it.
+     */
     afterWorkspaceDependencyReplacement?: (workspace: Workspace, target: suggestUtils.Target, fromDescriptor: Descriptor, toDescriptor: Descriptor) => Promise<void>;
+    /**
+     * Called when a dependency range is removed from a workspace. Note that
+     * this hook is only called by the CLI commands like `yarn remove` - manually
+     * removing the dependencies from the manifest and running `yarn install`
+     * won't trigger it.
+     */
     afterWorkspaceDependencyRemoval?: (workspace: Workspace, target: suggestUtils.Target, descriptor: Descriptor) => Promise<void>;
+    /**
+     * Called by `yarn info`. The `extra` field is the set of parameters passed
+     * to the `-X,--extra` flag. Calling `registerData` will add a new set of
+     * data that will be added to the package information.
+     *
+     * For instance, an "audit" plugin could check in `extra` whether the user
+     * requested audit information (via `-X audit`), and call `registerData`
+     * with those information (retrieved dynamically) if they did.
+     */
     fetchPackageInfo?: (pkg: Package, extra: Set<string>, registerData: (namespace: string, data: Array<formatUtils.Tuple> | {
         [key: string]: formatUtils.Tuple | undefined;
     }) => void) => Promise<void>;

package/lib/index.js

@@ -18,6 +18,7 @@ const run_1 = (0, tslib_1.__importDefault)(require("./commands/entries/run"));
 const version_1 = (0, tslib_1.__importDefault)(require("./commands/entries/version"));
 const exec_1 = (0, tslib_1.__importDefault)(require("./commands/exec"));
 const peerRequirements_1 = (0, tslib_1.__importDefault)(require("./commands/explain/peerRequirements"));
+const explain_1 = (0, tslib_1.__importDefault)(require("./commands/explain"));
 const info_1 = (0, tslib_1.__importDefault)(require("./commands/info"));
 const install_1 = (0, tslib_1.__importDefault)(require("./commands/install"));
 const link_1 = (0, tslib_1.__importDefault)(require("./commands/link"));
@@ -76,6 +77,7 @@ const plugin = {
         dedupe_1.default,
         exec_1.default,
         peerRequirements_1.default,
+        explain_1.default,
         info_1.default,
         install_1.default,
         link_1.default,

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@yarnpkg/plugin-essentials",
-  "version": "3.2.0-rc.2",
+  "version": "3.2.0-rc.6",
   "license": "BSD-2-Clause",
   "main": "./lib/index.js",
   "dependencies": {
-    "@yarnpkg/fslib": "^2.6.0",
+    "@yarnpkg/fslib": "^2.6.1-rc.3",
     "@yarnpkg/json-proxy": "^2.1.1",
-    "@yarnpkg/parsers": "^2.5.0-rc.2",
+    "@yarnpkg/parsers": "^2.5.0-rc.6",
     "ci-info": "^3.2.0",
-    "clipanion": "^3.0.1",
+    "clipanion": "^3.2.0-rc.4",
     "enquirer": "^2.3.6",
     "lodash": "^4.17.15",
     "micromatch": "^4.0.2",
@@ -17,18 +17,18 @@
     "typanion": "^3.3.0"
   },
   "peerDependencies": {
-    "@yarnpkg/cli": "^3.2.0-rc.4",
-    "@yarnpkg/core": "^3.2.0-rc.4",
-    "@yarnpkg/plugin-git": "^2.6.0-rc.4"
+    "@yarnpkg/cli": "^3.2.0-rc.8",
+    "@yarnpkg/core": "^3.2.0-rc.8",
+    "@yarnpkg/plugin-git": "^2.6.0-rc.8"
   },
   "devDependencies": {
     "@types/lodash": "^4.14.136",
     "@types/micromatch": "^4.0.1",
     "@types/semver": "^7.1.0",
     "@types/treeify": "^1.0.0",
-    "@yarnpkg/cli": "^3.2.0-rc.4",
-    "@yarnpkg/core": "^3.2.0-rc.4",
-    "@yarnpkg/plugin-git": "^2.6.0-rc.4"
+    "@yarnpkg/cli": "^3.2.0-rc.8",
+    "@yarnpkg/core": "^3.2.0-rc.8",
+    "@yarnpkg/plugin-git": "^2.6.0-rc.8"
   },
   "repository": {
     "type": "git",