@cavelang/parser 0.1.0

package/src/document.ts

@@ -0,0 +1,190 @@
+/**
+ * Document parser (spec §8, §16).
+ *
+ * Splits input into physical lines, measures indentation, classifies each
+ * line (blank / comment / claim / continuation / qualifier), and resolves
+ * each indented line's parent — the nearest less-indented structural line
+ * above (spec §8).
+ *
+ * Classification of an indented line follows spec §8's table, decided by
+ * what the line starts with:
+ *
+ * - qualifier verb (`WHEN`/`UNLESS`/`VIA`/`BECAUSE`) → qualifier
+ * - bare relational verb → continuation
+ * - full triple → grouped claim
+ *
+ * One ambiguity needs a tiebreak: `API NEEDS auth` starts with a token that
+ * is lexically verb-shaped. If the *second* token is also verb-shaped (and
+ * not `NOT`), the line is a full triple with an uppercase subject —
+ * `CONTAINS REVERSE PART-OF` and `API NEEDS auth` both land here; otherwise
+ * it is a continuation.
+ *
+ * `parseDocument` never throws: broken lines become `invalid` entries and
+ * every problem is a diagnostic. `parse` is the strict variant.
+ */
+
+import { Verb } from '@cavelang/core'
+import type * as Ast from './ast.ts'
+import * as Line from './line.ts'
+import * as Token from './token.ts'
+
+const indentOf = (raw: string): { depth: number, rest: string, tabs: boolean } => {
+  let depth = 0
+  let tabs = false
+  while (depth < raw.length && (raw[depth] === ' ' || raw[depth] === '\t')) {
+    tabs ||= raw[depth] === '\t'
+    depth += 1
+  }
+  return { depth, rest: raw.slice(depth), tabs }
+}
+
+type Classified = 'claim' | 'continuation' | 'qualifier'
+
+const classify = (tokens: readonly Token.t[], depth: number): Classified | { error: string } => {
+  const head = tokens[0]!
+  if (head.kind === 'word' && Verb.isQualifier(head.text)) {
+    return depth > 0 ?
+      'qualifier' :
+      { error: `qualifier verb ${head.text} at top level — qualifiers attach to a parent claim (spec §8.2)` }
+  }
+  if (head.kind === 'word' && Verb.isVerbToken(head.text)) {
+    const second = tokens[1]
+    const secondWord = second?.kind === 'word' ? second.text : undefined
+    // Tiebreak between "continuation" and "full triple with an uppercase
+    // subject", using the known standard vocabulary (see the README):
+    //   CONTAINS REVERSE PART-OF  → claim (declaration)
+    //   NEEDS NOT downtime        → continuation (NOT is a modifier)
+    //   API NEEDS auth            → claim (second token is a known verb)
+    //   USES JWT / PART-OF ORG    → continuation (first known, second not)
+    //   API MIGRATES postgres     → claim (neither known — subject wins)
+    const kind: Classified =
+      secondWord === Verb.REVERSE ? 'claim' :
+      secondWord !== undefined && secondWord !== 'NOT' && Verb.isVerbToken(secondWord) ?
+        (Verb.isKnown(secondWord) ? 'claim' : Verb.isKnown(head.text) ? 'continuation' : 'claim') :
+        'continuation'
+    if (kind === 'continuation' && depth === 0) {
+      return { error: `continuation line at top level — nothing to inherit a subject from (spec §8.3)` }
+    }
+    return kind
+  }
+  return 'claim'
+}
+
+type Frame = { index: number, depth: number }
+
+/**
+ * Parses a CAVE document. Never throws; problems surface as diagnostics and
+ * `invalid` lines.
+ */
+export const parseDocument = (input: string): Ast.Document => {
+  const lines: Ast.Line[] = []
+  const diagnostics: Ast.Diagnostic[] = []
+  const stack: Frame[] = []
+  const rawLines = input.split(/\r?\n/)
+  const problem = (line: number, raw: string, message: string): void => {
+    diagnostics.push({ line, message, raw })
+  }
+  rawLines.forEach((raw, at) => {
+    const lineNo = at + 1
+    const { depth, rest, tabs } = indentOf(raw)
+    if (tabs) {
+      problem(lineNo, raw, 'tab in indentation — use spaces')
+    }
+    if (rest === '') {
+      lines.push({ kind: 'blank', line: lineNo, raw })
+      return
+    }
+    if (rest.startsWith(';')) {
+      lines.push({ kind: 'comment', line: lineNo, raw, text: rest.slice(1).trim() })
+      return
+    }
+    const { head, comment } = Token.splitComment(rest)
+    const tokens = Token.tokenize(head)
+    if (tokens.length === 0) {
+      lines.push({ kind: 'comment', line: lineNo, raw, text: comment ?? '' })
+      return
+    }
+    const kind = classify(tokens, depth)
+    if (typeof kind === 'object') {
+      problem(lineNo, raw, kind.error)
+      lines.push({ kind: 'invalid', line: lineNo, raw, message: kind.error })
+      return
+    }
+    while (stack.length > 0 && stack[stack.length - 1]!.depth >= depth) {
+      stack.pop()
+    }
+    const parent = stack[stack.length - 1]?.index
+    if (parent === undefined && kind !== 'claim') {
+      const message = `${kind} line has no parent claim above (spec §8)`
+      problem(lineNo, raw, message)
+      lines.push({ kind: 'invalid', line: lineNo, raw, message })
+      return
+    }
+    const index = lines.length
+    const push = (line: Ast.Line, problems: readonly string[]): void => {
+      lines.push(line)
+      stack.push({ index, depth })
+      for (const message of problems) {
+        problem(lineNo, raw, message)
+      }
+    }
+    switch (kind) {
+      case 'claim': {
+        const result = Line.parseClaim(tokens, comment)
+        if (!result.ok) {
+          problem(lineNo, raw, result.message)
+          lines.push({ kind: 'invalid', line: lineNo, raw, message: result.message })
+          return
+        }
+        push(
+          { kind: 'claim', line: lineNo, raw, depth, ...parent !== undefined ? { parent } : {}, claim: result.value },
+          result.problems
+        )
+        return
+      }
+      case 'continuation': {
+        const result = Line.parseBody(tokens, comment)
+        if (!result.ok) {
+          problem(lineNo, raw, result.message)
+          lines.push({ kind: 'invalid', line: lineNo, raw, message: result.message })
+          return
+        }
+        push(
+          { kind: 'continuation', line: lineNo, raw, depth, parent: parent!, body: result.value },
+          result.problems
+        )
+        return
+      }
+      case 'qualifier': {
+        const qualifier = (tokens[0] as { text: string }).text as Verb.Qualifier
+        const result = Line.parseQualifierPayload(tokens.slice(1), comment)
+        if (!result.ok) {
+          problem(lineNo, raw, result.message)
+          lines.push({ kind: 'invalid', line: lineNo, raw, message: result.message })
+          return
+        }
+        push(
+          { kind: 'qualifier', line: lineNo, raw, depth, parent: parent!, qualifier, payload: result.value },
+          result.problems
+        )
+        return
+      }
+    }
+  })
+  return { lines, diagnostics }
+}
+
+/**
+ * Strict parse: like {@link parseDocument} but throws an `Error` listing
+ * every diagnostic when the document has any.
+ */
+export const parse = (input: string): readonly Ast.Line[] => {
+  const { lines, diagnostics } = parseDocument(input)
+  if (diagnostics.length > 0) {
+    const detail = diagnostics
+      .map(diagnostic => `  line ${diagnostic.line}: ${diagnostic.message}`)
+      .join('\n')
+    throw new Error(`CAVE parse failed with ${diagnostics.length} problem(s):\n${detail}`)
+  }
+  return lines
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `@cavelang/parser` — CAVE text → AST (spec §3, §4, §8, §16).
+ *
+ * Line-oriented parser for the normative CAVE language, built on
+ * `@prelude/parser` combinators. Produces pure syntax: inverse verbs,
+ * continuations and `UNLESS` are resolved later by `@cavelang/canonical`
+ * (spec §13.4).
+ *
+ * ```ts
+ * import { parseDocument } from '@cavelang/parser'
+ *
+ * const { lines, diagnostics } = parseDocument('auth/middleware USES jwt @ 90%')
+ * ```
+ */
+
+export * as Ast from './ast.ts'
+export * as Line from './line.ts'
+export * as Token from './token.ts'
+export { parseDocument, parse } from './document.ts'

package/src/line.ts

@@ -0,0 +1,335 @@
+/**
+ * Token-stream line parser (spec §3.2, §16).
+ *
+ * Parses the token list of one line into claim/continuation/qualifier
+ * bodies. The payload/metadata boundary is decided lexically: metadata items
+ * are unambiguous at their first token (spec §4.3 reserved characters), so
+ * everything before the first metadata token is payload.
+ */
+
+import { Claim, Confidence, Tag, Value, Verb } from '@cavelang/core'
+import type * as Ast from './ast.ts'
+import type { Token } from './token.ts'
+
+export type Result<T> =
+  | { readonly ok: true, readonly value: T, readonly problems: readonly string[] }
+  | { readonly ok: false, readonly message: string }
+
+const ok = <T>(value: T, problems: readonly string[] = []): Result<T> =>
+  ({ ok: true, value, problems })
+
+const fail = (message: string): Result<never> =>
+  ({ ok: false, message })
+
+const sigmaRe = /^\((\d+(?:\.\d+)?)σ\)$/u
+
+/** @returns `true` if `token` starts a metadata item (spec §4.3). */
+export const isMetaStart = (token: Token): boolean =>
+  token.kind === 'word' && (
+    token.text.startsWith('@') ||
+    token.text.startsWith('#') ||
+    token.text.startsWith('+/-') ||
+    token.text === '!' ||
+    sigmaRe.test(token.text)
+  )
+
+/** @returns term from a single token (spec §16: atom, literal or code literal). */
+const term = (token: Token): Claim.Term => {
+  switch (token.kind) {
+    case 'text':
+      return Claim.text(token.text)
+    case 'code':
+      return Claim.code(token.text)
+    default:
+      return Claim.entity(token.text)
+  }
+}
+
+/** @returns value from payload value tokens (attribute value or metric). */
+const valueOf = (tokens: readonly Token[]): undefined | Value.t => {
+  if (tokens.length === 0) {
+    return undefined
+  }
+  const [head] = tokens
+  if (tokens.length === 1 && head!.kind === 'text') {
+    return Value.ofText(head!.text)
+  }
+  if (tokens.length === 1 && head!.kind === 'code') {
+    return Value.ofCode(head!.text)
+  }
+  if (tokens.some(token => token.kind !== 'word')) {
+    return undefined
+  }
+  return Value.parse(tokens.map(token => token.text).join(' '))
+}
+
+/**
+ * Parses metadata tokens (spec §6). Never fails — unrecognized tokens are
+ * reported as problems and skipped, honoring the robust-extraction goal
+ * (spec §1.6).
+ */
+export const parseMeta = (tokens: readonly Token[], comment?: string): { meta: Ast.Meta, problems: string[] } => {
+  const contexts: string[] = []
+  const tags: Tag.t[] = []
+  const problems: string[] = []
+  let conf: undefined | number
+  let importance = false
+  let delta: undefined | Value.t
+  let sigmaLevel: undefined | number
+  let i = 0
+  const collectValueTokens = (): Token[] => {
+    const collected: Token[] = []
+    while (i < tokens.length && !isMetaStart(tokens[i]!) && tokens[i]!.kind === 'word') {
+      collected.push(tokens[i]!)
+      i += 1
+    }
+    return collected
+  }
+  while (i < tokens.length) {
+    const token = tokens[i]!
+    i += 1
+    if (token.kind !== 'word') {
+      problems.push(`unexpected literal ${JSON.stringify(token.text)} in metadata position`)
+      continue
+    }
+    const word = token.text
+    if (word === '@') {
+      const next = tokens[i]
+      const text = next?.kind === 'word' ? next.text : undefined
+      const parsed = text === undefined ? undefined : Confidence.parse(text)
+      if (parsed === undefined) {
+        // Consume a number-like token so `@ 90` / `@ 2026` yield one clear
+        // problem instead of a cascade (§6.3: confidence must end in %).
+        if (text !== undefined && /^\d/.test(text)) {
+          i += 1
+        }
+        problems.push(`expected percentage ending in % after "@ "${text === undefined ? '' : `, got ${JSON.stringify(text)}`} (spec §6.3)`)
+        continue
+      }
+      i += 1
+      if (Number(text!.slice(0, -1)) > 100) {
+        problems.push(`confidence ${text} above 100% clamped (spec §6.3)`)
+      }
+      if (conf !== undefined) {
+        problems.push('repeated confidence — only contexts and tags may repeat (spec §3.2); last one wins')
+      }
+      conf = parsed
+      continue
+    }
+    if (word.startsWith('@')) {
+      contexts.push(word.slice(1))
+      continue
+    }
+    if (word === '#') {
+      problems.push('empty tag')
+      continue
+    }
+    if (word.startsWith('#')) {
+      tags.push(Tag.parse(word.slice(1)))
+      continue
+    }
+    if (word.startsWith('+/-')) {
+      const glued = word.slice('+/-'.length)
+      const collected = collectValueTokens().map(token_ => token_.text)
+      const raw = [...glued === '' ? [] : [glued], ...collected].join(' ')
+      if (raw === '') {
+        problems.push('expected value after +/- (spec §7.2)')
+        continue
+      }
+      if (delta !== undefined) {
+        problems.push('repeated +/- uncertainty — only contexts and tags may repeat (spec §3.2); last one wins')
+      }
+      delta = Value.parse(raw)
+      continue
+    }
+    const sigma = sigmaRe.exec(word)
+    if (sigma) {
+      if (sigmaLevel !== undefined) {
+        problems.push('repeated (Nσ) level — only contexts and tags may repeat (spec §3.2); last one wins')
+      }
+      sigmaLevel = Number(sigma[1])
+      continue
+    }
+    if (word === '!') {
+      if (importance) {
+        problems.push('repeated ! importance marker (spec §3.2)')
+      }
+      importance = true
+      continue
+    }
+    problems.push(`unexpected token ${JSON.stringify(word)} after payload`)
+  }
+  return {
+    meta: {
+      contexts,
+      tags,
+      importance,
+      ...conf !== undefined ? { conf } : {},
+      ...delta !== undefined ? { delta } : {},
+      ...sigmaLevel !== undefined ? { sigmaLevel } : {},
+      ...comment !== undefined ? { comment } : {}
+    },
+    problems
+  }
+}
+
+/** Splits tokens at the first metadata token. */
+const splitAtMeta = (tokens: readonly Token[]): { payload: readonly Token[], meta: readonly Token[] } => {
+  const at = tokens.findIndex(isMetaStart)
+  return at === -1 ?
+    { payload: tokens, meta: [] } :
+    { payload: tokens.slice(0, at), meta: tokens.slice(at) }
+}
+
+/**
+ * Parses payload tokens (spec §16 `payload`):
+ *
+ * - `attr: value` — attribute claim; the colon is canonical (spec §3.4)
+ * - legacy colonless `HAS attr value` when the value is numeric/date-like
+ * - numeric/date value — metric claim (`latency IS 30ms`; also the shape a
+ *   comparison condition canonicalizes to, e.g. `load EXCEEDS 1000 req/s`,
+ *   which keeps `WHERE value > …` filters queryable, spec §12.2)
+ * - empty — bare existence, `EXISTS` only
+ * - otherwise — relational object (single term or multi-word phrase)
+ */
+const parsePayload = (verb: string, tokens: readonly Token[]): Result<Claim.Payload> => {
+  if (tokens.length === 0) {
+    return verb === 'EXISTS' ?
+      ok(Claim.none) :
+      fail(`missing object after ${verb} (the minimum line is "entity VERB object", spec §2.2)`)
+  }
+  const [head, ...rest] = tokens
+  if (head!.kind === 'word' && head!.text.endsWith(':') && head!.text.length > 1) {
+    const attribute = head!.text.slice(0, -1)
+    const value = valueOf(rest)
+    if (value === undefined) {
+      return fail(`missing or mixed value after attribute ${JSON.stringify(attribute)} (spec §3.4)`)
+    }
+    return ok(Claim.attribute(attribute, value))
+  }
+  if (head!.kind === 'word') {
+    // Glued colon: `expiry:3600s`. The payload `:` is reserved as the
+    // attribute/value separator (spec §4.3) — split it, keep a diagnostic.
+    const colonAt = head!.text.indexOf(':')
+    if (colonAt > 0 && colonAt < head!.text.length - 1) {
+      const attribute = head!.text.slice(0, colonAt)
+      const value = valueOf([{ kind: 'word', text: head!.text.slice(colonAt + 1) }, ...rest])
+      if (value !== undefined) {
+        return ok(
+          Claim.attribute(attribute, value),
+          [`glued attribute colon; canonical is "${attribute}: ${value.raw}" — quote the object for a literal : (spec §3.4, §4.3)`]
+        )
+      }
+    }
+  }
+  if (verb === 'HAS' && rest.length > 0 && head!.kind === 'word') {
+    const value = valueOf(rest)
+    if (value !== undefined && (value.kind === 'number' || value.kind === 'date')) {
+      return ok(
+        Claim.attribute(head!.text, value),
+        [`legacy colonless attribute form; canonical is "${head!.text}: ${value.raw}" (spec §3.4)`]
+      )
+    }
+  }
+  {
+    const value = valueOf(tokens)
+    if (value !== undefined && (value.kind === 'number' || value.kind === 'date')) {
+      return ok(Claim.metric(value))
+    }
+  }
+  if (tokens.length === 1) {
+    return ok(Claim.relation(term(head!)))
+  }
+  if (tokens.every(token => token.kind === 'word')) {
+    return ok(Claim.relation(Claim.entity(tokens.map(token => token.text).join(' '))))
+  }
+  return fail('object phrase mixes words and literals — quote the whole object (spec §4.3)')
+}
+
+/** Parses `verb [NOT] payload metadata` — a continuation body (spec §8.3). */
+export const parseBody = (tokens: readonly Token[], comment?: string): Result<Ast.Body> => {
+  const [head, ...rest] = tokens
+  if (head === undefined || head.kind !== 'word' || !Verb.isVerbToken(head.text)) {
+    return fail(`expected an UPPERCASE verb, got ${JSON.stringify(head?.text ?? 'end of line')}`)
+  }
+  const verb = head.text
+  const negated = rest[0]?.kind === 'word' && rest[0].text === 'NOT'
+  const afterNot = negated ? rest.slice(1) : rest
+  const { payload, meta } = splitAtMeta(afterNot)
+  const payloadResult = parsePayload(verb, payload)
+  if (!payloadResult.ok) {
+    return payloadResult
+  }
+  const parsedMeta = parseMeta(meta, comment)
+  return ok(
+    { verb, negated, payload: payloadResult.value, meta: parsedMeta.meta },
+    [...payloadResult.problems, ...parsedMeta.problems]
+  )
+}
+
+/** Parses `subject verb [NOT] payload metadata` — a full claim line (spec §16). */
+export const parseClaim = (tokens: readonly Token[], comment?: string): Result<Ast.Full> => {
+  const [head, ...rest] = tokens
+  if (head === undefined) {
+    return fail('empty claim line')
+  }
+  if (isMetaStart(head)) {
+    return fail(`expected a subject, got ${JSON.stringify(head.text)}`)
+  }
+  const body = parseBody(rest, comment)
+  if (!body.ok) {
+    return body
+  }
+  return ok({ subject: term(head), ...body.value }, body.problems)
+}
+
+const isComparisonOp = (text: string): text is Ast.ComparisonOp =>
+  (['>', '<', '>=', '<=', '=', '!='] as const).includes(text as Ast.ComparisonOp)
+
+/**
+ * Parses a qualifier payload (spec §8.2): a full claim, a comparison, or a
+ * bare entity — tried in that order.
+ */
+export const parseQualifierPayload = (tokens: readonly Token[], comment?: string): Result<Ast.QualifierPayload> => {
+  const negated = tokens[0]?.kind === 'word' && tokens[0].text === 'NOT'
+  const rest = negated ? tokens.slice(1) : tokens
+  const [head, second] = rest
+  if (head === undefined) {
+    return fail('empty qualifier payload')
+  }
+  if (
+    second?.kind === 'word' &&
+    Verb.isVerbToken(second.text) &&
+    second.text !== 'NOT' &&
+    !isMetaStart(head)
+  ) {
+    const claim = parseClaim(rest, comment)
+    if (!claim.ok) {
+      return claim
+    }
+    return ok({ kind: 'claim', negated, claim: claim.value }, claim.problems)
+  }
+  if (second?.kind === 'word' && isComparisonOp(second.text)) {
+    const { payload, meta } = splitAtMeta(rest.slice(2))
+    const value = valueOf(payload)
+    if (value === undefined) {
+      return fail(`missing value after comparison operator ${second.text}`)
+    }
+    const parsedMeta = parseMeta(meta, comment)
+    return ok(
+      { kind: 'comparison', negated, left: term(head), op: second.text, value, meta: parsedMeta.meta },
+      parsedMeta.problems
+    )
+  }
+  if (isMetaStart(head)) {
+    return fail(`expected qualifier payload, got ${JSON.stringify(head.text)}`)
+  }
+  const parsedMeta = parseMeta(rest.slice(1), comment)
+  if (rest.length > 1 && !isMetaStart(rest[1]!)) {
+    return fail('cannot parse qualifier payload as claim, comparison or entity')
+  }
+  return ok(
+    { kind: 'entity', negated, term: term(head), meta: parsedMeta.meta },
+    parsedMeta.problems
+  )
+}

package/src/token.ts

@@ -0,0 +1,80 @@
+/**
+ * Line tokenizer (spec §4).
+ *
+ * Splits one line (indentation and comment already removed) into tokens:
+ * backticked code literals, double-quoted text literals, and whitespace
+ * separated words. Built on `@prelude/parser` combinators.
+ *
+ * Literals contain no escape sequences (the spec defines none) — a quoted
+ * token runs to the next matching delimiter. An unterminated delimiter
+ * degrades gracefully: the raw text is consumed as an ordinary word.
+ */
+
+import * as P from '@prelude/parser'
+
+export type Token =
+  | { readonly kind: 'word', readonly text: string }
+  | { readonly kind: 'text', readonly text: string }
+  | { readonly kind: 'code', readonly text: string }
+
+export type t = Token
+
+export const word = (text: string): Token =>
+  ({ kind: 'word', text })
+
+export const text = (value: string): Token =>
+  ({ kind: 'text', text: value })
+
+export const code = (value: string): Token =>
+  ({ kind: 'code', text: value })
+
+const codeToken: P.Parser<Token> =
+  P.map(P.seq(P.lit('`'), P.whileNotChars('`'), P.lit('`')), ([, body]) => code(body))
+
+const textToken: P.Parser<Token> =
+  P.map(P.seq(P.lit('"'), P.whileNotChars('"'), P.lit('"')), ([, body]) => text(body))
+
+const wordToken: P.Parser<Token> =
+  P.map(P.whileNotChars(' \t', 1), word)
+
+const anyToken: P.Parser<Token> =
+  P.first(codeToken, textToken, wordToken)
+
+const lineTokens: P.Parser<Token[]> =
+  P.map(
+    P.seq(P.star(P.map(P.seq(P.ws0, anyToken), ([, token]) => token)), P.ws0),
+    ([tokens]) => tokens
+  )
+
+/** @returns tokens of a single line. Total — any input tokenizes. */
+export const tokenize = (line: string): Token[] =>
+  P.parse(lineTokens, line)
+
+/**
+ * Splits a line at the first `;` that sits outside quotes and backticks
+ * (spec §6.4). @returns the head and the trimmed comment text, `undefined`
+ * when there is no comment or it is empty.
+ */
+export const splitComment = (line: string): { head: string, comment?: string } => {
+  let quote: undefined | string
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i]!
+    if (quote !== undefined) {
+      if (char === quote) {
+        quote = undefined
+      }
+      continue
+    }
+    if (char === '"' || char === '`') {
+      quote = char
+      continue
+    }
+    if (char === ';') {
+      const comment = line.slice(i + 1).trim()
+      return comment === '' ?
+        { head: line.slice(0, i) } :
+        { head: line.slice(0, i), comment }
+    }
+  }
+  return { head: line }
+}