@hanseltime/template-repo-sync 2.2.1 → 2.4.0-alpha.0

package/docs/merge-plugins/CURRENT_PLUGINS.md

@@ -1,168 +0,0 @@
-# Current Merge Plugins
-
-This document lists all merge plugins that are provided as defaults for certain file extensions.
-These should be found in the [plugins folder](src/plugins)
-
-- [Current Merge Plugins](#current-merge-plugins)
-  - [Json Merge Plugin](#json-merge-plugin)
-  - [Configuration Options:](#configuration-options)
-    - [Simple merge spec](#simple-merge-spec)
-    - [JsonPath config](#jsonpath-config)
-      - [Example](#example)
-    - [About Comments](#about-comments)
-
-<!-- Created with Markdown All In One VsCode Extension -->
-
-## Json Merge Plugin
-
-The json merge plugin allows you to configure jsonpath based merges on any .json file.
-
-Plugin Field Name: `_json`
-
-## Configuration Options:
-
-### Simple merge spec
-
-At it's simplest, you can take advantage of lodash merge behavior by just specifying one of:
-
-- overwrite - the template completely overwrites the file
-- merge-template - keys are merged together with the template overwriting any matching keys on local file
-- merge-current - keys are merged together with the local file keeping any keys that match in the template
-
-Example config:
-
-```json
-{
-  "merge": {
-    ".json": {
-      "rules": [
-        {
-          "glob": "metadata.json",
-          "options": "merge-template"
-        },
-        {
-          "glob": "template-lock.json",
-          "options": "overwrite"
-        },
-        {
-          "glob": "package.json",
-          "options": "merge-current"
-        }
-      ]
-    }
-  }
-}
-```
-
-### JsonPath config
-
-If you would like further control over what merges within a .json file, you can actually specify, via way of jsonpath operators,
-the level of merge per field.
-
-A few rules:
-
-- Once you have provided jsonpath options, only the json path options (or new fields if the option is enabled) will be merged
-- jsonpaths are run from first to last. This means you can layer merges.
-
-```typescript
-interface Options {
-  /**
-   * If set to true, this means we won't add new properties from the template
-   */
-  ignoreNewProperties?: boolean;
-  /**
-   * If set to true, overwrite will apply undefined values as deleted for the jsonpaths
-   * or for values that are supposed to be merged on top of other values
-   */
-  missingIsDelete?: boolean;
-  /**
-   * Note, if multiple json paths match a rule, we pick the first one in the list that matches
-   */
-  paths: /**
-   * We only override jsonpaths.  Anything not specified is kept the same.
-   */
-  [jsonPath: `$.${string}`, options: BaseJsonMergeOptions][];
-}
-```
-
-#### Example
-
-```json
-{
-  "merge": {
-    ".json": {
-      "rules": [
-        {
-          "glob": "metadata.json",
-          "options": {
-            "ignoreNewProperties": false,
-            "missingIsDelete:": true,
-            "paths": [
-              ["$.path", "template-merge"] // if we delete path in the template, it will delete the path
-            ]
-          }
-        },
-        {
-          "glob": "template-lock.json",
-          "options": "overwrite"
-        },
-        {
-          "glob": "package.json",
-          "options": {
-            "ignoreNewProperties": false,
-            "paths": [
-              ["$.scripts.*", "template-merge"],
-              ["$.scripts.specific-script", "template-currrent"] // We end up keeping the current template
-            ]
-          }
-        }
-      ]
-    }
-  }
-}
-```
-
-### About Comments
-
-There are numerous json files that support comments now; tsconfig.json is a prime example of this. In order to support this,
-this library makes use of comment-json for parsing and stringifying. This means that, minimally, you will not run into errors
-when merging commented json files (and that you can comment on your templatesync config files).
-
-One thing to note however, is that only include comments from the template if they are inside of an object that is being merged.
-This is because this plugin has not yet defined a good configuration for merging comments. If you run into a pertinent need for this,
-please feel free to open an issue and potentially contribute a fix in a PR.
-
-Example of comment merging:
-
-```json
-// In template
-
-{
-  // I have a comment here
-  "newField": 44,
-  "overridingField": {
-    // Comment in here
-    "value": "v",
-  }
-}
-
-// In the extending repo
-{
-  // My custom comment
-  "newField": 88,
-  "overridingField": 66
-}
-
-// After merging with template-merge
-{
-  // My custom comment
-  "newField": 44,
-  "overridingField": {
-    // Comment in here
-    "value": "v",
-  }
-}
-```
-
-From the above example, you can see that we specifically keep as many of the comments as possible from the extending repo
-and only the comment that was fully nested inside new value that we were adding was kept.

package/docs/merge-plugins/PLUGIN_DEVELOPMENT.md

@@ -1,122 +0,0 @@
-# Plugin Development
-
-- [Plugin Development](#plugin-development)
-  - [Example: hello \<world\>](#example-hello-world)
-    - [Example one: local file](#example-one-local-file)
-    - [Example two: npm package](#example-two-npm-package)
-
-The templatesync.json and templatesync.local.config files make use of a `"merge"` property where you can
-customize the baseline behavior of ignore or overwrite from template.
-
-This library provides a set of typescript types for you to create additional plugins.
-
-At the core of it, you need to have a file or npm package that exposes the interface:
-
-```typescript
-export interface MergePlugin<PluginOptions> {
-  /**
-   * This method will be called when a file from the template and it's analog in the downstream repo
-   * have some differences.  The plugin must perform the merge and return the appropriate file contents
-   * as a string
-   *
-   * TODO: we may create a V2 plugin that could deal with large files and not pass around strings in memory,
-   * but for now, this is the current implementation
-   *
-   * @param current - The downstream repo's current file contents
-   * @param fromTemplateRepo - the current
-   * @param context - an object defining the context around the file and the specific options
-   */
-  merge(
-    current: string,
-    fromTemplateRepo: string,
-    context: MergeContext<PluginOptions>,
-  ): Promise<string>;
-  /**
-   * Given an options object for the merge, this validates the options object and returns error messages if there is anything wrong.
-   * @param options any json value that the user provided - must be validated against the expected options
-   */
-  validate(options: unknown): string[] | undefined;
-}
-```
-
-## Example: hello \<world>
-
-So let's say that we want to have a plugin that will take every file assigned to it, and just write hello {world} instead.
-(Not much of a merge, but so it goes)
-
-We will define and export an options object, validate function, and merge function
-
-```typescript
-// src/hello-plugin.ts
-import { MergePlugin, MergeContext } from '@hanseltime/template-repo-sync'
-
-export interface HelloOptions: {
-  /** the name of the world we're greeting */
-  world: string
-}
-
-export const validate: MergePlugin<HelloOptions>['validate'] = (options: unknown) => {
-  const errors: string[] = [];
-  // In our case, we have decided you HAVE to use an object
-  if (typeof options !== 'object') {
-    errors.push('must provide an object');
-    return errors;
-  }
-
-  // make sure there aren't extra keys
-  const { world, ...rest } = options;
-  const unknownKeys = Object.keys(rest);
-  if (unknownKeys.length > 0 ) {
-    errors.push(`Unexpected options keys: ${unknownKeys.join(' ')}`);
-  }
-
-  if (!world) {
-    errors.push(`Must provide a valid world value`);
-  }
-
-  return errors
-}
-
-export const merge:  MergePlugin<HelloOptions>['merge'] = async (current, fromTemplateRepo, options: HelloOptions) => {
-  // Note, we don't use the current with this simple plugin, but we would use the first 2 args normally
-  return `Hello ${options.world}`
-}
-
-```
-
-With all of that set up, as long as we have the package available to the pacakge manager running our script, we can use it:
-
-### Example one: local file
-
-```json
-{
-  "merge": [
-    {
-      "glob": "**/*.txt",
-      "plugin": "dist/hello-plugin.js",
-      "options": {
-        "world": "chad"
-      }
-    }
-  ]
-}
-```
-
-### Example two: npm package
-
-Let's assume that you published this as an npm package to @myscope/hello-merge. Once you have install the pacakge to the project, you can
-simply reference the package (assuming that it exposes the required functions as it's index file).
-
-```json
-{
-  "merge": [
-    {
-      "glob": "**/*.txt",
-      "plugin": "@myscope/hello-merge",
-      "options": {
-        "world": "chad"
-      }
-    }
-  ]
-}
-```

package/docs/merge-plugins/README.md

@@ -1,75 +0,0 @@
-# Merge Plugins
-
-The templatesync.json and templatesync.local.config files make use of a `"merge"` property where you can
-customize the baseline behavior of just ignoring or overwriting from the template.
-
-# Example Use Case
-
-One example of this behavior is around an npm package.json. If you were making a template for a particular
-set of boilerplate for an npm package, you would probably provide an example package.json like:
-
-```json
-{
-  "name": "<fill in your package name",
-  "description": "<fill in your package description",
-  "license": "MIT",
-  "scripts": {
-    "build": "tsc",
-    "publish": "our-artifact-script"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "our-artifact-package": "^1.0.0"
-  }
-}
-```
-
-In this scenario, we expect the template user to declare their own `name` and `description`, and add their own
-`scripts` and `devDependencies`. However, we are hoping to make sure that the publish method and and its
-our-artifact-package are kept up-to-date on syncs. Because of this, we would make use of the built-in json merge
-plugin `_json` that is provided with this library:
-
-```json
-{
-  "merge": [
-    {
-      "glob": "package.json",
-      "plugin": "_json",
-      "options": {
-        "paths": [
-          ["$.scripts.publish", "merge-template"], // Any changes to publish are so critical that we want them to sync
-          ["$.devDependencies", "merge-template"] // Always ensure dev dependency versions for our scripts are updated
-        ]
-      }
-    }
-  ]
-}
-```
-
-As a repo maintainer, we can be sure that when people sync from our repo in its current state, the publish script
-and devDependency should be synced from package.json, without anything else!
-
-## What if the repo extender is annoyed?
-
-If the repo extender already made the decision to update the publish method for a good reason, they may find it
-tedious to constantly get their publish script overwritten and then have to undo it. Due to the local
-config file, they can specify their own merge configuration for the package.json.
-
-```json
-{
-  "merge": [
-    {
-      "glob": "package.json",
-      "plugin": "_json",
-      "paths": [
-        ["$.devDependencies", "merge-template"] // Always ensure dev dependency versions for our scripts are updated
-      ]
-    }
-  ]
-}
-```
-
-This configuration will now override the template repo's merge and only allow devDependencies to be updated. We report
-this override as part of the output of the sync call, and for things like our
-[github action](https://github.com/HanseltimeIndustries/template-repo-sync-action), we format that output into the PR
-that is opened up when performing a sync.

package/jest.config.js

@@ -1,19 +0,0 @@
-module.exports = {
-  preset: "ts-jest",
-  testEnvironment: "node",
-  roots: ["<rootDir>/src"],
-  transform: {
-    "\\.tsx?$": "ts-jest",
-    "\\.jsx?$": "babel-jest",
-  },
-  collectCoverage: true,
-  collectCoverageFrom: ["./src/**"],
-  coverageThreshold: {
-    global: {
-      branches: 77,
-      functions: 80,
-      // Lines can get skewed by bucket files
-      statements: 80,
-    },
-  },
-};

package/lib/cjs/checkout-drivers/git-checkout.js

@@ -1,29 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.gitCheckout = void 0;
-const child_process_1 = require("child_process");
-async function gitCheckout(options) {
-    const { branch, remoteName, tmpDir } = options;
-    const remoteInfo = (0, child_process_1.execSync)(`git remote show ${remoteName}`, {
-        cwd: tmpDir,
-        env: process.env,
-    }).toString();
-    const defaultMatch = /HEAD branch:\s*([a-zA-Z0-9_-]+)/.exec(remoteInfo);
-    if (!defaultMatch || !defaultMatch[1]) {
-        throw new Error(`Could not determine default branch of cloned repo.\nAttempted to find in remote info:\n${remoteInfo} `);
-    }
-    const defaultBranch = defaultMatch[1];
-    // Skip this if the default branch is already pulled
-    if (defaultBranch !== branch) {
-        (0, child_process_1.execSync)(`git fetch ${remoteName} ${branch}`, {
-            cwd: tmpDir,
-            env: process.env,
-        });
-        (0, child_process_1.execSync)(`git checkout -b ${branch} --track ${remoteName}/${branch}`, {
-            cwd: tmpDir,
-            env: process.env,
-        });
-    }
-    return true;
-}
-exports.gitCheckout = gitCheckout;

package/lib/cjs/checkout-drivers/index.js

@@ -1,18 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./git-checkout"), exports);
-__exportStar(require("./types"), exports);

package/lib/cjs/checkout-drivers/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/clone-drivers/git-clone.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.gitClone = void 0;
-const child_process_1 = require("child_process");
-const path_1 = require("path");
-const CLONE_DIR = "cloned_repo";
-async function gitClone(tmpDir, repoUrl) {
-    (0, child_process_1.execSync)(`git clone ${repoUrl} ${CLONE_DIR}`, {
-        cwd: tmpDir,
-        env: process.env,
-    });
-    return {
-        dir: (0, path_1.resolve)(tmpDir, CLONE_DIR),
-        remoteName: "origin",
-    };
-}
-exports.gitClone = gitClone;

package/lib/cjs/clone-drivers/index.js

@@ -1,18 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./types"), exports);
-__exportStar(require("./git-clone"), exports);

package/lib/cjs/clone-drivers/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/diff-drivers/git-diff.js

@@ -1,41 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.gitDiff = void 0;
-const child_process_1 = require("child_process");
-/**
- * For a given directory with a git configuration, this will return the modified, added, and
- * deleted files since the last afterRef
- * @param gitDir The git directory folder
- * @param afterRef The git ref to look for diffs after
- * @returns
- */
-async function gitDiff(gitDir, afterRef) {
-    const baseCommand = `git diff ${afterRef}.. --no-renames --name-only`;
-    const modifiedFiles = (0, child_process_1.execSync)(`${baseCommand} --diff-filter=M`, {
-        cwd: gitDir,
-    })
-        .toString()
-        .trim()
-        .split("\n")
-        .filter((s) => s !== "");
-    const addedFiles = (0, child_process_1.execSync)(`${baseCommand} --diff-filter=A`, {
-        cwd: gitDir,
-    })
-        .toString()
-        .trim()
-        .split("\n")
-        .filter((s) => s !== "");
-    const deletedFiles = (0, child_process_1.execSync)(`${baseCommand} --diff-filter=D`, {
-        cwd: gitDir,
-    })
-        .toString()
-        .trim()
-        .split("\n")
-        .filter((s) => s !== "");
-    return {
-        modified: modifiedFiles,
-        added: addedFiles,
-        deleted: deletedFiles,
-    };
-}
-exports.gitDiff = gitDiff;

package/lib/cjs/diff-drivers/index.js

@@ -1,18 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./types"), exports);
-__exportStar(require("./git-diff"), exports);

package/lib/cjs/diff-drivers/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/formatting/index.js

@@ -1,18 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./sync-results-to-md"), exports);
-__exportStar(require("./infer-json-indent"), exports);

package/lib/cjs/formatting/infer-json-indent.js

@@ -1,18 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.inferJSONIndent = void 0;
-const spacingRegex = /[{[]\n?(?<spacing>\s+)["tf\d]/;
-function inferJSONIndent(rawJSON) {
-    const match = spacingRegex.exec(rawJSON);
-    if (!match?.groups?.spacing) {
-        // eslint-disable-next-line no-console
-        console.warn(`Could not find json indentation for json string: ${rawJSON.slice(40)} ... \nDefaulting to 4 spaces`);
-        // Four spaces
-        return "    ";
-    }
-    const spacing = match.groups.spacing;
-    // Handle the case where there were multiple newlines before a value
-    const lastNewLine = spacing.lastIndexOf("\n");
-    return match?.groups.spacing.slice(lastNewLine >= 0 ? lastNewLine + 1 : 0);
-}
-exports.inferJSONIndent = inferJSONIndent;

package/lib/cjs/formatting/sync-results-to-md.d.ts

@@ -1,2 +0,0 @@
-import { TemplateSyncReturn } from "../template-sync";
-export declare function syncResultsToMd(result: TemplateSyncReturn): string;

package/lib/cjs/formatting/sync-results-to-md.js

@@ -1,57 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.syncResultsToMd = void 0;
-const template_sync_1 = require("../template-sync");
-function syncResultsToMd(result) {
-    return `# ${template_sync_1.TEMPLATE_SYNC_LOCAL_CONFIG} 
-
-## Stopped the following files from syncing:
-
-${result.localSkipFiles.reduce((s, file) => {
-        return `${s}* ${file}\n`;
-    }, "")}
-
-## Changed the following files from what they would have synced:
-
-${Object.keys(result.localFileChanges).reduce((s, file) => {
-        return `${s}${file}
-\`\`\`diff
-${result.localFileChanges[file].reduce((diffS, change) => {
-            return `${diffS}\n${makeChangeIntoDiffLines(change)}`;
-        }, "")}
-\`\`\``;
-    }, "")}
-
-## Files Modified (${result.modifiedFiles.total})
-
-Added:
-${result.modifiedFiles.added.reduce((s, f) => {
-        return `${s}\n- ${f}`;
-    }, "")}
-
-Modified:
-${result.modifiedFiles.modified.reduce((s, f) => {
-        return `${s}\n- ${f}`;
-    }, "")}
-
-Deleted:
-${result.modifiedFiles.deleted.reduce((s, f) => {
-        return `${s}\n- ${f}`;
-    }, "")}
-`;
-}
-exports.syncResultsToMd = syncResultsToMd;
-function makeChangeIntoDiffLines(change, nonchangeMax = 3) {
-    const operator = change.added ? "+" : change.removed ? "-" : "";
-    if (!operator &&
-        nonchangeMax > 0 &&
-        change.count &&
-        change.count > nonchangeMax) {
-        const lines = change.value.split("\n");
-        const partial = lines.slice(lines.length - nonchangeMax);
-        return `...\n${partial.join("\n")}\n`;
-    }
-    return change.value.split("\n").reduce((s, line) => {
-        return `${s}${operator}${line}\n`;
-    }, "");
-}

package/lib/cjs/index.js

@@ -1,19 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./types"), exports);
-__exportStar(require("./template-sync"), exports);
-__exportStar(require("./formatting"), exports);