@dotcom-tool-kit/package-json-hook 4.2.0 → 5.0.0-beta.1

package/.toolkitrc.yml

@@ -0,0 +1,7 @@
+installs:
+  PackageJson:
+    entryPoint: './lib/package-json-helper'
+    managesFiles:
+      - 'package.json'
+
+version: 2

package/lib/package-json-helper.d.ts

@@ -1,25 +1,27 @@
-import { Hook } from '@dotcom-tool-kit/types';
-interface PackageJson {
-    [field: string]: PackageJson | string;
+import type { z } from 'zod';
+import { Hook, HookInstallation } from '@dotcom-tool-kit/base';
+import type { Plugin } from '@dotcom-tool-kit/plugin';
+import { PackageJsonSchema } from '@dotcom-tool-kit/schemas/lib/hooks/package-json';
+import { Conflict } from '@dotcom-tool-kit/conflict';
+interface PackageJsonContents {
+    [field: string]: PackageJsonContents | string;
 }
 interface PackageJsonStateValue {
-    hooks: string[];
-    trailingString: string;
+    commands: string[];
+    trailingString?: string;
+    installedBy: PackageJson;
 }
 interface PackageJsonState {
-    [field: string]: PackageJsonState | PackageJsonStateValue;
+    [path: string]: PackageJsonStateValue;
 }
-export declare abstract class PackageJsonHelper extends Hook<PackageJsonState> {
+export default class PackageJson extends Hook<typeof PackageJsonSchema, PackageJsonState> {
     private _packageJson?;
-    abstract field: string | string[];
-    abstract key: string;
-    abstract hook: string;
-    trailingString?: string;
     installGroup: string;
     filepath: string;
-    getPackageJson(): Promise<PackageJson>;
-    private get hookPath();
-    check(): Promise<boolean>;
+    static mergeChildInstallations(plugin: Plugin, childInstallations: (HookInstallation<z.output<typeof PackageJsonSchema>> | Conflict<HookInstallation<z.output<typeof PackageJsonSchema>>>)[]): (HookInstallation<z.output<typeof PackageJsonSchema>> | Conflict<HookInstallation>)[];
+    static overrideChildInstallations(plugin: Plugin, parentInstallation: HookInstallation<z.output<typeof PackageJsonSchema>>, childInstallations: (HookInstallation<z.output<typeof PackageJsonSchema>> | Conflict<HookInstallation<z.output<typeof PackageJsonSchema>>>)[]): (HookInstallation<z.output<typeof PackageJsonSchema>> | Conflict<HookInstallation>)[];
+    getPackageJson(): Promise<PackageJsonContents>;
+    isInstalled(): Promise<boolean>;
     install(state?: PackageJsonState): Promise<PackageJsonState>;
     commitInstall(state: PackageJsonState): Promise<void>;
 }

package/lib/package-json-helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-json-helper.d.ts","sourceRoot":"","sources":["../src/package-json-helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAA;AAQ7C,UAAU,WAAW;IACnB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;CACtC;AAED,UAAU,qBAAqB;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,UAAU,gBAAgB;IACxB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,qBAAqB,CAAA;CAC1D;AAED,8BAAsB,iBAAkB,SAAQ,IAAI,CAAC,gBAAgB,CAAC;IACpE,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAIrB,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,YAAY,SAAiB;IAE7B,QAAQ,SAA8C;IAEhD,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAW5C,OAAO,KAAK,QAAQ,GAEnB;IAEK,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAKzB,OAAO,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAU5D,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAa5D"}
+{"version":3,"file":"package-json-helper.d.ts","sourceRoot":"","sources":["../src/package-json-helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AASrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iDAAiD,CAAA;AACnF,OAAO,EAAE,QAAQ,EAAc,MAAM,2BAA2B,CAAA;AAEhE,UAAU,mBAAmB;IAC3B,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,GAAG,MAAM,CAAA;CAC9C;AAED,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,WAAW,EAAE,WAAW,CAAA;CACzB;AAED,UAAU,gBAAgB;IACxB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAAA;CACtC;AAuED,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,IAAI,CAAC,OAAO,iBAAiB,EAAE,gBAAgB,CAAC;IACvF,OAAO,CAAC,YAAY,CAAC,CAAqB;IAE1C,YAAY,SAAiB;IAE7B,QAAQ,SAA8C;IAEtD,MAAM,CAAC,uBAAuB,CAC5B,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,CAChB,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC,GACpD,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CACjE,EAAE,GACF,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE;IAexF,MAAM,CAAC,0BAA0B,CAC/B,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC,EACxE,kBAAkB,EAAE,CAChB,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC,GACpD,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CACjE,EAAE,GACF,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE;IAsBlF,cAAc,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAW9C,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAsB/B,OAAO,CAAC,KAAK,GAAE,gBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgChE,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAe5D"}

package/lib/package-json-helper.js

@@ -1,20 +1,93 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PackageJsonHelper = void 0;
 const tslib_1 = require("tslib");
-const types_1 = require("@dotcom-tool-kit/types");
+const base_1 = require("@dotcom-tool-kit/base");
 const fs_1 = tslib_1.__importDefault(require("fs"));
 const get_1 = tslib_1.__importDefault(require("lodash/get"));
-const mapValues_1 = tslib_1.__importDefault(require("lodash/mapValues"));
-const merge_1 = tslib_1.__importDefault(require("lodash/merge"));
+const set_1 = tslib_1.__importDefault(require("lodash/set"));
+const partition_1 = tslib_1.__importDefault(require("lodash/partition"));
 const update_1 = tslib_1.__importDefault(require("lodash/update"));
+const merge_1 = tslib_1.__importDefault(require("lodash/merge"));
 const path_1 = tslib_1.__importDefault(require("path"));
-class PackageJsonHelper extends types_1.Hook {
+const conflict_1 = require("@dotcom-tool-kit/conflict");
+function installationsOverlap(installation, other) {
+    for (const [field, object] of Object.entries(installation.options)) {
+        for (const key of Object.keys(object)) {
+            if (field in other.options && key in other.options[field]) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function partitionInstallations(installation, mergeable, unmergeable) {
+    const [noLongerMergeable, stillMergeable] = (0, partition_1.default)(mergeable, (other) => installationsOverlap(installation, other));
+    const overlapsWithUnmergeable = unmergeable.some((other) => installationsOverlap(installation, other));
+    if (noLongerMergeable.length > 0 || overlapsWithUnmergeable) {
+        return [stillMergeable, [...unmergeable, ...noLongerMergeable, installation]];
+    }
+    return [[...stillMergeable, installation], unmergeable];
+}
+function mergeInstallationResults(plugin, mergeable, unmergeable) {
+    const results = [];
+    if (mergeable.length > 0) {
+        results.push({
+            plugin,
+            forHook: 'PackageJson',
+            hookConstructor: PackageJson,
+            options: (0, merge_1.default)({}, ...mergeable.map((installation) => installation.options))
+        });
+    }
+    if (unmergeable.length > 0) {
+        results.push({
+            plugin,
+            conflicting: unmergeable
+        });
+    }
+    return results;
+}
+// split the path on all unescaped full stops, then unescape all escaped full
+// stops. this will mean we can pass fields to lodash functions taking a path
+// even if the fields contain full stops.
+function splitAndUnescapePath(path) {
+    return path.split(/(?<!\\)\./).map((component) => component.replace('\\.', '.'));
+}
+class PackageJson extends base_1.Hook {
     constructor() {
         super(...arguments);
         this.installGroup = 'package-json';
         this.filepath = path_1.default.resolve(process.cwd(), 'package.json');
     }
+    static mergeChildInstallations(plugin, childInstallations) {
+        let mergeable = [];
+        let unmergeable = [];
+        for (const installation of childInstallations) {
+            if ((0, conflict_1.isConflict)(installation)) {
+                unmergeable.push(...installation.conflicting);
+            }
+            else {
+                ;
+                [mergeable, unmergeable] = partitionInstallations(installation, mergeable, unmergeable);
+            }
+        }
+        return mergeInstallationResults(plugin, mergeable, unmergeable);
+    }
+    static overrideChildInstallations(plugin, parentInstallation, childInstallations) {
+        const mergeable = [];
+        const unmergeable = [];
+        for (const installation of childInstallations) {
+            if ((0, conflict_1.isConflict)(installation)) {
+                const [canHandle, cannotHandle] = (0, partition_1.default)(installation.conflicting, (other) => installationsOverlap(parentInstallation, other));
+                mergeable.push(...canHandle);
+                unmergeable.push(...cannotHandle);
+            }
+            else {
+                mergeable.push(installation);
+            }
+        }
+        mergeable.push(parentInstallation);
+        return mergeInstallationResults(plugin, mergeable, unmergeable);
+    }
     async getPackageJson() {
         if (!this._packageJson) {
             const rawPackageJson = await fs_1.default.promises.readFile(this.filepath, 'utf8');
@@ -24,28 +97,57 @@ class PackageJsonHelper extends types_1.Hook {
         }
         return this._packageJson;
     }
-    get hookPath() {
-        return Array.isArray(this.field) ? [...this.field, this.key] : [this.field, this.key];
-    }
-    async check() {
+    async isInstalled() {
         const packageJson = await this.getPackageJson();
-        return (0, get_1.default)(packageJson, this.hookPath)?.includes(this.hook);
-    }
-    async install(state) {
-        state ??= {};
-        // prepend each hook to maintain the same order as previous implementations
-        (0, update_1.default)(state, this.hookPath, (hookState) => ({
-            hooks: [this.hook, ...(hookState?.hooks ?? [])],
-            trailingString: this.trailingString
-        }));
+        // this instance's `options` is a nested object of expected package.json field/command mappings, e.g.
+        // { "scripts": { "build": "build:local" } }. in the package.json, they'll have the same structure
+        // with a `dotcom-tool-kit` CLI prefix, e.g. { "scripts": { "build": "dotcom-tool-kit build:local" } }.
+        // loop through the nested options object, get the same nested key from package.json, and check that
+        // field exists, and its string includes the name of the command. if any command from our options is
+        // missing, the check should fail.
+        for (const [field, object] of Object.entries(this.options)) {
+            for (const [key, command] of Object.entries(object)) {
+                const currentPackageJsonField = (0, get_1.default)(packageJson, [...splitAndUnescapePath(field), key]);
+                if (!currentPackageJsonField || !currentPackageJsonField.includes(command)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    async install(state = {}) {
+        for (const [field, object] of Object.entries(this.options)) {
+            for (const [key, entry] of Object.entries(object)) {
+                let trailingString;
+                let commands;
+                if (Array.isArray(entry)) {
+                    commands = entry;
+                }
+                else if (typeof entry === 'string') {
+                    commands = [entry];
+                }
+                else {
+                    commands = Array.isArray(entry.commands) ? entry.commands : [entry.commands];
+                    trailingString = entry.trailingString;
+                }
+                (0, update_1.default)(state, 
+                // full stops in the key shouldn't be treated as path separators
+                [field + '.' + key.replace('.', '\\.')], (hookState) => ({
+                    // prepend each command to maintain the same order as previous implementations
+                    commands: [...commands, ...(hookState?.commands ?? [])],
+                    installedBy: this,
+                    trailingString: trailingString
+                }));
+            }
+        }
         return state;
     }
     async commitInstall(state) {
-        const reduceHooks = (state) => (0, mapValues_1.default)(state, (field) => Array.isArray(field?.hooks)
-            ? `dotcom-tool-kit ${field.hooks.join(' ')}${field.trailingString ? ' ' + field.trailingString : ''}`
-            : reduceHooks(field));
-        const newPackageJson = (0, merge_1.default)(await this.getPackageJson(), reduceHooks(state));
-        await fs_1.default.promises.writeFile(this.filepath, JSON.stringify(newPackageJson, null, 2) + '\n');
+        const packageJson = await this.getPackageJson();
+        for (const [path, installation] of Object.entries(state)) {
+            (0, set_1.default)(packageJson, splitAndUnescapePath(path), `dotcom-tool-kit ${installation.commands.join(' ')}${installation.trailingString ? ' ' + installation.trailingString : ''}`);
+        }
+        await fs_1.default.promises.writeFile(this.filepath, JSON.stringify(packageJson, null, 2) + '\n');
     }
 }
-exports.PackageJsonHelper = PackageJsonHelper;
+exports.default = PackageJson;

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@dotcom-tool-kit/package-json-hook",
-  "version": "4.2.0",
+  "version": "5.0.0-beta.1",
   "description": "",
   "main": "lib",
   "scripts": {
-    "test": "cd ../../ ; npx jest --silent --projects lib/package-json-hook"
+    "test": "cd ../../ ; npx jest --silent --projects plugins/package-json-hook"
   },
   "keywords": [],
   "author": "FT.com Platforms Team <platforms-team.customer-products@ft.com>",
   "license": "ISC",
   "dependencies": {
+    "@dotcom-tool-kit/base": "4.0.0-beta.0",
+    "@dotcom-tool-kit/conflict": "2.0.0-beta.0",
+    "@dotcom-tool-kit/plugin": "2.0.0-beta.0",
     "@financial-times/package-json": "^3.0.0",
     "lodash": "^4.17.21",
     "tslib": "^2.3.1"
@@ -17,14 +20,19 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/financial-times/dotcom-tool-kit.git",
-    "directory": "lib/package-json-hook"
+    "directory": "plugins/package-json-hook"
   },
   "bugs": "https://github.com/financial-times/dotcom-tool-kit/issues",
-  "homepage": "https://github.com/financial-times/dotcom-tool-kit/tree/main/lib/package-json-hook",
+  "homepage": "https://github.com/financial-times/dotcom-tool-kit/tree/main/plugins/package-json-hook",
+  "peerDependencies": {
+    "zod": "^3.22.4"
+  },
   "devDependencies": {
+    "@dotcom-tool-kit/schemas": "2.0.0-beta.0",
     "@jest/globals": "^27.4.6",
     "@types/lodash": "^4.14.185",
-    "winston": "^3.5.1"
+    "winston": "^3.5.1",
+    "zod": "^3.22.4"
   },
   "files": [
     "/lib",
@@ -34,7 +42,7 @@
     "extends": "../../package.json"
   },
   "engines": {
-    "node": "16.x || 18.x || 20.x",
+    "node": "18.x || 20.x",
     "npm": "7.x || 8.x || 9.x || 10.x"
   }
 }

package/readme.md

@@ -0,0 +1,70 @@
+# @dotcom-tool-kit/package-json-hook
+
+This plugin manages Tool Kit commands that are run from npm scripts, via a Tool Kit [`Hook`](#hooks) that automatically manages `package.json`.
+
+Although you can write npm scripts yourself in `package.json`, this plugin allows other Tool Kit plugins to define them in a repeatable, modular way. Adding custom scripts via configuring this plugin in your `.toolkitrc.yml` means that if a new use case emerges, it's much easier to abstract it into a plugin that can be shared with other Tool Kit users.
+
+## Installation
+
+Most repositories won't need to use this plugin directly. It's installed of a dependency of plugins like [`npm`](../npm) which configure it with standard use cases.
+
+
+Install `@dotcom-tool-kit/package-json-hook` as a `devDependency` in your app:
+
+```sh
+npm install --save-dev @dotcom-tool-kit/package-json-hook
+```
+
+Add the plugin to your [Tool Kit configuration](https://github.com/financial-times/dotcom-tool-kit/blob/main/readme.md#configuration):
+
+```yaml
+plugins:
+	- '@dotcom-tool-kit/package-json-hook'
+```
+
+And install this plugin's hooks:
+
+```sh
+npx dotcom-tool-kit --install
+```
+
+<!-- begin autogenerated docs -->
+## Hooks
+
+### `PackageJson`
+
+This hook accepts a nested object with a structure that matches the generated output in `package.json`. The values are used as Tool Kit command names to run. You can provide a single command or an array; multiple commands are concatenated in order.
+
+For more complex use cases, you can provide an object instead of a command. The object must contain keys `commands` (as above), and `trailingString` (which will be appended to the resulting `dotcom-tool-kit` CLI invocation). This is useful for tasks that accept a list of files after a trailing `--`.
+
+Options provided in your repository's `.toolkitrc.yml` for this hook are merged with any Tool Kit plugin that also provides options for the hook.
+
+For example, configuring this hook with the following options:
+
+~~~yml
+options:
+  hooks:
+    - PackageJson:
+        scripts:
+          start: 'run:local'
+          customScript:
+            commands:
+              - custom:one
+              - custom:two
+            trailingString: '--'
+~~~
+
+will result in the following output in `package.json`:
+
+~~~json
+{
+  "scripts": {
+    "start": "dotcom-tool-kit run:local",
+    "customScript": "dotcom-tool-kit custom:one custom:two --"
+  }
+}
+~~~
+
+<!-- hide autogenerated schema docs -->
+
+<!-- end autogenerated docs -->

package/lib/index.d.ts

@@ -1,3 +0,0 @@
-export { PackageJsonScriptHook, PackageJsonScriptHook as PackageJsonHook } from './script-hook';
-export { PackageJsonHelper } from './package-json-helper';
-//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,IAAI,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/lib/index.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PackageJsonHelper = exports.PackageJsonHook = exports.PackageJsonScriptHook = void 0;
-var script_hook_1 = require("./script-hook");
-Object.defineProperty(exports, "PackageJsonScriptHook", { enumerable: true, get: function () { return script_hook_1.PackageJsonScriptHook; } });
-Object.defineProperty(exports, "PackageJsonHook", { enumerable: true, get: function () { return script_hook_1.PackageJsonScriptHook; } });
-var package_json_helper_1 = require("./package-json-helper");
-Object.defineProperty(exports, "PackageJsonHelper", { enumerable: true, get: function () { return package_json_helper_1.PackageJsonHelper; } });

package/lib/script-hook.d.ts

@@ -1,5 +0,0 @@
-import { PackageJsonHelper } from './package-json-helper';
-export declare abstract class PackageJsonScriptHook extends PackageJsonHelper {
-    field: string;
-}
-//# sourceMappingURL=script-hook.d.ts.map

package/lib/script-hook.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"script-hook.d.ts","sourceRoot":"","sources":["../src/script-hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAEzD,8BAAsB,qBAAsB,SAAQ,iBAAiB;IACnE,KAAK,SAAY;CAClB"}

package/lib/script-hook.js

@@ -1,11 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PackageJsonScriptHook = void 0;
-const package_json_helper_1 = require("./package-json-helper");
-class PackageJsonScriptHook extends package_json_helper_1.PackageJsonHelper {
-    constructor() {
-        super(...arguments);
-        this.field = 'scripts';
-    }
-}
-exports.PackageJsonScriptHook = PackageJsonScriptHook;