Merge remote-tracking branch 'origin/dev' into hk/006a_exact_phrase_search

Author: hkong-mitre

.gitignore

@@ -49,6 +49,7 @@ Notes.md
 .env.*
 
 # development and testing files
+.notes
 aws.temp
 bulk/converted*.jsonl
 cves/deltaLog.json

ChangeLog.md

@@ -1,7 +1,12 @@
 # Change Log
 
-### 2.2.0-rc1 (Sprint 1)
+### 2.2.0-rc3 (Sprint 4)
   - exact phrase search using double quotes
+  - date and date range search on date fields, using the following formats (date ranges are inclusive):
+    - YYYY-MM-DD
+    - YYYY-MM-DDTHH:MM:SS(.mmm)(Z) (where the .mmm and Z are optional, defaults to .000Z if missing)
+    - YYYY-MM-DD..YYYY-MM-DD
+    - YYYY-MM-DDTHH:MM:SS(.mmm)(Z)..YYYY-MM-DDTHH:MM:SS.(mmm)(Z)
 
 ### 2.1.0
   - wildcard search using "*" and "?"

config/devel.jsonc

@@ -31,8 +31,8 @@
         "fixtures": {
           // @todo these constants needs to be in sync in cve-fixtures 
           // so that testing snapshots are consistent and valid
-          "name": "fixtures-search-baseline-1086", // release tag
-          "numCves": "1086" // possible identifier assuming we always add cves to a new release
+          "name": "fixtures-search-baseline-1008", // release tag
+          "numCves": "1008" // possible identifier assuming we always add cves to a new release
         }
       },
       // constants for testing node-config

index.ts

@@ -26,6 +26,9 @@ export * from "./src/commands/GenericCommand.js";
 export * from "./src/commands/MainCommands.js";
 
 // common
+export * from "./src/common/IsoDate/IsoDate.js";
+export * from "./src/common/IsoDate/IsoDatetime.js";
+export * from "./src/common/IsoDate/IsoDatetimeRange.js";
 export * from "./src/common/IsoDate/IsoDateString.js";
 export * from "./src/common/Json/Json.js";
 export * from "./src/common/comparer/ObjectComparer.js";

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "cve-core",
-  "version": "2.2.0-rc1",
+  "version": "2.2.0-rc3",
   "description": "CVE npm package for working with CVEs",
   "type": "module",
   "engines": {

package.json

@@ -0,0 +1,27 @@
+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:56.001Z', expected: '2025-03-01T12:34:56.001Z' },
+    { input: '2025-03-01T12:34:56.001', expected: '2025-03-01T12:34:56.001Z' },
+    { input: '2025-03-01T12:34:56Z', expected: '2025-03-01T12:34:56Z' },
+    { input: '2025-03-01T12:34:56', 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();
+  });
+});

src/adapters/search/OpensearchDatetimeUtils.test.unit.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();
+  }
+};

src/adapters/search/OpensearchDatetimeUtils.ts

@@ -0,0 +1,161 @@
+/**
+ * Unit tests for IsoDate
+ * 
+ * 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 { IsoDate, isValidIsoDate } from './IsoDate';
+
+describe('IsoDate.parse – valid inputs', () => {
+
+  test('full date with hyphens', () => {
+    const str = '2025-01-01';
+    expect(isValidIsoDate(str)).toBeTruthy();
+    const d = IsoDate.parse(str);
+    expect(d.year).toBe(2025);
+    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', () => {
+    const str = '2025-01';
+    expect(isValidIsoDate(str)).toBeTruthy();
+    const d = IsoDate.parse(str);
+    expect(d.year).toBe(2025);
+    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', () => {
+    const str = '2025';
+    expect(isValidIsoDate(str)).toBeTruthy();
+    const d = IsoDate.parse(str);
+    expect(d.year).toBe(2025);
+    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', () => {
+    const str = '2024-02-29';
+    expect(isValidIsoDate(str)).toBeTruthy();
+    const d = IsoDate.parse(str);
+    expect(d.year).toBe(2024);
+    expect(d.month).toBe(2);
+    expect(d.day).toBe(29);
+    expect(d.toString()).toBe('2024-02-29');
+  });
+
+  test('month‑day boundary', () => {
+    const str = '2025-01-30';
+    expect(isValidIsoDate(str)).toBeTruthy();
+    const d = IsoDate.parse(str);    
+    expect(d.year).toBe(2025);
+    expect(d.month).toBe(1);
+    expect(d.day).toBe(30);
+    expect(d.toString()).toBe('2025-01-30');
+  });
+});
+
+
+describe('IsoDate.parse/toString/isMonth/isDate/isYear', () => {
+  const tests: Array<{ value: string; isYear?: boolean; isMonth?: boolean; isDate?: boolean; isDatetime?: boolean; threw?: RegExp; }> = [
+    // valid ISO Date specs
+    { value: `2025`, isYear: true },
+    { value: ` 2025 `, isYear: true },
+    { value: `2025-10`, isMonth: true },
+    { value: `2024-02-29`, isDate: true },
+    // invalid ISO Date specs
+    { value: `25`, threw: /Invalid calendar date format/ },  // year must be after 1000 and before 2500
+    { value: `1899`, threw: /Year out of range/ },  // year must be after 1900 and before 2100
+    { value: `2500`, threw: /Year out of range/ },  // year must be after 1900 and before 2100
+    { value: `1/1/25`, threw: /Invalid calendar date format/ },  // bad format
+    { value: `abc`, threw: /Invalid calendar date format/ },  // bad format
+    { value: `202501`, threw: /Invalid calendar date format/ }, // year+month without hyphen
+    { value: `20250101`, threw: /Invalid calendar date format/ }, // compact full date (properly rejected in this class)
+    { value: `250101`, threw: /Invalid calendar date format/ }, // two‑digit year
+    { value: `-2025-04-31`, threw: /Invalid calendar date format/ },  // leading hyphen
+    { value: `-2025-04`, threw: /Invalid calendar date format/ },  // leading hyphen
+    { value: `01-01`, threw: /Invalid calendar date format/ },
+    { value: `2025--01`, threw: /Invalid calendar date format/ },
+    { value: `2025-01-01T014:00:00:00Z`, threw: /Invalid calendar date format/ },
+    { value: `2025-13-01`, threw: /Month out of range/ },
+    { value: `2025-02-29`, threw: /Day out of range/ }, // not a leap year
+    { value: `2025-02-30`, threw: /Day out of range/ },
+    { value: `2025-04-31`, threw: /Day out of range/ },
+  ];
+
+  tests.forEach(({ value, isYear = false, isMonth = false, isDate = false, threw = '' }) => {
+    test(`properly determines if ${value} is a ${isYear ? 'year' : ''}${isMonth ? 'month' : ''}${isDate ? 'date' : ''}${threw ? 'error' : ''}`, () => {
+      if (threw) {
+        expect(() => IsoDate.parse(value)).toThrow(threw);
+      }
+      else {
+        const isoDate = IsoDate.parse(value);
+        if (isYear) {
+          expect(isoDate.isYear()).toBeTruthy();
+          expect(isoDate.isMonth()).toBeFalsy();
+          expect(isoDate.isDate()).toBeFalsy();
+          expect(isoDate.isDatetime()).toBeFalsy();
+        }
+        else if (isMonth) {
+          expect(isoDate.isYear()).toBeFalsy();
+          expect(isoDate.isMonth()).toBeTruthy();
+          expect(isoDate.isDate()).toBeFalsy();
+          expect(isoDate.isDatetime()).toBeFalsy();
+        }
+        else if (isDate) {
+          expect(isoDate.isYear()).toBeFalsy();
+          expect(isoDate.isMonth()).toBeFalsy();
+          expect(isoDate.isDate()).toBeTruthy();
+          expect(isoDate.isDatetime()).toBeFalsy();
+        }
+        expect(isoDate.toString()).toBe(value.trim());
+      }
+    });
+  });
+});
+
+
+describe('IsoDate.daysInMonth()', () => {
+  const tests: Array<{ year: number; month: number, expected: number; }> = [
+    { year: 2025, month: 1, expected: 31 },
+    { year: 2025, month: 2, expected: 28 },
+    { year: 2025, month: 3, expected: 31 },
+    { year: 2025, month: 4, expected: 30 },
+    { year: 2025, month: 5, expected: 31 },
+    { year: 2025, month: 6, expected: 30 },
+    { year: 2025, month: 7, expected: 31 },
+    { year: 2025, month: 8, expected: 31 },
+    { year: 2025, month: 9, expected: 30 },
+    { year: 2025, month: 10, expected: 31 },
+    { year: 2025, month: 11, expected: 30 },
+    { year: 2025, month: 12, expected: 31 },
+    { year: 2024, month: 2, expected: 29 }, // leap year
+  ];
+
+  tests.forEach(({ year, month, expected }) => {
+    test(`properly calculates ${year}-${month} to have ${expected} days`, () => {
+      const days = IsoDate.daysInMonth(year, month);
+      expect(days).toBe(expected);
+    });
+  });
+});