watskeburt 0.1.0 → 0.4.0

package/README.md

@@ -1,47 +1,88 @@
 # watskeburt
 
-get git changed files & their statusses since _any reference_
+get git changed files & their statuses since _any revision_
 
 ## 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.
+modified, renamed, deleted, ...) since the revision it got passed. Also
+sports a cli for use outside of JavaScript c.s.
 
-- :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.
+  tested + it's using itself - but a bunch of static analysis and a bit of
+  automation still needs be added.
+- :warning: Interface is stable-ish, but can can change until 1.0.0 is published
+- :warning: expect some rough edges for e.g. error scenarios
 
-## sample return value
+## why?
 
-```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" }
-  // ...
-]
-```
+Useful primitives to support e.g. auto-documenting pull requests, or to save
+processing power by only doing static analysis only over stuff that is changed.
+
+There are a few packages like these like this on npm, but it seems they've
+fallen out of maintenance. More generic packages don't get plagued by this
+but for just this simple usage they're a bit overkill.
+
+## usage
 
-## cli
+### :shell: cli
 
 For now there's also a simple command line interface
 
+```shell
+# list all JavaScript-ish files changed since main in a regular expression
+$ npx watskeburt main
+^(src/cli.mjs|src/formatters/regex.mjs|src/version.mjs)$
 ```
-Usage: watskeburt [options] <reference>
 
-lists files since <reference>
+By default this returns a regex that contains all changed files that could be
+source files in the JavaScript ecosystem (.js, .mjs, .ts, .tsx ...) that can
+be used in e.g. the `--focus` filter of dependency-cruiser:
+
+```
+Usage: cli [options] [revision]
+
+lists files & their statuses since [revision].
+
+-> When you don't pass a revision the revision defaults to the current one.
 
 Options:
+  -V, --version             output the version number
   -T, --output-type <type>  json,regex (default: "regex")
   --tracked-only            only take tracked files into account (default: false)
   -h, --help                display help for command
+```
 
+### :scroll: API
+
+```javascript
+// const { list } = require('watskeburt'); // will work in commonjs  contexts  as well
+import { list, getSHA } from "watskeburt";
+
+// print the SHA1 of the current HEAD
+console.log(getSHA());
+
+// list all files that differ between 'main' and
+/** @type {import('watskeburt').IChange[]} */
+const lChangedFiles = list("main");
 ```
+
+An array of changes looks something like this:
+
+```javascript
+[
+  { name: "doc/cli.md", changeType: "modified" },
+  {
+    name: "test/thing.spec.mjs",
+    changeType: "renamed",
+    oldName: "test/old-thing.spec.mjs",
+  },
+  { name: "src/not-tracked-yet.mjs", changeType: "untracked" },
+];
+```
+
+## 🇳🇱 'watskeburt'??
+
+_watskeburt_ is a fast pronunciation of the Dutch sentence "Wat is er gebeurd?"
+(What has happened?), as well as the title of a song by the Dutch hip hop group
+"De Jeugd van Tegenwoordig".

package/dist/cjs-bundle.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var x=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var C=Object.prototype.hasOwnProperty;var A=(e,t)=>{for(var n in t)s(e,n,{get:t[n],enumerable:!0})},_=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of E(t))!C.call(e,o)&&o!==n&&s(e,o,{get:()=>t[o],enumerable:!(r=x(t,o))||r.enumerable});return e};var R=e=>_(s({},"__esModule",{value:!0}),e);var H={};A(H,{getSHA:()=>w,list:()=>M});module.exports=R(H);var u=require("os"),D=/^(?<changeType>[ACDMRTUXB])(?<similarity>[0-9]{3})?[ \t]+(?<name>[^ \t]+)[ \t]*(?<newName>[^ \t]+)?$/,L=/^(?<stagedChangeType>[ ACDMRTUXB?!])(?<unStagedChangeType>[ ACDMRTUXB?!])[ \t]+(?<name>[^ \t]+)(( -> )(?<newName>[^ \t]+))?$/,O={A:"added",C:"copied",D:"deleted",M:"modified",R:"renamed",T:"type changed",U:"unmerged",B:"pairing broken"," ":"unmodified","?":"untracked","!":"ignored"};function i(e){return O[e]||"unknown"}function U(e){let t=e.match(L),n={};if(t){let r=i(t.groups.stagedChangeType),o=i(t.groups.unStagedChangeType);n.changeType=r==="unmodified"?o:r,t.groups.newName?(n.name=t.groups.newName,n.oldName=t.groups.name):n.name=t.groups.name}return n}function v(e){let t=e.match(D),n={};return t&&(n.changeType=i(t.groups.changeType),t.groups.newName?(n.name=t.groups.newName,n.oldName=t.groups.name):n.name=t.groups.name),n}function m(e){return e.split(u.EOL).filter(Boolean).map(U).filter(({changeType:t})=>Boolean(t))}function g(e){return e.split(u.EOL).filter(Boolean).map(v).filter(({changeType:t})=>Boolean(t))}var a=require("child_process");function d(e){return e instanceof Buffer?e.toString("utf8"):e}function $(e){throw e.code==="ENOENT"?new Error("git executable not found"):new Error(`internal spawn error: ${e}`)}function c(e,t,n){let r=n("git",e,{cwd:process.cwd(),env:process.env});if(r.error&&$(r.error),r.status===0)return d(r.stdout);throw new Error(t[r.status]||`internal git error: ${r.status} (${d(r.stderr)})`)}function T(e=a.spawnSync){let t={129:`'${process.cwd()}' does not seem to be a git repository`};return c(["status","--porcelain"],t,e)}function h(e,t=a.spawnSync){let n={128:`revision '${e}' unknown `,129:`'${process.cwd()}' does not seem to be a git repository`};return c(["diff",e,"--name-status"],n,t)}function S(e=a.spawnSync){return c(["rev-parse","HEAD"],{},e).slice(0,40)}var N=require("path");function f(e,t=[".js",".jsx",".mjs",".cjs",".ts",".tsx",".vue",".vuex",".json"],n=["modified","added","renamed","copied","untracked"]){return`^(${e.filter(o=>n.includes(o.changeType)).map(({name:o})=>o).filter(o=>t.includes((0,N.extname)(o))).join("|")})$`}function p(e){return JSON.stringify(e,null,2)}var j={regex:f,json:p,object:e=>e},B="object";function l(e,t){return j[t||B](e)}function w(){return S()}function M(e,t){let n=e||w(),r=g(h(n)),o=t||{};return o.trackedOnly||(r=r.concat(m(T()).filter(({changeType:y})=>y==="untracked"))),l(r,o.outputType)}0&&(module.exports={getSHA,list});

package/package.json

@@ -1,20 +1,41 @@
 {
   "name": "watskeburt",
-  "version": "0.1.0",
-  "description": "list files changed since a git reference",
+  "version": "0.4.0",
+  "description": "List files changed since a git revision",
+  "keywords": [
+    "git",
+    "diff"
+  ],
+  "homepage": "https://github.com/sverweij/watskeburt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sverweij/watskeburt"
+  },
+  "bugs": {
+    "url": "https://github.com/sverweij/watskeburt/issues"
+  },
+  "author": {
+    "name": "Sander Verweij",
+    "url": "https://sverweij.github.io"
+  },
+  "license": "MIT",
   "bin": "src/cli.mjs",
-  "main": "src/main.mjs",
+  "main": "dist/cjs-bundle.js",
   "module": "src/main.mjs",
+  "sideEffects": false,
   "exports": {
     ".": [
       {
-        "import": "./src/main.mjs"
-      }
+        "import": "./src/main.mjs",
+        "require": "./dist/cjs-bundle.js"
+      },
+      "./dist/cjs-bundle.js"
     ]
   },
   "types": "types/watskeburt.d.ts",
   "files": [
     "src",
+    "dist",
     "!src/**/*.spec.mjs",
     "!**/*.DS_Store",
     "types",
@@ -22,31 +43,61 @@
     "package.json",
     "README.md"
   ],
+  "dependencies": {
+    "commander": "^9.3.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^5.30.5",
+    "c8": "^7.11.3",
+    "dependency-cruiser": "^11.11.0",
+    "esbuild": "^0.14.48",
+    "eslint": "^8.19.0",
+    "eslint-config-moving-meadow": "^3.0.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-budapestian": "^4.0.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-mocha": "^10.0.5",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-security": "^1.5.0",
+    "eslint-plugin-unicorn": "^43.0.1",
+    "mocha": "^10.0.0",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^2.7.1",
+    "typescript": "^4.7.4"
+  },
+  "engines": {
+    "node": "^12.20||^14||>=16"
+  },
   "scripts": {
+    "build": "npm-run-all --sequential build:version build:dist",
+    "build:version": "node tools/get-version.mjs > src/version.mjs",
+    "build:dist": "esbuild src/main.mjs --format=cjs --target=node12 --platform=node --bundle --global-name=wkbtcjs --minify --outfile=dist/cjs-bundle.js",
+    "check": "npm-run-all --parallel --aggregate-output lint depcruise test:cover",
+    "clean": "rm -rf dist",
     "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": "depcruise src --include-only '^(src)' --config --output-type dot | dot -T svg | tee docs/dependency-graph.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"
+    "depcruise:focus": "depcruise src --progress --config --output-type text --focus",
+    "lint": "npm-run-all --parallel --aggregate-output lint:format lint:eslint",
+    "lint:fix": "npm-run-all --parallel --aggregate-output lint:format:fix lint:eslint:fix",
+    "lint:eslint": "eslint src --cache --cache-location node_modules/.cache/eslint/",
+    "lint:eslint:fix": "eslint src tools --fix --cache --cache-location node_modules/.cache/eslint/",
+    "lint:format": "prettier --check \"{src,tools}/**/*.mjs\" \"types/**/*.ts\" \"*.{json,yml,md,js}\"",
+    "lint:format:fix": "prettier --loglevel warn --write \"{src,tools}/**/*.mjs\" \"types/**/*.ts\" \"*.{json,yml,md,js}\"",
+    "scm:stage": "git add .",
+    "version": "npm-run-all --sequential clean build lint depcruise:graph scm:stage"
   },
-  "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"
-  }
+  "eslintIgnore": [
+    "coverage",
+    "docs",
+    "dist",
+    "node_modules"
+  ]
 }

package/src/.eslintrc.json

@@ -0,0 +1,47 @@
+{
+  "root": true,
+  "extends": ["moving-meadow"],
+  "overrides": [
+    {
+      "files": ["**/*.mjs"],
+      "rules": {
+        "unicorn/no-null": "off",
+        "unicorn/prefer-spread": "off",
+        "node/no-unsupported-features/es-syntax": "off",
+        "import/no-relative-parent-imports": "off",
+        "sort-imports": "off",
+        "unicorn/prefer-node-protocol": "error",
+        "unicorn/prefer-module": "error"
+      },
+      "parserOptions": {
+        "ecmaVersion": "latest"
+      }
+    },
+    {
+      "files": ["**/*.spec.mjs"],
+      "env": {
+        "mocha": true
+      },
+      "rules": {
+        "no-magic-numbers": "off",
+        "security/detect-non-literal-require": "off",
+        "security/detect-non-literal-fs-filename": "off",
+        "max-lines-per-function": "off",
+        "max-lines": "off",
+        "no-null": "off"
+      }
+    },
+    {
+      "files": ["types/*.ts"],
+      "plugins": ["@typescript-eslint"],
+      "extends": ["plugin:@typescript-eslint/recommended"],
+      "parser": "@typescript-eslint/parser",
+      "parserOptions": {
+        "ecmaVersion": "latest"
+      },
+      "rules": {
+        "node/no-unsupported-features/es-syntax": "off"
+      }
+    }
+  ]
+}

package/src/cli.mjs

@@ -1,21 +1,23 @@
 #!/usr/bin/env node
+/* eslint-disable no-console */
 
 import { program } from "commander";
-import { convert } from "./main.mjs";
+import { list } from "./main.mjs";
+import { VERSION } from "./version.mjs";
 
 program
-  .description("lists files since <reference>")
+  .description(
+    "lists files & their statuses since [revision].\n\n" +
+      "-> When you don't pass a revision the revision defaults to the current one."
+  )
+  .version(VERSION)
   .option("-T, --output-type <type>", "json,regex", "regex")
   .option("--tracked-only", "only take tracked files into account", false)
-  .arguments("<reference>")
+  .arguments("[revision]")
   .parse(process.argv);
 
-if (program.args[0]) {
-  try {
-    console.log(convert(program.args[0], program.opts()));
-  } catch (pError) {
-    console.error(pError);
-  }
-} else {
-  program.help();
+try {
+  console.log(list(program.args[0], program.opts()));
+} catch (pError) {
+  console.error(`ERROR: ${pError.message}`);
 }

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

@@ -1,10 +1,13 @@
+// the security (and unicorn) plugins don't seem to detect named caption
+// groups very well - false-flagging below regular expressions to be susceptible
+// to redos attacks.
+/* eslint-disable unicorn/no-unsafe-regex, security/detect-unsafe-regex */
 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 DIFF_NAME_STATUS_LINE_PATTERN =
+  /^(?<changeType>[ACDMRTUXB])(?<similarity>[0-9]{3})?[ \t]+(?<name>[^ \t]+)[ \t]*(?<newName>[^ \t]+)?$/;
+const DIFF_SHORT_STATUS_LINE_PATTERN =
+  /^(?<stagedChangeType>[ ACDMRTUXB?!])(?<unStagedChangeType>[ ACDMRTUXB?!])[ \t]+(?<name>[^ \t]+)(( -> )(?<newName>[^ \t]+))?$/;
 
 const CHANGE_CHAR_2_CHANGE_TYPE = {
   A: "added",
@@ -22,6 +25,7 @@ const CHANGE_CHAR_2_CHANGE_TYPE = {
 };
 
 function changeChar2ChangeType(pChar) {
+  // eslint-disable-next-line security/detect-object-injection
   return CHANGE_CHAR_2_CHANGE_TYPE[pChar] || "unknown";
 }
 
@@ -72,12 +76,6 @@ export function convertDiffLine(pString) {
     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;

package/src/formatters/format.mjs

@@ -4,7 +4,7 @@ import formatToJSON from "./json.mjs";
 const OUTPUT_TYPE_TO_FUNCTION = {
   regex: formatToRegex,
   json: formatToJSON,
-  object: (x) => x,
+  object: (pX) => pX,
 };
 const DEFAULT_OUTPUT_TYPE = "object";
 

package/src/formatters/json.mjs

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

package/src/formatters/regex.mjs

@@ -9,13 +9,24 @@ import { extname } from "node:path";
  */
 export default function formatToRegex(
   pChanges,
-  pExtensions = [".js", ".ts", ".mjs", ".cjs"],
+  pExtensions = [
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".ts",
+    ".tsx",
+    ".vue",
+    ".vuex",
+    ".json",
+  ],
   pChangeTypes = ["modified", "added", "renamed", "copied", "untracked"]
 ) {
   const lChanges = pChanges
     .filter((pChange) => pChangeTypes.includes(pChange.changeType))
     .map(
-      ({ name }) => name //.replace(/\./g, "\\\\.")
+      // .replace(/\./g, "\\\\.")
+      ({ name }) => name
     )
     .filter((pName) => pExtensions.includes(extname(pName)))
     .join("|");

package/src/git-primitives.mjs

@@ -0,0 +1,88 @@
+import { spawnSync } from "node:child_process";
+
+function stringifyOutStream(pError) {
+  if (pError instanceof Buffer) {
+    return pError.toString("utf8");
+  } else {
+    return pError;
+  }
+}
+
+function throwSpawnError(pError) {
+  if (pError.code === "ENOENT") {
+    throw new Error("git executable not found");
+  } else {
+    throw new Error(`internal spawn error: ${pError}`);
+  }
+}
+
+/**
+ *
+ * @param {string[]} pArguments
+ * @return {string}
+ * @throws {Error}
+ */
+function getGitResult(pArguments, pErrorMap, pSpawnFunction) {
+  const lGitResult = pSpawnFunction("git", pArguments, {
+    cwd: process.cwd(),
+    // eslint-disable-next-line node/no-process-env
+    env: process.env,
+  });
+
+  if (lGitResult.error) {
+    throwSpawnError(lGitResult.error);
+  }
+
+  if (lGitResult.status === 0) {
+    return stringifyOutStream(lGitResult.stdout);
+  } else {
+    throw new Error(
+      pErrorMap[lGitResult.status] ||
+        `internal git error: ${lGitResult.status} (${stringifyOutStream(
+          lGitResult.stderr
+        )})`
+    );
+  }
+}
+
+/**
+ *
+ * @returns {string}
+ * @throws {Error}
+ */
+export function getStatusShort(pSpawnFunction = spawnSync) {
+  const lErrorMap = {
+    129: `'${process.cwd()}' does not seem to be a git repository`,
+  };
+  return getGitResult(["status", "--porcelain"], lErrorMap, pSpawnFunction);
+}
+
+/**
+ *
+ * @param {string} pOldRevision the target to compare against (e.g. branch name, commit, tag etc)
+ * @return {string}
+ * @throws {Error}
+ */
+export function getDiffLines(pOldRevision, pSpawnFunction = spawnSync) {
+  const lErrorMap = {
+    128: `revision '${pOldRevision}' unknown `,
+    129: `'${process.cwd()}' does not seem to be a git repository`,
+  };
+  return getGitResult(
+    ["diff", pOldRevision, "--name-status"],
+    lErrorMap,
+    pSpawnFunction
+  );
+}
+/**
+ *
+ * @returns {string}
+ */
+export function getSHA1(pSpawnFunction = spawnSync) {
+  const lSha1Length = 40;
+
+  return getGitResult(["rev-parse", "HEAD"], {}, pSpawnFunction).slice(
+    0,
+    lSha1Length
+  );
+}

package/src/main.mjs

@@ -2,31 +2,26 @@ import {
   convertDiffLines,
   convertStatusLines,
 } from "./convert-to-change-object.mjs";
-import { getDiffLines, getStatusShort } from "./get-diff-lines.mjs";
+import { getDiffLines, getSHA1, getStatusShort } from "./git-primitives.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));
+/** @type {import("../types/watskeburt.js").getSHA} */
+export function getSHA() {
+  return getSHA1();
+}
+
+/** @type {import("../types/watskeburt.js").list} */
+export function list(pOldRevision, pOptions) {
+  const lOldRevision = pOldRevision || getSHA();
+  let lChanges = convertDiffLines(getDiffLines(lOldRevision));
+  const lOptions = pOptions || {};
 
-  if (!pOptions.trackedOnly) {
+  if (!lOptions.trackedOnly) {
     lChanges = lChanges.concat(
       convertStatusLines(getStatusShort()).filter(
         ({ changeType }) => changeType === "untracked"
       )
     );
   }
-  return format(lChanges, pOptions.outputType);
+  return format(lChanges, lOptions.outputType);
 }

package/src/version.mjs

@@ -0,0 +1 @@
+export const VERSION = "0.4.0";

package/types/watskeburt.d.ts

@@ -13,15 +13,55 @@ export type changeTypeType =
   | "ignored";
 
 export interface IChange {
+  /**
+   * name of the file
+   */
   name: string;
+  /**
+   * how the file was changed
+   */
   changeType: changeTypeType;
-  similarity?: Number;
+  /**
+   * if the file was renamed: what the old file's name was
+   */
   oldName?: string;
 }
 
 export type outputTypeType = "regex" | "json" | "object";
 
 export interface IOptions {
+  /**
+   * The type of output to deliver. Defaults to "object" - in which case
+   * the list function returns an IChange[] object
+   */
   outputType: outputTypeType;
+  /**
+   * When true _only_ takes already tracked files into account.
+   * When true also takes untracked files into account.
+   *
+   * Defaults to true.
+   */
   trackedOnly: boolean;
 }
+
+/**
+ * returns a list of files changed since pOldRevision.
+ *
+ * @param pOldRevision the revision against which to compare. E.g. a commit-hash,
+ *                 a branch or a tag. When not passed defaults to the _current_
+ *                 commit hash (if there's any)
+ * @param pOptions Options that influence how the changes are returned and that
+ *                 filter what is returned and
+ * @throws {Error}
+ */
+export function list(
+  pOldRevision?: string,
+  pOptions?: IOptions
+): IChange[] | string;
+
+/**
+ * Returns the SHA1 of the current HEAD
+ *
+ * @throws {Error}
+ */
+export function getSHA(): string;

package/src/get-diff-lines.mjs

@@ -1,51 +0,0 @@
-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);
-}