Haskell Algebraic IR (AIR) prover… Y? Because every project name needs a questionable backronym and we're not shaving it off. Hairy is a re-write of Stwo in Haskell.

This project is built & maintained by AI Agents (shocking!). Idea being that LLMs are pretty bad at writing good Haskell code and maybe there is a process here that allows us to write better Haskell code. Such a process can look like mathematical specification (inspired by another repository) generated by an LLM --> code generated by an LLM --> test generated by an LLM.

• Features
• Project Structure
• Prerequisites
• Installation
  • Setup Guide
  • Using Cabal
  • Using Stack
• Usage
  • Library
  • Executables
• Running Tests
• Development
• Contributing
• License

HAIRY is experimental at best. But it tries to replicated the Stwo repo as best it can. For now, expect some primitive packages only.

This project uses Cabal and is structured as a multi-package monorepo. The main packages are defined in the root cabal.project file:

• core: The primary library containing the core STARK proving logic, located in core/core.cabal.
• examples: Sample executables demonstrating the library, located in core/examples/examples.cabal.
• (Add more packages here as your project evolves)

The cabal.project file orchestrates the build for the entire workspace.

Before you begin, ensure you have the following installed:

• GHC (Glasgow Haskell Compiler) (e.g., version 9.x.x or as specified in your .cabal files)
• Cabal (Haskell build tool) (e.g., version 3.x)
• OR Stack (Haskell build tool) (optional, if you add a stack.yaml)

Clone the repository:

git clone https://github.com/teddyjfpender/hairy.git
cd hairy

To set up the development environment, follow these steps in order:

1. Initial Setup: Run the devcontainer setup script first to check prerequisites and prepare the environment:

   chmod +x devcontainer-setup.sh
   ./devcontainer-setup.sh

   This script will check if you have Docker and VS Code installed, pull the necessary Docker image, and offer to open VS Code with the devcontainer.

2. Container Initialization: When the devcontainer starts, the container-setup.sh script will run automatically to install all dependencies. This may take several minutes. If you need to run this script manually:

   chmod +x container-setup.sh
   ./container-setup.sh

3. Verify Installation: Once the setup is complete, verify that everything is working correctly:

   cabal build all
   cabal test all

After completing these steps, your development environment will be fully set up with all dependencies installed for offline development.

To build the project using Cabal:

cabal update  # Fetches the latest package list from Hackage
cabal build all # Builds all packages in the project
cabal test all # Tests all packages in the project

This will compile all local packages defined in your cabal.project file.

To install executables (if any) from the project:

# Replace <executable-name> with the actual executable name from your .cabal file
cabal install exe:<executable-name> --install-method=copy --overwrite-policy=always

Or, to run an executable directly:

# Replace <executable-name> with the actual executable name
cabal run exe:<executable-name> -- arguments

(Optional: If you set up a stack.yaml for the project)

stack setup   # Downloads the correct GHC version if needed
stack build   # Builds all packages
stack test    # Tests all packages

To run an executable:

# Replace <executable-name> with the actual executable name
stack exec <executable-name> -- arguments

The primary library provided by this project is core. To use it in another Haskell project, add core (or the specific package name you intend to use if it differs) to the build-depends section of your .cabal file.

-- Example of using a function from the 'core' library
import Core.SomeModule (someFunction) -- TODO: Update with actual module and function

main :: IO ()
main = do
  putStrLn "Using the HAIRY library:"
  print (someFunction 42) -- TODO: Update with actual function call

If the HAIRY project provides any command-line executables, describe how to run them here.

# For Cabal (replace <executable-name> with actual name)
cabal run exe:<executable-name> -- --option1 value1 --option2

# For Stack (replace <executable-name> with actual name, if using Stack)
stack exec <executable-name> -- --option1 value1 --option2

To run all test suites in the project:

cabal test all

This command will execute all test suites defined in the .cabal files of your local packages (e.g., m31-tests from the core package).

If you're looking to create some coverage reports then you can run:

cabal test all --enable-coverage

Information for developers:

• Setting up a development environment: Standard cabal build all or stack build should suffice.
• Interactive Development (REPL):

  # For a specific component (e.g., the 'core' library)
  cabal repl lib:core
  # Or for a test suite
  cabal repl test:m31-tests

• Live Reloading (GHCID): Install ghcid (cabal install ghcid or stack install ghcid) then run:

  ghcid --command="cabal repl lib:core" # Or your target component

• Code Formatting: Consider using Ormolu or Fourmolu.

  # Example with Ormolu
  ormolu -i . # Formats files in place

• Linting: HLint is a popular choice.

  hlint .

This project includes a devcontainer configuration for easy development setup. The devcontainer provides a consistent development environment with all necessary tools pre-installed.

To use the devcontainer:

1. Make sure you have Docker and VS Code with the Remote - Containers extension installed.

2. Run the setup script at the root of the repository:

   ./devcontainer-setup.sh

   This script will check prerequisites, pull the required Docker image, and provide options to open the project in VS Code with the devcontainer.

3. Alternatively, you can open the project in VS Code and use the command palette (F1) to select "Remote-Containers: Open Folder in Container..."

The devcontainer includes:

• GHC 9.6.3
• Cabal
• Python 3 with required dependencies
• All the tools needed for development

This project is designed to support offline development once the container is set up. The container-setup.sh script installs all necessary dependencies and development tools during container initialization, including:

• Haskell development tools (hlint, ormolu, ghcid, cabal-fmt, hoogle)
• Python testing and linting tools (pytest, black, flake8, mypy)
• Common Haskell libraries pre-downloaded for offline use
• Full documentation via Hoogle

When working in the devcontainer, you should have everything needed without requiring further internet access.

To manually run the setup script (if needed):

./container-setup.sh

This project uses GitHub Actions for continuous integration. The CI workflow:

• Runs on every push to main/master branches and on pull requests
• Sets up the Haskell environment with GHC 9.6.3
• Installs Python dependencies
• Builds and tests all packages
• Uses caching to speed up builds

You can see the build status in the badge at the top of this README.

Contributions are welcome! Please follow these general steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature-name).
3. Make your changes.
4. Ensure tests pass (cabal test all or stack test).
5. Add tests for new features or bug fixes.
6. Format and lint your code.
7. Commit your changes (git commit -am 'Add some feature').
8. Push to the branch (git push origin feature/your-feature-name).
9. Create a new Pull Request.

Please make sure to update tests and documentation as appropriate.

This project is licensed under the MIT License. You should create a LICENSE file in the root of your project with the full text of the MIT license, or your chosen license.