@hugobatist/smartcode 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,374 @@
+/** Status of a diagram node */
+type NodeStatus = 'ok' | 'problem' | 'in-progress' | 'discarded';
+/** A flag annotation on a diagram node */
+interface Flag {
+    nodeId: string;
+    message: string;
+    timestamp?: number;
+}
+/** A node in a Mermaid diagram */
+interface DiagramNode {
+    id: string;
+    label: string;
+    shape: string;
+    status?: NodeStatus;
+}
+/** An edge between two nodes */
+interface DiagramEdge {
+    from: string;
+    to: string;
+    label?: string;
+    type: 'arrow' | 'open' | 'dotted' | 'thick';
+}
+/** Parsed content of a .mmd file */
+interface DiagramContent {
+    /** The raw file content including annotations */
+    raw: string;
+    /** Mermaid content with annotations stripped */
+    mermaidContent: string;
+    /** Parsed flag annotations */
+    flags: Map<string, Flag>;
+    /** Parsed status annotations */
+    statuses: Map<string, NodeStatus>;
+    /** Parsed breakpoint annotations (node IDs with active breakpoints) */
+    breakpoints: Set<string>;
+    /** Parsed risk annotations */
+    risks: Map<string, RiskAnnotation>;
+    /** Parsed ghost path annotations */
+    ghosts: GhostPathAnnotation[];
+    /** Validation result for the Mermaid syntax */
+    validation: ValidationResult;
+    /** Relative file path within the project */
+    filePath: string;
+}
+/** Result of Mermaid syntax validation */
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    diagramType?: string;
+}
+/** A structured validation error */
+interface ValidationError {
+    message: string;
+    line?: number;
+    column?: number;
+}
+/** Risk level for a node annotation */
+type RiskLevel = 'high' | 'medium' | 'low';
+/** A risk annotation on a diagram node */
+interface RiskAnnotation {
+    nodeId: string;
+    level: RiskLevel;
+    reason: string;
+}
+/** A ghost path suggested by AI for alternative diagram flow */
+interface GhostPath {
+    fromNodeId: string;
+    toNodeId: string;
+    label?: string;
+    timestamp: number;
+}
+/** A ghost path annotation persisted in a .mmd file (no timestamp) */
+interface GhostPathAnnotation {
+    fromNodeId: string;
+    toNodeId: string;
+    label: string;
+}
+/** A project containing .mmd files */
+interface Project {
+    /** Absolute path to the project root directory */
+    rootDir: string;
+    /** Relative paths to .mmd files within the project */
+    files: string[];
+}
+
+type NodeShape = 'rect' | 'rounded' | 'stadium' | 'subroutine' | 'cylinder' | 'circle' | 'asymmetric' | 'diamond' | 'hexagon' | 'parallelogram' | 'parallelogram-alt' | 'trapezoid' | 'trapezoid-alt';
+type EdgeType = 'arrow' | 'open' | 'dotted' | 'thick' | 'invisible';
+type FlowDirection = 'TB' | 'LR' | 'BT' | 'RL';
+interface GraphNode {
+    id: string;
+    label: string;
+    shape: NodeShape;
+    status?: NodeStatus;
+    flag?: Flag;
+    subgraphId?: string;
+    cssClass?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+interface GraphEdge {
+    id: string;
+    from: string;
+    to: string;
+    label?: string;
+    type: EdgeType;
+    bidirectional?: boolean;
+}
+interface GraphSubgraph {
+    id: string;
+    label: string;
+    parentId: string | null;
+    nodeIds: string[];
+    childSubgraphIds: string[];
+}
+interface GraphModel {
+    diagramType: 'flowchart' | 'graph';
+    direction: FlowDirection;
+    nodes: Map<string, GraphNode>;
+    edges: GraphEdge[];
+    subgraphs: Map<string, GraphSubgraph>;
+    classDefs: Map<string, string>;
+    nodeStyles: Map<string, string>;
+    linkStyles: Map<number, string>;
+    classAssignments: Map<string, string>;
+    filePath: string;
+    flags: Map<string, Flag>;
+    statuses: Map<string, NodeStatus>;
+    validation: ValidationResult;
+}
+
+/**
+ * DiagramService -- single entry point for all .mmd file operations.
+ * Each instance is bound to a project root for path security.
+ */
+declare class DiagramService {
+    private readonly projectRoot;
+    /** Per-file write locks to serialize concurrent write operations */
+    private writeLocks;
+    /**
+     * Serialize write operations on a given file path.
+     * Each call waits for the previous write on the same file to finish before running.
+     * Cleans up lock entry when no further writes are queued.
+     */
+    private withWriteLock;
+    constructor(projectRoot: string);
+    /**
+     * Read a .mmd file and parse all annotations + mermaid content in one pass.
+     */
+    private readAllAnnotations;
+    /**
+     * Read-modify-write cycle for annotation mutations.
+     * Acquires the write lock, reads all annotations, calls modifyFn to mutate them,
+     * then writes the result back.
+     */
+    private modifyAnnotation;
+    /**
+     * Read and parse a .mmd file.
+     * Resolves path with traversal protection, parses content, and validates syntax.
+     */
+    readDiagram(filePath: string): Promise<DiagramContent>;
+    /**
+     * Read a .mmd file and parse it into a structured GraphModel.
+     */
+    readGraph(filePath: string): Promise<GraphModel>;
+    /**
+     * Write a .mmd file. If flags or statuses are provided, injects annotation block.
+     * Creates parent directories if they don't exist.
+     */
+    writeDiagram(filePath: string, content: string, flags?: Map<string, Flag>, statuses?: Map<string, NodeStatus>, breakpoints?: Set<string>, risks?: Map<string, RiskAnnotation>, ghosts?: GhostPathAnnotation[]): Promise<void>;
+    /**
+     * Write diagram content while preserving existing developer-owned annotations (flags, breakpoints).
+     * Reads existing annotations first, merges caller-provided statuses/risks/ghosts on top, preserves flags
+     * and breakpoints unconditionally, then writes the merged result atomically under the write lock.
+     *
+     * Merge semantics:
+     * - `content`: always replaces the Mermaid diagram body
+     * - `statuses`: if provided, replaces all statuses; if undefined, preserves existing
+     * - `risks`: if provided, replaces all risks; if undefined, preserves existing
+     * - `ghosts`: if provided, replaces all ghosts; if undefined, preserves existing
+     * - `flags`: always preserved from the file (developer-owned, never touched by MCP)
+     * - `breakpoints`: always preserved from the file (developer-owned, never touched by MCP)
+     */
+    writeDiagramPreserving(filePath: string, content: string, statuses?: Map<string, NodeStatus>, risks?: Map<string, RiskAnnotation>, ghosts?: GhostPathAnnotation[]): Promise<void>;
+    /**
+     * Write raw content to a .mmd file under the write lock.
+     * Does NOT process annotations -- writes content as-is.
+     * Used by /save endpoint which receives pre-formatted content from the editor.
+     */
+    writeRaw(filePath: string, content: string): Promise<void>;
+    /**
+     * Internal write without acquiring the lock.
+     * Used by methods that already hold the write lock for the same file.
+     */
+    private _writeDiagramInternal;
+    /** Get all flags from a .mmd file as an array. */
+    getFlags(filePath: string): Promise<Flag[]>;
+    /** Set (add or update) a flag on a specific node. */
+    setFlag(filePath: string, nodeId: string, message: string): Promise<void>;
+    /** Remove a flag from a specific node. */
+    removeFlag(filePath: string, nodeId: string): Promise<void>;
+    /** Get all statuses from a .mmd file. */
+    getStatuses(filePath: string): Promise<Map<string, NodeStatus>>;
+    /** Set (add or update) a status on a specific node. */
+    setStatus(filePath: string, nodeId: string, status: NodeStatus): Promise<void>;
+    /** Remove a status from a specific node. */
+    removeStatus(filePath: string, nodeId: string): Promise<void>;
+    /** Get all breakpoints from a .mmd file. */
+    getBreakpoints(filePath: string): Promise<Set<string>>;
+    /** Set (add) a breakpoint on a specific node. */
+    setBreakpoint(filePath: string, nodeId: string): Promise<void>;
+    /** Remove a breakpoint from a specific node. */
+    removeBreakpoint(filePath: string, nodeId: string): Promise<void>;
+    /** Get all risk annotations from a .mmd file. */
+    getRisks(filePath: string): Promise<Map<string, RiskAnnotation>>;
+    /** Set (add or update) a risk annotation on a specific node. */
+    setRisk(filePath: string, nodeId: string, level: RiskLevel, reason: string): Promise<void>;
+    /** Remove a risk annotation from a specific node. */
+    removeRisk(filePath: string, nodeId: string): Promise<void>;
+    /** Get all ghost path annotations from a .mmd file. */
+    getGhosts(filePath: string): Promise<GhostPathAnnotation[]>;
+    /** Add a ghost path annotation to a .mmd file. */
+    addGhost(filePath: string, fromNodeId: string, toNodeId: string, label: string): Promise<void>;
+    /** Remove a specific ghost path annotation (by from+to+label exact match). */
+    removeGhost(filePath: string, fromNodeId: string, toNodeId: string): Promise<void>;
+    /** Clear all ghost path annotations from a .mmd file. */
+    clearGhosts(filePath: string): Promise<void>;
+    /** Validate the Mermaid syntax of a .mmd file. */
+    validate(filePath: string): Promise<ValidationResult>;
+    /** List all .mmd files in the project root. */
+    listFiles(): Promise<string[]>;
+    /**
+     * Resolve a relative file path against the project root.
+     * Single chokepoint for path security -- rejects path traversal.
+     */
+    private resolvePath;
+}
+
+/** Result of parsing all annotation types in a single pass */
+interface AllAnnotations {
+    flags: Map<string, Flag>;
+    statuses: Map<string, NodeStatus>;
+    breakpoints: Set<string>;
+    risks: Map<string, RiskAnnotation>;
+    ghosts: GhostPathAnnotation[];
+}
+/**
+ * Parse all annotation types (flags, statuses, breakpoints, risks) in a single pass.
+ * Iterates through lines once, matching each annotation regex.
+ * Unrecognized lines inside the annotation block are logged as debug warnings.
+ */
+declare function parseAllAnnotations(content: string): AllAnnotations;
+/** Parse all `%% @flag` lines. Delegates to parseAllAnnotations. */
+declare function parseFlags(content: string): Map<string, Flag>;
+/**
+ * Remove the entire annotation block (from ANNOTATION_START to ANNOTATION_END inclusive)
+ * and any trailing blank lines. Returns pure Mermaid content.
+ */
+declare function stripAnnotations(content: string): string;
+/**
+ * Strip existing annotations, then append a new annotation block at the end.
+ * If both flags and statuses maps are empty, returns content with no annotation block.
+ * Escapes double quotes in flag messages by replacing " with ''.
+ */
+declare function injectAnnotations(content: string, flags: Map<string, Flag>, statuses?: Map<string, NodeStatus>, breakpoints?: Set<string>, risks?: Map<string, RiskAnnotation>, ghosts?: GhostPathAnnotation[]): string;
+
+/**
+ * Validate Mermaid syntax using a regex-based heuristic approach.
+ *
+ * The @mermaid-js/parser package (v0.6) only supports a limited set of diagram types
+ * (info, packet, pie, architecture, gitGraph, radar) and does NOT support flowchart,
+ * which is the primary diagram type for SmartCode. We use a heuristic validator that
+ * catches obvious syntax errors. Browser-side Mermaid.js catches the rest at render time.
+ */
+declare function validateMermaidSyntax(content: string): ValidationResult;
+
+/**
+ * Extract the diagram type from the first non-empty, non-comment line.
+ * Returns the matched type string or undefined if no match.
+ */
+declare function parseDiagramType(content: string): string | undefined;
+/**
+ * Convenience function that strips annotations, parses flags, and detects diagram type.
+ * Returns all three results together.
+ */
+declare function parseDiagramContent(rawContent: string): {
+    mermaidContent: string;
+    flags: Map<string, Flag>;
+    diagramType?: string;
+};
+
+/**
+ * SmartCode - Mermaid to GraphModel Parser
+ * Multi-pass parser that converts raw .mmd content into a structured GraphModel.
+ */
+
+/**
+ * Parse raw .mmd content into a structured GraphModel.
+ * Uses a multi-pass pipeline: preprocessing, direction, styles,
+ * subgraphs, nodes, edges, annotations merge, validation.
+ */
+declare function parseMermaidToGraph(rawContent: string, filePath: string): GraphModel;
+
+/**
+ * SmartCode - GraphModel to Mermaid Serializer
+ * Converts a structured GraphModel back into valid Mermaid flowchart text.
+ * Counterpart to graph-parser.ts — together they enable round-trip fidelity.
+ */
+
+/**
+ * Serialize a GraphModel to valid Mermaid flowchart text.
+ *
+ * Output order (canonical):
+ *   1. Direction line: `flowchart LR`
+ *   2. classDef directives
+ *   3. Subgraph blocks (recursive, with nodes inside)
+ *   4. Root-level nodes (not inside any subgraph)
+ *   5. Edges
+ *   6. style directives
+ *   7. linkStyle directives
+ *   8. class assignments
+ */
+declare function serializeGraphToMermaid(graph: GraphModel): string;
+/**
+ * Serialize a GraphModel to a plain JSON-safe object.
+ * Converts all Map fields to plain objects for transmission over WebSocket or REST.
+ */
+declare function serializeGraphModel(graph: GraphModel): Record<string, unknown>;
+
+/**
+ * ProjectManager managing multiple project directories.
+ * Each project gets its own DiagramService with independent path security.
+ */
+declare class ProjectManager {
+    private projects;
+    /**
+     * Register a project directory and return its DiagramService.
+     * If the directory is already registered, returns the existing service.
+     * Throws if the directory does not exist.
+     */
+    addProject(rootDir: string): DiagramService;
+    /**
+     * Remove a project from management.
+     * Returns true if it was registered, false otherwise.
+     */
+    removeProject(rootDir: string): boolean;
+    /**
+     * Get the DiagramService for a registered project directory.
+     * Returns undefined if the directory is not registered.
+     */
+    getProject(rootDir: string): DiagramService | undefined;
+    /**
+     * List all registered project root directories.
+     */
+    listProjects(): string[];
+    /**
+     * Discover .mmd files across all registered projects.
+     * Returns a map of rootDir to file lists.
+     */
+    discoverAll(): Promise<Map<string, string[]>>;
+}
+
+/**
+ * Discover all .mmd files recursively under the given directory.
+ * Returns relative paths (relative to the directory).
+ * Excludes node_modules, .git, test, dist, .planning, and .smartcode directories.
+ * Results are sorted alphabetically for deterministic output.
+ *
+ * Uses recursive readdir (Node 18.17+) with post-filtering to avoid
+ * external CJS dependency bundling issues with tsup ESM output.
+ */
+declare function discoverMmdFiles(directory: string): Promise<string[]>;
+
+export { type AllAnnotations, type DiagramContent, type DiagramEdge, type DiagramNode, DiagramService, type EdgeType, type Flag, type FlowDirection, type GhostPath, type GhostPathAnnotation, type GraphEdge, type GraphModel, type GraphNode, type GraphSubgraph, type NodeShape, type NodeStatus, type Project, ProjectManager, type RiskAnnotation, type RiskLevel, type ValidationError, type ValidationResult, discoverMmdFiles, injectAnnotations, parseAllAnnotations, parseDiagramContent, parseDiagramType, parseFlags, parseMermaidToGraph, serializeGraphModel, serializeGraphToMermaid, stripAnnotations, validateMermaidSyntax };