codec-cortex 0.3.2__py3-none-any.whl

cortex/core/__init__.py

@@ -0,0 +1,85 @@
+"""Core module exports."""
+
+from .ast import (
+    AttrsPosContract,
+    CortexDocument,
+    Entry,
+    Glossary,
+    MicroDef,
+    Section,
+    SigilDef,
+    TypeDef,
+    compute_document_hash,
+    compute_entry_hash,
+    normalize_section_id,
+)
+from .compare import Diff, DiffResult, compare_ast
+from .errors import (
+    CANONICAL_MICRO,
+    CANONICAL_SIGILS,
+    CANONICAL_TYPES,
+    CortexError,
+    Diagnostic,
+    DiagnosticBag,
+    GLOSSARY_RESERVED_SIGILS,
+    MissingGlossaryError,
+    GlossaryNotFirstError,
+    UnknownSigilError,
+    UnknownTypeError,
+    BraceError,
+    InvalidAttrsError,
+    AttrsPosContractMissingError,
+    DuplicateEntryError,
+    ProtectedEntryError,
+    HCortexReadNotCompilableError,
+    HCortexEditMetadataMissingError,
+    RoundtripFailedError,
+    NotFoundError,
+    AmbiguousSelectorError,
+    AtomicWriteError,
+    InvalidSectionHeaderError,
+    UnparsedLineError,
+    ProtectedSigilError,
+    SigilInUseError,
+    MicroInUseError,
+    InvalidValueError,
+    TemplateUnknownError,
+)
+from .lexer import lex
+from .parser import parse_cortex, parse_attrs_body, parse_attrs_pos_body, build_entry_from_value
+from .validator import validate, is_valid, is_protected_entry
+from .document_kind import (
+    DocumentKind, infer_document_kind, validate_level_policy,
+    LIVE_STATE_SIGILS,
+)
+from .writer import write_cortex, serialize_entry, serialize_entry_value, serialize_glossary
+
+__all__ = [
+    # AST
+    "AttrsPosContract", "CortexDocument", "Entry", "Glossary", "MicroDef",
+    "Section", "SigilDef", "TypeDef", "compute_document_hash",
+    "compute_entry_hash", "normalize_section_id",
+    # Compare
+    "Diff", "DiffResult", "compare_ast",
+    # Errors
+    "CANONICAL_MICRO", "CANONICAL_SIGILS", "CANONICAL_TYPES",
+    "CortexError", "Diagnostic", "DiagnosticBag",
+    "GLOSSARY_RESERVED_SIGILS",
+    "MissingGlossaryError", "GlossaryNotFirstError", "UnknownSigilError",
+    "UnknownTypeError", "BraceError", "InvalidAttrsError",
+    "AttrsPosContractMissingError", "DuplicateEntryError",
+    "ProtectedEntryError", "HCortexReadNotCompilableError",
+    "HCortexEditMetadataMissingError", "RoundtripFailedError",
+    "NotFoundError", "AmbiguousSelectorError", "AtomicWriteError",
+    "InvalidSectionHeaderError", "UnparsedLineError", "ProtectedSigilError",
+    "SigilInUseError", "MicroInUseError", "InvalidValueError",
+    "TemplateUnknownError",
+    # Parser / writer / validator
+    "lex", "parse_cortex", "parse_attrs_body", "parse_attrs_pos_body",
+    "build_entry_from_value",
+    "validate", "is_valid", "is_protected_entry",
+    "DocumentKind", "infer_document_kind", "validate_level_policy",
+    "LIVE_STATE_SIGILS",
+    "write_cortex", "serialize_entry", "serialize_entry_value",
+    "serialize_glossary",
+]

cortex/core/ast.py

@@ -0,0 +1,313 @@
+"""Canonical AST for CODEC-CORTEX.
+
+The AST is the *only* internal representation of a ``.cortex`` document.
+Every parser, renderer, compiler and CRUD operation goes through the AST.
+
+The dataclasses below mirror Section 5.1 of the specification.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Glossary model
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SigilDef:
+    """A sigil declaration from ``$0``.
+
+    Fields mirror the canonical pipe-separated table:
+    ``SIGIL | NAME | TYPE | RISK | LAYER | DESCRIPTION``.
+    """
+
+    sigil: str
+    name: str
+    type: str
+    risk: str = "M"
+    layer: str = "Semantic"
+    description: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "sigil": self.sigil,
+            "name": self.name,
+            "type": self.type,
+            "risk": self.risk,
+            "layer": self.layer,
+            "description": self.description,
+        }
+
+
+@dataclass
+class TypeDef:
+    """An expansion-type declaration from ``$0``."""
+
+    name: str
+    description: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"name": self.name, "description": self.description}
+
+
+@dataclass
+class MicroDef:
+    """A micro-token declaration from ``$0``."""
+
+    token: str
+    value: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"token": self.token, "value": self.value}
+
+
+@dataclass
+class AttrsPosContract:
+    """Positional contract for an ``attrs-pos`` sigil.
+
+    ``fields`` is the ordered list of field names declared in ``$0``.
+    """
+
+    sigil: str
+    fields: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"sigil": self.sigil, "fields": list(self.fields)}
+
+
+@dataclass
+class Glossary:
+    """Local ``$0`` glossary attached to a :class:`CortexDocument`."""
+
+    sigils: Dict[str, SigilDef] = field(default_factory=dict)
+    types: Dict[str, TypeDef] = field(default_factory=dict)
+    micro: Dict[str, MicroDef] = field(default_factory=dict)
+    contracts: Dict[str, AttrsPosContract] = field(default_factory=dict)
+
+    def add_sigil(self, sigil: SigilDef) -> None:
+        self.sigils[sigil.sigil] = sigil
+
+    def add_type(self, t: TypeDef) -> None:
+        self.types[t.name] = t
+
+    def add_micro(self, m: MicroDef) -> None:
+        self.micro[m.token] = m
+
+    def add_contract(self, c: AttrsPosContract) -> None:
+        self.contracts[c.sigil] = c
+
+    def sigil_type(self, sigil: str) -> Optional[str]:
+        s = self.sigils.get(sigil)
+        return s.type if s else None
+
+    def contract_for(self, sigil: str) -> Optional[AttrsPosContract]:
+        return self.contracts.get(sigil)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "sigils": {k: v.to_dict() for k, v in self.sigils.items()},
+            "types": {k: v.to_dict() for k, v in self.types.items()},
+            "micro": {k: v.to_dict() for k, v in self.micro.items()},
+            "contracts": {k: v.to_dict() for k, v in self.contracts.items()},
+        }
+
+
+# ---------------------------------------------------------------------------
+# Entry / Section / Document
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Entry:
+    """A single ``SIGIL:name{...}`` entry inside a section."""
+
+    section: str
+    sigil: str
+    name: str
+    type: str  # attrs | attrs-pos | cuerpo | bloque | relación
+    value: Any  # dict | str | list (depends on type)
+    raw: str = ""  # original text (for bloque verbatim)
+    line_start: int = 0
+    line_end: int = 0
+    hash: str = ""
+    entry_id: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.hash:
+            self.hash = compute_entry_hash(self)
+        if not self.entry_id:
+            self.entry_id = self.hash
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "entry_id": self.entry_id,
+            "section": self.section,
+            "sigil": self.sigil,
+            "name": self.name,
+            "type": self.type,
+            "value": self.value,
+            "raw": self.raw,
+            "line_start": self.line_start,
+            "line_end": self.line_end,
+            "hash": self.hash,
+        }
+
+
+@dataclass
+class Section:
+    """A numbered ``$N`` section inside a :class:`CortexDocument`."""
+
+    id: str  # e.g. "$0", "$1"
+    title: str = ""
+    entries: List[Entry] = field(default_factory=list)
+    line_start: int = 0
+    # Raw comment lines preserved verbatim — used by $0 glossary parser
+    # and by the writer when re-serialising a section.
+    comments: List[str] = field(default_factory=list)
+    # Raw non-comment, non-entry lines (rare; recorded for round-trip safety)
+    raw_lines: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "entries": [e.to_dict() for e in self.entries],
+            "line_start": self.line_start,
+            "comments": list(self.comments),
+        }
+
+
+@dataclass
+class CortexDocument:
+    """Canonical AST root for a ``.cortex`` document.
+
+    Mirrors Section 5.1 of the spec.
+    """
+
+    meta: Dict[str, Any] = field(default_factory=dict)
+    glossary: Glossary = field(default_factory=Glossary)
+    sections: List[Section] = field(default_factory=list)
+    diagnostics: List[Dict[str, Any]] = field(default_factory=list)
+
+    # --- convenience helpers -------------------------------------------------
+
+    @property
+    def section_ids(self) -> List[str]:
+        return [s.id for s in self.sections]
+
+    def get_section(self, section_id: str) -> Optional[Section]:
+        # Normalize "$2", "2", "$2: x" forms
+        norm = normalize_section_id(section_id)
+        for s in self.sections:
+            if s.id == norm:
+                return s
+        return None
+
+    def get_or_create_section(self, section_id: str, title: str = "") -> Section:
+        sec = self.get_section(section_id)
+        if sec is not None:
+            return sec
+        norm = normalize_section_id(section_id)
+        sec = Section(id=norm, title=title)
+        self.sections.append(sec)
+        return sec
+
+    def iter_entries(self):
+        for sec in self.sections:
+            for e in sec.entries:
+                yield sec, e
+
+    def find_entries(self, sigil: Optional[str] = None, name: Optional[str] = None,
+                     section: Optional[str] = None) -> List[Entry]:
+        out: List[Entry] = []
+        for sec, e in self.iter_entries():
+            if section is not None and sec.id != normalize_section_id(section):
+                continue
+            if sigil is not None and e.sigil != sigil:
+                continue
+            if name is not None and e.name != name:
+                continue
+            out.append(e)
+        return out
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "meta": dict(self.meta),
+            "glossary": self.glossary.to_dict(),
+            "sections": [s.to_dict() for s in self.sections],
+            "diagnostics": list(self.diagnostics),
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False, sort_keys=False)
+
+
+# ---------------------------------------------------------------------------
+# Hashing helpers
+# ---------------------------------------------------------------------------
+
+def compute_entry_hash(entry: Entry) -> str:
+    """Stable structural hash of an entry.
+
+    The hash is computed over the *canonical* representation
+    (sigil, name, type, value) — not the raw text — so equivalent
+    entries that differ only in formatting still hash identically.
+    ``bloque`` entries include the verbatim raw text in the hash.
+    """
+
+    if entry.type == "bloque":
+        payload = {
+            "sigil": entry.sigil,
+            "name": entry.name,
+            "type": entry.type,
+            "raw": entry.raw,
+        }
+    else:
+        payload = {
+            "sigil": entry.sigil,
+            "name": entry.name,
+            "type": entry.type,
+            "value": entry.value,
+        }
+    blob = json.dumps(payload, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    return "sha256:" + hashlib.sha256(blob).hexdigest()
+
+
+def compute_document_hash(text: str) -> str:
+    blob = text.encode("utf-8")
+    return "sha256:" + hashlib.sha256(blob).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Section id normalization
+# ---------------------------------------------------------------------------
+
+def normalize_section_id(section_id: str) -> str:
+    """Normalize section identifiers.
+
+    Accepts:
+      - ``"$2"``        → ``"$2"``
+      - ``"2"``         → ``"$2"``
+      - ``"$2: TITLE"`` → ``"$2"``
+      - ``"$2 · TITLE"``→ ``"$2"``
+    """
+
+    if section_id is None:
+        return "$0"
+    s = section_id.strip()
+    if not s:
+        return "$0"
+    if not s.startswith("$"):
+        # accept "2" or "2: title"
+        if s.split(":", 1)[0].strip().isdigit():
+            return "$" + s.split(":", 1)[0].strip()
+        return "$" + s
+    # already starts with $
+    head = s[1:].split(":", 1)[0].split("·", 1)[0].strip()
+    if head.isdigit():
+        return "$" + head
+    return s

cortex/core/compare.py

@@ -0,0 +1,180 @@
+"""Structural comparison of two :class:`CortexDocument` ASTs.
+
+Used by ``cortex verify --roundtrip hcortex-edit`` to verify that
+``.cortex → HCORTEX-EDIT → .cortex`` preserves structural identity.
+
+Comparison rules (Section 10.2 of the spec):
+
+- Compare: section id, section order, sigil, entry name, expansion type,
+  parsed value, raw bloque exact, glossary definitions.
+- Ignore: non-structural comments, formatting whitespace, line numbers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from .ast import CortexDocument, Entry, Glossary
+
+
+@dataclass
+class Diff:
+    kind: str  # section_added | section_removed | section_reordered
+              # | entry_added | entry_removed | entry_value_changed
+              # | entry_type_changed | bloque_changed | glossary_changed
+    path: str
+    left: Any = None
+    right: Any = None
+    message: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "path": self.path,
+            "left": self.left,
+            "right": self.right,
+            "message": self.message,
+        }
+
+
+@dataclass
+class DiffResult:
+    equal: bool
+    diffs: List[Diff] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "equal": self.equal,
+            "diffs": [d.to_dict() for d in self.diffs],
+        }
+
+
+def compare_glossary(left: Glossary, right: Glossary) -> List[Diff]:
+    diffs: List[Diff] = []
+    # sigils
+    left_sigils = set(left.sigils)
+    right_sigils = set(right.sigils)
+    for s in sorted(left_sigils - right_sigils):
+        diffs.append(Diff("glossary_changed", f"sigils.{s}",
+                          left=left.sigils[s].to_dict(), right=None,
+                          message=f"sigil {s} removed from glossary"))
+    for s in sorted(right_sigils - left_sigils):
+        diffs.append(Diff("glossary_changed", f"sigils.{s}",
+                          left=None, right=right.sigils[s].to_dict(),
+                          message=f"sigil {s} added to glossary"))
+    for s in sorted(left_sigils & right_sigils):
+        ld = left.sigils[s].to_dict()
+        rd = right.sigils[s].to_dict()
+        if ld != rd:
+            diffs.append(Diff("glossary_changed", f"sigils.{s}",
+                              left=ld, right=rd,
+                              message=f"sigil {s} definition changed"))
+    # types
+    lt = set(left.types)
+    rt = set(right.types)
+    for t in sorted(lt - rt):
+        diffs.append(Diff("glossary_changed", f"types.{t}",
+                          left=left.types[t].to_dict(), right=None,
+                          message=f"type {t} removed"))
+    for t in sorted(rt - lt):
+        diffs.append(Diff("glossary_changed", f"types.{t}",
+                          left=None, right=right.types[t].to_dict(),
+                          message=f"type {t} added"))
+    # micro
+    lm = set(left.micro)
+    rm = set(right.micro)
+    for tok in sorted(lm - rm):
+        diffs.append(Diff("glossary_changed", f"micro.{tok}",
+                          left=left.micro[tok].to_dict(), right=None,
+                          message=f"micro-token {tok} removed"))
+    for tok in sorted(rm - lm):
+        diffs.append(Diff("glossary_changed", f"micro.{tok}",
+                          left=None, right=right.micro[tok].to_dict(),
+                          message=f"micro-token {tok} added"))
+    for tok in sorted(lm & rm):
+        if left.micro[tok].value != right.micro[tok].value:
+            diffs.append(Diff("glossary_changed", f"micro.{tok}",
+                              left=left.micro[tok].value,
+                              right=right.micro[tok].value,
+                              message=f"micro-token {tok} value changed"))
+    return diffs
+
+
+def compare_entry(left: Entry, right: Entry) -> List[Diff]:
+    diffs: List[Diff] = []
+    path = f"{left.section}/{left.sigil}:{left.name}"
+    if left.sigil != right.sigil:
+        diffs.append(Diff("entry_type_changed", path,
+                          left=left.sigil, right=right.sigil,
+                          message="sigil changed"))
+    if left.name != right.name:
+        diffs.append(Diff("entry_type_changed", path,
+                          left=left.name, right=right.name,
+                          message="name changed"))
+    if left.type != right.type:
+        diffs.append(Diff("entry_type_changed", path,
+                          left=left.type, right=right.type,
+                          message="expansion type changed"))
+    # Value comparison
+    if left.type == "bloque":
+        # Compare verbatim raw
+        if left.value != right.value:
+            diffs.append(Diff("bloque_changed", path,
+                              left=left.value, right=right.value,
+                              message="bloque content changed (verbatim mismatch)"))
+    else:
+        if left.value != right.value:
+            diffs.append(Diff("entry_value_changed", path,
+                              left=left.value, right=right.value,
+                              message="parsed value changed"))
+    return diffs
+
+
+def compare_ast(left: CortexDocument, right: CortexDocument) -> DiffResult:
+    """Compare two ASTs structurally; return :class:`DiffResult`."""
+
+    diffs: List[Diff] = []
+    diffs.extend(compare_glossary(left.glossary, right.glossary))
+
+    # Sections
+    left_secs = {s.id: s for s in left.sections if s.id != "$0"}
+    right_secs = {s.id: s for s in right.sections if s.id != "$0"}
+    left_order = [s.id for s in left.sections if s.id != "$0"]
+    right_order = [s.id for s in right.sections if s.id != "$0"]
+    # added/removed
+    for sid in left_order:
+        if sid not in right_secs:
+            diffs.append(Diff("section_removed", sid,
+                              message=f"section {sid} removed"))
+    for sid in right_order:
+        if sid not in left_secs:
+            diffs.append(Diff("section_added", sid,
+                              message=f"section {sid} added"))
+    # order (only among common sections)
+    common_left = [s for s in left_order if s in right_secs]
+    common_right = [s for s in right_order if s in left_secs]
+    if common_left != common_right:
+        diffs.append(Diff("section_reordered", "sections",
+                          left=common_left, right=common_right,
+                          message="section order changed"))
+
+    # Entries per common section
+    for sid in common_left:
+        ls = left_secs[sid]
+        rs = right_secs[sid]
+        le = {f"{e.sigil}:{e.name}": e for e in ls.entries}
+        re_ = {f"{e.sigil}:{e.name}": e for e in rs.entries}
+        for key in le:
+            if key not in re_:
+                diffs.append(Diff("entry_removed", f"{sid}/{key}",
+                                  message=f"entry {key} removed from {sid}"))
+        for key in re_:
+            if key not in le:
+                diffs.append(Diff("entry_added", f"{sid}/{key}",
+                                  message=f"entry {key} added to {sid}"))
+        for key in le:
+            if key in re_:
+                diffs.extend(compare_entry(le[key], re_[key]))
+
+    return DiffResult(equal=(len(diffs) == 0), diffs=diffs)