improve search parameter when working with dates

hkong-mitre · hkong-mitre · commit d5cd6a6ce374 · 2025-09-30T09:32:10.000-04:00
diff --git a/src/adapters/search/OpensearchDatetimeUtils.test.unit.ts b/src/adapters/search/OpensearchDatetimeUtils.test.unit.ts
@@ -0,0 +1,24 @@
+import { describe, test, expect } from '@jest/globals';
+import { toSearchDateDslString } from './OpensearchDatetimeUtils';
+import { IsoDate, IsoDatetime } from '../../common/IsoDate/IsoDatetime';
+
+
+describe('OpensearchDatetimeUtils.toSearchDateDslString()', () => {
+  const testcases = [
+    { input: '2025-03-01T12:34:56Z', expected: '2025-03-01T12:34:56Z' },
+    { input: '2025-03-01', expected: '2025-03-01||/d' },
+    { input: '2025-03', expected: '2025-03||/M' },
+    { input: '2025', expected: '2025||/y' },
+  ];
+
+  testcases.forEach(({ input, expected }) => {
+    test(`throws for "${input}"`, () => {
+      let iso = (input.length > 10) ? IsoDatetime.parse(input) : IsoDate.parse(input);
+      expect(toSearchDateDslString(iso)).toBe(expected);
+    });
+  });
+
+  test('throws on invalid date string', () => {
+    expect(() => IsoDate.parse('2025-13')).toThrow();
+  });
+});
diff --git a/src/adapters/search/OpensearchDatetimeUtils.ts b/src/adapters/search/OpensearchDatetimeUtils.ts
@@ -0,0 +1,25 @@
+/**
+ *  OpenSearch and ElasticSearch both use additional symbols in the Search DSL to make ISO 8601 representations 
+ *  even more precise for years, months, days.  This utility class simplifies that
+ */
+
+import { IsoDate, IsoDatetime } from '../../common/IsoDate/IsoDatetime.js';
+
+export const toSearchDateDslString = (iso: IsoDate | IsoDatetime): string => {
+  if (iso.isMonth()) {
+    // isoDate is a month
+    return `${iso.toString()}||/M`;
+  }
+  else if (iso.isYear()) {
+    // isoDate is a year
+    return `${iso.toString()}||/y`;
+  } 
+  else if (iso.isDate()) {
+    // isoDate is a year
+    return `${iso.toString()}||/d`;
+  }
+  else {
+    // all other instances will be the original string
+    return iso.toString();
+  }
+};
diff --git a/src/common/IsoDate/IsoDate.test.unit.ts b/src/common/IsoDate/IsoDate.test.unit.ts
@@ -23,6 +23,9 @@ describe('IsoDate.parse – valid inputs', () => {
     expect(d.month).toBe(1);
     expect(d.day).toBe(1);
     expect(d.toString()).toBe('2025-01-01');
+    expect(d.isDate()).toBeTruthy();
+    expect(d.isMonth()).toBeFalsy();
+    expect(d.isYear()).toBeFalsy()
   });
 
   test('year‑month', () => {
@@ -33,6 +36,9 @@ describe('IsoDate.parse – valid inputs', () => {
     expect(d.month).toBe(1);
     expect(d.day).toBeUndefined();
     expect(d.toString()).toBe('2025-01');
+    expect(d.isDate()).toBeFalsy();
+    expect(d.isMonth()).toBeTruthy();
+    expect(d.isYear()).toBeFalsy()
   });
 
   test('year only', () => {
@@ -43,6 +49,9 @@ describe('IsoDate.parse – valid inputs', () => {
     expect(d.month).toBeUndefined();
     expect(d.day).toBeUndefined();
     expect(d.toString()).toBe('2025');
+    expect(d.isDate()).toBeFalsy();
+    expect(d.isMonth()).toBeFalsy();
+    expect(d.isYear()).toBeTruthy()
   });
 
   test('leap‑year February 29', () => {
diff --git a/src/common/IsoDate/IsoDate.ts b/src/common/IsoDate/IsoDate.ts
@@ -1,10 +1,12 @@
 /**
  * IsoDate – a lightweight class for representing calendar dates.
-*
+ *
  * Supported input formats:
- *   - YYYY-MM-DD   (e.g., 2025-01-01)
- *   - YYYY-MM      (e.g., 2025-01)
- *   - YYYY         (e.g., 2025)
+ *   - YYYY-MM-DD   (e.g., 2025-01-01, equivalent to 2025-01-01T00:00:00.000Z/2025-01-01T23:59:59.999Z)
+ *   - YYYY-MM      (e.g., 2025-01, equivalent to 2025-01-01T00:00:00.000Z/2025-01-31T23:59:59.999Z)
+ *   - YYYY         (e.g., 2025, equivalent to 2025-01-01T00:00:00.000Z/2025-12-31T23:59:59.999Z)
+ * 
+ * As shown in the example above, all IsoDate is assumed to be UTC (i.e., timezone = 'Z')
  * 
  * Note we do not support (even though it is allowed by ISO 8601)
  *  - "compact date" (i.e., YYYYMMDD)
@@ -111,6 +113,22 @@ export class IsoDate {
     return IsoDate.isLeapYear(this.year);
   }
 
+  /** Return true if the stored year is a leap year. */
+  public isYear(): boolean {
+    return this.toString().length === 4;
+  }
+
+  /** Return true if the stored year is a leap year. */
+  public isMonth(): boolean {
+    return this.toString().length === 7;
+  }
+
+  /** Return true if the stored year is a leap year. */
+  public isDate(): boolean {
+    return this.toString().length === 10;
+  }
+
+
   /** Normalized string representation. */
   public toString(): string {
     const y = String(this.year).padStart(4, '0');
diff --git a/src/common/IsoDate/IsoDatetime.test.unit.ts b/src/common/IsoDate/IsoDatetime.test.unit.ts
@@ -1,3 +1,14 @@
+/**
+ * Unit tests for IsoDatetime
+ * 
+ * AI Usage:  
+ *   - This code was originally generated using
+ *      1. OpenAI/GPT OSS 120b on Roo Code
+ *      2. Gemini 2.5 Flash and 2.5 Pro
+ *     then modified to fix incorrect implementations and fit project needs.  
+ *     The first commit contains these corrections so that all code committed 
+ *     works as designed.
+ */
 import { describe, test, expect } from '@jest/globals';
 import { IsoDatetime } from './IsoDatetime.js';
 
@@ -60,6 +71,9 @@ describe('IsoDatetime.parse – valid inputs', () => {
 
 describe('IsoDatetime.parse – invalid inputs', () => {
   const invalid = [
+    '2025-03-01', // date only
+    '2025-03', // month only
+    '2025', // year only
     '2025-03-01 12:34:56Z', // no 'T' separator
     '2025-03-01T12:34Z',    // missing seconds
     '2025-03-01T12:34:56.789',  // missing Z
@@ -97,54 +111,76 @@ describe('IsoDatetime.toString – formatting', () => {
   });
 });
 
+
+describe('IsoDatetime.toIsoDate', () => {
+  const tests = [
+    { input: '2025-03-01T12:34:56Z', expected: '2025-03-01' },
+    { input: '2025-03-01T12:34:56.001Z', expected: '2025-03-01' },
+    { input: '2025-03-01T12:34:56+02:00', expected: '2025-03-01' },
+    { input: '2025-03-01T12:34:56-04:30', expected: '2025-03-01' },
+  ];
+
+  tests.forEach(({ input, expected }) => {
+    test(`converts an IsoDatetime(${input}) to its IsoDate equivalent`, () => {
+      const isoDatetime = IsoDatetime.parse(input);
+      const isoDate = isoDatetime.toIsoDate();
+      expect(isoDate.toString()).toBe(expected);
+    });
+  });
+});
+
 describe('IsoDatetime.getNextDay – day increments and decrements', () => {
+  test('regular date: March 4 +1 day => March 5', () => {
+    const dt = IsoDatetime.parse('2024-03-04T00:00:00Z');
+    expect(dt.getNextDay()).toEqual(IsoDatetime.parse('2024-03-05T00:00:00Z'));
+  });
   test('leap year: Feb 28 +1 day => Feb 29', () => {
     const dt = IsoDatetime.parse('2024-02-28T00:00:00Z');
-    expect(dt.getNextDay()).toBe('2024-02-29T00:00:00Z');
+    expect(dt.getNextDay()).toEqual(IsoDatetime.parse('2024-02-29T00:00:00Z'));
   });
 
   test('non‑leap year: Feb 28 +1 day => Mar 01', () => {
     const dt = IsoDatetime.parse('2025-02-28T00:00:00Z');
-    expect(dt.getNextDay(1)).toBe('2025-03-01T00:00:00Z');
+    expect(dt.getNextDay(1)).toEqual(IsoDatetime.parse('2025-03-01T00:00:00Z'));
   });
 
   test('leap day: Feb 29 +1 day => Mar 01', () => {
     const dt = IsoDatetime.parse('2024-02-29T00:00:00Z');
-    expect(dt.getNextDay(1)).toBe('2024-03-01T00:00:00Z');
+    expect(dt.getNextDay(1)).toEqual(IsoDatetime.parse('2024-03-01T00:00:00Z'));
   });
 
   test('month boundary: Jan 31 +1 day => Feb 01', () => {
     const dt = IsoDatetime.parse('2025-01-31T00:00:00Z');
-    expect(dt.getNextDay(1)).toBe('2025-02-01T00:00:00Z');
+    expect(dt.getNextDay(1)).toEqual(IsoDatetime.parse('2025-02-01T00:00:00Z'));
   });
 
   test('year boundary: Dec 31 +1 day => Jan 01 of next year', () => {
     const dt = IsoDatetime.parse('2025-12-31T00:00:00Z');
-    expect(dt.getNextDay(1)).toBe('2026-01-01T00:00:00Z');
+    expect(dt.getNextDay(1)).toEqual(IsoDatetime.parse('2026-01-01T00:00:00Z'));
   });
 
   test('century non‑leap year (1900): Feb 28 +1 day => Mar 01', () => {
     const dt = IsoDatetime.parse('1900-02-28T00:00:00Z');
-    expect(dt.getNextDay(1)).toBe('1900-03-01T00:00:00Z');
+    expect(dt.getNextDay(1)).toEqual(IsoDatetime.parse('1900-03-01T00:00:00Z'));
   });
 
   test('century leap year (2000): Feb 28 +1 day => Feb 29', () => {
     const dt = IsoDatetime.parse('2000-02-28T00:00:00Z');
-    expect(dt.getNextDay(1)).toBe('2000-02-29T00:00:00Z');
+    expect(dt.getNextDay(1)).toEqual(IsoDatetime.parse('2000-02-29T00:00:00Z'));
   });
 
   test('negative increment: Mar 01 -1 day => Feb 28 (non‑leap year)', () => {
     const dt = IsoDatetime.parse('2025-03-01T00:00:00Z');
-    expect(dt.getNextDay(-1)).toBe('2025-02-28T00:00:00Z');
+    expect(dt.getNextDay(-1)).toEqual(IsoDatetime.parse('2025-02-28T00:00:00Z'));
   });
 
   test('negative increment: Mar 01 -1 day => Feb 28 (leap year)', () => {
     const dt = IsoDatetime.parse('2024-03-01T00:00:00Z');
-    expect(dt.getNextDay(-1)).toBe('2024-02-29T00:00:00Z');
+    expect(dt.getNextDay(-1)).toEqual(IsoDatetime.parse('2024-02-29T00:00:00Z'));
   });
 
   test('negative crossing year: Jan 01 -1 day => Dec 31 of previous year', () => {
     const dt = IsoDatetime.parse('2025-01-01T00:00:00Z');
-    expect(dt.getNextDay(-1)).toBe('2024-12-31T00:00:00Z');
+    expect(dt.getNextDay(-1)).toEqual(IsoDatetime.parse('2024-12-31T00:00:00Z'));
   });
-});
+});
diff --git a/src/common/IsoDate/IsoDatetime.ts b/src/common/IsoDate/IsoDatetime.ts
@@ -15,9 +15,19 @@
  * Example:
  *   const dt = IsoDatetime.parse('2025-03-01T12:34:56.789+02:00');
  *   console.log(dt.toString()); // "2025-03-01T10:34:56.789Z"
+ * 
+ * AI Usage:  
+ *   - This code was originally generated using
+ *      1. OpenAI/GPT OSS 120b on Roo Code
+ *      2. Gemini 2.5 Flash and 2.5 Pro
+ *     then modified to fix incorrect implementations and fit project needs.  
+ *     The first commit contains these corrections so that all code committed 
+ *     works as designed.
  */
 import { IsoDate } from './IsoDate.js';
 
+export * from './IsoDate.js'
+
 export class IsoDatetime extends IsoDate {
   /** Hour (0‑23) */
   public readonly hour: number;
@@ -151,14 +161,28 @@ export class IsoDatetime extends IsoDate {
     const msPart = this.millisecond > 0 ? `.${String(this.millisecond).padStart(3, '0')}` : '';
     return `${y}-${m}-${d}T${h}:${min}:${s}${msPart}Z`;
   }
+
+  /** returns an IsoDate
+   *  Note: lossy precision
+   *  Even though this reduces the precision of a Datetime, it is useful for some purposes 
+   */
+  public toIsoDate(): IsoDate {
+    const y = String(this.year).padStart(4, '0');
+    const m = String(this.month).padStart(2, '0');
+    const d = String(this.day).padStart(2, '0');
+    const dateString = `${y}-${m}-${d}`;
+    return IsoDate.parse(dateString);
+  }
+
+
   /**
    * Returns an ISO‑8601 string representing this datetime shifted by the given
    * number of days (positive or negative). The shift respects month lengths,
    * leap‑year rules, and century leap‑year exceptions.
    *
    * @param increment Number of days to shift; may be negative.
    */
-  public getNextDay(increment: number = 1): string {
+  public getNextDay(increment: number = 1): IsoDatetime {
     // Compute the UTC timestamp for the current instance.
     const utcMs = Date.UTC(
       this.year,
@@ -181,7 +205,7 @@ export class IsoDatetime extends IsoDate {
       d.getUTCSeconds(),
       d.getUTCMilliseconds(),
     );
-    return next.toString();
+    return next;
   }
 
 }
diff --git a/src/search/SearchQueryBuilder.test.unit.ts b/src/search/SearchQueryBuilder.test.unit.ts
@@ -1,6 +1,6 @@
 // For a more comprehensive set of test cases, see the tests
 // in test_cases/search_*
-import { describe, it, test, expect } from '@jest/globals';
+import { describe, it, expect } from '@jest/globals';
 
 import { SearchOptions } from "./BasicSearchManager.js"
 import { SearchRequestType, SearchRequest, SearchRequestTypeId } from "./SearchRequest.js";
diff --git a/src/search/SearchQueryBuilder.ts b/src/search/SearchQueryBuilder.ts
@@ -1,4 +1,7 @@
 import { CveResult } from '../result/CveResult.js';
+import { IsoDate } from '../common/IsoDate/IsoDate.js';
+import { IsoDatetime } from '../common/IsoDate/IsoDatetime.js';
+import { toSearchDateDslString } from '../adapters/search/OpensearchDatetimeUtils.js';
 import { SearchOptions } from './BasicSearchManager.js';
 import { SearchRequest } from './SearchRequest.js';
 
@@ -85,11 +88,13 @@ export class SearchQueryBuilder {
     if (isDate) {
       // assemble all the date fields into an array
       let dateFields = [];
+      const startDate = (this._searchText.length > 10) ? IsoDatetime.parse(this._searchText) : IsoDate.parse(this._searchText);
+      const startDateStr = toSearchDateDslString(startDate)
       SearchQueryBuilder.kDateFieldPaths.map(path => {
         let field = `{
           "range": {
             "${path}": {
-              "gte": "${this._searchText}"
+              "gte": "${startDateStr}"
             }
           }
         }`;
diff --git a/src/search/__snapshots__/SearchQueryBuilder.test.unit.ts.snap b/src/search/__snapshots__/SearchQueryBuilder.test.unit.ts.snap
@@ -108,14 +108,14 @@ CveResult {
             Object {
               "range": Object {
                 "containers.cna.providerMetadata.dateUpdated": Object {
-                  "gte": "2023-12-21",
+                  "gte": "2023-12-21||/d",
                 },
               },
             },
             Object {
               "range": Object {
                 "containers.cna.timeline.time": Object {
-                  "gte": "2023-12-21",
+                  "gte": "2023-12-21||/d",
                 },
               },
             },
