@balpal4495/quorum 3.0.3 → 3.1.0

package/modules/oracle/summary.ts

@@ -1,116 +0,0 @@
-import { promises as fs } from "fs"
-import path from "path"
-import type { ChronicleEntry } from "../shared/types"
-import { entryText } from "../shared/types"
-
-const SUMMARY_WEEKS = 12
-const DIRECTIVE =
-  "<!-- Chronicle Summary v1 — temporal orientation for agents. " +
-  "Use for sequence context; query Oracle by entry ID for full reasoning. -->"
-
-/**
- * Returns the ISO week string (YYYY-Www) for a given date.
- * Uses the ISO 8601 definition: week 1 is the week containing the first Thursday.
- */
-function isoWeekKey(date: Date): string {
-  const d = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()))
-  const day = d.getUTCDay() || 7
-  d.setUTCDate(d.getUTCDate() + 4 - day)
-  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1))
-  const week = Math.ceil(((d.getTime() - yearStart.getTime()) / 86_400_000 + 1) / 7)
-  return `${d.getUTCFullYear()}-W${String(week).padStart(2, "0")}`
-}
-
-function workRefLabel(entry: ChronicleEntry): string {
-  if (!entry.work_ref) return "__none__"
-  const { type, ref } = entry.work_ref
-  return ref ? `[${type} ${ref}]` : `[${type}]`
-}
-
-function renderEntry(entry: ChronicleEntry): string {
-  const areas = entry.affected_areas.join(", ")
-  const id = entry.id.slice(0, 8)
-  return `- **[${id}]** ${areas} — \`${entry.status}\` (${entry.confidence.toFixed(2)}) — ${entryText(entry)}`
-}
-
-/**
- * Rebuild .chronicle/SUMMARY.md from all committed entries.
- *
- * Groups entries by ISO week (most-recent first), then by work_ref within
- * each week. Shows the last SUMMARY_WEEKS weeks; older entries are omitted
- * (still fully queryable via Oracle).
- *
- * Called by commit() as a best-effort side-effect — never throws.
- */
-export async function updateSummary(chronicleDir: string): Promise<void> {
-  const committedDir = path.join(chronicleDir, "committed")
-
-  let files: string[]
-  try {
-    files = await fs.readdir(committedDir)
-  } catch {
-    return
-  }
-
-  const entries: ChronicleEntry[] = []
-  for (const file of files) {
-    if (!file.endsWith(".json")) continue
-    try {
-      const raw = await fs.readFile(path.join(committedDir, file), "utf8")
-      entries.push(JSON.parse(raw) as ChronicleEntry)
-    } catch {
-      // Skip malformed entries
-    }
-  }
-
-  if (entries.length === 0) return
-
-  entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp))
-
-  // Group by ISO week
-  const byWeek = new Map<string, ChronicleEntry[]>()
-  for (const entry of entries) {
-    const week = isoWeekKey(new Date(entry.timestamp))
-    const bucket = byWeek.get(week) ?? []
-    bucket.push(entry)
-    byWeek.set(week, bucket)
-  }
-
-  const weeks = [...byWeek.keys()].sort().reverse().slice(0, SUMMARY_WEEKS)
-
-  const lines: string[] = [DIRECTIVE, ""]
-
-  for (const week of weeks) {
-    lines.push(`## Week ${week}`, "")
-
-    // Group entries within week by work_ref label
-    const weekEntries = byWeek.get(week)!
-    const byWork = new Map<string, ChronicleEntry[]>()
-    for (const entry of weekEntries) {
-      const key = workRefLabel(entry)
-      const bucket = byWork.get(key) ?? []
-      bucket.push(entry)
-      byWork.set(key, bucket)
-    }
-
-    // Labelled work groups first, then ungrouped
-    const workKeys = [...byWork.keys()].sort((a, b) =>
-      a === "__none__" ? 1 : b === "__none__" ? -1 : a.localeCompare(b),
-    )
-
-    for (const key of workKeys) {
-      if (key === "__none__") {
-        lines.push(`### (no work context — query Oracle by entry ID for details)`)
-      } else {
-        lines.push(`### ${key}`)
-      }
-      for (const entry of byWork.get(key)!) {
-        lines.push(renderEntry(entry))
-      }
-      lines.push("")
-    }
-  }
-
-  const summaryPath = path.join(chronicleDir, "SUMMARY.md")
-  await fs.writeFile(summaryPath, lines.join("\n"), "utf8")
-}

package/modules/oracle/types.ts

@@ -1,32 +0,0 @@
-import type { ChronicleEntry } from "../shared/types"
-
-/**
- * Abstract vector store interface.
- * Swap implementations without changing Oracle logic.
- * Default implementation: LanceDB (see adapters/lance-db.ts).
- */
-export interface VectorStore {
-  /**
-   * Upsert a Chronicle entry with its embedding vector.
-   * If an entry with this ID already exists, it is replaced.
-   */
-  upsert: (id: string, vector: number[], metadata: ChronicleEntry) => Promise<void>
-  /**
-   * Return the top-K most similar entries to the given query vector.
-   * Scores should be in [0, 1] (higher = more similar).
-   */
-  search: (
-    vector: number[],
-    limit: number,
-  ) => Promise<Array<{ entry: ChronicleEntry; score: number }>>
-  /** Return all stored entries (used for full-corpus BM25 if needed). */
-  getAll: () => Promise<ChronicleEntry[]>
-}
-
-export interface OracleDeps {
-  /** Converts text to a numeric embedding vector. */
-  embedder: (text: string) => Promise<number[]>
-  vectorStore: VectorStore
-  /** Root directory for Chronicle data. Default: ".chronicle" */
-  chronicleDir?: string
-}

package/modules/sentinel/assert.ts

@@ -1,95 +0,0 @@
-import { coverage } from "./coverage"
-import { detectDrift } from "./drift"
-import type { LLMProvider } from "../shared/types"
-
-export interface SentinelAssertOptions {
-  chronicleDir?: string
-  codebasePath?: string
-  /** When provided, drift detection runs. When absent, drift tests are skipped. */
-  llm?: LLMProvider
-  extensions?: string[]
-  /**
-   * Chronicle coverage must reach this percentage for the CI test to pass.
-   * Default 0 = report gaps as advisory output without failing the build.
-   * Raise this as the project matures (e.g. 50 for an established codebase).
-   */
-  minCoveragePercent?: number
-}
-
-/**
- * Returns a set of named assertions designed to be called inside a Vitest
- * describe block. Coverage assertions are deterministic and always run.
- * Drift assertions skip gracefully when no LLM is provided.
- *
- * @example
- * import { describe } from "vitest"
- * import { sentinelAssertions } from "../modules/sentinel/assert"
- *
- * const assertions = sentinelAssertions({ chronicleDir: ".chronicle", codebasePath: "modules" })
- * describe("sentinel", () => { assertions.forEach(a => a()) })
- */
-export function sentinelAssertions(options: SentinelAssertOptions = {}): Array<() => void> {
-  const {
-    chronicleDir = ".chronicle",
-    codebasePath = ".",
-    llm,
-    extensions,
-    minCoveragePercent = 0,
-  } = options
-
-  // Import vitest lazily so this file is usable outside of a test context too
-  // eslint-disable-next-line @typescript-eslint/no-var-requires
-  const { it, expect, describe: _describe } = require("vitest") as typeof import("vitest")
-
-  const assertions: Array<() => void> = []
-
-  // ── Coverage (deterministic, always run) ──────────────────────────────────
-  assertions.push(() => {
-    const label = minCoveragePercent > 0
-      ? `coverage: Chronicle coverage ≥ ${minCoveragePercent}%`
-      : "coverage: Chronicle coverage report [advisory]"
-    it(label, async () => {
-      const report = await coverage(chronicleDir, codebasePath, { extensions })
-      if (report.uncoveredFiles.length > 0) {
-        const list = report.uncoveredFiles.slice(0, 10).join("\n  ")
-        const msg = `${report.uncoveredFiles.length} source file(s) have no Chronicle coverage (${report.percentage}% covered):\n  ${list}`
-        if (minCoveragePercent > 0) {
-          expect(report.percentage, msg).toBeGreaterThanOrEqual(minCoveragePercent)
-        } else {
-          // New project or no threshold set — surface gaps without failing the build
-          console.info(`[sentinel] ${msg}`)
-        }
-      }
-    })
-  })
-
-  assertions.push(() => {
-    it("coverage: report is readable and well-formed", async () => {
-      const report = await coverage(chronicleDir, codebasePath, { extensions })
-      expect(report.totalFiles).toBeGreaterThanOrEqual(0)
-      expect(report.percentage).toBeGreaterThanOrEqual(0)
-      expect(report.percentage).toBeLessThanOrEqual(100)
-    })
-  })
-
-  // ── Drift (advisory, skips when no LLM configured) ────────────────────────
-  assertions.push(() => {
-    it.skipIf(!llm)(
-      "drift: no Chronicle entries flagged as potentially stale [advisory]",
-      async () => {
-        const report = await detectDrift(chronicleDir, codebasePath, llm!)
-        if (report.flags.length > 0) {
-          const detail = report.flags
-            .map(f => `  [${f.entryId.slice(0, 8)}] ${f.keyInsight}\n    → ${f.reasoning}`)
-            .join("\n")
-          expect(
-            report.flags,
-            `${report.flags.length} Chronicle entry/entries may have drifted (advisory — review before marking refuted):\n${detail}`,
-          ).toHaveLength(0)
-        }
-      },
-    )
-  })
-
-  return assertions
-}

package/modules/sentinel/coverage.ts

@@ -1,106 +0,0 @@
-import { promises as fs, Dirent } from "fs"
-import path from "path"
-import type { ChronicleEntry, CoverageReport, FileCoverage } from "../shared/types"
-
-const IGNORED_DIRS = new Set(["node_modules", "dist", ".git", ".chronicle", "coverage", "__tests__"])
-const TEST_SUFFIXES = [".test.ts", ".spec.ts", ".test.js", ".spec.js"]
-
-async function walkFiles(
-  dir: string,
-  extensions: string[],
-  excludeTestFiles: boolean,
-): Promise<string[]> {
-  const results: string[] = []
-
-  async function recurse(current: string): Promise<void> {
-    let entries: Dirent<string>[]
-    try {
-      entries = await fs.readdir(current, { withFileTypes: true, encoding: "utf8" })
-    } catch {
-      return
-    }
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        if (!IGNORED_DIRS.has(entry.name)) await recurse(path.join(current, entry.name))
-      } else if (extensions.some(ext => entry.name.endsWith(ext))) {
-        if (excludeTestFiles && TEST_SUFFIXES.some(s => entry.name.endsWith(s))) continue
-        results.push(path.join(current, entry.name))
-      }
-    }
-  }
-
-  await recurse(dir)
-  return results
-}
-
-async function readCommittedEntries(chronicleDir: string): Promise<ChronicleEntry[]> {
-  const committedDir = path.join(chronicleDir, "committed")
-  let files: string[]
-  try {
-    files = await fs.readdir(committedDir)
-  } catch {
-    return []
-  }
-  const entries: ChronicleEntry[] = []
-  for (const file of files) {
-    if (!file.endsWith(".json")) continue
-    try {
-      const raw = await fs.readFile(path.join(committedDir, file), "utf8")
-      entries.push(JSON.parse(raw) as ChronicleEntry)
-    } catch {
-      // skip malformed
-    }
-  }
-  return entries
-}
-
-function isCovered(relativePath: string, entries: ChronicleEntry[]): { covered: boolean; entryIds: string[] } {
-  const matched: string[] = []
-  const normalised = relativePath.replace(/\\/g, "/")
-  for (const entry of entries) {
-    const hits = entry.affected_areas.some(area => {
-      const normArea = area.replace(/\\/g, "/")
-      return normalised.includes(normArea) || normArea.includes(normalised)
-    })
-    if (hits) matched.push(entry.id)
-  }
-  return { covered: matched.length > 0, entryIds: matched }
-}
-
-/**
- * Scan the codebase and report which files have Chronicle entries referencing
- * them in affected_areas and which do not.
- *
- * Matching is substring-based — "oracle/propose.ts" in affected_areas covers
- * "modules/oracle/propose.ts" in the codebase. Treat percentage as directional
- * signal, not a precision metric.
- */
-export async function coverage(
-  chronicleDir: string,
-  codebasePath: string,
-  options: { extensions?: string[]; excludeTestFiles?: boolean } = {},
-): Promise<CoverageReport> {
-  const extensions = options.extensions ?? [".ts"]
-  const excludeTestFiles = options.excludeTestFiles ?? true
-  const [entries, files] = await Promise.all([
-    readCommittedEntries(chronicleDir),
-    walkFiles(codebasePath, extensions, excludeTestFiles),
-  ])
-
-  const coverageByFile: FileCoverage[] = files.map(absolute => {
-    const relative = path.relative(codebasePath, absolute).replace(/\\/g, "/")
-    const { covered, entryIds } = isCovered(relative, entries)
-    return { file: relative, covered, entryIds }
-  })
-
-  const covered = coverageByFile.filter(f => f.covered)
-  const uncovered = coverageByFile.filter(f => !f.covered)
-
-  return {
-    totalFiles: files.length,
-    coveredFiles: covered.length,
-    uncoveredFiles: uncovered.map(f => f.file),
-    coverageByFile,
-    percentage: files.length === 0 ? 0 : Math.round((covered.length / files.length) * 100),
-  }
-}

package/modules/sentinel/drift.ts

@@ -1,163 +0,0 @@
-import { promises as fs } from "fs"
-import path from "path"
-import type { ChronicleEntry, DriftFlag, DriftReport, LLMProvider } from "../shared/types"
-import { entryText } from "../shared/types"
-
-const FILE_CONTENT_LIMIT = 3000
-
-async function readCommittedEntries(chronicleDir: string): Promise<ChronicleEntry[]> {
-  const committedDir = path.join(chronicleDir, "committed")
-  let files: string[]
-  try {
-    files = await fs.readdir(committedDir)
-  } catch {
-    return []
-  }
-  const entries: ChronicleEntry[] = []
-  for (const file of files) {
-    if (!file.endsWith(".json")) continue
-    try {
-      const raw = await fs.readFile(path.join(committedDir, file), "utf8")
-      entries.push(JSON.parse(raw) as ChronicleEntry)
-    } catch {
-      // skip malformed
-    }
-  }
-  return entries
-}
-
-async function resolveLocalFiles(areas: string[], codebasePath: string): Promise<string[]> {
-  const resolved: string[] = []
-  for (const area of areas) {
-    // Try as a direct relative path first
-    const candidate = path.join(codebasePath, area)
-    try {
-      await fs.access(candidate)
-      resolved.push(candidate)
-      continue
-    } catch {
-      // not a direct path — try substring search
-    }
-    // Walk up to two levels to find files whose relative path contains the area string
-    try {
-      const all = await fs.readdir(codebasePath, { recursive: true, encoding: "utf8" })
-      for (const f of all) {
-        const normalised = f.replace(/\\/g, "/")
-        if (normalised.includes(area.replace(/\\/g, "/")) && normalised.endsWith(".ts")) {
-          resolved.push(path.join(codebasePath, f))
-          break
-        }
-      }
-    } catch {
-      // ignore
-    }
-  }
-  return [...new Set(resolved)]
-}
-
-async function evaluateDrift(
-  entry: ChronicleEntry,
-  files: Array<{ filePath: string; content: string }>,
-  llm: LLMProvider,
-): Promise<DriftFlag> {
-  const fileSection = files
-    .map(f => `### ${path.basename(f.filePath)}\n\`\`\`\n${f.content.slice(0, FILE_CONTENT_LIMIT)}\n\`\`\``)
-    .join("\n\n")
-
-  const response = await llm([
-    {
-      role: "system",
-      content:
-        "You are a code reviewer checking whether a documented insight still accurately describes the current source code. " +
-        "Reply with a JSON object only — no markdown, no explanation outside the object.",
-    },
-    {
-      role: "user",
-      content:
-        `Documented insight:
-"${entryText(entry)}"
-
-` +
-        `Current source:\n${fileSection}\n\n` +
-        `Does this insight still accurately describe the code above?\n` +
-        `{"stillValid": boolean, "confidence": number, "reasoning": "one sentence"}`,
-    },
-  ])
-
-  try {
-    const match = response.match(/\{[\s\S]*?\}/)
-    if (!match) throw new Error("no JSON")
-    const parsed = JSON.parse(match[0]) as { stillValid?: unknown; confidence?: unknown; reasoning?: unknown }
-    return {
-      entryId: entry.id,
-      keyInsight: entryText(entry),
-      affectedFiles: files.map(f => f.filePath),
-      stillValid: Boolean(parsed.stillValid),
-      confidence: typeof parsed.confidence === "number" ? Math.max(0, Math.min(1, parsed.confidence)) : 0.5,
-      reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : "no reasoning provided",
-    }
-  } catch {
-    // Parse failure → conservative: flag for human review
-    return {
-      entryId: entry.id,
-      keyInsight: entryText(entry),
-      affectedFiles: files.map(f => f.filePath),
-      stillValid: false,
-      confidence: 0,
-      reasoning: "LLM response could not be parsed — manual review recommended",
-    }
-  }
-}
-
-/**
- * For each Chronicle entry whose affected_areas resolves to at least one local
- * source file, ask the LLM whether the key_insight still accurately describes
- * the current code.
- *
- * Output is strictly advisory — entries are never updated autonomously.
- * Entries where no affected_areas value resolves to a local file are skipped
- * (e.g. entries about external tools, workflows, or conceptual areas).
- */
-export async function detectDrift(
-  chronicleDir: string,
-  codebasePath: string,
-  llm: LLMProvider,
-): Promise<DriftReport> {
-  const entries = await readCommittedEntries(chronicleDir)
-
-  const flags: DriftFlag[] = []
-  const confirmed: DriftFlag[] = []
-  const skipped: string[] = []
-
-  for (const entry of entries) {
-    const localPaths = await resolveLocalFiles(entry.affected_areas, codebasePath)
-    if (localPaths.length === 0) {
-      skipped.push(entry.id)
-      continue
-    }
-
-    const files: Array<{ filePath: string; content: string }> = []
-    for (const p of localPaths) {
-      try {
-        const content = await fs.readFile(p, "utf8")
-        files.push({ filePath: p, content })
-      } catch {
-        // file unreadable — skip this path
-      }
-    }
-
-    if (files.length === 0) {
-      skipped.push(entry.id)
-      continue
-    }
-
-    const result = await evaluateDrift(entry, files, llm)
-    if (result.stillValid) {
-      confirmed.push(result)
-    } else {
-      flags.push(result)
-    }
-  }
-
-  return { checkedAt: new Date().toISOString(), flags, confirmed, skipped }
-}

package/modules/sentinel/index.ts

@@ -1,6 +0,0 @@
-export { coverage } from "./coverage"
-export { detectDrift } from "./drift"
-export { reviewContext } from "./review"
-export { sentinelAssertions } from "./assert"
-export type { CoverageReport, FileCoverage, DriftReport, DriftFlag } from "../shared/types"
-export type { SentinelAssertOptions } from "./assert"