zyflow 0.6.4

package/packages/gitdiagram-core/src/mermaid-utils.ts

@@ -0,0 +1,304 @@
+/**
+ * Mermaid.js Utilities
+ *
+ * Validation, parsing, and click event processing for Mermaid diagrams
+ */
+
+export interface ClickEvent {
+  /** Node ID in the diagram */
+  nodeId: string;
+  /** File or directory path */
+  path: string;
+}
+
+export interface ValidationResult {
+  /** Whether the diagram is valid */
+  valid: boolean;
+  /** Validation errors */
+  errors: string[];
+  /** Validation warnings */
+  warnings: string[];
+}
+
+/**
+ * Common Mermaid syntax errors to check for
+ */
+const SYNTAX_CHECKS = [
+  {
+    // Special characters without quotes in node labels
+    pattern: /\[([^\]"]*[()\\<>][^\]"]*)\]/g,
+    message: 'Node label contains special characters without quotes',
+    severity: 'error' as const,
+  },
+  {
+    // Spaces in relationship labels
+    pattern: /-->\|\s+[^|]+\s+\|/g,
+    message: 'Relationship label has spaces around content',
+    severity: 'warning' as const,
+  },
+  {
+    // Class style on subgraph
+    pattern: /subgraph\s+"[^"]*":::/g,
+    message: 'Cannot apply class style directly to subgraph declaration',
+    severity: 'error' as const,
+  },
+  {
+    // Subgraph with alias
+    pattern: /subgraph\s+\w+\s+"[^"]*"/g,
+    message: 'Subgraphs cannot have aliases like nodes',
+    severity: 'error' as const,
+  },
+  {
+    // Init declaration (should be handled externally)
+    pattern: /%%\{init:/g,
+    message: 'Init declaration should be handled externally',
+    severity: 'warning' as const,
+  },
+];
+
+/**
+ * Validate Mermaid diagram syntax
+ */
+export function validateMermaidSyntax(code: string): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Check for empty code
+  if (!code.trim()) {
+    return {
+      valid: false,
+      errors: ['Empty diagram code'],
+      warnings: [],
+    };
+  }
+
+  // Check for diagram type declaration
+  const firstLine = code.trim().split('\n')[0];
+  const validTypes = [
+    'flowchart',
+    'graph',
+    'sequenceDiagram',
+    'classDiagram',
+    'stateDiagram',
+    'erDiagram',
+    'journey',
+    'gantt',
+    'pie',
+    'gitGraph',
+    'mindmap',
+    'timeline',
+    'quadrantChart',
+    'requirementDiagram',
+    'C4Context',
+    'architecture',
+  ];
+
+  const hasValidType = validTypes.some(
+    (type) =>
+      firstLine.startsWith(type) ||
+      firstLine.startsWith(`%%`) ||
+      firstLine.startsWith('---')
+  );
+
+  if (!hasValidType) {
+    warnings.push(
+      `First line should be a diagram type declaration (found: "${firstLine.slice(0, 30)}...")`
+    );
+  }
+
+  // Run syntax checks
+  for (const check of SYNTAX_CHECKS) {
+    const matches = code.match(check.pattern);
+    if (matches) {
+      const message = `${check.message} (${matches.length} occurrence(s))`;
+      if (check.severity === 'error') {
+        errors.push(message);
+      } else {
+        warnings.push(message);
+      }
+    }
+  }
+
+  // Check for balanced brackets and parentheses
+  const brackets = { '[': ']', '(': ')', '{': '}', '"': '"' };
+  const stack: string[] = [];
+
+  for (const char of code) {
+    if ('[({'.includes(char)) {
+      stack.push(char);
+    } else if ('])}'.includes(char)) {
+      const expected = brackets[stack.pop() as keyof typeof brackets];
+      if (expected !== char) {
+        errors.push('Unbalanced brackets/parentheses');
+        break;
+      }
+    }
+  }
+
+  if (stack.length > 0) {
+    errors.push('Unclosed brackets/parentheses');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Extract click events from Mermaid code
+ */
+export function extractClickEvents(code: string): ClickEvent[] {
+  const events: ClickEvent[] = [];
+
+  // Match click events: click NodeId "path"
+  const clickPattern = /click\s+(\w+)\s+"([^"]+)"/g;
+
+  let match;
+  while ((match = clickPattern.exec(code)) !== null) {
+    events.push({
+      nodeId: match[1],
+      path: match[2],
+    });
+  }
+
+  return events;
+}
+
+/**
+ * Add or update click events in Mermaid code
+ */
+export function updateClickEvents(
+  code: string,
+  events: ClickEvent[]
+): string {
+  let result = code;
+
+  // Remove existing click events section if present
+  result = result.replace(/\n\s*%% Click Events[\s\S]*?(?=\n\s*%%|$)/g, '');
+
+  // Remove individual click events
+  result = result.replace(/\n\s*click\s+\w+\s+"[^"]+"/g, '');
+
+  // Add new click events before styles section or at the end
+  if (events.length > 0) {
+    const clickSection =
+      '\n    %% Click Events\n' +
+      events.map((e) => `    click ${e.nodeId} "${e.path}"`).join('\n');
+
+    // Try to insert before styles section
+    const stylesMatch = result.match(/\n\s*%% Styles/);
+    if (stylesMatch && stylesMatch.index !== undefined) {
+      result =
+        result.slice(0, stylesMatch.index) +
+        clickSection +
+        '\n' +
+        result.slice(stylesMatch.index);
+    } else {
+      result = result.trimEnd() + '\n' + clickSection;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convert file paths to GitHub URLs
+ */
+export function pathsToGitHubUrls(
+  code: string,
+  repoUrl: string,
+  branch: string = 'main'
+): string {
+  // Normalize repo URL
+  const baseUrl = repoUrl.replace(/\.git$/, '').replace(/\/$/, '');
+
+  // Extract click events and update paths
+  const clickPattern = /click\s+(\w+)\s+"([^"]+)"/g;
+
+  return code.replace(clickPattern, (match, nodeId, path) => {
+    // Skip if already a URL
+    if (path.startsWith('http')) {
+      return match;
+    }
+
+    const fullUrl = `${baseUrl}/blob/${branch}/${path}`;
+    return `click ${nodeId} "${fullUrl}"`;
+  });
+}
+
+/**
+ * Extract node IDs from Mermaid code
+ */
+export function extractNodeIds(code: string): string[] {
+  const nodeIds = new Set<string>();
+
+  // Match node definitions: NodeId[...] or NodeId(...) or NodeId{...}
+  const nodePattern = /^\s*(\w+)\s*[[({]/gm;
+
+  let match;
+  while ((match = nodePattern.exec(code)) !== null) {
+    nodeIds.add(match[1]);
+  }
+
+  return Array.from(nodeIds);
+}
+
+/**
+ * Add color styling if missing
+ */
+export function ensureColorStyles(code: string): string {
+  // Check if any classDef is present
+  if (code.includes('classDef')) {
+    return code;
+  }
+
+  // Add default color styles
+  const defaultStyles = `
+    %% Styles
+    classDef frontend fill:#42b883,stroke:#35495e,color:#fff
+    classDef backend fill:#68a063,stroke:#3e6b38,color:#fff
+    classDef database fill:#336791,stroke:#1a3a52,color:#fff
+    classDef external fill:#f5a623,stroke:#c4841d,color:#fff
+    classDef api fill:#61dafb,stroke:#20a4d8,color:#333
+`;
+
+  return code.trimEnd() + '\n' + defaultStyles;
+}
+
+/**
+ * Format Mermaid code for better readability
+ */
+export function formatMermaidCode(code: string): string {
+  const lines = code.split('\n');
+  const formatted: string[] = [];
+
+  let indentLevel = 0;
+  const baseIndent = '    ';
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines
+    if (!trimmed) {
+      formatted.push('');
+      continue;
+    }
+
+    // Decrease indent for 'end' keyword
+    if (trimmed === 'end') {
+      indentLevel = Math.max(0, indentLevel - 1);
+    }
+
+    // Add line with proper indentation
+    formatted.push(baseIndent.repeat(indentLevel) + trimmed);
+
+    // Increase indent after 'subgraph'
+    if (trimmed.startsWith('subgraph')) {
+      indentLevel++;
+    }
+  }
+
+  return formatted.join('\n');
+}

package/packages/gitdiagram-core/src/prompts.ts

@@ -0,0 +1,281 @@
+/**
+ * GitDiagram Prompt Templates
+ *
+ * Ported from: https://github.com/ahmedkhaleel2004/gitdiagram/blob/main/backend/app/prompts.py
+ * Original author: Ahmed Khaleel
+ *
+ * The generation process:
+ * 1. prompt1(file_tree, readme) -> explanation of diagram
+ * 2. prompt2(explanation, file_tree) -> maps relevant directories and files for interactivity
+ * 3. prompt3(explanation, map) -> Mermaid.js code
+ */
+
+/**
+ * First prompt: Analyzes project structure and README to explain how to create
+ * an accurate system design diagram.
+ */
+export const SYSTEM_FIRST_PROMPT = `
+You are tasked with explaining to a principal software engineer how to draw the best and most accurate system design diagram / architecture of a given project. This explanation should be tailored to the specific project's purpose and structure. To accomplish this, you will be provided with two key pieces of information:
+
+1. The complete and entire file tree of the project including all directory and file names, which will be enclosed in <file_tree> tags in the users message.
+
+2. The README file of the project, which will be enclosed in <readme> tags in the users message.
+
+Analyze these components carefully, as they will provide crucial information about the project's structure and purpose. Follow these steps to create an explanation for the principal software engineer:
+
+1. Identify the project type and purpose:
+   - Examine the file structure and README to determine if the project is a full-stack application, an open-source tool, a compiler, or another type of software imaginable.
+   - Look for key indicators in the README, such as project description, features, or use cases.
+
+2. Analyze the file structure:
+   - Pay attention to top-level directories and their names (e.g., "frontend", "backend", "src", "lib", "tests").
+   - Identify patterns in the directory structure that might indicate architectural choices (e.g., MVC pattern, microservices).
+   - Note any configuration files, build scripts, or deployment-related files.
+
+3. Examine the README for additional insights:
+   - Look for sections describing the architecture, dependencies, or technical stack.
+   - Check for any diagrams or explanations of the system's components.
+
+4. Based on your analysis, explain how to create a system design diagram that accurately represents the project's architecture. Include the following points:
+
+   a. Identify the main components of the system (e.g., frontend, backend, database, building, external services).
+   b. Determine the relationships and interactions between these components.
+   c. Highlight any important architectural patterns or design principles used in the project.
+   d. Include relevant technologies, frameworks, or libraries that play a significant role in the system's architecture.
+
+5. Provide guidelines for tailoring the diagram to the specific project type:
+   - For a full-stack application, emphasize the separation between frontend and backend, database interactions, and any API layers.
+   - For an open-source tool, focus on the core functionality, extensibility points, and how it integrates with other systems.
+   - For a compiler or language-related project, highlight the different stages of compilation or interpretation, and any intermediate representations.
+
+6. Instruct the principal software engineer to include the following elements in the diagram:
+   - Clear labels for each component
+   - Directional arrows to show data flow or dependencies
+   - Color coding or shapes to distinguish between different types of components
+
+7. NOTE: Emphasize the importance of being very detailed and capturing the essential architectural elements. Don't overthink it too much, simply separating the project into as many components as possible is best.
+
+Present your explanation and instructions within <explanation> tags, ensuring that you tailor your advice to the specific project based on the provided file tree and README content.
+`;
+
+/**
+ * Second prompt: Maps key components to their corresponding files and directories
+ * for click event interactivity in the diagram.
+ */
+export const SYSTEM_SECOND_PROMPT = `
+You are tasked with mapping key components of a system design to their corresponding files and directories in a project's file structure. You will be provided with a detailed explanation of the system design/architecture and a file tree of the project.
+
+First, carefully read the system design explanation which will be enclosed in <explanation> tags in the users message.
+
+Then, examine the file tree of the project which will be enclosed in <file_tree> tags in the users message.
+
+Your task is to analyze the system design explanation and identify key components, modules, or services mentioned. Then, try your best to map these components to what you believe could be their corresponding directories and files in the provided file tree.
+
+Guidelines:
+1. Focus on major components described in the system design.
+2. Look for directories and files that clearly correspond to these components.
+3. Include both directories and specific files when relevant.
+4. If a component doesn't have a clear corresponding file or directory, simply dont include it in the map.
+
+Now, provide your final answer in the following format:
+
+<component_mapping>
+1. [Component Name]: [File/Directory Path]
+2. [Component Name]: [File/Directory Path]
+[Continue for all identified components]
+</component_mapping>
+
+Remember to be as specific as possible in your mappings, only use what is given to you from the file tree, and to strictly follow the components mentioned in the explanation.
+`;
+
+/**
+ * Third prompt: Generates Mermaid.js diagram code based on the explanation
+ * and component mappings.
+ */
+export const SYSTEM_THIRD_PROMPT = `
+You are a principal software engineer tasked with creating a system design diagram using Mermaid.js based on a detailed explanation. Your goal is to accurately represent the architecture and design of the project as described in the explanation.
+
+The detailed explanation of the design will be enclosed in <explanation> tags in the users message.
+
+Also, sourced from the explanation, as a bonus, a few of the identified components have been mapped to their paths in the project file tree, whether it is a directory or file which will be enclosed in <component_mapping> tags in the users message.
+
+To create the Mermaid.js diagram:
+
+1. Carefully read and analyze the provided design explanation.
+2. Identify the main components, services, and their relationships within the system.
+3. Determine the appropriate Mermaid.js diagram type to use (e.g., flowchart, sequence diagram, class diagram, architecture, etc.) based on the nature of the system described.
+4. Create the Mermaid.js code to represent the design, ensuring that:
+   a. All major components are included
+   b. Relationships between components are clearly shown
+   c. The diagram accurately reflects the architecture described in the explanation
+   d. The layout is logical and easy to understand
+
+Guidelines for diagram components and relationships:
+- Use appropriate shapes for different types of components (e.g., rectangles for services, cylinders for databases, etc.)
+- Use clear and concise labels for each component
+- Show the direction of data flow or dependencies using arrows
+- Group related components together if applicable
+- Include any important notes or annotations mentioned in the explanation
+- Just follow the explanation. It will have everything you need.
+
+IMPORTANT!!: Please orient and draw the diagram as vertically as possible. You must avoid long horizontal lists of nodes and sections!
+
+You must include click events for components of the diagram that have been specified in the provided <component_mapping>:
+- Do not try to include the full url. This will be processed by another program afterwards. All you need to do is include the path.
+- For example:
+  - This is a correct click event: \`click Example "app/example.js"\`
+  - This is an incorrect click event: \`click Example "https://github.com/username/repo/blob/main/app/example.js"\`
+- Do this for as many components as specified in the component mapping, include directories and files.
+  - If you believe the component contains files and is a directory, include the directory path.
+  - If you believe the component references a specific file, include the file path.
+- Make sure to include the full path to the directory or file exactly as specified in the component mapping.
+- It is very important that you do this for as many files as possible. The more the better.
+
+- IMPORTANT: THESE PATHS ARE FOR CLICK EVENTS ONLY, these paths should not be included in the diagram's node's names. Only for the click events. Paths should not be seen by the user.
+
+Your output should be valid Mermaid.js code that can be rendered into a diagram.
+
+Do not include an init declaration such as \`%%{init: {'key':'etc'}}%%\`. This is handled externally. Just return the diagram code.
+
+Your response must strictly be just the Mermaid.js code, without any additional text or explanations.
+No code fence or markdown ticks needed, simply return the Mermaid.js code.
+
+Ensure that your diagram adheres strictly to the given explanation, without adding or omitting any significant components or relationships.
+
+For general direction, the provided example below is how you should structure your code:
+
+\`\`\`mermaid
+flowchart TD
+    %% or graph TD, your choice
+
+    %% Global entities
+    A("Entity A"):::external
+    %% more...
+
+    %% Subgraphs and modules
+    subgraph "Layer A"
+        A1("Module A"):::example
+        %% more modules...
+        %% inner subgraphs if needed...
+    end
+
+    %% more subgraphs, modules, etc...
+
+    %% Connections
+    A -->|"relationship"| B
+    %% and a lot more...
+
+    %% Click Events
+    click A1 "example/example.js"
+    %% and a lot more...
+
+    %% Styles
+    classDef frontend %%...
+    %% and a lot more...
+\`\`\`
+
+EXTREMELY Important notes on syntax!!! (PAY ATTENTION TO THIS):
+- Make sure to add colour to the diagram!!! This is extremely critical.
+- In Mermaid.js syntax, we cannot include special characters for nodes without being inside quotes! For example: \`EX[/api/process (Backend)]:::api\` and \`API -->|calls Process()| Backend\` are two examples of syntax errors. They should be \`EX["/api/process (Backend)"]:::api\` and \`API -->|"calls Process()"| Backend\` respectively. Notice the quotes. This is extremely important. Make sure to include quotes for any string that contains special characters.
+- In Mermaid.js syntax, you cannot apply a class style directly within a subgraph declaration. For example: \`subgraph "Frontend Layer":::frontend\` is a syntax error. However, you can apply them to nodes within the subgraph. For example: \`Example["Example Node"]:::frontend\` is valid, and \`class Example1,Example2 frontend\` is valid.
+- In Mermaid.js syntax, there cannot be spaces in the relationship label names. For example: \`A -->| "example relationship" | B\` is a syntax error. It should be \`A -->|"example relationship"| B\`
+- In Mermaid.js syntax, you cannot give subgraphs an alias like nodes. For example: \`subgraph A "Layer A"\` is a syntax error. It should be \`subgraph "Layer A"\`
+`;
+
+/**
+ * Additional instructions prompt: Handles custom user instructions.
+ * Returns "BAD_INSTRUCTIONS" if instructions are unclear or unrelated.
+ */
+export const ADDITIONAL_SYSTEM_INSTRUCTIONS_PROMPT = `
+IMPORTANT: the user will provide custom additional instructions enclosed in <instructions> tags. Please take these into account and give priority to them. However, if these instructions are unrelated to the task, unclear, or not possible to follow, ignore them by simply responding with: "BAD_INSTRUCTIONS"
+`;
+
+/**
+ * Modify prompt: Modifies existing Mermaid.js diagrams based on user instructions.
+ */
+export const SYSTEM_MODIFY_PROMPT = `
+You are tasked with modifying the code of a Mermaid.js diagram based on the provided instructions. The diagram will be enclosed in <diagram> tags in the users message.
+
+Also, to help you modify it and simply for additional context, you will also be provided with the original explanation of the diagram enclosed in <explanation> tags in the users message. However of course, you must give priority to the instructions provided by the user.
+
+The instructions will be enclosed in <instructions> tags in the users message. If these instructions are unrelated to the task, unclear, or not possible to follow, ignore them by simply responding with: "BAD_INSTRUCTIONS"
+
+Your response must strictly be just the Mermaid.js code, without any additional text or explanations. Keep as many of the existing click events as possible.
+No code fence or markdown ticks needed, simply return the Mermaid.js code.
+`;
+
+/**
+ * Helper function to create a user message for the first prompt
+ */
+export function createFirstPromptUserMessage(
+  fileTree: string,
+  readme: string
+): string {
+  return `<file_tree>
+${fileTree}
+</file_tree>
+
+<readme>
+${readme}
+</readme>`;
+}
+
+/**
+ * Helper function to create a user message for the second prompt
+ */
+export function createSecondPromptUserMessage(
+  explanation: string,
+  fileTree: string
+): string {
+  return `<explanation>
+${explanation}
+</explanation>
+
+<file_tree>
+${fileTree}
+</file_tree>`;
+}
+
+/**
+ * Helper function to create a user message for the third prompt
+ */
+export function createThirdPromptUserMessage(
+  explanation: string,
+  componentMapping: string
+): string {
+  return `<explanation>
+${explanation}
+</explanation>
+
+<component_mapping>
+${componentMapping}
+</component_mapping>`;
+}
+
+/**
+ * Helper function to create a user message for the modify prompt
+ */
+export function createModifyPromptUserMessage(
+  diagram: string,
+  explanation: string,
+  instructions: string
+): string {
+  return `<diagram>
+${diagram}
+</diagram>
+
+<explanation>
+${explanation}
+</explanation>
+
+<instructions>
+${instructions}
+</instructions>`;
+}
+
+/**
+ * Helper function to add additional instructions to a system prompt
+ */
+export function withAdditionalInstructions(systemPrompt: string): string {
+  return `${systemPrompt}\n\n${ADDITIONAL_SYSTEM_INSTRUCTIONS_PROMPT}`;
+}

package/packages/zyflow-parser/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@zyflow/parser",
+  "version": "2.0.0",
+  "description": "MoAI SPEC parser for ZyFlow",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "moai",
+    "spec",
+    "parser",
+    "zyflow"
+  ],
+  "license": "MIT"
+}

package/packages/zyflow-parser/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * ZyFlow Parser
+ * MoAI SPEC parser for plan.md, acceptance.md, spec.md
+ *
+ * @packageDocumentation
+ */
+
+// MoAI SPEC types
+export type {
+  SpecFrontmatter,
+  ParsedTag,
+  ParsedCondition,
+  ParsedAcceptanceCriteria,
+  ParsedRequirement,
+  ParsedMoaiPlan,
+  ParsedMoaiAcceptance,
+  ParsedMoaiSpec,
+} from './moai-types.js'
+
+// MoAI SPEC parser
+export {
+  parseFrontmatter,
+  parsePlanFile,
+  parseAcceptanceFile,
+  parseSpecFile,
+} from './moai-parser.js'