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
18 changes: 18 additions & 0 deletions docs/docs/proposals/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,24 @@ Seven parts, read in order: [the formats](ir-migrations/formats.md),
[format 4 as the first client](ir-migrations/format-4.md). *accepted 2026-11-13; tracked in
[core#268](https://github.com/ComlineProject/core/issues/268).*

#### [Own schemas, provenance and dependency groups](use-paths-and-groups/index.md)

How a `use` path says where a schema comes from, and how a package's dependencies
are organised. A package's own schemas are reached only through `package::`,
`parent::` or `self::` (a warning with a quick fix now, an error in the next
edition), so an absolute first segment always means `std` or a dependency; each
compiled schema records its provenance (the package, a named dependency, or
`std`) instead of tools inferring it from the namespace's spelling, which is an
IR format change; dependencies take an optional `group` that is presentation
only and moves no hash; and a file's imports have a default order (`std`, the
package's own, dependencies by group) configurable in a `[format]` table. Four
parts: [relative paths](use-paths-and-groups/relative-use.md),
[provenance](use-paths-and-groups/provenance.md),
[dependency groups](use-paths-and-groups/dependency-groups.md) and
[import formatting](use-paths-and-groups/import-formatting.md). *draft; related
to [core#277](https://github.com/ComlineProject/core/issues/277) and
[core#268](https://github.com/ComlineProject/core/issues/268).*

### Connections

- [Connections](connections.md): what a connection carries beyond one client
Expand Down
96 changes: 96 additions & 0 deletions docs/docs/proposals/use-paths-and-groups/dependency-groups.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Dependency groups

Status: **draft** · decided with the user 2026-11-15 · part of [Own schemas, provenance and dependency
groups](index.md)

**The question.** `dependencies` in `config.idp` is a flat table, and a package with a dozen of them has no way to say
which belong together. **Can a package organise its dependencies, for the people reading the manifest and the imports,
without changing what a dependency is called, what a `use` looks like, or any hash?**

## What it looks like

**Decided.** An optional `group` field on each dependency entry:

```idp
dependencies = {
logging = {
path = "../platform/logging"
group = "platform"
}

metrics = {
path = "../platform/metrics"
group = "platform"
}

shared_types = {
path = "../shared-types"
group = "team"
}

net = {
version = "1.2.0"
uri = "https://github.com/acme/net"
commit = "4f2c9e1"
hash = "blake3:…"
}
}
```

- **The table stays flat.** Every dependency is still `dependencies.<name>`, and dependency names stay unique across
the whole table, groups or not.
- **A group is a label.** A string, written on the entries that share it. An entry with no `group` is ungrouped, and
there is no group to declare first.
- **Groups never appear in a `use` path.** The imports are `use logging::…` and `use shared_types::…`, exactly as they
would be without groups. A group name is not a namespace, can equal any name or none, and isn't reserved.

## Presentation only

A group changes how dependencies are shown and ordered, and nothing else. It is **excluded** from:

- the **frozen config's hash**,
- a **dependency pin** (the content hash of `comline-dep-content-v2`, which covers a dependency's schemas and its
frozen config),
- **compat and config diffs**: moving a dependency to another group, adding a group, or removing one, is no change, and
has no bump.

So regrouping changes no hash and no history. The simplest way to hold that, and the one that can't drift, is that the
group isn't frozen at all: it is read from the manifest's source by the tools that present dependencies (the CLI and the
language server), the way a comment is. A dependency's own `group`s, in its own `config.idp`, don't reach the consumer
either: the pin already leaves a dependency's `Dependency` units out (`covered_by_pin`), and a test says a regrouped
dependency has the same pin.

Tests that carry this, in core and in the specification's cases: the same package regrouped has the same config hash,
the same pin, the same comparison with its previous version, and is no change to its changelog.

## Order

Groups are ordered by **first declaration**: the order of each group's first entry in the table as written, and not
alphabetically. That means the manifest is read in source order. Core's dependency parse is a map that is sorted to
freeze deterministically, so the order is taken from the syntax tree, not from it.

The formatter uses this to order a file's imports ([import formatting](import-formatting.md)); `comline deps list`
shows dependencies grouped in the same order.

## Commands

**Decided.** `comline deps add` and `comline deps pin` take `--group`:

```bash
comline deps add logging ../platform/logging --group platform
comline deps pin logging --group platform
```

`add` writes the field with the entry it adds, and `pin` sets or changes it on an existing entry, leaving the rest of
`config.idp` as written, as they do for `hash`.

## Alternatives rejected

- **Nested group tables**, `dependencies = { platform = { logging = { ... } } }`. A dependency's entry is itself a
table, with keys of its own (`path`, `version`, `uri`, `commit`, `hash`): `platform = { path = "..." }` could be a
group holding a dependency called `path`, or a dependency. The reader and the parser would have to guess, and
naming a dependency `path` or `hash` would change what the manifest means. Nesting also makes a dependency's address
depend on its group, which the next point rules out.
- **A separate `dependency_groups` list**, `dependency_groups = { platform = ["logging", "metrics"] }`. It names every
dependency twice, and the two can disagree (a name in a group that isn't a dependency, a dependency in two groups).
The user preferred the field: a dependency says what it belongs to where it is written.
97 changes: 97 additions & 0 deletions docs/docs/proposals/use-paths-and-groups/import-formatting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Import formatting

Status: **draft** · decided with the user 2026-11-15, where the configuration lives open · part of [Own schemas,
provenance and dependency groups](index.md)

**The question.** A file's `use` lines have no set order, so each author orders them their own way, and a diff mixes
real changes with reordering. Now that a path says where a schema comes from
([relative paths](relative-use.md)) and dependencies can have [groups](dependency-groups.md), **what order is the
default, and can a project change it?**

## The default order

**Decided.** The language server's formatter, and any `comline fmt`, put a file's imports in tiers:

1. **`std`**: `use std::…`
2. **the package's own**: `use package::…`, `use parent::…`, `use self::…`
3. **dependencies**: every other `use`

Within the dependencies tier, **groups come in first-declared order** (the order of each group's first entry in
`config.idp`, see [Dependency groups](dependency-groups.md#order)), **then ungrouped dependencies**. Within a tier
(and within a group), imports are **alphabetical** by path.

```ids
use std::http::Request
use std::validators::{NonEmpty, MinChars}

use package::types::{Customer, Order}
use parent::common::Error

use logging::Logger
use metrics::Counter

use shared_types::foo::X

use net::Client
```

Here `logging` and `metrics` are in the group `platform`, declared first; `shared_types` is in `team`; `net` has no
group. A blank line separates tiers, and separates groups inside the dependencies tier, the way the example shows.

Whether a group can also order `std`, so that, say, a group sorts before it or between the tiers, is
[an open question](index.md#open-questions); today a group orders dependencies among themselves only.

The formatter doesn't change what an import means: it only reorders `use` statements.

## Configuring it

**Decided.** The order is configurable in a `[format]` table:

```toml
[format]
imports.order = ["std", "package", "dependencies"]
```

`imports.order` lists the tiers, each once, in the order they are written: `std`, `package` (the package's own) and
`dependencies`. The default is the order above. Putting `dependencies` first is
`["dependencies", "std", "package"]`. The list is read strictly (a proposed detail): a tier left out, repeated or misspelt is
an error, so a typo doesn't quietly reorder every file.

### Where the configuration lives

**Recommendation, to be confirmed: [`comline.toml`](../../reference/package/comline-toml.md), not `config.idp`.**

- `config.idp` is **frozen into every build and hashed**. It holds what a package *is*: its identity, what it
depends on, how it is put on the wire. An import order is how a file is *written*; putting it there would make
reordering a style setting a change to the frozen config, to every hash that covers it, and potentially to the
package's history. The same reasoning kept groups out of every hash.
- `comline.toml` is **tooling configuration**: consumer-owned, committed, never frozen and never part of a published
package, and it already holds the tools' tables (`[generate]`, `[doc]`). `[format]` is another.
- Nothing downstream has to read it: a dependency's formatting is its authors' business, and a package's consumers
never see it.

The alternative, a `format` key in `config.idp`, would be read by the same tools and would travel with a published
package. It is the user's to decide; this page is written as if `comline.toml` is chosen, and the cost of the other is a
change to where the table is read from.

### Precedence

**Decided:** the project's `comline.toml`, then the defaults. Each is applied key by key, like
[`[generate]`](../../reference/package/comline-toml.md#precedence).

**Open:** whether a per-user configuration, outside the project, can override the project's. The case for it: an
author who reads imports in another order and doesn't want to change everyone's. The case against: a formatter's point
is that every author's editor produces the same file, and a per-user override means a save in one editor makes a diff
in the next. If it exists, it is the highest in the chain: defaults, the project's `[format]`, the user's.

## Who reads it

- **The language server's formatter**, in the editor, on a format request. It reads `[format]` from the `comline.toml`
beside the package, with or without the `#:schema` line, as it already checks the file.
- **Any `comline fmt`.** There is no such command today; if one is added, it reads the same table with the same
function. The ordering lives in core, over the parsed `use` statements, so the two can't disagree, and a conformance
case in the specification repository (a schema, a configuration, and the text it must format to) holds every
implementation to it.

`comline.toml` gains the table in its [reference](../../reference/package/comline-toml.md) and in the JSON Schema served
for it, so an editor completes `imports.order` and checks its values.
Loading
Loading