ids

Validate, materialize, and index Calor declaration IDs

Bash

calor ids <command> [paths] [options]

Current Calor syntax permits structural openers without source IDs. The parser gives those declarations in-memory _auto IDs; use ids assign only when your repository needs explicit, durable source identity.

Command	Purpose
`check`	Validate source IDs, including prefixes, formats, duplicate values, and test-ID policy
`assign`	Add compact IDs to declarations that omit them and optionally repair duplicates
`index`	Write a JSON declaration index

`ids check`

Bash

calor ids check <paths...> [options]

Option	Description
`--allow-test-ids`	Allow short IDs such as `f001` and `m001` outside test paths
`-v`, `--verbose`	Show file-processing detail in text mode
`-f`, `--format <text\|json>`	Select text output or the schema 2.0 machine envelope

Exit code 0 means every scanned ID passed; 1 means the command found an ID problem or no .calr inputs. JSON mode writes one envelope to stdout and keeps human diagnostics on stderr.

Bash

calor ids check src/
calor ids check src/ --format json

The check validates the current tree. It cannot infer from a standalone snapshot that one otherwise-valid ID was replaced by another; use version control or an edit hook when ID-churn detection matters.

`ids assign`

Bash

calor ids assign <paths...> [options]

Option	Short	Description
`--dry-run`	`-n`	Preview assignments without writing files
`--fix-duplicates`		Keep the first occurrence and reassign later duplicates
`--allow-test-ids`		Leave allowed short test IDs unchanged
`--verbose`	`-v`	List changed files and assignments

Assignments use the current compact format, such as f_7k9m2npqrstv.

Bash

calor ids assign src/ --dry-run
calor ids assign src/
calor ids assign src/ --fix-duplicates

`ids index`

Bash

calor ids index <paths...> [--output <file>]

--output (-o) defaults to calor.ids.json. The file contains an array of entries:

JSON

[
  {
    "id": "f_7k9m2npqrstv",
    "kind": "Function",
    "name": "Calculate",
    "file": "src/calculator.calr",
    "line": 3
  }
]

Formats and Policy

The canonical v0.12 form is a kind prefix plus 12 lowercase Crockford Base32 characters. The compiler still accepts legacy 26-character uppercase ULID payloads.

Kind	Compact example
Module	`m_3hj8x2bw9pkq`
Function	`f_7k9m2npqrstv`
Class	`c_z4w7n5q2gxht`
Method	`mt_5v8b3kxq2nhp`
Constructor	`ctor_9m4z7x2qhwjt`

Short sequential IDs are accepted in tests/, docs/, and examples/. Use calor fix --compact-ids for a reversible legacy-ULID migration rather than regenerating IDs:

Bash

calor fix src/ --compact-ids --log compact-ids.json

Suggested Workflow

Bash

# Compact authoring form is valid
calor -i src/app.calr -o generated/app.g.cs

# Materialize persistent IDs when external tools need them
calor ids assign src/ --dry-run
calor ids assign src/

# Validate in CI and generate an index for navigation tools
calor ids check src/
calor ids index src/ --output calor.ids.json

ids

ids check

ids assign

ids index

Formats and Policy

Suggested Workflow

See Also

`ids check`

`ids assign`

`ids index`