nl2time 0.3.0 → 0.3.1

package/README.md

@@ -114,11 +114,17 @@ Every imported conformance case carries machine-readable provenance (upstream pr
 
 ## Python
 
-A Python engine port lives in [`python/`](python/) (PyPI packaging prepared; `whenever`-based time model): IR validation, `TimeContext`, and the full deterministic resolver at **100% bit-exact parity** with the JS reference across all 2,760 engine-parity fixtures (`corpus/ir/`), enforced in CI on every push. Parsers and `describe()` are JS-only so far — [docs/porting.md](docs/porting.md) has the strategy and the divergence gates.
+[![PyPI](https://img.shields.io/pypi/v/nl2time)](https://pypi.org/project/nl2time/)
+
+```
+pip install nl2time
+```
+
+The Python engine port lives in [`python/`](python/) (`whenever`-based time model): IR validation, `TimeContext`, and the full deterministic resolver at **100% bit-exact parity** with the JS reference across all 2,760 engine-parity fixtures (`corpus/ir/`), enforced in CI on every push. Parsers and `describe()` are JS-only so far — [docs/porting.md](docs/porting.md) has the strategy and the divergence gates.
 
 ## Release history
 
-See **[CHANGELOG.md](CHANGELOG.md)** and [GitHub releases](https://github.com/AndyFooBlah/nl2time/releases). Current: v0.3.0 (multilingual parsing).
+See **[CHANGELOG.md](CHANGELOG.md)** and [GitHub releases](https://github.com/AndyFooBlah/nl2time/releases). Current: v0.3.0 (JS, multilingual parsing) · py-v0.1.0 (Python engine). Releases publish to npm/PyPI automatically via OIDC trusted publishing — see [docs/RELEASING.md](docs/RELEASING.md).
 
 ## Development
 

package/dist/engine/resolve.js

@@ -67,9 +67,13 @@ function evalExpr(expr, ctx, anchor) {
     // inside the interval it tightens the bound ("earlier this year" ends
     // today, not at midyear).
     if (expr.mod === 'start' || expr.mod === 'end') {
-        return intervalMap(cands, (zi) => {
-            if (zi.grain === 'instant')
-                return zi;
+        const out = [];
+        for (const c of cands) {
+            if (c.type !== 'interval' || c.zi.grain === 'instant') {
+                out.push(c);
+                continue;
+            }
+            const zi = c.zi;
             const totalMs = zi.end.epochMilliseconds - zi.start.epochMilliseconds;
             let mid = zi.start.add({ milliseconds: Math.floor(totalMs / 2) });
             const gi = GRAIN_ORDER.indexOf(zi.grain);
@@ -78,18 +82,25 @@ function evalExpr(expr, ctx, anchor) {
             else if (gi > GRAIN_ORDER.indexOf('day'))
                 mid = floorTo(mid, 'day', ctx.weekStart);
             let bound = mid;
+            let altHalf = false;
             if (gi > GRAIN_ORDER.indexOf('day')) {
                 const refDay = floorTo(ctx.zonedNow, 'day', ctx.weekStart);
                 const inRange = Temporal_compare(refDay, zi.start) > 0 && Temporal_compare(refDay, zi.end) < 0;
                 if (inRange) {
+                    // 'start' ("earlier this week/year") ends at the start of the
+                    // reference day: on a Thursday, "earlier this week" reaches
+                    // through Wednesday, not just past the midpoint (#20). When the
+                    // reference sits beyond the midpoint the plain first half stays
+                    // as an alternative (the Recognizers corpus pins it for "earlier
+                    // this month"). 'end' ("later this week") starts at the
+                    // reference day only once the midpoint has passed.
                     bound =
                         expr.mod === 'start'
-                            ? Temporal_compare(refDay, mid) < 0
-                                ? refDay
-                                : mid
+                            ? refDay
                             : Temporal_compare(refDay, mid) > 0
                                 ? refDay
                                 : mid;
+                    altHalf = expr.mod === 'start' && Temporal_compare(refDay, mid) > 0;
                 }
             }
             const narrowed = expr.mod === 'start'
@@ -97,12 +108,20 @@ function evalExpr(expr, ctx, anchor) {
                 : { start: bound, end: zi.end, grain: zi.grain };
             // A degenerate clamp (bound at an edge) falls back to the plain half.
             if (Temporal_compare(narrowed.start, narrowed.end) >= 0) {
-                return expr.mod === 'start'
-                    ? { start: zi.start, end: mid, grain: zi.grain }
-                    : { start: mid, end: zi.end, grain: zi.grain };
+                out.push({
+                    type: 'interval',
+                    zi: expr.mod === 'start'
+                        ? { start: zi.start, end: mid, grain: zi.grain }
+                        : { start: mid, end: zi.end, grain: zi.grain },
+                });
+                continue;
             }
-            return narrowed;
-        });
+            out.push({ type: 'interval', zi: narrowed });
+            if (altHalf && Temporal_compare(zi.start, mid) < 0) {
+                out.push({ type: 'interval', zi: { start: zi.start, end: mid, grain: zi.grain } });
+            }
+        }
+        return out;
     }
     // mod 'mid': the middle stretch. Conventions follow common usage: mid-month
     // = the 10th through the 20th; mid-day = 10:00–14:00; otherwise the middle
@@ -159,10 +178,27 @@ function evalExprInner(expr, ctx, anchor) {
                 for (const e of evalExpr(expr.end, ctx, s.zi)) {
                     if (e.type !== 'interval')
                         continue;
-                    // Non-point ends are exclusive at their *start* ("May 2 to May 7"
-                    // ends at May 7 00:00); point ends are used directly.
-                    let endPoint = Temporal_compare(e.zi.start, e.zi.end) === 0 ? e.zi.end : e.zi.start;
+                    const isPoint = Temporal_compare(e.zi.start, e.zi.end) === 0;
                     const timeGrained = GRAIN_ORDER.indexOf(e.zi.grain) < GRAIN_ORDER.indexOf('day');
+                    // Day-grain-or-coarser ends are conversationally inclusive:
+                    // "between July 4th and July 10th" covers the 10th. Emit the
+                    // inclusive reading (end operand contributes its END) first, with
+                    // the strict exclusive-at-start reading as an alternative — the
+                    // Recognizers-derived corpus pins the exclusive value, so both
+                    // must remain candidates (#17).
+                    if (!isPoint && !timeGrained) {
+                        const grain = finerGrain(s.zi.grain, e.zi.grain);
+                        if (Temporal_compare(s.zi.start, e.zi.end) < 0) {
+                            out.push({ type: 'interval', zi: { start: s.zi.start, end: e.zi.end, grain } });
+                        }
+                        if (Temporal_compare(s.zi.start, e.zi.start) < 0) {
+                            out.push({ type: 'interval', zi: { start: s.zi.start, end: e.zi.start, grain } });
+                        }
+                        continue;
+                    }
+                    // Non-point time ends are exclusive at their *start* ("9 to 5pm"
+                    // ends at 17:00); point ends are used directly.
+                    let endPoint = isPoint ? e.zi.end : e.zi.start;
                     if (Temporal_compare(s.zi.start, endPoint) >= 0) {
                         // A clock-time range wrapping midnight ("9:30pm to 7:30am") rolls
                         // the end into the next day; date ranges just drop.

package/dist/parse/en.js

@@ -610,6 +610,51 @@ function buildRange(a, b, scope, period, connWord) {
     }
     return undefined;
 }
+/**
+ * Open-range connectors (#18): "since X" → [start(X), now]; "until X" /
+ * "till X" / "through X" / "up to X" / "by X" (deadline) → [now, end(X)].
+ * These only fire when the connector opens the range — "A until B" and
+ * "from A through B" are consumed earlier by the range rule.
+ */
+const ruleOpenRange = (tokens, i, ctx) => {
+    const w = word(tokens[i]);
+    let mode;
+    let at = i + 1;
+    if (w === 'since')
+        mode = 'since';
+    else if (w === 'until' || w === 'till' || w === 'through' || w === 'thru' || w === 'by') {
+        mode = 'until';
+    }
+    else if (w === 'up' && word(tokens[i + 1]) === 'to') {
+        mode = 'until';
+        at = i + 2;
+    }
+    if (!mode)
+        return undefined;
+    // "by the 15th": a bare article only before an explicit calendar date —
+    // NOT "through the week"-style prose, which stays unmatched.
+    if (word(tokens[at]) === 'the' && ruleCalendarDate(tokens, at + 1, ctx))
+        at += 1;
+    const inner = ruleDeicticDay(tokens, at, ctx) ??
+        ruleLastThisNext(tokens, at, ctx) ??
+        ruleHoliday(tokens, at, ctx) ??
+        ruleEndOf(tokens, at, ctx) ??
+        ruleWeekOf(tokens, at, ctx) ??
+        ruleBareYear(tokens, at, ctx) ??
+        ruleCalendarDate(tokens, at, ctx) ??
+        ruleClockTime(tokens, at, ctx) ??
+        ruleWeekdayAlone(tokens, at, ctx);
+    if (!inner || inner.role === 'duration')
+        return undefined;
+    // Boundary points ("by EOD", "by the end of the month") keep their point
+    // reading — the deadline instant is the answer there, not a range.
+    if (inner.expr.op === 'snap' && inner.expr.edge !== undefined)
+        return undefined;
+    const expr = mode === 'since'
+        ? { op: 'between', start: inner.expr, end: NOW }
+        : { op: 'between', start: NOW, end: inner.expr };
+    return { expr, consumed: at + inner.consumed - i, confidence: 0.9, role: 'datetime' };
+};
 /** "week of April 10th", "the first/last week of July", "the week starting on Feb 4". */
 const ruleWeekOf = (tokens, i, ctx) => {
     let at = i;
@@ -915,6 +960,88 @@ const ruleEndOf = (tokens, i, ctx) => {
         : { ...inner.expr, mod: isEnd ? 'end' : isMid ? 'mid' : 'start' };
     return { expr, consumed: at + inner.consumed - i, confidence: 0.95, role: 'date' };
 };
+/** The period unit a half-of scope denotes, if determinable. */
+function halfScopeUnit(expr) {
+    if (expr.op === 'snap') {
+        return expr.edge === undefined &&
+            (expr.unit === 'week' || expr.unit === 'month' || expr.unit === 'quarter' || expr.unit === 'year')
+            ? expr.unit
+            : undefined;
+    }
+    if (expr.op === 'literal' && expr.date !== undefined && expr.time === undefined) {
+        if (expr.date.day !== undefined)
+            return undefined;
+        return expr.date.month !== undefined ? 'month' : 'year';
+    }
+    if (expr.op === 'seek' && expr.target.kind === 'month')
+        return 'month';
+    return undefined;
+}
+/** "the first/second half of <period>" → [start, mid) / [mid, end) (#24). */
+const ruleHalfOf = (tokens, i, ctx) => {
+    let at = i;
+    if (word(tokens[at]) === 'the')
+        at += 1;
+    const w = word(tokens[at]);
+    const t = tokens[at];
+    let which;
+    if (w === 'first')
+        which = 1;
+    else if (w === 'second' || w === 'latter' || w === 'back')
+        which = 2;
+    else if (t?.type === 'number' && t.ordinal && (t.value === 1 || t.value === 2)) {
+        which = t.value;
+    }
+    if (which === undefined)
+        return undefined;
+    if (word(tokens[at + 1]) !== 'half' || word(tokens[at + 2]) !== 'of')
+        return undefined;
+    at += 3;
+    if (word(tokens[at]) === 'the')
+        at += 1;
+    // Scope: a bare unit ("the year"), a relative period ("next month"), a
+    // month name, a quarter, or a year.
+    let scope;
+    let unit;
+    let consumed = 0;
+    const uw = word(tokens[at]) !== 'night' ? UNIT_WORDS[word(tokens[at]) ?? ''] : undefined;
+    if (uw === 'week' || uw === 'month' || uw === 'quarter' || uw === 'year') {
+        scope = snapNow(uw);
+        unit = uw;
+        consumed = 1;
+    }
+    else {
+        const inner = ruleLastThisNext(tokens, at, ctx) ??
+            ruleBareYear(tokens, at, ctx) ??
+            ruleCalendarDate(tokens, at, ctx);
+        if (inner && inner.role === 'date') {
+            unit = halfScopeUnit(inner.expr);
+            if (unit) {
+                scope = inner.expr;
+                consumed = inner.consumed;
+            }
+        }
+    }
+    if (!scope || !unit)
+        return undefined;
+    // Fixed split, deliberately not reference-clamped (unlike mod
+    // 'start'/'end'): "the first half of the year" is Jan–Jun regardless of
+    // today. Midpoints: year +6 months, quarter +45 days, month +15 days
+    // (the 16th), week +84 hours.
+    const startPoint = { op: 'snap', base: scope, unit, edge: 'start' };
+    const endPoint = { op: 'snap', base: scope, unit, edge: 'end' };
+    const mid = unit === 'year'
+        ? { op: 'offset', base: startPoint, amount: 6, unit: 'month' }
+        : unit === 'quarter'
+            ? { op: 'offset', base: startPoint, amount: 45, unit: 'day' }
+            : unit === 'month'
+                ? { op: 'offset', base: startPoint, amount: 15, unit: 'day' }
+                : { op: 'offset', base: startPoint, amount: 84, unit: 'hour' };
+    const expr = which === 1
+        ? { op: 'between', start: startPoint, end: mid }
+        : { op: 'between', start: mid, end: endPoint };
+    return { expr, consumed: at + consumed - i, confidence: 1, role: 'date' };
+};
 const REL_SYNONYMS = {
     last: 'last', previous: 'last', prior: 'last',
     this: 'this', current: 'this', present: 'this', that: 'this',
@@ -1164,6 +1291,33 @@ const ruleUnitAfterNext = (tokens, i) => {
         return undefined;
     return { expr: snapOffset(2, unit), consumed: 3, confidence: 1, role: 'date' };
 };
+/** "[the] <weekday> before last" → two occurrences back; "the week before last" → two units back (#21). */
+const ruleBeforeLast = (tokens, i) => {
+    let at = i;
+    if (word(tokens[at]) === 'the')
+        at += 1;
+    const w = word(tokens[at]);
+    if (w === undefined)
+        return undefined;
+    if (word(tokens[at + 1]) !== 'before' || word(tokens[at + 2]) !== 'last')
+        return undefined;
+    const consumed = at + 3 - i;
+    const weekday = WEEKDAY_WORDS[w];
+    if (weekday) {
+        // Strict occurrence counting: the second one strictly in the past.
+        return {
+            expr: { op: 'seek', base: NOW, dir: 'prev', target: { kind: 'weekday', weekday }, n: 2 },
+            consumed,
+            confidence: 1,
+            role: 'date',
+        };
+    }
+    const unit = w !== 'night' ? UNIT_WORDS[w] : undefined;
+    if (unit && unit !== 'second' && unit !== 'minute' && unit !== 'hour') {
+        return { expr: snapOffset(-2, unit), consumed, confidence: 1, role: 'date' };
+    }
+    return undefined;
+};
 /** "last/past/previous N units" → span backwards; "the past week" → trailing 7 days. */
 const rulePastN = (tokens, i) => {
     const w = word(tokens[i]);
@@ -1440,16 +1594,57 @@ const ruleWeekendOf = (tokens, i, ctx) => {
     if (word(tokens[at]) !== 'weekend' || word(tokens[at + 1]) !== 'of')
         return undefined;
     at += 2;
-    const inner = ruleHoliday(tokens, at, ctx) ?? ruleCalendarDate(tokens, at, ctx);
+    // Holidays keep the long-weekend reading: Saturday before through the end
+    // of the holiday ("Memorial Day weekend" = Sat–Mon).
+    const holiday = ruleHoliday(tokens, at, ctx);
+    if (holiday && holiday.role === 'date') {
+        return {
+            expr: {
+                op: 'between',
+                start: { op: 'seek', base: holiday.expr, dir: 'prev', target: { kind: 'weekday', weekday: 'sat' }, n: 1 },
+                end: { op: 'snap', base: holiday.expr, unit: 'day', edge: 'end' },
+            },
+            consumed: at + holiday.consumed - i,
+            confidence: 0.95,
+            role: 'date',
+        };
+    }
+    if (word(tokens[at]) === 'the')
+        at += 1; // "the weekend of the 18th"
+    const inner = ruleCalendarDate(tokens, at, ctx);
     if (!inner || inner.role !== 'date')
         return undefined;
+    let consumed = at + inner.consumed - i;
+    // "the weekend of July 18th and 19th": the conjunct names the weekend's
+    // other day — absorb it (#22).
+    const andAt = at + inner.consumed;
+    if (word(tokens[andAt]) === 'and') {
+        const t = tokens[andAt + 1];
+        if (t?.type === 'number' && t.ordinal && t.value >= 1 && t.value <= 31) {
+            consumed = andAt + 2 - i;
+        }
+        else {
+            const ord = readOrdinalDayWord(tokens, andAt + 1);
+            if (ord)
+                consumed = andAt + 1 + ord.consumed - i;
+        }
+    }
+    // The Sat–Sun weekend containing the date, or the following one for a
+    // midweek date: the first Saturday on-or-after (date − 1 day), so a
+    // Sunday still maps back to its own weekend (#22).
     return {
         expr: {
-            op: 'between',
-            start: { op: 'seek', base: inner.expr, dir: 'prev', target: { kind: 'weekday', weekday: 'sat' }, n: 1 },
-            end: { op: 'snap', base: inner.expr, unit: 'day', edge: 'end' },
+            op: 'span',
+            anchor: {
+                op: 'seek',
+                base: { op: 'offset', base: inner.expr, amount: -2, unit: 'day' },
+                dir: 'next',
+                target: { kind: 'weekday', weekday: 'sat' },
+                n: 1,
+            },
+            amount: { days: 2 },
         },
-        consumed: at + inner.consumed - i,
+        consumed,
         confidence: 0.95,
         role: 'date',
     };
@@ -2722,17 +2917,20 @@ const ruleAllUnit = (tokens, i) => {
  */
 export const EN_RULE_ENTRIES = [
     { name: 'range', rule: ruleRange },
+    { name: 'open-range', rule: ruleOpenRange },
     { name: 'week-of', rule: ruleWeekOf },
     { name: 'nth-weekday-of', rule: ruleNthWeekdayOf },
     { name: 'day-of-scope', rule: ruleDayOfScope },
     { name: 'weekend-of', rule: ruleWeekendOf },
     { name: 'holiday', rule: ruleHoliday },
     { name: 'early-late', rule: ruleEarlyLate },
+    { name: 'half-of', rule: ruleHalfOf },
     { name: 'end-of', rule: ruleEndOf },
     { name: 'deictic-day', rule: ruleDeicticDay },
     { name: 'within', rule: ruleWithin },
     { name: 'n-after-date', rule: ruleNAfterDate },
     { name: 'unit-after-next', rule: ruleUnitAfterNext },
+    { name: 'before-last', rule: ruleBeforeLast },
     { name: 'past-n', rule: rulePastN },
     { name: 'next-n', rule: ruleNextN },
     { name: 'the-n-past-next', rule: ruleTheNPastNext },

package/dist/parse/index.js

@@ -137,7 +137,10 @@ function mergeAdjacent(matches, tokens, connectors) {
             let timeExpr = inferMeridiem(dateExpr, timePart.expr);
             // A day-period on the date side pushes its meridiem into an explicit
             // time range and then steps aside: "Monday morning 6-8" is Monday
-            // 06:00–08:00, not clipped to the morning boundaries.
+            // 06:00–08:00, not clipped to the morning boundaries. A cross-midnight
+            // range ("last night between 11pm and 1am") keeps the period part:
+            // its window extends past midnight, so the range can roll into the
+            // next day instead of being clipped at the day anchor's end (#19).
             if (timeExpr.op === 'between') {
                 const period = findDayPeriod(dateExpr);
                 if (period) {
@@ -146,7 +149,11 @@ function mergeAdjacent(matches, tokens, connectors) {
                         start: forceMeridiem(timeExpr.start, period),
                         end: forceMeridiem(timeExpr.end, period),
                     };
-                    dateExpr = stripDayPeriod(dateExpr) ?? dateExpr;
+                    const sm = literalMinuteOfDay(timeExpr.start);
+                    const em = literalMinuteOfDay(timeExpr.end);
+                    const wraps = sm !== undefined && em !== undefined && em <= sm;
+                    if (!wraps)
+                        dateExpr = stripDayPeriod(dateExpr) ?? dateExpr;
                 }
             }
             out.push({
@@ -211,6 +218,18 @@ function inferMeridiem(dateExpr, timeExpr) {
         time: { ...timeExpr.time, meridiem },
     };
 }
+/** Minutes-since-midnight of a literal time with a known meridiem, if any. */
+function literalMinuteOfDay(expr) {
+    if (expr.op !== 'literal' || expr.time?.hour === undefined)
+        return undefined;
+    const h = expr.time.hour % 12;
+    const min = expr.time.minute ?? 0;
+    if (expr.time.meridiem === 'am')
+        return h * 60 + min;
+    if (expr.time.meridiem === 'pm')
+        return (h + 12) * 60 + min;
+    return undefined;
+}
 function forceMeridiem(expr, period) {
     if (expr.op !== 'literal' || !expr.time || (expr.time.meridiem && expr.time.meridiem !== 'unknown')) {
         return expr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nl2time",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Bidirectional natural language \u21c4 date/time: parse expressions like 'last week' into concrete intervals, and describe instants as '9pm last night' \u2014 deterministic core, optional LLM assist.",
   "license": "MIT",
   "type": "module",