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

package/src/template-sync.ts

@@ -1,256 +0,0 @@
-import { join } from "path";
-import { existsSync, readFileSync, writeFileSync } from "fs";
-import { getAllFilesInDir } from "./match";
-import { Config, FileOperation, LocalConfig } from "./types";
-import { mergeFile } from "./merge-file";
-import { gitClone } from "./clone-drivers/git-clone";
-import { Change } from "diff";
-import { TemplateCloneDriverFn } from "./clone-drivers";
-import { DiffResult, TemplateDiffDriverFn, gitDiff } from "./diff-drivers";
-import { gitCurrentRef } from "./ref-drivers";
-import { TemplateRefDriverFn } from "./ref-drivers/types";
-import { inferJSONIndent } from "./formatting";
-import * as commentJSON from "comment-json";
-import { TemplateCheckoutDriverFn, gitCheckout } from "./checkout-drivers";
-import { some } from "micromatch";
-
-export interface TemplateSyncOptions {
-  /**
-   * This is the url of the template repo
-   */
-  repoUrl: string;
-
-  /**
-   * Optional Branch to check out - if not specified, this checks out the
-   * default branch of the template repo
-   */
-  branch?: string;
-
-  /**
-   * The directory for cloning our template repo into via the cloneDriver
-   */
-  tmpCloneDir: string;
-
-  /**
-   * The repo directory path that we are going to merge toward
-   */
-  repoDir: string;
-
-  /**
-   * If set to true, template sync will apply the current ref
-   * of the template repo to afterRef
-   */
-  updateAfterRef?: boolean;
-
-  /**
-   * Defaults to using git clone
-   */
-  cloneDriver?: TemplateCloneDriverFn;
-
-  /**
-   * Defaults to using git diff
-   */
-  diffDriver?: TemplateDiffDriverFn;
-
-  /**
-   * Defaults to using git current ref
-   */
-  currentRefDriver?: TemplateRefDriverFn;
-
-  /**
-   * Defaults to using git checkout driver
-   */
-  checkoutDriver?: TemplateCheckoutDriverFn;
-}
-
-export interface TemplateSyncReturn {
-  /**
-   * An array of files that were skipped outright due to a templatesync.local ignore glob
-   */
-  localSkipFiles: string[];
-  /**
-   * An object mapping all file paths to any merge rules that would've overridden the merge rules
-   * of the template sync file.
-   *
-   * Note: right now, this shows non-changed diffs as well so you have to look for added or removed
-   */
-  localFileChanges: {
-    [filePath: string]: Change[];
-  };
-  /**
-   * A list of all files that are modified by this operation.  You can use total to quickly check if
-   * there was an actual meaningful change.
-   *
-   * Please note, ther may be localSkipfiles and total: 0, which indicates there were changes BUT the local template
-   * sync file rendered them meaningless.
-   */
-  modifiedFiles: DiffResult & {
-    total: number;
-  };
-}
-
-export const TEMPLATE_SYNC_CONFIG = "templatesync";
-export const TEMPLATE_SYNC_LOCAL_CONFIG = "templatesync.local";
-
-export async function templateSync(
-  options: TemplateSyncOptions,
-): Promise<TemplateSyncReturn> {
-  const cloneDriver = options.cloneDriver ?? gitClone;
-  const diffDriver = options.diffDriver ?? gitDiff;
-  const currentRefDriver = options.currentRefDriver ?? gitCurrentRef;
-  const checkoutDriver = options.checkoutDriver ?? gitCheckout;
-  const cloneReturn = await cloneDriver(options.tmpCloneDir, options.repoUrl);
-
-  const { dir: tempCloneDir, remoteName } =
-    typeof cloneReturn === "string"
-      ? {
-          dir: cloneReturn,
-          remoteName: "origin", // Default to this
-        }
-      : cloneReturn;
-
-  if (options.branch) {
-    await checkoutDriver({
-      tmpDir: tempCloneDir,
-      remoteName,
-      branch: options.branch,
-    });
-  }
-
-  // Get the clone Config
-  const cloneConfigPath = join(tempCloneDir, `${TEMPLATE_SYNC_CONFIG}.json`);
-  const templateSyncConfig: Config = existsSync(cloneConfigPath)
-    ? (commentJSON.parse(
-        readFileSync(cloneConfigPath).toString(),
-      ) as unknown as Config)
-    : { ignore: [] };
-
-  const localConfigFile = `${TEMPLATE_SYNC_LOCAL_CONFIG}.json`;
-  const localConfigPath = join(options.repoDir, localConfigFile);
-  const localTemplateSyncConfig: LocalConfig = existsSync(localConfigPath)
-    ? (commentJSON.parse(
-        readFileSync(localConfigPath).toString(),
-      ) as unknown as LocalConfig)
-    : { ignore: [] };
-
-  let filesToSync: DiffResult;
-  const ref = await currentRefDriver({
-    rootDir: tempCloneDir,
-  });
-  if (localTemplateSyncConfig.afterRef) {
-    if (ref === localTemplateSyncConfig.afterRef) {
-      // short circuit if the refs match
-      return {
-        localSkipFiles: [],
-        localFileChanges: {},
-        modifiedFiles: {
-          added: [],
-          modified: [],
-          deleted: [],
-          total: 0,
-        },
-      };
-    }
-    filesToSync = await diffDriver(
-      tempCloneDir,
-      localTemplateSyncConfig.afterRef,
-    );
-  } else {
-    filesToSync = {
-      added: getAllFilesInDir(tempCloneDir, [
-        ...templateSyncConfig.ignore,
-        ".git/**",
-      ]),
-      deleted: [],
-      modified: [],
-    };
-  }
-
-  // Apply ignore filters
-  filesToSync.added = filesToSync.added.filter(
-    (f) => !some(f, templateSyncConfig.ignore),
-  );
-  filesToSync.modified = filesToSync.modified.filter(
-    (f) => !some(f, templateSyncConfig.ignore),
-  );
-  filesToSync.deleted = filesToSync.deleted.filter(
-    (f) => !some(f, templateSyncConfig.ignore),
-  );
-
-  const localSkipFiles: Set<string> = new Set();
-  const localFileChanges: {
-    [filePath: string]: Change[];
-  } = {};
-
-  const fileSyncFactory = (op: FileOperation) => {
-    return async (f: string) => {
-      const result = await mergeFile(f, {
-        localTemplateSyncConfig,
-        templateSyncConfig,
-        tempCloneDir,
-        cwd: options.repoDir,
-        fileOperation: op,
-      });
-      if (result.ignoredDueToLocal) {
-        localSkipFiles.add(f);
-      } else if (result?.localChanges && result.localChanges.length > 0) {
-        localFileChanges[f] = result.localChanges;
-      }
-    };
-  };
-
-  // Added and modified have the same setup for now
-  await Promise.all(filesToSync.added.map(fileSyncFactory("added")));
-  await Promise.all(filesToSync.modified.map(fileSyncFactory("modified")));
-  await Promise.all(filesToSync.deleted.map(fileSyncFactory("deleted")));
-
-  // Report the files that changed in general
-  const actualAdded = filesToSync.added.filter((f) => !localSkipFiles.has(f));
-  const actualModified = filesToSync.modified.filter(
-    (f) => !localSkipFiles.has(f),
-  );
-  const actualDeleted = filesToSync.deleted.filter(
-    (f) => !localSkipFiles.has(f),
-  );
-  const modifiedFiles = {
-    added: actualAdded,
-    modified: actualModified,
-    deleted: actualDeleted,
-  };
-
-  // apply after ref
-  if (options.updateAfterRef) {
-    const ref = await currentRefDriver({
-      rootDir: tempCloneDir,
-    });
-
-    if (existsSync(localConfigPath)) {
-      const configStr = readFileSync(localConfigPath).toString();
-      const config = commentJSON.parse(configStr) as unknown as LocalConfig;
-      config.afterRef = ref;
-      writeFileSync(
-        localConfigPath,
-        commentJSON.stringify(config, null, inferJSONIndent(configStr)),
-      );
-      modifiedFiles.modified.push(localConfigFile);
-    } else {
-      writeFileSync(
-        localConfigPath,
-        commentJSON.stringify({ afterRef: ref }, null, 4),
-      );
-      modifiedFiles.added.push(localConfigFile);
-    }
-  }
-
-  return {
-    localSkipFiles: Array.from(localSkipFiles),
-    localFileChanges,
-    modifiedFiles: {
-      ...modifiedFiles,
-      total:
-        modifiedFiles.added.length +
-        modifiedFiles.deleted.length +
-        modifiedFiles.modified.length,
-    },
-  };
-}

package/src/test-utils/index.ts

@@ -1,13 +0,0 @@
-import { resolve } from "path";
-import { tmpdir } from "os";
-
-export const TEST_FIXTURES_DIR = resolve(
-  __dirname,
-  "..",
-  "..",
-  "test-fixtures",
-);
-
-export function tempDir(): string {
-  return process.env.RUNNER_TEMP ?? tmpdir();
-}

package/src/types.ts

@@ -1,129 +0,0 @@
-/**
- * How we want to merge json
- *
- * overwrite - the template sync overwrites completely
- * merge-template - we merge template into the current json with overrides on matching values happening from the template
- * merge-current - we merge the current json into the template json with overrides on matching values happening from the current json
- */
-export type BaseJsonMergeOptions =
-  | "overwrite"
-  | "merge-template"
-  | "merge-current";
-export interface JsonPathOverrides {
-  /**
-   * 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][];
-}
-export type JsonFileMergeOptions = BaseJsonMergeOptions | JsonPathOverrides;
-
-// Sum of all basic file merge options
-type MergePluginOptions = JsonFileMergeOptions;
-
-/**
- * Configuration object for a given file type merge configuration
- */
-export interface MergeConfig<T> {
-  /**
-   * A glob or array of globs (using micromatch syntax) that selects the files that this applies to
-   * when merging
-   */
-  glob: string | string[];
-  /**
-   * The node module, available on the calling node context, that you want to run.
-   * Built-in plugins can be specified via their built-in name (see documentation):
-   *
-   * Example: _json
-   */
-  plugin: string;
-  /**
-   * An array of first match file globs that will then call the plugin with the appropriate options
-   */
-  options: MergePluginOptions | T;
-}
-
-/**
- * The shape of a template sync config file
- */
-export interface Config<T = unknown> {
-  ignore: string[];
-  /**
-   * If there is no merge config, then we will always just overwrite the file for the diff
-   */
-  merge?: MergeConfig<T>[];
-}
-
-/**
- * The shape of a local template sync config file that overrides the root template repo
- */
-export interface LocalConfig<T = unknown> {
-  /**
-   * This is the ref that we compare against.  If empty, we use all files that have changed since the
-   * beginning of the template repo.
-   */
-  afterRef?: string;
-
-  ignore: string[];
-  /**
-   * If there is no merge config, then we will always just overwrite the file for the diff
-   */
-  merge?: MergeConfig<T>[];
-}
-
-/**
- * Information around the file we are trying to merge and that arguments for that merge
- * from matching a merge configuration
- */
-export interface MergeContext<PluginOptions = unknown> {
-  relFilePath: string;
-  /**
-   * If you have provided a custom merge plugin, this will be the "options" section of
-   * the matching glob
-   */
-  mergeArguments: PluginOptions;
-  /**
-   * If this run is for the local config.  Keep in mind that any local config overrides will
-   * be run after the template sync options and we would like to report any changes that
-   * are done
-   */
-  isLocalOptions?: boolean;
-}
-
-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 repos 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;
-}
-
-export type FileOperation = "added" | "modified" | "deleted";

package/templatesync.local.json

@@ -1,15 +0,0 @@
-{
-  "ignore": ["**/*.md"],
-  "merge": {
-    ".json": {
-      "rules": [
-        {
-          "glob": "package.json",
-          "options": {
-            "paths": [["$.repository", "merge-template"]]
-          }
-        }
-      ]
-    }
-  }
-}

package/test-fixtures/downstream/README.md

@@ -1,3 +0,0 @@
-# My custom readme
-
-This is a custom readme for my file

package/test-fixtures/downstream/package.json

@@ -1,18 +0,0 @@
-{
-  "name": "mypkg",
-  "description": "my description",
-  "dependencies": {
-    "mypackage": "^1.2.0",
-    "newpacakge": "^22.2.2",
-    "package2": "3.22.1",
-    "huh": "^2.30.0"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "build",
-    "test": "jest",
-    "myscript": "somescript"
-  }
-}

package/test-fixtures/downstream/plugins/custom-plugin.js

@@ -1,11 +0,0 @@
-module.exports = {
-  merge: () => {
-    return JSON.stringify(
-      {
-        downstream: true,
-      },
-      null,
-      4,
-    );
-  },
-};

package/test-fixtures/downstream/src/index.js

@@ -1,2 +0,0 @@
-"use strict";
-console.log("This is my custom stuff");

package/test-fixtures/downstream/src/index.ts

@@ -1 +0,0 @@
-console.log("This is my custom stuff");

package/test-fixtures/downstream/src/templated.js

@@ -1,2 +0,0 @@
-"use strict";
-console.log("this is downstream stuff that should not change");

package/test-fixtures/downstream/src/templated.ts

@@ -1 +0,0 @@
-console.log("this is downstream stuff that should not change");

package/test-fixtures/downstream/templatesync.json

@@ -1,16 +0,0 @@
-{
-  "ignore": ["src/!(templated).ts", "custom-bin/**"],
-  "merge": [
-    {
-      "glob": "package.json",
-      "plugin": "_json",
-      "options": {
-        "paths": [
-          ["$.dependencies", "merge-template"],
-          ["$.devDependencies", "merge-template"],
-          ["$.engines", "merge-template"]
-        ]
-      }
-    }
-  ]
-}

package/test-fixtures/downstream/templatesync.local.json

@@ -1,10 +0,0 @@
-{
-  "ignore": ["custom-bin/**"],
-  "merge": [
-    {
-      "glob": "package.json",
-      "plugin": "plugins/custom-plugin.js",
-      "options": {}
-    }
-  ]
-}

package/test-fixtures/dummy-plugin.js

@@ -1,8 +0,0 @@
-module.exports = {
-  merge: () => {
-    return JSON.stringify({ tested: true }, null, 4);
-  },
-  validate: () => {
-    return [];
-  },
-};

package/test-fixtures/glob-test/folder1/something.js

@@ -1 +0,0 @@
-"use strict";

package/test-fixtures/template/custom-bin/something.txt

@@ -1 +0,0 @@
-This is a file that is only meant for the base template maintainers

package/test-fixtures/template/package.json

@@ -1,17 +0,0 @@
-{
-  "name": "some-stub-name",
-  "description": "some-stub-description",
-  "dependencies": {
-    "mypackage": "^1.2.0",
-    "package2": "3.22.1",
-    "huh": "~1.0.0"
-  },
-  "engines": {
-    "node": ">=15"
-  },
-  "scripts": {
-    "build": "build",
-    "test": "fill this in yourself"
-  },
-  "version": "new-version"
-}

package/test-fixtures/template/src/index.js

@@ -1,2 +0,0 @@
-"use strict";
-console.log("replace this in the downstream");

package/test-fixtures/template/src/index.ts

@@ -1 +0,0 @@
-console.log("replace this in the downstream");

package/test-fixtures/template/src/templated.js

@@ -1,2 +0,0 @@
-"use strict";
-console.log("we changed this up and want to push the changes");

package/test-fixtures/template/src/templated.ts

@@ -1 +0,0 @@
-console.log("we changed this up and want to push the changes");

package/test-fixtures/template/templatesync.json

@@ -1,16 +0,0 @@
-{
-  "ignore": ["src/!(templated).ts", "custom-bin/**"],
-  "merge": [
-    {
-      "glob": "package.json",
-      "plugin": "_json",
-      "options": {
-        "paths": [
-          ["$.dependencies", "merge-template"],
-          ["$.devDependencies", "merge-template"],
-          ["$.engines", "merge-template"]
-        ]
-      }
-    }
-  ]
-}

package/test-fixtures/testGitRepo/README.md

@@ -1,17 +0,0 @@
-# This is the master branch
-
-How to update this?
-
-You will want to "re-initialize this folder" by createing your .git repo
-
-```shell
-mv gitDir .git
-```
-
-From here, you can CD into the folder and run git commands. Anything you do will be recorded into the .git
-
-Before you commit those git history changes, please create the gitDir again from the new .git
-
-```shell
-mv .git gitDir
-```

package/test-fixtures/testGitRepo/gitDir/COMMIT_EDITMSG

@@ -1,14 +0,0 @@
-first commit
-
-# Please enter the commit message for your changes. Lines starting
-# with '#' will be ignored, and an empty message aborts the commit.
-#
-# Date:      Sun Jun 9 13:06:24 2024 -0600
-#
-# On branch master
-#
-# Initial commit
-#
-# Changes to be committed:
-#	new file:   README.md
-#

package/test-fixtures/testGitRepo/gitDir/HEAD

@@ -1 +0,0 @@
-ref: refs/heads/master

package/test-fixtures/testGitRepo/gitDir/config

@@ -1,7 +0,0 @@
-[core]
-	repositoryformatversion = 0
-	filemode = true
-	bare = false
-	logallrefupdates = true
-	ignorecase = true
-	precomposeunicode = true

package/test-fixtures/testGitRepo/gitDir/description

@@ -1 +0,0 @@
-Unnamed repository; edit this file 'description' to name the repository.

package/test-fixtures/testGitRepo/gitDir/hooks/applypatch-msg.sample

@@ -1,15 +0,0 @@
-#!/bin/sh
-#
-# An example hook script to check the commit log message taken by
-# applypatch from an e-mail message.
-#
-# The hook should exit with non-zero status after issuing an
-# appropriate message if it wants to stop the commit.  The hook is
-# allowed to edit the commit message file.
-#
-# To enable this hook, rename this file to "applypatch-msg".
-
-. git-sh-setup
-commitmsg="$(git rev-parse --git-path hooks/commit-msg)"
-test -x "$commitmsg" && exec "$commitmsg" ${1+"$@"}
-:

package/test-fixtures/testGitRepo/gitDir/hooks/commit-msg.sample

@@ -1,24 +0,0 @@
-#!/bin/sh
-#
-# An example hook script to check the commit log message.
-# Called by "git commit" with one argument, the name of the file
-# that has the commit message.  The hook should exit with non-zero
-# status after issuing an appropriate message if it wants to stop the
-# commit.  The hook is allowed to edit the commit message file.
-#
-# To enable this hook, rename this file to "commit-msg".
-
-# Uncomment the below to add a Signed-off-by line to the message.
-# Doing this in a hook is a bad idea in general, but the prepare-commit-msg
-# hook is more suited to it.
-#
-# SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
-# grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"
-
-# This example catches duplicate Signed-off-by lines.
-
-test "" = "$(grep '^Signed-off-by: ' "$1" |
-	 sort | uniq -c | sed -e '/^[ 	]*1[ 	]/d')" || {
-	echo >&2 Duplicate Signed-off-by lines.
-	exit 1
-}