# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json

structure:
  - heading:
      expr: "filename == heading"
    children:
      # Permission scope for grouping related permissions - REQUIRED
      # Commands with the same scope form a permission set
      - heading: "## Permission Scope"

      # What this command does - REQUIRED
      - heading: "## Overview"

      # Business rules - REQUIRED
      # Rules, constraints, and validation logic
      - heading: "## Business Rules"
        allow_additional: true
        lists:
          - min: 0
            type: unordered
            min_items: 1

      # How it works - REQUIRED
      # Step-by-step flow or workflow
      - heading: "## Process Flow"
        code_blocks:
          - lang: mermaid
            min: 1

      # External dependencies - OPTIONAL
      # Commands from other modules that this command depends on
      - heading: "## External Dependencies"
        description: "e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity`"
        lists:
          - min: 0
            type: unordered
            min_items: 1

      # Error handling - REQUIRED
      # How errors are handled
      - heading: "## Error Scenarios"
        description: "Use UPPER_SNAKE_CASE error codes to identify each scenario.\ne.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist`"
        lists:
          - min: 0
            type: unordered
            min_items: 1

      # Test cases - REQUIRED
      # Each item corresponds to an it() block in the test file
      - heading: "## Test Cases"
        description: "List test case descriptions that correspond to it() blocks in the test file.\ne.g. `- returns error when code is empty`"
        lists:
          - min: 1
            type: unordered
            min_items: 1

# Link validation
links:
  validate_internal: true
  validate_files: true

# Heading rules
heading_rules:
  no_skip_levels: true
  unique: true
  max_depth: 4