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
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ comline generation # write generated code for each configured target
|---|---|
| `comline new <name> [--git]` | Scaffold `<name>/` with `config.idp`, `comline.toml`, `src/main.ids` and a `.gitignore`. `--git` also runs `git init`. |
| `comline deps add <name> <dir>` / `comline deps add <name> --git <uri> --commit <sha> --version <v>` | Add a dependency to `config.idp`: resolved first (a git pin is fetched), then written with its content `hash` pinned. `--no-hash` skips the pin. |
| `comline deps pin <name> [--commit <sha> --version <v>]` | Re-pin a dependency's `hash` to the content it has now (after it changed on purpose), resolving it first. With `--commit`/`--version`, moves a git dependency to another commit at the same time. |
| `comline deps list [--json]` | List the declared dependencies: source, pin and what's accepted. Reads only `config.idp`; nothing is fetched or written. |
| `comline deps remove <name> [--dry-run]` | Remove a dependency from `config.idp`; refused, listing each use, while a schema still imports it. |
| `comline check` | Parse, resolve and validate every schema. No `.comline/` writes (beyond fetching git dependencies), 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 generation [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--watch]` | Validate (no freeze), then write generated code. Output location/layout come from `comline.toml` `[generate]`; targets from there or `config.idp`. `gen` is short for `generation`. |
Expand Down
107 changes: 107 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ This is the long-form reference. For a two-minute tour see the
- [Commands](#commands)
- [`new`](#comline-new)
- [`deps add`](#comline-deps-add)
- [`deps pin`](#comline-deps-pin)
- [`deps list`](#comline-deps-list)
- [`deps remove`](#comline-deps-remove)
- [`check`](#comline-check)
- [`inspect`](#comline-inspect)
- [`build`](#comline-build)
Expand Down Expand Up @@ -178,6 +181,110 @@ Exit `0` once added, `1` if the dependency doesn't resolve or can't be added
(the name is already declared, isn't an identifier, or is already one of this
package's own namespaces), `2` if the directory is not a Comline project.

### `comline deps pin`

```
comline deps pin <name> [--commit <sha> --version <version>] [--accept-unverified]
```

Pin a dependency's `hash` to the content it has now. For a dependency that
changed on purpose: `check` and `build` fail on the old pin
(`hash mismatch`) until it's updated. The dependency is resolved first, the way
[`deps add`](#comline-deps-add) resolves it (a git pin is fetched into
`.comline/deps-cache/`, then compiled), so a dependency that doesn't resolve is
never pinned. Only its entry in `config.idp` changes; every other line is left
as written. An entry written without a hash (`deps add --no-hash`) gains one.

The old and new hash are printed. If they're the same, it says so and writes
nothing.

- `--commit <sha> --version <version>` — move a git dependency to another
commit in the same step (both together, git dependencies only).
- `--accept-unverified` — if the new content gives up more through
`@unverified` than the entry already accepts, what it gives up is shown and,
on a terminal, you are asked to accept it; without a terminal this flag
accepts it. The same steps as `deps add`. Nothing is written unless it's
accepted.

```bash
comline deps pin shared_types
comline deps pin net --commit 9b1d3e7 --version 1.3.0
```

```
$ comline --plain deps pin shared_types
Resolving shared_types
Pinned shared_types in config.idp
was: blake3:4b2c2573d7022c99ff9c66922673441b9b4cc36b79e5e6bdfee2251cf3ad10d1
now: blake3:b9684859cabadf2f66d72f47811581ec4fdbd2821816008d3e85bf550f3fae7a
```

Exit `0` once pinned or already pinned, `1` if the dependency isn't declared,
doesn't resolve or can't be written, `2` if it needs accepting and there's no
terminal and no flag, or the directory is not a Comline project.

### `comline deps list`

```
comline deps list [--json]
```

One line per dependency in `config.idp`: its name, where it comes from (a path,
or a git URI at a short commit and its version), what its hash is pinned to
(`unpinned` if there is none), and what `accept_unverified` accepts of it, if
anything.

```
$ comline --plain deps list
billing path ../billing blake3:4b2c2573d702 accepts Billing (schema agreement and encoding agreement)
net git https://github.com/acme/net@9b1d3e7 (1.3.0) blake3:d476bafdea0f
scratch path ../scratch unpinned
```

It only reads `config.idp`: nothing is resolved or fetched, so it never uses
the network, and nothing is written, `.comline/` included. What it shows is what
the file says, not whether the dependency still matches it (that's `check`).

`--json` prints the same as `{ "dependencies": [...] }` on stdout, one object
per dependency with the full values: `name`, `source` (`{ "kind": "path",
"path" }` or `{ "kind": "git", "uri", "commit", "version" }`), `hash` (`null` if
unpinned), and `accept_unverified` (each accepted protocol with its guarantees,
as `config.idp` names them). With none declared the text report is empty and
the JSON's list is `[]`.

Exit `0`, or `2` if the directory is not a Comline project.

### `comline deps remove`

```
comline deps remove <name> [--dry-run]
```

Take `<name>`'s entry out of `config.idp`'s `dependencies` block. Only that
entry goes; every other line is left as written.

If a schema still imports it (`use <name>::...`), it isn't removed: the error
lists each use by file and line, and nothing is written, `--dry-run` or not.

- `--dry-run` — show the entry that would be removed without writing anything.

```bash
comline deps remove shared_types
comline deps remove shared_types --dry-run
```

```
$ comline --plain deps remove shared
error: can't remove `shared`: 1 schema statement still imports it:
src/holder.ids:1 use shared::models::Thing

remove or change those first; config.idp is unchanged
```

A name that isn't declared is an error that lists the ones that are. Exit `0`
once removed, `1` if it's still imported, isn't declared or can't be removed,
`2` if the directory is not a Comline project.

### `comline check`

```
Expand Down
87 changes: 84 additions & 3 deletions src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -365,12 +365,16 @@ pass `--force`.")]

/// Manage the package's dependencies
#[command(long_about = "\
Declare, resolve and accept the other Comline packages this one depends on, \
recorded in `config.idp`'s `dependencies` block.
Declare, resolve, pin, accept, list and remove the other Comline packages this \
one depends on, recorded in `config.idp`'s `dependencies` block. The commands that \
write change only the affected entry; the rest of `config.idp` is left as written.

Examples:
comline deps add shared_types ../shared-types
comline deps accept billing")]
comline deps accept billing
comline deps pin shared_types
comline deps list
comline deps remove shared_types")]
Deps {
#[command(subcommand)]
command: DepsCommand,
Expand Down Expand Up @@ -574,6 +578,83 @@ Examples:
#[arg(long, short)]
yes: bool,
},

/// Re-pin a dependency's `hash` to the content it has now
#[command(long_about = "\
Resolve the dependency the way `add` does (a git pin is fetched into \
`.comline/deps-cache/`, then compiled) and write its `hash` as the content just \
compiled. Use it when a dependency's content changed on purpose: the build \
fails on the old pin until it's updated. A dependency that doesn't resolve is \
never pinned, and an entry written without a hash (`add --no-hash`) gains one. \
The old and new hash are printed; if they're the same, nothing is written.

`--commit` and `--version` (both, git dependencies only) move the dependency \
to another commit in the same step.

If the new content gives up more through `@unverified` than the entry already \
accepts, what it gives up is shown and, on a terminal, you are asked to accept \
it (see `comline deps accept`); otherwise pass `--accept-unverified`. Nothing \
is written unless it's accepted.

Examples:
comline deps pin shared_types
comline deps pin net --commit 9b1d3e7 --version 1.3.0")]
Pin {
/// The dependency to pin
name: String,

/// Move a git dependency to this commit (with `--version`)
#[arg(long, value_name = "SHA", requires = "version")]
commit: Option<String>,

/// Version that commit stands for (with `--commit`)
#[arg(long, value_name = "VERSION", requires = "commit")]
version: Option<String>,

/// Accept what its `@unverified` protocols give up without being asked
#[arg(long)]
accept_unverified: bool,
},

/// List the declared dependencies
#[command(long_about = "\
One line per dependency in `config.idp`: its name, where it comes from (a path, \
or a git URI at a commit and its version), what its hash is pinned to \
(`unpinned` if it isn't) and what `accept_unverified` accepts of it.

It only reads `config.idp`: nothing is resolved or fetched, and nothing is \
written, `.comline/` included. `--json` prints the same as JSON, with every \
commit and hash in full.

Examples:
comline deps list
comline deps list --json")]
List {
/// Print the dependencies as JSON
#[arg(long)]
json: bool,
},

/// Remove a dependency from `config.idp`
#[command(long_about = "\
Take NAME's entry out of `config.idp`'s `dependencies` block. The rest of \
`config.idp` is left as written.

A dependency a schema still imports (`use NAME::...`) isn't removed: the error \
lists each use, by file and line, and nothing is written. Remove or change \
those first.

Examples:
comline deps remove shared_types
comline deps remove shared_types --dry-run")]
Remove {
/// The dependency to remove
name: String,

/// Show what would be removed without writing anything
#[arg(long)]
dry_run: bool,
},
}

/// `comline generation <subcommand>`.
Expand Down
47 changes: 39 additions & 8 deletions src/commands/accept.rs
Original file line number Diff line number Diff line change
Expand Up @@ -217,40 +217,71 @@ pub fn with_acceptance(
));
}

Ok(with_line(manifest, entry_close, &line))
}

/// `manifest` with `line` added as the last line of the entry whose `}` is at
/// `entry_close`, in the indentation of the fields above it; an entry written
/// on one line stays on one line.
pub(crate) fn with_line(manifest: &str, entry_close: usize, line: &str) -> String {
let line_start = manifest[..entry_close].rfind('\n').map_or(0, |i| i + 1);
if manifest[line_start..entry_close].trim().is_empty() {
// `}` on its own line: a new line before it, indented like the fields.
let close_indent = indent_of(manifest, entry_close);
let field_indent = format!("{close_indent}{}", unit(close_indent));
Ok(format!(
// The line above, if it's a field further in than the `}`, sets it.
let above = manifest[..line_start].trim_end_matches('\n');
let above = &above[above.rfind('\n').map_or(0, |i| i + 1)..];
let above_indent = &above[..above.len() - above.trim_start_matches([' ', '\t']).len()];
let field_indent = match above.trim().is_empty() || above_indent.len() <= close_indent.len()
{
true => format!("{close_indent}{}", unit(close_indent)),
false => above_indent.to_string(),
};
format!(
"{}{field_indent}{line}\n{}",
&manifest[..line_start],
&manifest[line_start..]
))
)
} else {
// A one-line entry (`a = { path = "../a" }`): keep it on one line.
Ok(format!(
format!(
"{} {line} {}",
manifest[..entry_close].trim_end(),
&manifest[entry_close..]
))
)
}
}

/// The `{` and `}` of `name = { ... }` directly inside the block.
fn entry(manifest: &str, open: usize, close: usize, name: &str) -> Option<(usize, usize)> {
pub(crate) fn entry(
manifest: &str,
open: usize,
close: usize,
name: &str,
) -> Option<(usize, usize)> {
entry_at(manifest, open, close, name).map(|(_, open, close)| (open, close))
}

/// [`entry`], and where its name starts too.
pub(crate) fn entry_at(
manifest: &str,
open: usize,
close: usize,
name: &str,
) -> Option<(usize, usize, usize)> {
let toks: Vec<_> = tokens(manifest)
.into_iter()
.filter(|&(_, at)| at > open && at < close)
.collect();
let mut depth = 0usize;
for (i, &(token, _)) in toks.iter().enumerate() {
for (i, &(token, at)) in toks.iter().enumerate() {
match token {
Token::Open => depth += 1,
Token::Close => depth = depth.saturating_sub(1),
Token::Word(word) if depth == 0 && word == name => {
if let [(Token::Equals, _), (Token::Open, entry_open), ..] = toks[i + 1..] {
return matching(&toks[i + 2..]).map(|entry_close| (entry_open, entry_close));
return matching(&toks[i + 2..])
.map(|entry_close| (at, entry_open, entry_close));
}
}
_ => {}
Expand Down
23 changes: 22 additions & 1 deletion src/commands/add.rs
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,28 @@ pub(crate) fn declared_dependencies(manifest: &str) -> Result<Vec<DependencyConf
})?;
let declared = DependencyConfig::parse_dependencies(&congregation.assignments)
.map_err(|e| miette::miette!("config.idp: {e}"))?;
Ok(declared.into_values().collect())
// By name: the map has no order of its own.
let mut declared: Vec<_> = declared.into_values().collect();
declared.sort_by(|a, b| a.name.cmp(&b.name));
Ok(declared)
}

/// The declared dependency called `name`, or an error that lists the ones
/// that are declared.
pub(crate) fn declared_named<'a>(
declared: &'a [DependencyConfig],
name: &str,
) -> Result<&'a DependencyConfig> {
declared.iter().find(|d| d.name == name).ok_or_else(|| {
let names: Vec<&str> = declared.iter().map(|d| d.name.as_str()).collect();
miette::miette!(
"`{name}` isn't a dependency in config.idp; {}",
match names.as_slice() {
[] => "it declares none".to_string(),
names => format!("it declares: {}", names.join(", ")),
}
)
})
}

/// The entry's `key = "value"` lines, in the order the docs write them.
Expand Down
Loading
Loading