@cyber-dash-tech/revela 0.16.4 → 0.17.1

package/lib/narrative-vault/diagnostic-report.ts

@@ -0,0 +1,117 @@
+import type { VaultDiagnostic, VaultDiagnosticSeverity } from "./types"
+
+export interface VaultDiagnosticDisplay {
+  code: string
+  severity: VaultDiagnosticSeverity
+  file?: string
+  nodeId?: string
+  message: string
+  suggestedFix: string
+  suggestedAction?: string
+}
+
+export interface VaultDiagnosticReport {
+  ok: boolean
+  errorCount: number
+  warningCount: number
+  blockers: VaultDiagnosticDisplay[]
+  warnings: VaultDiagnosticDisplay[]
+  nextActions: string[]
+  summary: string
+}
+
+export function formatVaultDiagnosticReport(diagnostics: VaultDiagnostic[]): VaultDiagnosticReport {
+  const displays = diagnostics.map(formatDiagnostic)
+  const blockers = displays.filter((diagnostic) => diagnostic.severity === "error")
+  const warnings = displays.filter((diagnostic) => diagnostic.severity === "warning")
+  const nextActions = unique(displays.map((diagnostic) => diagnostic.suggestedAction).filter(Boolean) as string[])
+  const summary = blockers.length === 0 && warnings.length === 0
+    ? "Narrative vault diagnostics: clean."
+    : `Narrative vault diagnostics: ${blockers.length} blocker(s), ${warnings.length} warning(s).`
+  return {
+    ok: blockers.length === 0,
+    errorCount: blockers.length,
+    warningCount: warnings.length,
+    blockers,
+    warnings,
+    nextActions,
+    summary,
+  }
+}
+
+export function formatVaultDiagnosticMarkdown(report: VaultDiagnosticReport): string {
+  if (report.errorCount === 0 && report.warningCount === 0) return ""
+  const lines = ["**Narrative vault diagnostics**", "", report.summary]
+  if (report.blockers.length > 0) {
+    lines.push("", "Blockers:")
+    for (const diagnostic of report.blockers) lines.push(`- ${formatDisplayLine(diagnostic)}`)
+  }
+  if (report.warnings.length > 0) {
+    lines.push("", "Warnings:")
+    for (const diagnostic of report.warnings) lines.push(`- ${formatDisplayLine(diagnostic)}`)
+  }
+  if (report.nextActions.length > 0) {
+    lines.push("", "Next actions:")
+    for (const action of report.nextActions) lines.push(`- ${action}`)
+  }
+  return lines.join("\n")
+}
+
+function formatDiagnostic(diagnostic: VaultDiagnostic): VaultDiagnosticDisplay {
+  const suggestion = suggestionForCode(diagnostic.code)
+  return {
+    code: diagnostic.code,
+    severity: diagnostic.severity,
+    file: diagnostic.file,
+    nodeId: diagnostic.nodeId,
+    message: diagnostic.message,
+    suggestedFix: suggestion.fix,
+    suggestedAction: suggestion.action,
+  }
+}
+
+function suggestionForCode(code: string): { fix: string; action?: string } {
+  switch (code) {
+    case "empty_vault":
+      return { fix: "Export the existing JSON narrative with exportNarrativeVault, or add the required Markdown narrative nodes.", action: "Run exportNarrativeVault if DECKS.json has a narrative; otherwise add core vault Markdown nodes." }
+    case "duplicate_id":
+      return { fix: "Rename one Markdown node id so each canonical narrative id is unique.", action: "Edit the duplicate Markdown node id and rerun compileNarrativeVault." }
+    case "missing_type":
+      return { fix: "Add the required frontmatter field type with a valid narrative vault node type.", action: "Edit the reported Markdown file and rerun compileNarrativeVault." }
+    case "missing_id":
+      return { fix: "Add the required frontmatter field id and keep it stable after creation.", action: "Edit the reported Markdown file and rerun compileNarrativeVault." }
+    case "unknown_node_type":
+      return { fix: "Use one of the supported node types: index, audience, decision, thesis, claim, evidence, objection, risk, or research-gap.", action: "Correct the type frontmatter and rerun compileNarrativeVault." }
+    case "broken_link":
+      return { fix: "Create the linked target node or correct the wikilink id in the Relations section.", action: "Repair the wikilink and rerun compileNarrativeVault." }
+    case "illegal_relation_target":
+      return { fix: "Change the relation type or target node so the typed relation connects allowed node types.", action: "Repair the relation and rerun compileNarrativeVault." }
+    case "compile_failed":
+      return { fix: "Fix structural vault diagnostics first; the narrative could not be normalized.", action: "Resolve blocker diagnostics and rerun compileNarrativeVault." }
+    case "evidence_claim_missing":
+      return { fix: "Correct the evidence claimId or create the target claim before treating the evidence as support.", action: "Use upsertVaultClaim for the missing claim or update the evidence claimId, then rerun compileNarrativeVault." }
+    case "stale_approval_hash":
+      return { fix: "The latest approval no longer matches the current narrative hash.", action: "Run /revela story and ask for approval or an explicit render override after review." }
+    case "evidence_trace_incomplete":
+      return { fix: "Add explicit source, quote/snippet, support scope, unsupported scope, caveat, and strength to the evidence node.", action: "Use upsertVaultEvidence with complete source trace fields." }
+    case "orphan_central_claim":
+      return { fix: "Add or repair claim relations, or confirm the central claim should stand alone.", action: "Review the claim in /revela story; edit Relations only when the relation is explicit." }
+    case "claim_missing_evidence":
+      return { fix: "Bind explicit evidence or keep the missing support visible as a research gap.", action: "Run /revela research or use upsertVaultEvidence when source trace is explicit." }
+    case "research_gap_unresolved":
+      return { fix: "Resolve, close, or keep researching the gap; do not treat it as evidence until bound.", action: "Run /revela research or updateVaultResearchGap with the current lifecycle status." }
+    case "gap_evidence_missing":
+      return { fix: "Correct evidenceBindingIds or create the referenced evidence node.", action: "Use upsertVaultEvidence for the missing evidence or updateVaultResearchGap to remove the bad reference." }
+    default:
+      return { fix: "Inspect the reported Markdown file or node and rerun compileNarrativeVault after the smallest safe fix.", action: "Rerun compileNarrativeVault after fixing the reported vault node." }
+  }
+}
+
+function formatDisplayLine(diagnostic: VaultDiagnosticDisplay): string {
+  const location = [diagnostic.file, diagnostic.nodeId].filter(Boolean).join(" / ")
+  return `\`${diagnostic.code}\`${location ? ` (${location})` : ""}: ${diagnostic.message} Fix: ${diagnostic.suggestedFix}`
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)]
+}

package/lib/narrative-vault/export.ts

@@ -0,0 +1,71 @@
+import { mkdirSync, writeFileSync } from "fs"
+import { join } from "path"
+import { narrativeVaultPath } from "./paths"
+import type { NarrativeStateV1 } from "../narrative-state/types"
+
+export interface ExportNarrativeVaultResult {
+  files: string[]
+}
+
+export function exportNarrativeStateToVault(workspaceRoot: string, narrative: NarrativeStateV1): ExportNarrativeVaultResult {
+  const root = narrativeVaultPath(workspaceRoot)
+  const files: string[] = []
+  mkdirSync(root, { recursive: true })
+  for (const dir of ["claims", "evidence", "objections", "risks", "research-gaps"]) mkdirSync(join(root, dir), { recursive: true })
+
+  write(root, files, "index.md", frontmatter({ type: "index", id: narrative.id, status: narrative.status }) + "\n")
+  write(root, files, "audience.md", frontmatter({ type: "audience", ...narrative.audience }) + "\n")
+  write(root, files, "decision.md", frontmatter({ type: "decision", ...narrative.decision }) + "\n")
+  if (narrative.thesis) write(root, files, "thesis.md", frontmatter({ type: "thesis", ...narrative.thesis }) + `\n${narrative.thesis.statement}\n`)
+
+  const relationsByClaim = new Map<string, string[]>()
+  for (const relation of narrative.claimRelations ?? []) {
+    const lines = relationsByClaim.get(relation.fromClaimId) ?? []
+    lines.push(`- ${relation.relation}: [[${relation.toClaimId}]]${relation.rationale ? ` - ${relation.rationale}` : ""}`)
+    relationsByClaim.set(relation.fromClaimId, lines)
+  }
+
+  for (const claim of narrative.claims) {
+    const relationLines = relationsByClaim.get(claim.id) ?? []
+    const caveats = claim.caveats?.length ? `\n## Caveats\n\n${claim.caveats.map((item) => `- ${item}`).join("\n")}\n` : ""
+    const relations = relationLines.length ? `\n## Relations\n\n${relationLines.join("\n")}\n` : ""
+    write(root, files, join("claims", `${safeFileName(claim.id)}.md`), frontmatter({ type: "claim", id: claim.id, kind: claim.kind, importance: claim.importance, evidenceRequired: claim.evidenceRequired, supportedScope: claim.supportedScope, unsupportedScope: claim.unsupportedScope }) + `\n${claim.text}\n${caveats}${relations}`)
+  }
+
+  for (const binding of narrative.evidenceBindings) write(root, files, join("evidence", `${safeFileName(binding.id)}.md`), frontmatter({ type: "evidence", ...binding }) + `\n${binding.quote ?? ""}\n`)
+  for (const objection of narrative.objections) write(root, files, join("objections", `${safeFileName(objection.id)}.md`), frontmatter({ type: "objection", ...objection }) + `\n${objection.text}\n`)
+  for (const risk of narrative.risks) write(root, files, join("risks", `${safeFileName(risk.id)}.md`), frontmatter({ type: "risk", ...risk }) + `\n${risk.text}\n`)
+  for (const gap of narrative.researchGaps ?? []) write(root, files, join("research-gaps", `${safeFileName(gap.id)}.md`), frontmatter({ type: "research-gap", ...gap }) + `\n${gap.question}\n`)
+  return { files }
+}
+
+function write(root: string, files: string[], relativePath: string, content: string): void {
+  const filePath = join(root, relativePath)
+  writeFileSync(filePath, content.endsWith("\n") ? content : `${content}\n`, "utf-8")
+  files.push(relativePath.split(/[/\\]+/).join("/"))
+}
+
+function frontmatter(values: Record<string, unknown>): string {
+  const lines = ["---"]
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined || value === "" || (Array.isArray(value) && value.length === 0)) continue
+    if (Array.isArray(value)) {
+      lines.push(`${key}:`)
+      for (const item of value) lines.push(`  - ${quote(String(item))}`)
+    } else if (typeof value === "boolean") {
+      lines.push(`${key}: ${value ? "true" : "false"}`)
+    } else {
+      lines.push(`${key}: ${quote(String(value))}`)
+    }
+  }
+  lines.push("---", "")
+  return lines.join("\n")
+}
+
+function quote(value: string): string {
+  return JSON.stringify(value)
+}
+
+function safeFileName(id: string): string {
+  return id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "node"
+}

package/lib/narrative-vault/frontmatter.ts

@@ -0,0 +1,41 @@
+export interface ParsedVaultFrontmatter {
+  frontmatter: Record<string, string | string[] | boolean>
+  body: string
+}
+
+export function parseVaultFrontmatter(markdown: string): ParsedVaultFrontmatter {
+  const normalized = markdown.replace(/\r\n/g, "\n")
+  if (!normalized.startsWith("---\n")) return { frontmatter: {}, body: normalized.trim() }
+  const end = normalized.indexOf("\n---", 4)
+  if (end === -1) return { frontmatter: {}, body: normalized.trim() }
+  const raw = normalized.slice(4, end).trim()
+  const body = normalized.slice(end + 4).replace(/^\n/, "").trim()
+  const frontmatter: Record<string, string | string[] | boolean> = {}
+  const lines = raw.split("\n")
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]
+    const match = /^(\w[\w-]*):\s*(.*)$/.exec(line)
+    if (!match) continue
+    const key = match[1]
+    const value = match[2].trim()
+    if (value === "true" || value === "false") {
+      frontmatter[key] = value === "true"
+    } else if (value.startsWith("[") && value.endsWith("]")) {
+      frontmatter[key] = value.slice(1, -1).split(",").map((item) => unquote(item.trim())).filter(Boolean)
+    } else if (!value) {
+      const items: string[] = []
+      while (lines[index + 1]?.trim().startsWith("- ")) {
+        index += 1
+        items.push(unquote(lines[index].trim().slice(2).trim()))
+      }
+      frontmatter[key] = items.length > 0 ? items : ""
+    } else {
+      frontmatter[key] = unquote(value)
+    }
+  }
+  return { frontmatter, body }
+}
+
+function unquote(value: string): string {
+  return value.replace(/^['"]|['"]$/g, "").trim()
+}

package/lib/narrative-vault/hook-targets.ts

@@ -0,0 +1,40 @@
+import { relative, resolve } from "path"
+
+const VAULT_MARKDOWN_RE = /^revela-narrative\/(.+)\.md$/
+
+export function isNarrativeVaultMarkdownPath(filePath: string, workspaceRoot: string): boolean {
+  const workspaceRelative = toWorkspaceRelativePath(filePath, workspaceRoot)
+  if (!workspaceRelative) return false
+  const match = VAULT_MARKDOWN_RE.exec(workspaceRelative)
+  return Boolean(match?.[1])
+}
+
+export function normalizeNarrativeVaultMarkdownPath(filePath: string, workspaceRoot: string): string | undefined {
+  const workspaceRelative = toWorkspaceRelativePath(filePath, workspaceRoot)
+  if (!workspaceRelative) return undefined
+  return VAULT_MARKDOWN_RE.test(workspaceRelative) ? workspaceRelative : undefined
+}
+
+export function extractNarrativeVaultMarkdownTargetsFromPatch(patchText: string, workspaceRoot: string): string[] {
+  const targets = new Set<string>()
+
+  for (const line of patchText.replace(/\r\n/g, "\n").split("\n")) {
+    const match = /^\*\*\*\s+(?:Add File|Update File|Delete File|Move to):\s*(.+?)\s*$/.exec(line)
+    if (!match) continue
+    const target = normalizeNarrativeVaultMarkdownPath(match[1].trim(), workspaceRoot)
+    if (target) targets.add(target)
+  }
+
+  return [...targets]
+}
+
+function toWorkspaceRelativePath(filePath: string, workspaceRoot: string): string | undefined {
+  const normalized = filePath.replace(/\\/g, "/").trim()
+  if (!normalized) return undefined
+
+  const root = resolve(workspaceRoot)
+  const absolute = resolve(root, normalized)
+  const rel = relative(root, absolute).replace(/\\/g, "/")
+  if (!rel || rel === "." || rel.startsWith("../") || rel === "..") return undefined
+  return rel
+}

package/lib/narrative-vault/index.ts

@@ -0,0 +1,18 @@
+export * from "./cache"
+export * from "./authoring-contract"
+export * from "./bootstrap"
+export * from "./compile"
+export * from "./diagnostic-report"
+export * from "./export"
+export * from "./frontmatter"
+export * from "./inventory"
+export * from "./markdown"
+export * from "./markdown-qa"
+export * from "./migration"
+export * from "./mutate"
+export * from "./paths"
+export * from "./read"
+export * from "./relations"
+export * from "./source-loader"
+export * from "./timestamp"
+export * from "./types"