watskeburt 0.2.0 → 0.3.0

package/README.md

@@ -1,45 +1,88 @@
 # watskeburt
 
-get git changed files & their statuses 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: in the process of getting 'production ready'. It's automatically
   tested + it's using itself - but a bunch of static analysis and a bit of
   automation still needs be added.
-- Interface is stable-ish, but can can change until 1.0.0 is published
+- :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>
 
 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
+-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",
+    similarity: 66,
+  },
+  { 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

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

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "watskeburt",
-  "version": "0.2.0",
-  "description": "list files changed since a git reference",
+  "version": "0.3.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": "dist/cjs-bundle.js",
   "module": "src/main.mjs",
+  "sideEffects": false,
   "exports": {
     ".": [
       {
@@ -25,8 +43,34 @@
     "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"
+  },
+  "engines": {
+    "node": "^12.20||^14||>=16"
+  },
   "scripts": {
-    "build": "esbuild src/main.mjs --format=cjs --target=node12 --platform=node --bundle --global-name=wkbtcjs --minify --outfile=dist/cjs-bundle.js",
+    "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",
     "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",
@@ -39,23 +83,19 @@
     "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",
+    "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": "run-s clean build 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",
-    "esbuild": "^0.14.48",
-    "mocha": "^10.0.0",
-    "npm-run-all": "^4.1.5"
+    "version": "npm-run-all --sequential clean build lint depcruise:graph scm:stage"
   },
-  "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,20 +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>")
+  .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()));
+    console.log(list(program.args[0], program.opts()));
   } catch (pError) {
-    console.error(pError);
+    console.error(`ERROR: ${pError.message}`);
   }
 } else {
   program.help();

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";
 }
 

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,24 +2,12 @@ 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").list} */
+export function list(pOldRevision, pOptions) {
+  let lChanges = convertDiffLines(getDiffLines(pOldRevision));
   const lOptions = pOptions || {};
 
   if (!lOptions.trackedOnly) {
@@ -31,3 +19,8 @@ export function convert(pOldThing, pOptions) {
   }
   return format(lChanges, lOptions.outputType);
 }
+
+/** @type {import("../types/watskeburt.js").getSHA} */
+export function getSHA() {
+  return getSHA1();
+}

package/src/version.mjs

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

package/types/watskeburt.d.ts

@@ -13,15 +13,58 @@ export type changeTypeType =
   | "ignored";
 
 export interface IChange {
+  /**
+   * name of the file
+   */
   name: string;
+  /**
+   * how the file was changed
+   */
   changeType: changeTypeType;
+  /**
+   * if the file was renamed: the % of similarity (range: 0 - 100)
+   */
   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.
+ * @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);
-}