codec-cortex 0.3.2__py3-none-any.whl

cortex/glossary/minimal.py

@@ -0,0 +1,94 @@
+"""Minimal sigil sets per template kind.
+
+Each function returns a list of :class:`~cortex.core.ast.SigilDef`
+appropriate for the template (brain / skill / package / generic).
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from ..core.ast import SigilDef
+
+
+def brain_sigils() -> List[SigilDef]:
+    """Sigils for a ``brain.cortex`` template (Nivel 2 operativo)."""
+
+    return [
+        SigilDef("IDN", "identity",   "attrs",  "B", "Semantic",   "Actor or memory identity"),
+        SigilDef("DOM", "domain",     "attrs",  "B", "Semantic",   "Operating domain or scope"),
+        SigilDef("CNST","constraint", "attrs",  "H", "Prefrontal", "Hard operational boundary"),
+        SigilDef("FCS", "focus",      "attrs",  "H", "Working",    "Active attention anchor"),
+        SigilDef("OBJ", "objective",  "attrs",  "H", "Working",    "Active goal with success criterion"),
+        SigilDef("WRK", "work",       "attrs",  "M", "Working",    "Current operational state"),
+        SigilDef("STP", "step",       "attrs",  "M", "Working",    "Immediate next action"),
+        SigilDef("NXT", "next",       "attrs",  "M", "Working",    "Queued next action"),
+        SigilDef("RSK", "risk",       "attrs",  "M", "Prefrontal", "Risk and mitigation"),
+        SigilDef("AUD", "audit",      "attrs",  "M", "Prefrontal", "Audit or verification record"),
+        SigilDef("STAT","status",     "attrs",  "B", "Semantic",   "Status or maturity declaration"),
+        SigilDef("REF", "reference",  "attrs",  "B", "Semantic",   "File, object or source reference"),
+        SigilDef("KNW", "knowledge",  "attrs",  "B", "Semantic",   "Stable or promoted knowledge"),
+        SigilDef("SES", "session",    "attrs",  "M", "Episodic",   "Compressed episode I/O/R"),
+        SigilDef("LNG", "lesson",     "attrs",  "M", "Episodic",   "Lesson or pattern"),
+        SigilDef("DIAG","diagram",    "bloque", "M", "Episodic/Visual", "Verbatim diagram block"),
+        SigilDef("!",   "rule",       "attrs",  "H", "Prefrontal", "Mandatory compact rule"),
+    ]
+
+
+def skill_sigils() -> List[SigilDef]:
+    """Sigils for a ``SKILL.cortex`` template (Nivel 1)."""
+
+    return [
+        SigilDef("IDN", "identity",   "attrs",  "B", "Semantic",   "Skill identity"),
+        SigilDef("DOM", "domain",     "attrs",  "B", "Semantic",   "Adoption scope and context"),
+        SigilDef("AXM", "axiom",      "cuerpo", "H", "Prefrontal", "Non-negotiable principle"),
+        SigilDef("CNST","constraint", "attrs",  "H", "Prefrontal", "Hard operational boundary"),
+        SigilDef("KNW", "knowledge",  "attrs",  "B", "Semantic",   "Protocol knowledge"),
+        SigilDef("HDL", "handler",    "attrs-pos","M","Semantic",  "Operation descriptor (positional)"),
+        SigilDef("STAT","status",     "attrs",  "B", "Semantic",   "Status or maturity declaration"),
+        SigilDef("DIAG","diagram",    "bloque", "M", "Episodic/Visual", "Normative diagram"),
+        SigilDef("REF", "reference",  "attrs",  "B", "Semantic",   "Source or cross-reference"),
+        SigilDef("RSK", "risk",       "attrs",  "M", "Prefrontal", "Protocol risk and mitigation"),
+        SigilDef("AUD", "audit",      "attrs",  "M", "Prefrontal", "Spec audit record"),
+        SigilDef("!",   "rule",       "attrs",  "H", "Prefrontal", "Mandatory compact rule"),
+    ]
+
+
+def package_sigils() -> List[SigilDef]:
+    """Sigils for a Nivel 3 ``*.cortex`` package."""
+
+    return [
+        SigilDef("IDN", "identity",   "attrs",  "B", "Semantic",   "Package identity"),
+        SigilDef("DOM", "domain",     "attrs",  "B", "Semantic",   "Scope and purpose"),
+        SigilDef("KNW", "knowledge",  "attrs",  "B", "Semantic",   "Compressed knowledge"),
+        SigilDef("REF", "reference",  "attrs",  "B", "Semantic",   "Source or traceability reference"),
+        SigilDef("LIM", "limit",      "attrs",  "M", "Prefrontal", "Explicit operational limit"),
+        SigilDef("CLAIM","claim",     "attrs",  "M", "Prefrontal", "Verifiable assertion"),
+        SigilDef("DIAG","diagram",    "bloque", "M", "Episodic/Visual", "Verbatim diagram block"),
+        SigilDef("STAT","status",     "attrs",  "B", "Semantic",   "Status declaration"),
+        SigilDef("AUD", "audit",      "attrs",  "M", "Prefrontal", "Audit record"),
+        SigilDef("RSK", "risk",       "attrs",  "M", "Prefrontal", "Risk and mitigation"),
+    ]
+
+
+def generic_sigils() -> List[SigilDef]:
+    """A superset sigil set for generic ``.cortex`` files."""
+
+    return brain_sigils() + [
+        SigilDef("AXM", "axiom",      "cuerpo", "H", "Prefrontal", "Non-negotiable principle"),
+        SigilDef("CLAIM","claim",     "attrs",  "M", "Prefrontal", "Verifiable assertion"),
+        SigilDef("LIM", "limit",      "attrs",  "M", "Prefrontal", "Explicit operational limit"),
+        SigilDef("HDL", "handler",    "attrs-pos","M","Semantic",  "Operation descriptor (positional)"),
+        SigilDef("TAG", "tag",        "attrs",  "B", "Semantic",   "Classification metadata"),
+        SigilDef("PFL", "pitfall",    "attrs",  "M", "Prefrontal", "Known antipattern"),
+        SigilDef("DEP", "dependency", "attrs",  "M", "Semantic",   "Cross-artefact dependency"),
+        SigilDef("DESC","description","cuerpo", "B", "Semantic",   "Structured description"),
+        SigilDef("ERR", "error",      "attrs",  "M", "Prefrontal", "Known error with cause/solution"),
+    ]
+
+
+def hdL_contract():
+    """Default positional contract for ``HDL`` (operation | status | requires)."""
+
+    from ..core.ast import AttrsPosContract
+    return AttrsPosContract(sigil="HDL", fields=["operation", "status", "requires"])

cortex/glossary/model.py

@@ -0,0 +1,77 @@
+"""Glossary model and helpers.
+
+Wraps the :class:`~cortex.core.ast.Glossary` with convenience builders
+and queries used by templates, the CRUD layer and the CLI.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ..core.ast import (
+    AttrsPosContract,
+    Glossary,
+    MicroDef,
+    SigilDef,
+    TypeDef,
+)
+from ..core.errors import CANONICAL_MICRO
+
+
+def minimal_glossary() -> Glossary:
+    """Return a fresh glossary seeded with canonical types + micro-tokens.
+
+    Sigils are *not* added here; the caller picks the relevant sigil set
+    from :mod:`cortex.glossary.minimal` based on the template kind.
+    """
+
+    g = Glossary()
+    # Canonical types
+    for name, desc in [
+        ("attrs", "key:value pairs"),
+        ("attrs-pos", "positional with explicit contract"),
+        ("cuerpo", "free text body"),
+        ("bloque", "verbatim multiline block"),
+        ("relación", "causal A -> B form"),
+    ]:
+        g.add_type(TypeDef(name=name, description=desc))
+    # Canonical micro-tokens
+    for tok, val in CANONICAL_MICRO.items():
+        g.add_micro(MicroDef(token=tok, value=val))
+    return g
+
+
+def add_sigil(glossary: Glossary, sigil: SigilDef) -> None:
+    """Add a sigil, rejecting silent redefinition of existing ones."""
+
+    existing = glossary.sigils.get(sigil.sigil)
+    if existing is not None and existing.to_dict() != sigil.to_dict():
+        from ..core.errors import ProtectedSigilError
+        raise ProtectedSigilError(sigil.sigil)
+    glossary.add_sigil(sigil)
+
+
+def add_micro(glossary: Glossary, micro: MicroDef) -> None:
+    existing = glossary.micro.get(micro.token)
+    if existing is not None and existing.value != micro.value:
+        from ..core.errors import CortexError
+        raise CortexError(
+            "E021_INVALID_VALUE",
+            f"micro-token {micro.token!r} already declared with value {existing.value!r}",
+        )
+    glossary.add_micro(micro)
+
+
+def add_contract(glossary: Glossary, contract: AttrsPosContract) -> None:
+    glossary.add_contract(contract)
+
+
+def sigils_in_use(glossary: Glossary, entries: Iterable) -> dict:
+    """Return ``{sigil: count}`` for sigils used by ``entries``."""
+
+    counts: dict = {}
+    for e in entries:
+        if e.sigil in {"GSIG", "GTYP", "GMIC", "GCON"}:
+            continue
+        counts[e.sigil] = counts.get(e.sigil, 0) + 1
+    return counts

cortex/glossary/resolver.py

@@ -0,0 +1,96 @@
+"""Glossary resolver — runtime queries over a :class:`Glossary`.
+
+Used by renderers, the validator and the CRUD layer to answer:
+  - "what is the type of sigil X?"
+  - "is this sigil declared?"
+  - "does this sigil have a positional contract?"
+  - "what is the expansion of this micro-token?"
+  - "is this token used by any entry?"
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from ..core.ast import Entry, Glossary
+from ..core.errors import CANONICAL_SIGILS
+
+
+def is_canonical(sigil: str) -> bool:
+    return sigil in CANONICAL_SIGILS
+
+
+def is_declared(glossary: Glossary, sigil: str) -> bool:
+    return sigil in glossary.sigils
+
+
+def type_of(glossary: Glossary, sigil: str) -> Optional[str]:
+    sd = glossary.sigils.get(sigil)
+    return sd.type if sd else None
+
+
+def contract_of(glossary: Glossary, sigil: str):
+    return glossary.contracts.get(sigil)
+
+
+def expand_micro(glossary: Glossary, value: str) -> str:
+    """Expand micro-tokens in ``value`` if they are properly delimited.
+
+    Delimiters recognised: whitespace, ``,``, ``{``, ``}``, start/end.
+    Tokens inside words (e.g. ``param_cur``) are NOT expanded.
+    """
+
+    if not isinstance(value, str):
+        return value
+    out = []
+    i = 0
+    n = len(value)
+    while i < n:
+        ch = value[i]
+        if ch.isalnum() or ch == "_":
+            # consume identifier
+            j = i
+            while j < n and (value[j].isalnum() or value[j] == "_"):
+                j += 1
+            word = value[i:j]
+            # check if word matches a micro-token AND is delimited
+            prev_ch = value[i - 1] if i > 0 else ""
+            next_ch = value[j] if j < n else ""
+            left_delim = (prev_ch == "" or prev_ch in " ,{}\n\t")
+            right_delim = (next_ch == "" or next_ch in " ,{}\n\t")
+            if left_delim and right_delim and word in glossary.micro:
+                out.append(glossary.micro[word].value)
+            else:
+                out.append(word)
+            i = j
+        else:
+            out.append(ch)
+            i += 1
+    return "".join(out)
+
+
+def sigil_usage_count(entries: Iterable[Entry]) -> dict:
+    counts: dict = {}
+    for e in entries:
+        if e.sigil in {"GSIG", "GTYP", "GMIC", "GCON"}:
+            continue
+        counts[e.sigil] = counts.get(e.sigil, 0) + 1
+    return counts
+
+
+def is_micro_used(entries: Iterable[Entry], token: str) -> bool:
+    """Return True if any entry's value contains the micro-token.
+
+    Conservative check: scans string values for delimited occurrences.
+    """
+
+    for e in entries:
+        if e.type == "bloque":
+            continue  # micro-tokens never expand inside bloque
+        if isinstance(e.value, dict):
+            for v in e.value.values():
+                if isinstance(v, str) and token in v.split():
+                    return True
+        elif isinstance(e.value, str) and token in e.value.split():
+            return True
+    return False

cortex/hcortex/__init__.py

@@ -0,0 +1,35 @@
+"""HCORTEX package — READ renderer, EDIT renderer, EDIT parser, profiles, recovery."""
+
+from .profiles import (
+    Profile, PROFILES, DEFAULT_PROFILE,
+    resolve_profile, classify_entry, classify_doc,
+    filter_by_profile, sort_by_plevel, plevel_rank,
+)
+from .read_renderer import render_hcortex_read
+from .edit_renderer import render_hcortex_edit
+from .edit_parser import parse_hcortex_edit, parse_glossary_block
+from .markdown_model import (
+    HCORTEX_READ_HEADER, HCORTEX_EDIT_HEADER,
+    EditHeader, is_hcortex_read, is_hcortex_edit,
+)
+from .recovery import (
+    RecoveryResult, recover_cortex, strip_preamble,
+    normalise_legacy_type_name, LEGACY_TYPE_ALIASES, LEGACY_COLUMN_ALIASES,
+)
+
+__all__ = [
+    # Profiles and priority classifier
+    "Profile", "PROFILES", "DEFAULT_PROFILE",
+    "resolve_profile", "classify_entry", "classify_doc",
+    "filter_by_profile", "sort_by_plevel", "plevel_rank",
+    # Renderers
+    "render_hcortex_read", "render_hcortex_edit",
+    # Parser
+    "parse_hcortex_edit", "parse_glossary_block",
+    # Markdown model
+    "HCORTEX_READ_HEADER", "HCORTEX_EDIT_HEADER",
+    "EditHeader", "is_hcortex_read", "is_hcortex_edit",
+    # Recovery
+    "RecoveryResult", "recover_cortex", "strip_preamble",
+    "normalise_legacy_type_name", "LEGACY_TYPE_ALIASES", "LEGACY_COLUMN_ALIASES",
+]