watskeburt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-2022 Sander Verweij
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# watskeburt
+
+get git changed files & their statusses since _any reference_
+
+## what's this do?
+
+A micro-lib to retrieve an array of file names that were changed (added,
+modified, renamed, deleted, ...) since the reference it got passed.
+
+- :warning: NOT yet published on npm
+- :warning: in the process of getting 'production ready'. It's automatically
+  tested + it's using itself + interface is stable - but a bunch of static
+  analysis still needs be added, as well as a commonjs version.
+- :warning: currently esm only - commonjs compiledown will follow as part of the
+  previous point.
+
+## sample return value
+
+```json
+[
+  { "name": "doc/cli.md", "changeType": "modified" },
+  {
+    "name": "test/report/mermaid/mermaid.spec.mjs",
+    "changeType": "renamed",
+    "oldName": "test/configs/plugins/mermaid-reporter-plugin/module-level/index.spec.mjs",
+    "similarity": 66
+  },
+  { "name": "src/not-tracked-yet.mjs", "changeType": "untracked" }
+  // ...
+]
+```
+
+## cli
+
+For now there's also a simple command line interface
+
+```
+Usage: watskeburt [options] <reference>
+
+lists files since <reference>
+
+Options:
+  -T, --output-type <type>  json,regex (default: "regex")
+  --tracked-only            only take tracked files into account (default: false)
+  -h, --help                display help for command
+
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "watskeburt",
+  "version": "0.1.0",
+  "description": "list files changed since a git reference",
+  "bin": "src/cli.mjs",
+  "main": "src/main.mjs",
+  "module": "src/main.mjs",
+  "exports": {
+    ".": [
+      {
+        "import": "./src/main.mjs"
+      }
+    ]
+  },
+  "types": "types/watskeburt.d.ts",
+  "files": [
+    "src",
+    "!src/**/*.spec.mjs",
+    "!**/*.DS_Store",
+    "types",
+    "LICENSE",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "mocha \"src/**/*.spec.mjs\"",
+    "test:cover": "c8 --check-coverage --statements 100 --branches 100 --functions 100 --lines 100 --exclude \"**/*.spec.mjs\" --reporter text-summary --reporter html --reporter json-summary npm test",
+    "depcruise": "depcruise src --config",
+    "depcruise:graph": "depcruise src --include-only '^(src)' --config --output-type dot | dot -T svg | depcruise-wrap-stream-in-html > docs/dependency-graph.html",
+    "depcruise:graph:archi": "depcruise src --include-only '^(src)' --config --output-type archi | dot -T svg | depcruise-wrap-stream-in-html > docs/high-level-dependency-graph.html",
+    "depcruise:graph:dev": "depcruise src --include-only '^(src)' --prefix vscode://file/$(pwd)/ --config --output-type dot | dot -T svg | depcruise-wrap-stream-in-html | browser",
+    "depcruise:graph:diff:dev": "depcruise src --include-only '^(src)' --focus \"$(node src/cli.mjs main -T regex)\" --prefix vscode://file/$(pwd)/ --config --output-type dot | dot -T svg | depcruise-wrap-stream-in-html | browser",
+    "depcruise:graph:diff:mermaid": "depcruise src --include-only '^(src)' --config --output-type mermaid --output-to - --focus \"$(node src/cli.mjs $SHA -T regex)\"",
+    "depcruise:html": "depcruise src --progress --config --output-type err-html --output-to dependency-violation-report.html",
+    "depcruise:text": "depcruise src --progress --config --output-type text",
+    "depcruise:focus": "depcruise src --progress --config --output-type text --focus"
+  },
+  "keywords": [
+    "git",
+    "diff"
+  ],
+  "author": "Sander Verweij (https://sverweij.github.io/)",
+  "license": "MIT",
+  "devDependencies": {
+    "c8": "^7.11.3",
+    "dependency-cruiser": "^11.11.0",
+    "mocha": "^10.0.0"
+  },
+  "dependencies": {
+    "commander": "^9.3.0"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+import { program } from "commander";
+import { convert } from "./main.mjs";
+
+program
+  .description("lists files since <reference>")
+  .option("-T, --output-type <type>", "json,regex", "regex")
+  .option("--tracked-only", "only take tracked files into account", false)
+  .arguments("<reference>")
+  .parse(process.argv);
+
+if (program.args[0]) {
+  try {
+    console.log(convert(program.args[0], program.opts()));
+  } catch (pError) {
+    console.error(pError);
+  }
+} else {
+  program.help();
+}

package/src/convert-to-change-object.mjs

@@ -0,0 +1,115 @@
+import { EOL } from "node:os";
+const DIFF_NAME_STATUS_LINE_PATTERN = new RegExp(
+  "^(?<changeType>[ACDMRTUXB])(?<similarity>[0-9]{3})?[ \t]+(?<name>[^ \t]+)[ \t]*(?<newName>[^ \t]+)?$"
+);
+const DIFF_SHORT_STATUS_LINE_PATTERN = new RegExp(
+  "^(?<stagedChangeType>[ ACDMRTUXB?!])(?<unStagedChangeType>[ ACDMRTUXB?!])[ \t]+(?<name>[^ \t]+)(( -> )(?<newName>[^ \t]+))?$"
+);
+
+const CHANGE_CHAR_2_CHANGE_TYPE = {
+  A: "added",
+  C: "copied",
+  D: "deleted",
+  M: "modified",
+  R: "renamed",
+  T: "type changed",
+  U: "unmerged",
+  B: "pairing broken",
+  " ": "unmodified",
+  "?": "untracked",
+  "!": "ignored",
+  // X: "unknown"
+};
+
+function changeChar2ChangeType(pChar) {
+  return CHANGE_CHAR_2_CHANGE_TYPE[pChar] || "unknown";
+}
+
+/**
+ *
+ * @param {string} pString
+ * @returns {import('../types/watskeburt').IChange}
+ */
+export function convertStatusLine(pString) {
+  const lMatchResult = pString.match(DIFF_SHORT_STATUS_LINE_PATTERN);
+  /**  @type {import('../types/watskeburt').IChange} */
+  let lReturnValue = {};
+
+  if (lMatchResult) {
+    const lStagedChangeType = changeChar2ChangeType(
+      lMatchResult.groups.stagedChangeType
+    );
+    const lUnStagedChangeType = changeChar2ChangeType(
+      lMatchResult.groups.unStagedChangeType
+    );
+
+    lReturnValue.changeType =
+      lStagedChangeType === "unmodified"
+        ? lUnStagedChangeType
+        : lStagedChangeType;
+
+    if (lMatchResult.groups.newName) {
+      lReturnValue.name = lMatchResult.groups.newName;
+      lReturnValue.oldName = lMatchResult.groups.name;
+    } else {
+      lReturnValue.name = lMatchResult.groups.name;
+    }
+  }
+  return lReturnValue;
+}
+
+/**
+ *
+ * @param {string} pString
+ * @returns {import('../types/watskeburt').IChange}
+ */
+export function convertDiffLine(pString) {
+  const lMatchResult = pString.match(DIFF_NAME_STATUS_LINE_PATTERN);
+  /**  @type {import('../types/watskeburt').IChange} */
+  let lReturnValue = {};
+
+  if (lMatchResult) {
+    lReturnValue.changeType = changeChar2ChangeType(
+      lMatchResult.groups.changeType
+    );
+    if (lMatchResult.groups.similarity) {
+      lReturnValue.similarity = Number.parseInt(
+        lMatchResult.groups.similarity,
+        10
+      );
+    }
+    if (lMatchResult.groups.newName) {
+      lReturnValue.name = lMatchResult.groups.newName;
+      lReturnValue.oldName = lMatchResult.groups.name;
+    } else {
+      lReturnValue.name = lMatchResult.groups.name;
+    }
+  }
+  return lReturnValue;
+}
+
+/**
+ *
+ * @param {string} pString
+ * @returns {import('../types/watskeburt').IChange[]}
+ */
+export function convertStatusLines(pString) {
+  return pString
+    .split(EOL)
+    .filter(Boolean)
+    .map(convertStatusLine)
+    .filter(({ changeType }) => Boolean(changeType));
+}
+
+/**
+ *
+ * @param {string} pString
+ * @returns {import('../types/watskeburt').IChange[]}
+ */
+export function convertDiffLines(pString) {
+  return pString
+    .split(EOL)
+    .filter(Boolean)
+    .map(convertDiffLine)
+    .filter(({ changeType }) => Boolean(changeType));
+}

package/src/formatters/format.mjs

@@ -0,0 +1,19 @@
+import formatToRegex from "./regex.mjs";
+import formatToJSON from "./json.mjs";
+
+const OUTPUT_TYPE_TO_FUNCTION = {
+  regex: formatToRegex,
+  json: formatToJSON,
+  object: (x) => x,
+};
+const DEFAULT_OUTPUT_TYPE = "object";
+
+/**
+ *
+ * @param {import("../../types/watskeburt.js").IChange[]} pChanges
+ * @param {import("../../types/watskeburt.js").outputTypeType} pOutputType
+ * @returns {string|import("../../types/watskeburt.js").IChange[]}
+ */
+export default function format(pChanges, pOutputType) {
+  return OUTPUT_TYPE_TO_FUNCTION[pOutputType || DEFAULT_OUTPUT_TYPE](pChanges);
+}

package/src/formatters/json.mjs

@@ -0,0 +1,8 @@
+/**
+ *
+ * @param {import('../types/watskeburt').IChange[]} pChanges
+ * @return {string}
+ */
+export default function formatToJSON(pChanges) {
+  return JSON.stringify(pChanges, null, 2);
+}

package/src/formatters/regex.mjs

@@ -0,0 +1,23 @@
+import { extname } from "node:path";
+
+/**
+ *
+ * @param {import('../types/watskeburt').IChange[]} pChanges
+ * @param {string[]} pExtensions
+ * @param {import('../types/watskeburt').changeTypeType[]} pChangeTypes
+ * @return {string}
+ */
+export default function formatToRegex(
+  pChanges,
+  pExtensions = [".js", ".ts", ".mjs", ".cjs"],
+  pChangeTypes = ["modified", "added", "renamed", "copied", "untracked"]
+) {
+  const lChanges = pChanges
+    .filter((pChange) => pChangeTypes.includes(pChange.changeType))
+    .map(
+      ({ name }) => name //.replace(/\./g, "\\\\.")
+    )
+    .filter((pName) => pExtensions.includes(extname(pName)))
+    .join("|");
+  return `^(${lChanges})$`;
+}

package/src/get-diff-lines.mjs

@@ -0,0 +1,51 @@
+import { spawnSync } from "node:child_process";
+
+function stringifyOutStream(pError) {
+  if (pError instanceof Buffer) {
+    return pError.toString("utf8");
+  } else {
+    return pError;
+  }
+}
+
+/**
+ *
+ * @param {string[]} pArguments
+ * @return {string}
+ * @throws {Error}
+ */
+function getGitResult(pArguments, pSpawnFunction) {
+  const lGitResult = pSpawnFunction("git", pArguments, {
+    cwd: process.cwd(),
+    env: process.env,
+  });
+
+  if (lGitResult.error) {
+    throw new Error(stringifyOutStream(lGitResult.error));
+  }
+
+  if (lGitResult.status === 0) {
+    return stringifyOutStream(lGitResult.stdout);
+  } else {
+    throw new Error(lGitResult.output);
+  }
+}
+
+/**
+ *
+ * @returns {string}
+ * @throws {Error}
+ */
+export function getStatusShort(pSpawnFunction = spawnSync) {
+  return getGitResult(["status", "--porcelain"], pSpawnFunction);
+}
+
+/**
+ *
+ * @param {string} pOldThing the target to compare against (e.g. branch name, commit, tag etc)
+ * @return {string}
+ * @throws {Error}
+ */
+export function getDiffLines(pOldThing, pSpawnFunction = spawnSync) {
+  return getGitResult(["diff", pOldThing, "--name-status"], pSpawnFunction);
+}

package/src/main.mjs

@@ -0,0 +1,32 @@
+import {
+  convertDiffLines,
+  convertStatusLines,
+} from "./convert-to-change-object.mjs";
+import { getDiffLines, getStatusShort } from "./get-diff-lines.mjs";
+import format from "./formatters/format.mjs";
+
+/**
+ *
+ * returns a list of files changed since pOldThing. With pOptions
+ * you can
+ * - influence whether you want to have the output as an array of
+ *   IChange-s or one of the other output formats (outputType)
+ * - tell whether you want to take untracked files into account as
+ *   well (by setting trackedOnly to false)
+ *
+ * @param {string} pOldThing reference to a commit, branch, tag, ...
+ * @param {import("../types/watskeburt.js").IOptions} pOptions
+ * @returns {string|import("../types/watskeburt.js").IChange[]}
+ */
+export function convert(pOldThing, pOptions) {
+  let lChanges = convertDiffLines(getDiffLines(pOldThing));
+
+  if (!pOptions.trackedOnly) {
+    lChanges = lChanges.concat(
+      convertStatusLines(getStatusShort()).filter(
+        ({ changeType }) => changeType === "untracked"
+      )
+    );
+  }
+  return format(lChanges, pOptions.outputType);
+}

package/types/watskeburt.d.ts

@@ -0,0 +1,27 @@
+export type changeTypeType =
+  | "added"
+  | "copied"
+  | "deleted"
+  | "modified"
+  | "renamed"
+  | "type changed"
+  | "unmerged"
+  | "pairing broken"
+  | "unknown"
+  | "unmodified"
+  | "untracked"
+  | "ignored";
+
+export interface IChange {
+  name: string;
+  changeType: changeTypeType;
+  similarity?: Number;
+  oldName?: string;
+}
+
+export type outputTypeType = "regex" | "json" | "object";
+
+export interface IOptions {
+  outputType: outputTypeType;
+  trackedOnly: boolean;
+}