|
| yaml.ScalarNode | _represent_str (yaml.SafeDumper dumper, str data) |
| yaml.MappingNode | _represent_flowmap (yaml.SafeDumper dumper, _FlowMap data) |
| Any | _field_default (Any field_info) |
| Any | _to_yaml_obj (Any value) |
| Any | _depends_on_to_yaml (Any edge) |
| dict[str, Any] | model_to_frontmatter (RegistryModel model) |
| str | dump_frontmatter (dict[str, Any] mapping) |
| str | _normalize_body (str body) |
| str | format_record_text (RegistryModel model, str body="") |
| tuple[str, str] | split_record_text (str text) |
| None | _assert_no_yaml_features (str frontmatter, str rel_path) |
| Any | _model_for (ScannedRecord scanned) |
| tuple[RegistryModel, str] | load_record (ScannedRecord scanned) |
| None | _check_identity (ScannedRecord scanned, RegistryModel model) |
| str | canonicalize_file (ScannedRecord scanned) |
| list[str] | format_source_tree (list[ScannedRecord] records, *, bool check=False) |
| bytes | canonical_record_bytes (ScannedRecord scanned) |
Canonical YAML dumper + record loader for the AuthoredSource format.
Purpose
-------
Read a source record (``yaml.safe_load``) and re-emit byte-canonical frontmatter
with a custom ``yaml.SafeDumper`` subclass, per Registry Source & Storage Spec
V0.22 §3.2: scalar string values double-quoted, plain keys, field-declaration
key order, pydantic defaults + empty containers omitted, ``depends_on``
canonical emission, no anchors/aliases/tags, LF / UTF-8 / no-BOM / one trailing
newline. The formatter is idempotent (AC §8.4).
Responsibilities
----------------
- ``format_record_text(model, body)`` — canonical bytes for a record.
- ``load_record(scanned)`` — parse + strict-validate against the P1.1 model.
- ``canonicalize_file`` / ``format_source_tree`` — format or ``--check`` a tree.
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
L2 - format/load lifecycle
L3 - per-record canonicalisation
L4 - YAML node emission details
Contracts
---------
- Idempotent: ``format(format(x)) == format(x)``.
- Round-trip safe: a canonical record re-parses to an equal model.
- All string scalar VALUES double-quoted (round-trips any single-line content);
keys emitted plain. ``depends_on`` blocks → bare quoted id; enables/gates →
inline ``{id: "..", kind: ..}`` (never ``{id, kind: blocks}``).
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- yaml (safe_load + custom SafeDumper)
- option_c_registry_contracts (P1.1 entity models)
- oc_chat.registry.source.errors (SRC_* codes)
- oc_chat.registry.source.promoted_item (PromotedItem - the model for promoted_item records)
- oc_chat.registry.source.scanner (ScannedRecord - the scanned record every loader and formatter takes)
- pydantic (ValidationError - reported as an SRC_STRICT_TYPE failure)
- pydantic_core (PydanticUndefined - telling a field with no default apart)
| list[str] oc_chat.registry.source.canonical.format_source_tree |
( |
list[ScannedRecord] | records, |
|
|
* | , |
|
|
bool | check = False ) |
Format (or, with ``check=True``, verify) every formattable record.
Returns the list of relative paths that were rewritten (or, in check mode,
the non-canonical paths). [OP-5] promoted parity: promoted items are
canonicalised + ``--check``-verified like every other entity (the earlier
model-gap skip is removed) so ``format --check`` catches a non-canonical
promoted file.
Definition at line 372 of file canonical.py.
1.15.0