agentic-mermaid 0.1.1 → 0.2.0

package/src/agent/analyze.ts

@@ -1,157 +0,0 @@
-// ============================================================================
-// analyzeMermaid — deterministic facts without inventing Mermaid syntax.
-//
-// Issue #26 WS14 / issue #38 closure slice: expose the analysis facts that
-// already exist in the implementation (graph feedback classification, Gantt
-// critical path/slack, and source-only action records) through a stable API.
-// This module never executes callbacks and never mutates source/render output.
-// ============================================================================
-
-import { parseMermaid } from './parse.ts'
-import type { DiagramActionRecord, DiagramAnalysis, ParseError, Result, ValidDiagram } from './types.ts'
-import { err, ok } from './types.ts'
-import { classifyRoutes } from '../route-contracts.ts'
-import { parseMermaid as parseFlowchartLegacy } from '../parser.ts'
-import { stateBodyToGraph } from './state-body.ts'
-import { parseGanttModel, applyGanttFrontmatterConfig } from '../gantt/parser.ts'
-import { resolveGanttSchedule } from '../gantt/schedule.ts'
-import { normalizeMermaidSource, toMermaidLines } from '../mermaid-source.ts'
-import type { MermaidGraph } from '../types.ts'
-
-export function analyzeMermaid(d: ValidDiagram): DiagramAnalysis {
-  return {
-    kind: d.kind,
-    feedbackEdges: feedbackEdges(d),
-    actions: collectActionRecords(d),
-    ...(d.body.kind === 'gantt' ? ganttAnalysis(d) : {}),
-  }
-}
-
-export function analyzeMermaidSource(source: string): Result<DiagramAnalysis, ParseError[]> {
-  const parsed = parseMermaid(source)
-  return parsed.ok ? ok(analyzeMermaid(parsed.value)) : err(parsed.error)
-}
-
-function feedbackEdges(d: ValidDiagram): DiagramAnalysis['feedbackEdges'] {
-  let graph: MermaidGraph | null = null
-  if (d.body.kind === 'flowchart') graph = d.body.graph
-  else if (d.body.kind === 'state') graph = stateBodyToGraph(d.body)
-  else if (d.kind === 'flowchart' && d.body.kind === 'opaque') {
-    try { graph = parseFlowchartLegacy(d.canonicalSource) } catch { graph = null }
-  }
-  if (!graph) return []
-
-  const classes = classifyRoutes(graph)
-  return graph.edges.flatMap((edge, edgeIndex) => classes[edgeIndex] === 'feedback'
-    ? [{ edgeIndex, from: edge.source, to: edge.target, label: edge.label, routeClass: 'feedback' as const }]
-    : [])
-}
-
-function ganttAnalysis(d: ValidDiagram): Pick<DiagramAnalysis, 'gantt'> {
-  if (d.body.kind !== 'gantt') return {}
-  try {
-    const normalized = normalizeMermaidSource(d.canonicalSource)
-    const model = applyGanttFrontmatterConfig(parseGanttModel(normalized.lines), normalized.frontmatter)
-    const schedule = resolveGanttSchedule(model)
-    return schedule.analysis ? { gantt: {
-      criticalPathTaskIds: [...schedule.analysis.criticalPathTaskIds],
-      slackByTaskId: { ...schedule.analysis.slackByTaskId },
-      projectStart: schedule.analysis.projectStart,
-      projectEnd: schedule.analysis.projectEnd,
-      entryTaskIds: [...schedule.analysis.entryTaskIds],
-      sinkTaskIds: [...schedule.analysis.sinkTaskIds],
-    } } : {}
-  } catch {
-    return {}
-  }
-}
-
-export function collectActionRecords(d: ValidDiagram): DiagramActionRecord[] {
-  const source = d.body.kind === 'opaque' ? d.body.source : d.canonicalSource
-  const records: DiagramActionRecord[] = []
-  if (d.kind === 'flowchart') records.push(...collectFlowchartActions(source))
-  if (d.body.kind === 'gantt') records.push(...collectGanttActions(d))
-  const seen = new Map<string, number>()
-  return records.map(record => {
-    const key = `${record.family}:${record.target}`
-    const n = seen.get(key) ?? 0
-    seen.set(key, n + 1)
-    return { id: `action:${record.family}:${record.target}:${n}`, regionId: `node:${record.target}`, ...record }
-  })
-}
-
-function collectFlowchartActions(source: string): DiagramActionRecord[] {
-  const out: DiagramActionRecord[] = []
-  const lines = source.split(/\r?\n/)
-  for (let i = 0; i < lines.length; i++) {
-    const text = lines[i]!.trim()
-    if (!text || text.startsWith('%%')) continue
-    let m = text.match(/^href\s+(\S+)\s+(.+)$/i)
-    if (m) {
-      out.push(actionRecord('flowchart', m[1]!, 'href', m[2]!, i + 1))
-      continue
-    }
-    m = text.match(/^click\s+(\S+)\s+(.+)$/i)
-    if (!m) continue
-    const target = m[1]!
-    const rest = m[2]!.trim()
-    const explicit = rest.match(/^(href|call)\s+(.+)$/i)
-    if (explicit?.[1]?.toLowerCase() === 'href') out.push(actionRecord('flowchart', target, 'href', explicit[2]!, i + 1))
-    else if (explicit?.[1]?.toLowerCase() === 'call') out.push(actionRecord('flowchart', target, 'call', explicit[2]!, i + 1))
-    else out.push(actionRecord('flowchart', target, looksLikeHref(rest) ? 'href' : 'callback', rest, i + 1))
-  }
-  return out
-}
-
-function collectGanttActions(d: ValidDiagram): DiagramActionRecord[] {
-  if (d.body.kind !== 'gantt') return []
-  try {
-    const model = parseGanttModel(toMermaidLines(d.canonicalSource))
-    return model.clicks.map(click => actionRecord('gantt', click.taskId, click.action, click.rest, click.line))
-  } catch {
-    return []
-  }
-}
-
-function actionRecord(
-  family: DiagramActionRecord['family'],
-  target: string,
-  action: DiagramActionRecord['action'],
-  raw: string,
-  line?: number,
-): DiagramActionRecord {
-  const href = action === 'href' ? firstActionToken(raw) : undefined
-  const unsafe = href !== undefined && !isSafeHref(href)
-  return {
-    family,
-    target,
-    action,
-    raw,
-    line,
-    href,
-    executable: false,
-    security: action === 'href' ? (unsafe ? 'unsafe' : 'safe') : 'source-only',
-    message: action === 'href'
-      ? (unsafe ? 'Unsafe href is source-only and must be stripped by strict renderers.' : 'Href is an action record; non-SVG renderers keep it as source-only metadata.')
-      : 'Callbacks/calls are recorded for analysis but are never executed.',
-  }
-}
-
-function firstActionToken(raw: string): string {
-  const trimmed = raw.trim()
-  const quoted = trimmed.match(/^["']([^"']+)["']/)
-  if (quoted) return quoted[1]!
-  return trimmed.split(/\s+/)[0] ?? ''
-}
-
-function isSafeHref(href: string): boolean {
-  const trimmed = href.trim()
-  if (/^(?:https?:|mailto:)/i.test(trimmed)) return true
-  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return false
-  return trimmed.length > 0
-}
-
-function looksLikeHref(raw: string): boolean {
-  const token = firstActionToken(raw)
-  return isSafeHref(token) && (/^(?:https?:|mailto:|#|\/|\.\/|\.\.)/i.test(token) || !/^[a-z][a-z0-9+.-]*:/i.test(token))
-}

package/src/agent/apply.ts

@@ -1,146 +0,0 @@
-// ============================================================================
-// apply: the declarative, plain-JSON edit surface — the shape a hosted MCP
-// `mutate`/`build` tool and the CLI expose, and the counterpart to the Code
-// Mode `execute` path. Where `execute` hands an LLM the raw typed SDK behind a
-// sandbox, this hands it a validated op list and one canonical result DTO.
-//
-// Three jobs, one shared core (mutateChecked):
-//   - buildChecked(): author from blank — createMermaid then fold mutateChecked
-//     over the ops. Validates shape; same Result shape as buildMermaid.
-//   - applyOps(): the batch entrypoint — parse `source` (edit) or `family`
-//     (build), fold the ops, and return ONE canonical OpEnvelope: always
-//     `{ok, …}`, always plain JSON (no Result-vs-plain split, no provenance
-//     proxy, no Map), so a caller reads success and failure the same way.
-//
-// Both entrypoints, the Code Mode facade, and the CLI funnel op application
-// through mutateChecked — there is no second validator to drift from.
-// ============================================================================
-
-import { parseMermaid } from './parse.ts'
-import { serializeMermaid } from './serialize.ts'
-import { createMermaid, type CreateMermaidOptions } from './create.ts'
-import { mutateChecked } from './mutate.ts'
-import { verifyMermaid } from './verify.ts'
-import { hasOpSchema, type OpFamily, type OpValidationError } from './op-schema.ts'
-import type { MutableValidDiagram, VerifyResult, DiagramKind, MutationError, Result } from './types.ts'
-import { ok, err } from './types.ts'
-
-// ---- Canonical result envelope --------------------------------------------
-
-/** A verify summary reduced to plain JSON (no RenderedLayout proxy graph). */
-export interface VerifySummary {
-  ok: boolean
-  warnings: VerifyResult['warnings']
-}
-
-/** A mutation failure annotated with which op in the list failed. */
-export type CheckedBuildError = MutationError & { opIndex: number }
-
-/**
- * THE single output DTO for the declarative surface. Success and failure share
- * one shape: `ok` discriminates. Every field is plain JSON — safe to return
- * straight out as an MCP tool result and safe to JSON round-trip: no
- * `{ok,value}`-vs-plain split, no provenance proxy, no Map.
- */
-export type OpEnvelope =
-  | {
-      ok: true
-      family: DiagramKind
-      /** canonical Mermaid source of the mutated diagram */
-      source: string
-      verify: VerifySummary
-    }
-  | {
-      ok: false
-      family: OpFamily | DiagramKind | null
-      /** index of the failing op within the batch, when the failure is op-scoped */
-      opIndex?: number
-      error: OpValidationError | { code: string; message: string }
-    }
-
-/** Drop the layout proxy graph; keep the model-actionable verdict. The JSON
- *  round-trip guarantees no residual Map / prototype leaks through. */
-export function verifySummary(v: VerifyResult): VerifySummary {
-  return JSON.parse(JSON.stringify({ ok: v.ok, warnings: v.warnings }))
-}
-
-// ---- Blank-slate build through the checked core ---------------------------
-
-/**
- * buildMermaid's contract (createMermaid → fold ops) with the shape check in
- * front of every op. Same Result shape as buildMermaid, so it is a drop-in for
- * the untyped build path (Code Mode facade `buildMermaid`, declarative `build`).
- */
-export function buildChecked(kind: DiagramKind, ops: unknown[], opts?: CreateMermaidOptions): Result<MutableValidDiagram, CheckedBuildError> {
-  let d: MutableValidDiagram
-  try {
-    d = createMermaid(kind, opts)
-  } catch (e) {
-    return err({ code: 'INVALID_OP', message: e instanceof Error ? e.message : String(e), opIndex: -1 })
-  }
-  for (let i = 0; i < ops.length; i++) {
-    const r = mutateChecked(d, ops[i])
-    if (!r.ok) {
-      const kindLabel = (ops[i] as { kind?: unknown } | null)?.kind
-      return err({ ...r.error, opIndex: i, message: `op[${i}]${typeof kindLabel === 'string' ? ` (${kindLabel})` : ''}: ${r.error.message}` })
-    }
-    d = r.value
-  }
-  return ok(d)
-}
-
-// ---- Declarative batch entrypoint -----------------------------------------
-
-export interface ApplyOpsInput {
-  /** Existing Mermaid `source` to edit, OR `family` to author from blank. */
-  source?: string
-  family?: string
-  ops: unknown
-}
-
-/**
- * Plain-JSON-in / plain-JSON-out batch edit. Fail-fast, all-or-nothing: ops
- * apply in order over a working copy; the first invalid or semantically-rejected
- * op stops the batch and reports its index — nothing is committed (the input
- * `source` is untouched, mirroring buildMermaid). Returns the canonical envelope.
- */
-export function applyOps(input: ApplyOpsInput): OpEnvelope {
-  const { source, family, ops } = input
-
-  if (!Array.isArray(ops)) {
-    return { ok: false, family: (typeof family === 'string' && hasOpSchema(family)) ? family : null, error: { code: 'INVALID_OP', message: '`ops` must be an array of op objects' } }
-  }
-
-  let d: MutableValidDiagram
-
-  if (typeof source === 'string' && source.trim().length > 0) {
-    const parsed = parseMermaid(source)
-    if (!parsed.ok) {
-      return { ok: false, family: null, error: { code: 'PARSE_ERROR', message: parsed.error.map(e => e.message).join('; ') || 'could not parse source' } }
-    }
-    d = parsed.value as MutableValidDiagram
-    if (!hasOpSchema(d.kind)) {
-      return { ok: false, family: d.kind, error: { code: 'INVALID_OP', message: `family "${d.kind}" has no structured ops; edit it as source text` } }
-    }
-  } else if (typeof family === 'string') {
-    if (!hasOpSchema(family)) {
-      return { ok: false, family: null, error: { code: 'INVALID_OP', message: `unknown family "${family}"` } }
-    }
-    const built = buildChecked(family, ops)
-    if (!built.ok) {
-      const { opIndex, ...error } = built.error
-      return { ok: false, family, opIndex: opIndex >= 0 ? opIndex : undefined, error }
-    }
-    return { ok: true, family: built.value.kind, source: serializeMermaid(built.value), verify: verifySummary(verifyMermaid(built.value)) }
-  } else {
-    return { ok: false, family: null, error: { code: 'INVALID_OP', message: 'applyOps requires either `source` (to edit) or `family` (to build)' } }
-  }
-
-  // Edit path: fold ops over the parsed diagram.
-  for (let i = 0; i < ops.length; i++) {
-    const r = mutateChecked(d, ops[i])
-    if (!r.ok) return { ok: false, family: d.kind, opIndex: i, error: r.error }
-    d = r.value
-  }
-  return { ok: true, family: d.kind, source: serializeMermaid(d), verify: verifySummary(verifyMermaid(d)) }
-}