chore: update CI workflow to use latest action versions and improve caching strategy; enhance fuzzy search functionality with validation and new options

Author: Aristide021

.github/workflows/ci.yml

@@ -16,23 +16,23 @@ jobs:
       matrix:
         node-version: [18.x, 20.x]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Cache npm modules
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-node-
       - name: Cache node_modules
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: node_modules
           key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-node-modules-
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm ci
@@ -60,20 +60,22 @@ jobs:
       issues: write       # for the "fail" plugin
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0   # full history needed for tagging
       - name: Configure npm for semantic-release
         run: |
           echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
       - name: Use Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: '20.x'
           registry-url: 'https://registry.npmjs.org'
       - run: npm ci
       - name: Run semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN:   ${{ secrets.NPM_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npm run release 

.releaserc.json

@@ -5,7 +5,7 @@
     "@semantic-release/release-notes-generator",
     ["@semantic-release/changelog", {"changelogFile": "CHANGELOG.md"}],
     ["@semantic-release/npm", {"npmPublish": true}],
-    ["@semantic-release/github", {"assets": "dist/**", "labels": ["bug", "release"]}],
+    ["@semantic-release/github", {"labels": ["bug", "release"]}],
     ["@semantic-release/git", {
       "assets": ["package.json", "CHANGELOG.md"],
       "message": "chore(release): ${nextRelease.version} [skip ci]"

README.md

@@ -7,7 +7,7 @@
 
 **Human-friendly, temporal & intent-driven wrapper around `git log`.**
 
-TGQ provides natural-language-style flags, fuzzy search, glob path filters, named presets, and structured exports (table, JSON, CSV, Markdown).
+Git-When provides natural-language-style flags, fuzzy search, glob path filters, named presets, and structured exports (table, JSON, CSV, Markdown).
 
 ---
 
@@ -45,13 +45,19 @@ npm install -g .
 • Dates passed to `--when` are interpreted in UTC by default (e.g. `2023-05-07` → `2023-05-07T00:00:00Z`). If your local timezone is behind UTC, a shorter-than-expected time window may appear. Always use ISO (`YYYY-MM-DD..YYYY-MM-DD`) or natural ranges (`today`, `last-week`).
 
 ### Glob Pattern Gotchas
-• Your shell may expand globs before TGQ sees them. Quote patterns (e.g. `--path="src/**/*.js"`) to avoid unintended matches.
+• Your shell may expand globs before Git-When sees them. Quote patterns (e.g. `--path="src/**/*.js"`) to avoid unintended matches.
 
 ### Tips for Large Repositories
 - Use `--limit <n>` to stop after the first _n_ commits.  
 - Push filtering into Git: `--author`, `--grep`, and `--path` reduce data before JS processing.  
 - Combine flags: `git-when --who Alice --limit 50 --format=json` for a quick API export.
 
+### Fuzzy Search Tips
+- **Default threshold**: 0.4 (balanced between strict and lenient)
+- **Stricter matching**: Use `--fuzzy-level=0.1` to `0.3` for more precise results
+- **Lenient matching**: Use `--fuzzy-level=0.6` to `0.8` to catch more variations
+- **Exact matching**: Use Git's native `--author` and `--grep` flags instead of `--who`/`--what`
+
 ### Exit Codes
 - **0**: Successful execution (even if no commits match).  
 - **1**: An error occurred, such as invalid flags, invalid date ranges, malformed presets, or Git errors (e.g., not a Git repository).
@@ -62,11 +68,17 @@ npm install -g .
   "perf-q2": {
     "when": "2025-02-01..2025-02-28",
     "who": "Bob",
-    "what": "perf"
+    "what": "perf",
+    "fuzzyThreshold": 0.3
   },
   "alice-week": {
     "when": "last-week",
     "who": "Alice"
+  },
+  "strict-search": {
+    "who": "john",
+    "fuzzyThreshold": 0.1,
+    "format": "json"
   }
 }
 ```
@@ -89,17 +101,18 @@ git-when [preset] [options]
 
 - **Preset**: If the first argument matches a saved preset name, its filters load automatically.
 - **Options**:
-  - `-w`, `--when <range>`     Date range (e.g. `2023-01..2023-03`, `last-week`, `today`)
-  - `-a`, `--who <author>`     Fuzzy author name
-  - `-k`, `--what <keyword>`   Fuzzy commit message keyword
-  - `-p`, `--path <glob>`      Glob file path (e.g. `src/**/*.js`, `*.md`)
-  - `-f`, `--format <type>`    Output format: `table` (default), `json`, `csv`, `md`
-  - `-s`, `--save <name>`      Save current filters as preset `<name>`
-  - `-n`, `--limit <number>`   Limit the number of commits fetched
-  - `--list-presets`           List saved preset names
-  - `--delete-preset <name>`   Remove a saved preset
-  - `--help`                   Show this help
-  - `--version`                Show version
+  - `-w`, `--when <range>`        Date range (e.g. `2023-01..2023-03`, `last-week`, `today`)
+  - `-a`, `--who <author>`        Fuzzy author name
+  - `-k`, `--what <keyword>`      Fuzzy commit message keyword
+  - `-p`, `--path <glob>`         Glob file path (e.g. `src/**/*.js`, `*.md`)
+  - `-f`, `--format <type>`       Output format: `table` (default), `json`, `csv`, `md`
+  - `--fuzzy-level <0.0-1.0>`     Fuzzy search threshold (default: 0.4, lower = more strict)
+  - `-s`, `--save <name>`         Save current filters as preset `<name>`
+  - `-n`, `--limit <number>`      Limit the number of commits fetched
+  - `--list-presets`              List saved preset names
+  - `--delete-preset <name>`      Remove a saved preset
+  - `--help`                      Show this help
+  - `--version`                   Show version
 
 ---
 
@@ -128,7 +141,12 @@ git-when --what="fix" -w="today" --format=json > fixes-today.json
 # 5. Manage presets
 git-when --list-presets
 git-when --delete-preset weekly-bob
-# 6. Batch Markdown output
+
+# 6. Fine-tune fuzzy search sensitivity
+git-when --who="john" --fuzzy-level=0.2  # Stricter matching
+git-when --who="john" --fuzzy-level=0.8  # More lenient matching
+
+# 7. Batch Markdown output
 git-when --when="last-week" --format=markdown --batch-size=50
 ```
 
@@ -137,9 +155,9 @@ git-when --when="last-week" --format=markdown --batch-size=50
 ## Features
 
 - **Natural flags** (`--when`, `--who`, `--what`, `--path`)
-- **Fuzzy search** on authors and commit messages via [`fuse.js`](https://github.com/krisk/Fuse)
+- **Configurable fuzzy search** on authors and commit messages via [`fuse.js`](https://github.com/krisk/Fuse) with adjustable threshold
 - **Glob file filtering** via [`minimatch`](https://github.com/isaacs/minimatch)
-- **Named presets** for saving and reusing common filters
+- **Named presets** for saving and reusing common filters with validation
 - **Structured output**: ASCII table, JSON, CSV, or Markdown
 - **Cross-platform**: Node.js CLI (macOS, Linux, Windows)
 

lib/filters.js

@@ -10,19 +10,21 @@ const minimatch = mm.minimatch || mm.default || mm;
  * @param {string} [opts.who]
  * @param {string} [opts.what]
  * @param {string} [opts.path]
+ * @param {number} [opts.fuzzyThreshold] - Fuzzy search threshold (0.0-1.0, default: 0.4)
  */
 function applyFilters(commits, opts = {}) {
   let result = commits;
+  const fuzzyThreshold = opts.fuzzyThreshold !== undefined ? opts.fuzzyThreshold : 0.4;
 
   // Fuzzy match on author
   if (opts.who) {
-    const fuse = new Fuse(result, { keys: ['author'], threshold: 0.4 });
+    const fuse = new Fuse(result, { keys: ['author'], threshold: fuzzyThreshold });
     result = fuse.search(opts.who).map(r => r.item);
   }
 
   // Fuzzy match on commit message
   if (opts.what) {
-    const fuse = new Fuse(result, { keys: ['message'], threshold: 0.4 });
+    const fuse = new Fuse(result, { keys: ['message'], threshold: fuzzyThreshold });
     result = fuse.search(opts.what).map(r => r.item);
   }
 

lib/index.js

@@ -1,6 +1,6 @@
 const path = require('path');
 const pkg = require(path.join(__dirname, '..', 'package.json'));
-const { loadPresets, savePreset, deletePreset, listPresets } = require('./presets');
+const { loadPresets, savePreset, deletePreset, listPresets, validatePresetOptions } = require('./presets');
 const { parseDateRange } = require('./utils');
 const { fetchCommits, streamCommits } = require('./gitClient');
 const { applyFilters } = require('./filters');
@@ -23,6 +23,7 @@ Options:
   -k, --what <keyword>   Commit message keyword (fuzzy)
   -p, --path <glob>      File path glob (e.g. 'src/**/*.js')
   -f, --format <type>    Output format: table, json, csv, md
+  --fuzzy-level <0.0-1.0> Fuzzy search threshold (default: 0.4)
   --batch-size <num>     For pretty formats, render N commits per batch
   -s, --save <name>      Save current flags as preset
   -o, --overwrite        Overwrite existing preset without warning
@@ -97,6 +98,7 @@ Options:
         if (arg.startsWith('--path=')) { optsEdit.path  = arg.slice('--path='.length);  continue; }
         if (arg.startsWith('--format=')){ optsEdit.format= arg.slice('--format='.length);continue; }
         if (arg.startsWith('--limit=')){ optsEdit.limit = parseInt(arg.slice('--limit='.length), 10); continue; }
+        if (arg.startsWith('--fuzzy-level=')){ optsEdit.fuzzyThreshold = parseFloat(arg.slice('--fuzzy-level='.length)); continue; }
         switch (arg) {
           case '-w': case '--when': optsEdit.when = args[++i]; break;
           case '-a': case '--who':  optsEdit.who   = args[++i]; break;
@@ -110,11 +112,25 @@ Options:
               process.exit(1);
             }
             break;
+          case '--fuzzy-level':
+            optsEdit.fuzzyThreshold = parseFloat(args[++i]);
+            if (isNaN(optsEdit.fuzzyThreshold) || optsEdit.fuzzyThreshold < 0 || optsEdit.fuzzyThreshold > 1) {
+              console.error('Error: --fuzzy-level must be a number between 0.0 and 1.0');
+              process.exit(1);
+            }
+            break;
           default:
             console.error(`Unknown option during edit: ${arg}`);
             process.exit(1);
         }
       }
+      // Validate the edited preset before saving
+      try {
+        validatePresetOptions(optsEdit);
+      } catch (e) {
+        console.error(`Error: ${e.message}`);
+        process.exit(1);
+      }
       savePreset(name, optsEdit);
       console.log(`Updated preset '${name}'.`);
       process.exit(0);
@@ -175,6 +191,14 @@ Options:
           }
           continue;
         }
+        if (arg.startsWith('--fuzzy-level=')) {
+          opts.fuzzyThreshold = parseFloat(arg.slice('--fuzzy-level='.length));
+          if (isNaN(opts.fuzzyThreshold) || opts.fuzzyThreshold < 0 || opts.fuzzyThreshold > 1) {
+            console.error('Error: --fuzzy-level must be a number between 0.0 and 1.0');
+            process.exit(1);
+          }
+          continue;
+        }
         switch (arg) {
           case '-w':
           case '--when':
@@ -215,6 +239,13 @@ Options:
               process.exit(1);
             }
             break;
+          case '--fuzzy-level':
+            opts.fuzzyThreshold = parseFloat(args[++i]);
+            if (isNaN(opts.fuzzyThreshold) || opts.fuzzyThreshold < 0 || opts.fuzzyThreshold > 1) {
+              console.error('Error: --fuzzy-level must be a number between 0.0 and 1.0');
+              process.exit(1);
+            }
+            break;
           default:
             console.error(`Unknown option: ${arg}`);
             printUsage();
@@ -230,35 +261,54 @@ Options:
         process.exit(1);
       }
       const name = opts.save;
-      delete opts.save;
-      delete opts.overwrite;
-      savePreset(name, opts);
+      const presetOpts = { ...opts };
+      delete presetOpts.save;
+      delete presetOpts.overwrite;
+      
+      // Validate the preset before saving
+      try {
+        validatePresetOptions(presetOpts);
+      } catch (e) {
+        console.error(`Error: ${e.message}`);
+        process.exit(1);
+      }
+      
+      savePreset(name, presetOpts);
       console.log(`Saved preset '${name}'.`);
       process.exit(0);
     }
 
     // Parse date range
-    let since, until;
+    let since, until, isShorthand;
     try {
       const range = opts.when || '';
-      ({ since, until } = parseDateRange(range));
+      ({ since, until, isShorthand } = parseDateRange(range));
     } catch (e) {
       console.error('Invalid date range:', e.message);
       process.exit(1);
     }
 
-    // Determine git log date filters: raw strings for explicit ranges, ISO for parsed dates
+    // Determine git log date filters: optimize for Git when possible
     let gitSince, gitUntil;
-    if (opts.when && opts.when.includes('..')) {
+    let needsJSDateFiltering = false;
+
+    if (isShorthand) {
+      // For shorthand dates, pass them directly to Git for optimal performance
+      gitSince = since ? since.toISOString().replace(/\.\d+Z$/, 'Z') : undefined;
+      gitUntil = until ? until.toISOString().replace(/\.\d+Z$/, 'Z') : undefined;
+      needsJSDateFiltering = false; // Git handles the filtering
+    } else if (opts.when && opts.when.includes('..')) {
       const parts = opts.when.split('..');
       // Use full UTC date-times to avoid local-timezone exclusion
       const start = parts[0];
       const end = parts[1];
       gitSince = `${start}T00:00:00+00:00`;
       gitUntil = `${end}T23:59:59+00:00`;
+      needsJSDateFiltering = false; // Git handles explicit ranges
     } else {
       gitSince = since ? since.toISOString().replace(/\.\d+Z$/, 'Z') : undefined;
       gitUntil = until ? until.toISOString().replace(/\.\d+Z$/, 'Z') : undefined;
+      needsJSDateFiltering = false; // Git can handle single dates too
     }
 
     // Streaming NDJSON output: emit each commit as a JSON line and exit
@@ -285,10 +335,12 @@ Options:
       }
       process.exit(1);
     }
-    // If we used an explicit '..' range, Git already filtered by date; otherwise, apply JS date filtering
+    // Apply date filtering only if Git didn't handle it completely
     let dated = commits;
-    if (since) dated = dated.filter(c => new Date(c.date) >= since);
-    if (until) dated = dated.filter(c => new Date(c.date) <= until);
+    if (needsJSDateFiltering) {
+      if (since) dated = dated.filter(c => new Date(c.date) >= since);
+      if (until) dated = dated.filter(c => new Date(c.date) <= until);
+    }
     const filtered = applyFilters(dated, opts);
 
     // Batch-size for pretty formats (table, CSV, Markdown)