File Validation

Validate files and directories in your project

Overview

The files section validates the existence of required files and directories, optionally checking file permissions. This ensures critical project files are present before running your application.

Configuration

Each file check is defined by a FileCheck struct (src/config.rs:40) with the following fields:

path · string · required

The file or directory path to check. Can be absolute or relative to the current directory.

required · boolean · default: "true"

Whether the file or directory must exist. If true, validation fails when the path is not found.

is_directory · boolean · default: "false"

Whether the path should be a directory. If true, validation fails if the path exists but is not a directory.

permissions · number

Unix file permissions in octal format (e.g., 0o755, 0o644). If specified, the file must have exactly these permissions.

Examples

Basic File Check

Check that a file exists:

files:
  - path: .env
    required: true
  - path: package.json
    required: true

Optional Files

Mark files as optional when they’re not always needed:

files:
  - path: .env
    required: false
  - path: .env.local
    required: false

Directory Validation

Check that directories exist:

files:
  - path: src
    required: true
    is_directory: true
  
  - path: node_modules
    required: true
    is_directory: true

Permission Checks

Validate file permissions (useful for scripts and executables):

files:
  - path: scripts/deploy.sh
    required: true
    permissions: 755  # Executable by owner, readable by all
  
  - path: .env
    required: true
    permissions: 600  # Readable/writable by owner only
  
  - path: config.yaml
    required: true
    permissions: 644  # Readable by all, writable by owner

Permissions are specified in octal format. Common values:

• 755: Executable files (rwxr-xr-x)
• 644: Regular files (rw-r—r—)
• 600: Private files (rw-------)
• 700: Private executables (rwx------)

Real-World Examples

Node.js Project

version: "1"

tools:
  - name: node
    version: ">=18.0.0"
    required: true

files:
  - path: .env
    required: true
  - path: package.json
    required: true

Common Use Cases

Configuration Files

files:
  - path: .env
    required: true
    permissions: 600  # Keep secrets private
  
  - path: config/app.yaml
    required: true
  
  - path: docker-compose.yml
    required: false

Project Structure

files:
  # Source directories
  - path: src
    required: true
    is_directory: true
  
  - path: tests
    required: true
    is_directory: true
  
  # Build artifacts
  - path: dist
    required: false
    is_directory: true

Executable Scripts

files:
  - path: scripts/setup.sh
    required: true
    permissions: 755
  
  - path: scripts/deploy.sh
    required: true
    permissions: 755
  
  - path: scripts/test.sh
    required: false
    permissions: 755

Language-Specific Files

Node.js

files:
  - path: package.json
    required: true
  - path: package-lock.json
    required: false
  - path: tsconfig.json
    required: false
  - path: node_modules
    required: false
    is_directory: true

Python

files:
  - path: requirements.txt
    required: true
  - path: setup.py
    required: false
  - path: pyproject.toml
    required: false
  - path: venv
    required: false
    is_directory: true

Rust

files:
  - path: Cargo.toml
    required: true
  - path: Cargo.lock
    required: false
  - path: src
    required: true
    is_directory: true
  - path: target
    required: false
    is_directory: true

Go

files:
  - path: go.mod
    required: true
  - path: go.sum
    required: false
  - path: main.go
    required: false
  - path: vendor
    required: false
    is_directory: true

Path Resolution

Paths can be specified as:

• Relative paths: Resolved from the current working directory

  - path: .env
  - path: src/main.rs
  - path: config/database.yml
  

• Absolute paths: Used as-is

  - path: /etc/myapp/config.yaml
  - path: /var/log/myapp
  

• Home directory: Use ~ for home directory expansion

  - path: ~/.myapp/credentials
  - path: ~/projects/myapp/.env
  

Default Behavior

From the struct definition in src/config.rs:40:

• path: Required field, no default
• required: Defaults to true
• is_directory: Defaults to false
• permissions: Defaults to None (no permission check)

When required: true, validation fails if:

• The file or directory does not exist
• is_directory: true but the path is a file
• is_directory: false (or omitted) but the path is a directory
• permissions is set but the file has different permissions

Combine required: false with permission checks to validate optional files only when they exist, ensuring correct permissions if present.