watskeburt 3.0.0 → 4.0.0

package/README.md

@@ -2,21 +2,6 @@
 
 Get changed files & their statuses since any git _revision_
 
-## what's this do?
-
-A micro-lib to retrieve an array of file names that were changed since a
-revision. Also sports a cli for use outside of JavaScript c.s.
-
-## why?
-
-I needed something simple and robust to support some upcoming features in
-[dependency-cruiser](https://github.com/sverweij/dependency-cruiser) and to
-run standalone to use _in combination_ with dependency-cruiser.
-
-There are a few specialized packages like this on npm, but it seems they've
-fallen out of maintenance. More generic packages are still maintained,
-but for just this simple usage they're a bit overkill.
-
 ## :construction_worker: usage
 
 ### :scroll: API
@@ -30,20 +15,23 @@ console.log(await getSHA());
 // list all files that differ between 'main' and the current revision (including
 // files not staged for commit and files not under revision control)
 /** @type {import('watskeburt').IChange[]} */
-const lChangedFiles = await list("main");
+const lChangedFiles = await list({ oldRevision: "main" });
 
 // list all files that differ between 'v0.6.1' and 'v0.7.1' (by definition
 // won't include files staged for commit and/ or not under revision control)
 /** @type {import('watskeburt').IChange[]} */
-const lChangedFiles = await list("v0.6.1", "v0.7.1");
+const lChangedFiles = await list({
+  oldRevision: "v0.6.1",
+  newRevision: "v0.7.1",
+});
 
+// list all files that differ between 'main' and the current revision
+// (excluding files not staged for commit)
 /** @type {import('watskeburt').IChange[]|string} */
 const lChangedFiles = await list({
   oldRevision: "main",
-  // this compares the working tree with the oldRevision. If you want to compare
-  // to another branch or revision you can pass that in a `newRevision` field
   trackedOnly: false, // when set to true leaves out files not under revision control
-  outputType: "object", // other options: "json" and "regex" (as used in the CLI)
+  outputType: "json", // options: "object", "json" and "regex"
 });
 ```
 
@@ -53,23 +41,23 @@ The array of changes this returns looks like this:
 [
   {
     name: "doc/cli.md",
-    changeType: "modified",
+    type: "modified",
   },
   {
     name: "test/thing.spec.mjs",
-    changeType: "renamed",
+    type: "renamed",
     oldName: "test/old-thing.spec.mjs",
   },
   {
     name: "src/not-tracked-yet.mjs",
-    changeType: "untracked",
+    type: "untracked",
   },
 ];
 ```
 
 ### :shell: cli
 
-There's also a simple command line interface (which works from node >=18.11).
+Works with node >=18.11
 
 ```shell
 # list all JavaScript-ish files changed since main in a regular expression
@@ -77,19 +65,18 @@ $ npx watskeburt main
 ^(src/cli[.]mjs|src/formatters/regex[.]mjs|src/version[.]mjs)$
 ```
 
-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` and `--reaches` filters of dependency-cruiser.
+This emits a regex that contains all changed files that could be
+source files in the JavaScript ecosystem (.js, .mjs, .ts, .tsx ...). It can
+be used in e.g. dependency-cruiser's `--focus` and `--reaches` filters.
 
-The JSON output (which looks a lot like the array above) is unfiltered and
-also contains other extensions.
+The JSON output (= the array above, serialized) also contains other extensions.
 
 ```
 Usage: watskeburt [options] [old-revision] [new-revision]
 
 lists files & their statuses since [old-revision] or between [old-revision] and [new-revision].
 
--> When you don't pass a revision at all old-revision defaults to the current one.
+-> When you don't pass a revision old-revision defaults to the current one.
 
 Options:
   -T, --outputType <type>  what format to emit (choices: "json", "regex", default: "regex")
@@ -98,11 +85,19 @@ Options:
   -h, --help               display help for command
 ```
 
+## why?
+
+I needed something robust to support caching in
+[dependency-cruiser](https://github.com/sverweij/dependency-cruiser) and to
+run standalone to use _in combination_ with dependency-cruiser.
+
+A few specialized packages like this existed, but they had fallen out of
+maintenance. More generic packages still were maintained, but for my use
+case they were overkill.
+
 ## 🇳🇱 what does 'watskeburt' mean?
 
 Wazzup.
 
 _watskeburt_ is a fast pronunciation of the Dutch "wat is er gebeurd?"
-(_what has happened?_) or "wat er is gebeurd" (_what has happened_). It's
-also the title of a song by the Dutch band "De Jeugd van Tegenwoordig"
-(_Youth these days_).
+(_what has happened?_) or "wat er is gebeurd" (_what has happened_).

package/dist/cli.js

@@ -6,7 +6,7 @@ const HELP_MESSAGE = `Usage: watskeburt [options] [old-revision] [new-revision]
 
 lists files & their statuses since [old-revision] or between [old-revision] and [new-revision].
 
--> When you don't pass a revision at all old-revision defaults to the current one.
+-> When you don't pass a revision old-revision defaults to the current one.
 
 Options:
   -T, --outputType <type>  what format to emit (choices: "json", "regex", default: "regex")

package/dist/format/format.js

@@ -0,0 +1,9 @@
+import formatAsRegex from "./regex.js";
+import formatAsJSON from "./json.js";
+const OUTPUT_TYPE_TO_FUNCTION = new Map([
+  ["regex", formatAsRegex],
+  ["json", formatAsJSON],
+]);
+export function format(pChanges, pOutputType) {
+  return OUTPUT_TYPE_TO_FUNCTION.get(pOutputType)(pChanges);
+}

package/dist/{formatters → format}/json.js

@@ -1,4 +1,4 @@
 const INDENT = 2;
-export default function formatToJSON(pChanges) {
+export default function formatAsJSON(pChanges) {
   return JSON.stringify(pChanges, null, INDENT);
 }

package/dist/{formatters → format}/regex.js

@@ -25,7 +25,7 @@ const DEFAULT_CHANGE_TYPES = new Set([
   "copied",
   "untracked",
 ]);
-export default function formatToRegex(
+export default function formatAsRegex(
   pChanges,
   pExtensions = DEFAULT_EXTENSIONS,
   pChangeTypes = DEFAULT_CHANGE_TYPES,
@@ -33,7 +33,7 @@ export default function formatToRegex(
   const lChanges = pChanges
     .filter(
       (pChange) =>
-        pChangeTypes.has(pChange.changeType) &&
+        pChangeTypes.has(pChange.type) &&
         pExtensions.has(extname(pChange.name)),
     )
     .map(({ name }) => name.replace(/\\/g, "\\\\").replace(/\./g, "[.]"))

package/dist/main.js

@@ -1,7 +1,6 @@
 import { parseDiffLines } from "./parse-diff-lines.js";
 import { parseStatusLines } from "./parse-status-lines.js";
 import * as primitives from "./git-primitives.js";
-import format from "./formatters/format.js";
 export async function list(pOptions) {
   const lOldRevision = pOptions?.oldRevision || (await primitives.getSHA());
   const lOptions = pOptions || {};
@@ -13,10 +12,14 @@ export async function list(pOptions) {
   if (!lOptions.trackedOnly) {
     lChanges = lChanges.concat(
       parseStatusLines(lStatusLines).filter(
-        ({ changeType }) => changeType === "untracked",
+        ({ type: changeType }) => changeType === "untracked",
       ),
     );
   }
+  if (!lOptions.outputType) {
+    return lChanges;
+  }
+  const { format } = await import("./format/format.js");
   return format(lChanges, lOptions.outputType);
 }
 export function getSHA() {

package/dist/parse-diff-lines.js

@@ -7,15 +7,15 @@ export function parseDiffLines(pString) {
     .split(EOL)
     .filter(Boolean)
     .map(parseDiffLine)
-    .filter(({ name, changeType }) => Boolean(name) && Boolean(changeType));
+    .filter(
+      ({ name, type: changeType }) => Boolean(name) && Boolean(changeType),
+    );
 }
 export function parseDiffLine(pString) {
   const lMatchResult = pString.match(DIFF_NAME_STATUS_LINE_PATTERN);
   const lReturnValue = {};
   if (lMatchResult?.groups) {
-    lReturnValue.changeType = changeChar2ChangeType(
-      lMatchResult.groups.changeType,
-    );
+    lReturnValue.type = changeChar2ChangeType(lMatchResult.groups.changeType);
     if (lMatchResult.groups.newName) {
       lReturnValue.name = lMatchResult.groups.newName;
       lReturnValue.oldName = lMatchResult.groups.name;

package/dist/parse-status-lines.js

@@ -7,7 +7,9 @@ export function parseStatusLines(pString) {
     .split(EOL)
     .filter(Boolean)
     .map(parseStatusLine)
-    .filter(({ name, changeType }) => Boolean(name) && Boolean(changeType));
+    .filter(
+      ({ name, type: changeType }) => Boolean(name) && Boolean(changeType),
+    );
 }
 export function parseStatusLine(pString) {
   const lMatchResult = pString.match(DIFF_SHORT_STATUS_LINE_PATTERN);
@@ -19,7 +21,7 @@ export function parseStatusLine(pString) {
     const lUnStagedChangeType = changeChar2ChangeType(
       lMatchResult.groups.unStagedChangeType,
     );
-    lReturnValue.changeType =
+    lReturnValue.type =
       lStagedChangeType === "unmodified"
         ? lUnStagedChangeType
         : lStagedChangeType;

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "3.0.0";
+export const VERSION = "4.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watskeburt",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "List files changed since a git revision",
   "keywords": [
     "git",

package/types/watskeburt.d.ts

@@ -1,4 +1,4 @@
-export type changeTypeType =
+export type changeType =
   | "added"
   | "copied"
   | "deleted"
@@ -20,63 +20,59 @@ export interface IChange {
   /**
    * how the file was changed
    */
-  changeType: changeTypeType;
+  type: changeType;
   /**
    * if the file was renamed: what the old file's name was
    */
   oldName?: string;
 }
 
-export type outputTypeType = "regex" | "json" | "object";
+export type outputTypeType = "regex" | "json";
 
 export interface IBaseOptions {
   /**
-   * 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)
+   * The revision against which to compare. When not passed defaults to the
+   * _current_ commit hash (if there's any)
    */
   oldRevision?: string;
   /**
-   * Newer revision against which to compare. Leave out or pass
-   * null when you want to compare against the working tree
+   * Newer revision against which to compare. Leave out when you want to
+   * compare against the working tree
    */
   newRevision?: string;
   /**
-   * When true _only_ takes already tracked files into account.
-   * When false also takes untracked files into account.
-   *
-   * Defaults to false.
+   * When true only takes already tracked files into account.
+   * When false also takes untracked files into account (default)
    */
   trackedOnly?: boolean;
 }
 
 export interface IFormatOptions extends IBaseOptions {
   /**
-   * The type of output to deliver. Defaults to "object" - in which case
-   * the listSync function returns an IChange[] object
+   * The type of output to deliver.
    */
   outputType: "regex" | "json";
 }
 
 export interface IInternalOptions extends IBaseOptions {
   /**
-   * The type of output to deliver. Defaults to "object" - in which case
-   * the listSync function returns an IChange[] object
+   * The type of output to deliver. undefined/ left out
+   * the outputType defaults to a list of `IChange`s
    */
-  outputType?: "object";
+  outputType?: undefined;
 }
 
 export type IOptions = IFormatOptions | IInternalOptions;
 
 /**
- * returns a promise of a list of files changed since pOldRevision.
+ * promises a list of files changed since pOldRevision.
  *
  * @throws {Error}
  */
 export function list(pOptions?: IInternalOptions): Promise<IChange[]>;
 
 /**
- * returns a promise of a list of files changed since pOldRevision, formatted
+ * promises a list of files changed since pOldRevision, formatted
  * into a string as a pOptions.outputType
  *
  * @throws {Error}
@@ -84,7 +80,7 @@ export function list(pOptions?: IInternalOptions): Promise<IChange[]>;
 export function list(pOptions?: IFormatOptions): Promise<string>;
 
 /**
- * Returns the SHA1 of the current HEAD
+ * Promises the SHA1 of the current HEAD
  *
  * @throws {Error}
  */

package/dist/formatters/format.js

@@ -1,12 +0,0 @@
-import formatToRegex from "./regex.js";
-import formatToJSON from "./json.js";
-const identity = (pX) => pX;
-const OUTPUT_TYPE_TO_FUNCTION = new Map([
-  ["regex", formatToRegex],
-  ["json", formatToJSON],
-]);
-export default function format(pChanges, pOutputType) {
-  return (OUTPUT_TYPE_TO_FUNCTION.get(pOutputType ?? "unknown") || identity)(
-    pChanges,
-  );
-}