.. index:: Validation, LSP

.. _validation:

Validation and Editor Integration
=================================

Bio_pype includes a validation system that checks snippets, profiles, and pipelines
for correctness. The validation can be used from the command line or integrated
with editors through the Language Server Protocol (LSP).

--------------

Command Line Validation
-----------------------

Validate Single Files
~~~~~~~~~~~~~~~~~~~~~

Validate individual files by type::

    # Validate a snippet
    pype validate snippet /path/to/snippet.md

    # Validate a profile
    pype validate profile /path/to/profile.yaml

    # Validate a pipeline
    pype validate pipeline /path/to/pipeline.yaml

Validate Directories
~~~~~~~~~~~~~~~~~~~~

Validate all files in a directory::

    # Validate all snippets in a directory
    pype validate snippet /path/to/snippets/

    # Recursive validation
    pype validate snippet /path/to/snippets/ --recursive

Validate Entire Workspace
~~~~~~~~~~~~~~~~~~~~~~~~~

Validate all modules in a workspace::

    pype validate all --workspace /path/to/pype_modules

Output Formats
~~~~~~~~~~~~~~

Results can be output as text (default) or JSON::

    # Human-readable text output
    pype validate snippet /path/to/snippet.md

    # JSON output (for CI/scripts)
    pype validate snippet /path/to/snippet.md --format json

    # Hide warnings, show only errors
    pype validate snippet /path/to/snippet.md --no-warnings

--------------

What Gets Validated
-------------------

Snippet Validation
~~~~~~~~~~~~~~~~~~

The validator checks:

**Required sections:**

- ``## description`` - Must be present
- ``## requirements`` - Must contain ``ncpu``, ``time``, ``mem``
- ``## results`` - Must have code chunk with ``@interpreter, yaml|json`` header
- ``## arguments`` - Must use valid numbered list format
- ``## snippet`` - Must contain at least one code chunk

**Arguments validation:**

- Sequential numbering (1, 2, 3, ...)
- Valid types: ``str``, ``int``, ``float``, ``bool``
- Valid options: ``help``, ``type``, ``required``, ``default``, ``nargs``, ``action``, ``choices``
- Valid actions: ``store_true``, ``store_false``

**Code chunks:**

- Header format: ``@interpreter, chunk_name [, options]``
- Valid options: ``namespace=``, ``stdout=``, ``stderr=``
- Chunk names must be valid identifiers

**Variables:**

- All ``%(variable)s`` references must be defined
- Arguments use long name only (not short flags)
- Profile variables must exist in referenced profile
- Results variables must match keys from results section

**Cross-references:**

- ``namespace=`` references must match profile programs
- ``profile_*`` variables must match profile files

Profile Validation
~~~~~~~~~~~~~~~~~~

The validator checks:

**Required info fields:**

- ``description`` - Profile description
- ``date`` - Creation or update date

**Files section:**

- All values must be strings (file paths)

**Programs section:**

- Each program requires ``namespace`` and ``version``
- Namespace format must be valid: ``path``, ``env_module@name``, or ``docker@image``

Pipeline Validation
~~~~~~~~~~~~~~~~~~~

The validator checks:

**Required info fields:**

- ``description`` - Pipeline description
- ``api`` - API version (2.0.0 or 2.1.0)

**Steps validation:**

- Valid step types: ``snippet``, ``pipeline``, ``batch_snippet``, ``batch_pipeline``
- ``depends_on`` references must match existing step IDs
- No circular dependencies

--------------

LSP Server
----------

The LSP server provides real-time validation and editor features for Bio_pype files.

Starting the LSP Server
~~~~~~~~~~~~~~~~~~~~~~~

Start the server for editor integration::

    # Start on stdio (standard for most editors)
    pype validate lsp --stdio

    # With debug logging
    pype validate lsp --stdio --log-file /tmp/bio_pype_lsp.log

    # On TCP port (for debugging)
    pype validate lsp --tcp 8080

LSP Features
~~~~~~~~~~~~

The server provides:

**Diagnostics (real-time validation):**

- Errors and warnings shown inline as you type
- Updates on document open, change, and save
- Debounced to avoid excessive validation

**Completions:**

- Variable names: ``%(`` triggers argument/profile/results completions
- Namespaces: ``namespace=`` triggers profile program completions
- Section headers: ``##`` suggests valid section names

**Hover information:**

- Hover over variables to see their source and description
- Hover over namespace references to see program details

--------------

Editor Integration
------------------

Helix
~~~~~

Add to ``~/.config/helix/languages.toml``::

    [[language]]
    name = "markdown"
    language-servers = ["bio-pype-lsp"]
    file-types = ["md"]
    roots = ["snippets", "profiles", "pipelines"]

    [language-server.bio-pype-lsp]
    command = "/path/to/venv/bin/pype"
    args = ["validate", "lsp", "--stdio", "--log-file", "/tmp/bio_pype_lsp.log"]

    [[language]]
    name = "yaml"
    language-servers = ["bio-pype-lsp"]
    file-types = ["yaml", "yml"]
    roots = ["snippets", "profiles", "pipelines"]

Neovim (with nvim-lspconfig)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Add to your Neovim configuration::

    local lspconfig = require('lspconfig')
    local configs = require('lspconfig.configs')

    if not configs.bio_pype_lsp then
      configs.bio_pype_lsp = {
        default_config = {
          cmd = { '/path/to/venv/bin/pype', 'validate', 'lsp', '--stdio' },
          filetypes = { 'markdown', 'yaml' },
          root_dir = lspconfig.util.root_pattern('snippets', 'profiles', 'pipelines'),
          settings = {},
        },
      }
    end

    lspconfig.bio_pype_lsp.setup({})

VS Code
~~~~~~~

Create a VS Code extension or use a generic LSP client extension with::

    {
      "lsp.server": {
        "bio-pype": {
          "command": "/path/to/venv/bin/pype",
          "args": ["validate", "lsp", "--stdio"],
          "filetypes": ["markdown", "yaml"]
        }
      }
    }

--------------

Exit Codes
----------

The validation commands use standard exit codes:

- ``0`` - All files valid (no errors)
- ``1`` - One or more files have errors

This allows integration with CI/CD pipelines::

    # In CI script
    pype validate all --workspace . || exit 1

--------------

Troubleshooting
---------------

LSP Not Working
~~~~~~~~~~~~~~~

1. Check the log file for errors::

    tail -f /tmp/bio_pype_lsp.log

2. Verify the command works standalone::

    pype validate lsp --stdio

3. Ensure the workspace contains valid module directories (snippets/, profiles/, pipelines/)

Validation Not Finding Profile
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The validator searches for profiles in the workspace. You can specify a profile
in snippets using a directive comment::

    # @profile: my_profile_name

    # My Snippet Title

    ## description
    ...

This tells the validator which profile to use for namespace and file validation.

See Also
--------

- :ref:`snippets` - Snippet documentation and syntax
- :ref:`profiles` - Profile documentation and syntax
- :ref:`pipelines` - Pipeline documentation and syntax