Monobase

Monobase is a convention for organizing single-file codebases with structured section markers, and a CLI tool (mono) that provides the navigational benefits of a multi-file project — modularity, dependency tracking, function-level indexing, searchability — while keeping each language in a single file.

A Monobase project is one file per language: project.rs, project.html, project.sql. Each file uses its language's native comment syntax to embed section markers. The mono tool parses those markers and gives you sliced views of exactly the code you need. No custom file format. No build step. Your files compile directly with standard toolchains.

*Note: this is more of an experiment rather than an actually practical way to organize codebases.

Quick Start

# Build
cargo build --release

# Create a new monobase project
mono init my_project.rs --name my_project --description "My project"

# View the table of contents
mono toc my_project.rs

# Show a specific section
mono show my_project.rs --section main

# View a section with its dependency context
mono context my_project.rs --section main

# Search across sections
mono search my_project.rs "fn handle"

# Validate structure and references
mono validate my_project.rs

# Edit a section in your $EDITOR
mono edit my_project.rs --section main

What It Looks Like

A monobase-annotated Rust file:

//# mono 0.1
//# name: minigrep
//# lang: rust
//# description: A minimal grep-like tool.

//#[imports]
//# type: config
//# brief: Crate-level imports.

use std::env;
use std::fs;

//#[search]
//# type: function
//# tags: core
//# uses: types
//# brief: Case-sensitive line search.

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    contents.lines()
        .filter(|line| line.contains(query))
        .collect()
}

//#[main]
//# type: function
//# uses: search
//# brief: Program entrypoint.

fn main() {
    // ...
}

This file compiles directly with rustc minigrep.rs. The //# ... comments are invisible to the compiler. The mono tool reads them to provide navigation and analysis.

Documentation

• Annotation Format — How to write section markers and metadata
• CLI Usage — Complete reference for all commands and flags
• Conventions — Recommended practices for structuring monobase files
• Architecture — How the code works, for contributors

How It Works

Sections replace directories. Each section is a named, typed, tagged unit of code with declared dependencies. The tool parses function signatures and call sites to build a dependency graph, then uses that graph to show you focused views of the code you care about.

The context command is the core workflow — it shows a section's code with call sites annotated inline, plus the signatures (or full bodies) of everything it depends on. Instead of jumping between files, you see the relevant code in one view.

The edit command extracts a section into a temp file, opens your editor, and writes changes back atomically. You edit clean code without scrolling through thousands of lines.

Building

cargo build --release

The binary is at target/release/mono. Copy it to your $PATH.

Requires Rust 1.70+.