Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,17 @@ jobs:
run: cargo build --verbose
- name: Run tests
run: cargo test --verbose

lint:
name: Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy
- name: rustfmt
run: cargo fmt --check
- name: clippy
run: cargo clippy --all-targets -- -D warnings
26 changes: 22 additions & 4 deletions Cargo.toml
100755 → 100644
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,35 @@ name = "comline"
version = "0.1.0"
edition = "2021"
license-file = "LICENSE"
repository = "https://github.com/ComlineProject/comline"
description = "A project in the works, patiently"
repository = "https://github.com/ComlineProject/cli"
description = "Command-line interface for Comline: build, validate, diff and generate code from Comline schemas"
readme = "README.md"
keywords = ["comline", "schema", "codegen", "idl", "cli"]
categories = ["command-line-utilities", "development-tools"]


[dependencies]
clap = { version = "4.5.4", features = ["derive", "cargo"] }
clap_complete = "4.5"
miette = { version = "7.2.0", features = ["fancy"] }
tokio = { version = "1.37.0", features = ["full"] }
thiserror = "1.0"
anstream = "0.6"
anstyle = "1.0"
indicatif = "0.17"
notify-debouncer-mini = "0.4"
tracing = "0.1.40"
tracing-subscriber = { version = "0.3.18", features = ["env-filter", "fmt"] }
comline-core = { git = "https://github.com/ComlineProject/core" }
# NOTE: consumed via git until `comline-core` is published to crates.io.
# Publishing `comline` to crates.io is blocked on that release.
comline-core = { git = "https://github.com/ComlineProject/core", rev = "3455622e111c68a2ac0efeec9abfe7092a479fd4" }

[target.'cfg(unix)'.dependencies]
libc = "0.2"

[build-dependencies]
clap = { version = "4.5.4", features = ["derive"] }
clap_mangen = "0.2"
clap_complete = "4.5"

[dev-dependencies]
assert_cmd = "2.0"
Expand Down
79 changes: 76 additions & 3 deletions README.md
100755 → 100644
Original file line number Diff line number Diff line change
@@ -1,3 +1,76 @@
# Comline
For the time being the project is in initial development and likely won't have
user-friendly tips or instructions.
# comline

The command-line interface for [Comline](https://github.com/ComlineProject) —
build, validate, diff and generate code from Comline schemas.

> Comline is in early development. The schema language and CLI surface may still
> change between versions.

## Install

`comline` is not on crates.io yet (it depends on `comline-core` via git until
that crate is published). Build it from this repository:

```bash
git clone https://github.com/ComlineProject/cli
cargo install --path cli
```

## Quick start

```bash
comline new my-api # scaffold a project
cd my-api
comline build # compile + freeze version 0.0.1
comline generate # write generated code for each configured target
```

## Commands

| Command | What it does |
|---|---|
| `comline new <name> [--git]` | Scaffold `<name>/` with `config.idp`, `src/main.ids` and a `.gitignore`. `--git` also runs `git init`. |
| `comline check` | Parse, resolve and validate every schema. No `.comline/` writes, no version bump — safe for editors, hooks and CI. |
| `comline build [--release] [--watch]` | Compile, validate, and freeze a new immutable version into `.comline/`. Prints the changelog and the version bump. |
| `comline generate [--target <lang>] [--watch]` | Build, then run each configured code generator (or just `<lang>`). |
| `comline diff <old> <new>` | Show the schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash, or `HEAD` (the default for `<new>`). |
| `comline clean [--dry-run]` | Remove `.comline/` and generated files. |
| `comline completions <shell>` | Print a shell completion script to stdout. |

Global flags: `--path <dir>` to run outside the current directory, `-v`/`-vv` for
more log detail, `-q`/`--quiet` to silence everything but errors.

See [`docs/cli.md`](docs/cli.md) for the full guide — every command and flag, the
versioning model, output and exit codes, watch mode, and packaging.

## Versioning model

Comline stores every build as an immutable commit in an append-only chain under
`.comline/` (content-addressable, git-inspired). Each `build` compares the new
schemas against the previous version and bumps automatically:

- **major** — a breaking change (removed/retyped field, removed variant, …)
- **minor** — a new feature (added struct/enum/variant/field, …)
- **patch** — a modification (field made optional, docstring change, …)

`comline diff` runs that same comparison between any two stored versions on
demand.

## Exit codes

| code | meaning |
|---|---|
| `0` | success |
| `1` | the command ran but failed |
| `2` | a precondition was not met (not a Comline project, nothing built yet) or a usage error |

## Development

```bash
cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings
```

Man pages and completion scripts for all shells are generated into `OUT_DIR`
(`target/.../build/comline-*/out/{man,completions}/`) on every build.
66 changes: 66 additions & 0 deletions build.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
//! Generates man pages and shell completions into `OUT_DIR` at build time so
//! packagers can install them. End users can also get completions at runtime via
//! `comline completions <shell>`.
//!
//! `src/cli.rs` is intentionally dependency-light so it can be shared here.

use std::env;
use std::fs;
use std::io::Error;
use std::path::{Path, PathBuf};

use clap::{Command, CommandFactory};
use clap_complete::Shell;

#[path = "src/cli.rs"]
mod cli;

fn main() -> Result<(), Error> {
println!("cargo:rerun-if-changed=src/cli.rs");
println!("cargo:rerun-if-changed=build.rs");

let Some(out_dir) = env::var_os("OUT_DIR").map(PathBuf::from) else {
return Ok(());
};

let man_dir = out_dir.join("man");
fs::create_dir_all(&man_dir)?;
render_man_pages(&man_dir, &cli::Cli::command())?;

let completions_dir = out_dir.join("completions");
fs::create_dir_all(&completions_dir)?;
let mut command = cli::Cli::command();
for shell in [
Shell::Bash,
Shell::Zsh,
Shell::Fish,
Shell::PowerShell,
Shell::Elvish,
] {
clap_complete::generate_to(shell, &mut command, "comline", &completions_dir)?;
}

Ok(())
}

fn render_man_pages(dir: &Path, command: &Command) -> Result<(), Error> {
let name = command.get_name().to_string();
write_man(&dir.join(format!("{name}.1")), command.clone(), &name)?;

for sub in command.get_subcommands() {
if sub.get_name() == "help" {
continue;
}
let page = format!("{name}-{}", sub.get_name());
write_man(&dir.join(format!("{page}.1")), sub.clone(), &page)?;
}
Ok(())
}

fn write_man(path: &Path, command: Command, title: &str) -> Result<(), Error> {
let mut buffer = Vec::new();
clap_mangen::Man::new(command)
.title(title.to_uppercase())
.render(&mut buffer)?;
fs::write(path, buffer)
}
Loading
Loading