things-api 0.8.0 → 0.10.0

package/dist/read/truncation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.js","sourceRoot":"","sources":["../../src/read/truncation.ts"],"names":[],"mappings":"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"}

package/dist/read/views.d.ts

@@ -20,7 +20,18 @@
  *             overdue bucket=1 items roll back into Today proper (live-
  *             verified against the UI, 2026-07-02).
  *             Sidebar badge split: red = items with deadline <= today,
- *             gray = the rest (exact 270/122 reconciliation on live data).
+ *             gray = the rest (exact 270/122 reconciliation on live data). The
+ *             badge counts OPEN members only — a checked-but-unswept row is in
+ *             the list but out of the count (the GUI badge is remaining work).
+ *             CHECKED-BUT-UNSWEPT (GUI-parity ruling 2026-07-14, Mike — "this
+ *             is the behavior of the Things GUI and I like it"): membership is
+ *             OPEN_OR_UNSWEPT, not OPEN — a completed/canceled row the log-move
+ *             sweep has NOT yet passed (completion ≠ logged; see
+ *             log-boundary.ts) stays in Today IN PLACE, keeping the exact
+ *             comparator slot (startBucket / referenceDate / todayIndex) it held
+ *             open. It leaves when the sweep boundary advances past its stopDate
+ *             (boundary-relative, no new state). Mixed-context resolved styling
+ *             (dim / dim+strike) applies automatically in formatItem.
  * - anytime:  ALL active items — unscheduled PLUS Today members (the UI
  *             renders Today members with a star; live-verified via screenshot
  *             2026-07-02: starred = in Today, unstarred = unscheduled).
@@ -29,7 +40,29 @@
  *             project that is not itself anytime-visible (someday/future/
  *             logged/trashed) are excluded — the project row represents
  *             them. Result is grouped in sidebar order (SidebarSection[]).
- * - upcoming: start=2 AND startDate > today, PLUS each fixed repeating
+ *             CHECKED-BUT-UNSWEPT (GUI-parity ruling 2026-07-14, Mike): like
+ *             Today, membership is OPEN_OR_UNSWEPT — a closed row the sweep has
+ *             not passed keeps its index slot until the boundary moves past its
+ *             stopDate. A closed-but-unswept PROJECT row shows in place and its
+ *             children stay cascade-excluded (PROJECT_ANYTIME_ACTIVE still tests
+ *             p.status = 0): the checked project row represents its children,
+ *             the same precedent as a logged/someday container.
+ * - upcoming: TWO cohorts merged, grouped/sorted by COALESCE(startDate,
+ *             deadline) (UPC1, GUI-verified, docs/lab/upcoming-research.md):
+ *             (1) SCHEDULED — start=2 AND startDate > today, grouped under its
+ *             when-date (a deadline it also carries rides along as a flag);
+ *             (2) DEADLINE-FORECAST — startDate IS NULL AND start IN (1, 2)
+ *             AND deadline > today AND (deadlineSuppressionDate IS NULL OR
+ *             deadlineSuppressionDate < deadline), grouped under its DEADLINE
+ *             date (both to-dos and projects). INBOX (start=0) is EXCLUDED — a
+ *             future deadline does not forecast an Inbox item into Upcoming,
+ *             though a DUE one still pulls it into Today. The suppression guard
+ *             drops a dismissed-nag deadline (supp == deadline) and lets a
+ *             re-armed one (supp < deadline) reappear — the todayView clause
+ *             one step earlier (deadline > today). A when+deadline row appears
+ *             ONCE under its when-date, never double-emitted (the forecast
+ *             cohort requires startDate IS NULL). Forecast rows keep
+ *             startDate=null (no faked when-date). PLUS each fixed repeating
  *             template's next occurrence synthesized from
  *             rt1_nextInstanceStartDate (UI parity; opt out via
  *             repeats:false). Occurrence deadline = start − rule.ts
@@ -48,22 +81,81 @@
 import type { DatabaseSync } from "node:sqlite";
 import { type IsoDate } from "../model/dates.ts";
 import type { Project, Ref, Todo } from "../model/entities.ts";
+import type { Area } from "../model/entities.ts";
 export type ListItem = Todo | Project;
 /** Optional list-view filters. */
 export interface ViewFilter {
     /**
-     * Tag (uuid or unique title): direct OR inherited membership (UI
-     * semantics), INCLUDING items tagged with a hierarchy descendant of the
-     * given tag (documented app behavior — the UI's tag filter matches
-     * child-tagged items; not lab-oracled).
+     * Convenience shorthand for a single-element {@link tags} — a lone
+     * inheritance-inclusive tag ref. Production surfaces (CLI `--tag`, MCP
+     * `tag`) always pass the array form; this exists for internal/test callers.
      */
     tag?: string;
     /**
-     * Match the given tag ONLY — no hierarchy descendants. Useful when a
+     * Tag refs (uuid or unique title). In FLAT views (today/inbox/anytime/
+     * someday/upcoming/search/logbook) this is direct OR inherited membership (UI
+     * semantics), INCLUDING items tagged with a hierarchy descendant of each
+     * given tag (documented app behavior — the UI's tag filter matches
+     * child-tagged items; not lab-oracled). In CONTAINER views (`project show`,
+     * `area show`, the `projects` list) the same ref instead matches rows carrying
+     * the tag DIRECTLY (still with descendant expansion) — the view's own
+     * container-inheritance hop is suppressed, since every child inherits the
+     * container's tags and an inheritance-inclusive filter there is vacuous. The
+     * host view selects the behavior via {@link tagFilter}'s `container` option.
+     * Multiple refs AND together — an item must match EVERY ref (each
+     * independently expanded to its descendant set, OR-matched within,
+     * AND-combined across).
+     */
+    tags?: string[];
+    /**
+     * Match each given tag ref ONLY — no hierarchy descendants. Useful when a
      * parent tag has its own direct assignments distinct from its children's.
      */
     exactTag?: boolean;
+    /**
+     * Only items with NO tag (the GUI's "No Tag"). In FLAT views this negates the
+     * WHOLE direct+inherited membership relation — an item is untagged iff no
+     * possible `tag` value could ever match it. In CONTAINER views it instead
+     * means "no DIRECT tag" (the container's own inherited tags are suppressed,
+     * matching the container `tag` semantics). Mutually exclusive with
+     * `tag`/`exactTag` (the surfaces reject the combination).
+     */
+    untagged?: boolean;
+    /**
+     * Only OPEN items whose deadline is strictly BEFORE today (due-today is NOT
+     * overdue — it mirrors the app's Today badge, where an equal-to-today
+     * deadline is "due" and only an earlier one is "overdue"). A content scope
+     * like `tag`: it narrows, never lifts a default, and composes as AND with
+     * `tag`/`untagged`. The boundary rides the view's injected clock (see
+     * {@link OVERDUE}). Honored by the current-work views (today, inbox, anytime,
+     * someday, search); the forward-looking `upcoming` and the closed-item
+     * `logbook` deliberately do not accept it (see docs/design/cli-grammar.md).
+     */
+    overdue?: boolean;
 }
+/**
+ * Compose the tag scope for a filter into an AND-chained SQL fragment plus its
+ * binds. Every clause AND-combines: the `untagged` negation and each `--tag`
+ * ref (each ref independently resolved and descendant-expanded per `exactTag`).
+ * The mutually-exclusive combination (`untagged` with a tag-presence flag) is
+ * refused at the CLI/MCP surfaces; here it would simply AND to an empty result.
+ * Splices in before {@link overdueFilter} so the tag binds precede the overdue
+ * bind.
+ *
+ * `options.container` selects the CONTAINER semantics (`project show` /
+ * `area show` / the `projects` list): the view's own inheritance hop is dropped,
+ * so `--tag` matches a DIRECT assignment (still descendant-expanded) and
+ * `--untagged` means "no direct tag". Every child inherits its container's tags,
+ * so an inheritance-inclusive filter there is vacuous — direct-on-the-row is the
+ * useful, GUI-faithful behavior. FLAT views omit the option and keep the
+ * inheritance-inclusive relation.
+ */
+export declare function tagFilter(db: DatabaseSync, filter: ViewFilter | undefined, options?: {
+    container?: boolean;
+}): {
+    sql: string;
+    binds: string[];
+};
 export interface TodayView {
     today: ListItem[];
     evening: ListItem[];
@@ -73,8 +165,28 @@ export interface TodayView {
         other: number;
     };
 }
-export declare function todayView(db: DatabaseSync, now?: Date, filter?: ViewFilter): TodayView;
-export declare function inboxView(db: DatabaseSync, filter?: ViewFilter): ListItem[];
+export interface TodayFilter extends ViewFilter {
+    /**
+     * Restrict to the This-Evening section: the Today section is filtered out
+     * (returned empty) and the badge counts only the evening members. A section
+     * visibility toggle, not a volume change — the row limit still applies.
+     */
+    eveningOnly?: boolean;
+}
+export declare function todayView(db: DatabaseSync, now?: Date, filter?: TodayFilter): TodayView;
+export interface InboxFilter extends ViewFilter {
+    /**
+     * Only captures created at/after this instant. Keyed on the item's CREATION
+     * timestamp (the raw Cocoa/Unix-epoch creationDate, compared like
+     * `changes`/`logbook` do their epoch columns — NOT the packed startDate
+     * encoding). A demoted item keeps its original creation date, so this is
+     * arrival-into-Things, not arrival-into-the-Inbox.
+     */
+    since?: Date;
+    /** Only captures created at/before this instant (creation timestamp). */
+    until?: Date;
+}
+export declare function inboxView(db: DatabaseSync, now?: Date, filter?: InboxFilter): ListItem[];
 /**
  * One sidebar-ordered block of a grouped view (anytime/someday): the area
  * (null = the top-level, area-less block, which the UI renders first) and its
@@ -86,7 +198,19 @@ export interface SidebarSection {
     items: ListItem[];
 }
 export declare function anytimeView(db: DatabaseSync, now?: Date, filter?: ViewFilter): SidebarSection[];
-/** The UI's star marker in Anytime: the item is also a Today member. */
+/**
+ * The UI's star marker in Anytime: the item is also a Today member. Mirrors
+ * {@link todayView}'s two membership arms so an unscheduled item pulled into
+ * Today by a due deadline stars exactly like a scheduled one:
+ *   - SCHEDULED — a When-date that has arrived (startDate <= today); or
+ *   - DEADLINE-DRIVEN — no When-date, but a due/overdue deadline (deadline <=
+ *     today) pulls it into Today (the todayView arm that lets a bare deadline
+ *     surface an item). Only reached for anytime-visible rows (start=1,
+ *     startDate NULL), so it never over-stars someday/inbox rows.
+ * KNOWN LIMITATION: todayView's deadline arm also drops a DISMISSED-nag
+ * deadline (deadlineSuppressionDate >= deadline); that column is not surfaced
+ * on the entity, so a suppressed unscheduled overdue row is over-starred here.
+ */
 export declare function isTodayMember(item: ListItem, now?: Date): boolean;
 export interface UpcomingFilter extends ViewFilter {
     /** Include repeating templates' next occurrences (UI parity; default true). */
@@ -105,6 +229,12 @@ export interface UpcomingFilter extends ViewFilter {
      * a date bound cannot apply to rows with no date.
      */
     until?: IsoDate;
+    /**
+     * Only rows scheduled on/after this date (inclusive) — skip occurrences
+     * before it. The dateless resting templates always survive, as with
+     * `until` (a date bound cannot apply to rows with no date).
+     */
+    since?: IsoDate;
 }
 export declare function upcomingView(db: DatabaseSync, now?: Date, filter?: UpcomingFilter): ListItem[];
 export interface SomedayFilter extends ViewFilter {
@@ -118,7 +248,8 @@ export interface SomedayFilter extends ViewFilter {
 }
 export declare function somedayView(db: DatabaseSync, now?: Date, filter?: SomedayFilter): SidebarSection[];
 export interface LogbookFilter extends ViewFilter {
-    limit?: number;
+    /** Row cap; `null` returns every match (surfaces slice for display). */
+    limit?: number | null;
     /**
      * Area scope: the area's direct items, its project rows, and every to-do
      * of its projects — INCLUDING heading-nested ones (heading → project →
@@ -132,17 +263,19 @@ export interface LogbookFilter extends ViewFilter {
     /** Only entries logged at/before this instant. */
     until?: Date;
 }
-export declare function logbookView(db: DatabaseSync, options?: LogbookFilter): ListItem[];
-export declare function trashView(db: DatabaseSync, options?: {
-    limit?: number;
+export declare function logbookView(db: DatabaseSync, now?: Date, options?: LogbookFilter): ListItem[];
+export declare function trashView(db: DatabaseSync, now?: Date, options?: {
+    limit?: number | null;
 }): ListItem[];
 export declare function projectsView(db: DatabaseSync, options?: {
     areaUuid?: string;
     later?: boolean;
+    overdue?: boolean;
     now?: Date;
-}): Project[];
+} & ViewFilter): Project[];
 export interface SearchOptions extends ViewFilter {
-    limit?: number;
+    /** Row cap; `null` returns every match (surfaces slice for display). */
+    limit?: number | null;
     /** Restrict to one project's children (headed children included). */
     project?: string;
     /** Restrict to one area's direct members. */
@@ -167,8 +300,33 @@ export type ChangedItem = ListItem & {
  * carry no modification dates, and checklist-item edits do not bump the
  * parent task — those changes are invisible here.
  */
-export declare function changesView(db: DatabaseSync, options: {
+export declare function changesView(db: DatabaseSync, now: Date | undefined, options: {
     since: Date;
-    limit?: number;
+    limit?: number | null;
 }): ChangedItem[];
-export declare function searchView(db: DatabaseSync, query: string, options?: SearchOptions): ListItem[];
+/** One did-you-mean candidate: an area, or a task (project / to-do). */
+export type LiteCandidate = {
+    kind: "area";
+    area: Area;
+} | {
+    kind: "task";
+    task: ListItem;
+};
+export interface LiteSearchResult {
+    /** Ordered (containers first, then to-dos; within a group: active before someday, then most-recently-modified) and capped. */
+    candidates: LiteCandidate[];
+    /** Total matches before the cap. */
+    total: number;
+}
+export declare function liteTitleSearch(db: DatabaseSync, query: string, options?: {
+    type?: "to-do" | "project" | "area";
+    limit?: number;
+}, now?: Date): LiteSearchResult;
+/** A search result annotated with WHY it surfaced (additive; `matchedVia` present only for heading-credited projects). */
+export type SearchResultItem = ListItem & {
+    matchedVia?: {
+        kind: "heading";
+        title: string;
+    };
+};
+export declare function searchView(db: DatabaseSync, query: string, options?: SearchOptions, now?: Date): SearchResultItem[];