@kernhq/module-tracker 0.1.0 → 0.1.2

package/src/kql/ast.ts

@@ -0,0 +1,136 @@
+/**
+ * KQL — Kern Query Language (JQL-like) abstract syntax tree.
+ * Produced by `parse()`, consumed by the SQL compiler and the visual filter builder.
+ */
+
+export type KqlOp =
+  | '='
+  | '!='
+  | '<'
+  | '<='
+  | '>'
+  | '>='
+  | '~'
+  | '!~'
+  | 'in'
+  | 'not-in'
+  | 'is-empty'
+  | 'is-not-empty'
+
+export interface Span {
+  start: number
+  end: number
+}
+
+export type KqlValue =
+  | { kind: 'string'; value: string; span: Span }
+  | { kind: 'number'; value: number; span: Span }
+  | { kind: 'date'; value: string; span: Span }
+  /** relative date `-7d` / `+2w`; units d(ay) w(eek) m(onth) y(ear), h(our) */
+  | { kind: 'reldate'; amount: number; unit: 'h' | 'd' | 'w' | 'm' | 'y'; span: Span }
+  | { kind: 'bool'; value: boolean; span: Span }
+  | { kind: 'null'; span: Span }
+  /** bareword like `done` or `high` */
+  | { kind: 'ident'; value: string; span: Span }
+  /** function call: currentUser(), membersOf("qa"), startOfWeek(-1) */
+  | { kind: 'func'; name: string; args: KqlValue[]; span: Span }
+
+export type KqlExpr =
+  | { kind: 'and'; children: KqlExpr[]; span: Span }
+  | { kind: 'or'; children: KqlExpr[]; span: Span }
+  | { kind: 'not'; child: KqlExpr; span: Span }
+  | KqlComparison
+
+export interface KqlComparison {
+  kind: 'cmp'
+  field: string
+  op: KqlOp
+  /** absent for is-empty / is-not-empty */
+  value: KqlValue | null
+  /** list for in / not-in */
+  values: KqlValue[] | null
+  span: Span
+}
+
+export interface KqlOrder {
+  field: string
+  dir: 'asc' | 'desc'
+  span: Span
+}
+
+export interface KqlQuery {
+  where: KqlExpr | null
+  orderBy: KqlOrder[]
+}
+
+/** Walk every comparison in an expression. */
+export function walkComparisons(expr: KqlExpr | null, fn: (cmp: KqlComparison) => void): void {
+  if (!expr) return
+  if (expr.kind === 'cmp') fn(expr)
+  else if (expr.kind === 'not') walkComparisons(expr.child, fn)
+  else for (const c of expr.children) walkComparisons(c, fn)
+}
+
+/** Collect field names used in where + order by. */
+export function fieldsUsed(query: KqlQuery): string[] {
+  const out = new Set<string>()
+  walkComparisons(query.where, (c) => out.add(c.field))
+  for (const o of query.orderBy) out.add(o.field)
+  return [...out]
+}
+
+/** Pretty-print a value back to KQL text. */
+export function printValue(v: KqlValue): string {
+  switch (v.kind) {
+    case 'string':
+      return JSON.stringify(v.value)
+    case 'number':
+      return String(v.value)
+    case 'date':
+      return v.value
+    case 'reldate':
+      return `${v.amount >= 0 ? '+' : ''}${v.amount}${v.unit}`
+    case 'bool':
+      return v.value ? 'true' : 'false'
+    case 'null':
+      return 'null'
+    case 'ident':
+      return /^[A-Za-z0-9_.-]+$/.test(v.value) ? v.value : JSON.stringify(v.value)
+    case 'func':
+      return `${v.name}(${v.args.map(printValue).join(', ')})`
+  }
+}
+
+/** Pretty-print a whole query (normalised form). */
+export function printQuery(query: KqlQuery): string {
+  const expr = (e: KqlExpr, parent?: 'and' | 'or'): string => {
+    switch (e.kind) {
+      case 'cmp': {
+        if (e.op === 'is-empty') return `${e.field} is empty`
+        if (e.op === 'is-not-empty') return `${e.field} is not empty`
+        if (e.op === 'in' || e.op === 'not-in')
+          return `${e.field} ${e.op === 'in' ? 'in' : 'not in'} (${(e.values ?? []).map(printValue).join(', ')})`
+        return `${e.field} ${e.op} ${e.value ? printValue(e.value) : ''}`.trim()
+      }
+      case 'not': {
+        const inner = expr(e.child)
+        return e.child.kind === 'cmp' ? `not ${inner}` : `not (${inner})`
+      }
+      case 'and': {
+        const s = e.children.map((c) => expr(c, 'and')).join(' and ')
+        return parent === 'or' ? s : s
+      }
+      case 'or': {
+        const s = e.children.map((c) => expr(c, 'or')).join(' or ')
+        return parent === 'and' ? `(${s})` : s
+      }
+    }
+  }
+  const parts: string[] = []
+  if (query.where) parts.push(expr(query.where))
+  if (query.orderBy.length)
+    parts.push(
+      `order by ${query.orderBy.map((o) => `${o.field}${o.dir === 'desc' ? ' desc' : ''}`).join(', ')}`,
+    )
+  return parts.join(' ')
+}

package/src/kql/dates.ts

@@ -0,0 +1,62 @@
+/**
+ * Date maths for KQL literals and functions. Everything is computed in UTC: the tracker stores
+ * timestamps with time zone, and a query must mean the same thing wherever it runs.
+ */
+
+export type RelUnit = 'h' | 'd' | 'w' | 'm' | 'y'
+
+const DAY_MS = 86_400_000
+
+/** Apply a relative offset (`-7d`, `+2w`) to a base instant. */
+export function shift(base: Date, amount: number, unit: RelUnit): Date {
+  const d = new Date(base.getTime())
+  switch (unit) {
+    case 'h':
+      return new Date(d.getTime() + amount * 3_600_000)
+    case 'd':
+      return new Date(d.getTime() + amount * DAY_MS)
+    case 'w':
+      return new Date(d.getTime() + amount * 7 * DAY_MS)
+    case 'm': {
+      const target = new Date(d.getTime())
+      const day = target.getUTCDate()
+      target.setUTCDate(1)
+      target.setUTCMonth(target.getUTCMonth() + Math.trunc(amount))
+      // clamp (31 Jan + 1m → 28/29 Feb)
+      const lastDay = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate()
+      target.setUTCDate(Math.min(day, lastDay))
+      return target
+    }
+    case 'y': {
+      const target = new Date(d.getTime())
+      target.setUTCFullYear(target.getUTCFullYear() + Math.trunc(amount))
+      return target
+    }
+  }
+}
+
+export function startOfDay(base: Date, offsetDays = 0): Date {
+  const d = new Date(base.getTime() + offsetDays * DAY_MS)
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()))
+}
+
+/** Start of the ISO week (Monday) containing `base`, shifted by `offsetWeeks`. */
+export function startOfWeek(base: Date, offsetWeeks = 0, weekStartsOn = 1): Date {
+  const day = startOfDay(base)
+  const diff = (day.getUTCDay() - weekStartsOn + 7) % 7
+  return new Date(day.getTime() - diff * DAY_MS + offsetWeeks * 7 * DAY_MS)
+}
+
+export function startOfMonth(base: Date, offsetMonths = 0): Date {
+  return new Date(Date.UTC(base.getUTCFullYear(), base.getUTCMonth() + offsetMonths, 1))
+}
+
+/** `YYYY-MM-DD` in UTC. */
+export const dateOnly = (d: Date): string => d.toISOString().slice(0, 10)
+
+/** Parse a KQL date literal (`2026-08-22` or a full ISO timestamp) into an instant. */
+export function parseDateLiteral(value: string): Date | null {
+  const iso = /^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00.000Z` : value.replace(' ', 'T')
+  const d = new Date(iso)
+  return Number.isNaN(d.getTime()) ? null : d
+}

package/src/kql/fields.ts

@@ -0,0 +1,150 @@
+import type { FieldType } from '../contract/models.js'
+import type { KqlOp } from './ast.js'
+
+export type KqlFieldKind =
+  | 'text'
+  | 'enum'
+  | 'user'
+  | 'number'
+  | 'date'
+  | 'datetime'
+  | 'boolean'
+  | 'ref'
+  | 'id'
+  | 'key'
+
+export interface KqlField {
+  name: string
+  kind: KqlFieldKind
+  label: string
+  /** value is a uuid[] column (membership semantics for = / in) */
+  array?: boolean
+  sortable?: boolean
+  /** enum values for autocomplete/validation */
+  enumValues?: readonly string[]
+  /** ref fields resolve barewords/strings by name via the resolver (labels, cycles…) */
+  refType?:
+    | 'project'
+    | 'type'
+    | 'label'
+    | 'component'
+    | 'version'
+    | 'cycle'
+    | 'milestone'
+    | 'status'
+    | 'issue'
+  custom?: { key: string; fieldType: FieldType }
+}
+
+const EQ: KqlOp[] = ['=', '!=', 'in', 'not-in']
+const EMPTY: KqlOp[] = ['is-empty', 'is-not-empty']
+const CMP: KqlOp[] = ['<', '<=', '>', '>=']
+const LIKE: KqlOp[] = ['~', '!~']
+
+export function operatorsFor(f: KqlField): KqlOp[] {
+  switch (f.kind) {
+    case 'text':
+      return [...LIKE, '=', '!=', ...EMPTY]
+    case 'enum':
+      return [...EQ, ...CMP, ...EMPTY]
+    case 'user':
+      return [...EQ, ...EMPTY]
+    case 'number':
+      return ['=', '!=', ...CMP, 'in', 'not-in', ...EMPTY]
+    case 'date':
+    case 'datetime':
+      return ['=', '!=', ...CMP, ...EMPTY]
+    case 'boolean':
+      return ['=', '!=']
+    case 'ref':
+    case 'id':
+      return [...EQ, ...EMPTY]
+    case 'key':
+      return [...EQ, ...LIKE]
+  }
+}
+
+export const PRIORITIES = ['none', 'low', 'medium', 'high', 'urgent'] as const
+export const STATUS_CATEGORIES = ['backlog', 'todo', 'in_progress', 'done', 'cancelled', 'triage'] as const
+
+/** System fields available in every KQL query. Custom fields are added as `cf.<key>`. */
+export const SYSTEM_FIELDS: readonly KqlField[] = [
+  { name: 'key', kind: 'key', label: 'Issue key', sortable: true },
+  { name: 'project', kind: 'ref', refType: 'project', label: 'Project', sortable: true },
+  { name: 'type', kind: 'ref', refType: 'type', label: 'Type', sortable: true },
+  { name: 'title', kind: 'text', label: 'Title', sortable: true },
+  { name: 'status', kind: 'ref', refType: 'status', label: 'Status', sortable: true },
+  {
+    name: 'statusCategory',
+    kind: 'enum',
+    label: 'Status category',
+    enumValues: STATUS_CATEGORIES,
+    sortable: true,
+  },
+  { name: 'priority', kind: 'enum', label: 'Priority', enumValues: PRIORITIES, sortable: true },
+  { name: 'assignee', kind: 'user', array: true, label: 'Assignee' },
+  { name: 'reporter', kind: 'user', label: 'Reporter' },
+  { name: 'label', kind: 'ref', refType: 'label', array: true, label: 'Label' },
+  { name: 'component', kind: 'ref', refType: 'component', array: true, label: 'Component' },
+  { name: 'version', kind: 'ref', refType: 'version', array: true, label: 'Fix version' },
+  { name: 'affectsVersion', kind: 'ref', refType: 'version', array: true, label: 'Affects version' },
+  { name: 'cycle', kind: 'ref', refType: 'cycle', label: 'Cycle', sortable: true },
+  { name: 'milestone', kind: 'ref', refType: 'milestone', label: 'Milestone', sortable: true },
+  { name: 'parent', kind: 'ref', refType: 'issue', label: 'Parent', sortable: true },
+  { name: 'created', kind: 'datetime', label: 'Created', sortable: true },
+  { name: 'updated', kind: 'datetime', label: 'Updated', sortable: true },
+  { name: 'completed', kind: 'datetime', label: 'Completed', sortable: true },
+  { name: 'due', kind: 'date', label: 'Due date', sortable: true },
+  { name: 'start', kind: 'date', label: 'Start date', sortable: true },
+  { name: 'estimate', kind: 'number', label: 'Estimate', sortable: true },
+  { name: 'timeSpent', kind: 'number', label: 'Time spent (s)', sortable: true },
+  { name: 'watcher', kind: 'user', array: true, label: 'Watcher' },
+  { name: 'resolution', kind: 'text', label: 'Resolution', sortable: true },
+  { name: 'text', kind: 'text', label: 'Full text' },
+  { name: 'triage', kind: 'boolean', label: 'In triage', sortable: true },
+  { name: 'archived', kind: 'boolean', label: 'Archived' },
+  /** sort-only pseudo field (manual order) */
+  { name: 'rank', kind: 'text', label: 'Manual rank', sortable: true },
+] as const
+
+export const KQL_FUNCTIONS = [
+  { name: 'currentUser', args: 0, detail: 'The authenticated user' },
+  { name: 'now', args: 0, detail: 'Current timestamp' },
+  { name: 'startOfDay', args: '0-1', detail: 'Midnight today (optional day offset)' },
+  { name: 'startOfWeek', args: '0-1', detail: 'Start of this week (optional week offset)' },
+  { name: 'startOfMonth', args: '0-1', detail: 'Start of this month (optional month offset)' },
+  { name: 'membersOf', args: 1, detail: 'Members of a workspace group' },
+  { name: 'activeCycle', args: 0, detail: 'The active cycle(s) of the queried projects' },
+  { name: 'openCycles', args: 0, detail: 'Active + upcoming cycles' },
+] as const
+
+export function findField(fields: readonly KqlField[], name: string): KqlField | undefined {
+  const lower = name.toLowerCase()
+  return fields.find((f) => f.name.toLowerCase() === lower)
+}
+
+/** Map a custom field def to a KQL field (`cf.<key>`). */
+export function customKqlField(key: string, fieldType: FieldType, label: string): KqlField {
+  const kind: KqlFieldKind =
+    fieldType === 'number' || fieldType === 'formula'
+      ? 'number'
+      : fieldType === 'date'
+        ? 'date'
+        : fieldType === 'datetime'
+          ? 'datetime'
+          : fieldType === 'checkbox'
+            ? 'boolean'
+            : fieldType === 'user' || fieldType === 'multiuser'
+              ? 'user'
+              : fieldType === 'select' || fieldType === 'multiselect' || fieldType === 'label'
+                ? 'enum'
+                : 'text'
+  return {
+    name: `cf.${key}`,
+    kind,
+    label,
+    array: fieldType === 'multiselect' || fieldType === 'multiuser' || fieldType === 'label',
+    sortable: kind === 'number' || kind === 'date' || kind === 'datetime' || kind === 'text',
+    custom: { key, fieldType },
+  }
+}

package/src/kql/index.ts

@@ -0,0 +1,15 @@
+/**
+ * KQL — Kern Query Language.
+ *
+ * A JQL-like query language over tracker issues: `assignee = currentUser() and status != done
+ * order by priority desc`. This entry point is isomorphic (no database, no Node built-ins) so the
+ * app can parse, validate and autocomplete a query while the user types; the SQL compiler that turns
+ * a parsed query into a statement lives server-side in `@kernhq/module-tracker/server`.
+ */
+export * from './ast.js'
+export * from './dates.js'
+export * from './fields.js'
+export { type LexError, type LexResult, type Token, type TokenKind, tokenize } from './lexer.js'
+export { type ParseError, type ParseResult, parseKql } from './parser.js'
+export { suggest } from './suggest.js'
+export { type KqlIssue, validateQuery } from './validate.js'