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

# IMPLEMENTATION TIER
# Resolver file: resolver/<resolverName>.md
# Documents GraphQL operations (queries, mutations, subscriptions)

# TODO: check against resolver implementations via CI/CD pipeline

structure:
  - heading:
      expr: "filename == heading"
    description: |
      Document the GraphQL operation - mainly mutations.
    children:
      # What this Resolver does - REQUIRED
      - heading: "## Overview"
        description: |
          One concise sentence, imperative mood, stating what the operation
          does and its effect (e.g. "Creates a category and returns its ID.").
          The first paragraph becomes the resolver's AI-facing `description`,
          so keep it self-contained and free of implementation detail.
        paragraphs:
          min: 1

      # Which modules and what parts are used - REQUIRED
      - heading: "## Modules Commands Used"
        description: |
          List modules and specific features/commands used from each.
        lists:
          - min: 1
            type: unordered
            min_items: 1

      # Error Handling
      - heading: "## Exception Handling"
        optional: true
        description: |
          Document possible errors returned by this operation.
        tables:
          - min: 1
            required_headers:
              - Error Code
              - Description

# Link validation
links:
  validate_internal: true
  validate_files: true

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