refactor(main)!: moves optional parameters to the options - BREAKING (#…

…44)

## Description

- removes the optional `pOldRevision` and `pNewRevision` parameters from
the main function
- adds `oldRevision` and `newRevision` attributes to the options object
passed to the main function that have the same function as the removed
parameters.

## Motivation and Context

This makes the interface less klunky to use - the parameters were both
optional and either one could be passed, which would result in calls
with the parameters that aren't relevant in the context as `null` like
`main(null, "somebranch")` or `main("develop", null {trackedOnly:
true})`.

## How Has This Been Tested?

- [x] green ci
- [x] updated automated non-regression tests

## Types of changes

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] Documentation only change
- [x] Refactor (non-breaking change which fixes an issue without
changing functionality)
- [ ] New feature (non-breaking change which adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)

.eslintrc.cjs

@@ -1,4 +1,3 @@
-/* eslint-disable unicorn/no-empty-file */
 module.exports = {
   root: true,
   ignorePatterns: ["coverage", "docs", "dist", "node_modules"],
@@ -17,6 +16,7 @@ module.exports = {
         "node/no-unsupported-features/es-syntax": "off",
         "import/no-relative-parent-imports": "off",
         "sort-imports": "off",
+        "unicorn/no-keyword-prefix": "off",
         "unicorn/prefer-node-protocol": "error",
         "unicorn/prefer-module": "error",
         "no-use-before-define": "off",

README.md

@@ -37,11 +37,11 @@ const lChangedFiles = await list("main");
 /** @type {import('watskeburt').IChange[]} */
 const lChangedFiles = await list("v0.6.1", "v0.7.1");
 
-// As a third parameter you can pass some options
-// (pass null as the second parameter if you only want to compare between
-// a revision and the working tree):
 /** @type {import('watskeburt').IChange[]|string} */
-const lChangedFiles = await list("main", null, {
+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)
 });
@@ -69,8 +69,7 @@ The array of changes this returns looks like this:
 
 ### :shell: cli
 
-For now there's also a simple command line interface (which works from node ^16.19 and
-node >=18.11).
+There's also a simple command line interface (which works from node >=18.11).
 
 ```shell
 # list all JavaScript-ish files changed since main in a regular expression

src/cli.ts

@@ -55,11 +55,11 @@ export async function cli(
       return;
     }
 
-    const lResult = await list(
-      lArguments.positionals[0],
-      lArguments.positionals[1],
-      lArguments.values,
-    );
+    const lResult = await list({
+      ...lArguments.values,
+      oldRevision: lArguments.positionals[0],
+      newRevision: lArguments.positionals[1],
+    });
     pOutStream.write(`${lResult}${EOL}`);
   } catch (pError: unknown) {
     pErrorStream.write(`${EOL}ERROR: ${(pError as Error).message}${EOL}${EOL}`);

src/main.spec.ts

@@ -29,15 +29,20 @@ describe("main - list & listSync ", () => {
 
   it("list (trackedOnly) returns an empty array when comparing current SHA, with current SHA", async () => {
     const lSHA = await getSHA();
-    const lResult = await list(lSHA, lSHA, {
+    const lResult = await list({
+      oldRevision: lSHA,
+      newRevision: lSHA,
       trackedOnly: true,
     });
     deepEqual(lResult, []);
   });
 
   it("list result contains the newly created untracked file when comparing current SHA, with current SHA", async () => {
     const lSHA = await getSHA();
-    const lResult = (await list(lSHA, lSHA)) as IChange[];
+    const lResult = (await list({
+      oldRevision: lSHA,
+      newRevision: lSHA,
+    })) as IChange[];
     deepEqual(
       lResult.filter(({ name }) => name === UNTRACKED_FILE_NAME),
       [

src/main.ts

@@ -4,16 +4,13 @@ import { parseStatusLines } from "./parse-status-lines.js";
 import * as primitives from "./git-primitives.js";
 import format from "./formatters/format.js";
 
-export async function list(
-  pOldRevision?: string,
-  pNewRevision?: string,
-  pOptions?: IOptions,
-): Promise<IChange[] | string> {
-  const lOldRevision: string = pOldRevision || (await primitives.getSHA());
+export async function list(pOptions?: IOptions): Promise<IChange[] | string> {
+  const lOldRevision: string =
+    pOptions?.oldRevision || (await primitives.getSHA());
   const lOptions: IOptions = pOptions || {};
 
   const [lDiffLines, lStatusLines] = await Promise.all([
-    primitives.getDiffLines(lOldRevision, pNewRevision),
+    primitives.getDiffLines(lOldRevision, pOptions?.newRevision),
     // to stay consistent with the use of trackedOnly below: negated condition
     // eslint-disable-next-line no-negated-condition
     !lOptions.trackedOnly ? primitives.getStatusShort() : "",

types/watskeburt.d.ts

@@ -29,12 +29,18 @@ export interface IChange {
 
 export type outputTypeType = "regex" | "json" | "object";
 
-export interface IFormatOptions {
+export interface IBaseOptions {
   /**
-   * The type of output to deliver. Defaults to "object" - in which case
-   * the listSync function returns an IChange[] object
+   * 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)
    */
-  outputType: "regex" | "json";
+  oldRevision?: string;
+  /**
+   * Newer revision against which to compare. Leave out or pass
+   * null 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.
@@ -44,59 +50,38 @@ export interface IFormatOptions {
   trackedOnly?: boolean;
 }
 
-export interface IInternalOptions {
+export interface IFormatOptions extends IBaseOptions {
   /**
    * The type of output to deliver. Defaults to "object" - in which case
    * the listSync function returns an IChange[] object
    */
-  outputType?: "object";
+  outputType: "regex" | "json";
+}
+
+export interface IInternalOptions extends IBaseOptions {
   /**
-   * When true _only_ takes already tracked files into account.
-   * When false also takes untracked files into account.
-   *
-   * Defaults to false.
+   * The type of output to deliver. Defaults to "object" - in which case
+   * the listSync function returns an IChange[] object
    */
-  trackedOnly?: boolean;
+  outputType?: "object";
 }
 
 export type IOptions = IFormatOptions | IInternalOptions;
 
 /**
- * returns promise of a list of files changed since pOldRevision.
+ * returns a promise of 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 pNewRevision Newer revision against which to compare. Leave out or pass
- *                 null when you want to compare against the working tree
- * @param pOptions Options that influence how the changes are returned and that
- *                 filter what is returned and
  * @throws {Error}
  */
-export function list(
-  pOldRevision?: string,
-  pNewRevision?: string,
-  pOptions?: IInternalOptions,
-): Promise<IChange[]>;
+export function list(pOptions?: IInternalOptions): Promise<IChange[]>;
 
 /**
- * returns promise a list of files changed since pOldRevision, formatted into a
- * string as a pOptions.outputType
+ * returns a promise of a list of files changed since pOldRevision, formatted
+ * into a string as a pOptions.outputType
  *
- * @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 pNewRevision Newer revision against which to compare. Leave out or pass
- *                 null when you want to compare against the working tree
- * @param pOptions Options that influence how the changes are returned and that
- *                 filter what is returned and
  * @throws {Error}
  */
-export function list(
-  pOldRevision?: string,
-  pNewRevision?: string,
-  pOptions?: IFormatOptions,
-): Promise<string>;
+export function list(pOptions?: IFormatOptions): Promise<string>;
 
 /**
  * Returns the SHA1 of the current HEAD