@wkronmiller/lisa 0.1.0

package/src/spec/grammar/parser.ts

@@ -0,0 +1,443 @@
+import { existsSync } from "fs";
+import { resolve } from "path";
+
+import type {
+  ConstraintStrength,
+  FieldLine,
+  FileRef,
+  GrammarParseResult,
+  GrammarWarning,
+  ParsedStatement,
+  RiskSeverity,
+  StatementKind,
+} from "./types";
+
+/** Section titles where specific statement kinds are expected. */
+const SECTION_EXPECTED_KINDS: Record<string, Set<StatementKind>> = {
+  invariants: new Set(["must", "must_not", "should", "should_not", "may", "note"]),
+  "acceptance criteria": new Set(["given_then", "given_when_then", "when_then", "note"]),
+  declarations: new Set([
+    "defines", "references", "exposes", "accepts", "returns",
+    "emits", "consumes", "stores", "transitions", "note",
+  ]),
+  dependencies: new Set(["requires", "after", "calls", "note"]),
+  performance: new Set(["metric", "tolerance", "baseline", "note"]),
+  "failure modes": new Set(["risk", "mitigated_by", "note"]),
+  "out of scope": new Set(["excludes", "deferred", "assumes", "note"]),
+  "use cases": new Set(["note"]),
+  summary: new Set(["note"]),
+};
+
+function normalizeSection(title: string): string {
+  return title.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function stripBullet(line: string): string {
+  return line.replace(/^\s*[-*]\s+/, "");
+}
+
+function isBulletLine(line: string): boolean {
+  return /^\s*[-*]\s+/.test(line);
+}
+
+function isContinuationLine(line: string): boolean {
+  return /^\s{2,}/.test(line) && !isBulletLine(line);
+}
+
+function parseFileRef(line: string, lineNumber: number, repoRoot?: string): FileRef | undefined {
+  const match = line.trim().match(/^@\s+(.+)$/);
+  if (!match) return undefined;
+  const filePath = match[1].trim();
+  const resolved = repoRoot ? existsSync(resolve(repoRoot, filePath)) : false;
+  return { path: filePath, line: lineNumber, resolved };
+}
+
+function parseFieldLine(line: string, lineNumber: number): FieldLine | undefined {
+  const trimmed = line.trim();
+  if (trimmed.startsWith("@")) return undefined;
+  const match = trimmed.match(/^([^:]+):\s+(.+)$/);
+  if (!match) return undefined;
+  return { name: match[1].trim(), description: match[2].trim(), line: lineNumber };
+}
+
+function tryParseConstraint(text: string): { kind: ConstraintStrength; body: string } | undefined {
+  const patterns: [RegExp, ConstraintStrength][] = [
+    [/^MUST NOT:\s*(.+)$/i, "must_not"],
+    [/^MUST:\s*(.+)$/i, "must"],
+    [/^SHOULD NOT:\s*(.+)$/i, "should_not"],
+    [/^SHOULD:\s*(.+)$/i, "should"],
+    [/^MAY:\s*(.+)$/i, "may"],
+  ];
+
+  for (const [pattern, strength] of patterns) {
+    const match = text.match(pattern);
+    if (match) {
+      return { kind: strength, body: match[1].trim() };
+    }
+  }
+  return undefined;
+}
+
+function tryParseCondition(text: string): { kind: StatementKind; body: string } | undefined {
+  if (/^GIVEN\s+.+\s+WHEN\s+.+\s+THEN\s+.+$/i.test(text)) {
+    return { kind: "given_when_then", body: text };
+  }
+  if (/^GIVEN\s+.+\s+THEN\s+.+$/i.test(text)) {
+    return { kind: "given_then", body: text };
+  }
+  if (/^WHEN\s+.+\s+THEN\s+.+$/i.test(text)) {
+    return { kind: "when_then", body: text };
+  }
+  // GIVEN without THEN => note (caller handles warning)
+  if (/^GIVEN\s+/i.test(text) && !/THEN\s+/i.test(text) && !/[,.;:]/.test(text)) {
+    return undefined;
+  }
+  return undefined;
+}
+
+const TYPED_DECLARATION_KEYWORDS: StatementKind[] = ["defines", "references", "exposes", "accepts", "returns"];
+const UNTYPED_DECLARATION_KEYWORDS: { pattern: RegExp; kind: StatementKind }[] = [
+  { pattern: /^EMITS\s+(\S+)(?::\s*(.*))?$/i, kind: "emits" },
+  { pattern: /^CONSUMES\s+(\S+)(?::\s*(.*))?$/i, kind: "consumes" },
+  { pattern: /^STORES\s+(\S+)(?::\s*(.*))?$/i, kind: "stores" },
+];
+
+function tryParseDeclaration(text: string): { kind: StatementKind; body: string; typeLabel?: string; name?: string } | undefined {
+  // TRANSITIONS has a unique syntax
+  const transMatch = text.match(/^TRANSITIONS\s+(.+?)\s+FROM\s+(.+?)\s+TO\s+(.+?)(?:\s+WHEN\s+(.+))?$/i);
+  if (transMatch) {
+    return { kind: "transitions", body: text, typeLabel: undefined, name: transMatch[1] };
+  }
+
+  // Typed declarations: KEYWORD <typeLabel> <name...>: <description>
+  for (const kind of TYPED_DECLARATION_KEYWORDS) {
+    const keyword = kind.toUpperCase();
+    const re = new RegExp(`^${keyword}\\s+(\\S+)\\s+(.+?)(?::\\s*(.*))?$`, "i");
+    const match = text.match(re);
+    if (match) {
+      // Split name from body: name is everything before `:`, but the regex already handles that
+      // However (.+?) is lazy and the optional colon group may not capture correctly.
+      // Use a two-step parse: first check if there's a colon separator.
+      const afterKeyword = text.replace(new RegExp(`^${keyword}\\s+`, "i"), "");
+      const typeLabel = afterKeyword.match(/^(\S+)/)?.[1] || "";
+      const rest = afterKeyword.slice(typeLabel.length).trim();
+      const colonIndex = rest.indexOf(":");
+      if (colonIndex >= 0) {
+        const name = rest.slice(0, colonIndex).trim();
+        const body = rest.slice(colonIndex + 1).trim();
+        return { kind, body, typeLabel, name };
+      }
+      return { kind, body: "", typeLabel, name: rest };
+    }
+  }
+
+  // Untyped declarations: EMITS/CONSUMES/STORES <name>: <description>
+  for (const { pattern, kind } of UNTYPED_DECLARATION_KEYWORDS) {
+    const match = text.match(pattern);
+    if (match) {
+      return { kind, body: match[2]?.trim() || "", typeLabel: undefined, name: match[1] };
+    }
+  }
+
+  return undefined;
+}
+
+function tryParseDependency(text: string): { kind: StatementKind; body: string; name?: string } | undefined {
+  const requiresFor = text.match(/^REQUIRES\s+(.+?)\s+FOR\s+(.+)$/i);
+  if (requiresFor) {
+    return { kind: "requires", body: requiresFor[2].trim(), name: requiresFor[1].trim() };
+  }
+  const requires = text.match(/^REQUIRES\s+(.+)$/i);
+  if (requires) {
+    return { kind: "requires", body: "", name: requires[1].trim() };
+  }
+  const after = text.match(/^AFTER\s+(.+)$/i);
+  if (after) {
+    return { kind: "after", body: "", name: after[1].trim() };
+  }
+  const calls = text.match(/^CALLS\s+(.+?):\s*(.*)$/i);
+  if (calls) {
+    return { kind: "calls", body: calls[2].trim(), name: calls[1].trim() };
+  }
+  return undefined;
+}
+
+function tryParseMetric(text: string): { kind: StatementKind; body: string; name?: string } | undefined {
+  const metricPer = text.match(/^METRIC\s+(\S+)\s*(<=|>=|<|>|==)\s*(\S+)\s+PER\s+(.+)$/i);
+  if (metricPer) {
+    return { kind: "metric", body: text, name: metricPer[1] };
+  }
+  const metric = text.match(/^METRIC\s+(\S+)\s*(<=|>=|<|>|==)\s*(\S+)$/i);
+  if (metric) {
+    return { kind: "metric", body: text, name: metric[1] };
+  }
+  const tolerance = text.match(/^TOLERANCE\s+(.+)$/i);
+  if (tolerance) {
+    return { kind: "tolerance", body: tolerance[1].trim() };
+  }
+  const baseline = text.match(/^BASELINE\s+(.+)$/i);
+  if (baseline) {
+    return { kind: "baseline", body: baseline[1].trim() };
+  }
+  return undefined;
+}
+
+function tryParseRisk(text: string): { kind: StatementKind; body: string; severity?: RiskSeverity } | undefined {
+  const risk = text.match(/^RISK\s+(critical|high|medium|low):\s*(.+)$/i);
+  if (risk) {
+    return { kind: "risk", body: risk[2].trim(), severity: risk[1].toLowerCase() as RiskSeverity };
+  }
+  const mitigated = text.match(/^MITIGATED BY:\s*(.+)$/i);
+  if (mitigated) {
+    return { kind: "mitigated_by", body: mitigated[1].trim() };
+  }
+  return undefined;
+}
+
+function tryParseScope(text: string): { kind: StatementKind; body: string } | undefined {
+  const excludes = text.match(/^EXCLUDES:\s*(.+)$/i);
+  if (excludes) return { kind: "excludes", body: excludes[1].trim() };
+  const deferred = text.match(/^DEFERRED:\s*(.+)$/i);
+  if (deferred) return { kind: "deferred", body: deferred[1].trim() };
+  const assumes = text.match(/^ASSUMES:\s*(.+)$/i);
+  if (assumes) return { kind: "assumes", body: assumes[1].trim() };
+  return undefined;
+}
+
+/**
+ * Parse a spec body into typed grammar statements.
+ * Lines that don't match any pattern become `note` statements.
+ */
+export function parseGrammarStatements(
+  body: string,
+  sections: { title: string; level: number; content: string }[],
+  options?: { repoRoot?: string },
+): GrammarParseResult {
+  const statements: ParsedStatement[] = [];
+  const warnings: GrammarWarning[] = [];
+  const lines = body.replace(/\r\n/g, "\n").split("\n");
+
+  let currentSection = "";
+  let fenceState: { marker: string; length: number } | undefined;
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNumber = i + 1;
+    const line = lines[i];
+
+    // Track code fences
+    const fenceMatch = line.match(/^([`~]{3,})(.*)$/);
+    if (fenceMatch) {
+      const fence = fenceMatch[1];
+      const marker = fence[0];
+      const trailingText = fenceMatch[2].trim();
+      if (!fenceState) {
+        fenceState = { marker, length: fence.length };
+      } else if (fenceState.marker === marker && fence.length >= fenceState.length && trailingText.length === 0) {
+        fenceState = undefined;
+      }
+      continue;
+    }
+
+    if (fenceState) continue;
+
+    // Track section headings
+    const headingMatch = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (headingMatch) {
+      currentSection = headingMatch[2];
+      continue;
+    }
+
+    // Skip empty lines and continuation lines at top level
+    if (!line.trim()) continue;
+    if (isContinuationLine(line)) continue; // handled when parsing bullet parent
+
+    const bulletLine = isBulletLine(line);
+    const text = bulletLine ? stripBullet(line) : line.trim();
+    if (!text) continue;
+
+    // Collect continuation lines
+    const continuationLines: { text: string; lineNumber: number }[] = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const nextLine = lines[j];
+      if (isContinuationLine(nextLine)) {
+        continuationLines.push({ text: nextLine.trim(), lineNumber: j + 1 });
+      } else {
+        break;
+      }
+    }
+
+    const statement = parseLine(text, lineNumber, currentSection, line, continuationLines, warnings, options?.repoRoot);
+    statements.push(statement);
+
+    // Check for misplaced statements
+    const normalizedSection = normalizeSection(currentSection);
+    const expectedKinds = SECTION_EXPECTED_KINDS[normalizedSection];
+    if (expectedKinds && statement.kind !== "note" && !expectedKinds.has(statement.kind)) {
+      warnings.push({ line: lineNumber, message: `Statement \`${statement.kind}\` is unexpected in section \`${currentSection}\`.` });
+    }
+  }
+
+  return { statements, warnings };
+}
+
+function parseLine(
+  text: string,
+  lineNumber: number,
+  section: string,
+  raw: string,
+  continuations: { text: string; lineNumber: number }[],
+  warnings: GrammarWarning[],
+  repoRoot?: string,
+): ParsedStatement {
+  // Try constraint
+  const constraint = tryParseConstraint(text);
+  if (constraint) {
+    const stmt: ParsedStatement = {
+      kind: constraint.kind,
+      raw,
+      body: constraint.body,
+      section,
+      line: lineNumber,
+      strength: constraint.kind as ConstraintStrength,
+    };
+    attachContinuations(stmt, continuations, warnings, repoRoot);
+    return stmt;
+  }
+
+  // Try condition (GIVEN/WHEN/THEN)
+  const condition = tryParseCondition(text);
+  if (condition) {
+    const stmt: ParsedStatement = {
+      kind: condition.kind,
+      raw,
+      body: condition.body,
+      section,
+      line: lineNumber,
+    };
+    attachContinuations(stmt, continuations, warnings, repoRoot);
+    return stmt;
+  }
+
+  // Check for GIVEN without THEN (uppercase keyword only)
+  if (/^GIVEN\s+/i.test(text) && !/THEN\s+/i.test(text) && !/[,.;:]/.test(text)) {
+      warnings.push({ line: lineNumber, message: "GIVEN without THEN — treated as note." });
+      const stmt: ParsedStatement = { kind: "note", raw, body: text, section, line: lineNumber };
+      attachContinuations(stmt, continuations, warnings, repoRoot);
+      return stmt;
+  }
+
+  // Try declaration
+  const declaration = tryParseDeclaration(text);
+  if (declaration) {
+    const stmt: ParsedStatement = {
+      kind: declaration.kind,
+      raw,
+      body: declaration.body,
+      section,
+      line: lineNumber,
+      typeLabel: declaration.typeLabel,
+      name: declaration.name,
+    };
+    attachContinuations(stmt, continuations, warnings, repoRoot);
+    return stmt;
+  }
+
+  // Try dependency
+  const dependency = tryParseDependency(text);
+  if (dependency) {
+    const stmt: ParsedStatement = {
+      kind: dependency.kind,
+      raw,
+      body: dependency.body,
+      section,
+      line: lineNumber,
+      name: dependency.name,
+    };
+    attachContinuations(stmt, continuations, warnings, repoRoot);
+    return stmt;
+  }
+
+  // Try metric
+  const metric = tryParseMetric(text);
+  if (metric) {
+    const stmt: ParsedStatement = {
+      kind: metric.kind,
+      raw,
+      body: metric.body,
+      section,
+      line: lineNumber,
+      name: metric.name,
+    };
+    attachContinuations(stmt, continuations, warnings, repoRoot);
+    return stmt;
+  }
+
+  // Try risk
+  const risk = tryParseRisk(text);
+  if (risk) {
+    const stmt: ParsedStatement = {
+      kind: risk.kind,
+      raw,
+      body: risk.body,
+      section,
+      line: lineNumber,
+      severity: risk.severity,
+    };
+    attachContinuations(stmt, continuations, warnings, repoRoot);
+    return stmt;
+  }
+
+  // Try scope
+  const scope = tryParseScope(text);
+  if (scope) {
+    const stmt: ParsedStatement = {
+      kind: scope.kind,
+      raw,
+      body: scope.body,
+      section,
+      line: lineNumber,
+    };
+    attachContinuations(stmt, continuations, warnings, repoRoot);
+    return stmt;
+  }
+
+  // Default: note
+  const stmt: ParsedStatement = { kind: "note", raw, body: text, section, line: lineNumber };
+  attachContinuations(stmt, continuations, warnings, repoRoot);
+  return stmt;
+}
+
+function attachContinuations(
+  stmt: ParsedStatement,
+  continuations: { text: string; lineNumber: number }[],
+  warnings: GrammarWarning[],
+  repoRoot?: string,
+): void {
+  if (continuations.length === 0) return;
+
+  for (const cont of continuations) {
+    const fileRef = parseFileRef(cont.text, cont.lineNumber, repoRoot);
+    if (fileRef) {
+      if (!stmt.files) stmt.files = [];
+      stmt.files.push(fileRef);
+      continue;
+    }
+
+    const structuredChild = parseLine(cont.text, cont.lineNumber, stmt.section, cont.text, [], warnings, repoRoot);
+    if (structuredChild.kind !== "note") {
+      if (!stmt.children) stmt.children = [];
+      stmt.children.push(structuredChild);
+      continue;
+    }
+
+    const field = parseFieldLine(cont.text, cont.lineNumber);
+    if (field) {
+      if (!stmt.fields) stmt.fields = [];
+      stmt.fields.push(field);
+      continue;
+    }
+
+    if (!stmt.children) stmt.children = [];
+    stmt.children.push(structuredChild);
+  }
+}

package/src/spec/grammar/types.ts

@@ -0,0 +1,70 @@
+export type StatementKind =
+  | "must"
+  | "must_not"
+  | "should"
+  | "should_not"
+  | "may"
+  | "given_then"
+  | "given_when_then"
+  | "when_then"
+  | "defines"
+  | "references"
+  | "exposes"
+  | "accepts"
+  | "returns"
+  | "emits"
+  | "consumes"
+  | "stores"
+  | "transitions"
+  | "requires"
+  | "after"
+  | "calls"
+  | "metric"
+  | "tolerance"
+  | "baseline"
+  | "risk"
+  | "mitigated_by"
+  | "excludes"
+  | "deferred"
+  | "assumes"
+  | "note";
+
+export type ConstraintStrength = "must" | "must_not" | "should" | "should_not" | "may";
+export type RiskSeverity = "critical" | "high" | "medium" | "low";
+
+export interface FileRef {
+  path: string;
+  line: number;
+  resolved: boolean;
+}
+
+export interface FieldLine {
+  name: string;
+  description: string;
+  line: number;
+}
+
+export interface ParsedStatement {
+  kind: StatementKind;
+  raw: string;
+  body: string;
+  section: string;
+  line: number;
+  strength?: ConstraintStrength;
+  severity?: RiskSeverity;
+  typeLabel?: string;
+  name?: string;
+  files?: FileRef[];
+  fields?: FieldLine[];
+  children?: ParsedStatement[];
+}
+
+export interface GrammarWarning {
+  line: number;
+  message: string;
+}
+
+export interface GrammarParseResult {
+  statements: ParsedStatement[];
+  warnings: GrammarWarning[];
+}

package/src/spec/grammar/validator.ts

@@ -0,0 +1,104 @@
+import type { ParsedStatement, GrammarWarning } from "./types";
+import type { ParsedSpecDocument, ValidationIssue } from "../types";
+import { parseGrammarStatements } from "./parser";
+
+/** Spec ID pattern: dotted segments like `backend.payment-gateway`. */
+const SPEC_ID_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*)+$/;
+
+function isSpecIdLike(target: string): boolean {
+  return SPEC_ID_PATTERN.test(target);
+}
+
+export interface GrammarValidationOptions {
+  strict?: boolean;
+  repoRoot?: string;
+}
+
+export interface GrammarValidationResult {
+  issues: ValidationIssue[];
+}
+
+/**
+ * Validate grammar-level cross-references across a workspace of parsed spec documents.
+ *
+ * - REFERENCES cross-referencing: warns when no matching DEFINES exists.
+ * - REQUIRES cross-referencing: warns when target looks like a spec ID and no matching spec exists.
+ * - File reference warnings: warns when `@ path` targets don't exist.
+ * - Strict mode: promotes advisory warnings to errors.
+ */
+export function validateGrammarCrossReferences(
+  documents: ParsedSpecDocument[],
+  options?: GrammarValidationOptions,
+): GrammarValidationResult {
+  const issues: ValidationIssue[] = [];
+  const severity: ValidationIssue["severity"] = options?.strict ? "error" : "warning";
+
+  // Collect all DEFINES across workspace: key = "typeLabel name" (lowercased)
+  const allDefines = new Set<string>();
+  // Collect all spec IDs
+  const allSpecIds = new Set<string>();
+
+  for (const doc of documents) {
+    if (doc.id) allSpecIds.add(doc.id);
+  }
+
+  // First pass: collect all DEFINES
+  for (const doc of documents) {
+    const { statements } = parseGrammarStatements(doc.body, doc.sections, { repoRoot: options?.repoRoot });
+    for (const stmt of statements) {
+      if (stmt.kind === "defines" && stmt.typeLabel && stmt.name) {
+        allDefines.add(`${stmt.typeLabel.toLowerCase()} ${stmt.name.toLowerCase()}`);
+      }
+    }
+  }
+
+  // Second pass: validate REFERENCES and REQUIRES
+  for (const doc of documents) {
+    const { statements, warnings } = parseGrammarStatements(doc.body, doc.sections, { repoRoot: options?.repoRoot });
+
+    // Promote grammar warnings (misplaced statements, GIVEN without THEN) to issues
+    for (const warning of warnings) {
+      issues.push({ path: doc.path, message: warning.message, severity });
+    }
+
+    for (const stmt of statements) {
+      // REFERENCES cross-referencing
+      if (stmt.kind === "references" && stmt.typeLabel && stmt.name) {
+        const key = `${stmt.typeLabel.toLowerCase()} ${stmt.name.toLowerCase()}`;
+        if (!allDefines.has(key)) {
+          issues.push({
+            path: doc.path,
+            message: `REFERENCES ${stmt.typeLabel} ${stmt.name} has no matching DEFINES in the workspace.`,
+            severity,
+          });
+        }
+      }
+
+      // REQUIRES / AFTER cross-referencing (only spec-ID-like targets)
+      if ((stmt.kind === "requires" || stmt.kind === "after") && stmt.name && isSpecIdLike(stmt.name)) {
+        if (!allSpecIds.has(stmt.name)) {
+          issues.push({
+            path: doc.path,
+            message: `${stmt.kind.toUpperCase()} ${stmt.name} references a spec that does not exist in the workspace.`,
+            severity,
+          });
+        }
+      }
+
+      // File reference warnings
+      if (stmt.files) {
+        for (const file of stmt.files) {
+          if (!file.resolved) {
+            issues.push({
+              path: doc.path,
+              message: `File reference \`@ ${file.path}\` on line ${file.line} does not exist.`,
+              severity,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return { issues };
+}