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

• Snippets - Snippet documentation and syntax

• Profiles - Profile documentation and syntax

• Pipelines - Pipeline documentation and syntax