From f6d42b6bdcf2002bd0a8b849a040cda94b2fe8fd Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 15 Nov 2026 04:54:01 +0800 Subject: [PATCH] proposals: relative-only use for own schemas, provenance, dependency groups, import formatting (draft) Four pages under proposals/use-paths-and-groups: own schemas reached only through package::, parent:: and self:: (by edition), provenance recorded per compiled schema instead of inferred from namespaces (an IR format change), an optional group field on dependency entries that is presentation only, and a default import order configurable in a [format] table. Related to core#277 and core#268. --- docs/docs/proposals/index.md | 18 +++ .../use-paths-and-groups/dependency-groups.md | 96 ++++++++++++ .../use-paths-and-groups/import-formatting.md | 97 ++++++++++++ .../proposals/use-paths-and-groups/index.md | 147 ++++++++++++++++++ .../use-paths-and-groups/provenance.md | 93 +++++++++++ .../use-paths-and-groups/relative-use.md | 102 ++++++++++++ docs/mkdocs.yml | 6 + 7 files changed, 559 insertions(+) create mode 100644 docs/docs/proposals/use-paths-and-groups/dependency-groups.md create mode 100644 docs/docs/proposals/use-paths-and-groups/import-formatting.md create mode 100644 docs/docs/proposals/use-paths-and-groups/index.md create mode 100644 docs/docs/proposals/use-paths-and-groups/provenance.md create mode 100644 docs/docs/proposals/use-paths-and-groups/relative-use.md diff --git a/docs/docs/proposals/index.md b/docs/docs/proposals/index.md index c807376..bd771b8 100755 --- a/docs/docs/proposals/index.md +++ b/docs/docs/proposals/index.md @@ -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 diff --git a/docs/docs/proposals/use-paths-and-groups/dependency-groups.md b/docs/docs/proposals/use-paths-and-groups/dependency-groups.md new file mode 100644 index 0000000..3c00a77 --- /dev/null +++ b/docs/docs/proposals/use-paths-and-groups/dependency-groups.md @@ -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.`, 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. diff --git a/docs/docs/proposals/use-paths-and-groups/import-formatting.md b/docs/docs/proposals/use-paths-and-groups/import-formatting.md new file mode 100644 index 0000000..f5c0135 --- /dev/null +++ b/docs/docs/proposals/use-paths-and-groups/import-formatting.md @@ -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. diff --git a/docs/docs/proposals/use-paths-and-groups/index.md b/docs/docs/proposals/use-paths-and-groups/index.md new file mode 100644 index 0000000..28d101b --- /dev/null +++ b/docs/docs/proposals/use-paths-and-groups/index.md @@ -0,0 +1,147 @@ +# Own schemas, provenance and dependency groups + +Status: **draft** · written 2026-11-15 · related: +[core#277](https://github.com/ComlineProject/core/issues/277) (a dependency's protocols on a connection: reach and +numbers recorded in the facts) and [core#268](https://github.com/ComlineProject/core/issues/268) (IR migrations, which +a change to the frozen IR has to go through) · builds on +[A dependency's protocols on a connection](../dependency-protocols/index.md) and +[Migrating stored IR](../ir-migrations/index.md) · four parts: +[relative paths for a package's own schemas](relative-use.md), [provenance](provenance.md), +[dependency groups](dependency-groups.md) and [import formatting](import-formatting.md) + +**The question.** A `use` path starts with a word. Today that word can be a schema of the package itself, a +dependency, or `std`, and nothing in the path says which: core and generation tell them apart by how the namespace is +spelled. **Can the language and the tools stop guessing, so that the first segment of a path always names where a schema +comes from, every compiled schema records where it came from, and the dependencies a package has can be organised +and imported in a consistent order?** + +## Where things stand + +- **A package's own schemas are reached by a bare path.** For `src/types.ids`, a schema writes `use types::User`. The + same first-segment slot holds a dependency (`use shared_types::foo::X`) and `std` (`use std::http::Request`). Core's + `ImportResolver` takes `self`, `parent` and `package` first, then `std`, then a name that matches a dependency, and + anything left is "from the same package". +- **Classification is by spelling, in three places.** A compiled schema is a dependency's when its namespace's first + segment is a dependency's name or `std`. Core's version history splits a stored version that way + (`compat::dependency_names`, `Loaded::of`, and the same split in the build's comparison), and generation mirrors it + (`connections::is_dependency`, [generation#146](https://github.com/ComlineProject/generation/pull/146)). +- **A guard keeps the spelling honest.** A package's own schema whose namespace starts with a dependency's name, or with + `std`, is a build error ("is named like the dependency 'greeting'", `reject_shadowing_namespaces`, + [#256](https://github.com/ComlineProject/core/pull/256)): were it allowed, its imports wouldn't be checked and its + protocols would be filed under the dependency's name. The error is the containment; the rule beneath it is still by + name, and it makes a perfectly good file name unusable. +- **Dependencies are a flat table.** `dependencies = { name = { ... } }` in `config.idp`, as long as the package needs. + Nothing says that three of them are the platform's, and two are the team's. + +## What this proposes + +1. **[Own schemas only through relative paths](relative-use.md).** Within a package, its own schemas are reached as + `package::…`, `parent::…` or `self::…`. An absolute first segment always means `std` or a dependency. Introduced + by a language edition: a warning with a quick fix now, an error in the next edition. +2. **[Provenance, not names](provenance.md).** Each compiled schema records the package it came from: the package + itself, a named dependency, or `std`. The frozen IR, the generation request and the facts carry it, so nothing infers + "dependency" from a namespace's spelling. This is a frozen IR change, so it goes through the + [IR migrations](../ir-migrations/index.md) framework. +3. **[Dependency groups](dependency-groups.md).** An optional `group = ""` on a dependency's entry. The table + stays flat, names stay unique, and a group never appears in a `use` path. It is presentation only, and no hash or + history moves when it changes. +4. **[Import formatting](import-formatting.md).** A default order for a file's `use` lines (`std`, the package's own, + then dependencies by group), configurable in a `[format]` table, read by the language server's formatter and + any `comline fmt`. + +The first two are about what a path and a compiled schema mean, and are needed together: the first makes the author's +side unambiguous, the second stops the tools depending on the author never having made a collision. The last two are +about how a package's dependencies are presented, and ride on the first only in that the order puts the package's own +imports in a tier of their own. + +## Decided + +Settled with the user while drafting (2026-11-15), and written into the pages as decided: + +| | Decision | +|---|---| +| Own schemas | reached only as `package::…`, `parent::…` or `self::…`; an absolute first segment is `std` or a dependency | +| The word for one level up | `parent`, as it is; no `super` synonym | +| Rollout | a language edition: a warning with a language-server quick fix (rewriting to `package::…`) in the current edition, an error in the next | +| Reserved dependency names | `std`, `package`, `parent`, `self` | +| Provenance | recorded per compiled schema (the package, a named dependency, or `std`) in the frozen IR, the generation request and the facts; one canonical namespace form in requests and facts | +| IR format | a bump under the IR migrations framework | +| Groups | an optional `group = ""` field on each dependency entry; the table stays flat and names unique; never in a `use` path | +| Rejected group shapes | nested group tables, and a separate `dependency_groups` list | +| Groups and hashes | excluded from the frozen config's hash, from dependency pins and from compat and config diffs | +| CLI | `comline deps add` and `comline deps pin` take `--group` | +| Import order | `std`, then the package's own, then dependencies: groups in first-declared order, then ungrouped dependencies; alphabetical within a tier | +| Configuration | a `[format]` table, for example `imports.order = ["std", "package", "dependencies"]`; the project's configuration, then the defaults; read by the language server's formatter and any `comline fmt` | + +## Open questions + +1. **Provenance's IR format.** Does provenance ride with format 4 (the first migration step, the + [granular `@unverified`](../shared-vocabulary/granular-unverified.md) chains of + [core#222](https://github.com/ComlineProject/core/issues/222)), or come right after it as format 5? See + [the IR format](provenance.md#which-format). +2. **Where `[format]` lives.** The recommendation is `comline.toml`, the tooling configuration, and not `config.idp`, + which is frozen into every build and hashed. Left open for the user to confirm. See + [where it lives](import-formatting.md#where-the-configuration-lives). +3. **A per-user override.** Whether a per-user configuration (outside the project) can override the project's + `[format]`, or the project's is always what formats. See + [precedence](import-formatting.md#precedence). +4. **Groups and `std`.** Whether a group can also order `std`: today a group orders dependencies among themselves + only, and `std` is a tier of its own. See [how groups are ordered](import-formatting.md#the-default-order). +5. **The edition for the error.** Which edition makes a bare path to a package's own schema an error: the next one, + 2, which [dependency protocols](../dependency-protocols/index.md) also proposes for its new defaults, or a + later one. See [the rollout of the rule](relative-use.md#rollout-by-edition). +6. **Equal namespaces after provenance** (raised while drafting; not one of the questions settled with the user). Once + provenance tells a package's schema from a dependency's, the guard on a package's own schema named like a + dependency has nothing left to protect, but two schemas can still have the same compiled namespace (an own + `greeting/hello.ids` and the dependency's `hello`, as `greeting::hello`) and write the same generated file. Does the + guard stay, narrowed to equal namespaces, or do a dependency's schemas get their own output prefix? See + [what the guard becomes](provenance.md#what-the-guard-becomes). + +## Rollout + +Staged so that each step ships and is useful alone. Nothing here is a tracking issue: the checklist is for whoever +turns the accepted proposal into issues. + +1. **specification: conformance cases first.** New compiler cases in `compiler/src`, regenerated into `compiler/cases` + by `specs/check.sh`, so every implementation reproduces them: a bare path to a package's own schema (the + warning in the current edition, the error in the next, the `package::` form clean); a package with a dependency and + an own schema of the same first word; reserved dependency names; a `group` on an entry, and the same package regrouped + (the same outcome). A new kind of case for formatting: a schema's text, the configuration, and the text the + formatter must produce, for the default order, a custom `imports.order`, and groups. New catalog entries for the + diagnostic codes, per the [shared vocabulary](../shared-vocabulary/index.md). +2. **core: the rule.** The resolver reads an absolute first segment as `std` or a dependency only; a bare path that + would have reached the package's own schema is the deprecation warning, with the fix attached, in the current + edition, and the error in the edition chosen above; `comline fix` applies it. The reserved names stay as they are + (`reserved_dependency_name` already refuses `std`, `package`, `parent` and `self`). +3. **core: provenance and the IR format.** Each compiled schema records its provenance; the frozen types, the + migration step and its fixtures, and the format document, in one pull request as the + [format gate](../ir-migrations/proof.md#the-gate) requires. `compat::dependency_names`, `Loaded::of` and the split in + the build's comparison read it instead of the namespace. +4. **core: groups.** The `group` key on a dependency entry, parsed in source order, kept out of every hash and diff, + with tests that regrouping changes no hash, pin or comparison. The ordering function for imports, in core, so the + tools that format agree. +5. **generation.** The request carries each schema's provenance and one canonical namespace form; + `connections::is_dependency` and `reached` read provenance. The `dependencies` list on the request stays, additive, + until the generators read provenance, then goes. +6. **CLI.** `comline deps add --group` and `comline deps pin --group`; `deps list` shows groups; `comline fix` applies + the rewrite; `comline fmt`, if and when it exists, reads `[format]`. +7. **language server.** The deprecation warning with its quick fix to `package::…`; the formatter's import order; + `[format]` read from `comline.toml`; completion and hover for `group`. +8. **docs.** The [Imports](../../guides/idl/use.md) guide (own schemas, the relative forms, what an absolute path + means), [Packages & dependencies](../../guides/packages/index.md#dependencies) (groups, `--group`), the + [`config.idp`](../../reference/package/idp.md) and [`comline.toml`](../../reference/package/comline-toml.md) + references (`group`, `[format]`, and the JSON Schema `scripts/sync-comline-toml-schema.py` writes), + [Editions](../../reference/versioning.md#editions), the [CLI reference](../../reference/tools/cli/index.md), and this + proposal marked accepted. + +## Related + +- [core#277](https://github.com/ComlineProject/core/issues/277): reach, recorded in the facts. A dependency's protocol + is reached by a `use`, and which package a protocol belongs to is exactly what provenance records. +- [core#268](https://github.com/ComlineProject/core/issues/268): IR migrations, the framework the provenance change + goes through. +- [core#245](https://github.com/ComlineProject/core/issues/245) (closed): a dependency's `use` of its own sibling + schema resolved to the consumer's schema of the same name. The same family of bug, from a bare path meaning + different things depending on who reads it. +- [generation#146](https://github.com/ComlineProject/generation/pull/146): the request's `dependencies` list and + `is_dependency`, which provenance replaces. diff --git a/docs/docs/proposals/use-paths-and-groups/provenance.md b/docs/docs/proposals/use-paths-and-groups/provenance.md new file mode 100644 index 0000000..9bcdfbc --- /dev/null +++ b/docs/docs/proposals/use-paths-and-groups/provenance.md @@ -0,0 +1,93 @@ +# Provenance, not names + +Status: **draft** · decided with the user 2026-11-15, the IR format open · part of [Own schemas, provenance and +dependency groups](index.md) · needs an IR format bump under [core#268](https://github.com/ComlineProject/core/issues/268) + +**The question.** Whether a compiled schema is the package's own, a dependency's or `std`'s decides what is done with +its protocols: whether they get wire numbers, whether they are on the package's connection, whether a comparison goes +by what they declare or by what the package reaches. **Can that be a recorded fact instead of something every tool +infers from how a namespace is spelled?** + +## Where things stand + +A dependency's schemas are compiled in their own package and brought in as they were frozen, with their namespace +prefixed by the name the consumer gave the dependency (`package::deps::resolve`: `shared_types`'s `src/foo.ids` is +`shared_types::foo`). `std`'s schemas sit under `std`. Nothing else says where a schema came from. So: + +| Who | How it tells a dependency's schema from the package's | +|---|---| +| core, the stored version history | the first segment of the namespace is in `compat::dependency_names`: the `dep_` entries of the version's tree (`compat::vendored`), plus `std`. `Loaded::of` and the build's comparison each do this split | +| core, `inspect` and `doc` | by the stored `dependency_configs` | +| generation | `connections::is_dependency`: `std`, or a namespace whose first segment is one of `GenerateRequest::dependencies`, mirrored from core because `compat` is behind a feature the codegen crate doesn't enable | +| core's shadowing guard | refuses a package's own schema named like a dependency or `std` | + +The same rule written three times, and each can only be right while no schema of the package is spelled like a +dependency's. + +There is a second, plainer disagreement. Core's compiled namespaces are `::`-joined (`localdeps::greeting`); a +generation request's are `/`-joined (`localdeps/greeting`). A comparison of the two forms failed for nested schemas, and +was fixed separately. That the fix had to be made is part of the case here: two forms of one name, compared as text. + +## The change + +**Decided.** Each compiled schema **records the package it came from**: one of + +- the package itself, +- a named dependency (the name the package gives it), or +- `std`. + +The record is carried in: + +- **the frozen IR**, with the schema, so a stored version says it, and a version history read years later doesn't depend + on the spelling rules of the core that reads it; +- **the generation request**, with each schema, replacing the list of dependency names the request carries today + ([generation#146](https://github.com/ComlineProject/generation/pull/146)): `is_dependency` and `reached` read it; +- **the facts**, per protocol, so that [reach and per-package numbers](https://github.com/ComlineProject/core/issues/277) + are recorded against the package a protocol belongs to and not against a name. + +Nothing infers "dependency" from a namespace's spelling any more. `compat::dependency_names` and `compat::vendored` +stop being a classifier: the `dep_` entries remain how a version *stores* what it vendored, and nothing else. + +A dependency's schemas keep their namespace prefix: it is how `use greeting::hello::X` reads and how the generated +files are laid out. What changes is that the prefix no longer decides anything. + +### One canonical namespace + +A namespace is compared as its segments, never as two strings joined differently, and requests and facts use one form. +Core's IR is frozen with `::`, so the request and the facts take that; where a generator needs a path (`/`, for a file), +it makes it from the segments. The spelling is settled where the request type changes, in generation. + +## Which format + +This is a change to what a version freezes, so the format stamp moves and there is a step for it under +[IR migrations](../ir-migrations/index.md): frozen copies of the formats, an `up` that writes what the old format never +recorded (as known where it can be shown, explicit unknown where it can't), an inverse witness, fixtures, a format +document, all in one pull request, or the gate fails. The question is *which* format. + +The first migration step, [3 to 4](../ir-migrations/format-4.md), is the chains of +[granular `@unverified`](../shared-vocabulary/granular-unverified.md) ([core#222](https://github.com/ComlineProject/core/issues/222)), +and is the first real client of the system. + +| | Rides with format 4 | Comes right after, as format 5 | +|---|---|---| +| **Bumps** | one: a store is migrated once | two: the first migration, then another; a store written by 3's closing core goes 3 to 4 to 5 | +| **The step** | the 3-to-4 step also writes provenance | a small step of its own, `up` writing provenance from the old rule | +| **What `up` writes** | provenance from the `dep_` entries and the namespace rule. That rule is the old classification, and exact for any version built since the shadowing guard ([#256](https://github.com/ComlineProject/core/pull/256)): the guard is what made the spelling a true record. For an older store it may be wrong, which the step would mark unknown instead | the same | +| **Risk to the first client** | format 4's pull request grows, and #222's chains and provenance have to be reviewed, proven and fixtured together, in the first real use of the system | format 4 is as designed; provenance gets its own fixtures and its own square | +| **Hashes** | moved once: every object's address, a dependency pin and `schema_ir_hash` change at the same bump | moved twice | +| **Timing** | provenance waits for #222, or #222 waits for it | independent; provenance can ship after 4, and the rest of this proposal doesn't wait on the IR | + +Open: [which of the two](index.md#open-questions). Whichever is chosen, the 1.0 reset applies: stores in today's +formats aren't migrated, and only the format that exists at 1.0 carries a guaranteed path. + +## What the guard becomes + +The shadowing guard exists because classification was by name. With provenance recorded, and an own schema reachable only +as `package::…`, a package's own `greeting` and a dependency's `greeting` can no longer be confused by a `use`, or by a +tool. + +They can still *land on the same compiled namespace*: an own `src/greeting/hello.ids` and the dependency's `hello.ids` +are both `greeting::hello`, and two files cannot be generated at one path +(`{{language}}/{{namespace}}.{{ext}}`). So the guard doesn't simply go. [Open](index.md#open-questions): whether it is +narrowed to **equal namespaces** (refused as a collision, with its own message, and no longer about classification), +or a dependency's schemas get their own prefix in the output, so that none can collide. diff --git a/docs/docs/proposals/use-paths-and-groups/relative-use.md b/docs/docs/proposals/use-paths-and-groups/relative-use.md new file mode 100644 index 0000000..b3c09f4 --- /dev/null +++ b/docs/docs/proposals/use-paths-and-groups/relative-use.md @@ -0,0 +1,102 @@ +# Own schemas only through relative paths + +Status: **draft** · decided with the user 2026-11-15 · part of [Own schemas, provenance and dependency +groups](index.md) + +**The question.** In `use greeting::hello::Greeting`, is `greeting` the package's own `src/greeting.ids`, a dependency +named `greeting`, or something else? **Can the first segment of an absolute path always mean one thing?** + +## The rule + +**Decided.** Within a package, its own schemas are reached only through a relative path: + +| To reach | Write | +|---|---| +| a schema of this package, from its root | `use package::types::User` | +| the schema one level up | `use parent::common::Error` | +| the current schema, and what is under it | `use self::nested::Type` | +| a dependency | `use greeting::hello::Greeting` | +| the standard library | `use std::http::Request` | + +An **absolute first segment always means `std` or a dependency**, never the package itself. The relative forms already +exist and are already documented ([Imports](../../guides/idl/use.md#path-forms)); what changes is that they become the +only way to name the package's own schemas, in every form (a single item, a whole namespace, `{ ... }` and `*`). + +```ids +// before: a bare path, which could as well be a dependency's +use types::User +use types::{Order, Customer} + +// after +use package::types::User +use package::types::{Order, Customer} +``` + +The reserved dependency names are **`std`, `package`, `parent` and `self`**. Core already refuses all four as a name +in `dependencies` (`reserved_dependency_name`); this proposal keeps that and says so in the reference, because from now +on the four words are the whole set of first segments that are not a dependency's name. + +## Why + +Today the first segment is resolved by trying, in order, `self` / `parent` / `package`, then `std`, then a dependency +of that name, and falling through to "the same package". That has three costs. + +- **The classification of compiled schemas follows the spelling.** A schema is a dependency's when the first segment of + its namespace is a dependency's name. A package that depends on `greeting` and also has `src/greeting.ids` has a + schema that looks like the dependency's. Classified by its spelling, its protocol would be taken for a dependency's: + it would lose its wire numbers, and compatibility would compare it by reach instead of by what it declares. Core + refuses to build such a package today (the shadowing guard, [see the index](index.md#where-things-stand)), so the rule is enforced by making a + file name unusable, and that only for the names the package happens to depend on today: **adding a dependency can + break a package's own schema**, and which name that is, is none of the schema's business. +- **A bare `use greeting::…` is equally ambiguous to a reader.** Without opening `config.idp` and `src/`, the line does + not say whether the schema is local, and a package author changing either file changes what the line means. +- **The same ambiguity has already been a bug.** [core#245](https://github.com/ComlineProject/core/issues/245): a + dependency's `use` of its own sibling schema resolved against the consumer's schema of the same name. + +Rust 2018 is the precedent: a path starting with `crate::` is the crate's own, and one starting with a name is an +external crate (or `std`). Comline's word is `package`, since that is the unit it has. + +## `parent`, not `super` + +**Decided.** The word for "one level up" stays `parent`; `super::` is not added as a synonym. It was suggested because +Rust spells it `super`. One word is kept because: + +- `parent` is already in the grammar, in the language's vocabulary, in the [Imports](../../guides/idl/use.md) guide and + in the language server. Two spellings of one meaning means every tool handles both, the formatter has to pick one, + and a codebase ends up with both. +- `super` would become a reserved word. A schema or a dependency named `super` is legal today and would stop being, + which is a breaking change this proposal doesn't otherwise need. +- A namespace is a path of files, not a tree of modules with visibility rules; `parent` says what it is, one level up, + without borrowing what `super` means in Rust. + +## What the editor and the fix do + +A bare path that reaches the package's own schema is a deprecation (below). The language server attaches a **quick fix** that +rewrites it to the `package::…` form. `package::` is chosen over the shortest relative form because it is the same +wherever the file sits: moving a schema to another directory doesn't change what its imports say. The qualified +references the import brought in, written with the old spelling, are rewritten with it. `comline fix` applies the +same rewrite to every file. + +A path that matches nothing is the error it is today ([When nothing +matches](../../guides/idl/use.md#when-nothing-matches)), with one addition: a bare path whose first segment is neither a +dependency nor `std`, but the name of one of the package's own schemas, is the deprecation, not "no schema matches". + +## Rollout by edition + +This is the kind of change [editions](../../reference/versioning.md#editions) are for: a form that was valid is no +longer, and the package keeps the old behaviour until it moves. + +1. **In the current edition: a warning.** A bare path to the package's own schema warns, in the `deprecation::` family, + on every use, with the fix attached, and the editor shows it struck through like any deprecated word. Builds pass. +2. **In the next edition: an error.** The same use is `edition::removed`, and `comline fix --edition N` rewrites it + with the rest of what the edition moves. +3. **Dependencies are unaffected.** A dependency's compiled schemas are frozen with their `use`s already resolved, and + a package compiled under any edition can depend on one compiled under another. + +Which edition number the error lands in is [an open question](index.md#open-questions). + +## What stays as it is + +- `use shared_types::foo::X`, `use std::http::Request`: a dependency's and `std`'s paths are unchanged. +- The shapes of a `use` (single, whole namespace, `{ ... }`, `*`, `as`) and what they bring in. +- A schema's namespace, which is still its path under `src/`. Only how it is *written in a `use`* changes. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 232b3fb..e878588 100755 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -254,6 +254,12 @@ nav: - 'Hashes, pins and history': 'proposals/ir-migrations/hashes-and-history.md' - 'Beyond the local store': 'proposals/ir-migrations/beyond-the-store.md' - 'Format 4': 'proposals/ir-migrations/format-4.md' + - 'Own schemas, provenance and groups': + - 'proposals/use-paths-and-groups/index.md' + - 'Relative paths': 'proposals/use-paths-and-groups/relative-use.md' + - 'Provenance': 'proposals/use-paths-and-groups/provenance.md' + - 'Dependency groups': 'proposals/use-paths-and-groups/dependency-groups.md' + - 'Import formatting': 'proposals/use-paths-and-groups/import-formatting.md' extra_css: - stylesheets/nav.css?v=23 # bump on every nav.css change — it is not cache-busted otherwise