codec-cortex 0.3.2__py3-none-any.whl

cortex/cli/commands/v2_compare.py

@@ -0,0 +1,74 @@
+"""``cortex compare`` — compare two CORTEX/HCORTEX artefacts.
+
+Canonical name: ``compare`` (since v0.3.2).
+Deprecated alias: ``v2-compare`` (still accepted).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from ...core.errors import CortexError
+from ...v2.parser import parse_cortex_v2
+from ...v2.hcortex_parser import parse_hcortex
+from ...v2.encoder import encode_cortex_from_ast
+from ...v2.equivalence import compare_documents, diff_by_sigil, diff_by_section, diff_by_view
+
+
+def run(args) -> int:
+    if not os.path.exists(args.left):
+        raise CortexError("E013_NOT_FOUND", f"file not found: {args.left}")
+    if not os.path.exists(args.right):
+        raise CortexError("E013_NOT_FOUND", f"file not found: {args.right}")
+
+    with open(args.left, "r", encoding="utf-8") as f:
+        left_text = f.read()
+    with open(args.right, "r", encoding="utf-8") as f:
+        right_text = f.read()
+
+    # Parse both
+    left_doc = _parse_any(left_text)
+    right_doc = _parse_any(right_text)
+
+    left_bytes = left_text.encode("utf-8")
+    right_bytes = right_text.encode("utf-8")
+
+    result = compare_documents(left_doc, right_doc, left_bytes, right_bytes)
+
+    if args.format == "json":
+        print(json.dumps(result.to_dict(), indent=2, default=str))
+    else:
+        print(f"byte_identical: {result.byte_identical}")
+        print(f"ast_equivalent: {result.ast_equivalent}")
+        print(f"semantic_equivalent: {result.semantic_equivalent}")
+        print(f"content_equivalent: {result.content_equivalent}")
+        print(f"diff_count: {len(result.diffs)}")
+
+        if result.diffs:
+            print("\nDiffs by section:")
+            for sec, ds in diff_by_section(result.diffs).items():
+                print(f"  {sec}: {len(ds)} diffs")
+            print("\nDiffs by sigil:")
+            for sig, ds in diff_by_sigil(result.diffs).items():
+                print(f"  {sig}: {len(ds)} diffs")
+            print("\nDiffs by VIEW:")
+            for v, ds in diff_by_view(result.diffs).items():
+                print(f"  {v}: {len(ds)} diffs")
+
+            if args.verbose:
+                print("\nFirst 20 diffs:")
+                for d in result.diffs[:20]:
+                    print(f"  {d.kind} at {d.location}" + (f".{d.field}" if d.field else ""))
+
+    return 0 if result.equivalent else 1
+
+
+def _parse_any(text):
+    """Parse text as CORTEX or HCORTEX, return CortexV2Document."""
+    if "internal_encoding: HCORTEX" in text:
+        hdoc = parse_hcortex(text, strict=False)
+        doc, _ = encode_cortex_from_ast(hdoc)
+        return doc
+    else:
+        return parse_cortex_v2(text)

cortex/cli/commands/v2_convert.py

@@ -0,0 +1,183 @@
+"""``cortex convert`` — convert between CORTEX v2 and HCORTEX.
+
+Canonical name: ``convert`` (since v0.3.2).
+Deprecated alias: ``v2-convert`` (still accepted).
+
+v2.3.0: Supports reverse conversion HCORTEX → CORTEX via parse_hcortex + encode_cortex_from_ast.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from ...core.errors import CortexError
+from ...v2.parser import parse_cortex_v2
+from ...v2.writer import write_cortex_v2
+from ...v2.view_renderer import render_hcortex
+from ...v2.hcortex_parser import parse_hcortex
+from ...v2.encoder import encode_cortex_from_ast
+
+
+def run(args) -> int:
+    if not os.path.exists(args.input):
+        raise CortexError("E013_NOT_FOUND", f"file not found: {args.input}")
+
+    with open(args.input, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    from_format = args.from_format
+    to_format = args.to_format
+    deprecated_warning = None
+
+    if from_format == "hcortex-r":
+        deprecated_warning = "--from hcortex-r is deprecated. Use --from hcortex."
+        from_format = "hcortex"
+    if to_format == "hcortex-r":
+        deprecated_warning = "--to hcortex-r is deprecated. Use --to hcortex."
+        to_format = "hcortex"
+
+    force_write_on_error = getattr(args, "force_write_on_error", False)
+    strict = getattr(args, "strict", False)
+    mode = getattr(args, "mode", "normal")
+    if strict and mode == "normal":
+        mode = "strict"
+
+    if deprecated_warning:
+        print(f"WARNING: {deprecated_warning}", file=sys.stderr)
+
+    # ---------------------------------------------------------------
+    # CORTEX → HCORTEX
+    # ---------------------------------------------------------------
+    if from_format == "cortex" and to_format == "hcortex":
+        doc = parse_cortex_v2(text)
+        hcortex_md, diags = render_hcortex(doc, mode=mode)
+
+        errors = [d for d in diags if d.severity == "error"]
+        warnings = [d for d in diags if d.severity == "warning"]
+
+        effective_errors = list(errors)
+        if strict:
+            strict_errors = [d for d in warnings if d.code.startswith("W_VIEW_") or d.code == "W_HCORTEX_DISPLAY_ONLY"]
+            effective_errors.extend(strict_errors)
+            warnings = [d for d in warnings if d not in strict_errors]
+
+        has_errors = bool(effective_errors)
+        should_write_out = bool(args.out) and (not has_errors or force_write_on_error)
+
+        if should_write_out:
+            with open(args.out, "w", encoding="utf-8") as f:
+                f.write(hcortex_md)
+            _print_cortex_to_hcortex_summary(args, doc, hcortex_md, effective_errors, warnings)
+            if has_errors:
+                print("  NOTE: --out written despite errors (--force-write-on-error).", file=sys.stderr)
+                return 1
+        elif args.out and has_errors and not force_write_on_error:
+            _print_cortex_to_hcortex_skip(args, doc, hcortex_md, effective_errors, warnings)
+            return 1
+        else:
+            sys.stdout.write(hcortex_md)
+            if has_errors:
+                _print_diags_to_stderr(effective_errors, warnings)
+                return 1
+        return 0
+
+    # ---------------------------------------------------------------
+    # HCORTEX → CORTEX (v2.3.0 F-09)
+    # ---------------------------------------------------------------
+    elif from_format == "hcortex" and to_format == "cortex":
+        hdoc = parse_hcortex(text, strict=strict)
+        doc, enc_diags = encode_cortex_from_ast(hdoc, mode=mode)
+
+        all_diags = list(hdoc.diags) + list(enc_diags)
+        errors = [d for d in all_diags if d.severity == "error"]
+        warnings = [d for d in all_diags if d.severity == "warning"]
+
+        has_errors = bool(errors)
+        should_write_out = bool(args.out) and (not has_errors or force_write_on_error)
+
+        cortex_text = write_cortex_v2(doc)
+
+        if should_write_out:
+            with open(args.out, "w", encoding="utf-8") as f:
+                f.write(cortex_text)
+            print(f"converted HCORTEX → CORTEX: {args.input} → {args.out}")
+            print(f"  sections: {len(doc.sections)}")
+            print(f"  entries:  {sum(len(s.entries) for s in doc.sections)}")
+            print(f"  blocks:   {len(hdoc.blocks)}")
+            print(f"  bytes:    {len(cortex_text.encode('utf-8'))}")
+            print(f"  errors:   {len(errors)}")
+            print(f"  warnings: {len(warnings)}")
+            for d in all_diags[:10]:
+                print(f"    [{d.severity}] {d.code}: {d.message}")
+            if has_errors:
+                print("  NOTE: --out written despite errors (--force-write-on-error).", file=sys.stderr)
+                return 1
+        elif args.out and has_errors and not force_write_on_error:
+            print(f"converted HCORTEX → CORTEX: {args.input} (NOT written — {len(errors)} errors)", file=sys.stderr)
+            print(f"  blocks:   {len(hdoc.blocks)}")
+            print(f"  errors:   {len(errors)}")
+            print(f"  warnings: {len(warnings)}")
+            for d in all_diags[:10]:
+                print(f"    [{d.severity}] {d.code}: {d.message}")
+            print("  Use --force-write-on-error to write --out anyway.", file=sys.stderr)
+            return 1
+        else:
+            sys.stdout.write(cortex_text)
+            if has_errors:
+                print(f"\n<!-- {len(errors)} errors, {len(warnings)} warnings -->", file=sys.stderr)
+                for d in all_diags[:10]:
+                    print(f"  [{d.severity}] {d.code}: {d.message}", file=sys.stderr)
+                return 1
+        return 0
+
+    # ---------------------------------------------------------------
+    # CORTEX → CORTEX (identity / format check)
+    # ---------------------------------------------------------------
+    elif from_format == "cortex" and to_format == "cortex":
+        doc = parse_cortex_v2(text)
+        reproduced = write_cortex_v2(doc)
+        if args.out:
+            with open(args.out, "w", encoding="utf-8") as f:
+                f.write(reproduced)
+        else:
+            sys.stdout.write(reproduced)
+        return 0
+
+    else:
+        raise CortexError("E021_INVALID_VALUE", f"unsupported conversion: {from_format} → {to_format}")
+
+
+def _print_cortex_to_hcortex_summary(args, doc, hcortex_md, errors, warnings):
+    print(f"converted CORTEX → HCORTEX: {args.input} → {args.out}")
+    print(f"  sections: {len(doc.sections)}")
+    print(f"  entries:  {sum(len(s.entries) for s in doc.sections)}")
+    print(f"  bytes:    {len(hcortex_md.encode('utf-8'))}")
+    print(f"  errors:   {len(errors)}")
+    print(f"  warnings: {len(warnings)}")
+    for d in errors[:10]:
+        print(f"    [{d.severity}] {d.code}: {d.message}")
+    for d in warnings[:10]:
+        print(f"    [{d.severity}] {d.code}: {d.message}")
+
+
+def _print_cortex_to_hcortex_skip(args, doc, hcortex_md, errors, warnings):
+    print(f"converted CORTEX → HCORTEX: {args.input} (NOT written — {len(errors)} errors)", file=sys.stderr)
+    print(f"  sections: {len(doc.sections)}")
+    print(f"  entries:  {sum(len(s.entries) for s in doc.sections)}")
+    print(f"  bytes:    {len(hcortex_md.encode('utf-8'))} (would-be)")
+    print(f"  errors:   {len(errors)}")
+    print(f"  warnings: {len(warnings)}")
+    for d in errors[:10]:
+        print(f"    [{d.severity}] {d.code}: {d.message}")
+    for d in warnings[:10]:
+        print(f"    [{d.severity}] {d.code}: {d.message}")
+    print("  Use --force-write-on-error to write --out anyway.", file=sys.stderr)
+
+
+def _print_diags_to_stderr(errors, warnings):
+    print(f"\n<!-- {len(errors)} errors, {len(warnings)} warnings -->", file=sys.stderr)
+    for d in errors[:10]:
+        print(f"  [{d.severity}] {d.code}: {d.message}", file=sys.stderr)
+    for d in warnings[:10]:
+        print(f"  [{d.severity}] {d.code}: {d.message}", file=sys.stderr)

cortex/cli/commands/v2_explain_loss.py

@@ -0,0 +1,97 @@
+"""``cortex explain-loss`` — explain loss, omission, or non-reversible content.
+
+Canonical name: ``explain-loss`` (since v0.3.2).
+Deprecated alias: ``v2-explain-loss`` (still accepted).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from ...core.errors import CortexError
+from ...v2.parser import parse_cortex_v2
+from ...v2.view import parse_view_entries_from_doc, calculate_view_coverage
+from ...v2.view_renderer import render_hcortex
+from ...v2.hcortex_parser import parse_hcortex
+from ...v2.encoder import encode_cortex_from_ast
+from ...v2.equivalence import compare_ast_equivalent
+
+
+def run(args) -> int:
+    if not os.path.exists(args.input):
+        raise CortexError("E013_NOT_FOUND", f"file not found: {args.input}")
+
+    with open(args.input, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    is_hcortex = "internal_encoding: HCORTEX" in text
+
+    losses = []
+
+    if not is_hcortex:
+        # CORTEX input: explain what would be lost in CORTEX → HCORTEX → CORTEX
+        doc_orig = parse_cortex_v2(text)
+        hcortex_md, _ = render_hcortex(doc_orig)
+        hdoc = parse_hcortex(hcortex_md, strict=False)
+        doc_reconstructed, _ = encode_cortex_from_ast(hdoc)
+
+        ast_eq, diffs = compare_ast_equivalent(doc_orig, doc_reconstructed)
+        if not ast_eq:
+            losses.append({
+                "direction": "CORTEX → HCORTEX → CORTEX",
+                "type": "AST-equivalence fail",
+                "diff_count": len(diffs),
+                "diffs": [d.to_dict() for d in diffs[:10]],
+            })
+
+        # Check VIEW coverage
+        directives, _ = parse_view_entries_from_doc(doc_orig)
+        coverage, uncovered = calculate_view_coverage(doc_orig, directives)
+        if coverage < 1.0:
+            losses.append({
+                "direction": "CORTEX → HCORTEX",
+                "type": "incomplete VIEW coverage",
+                "coverage_percent": int(coverage * 100),
+                "uncovered_count": len(uncovered),
+                "uncovered": uncovered[:10],
+            })
+    else:
+        # HCORTEX input
+        hdoc = parse_hcortex(text, strict=False)
+        losses.append({
+            "direction": "HCORTEX parse",
+            "type": "diagnostics",
+            "diag_count": len(hdoc.diags),
+            "diags": [d.to_dict() for d in hdoc.diags[:10]],
+        })
+        if hdoc.orphan_content:
+            losses.append({
+                "direction": "HCORTEX parse",
+                "type": "orphan content (outside VIEW)",
+                "line_count": len(hdoc.orphan_content),
+                "sample": hdoc.orphan_content[:5],
+            })
+
+    result = {
+        "input": args.input,
+        "format": "HCORTEX" if is_hcortex else "CORTEX",
+        "loss_count": len(losses),
+        "losses": losses,
+    }
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2, ensure_ascii=False, default=str))
+    else:
+        print(f"Input: {args.input} ({result['format']})")
+        print(f"Losses detected: {len(losses)}")
+        for i, loss in enumerate(losses, 1):
+            print(f"\n  Loss {i}: {loss['direction']} — {loss['type']}")
+            if 'diff_count' in loss:
+                print(f"    diff_count: {loss['diff_count']}")
+            if 'coverage_percent' in loss:
+                print(f"    coverage: {loss['coverage_percent']}%")
+            if 'uncovered_count' in loss:
+                print(f"    uncovered: {loss['uncovered_count']} entries")
+
+    return 0 if not losses else 1

cortex/cli/commands/v2_inspect.py

@@ -0,0 +1,113 @@
+"""``cortex inspect`` — show AST, sections, sigils, VIEW coverage, errors.
+
+Canonical name: ``inspect`` (since v0.3.2).
+Deprecated alias: ``v2-inspect`` (still accepted).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections import Counter
+
+from ...core.errors import CortexError
+from ...v2.parser import parse_cortex_v2
+from ...v2.view import parse_view_entries_from_doc, calculate_view_coverage
+
+
+def run(args) -> int:
+    if not os.path.exists(args.input):
+        raise CortexError("E013_NOT_FOUND", f"file not found: {args.input}")
+
+    with open(args.input, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    is_hcortex = "internal_encoding: HCORTEX" in text
+
+    if is_hcortex:
+        # For HCORTEX, parse and report blocks
+        from ...v2.hcortex_parser import parse_hcortex
+        hdoc = parse_hcortex(text, strict=False)
+        result = {
+            "format": "HCORTEX",
+            "header": hdoc.header.__dict__,
+            "block_count": len(hdoc.blocks),
+            "orphan_lines": len(hdoc.orphan_content),
+            "diagnostics": [d.to_dict() for d in hdoc.diags],
+            "blocks": [
+                {
+                    "view_name": b.view_name,
+                    "kind": b.kind,
+                    "target": b.target,
+                    "reverse": b.reverse,
+                    "section": b.section,
+                }
+                for b in hdoc.blocks
+            ],
+        }
+    else:
+        doc = parse_cortex_v2(text)
+        directives, diags = parse_view_entries_from_doc(doc)
+        coverage, uncovered = calculate_view_coverage(doc, directives)
+
+        # Sigil distribution
+        sigil_counter: Counter = Counter()
+        for sec in doc.sections:
+            for e in sec.entries:
+                sigil_counter[e.sigil] += 1
+
+        # Entry type distribution
+        type_counter: Counter = Counter()
+        for sec in doc.sections:
+            for e in sec.entries:
+                type_counter[e.entry_type] += 1
+
+        result = {
+            "format": "CORTEX",
+            "header": doc.header,
+            "section_count": len(doc.sections),
+            "entry_count": sum(len(s.entries) for s in doc.sections),
+            "view_count": len(directives),
+            "view_coverage_percent": int(coverage * 100),
+            "uncovered_count": len(uncovered),
+            "reversible": (coverage == 1.0) and not any(d.severity == "error" for d in diags),
+            "sections": [
+                {
+                    "id": s.id,
+                    "entry_count": len(s.entries),
+                }
+                for s in doc.sections
+            ],
+            "sigil_distribution": dict(sigil_counter.most_common()),
+            "entry_type_distribution": dict(type_counter.most_common()),
+            "diagnostics": [d.to_dict() for d in diags[:20]],
+        }
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2, ensure_ascii=False, default=str))
+    else:
+        print(f"Format: {result['format']}")
+        if result['format'] == "CORTEX":
+            print(f"Sections: {result['section_count']}")
+            print(f"Entries: {result['entry_count']}")
+            print(f"VIEW directives: {result['view_count']}")
+            print(f"VIEW coverage: {result['view_coverage_percent']}%")
+            print(f"Reversible: {result['reversible']}")
+            print("\nSections:")
+            for s in result['sections']:
+                print(f"  {s['id']}: {s['entry_count']} entries")
+            print("\nSigil distribution:")
+            for sig, cnt in list(result['sigil_distribution'].items())[:15]:
+                print(f"  {sig}: {cnt}")
+            print("\nEntry type distribution:")
+            for t, cnt in result['entry_type_distribution'].items():
+                print(f"  {t}: {cnt}")
+        else:
+            print(f"Header: reversible={result['header']['reversible']}, view_coverage={result['header']['view_coverage']}")
+            print(f"Blocks: {result['block_count']}")
+            print(f"Orphan lines: {result['orphan_lines']}")
+            print("\nBlocks:")
+            for b in result['blocks']:
+                print(f"  {b['view_name']}: kind={b['kind']}, target={b['target']}, reverse={b['reverse']}")
+
+    return 0

cortex/cli/commands/v2_roundtrip.py

@@ -0,0 +1,104 @@
+"""``cortex roundtrip`` — verify CORTEX v2 roundtrip fidelity.
+
+Canonical name: ``roundtrip`` (since v0.3.2).
+Deprecated alias: ``v2-roundtrip`` (still accepted).
+
+v2.0.1: compares bytes (not text) using read_bytes(), reports stat bytes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from ...core.errors import CortexError
+from ...v2.parser import parse_cortex_v2
+from ...v2.writer import write_cortex_v2
+
+
+def run(args) -> int:
+    if not os.path.exists(args.input):
+        raise CortexError("E013_NOT_FOUND", f"file not found: {args.input}")
+
+    # v2.0.1: read as BYTES, not text, to catch CRLF and other encoding differences
+    with open(args.input, "rb") as f:
+        original_bytes = f.read()
+
+    # Parse from text (UTF-8 decoded) — the parser works on text
+    text = original_bytes.decode("utf-8")
+    doc = parse_cortex_v2(text)
+    reproduced_text = write_cortex_v2(doc)
+    reproduced_bytes = reproduced_text.encode("utf-8")
+
+    # v2.0.1: compare BYTES, not text
+    stat_bytes = os.path.getsize(args.input)
+    text_chars = len(text)
+    repro_bytes = len(reproduced_bytes)
+
+    if original_bytes == reproduced_bytes:
+        if args.format == "json":
+            print(json.dumps({
+                "ok": True,
+                "input": args.input,
+                "sections": len(doc.sections),
+                "entries": sum(len(s.entries) for s in doc.sections),
+                "stat_bytes": stat_bytes,
+                "text_chars": text_chars,
+                "repro_bytes": repro_bytes,
+                "roundtrip": "byte-identical",
+            }, indent=2))
+        else:
+            print(f"✓ Roundtrip byte-identical: {args.input}")
+            print(f"  sections: {len(doc.sections)}")
+            print(f"  entries:  {sum(len(s.entries) for s in doc.sections)}")
+            print(f"  stat_bytes: {stat_bytes}")
+            print(f"  text_chars: {text_chars}")
+            print(f"  repro_bytes: {repro_bytes}")
+        return 0
+    else:
+        # Find first byte difference
+        diff_offset = -1
+        for i in range(min(len(original_bytes), len(reproduced_bytes))):
+            if original_bytes[i] != reproduced_bytes[i]:
+                diff_offset = i
+                break
+
+        # Also find first text line difference for human readability
+        orig_lines = text.split('\n')
+        repro_lines = reproduced_text.split('\n')
+        diff_line = -1
+        for i in range(min(len(orig_lines), len(repro_lines))):
+            if orig_lines[i] != repro_lines[i]:
+                diff_line = i + 1
+                break
+
+        if args.format == "json":
+            print(json.dumps({
+                "ok": False,
+                "input": args.input,
+                "stat_bytes": stat_bytes,
+                "repro_bytes": repro_bytes,
+                "text_chars": text_chars,
+                "orig_lines": len(orig_lines),
+                "repro_lines": len(repro_lines),
+                "first_byte_diff": diff_offset,
+                "first_line_diff": diff_line,
+                "orig_excerpt": orig_lines[diff_line - 1][:120] if diff_line > 0 else "",
+                "repro_excerpt": repro_lines[diff_line - 1][:120] if diff_line > 0 else "",
+            }, indent=2))
+        else:
+            print(f"✗ Roundtrip FAILED: {args.input}")
+            print(f"  stat_bytes: {stat_bytes}")
+            print(f"  repro_bytes: {repro_bytes}")
+            print(f"  text_chars: {text_chars}")
+            print(f"  orig_lines: {len(orig_lines)}")
+            print(f"  repro_lines: {len(repro_lines)}")
+            if diff_byte := diff_offset:
+                print(f"  first byte diff at offset {diff_byte}:")
+                print(f"    orig:  0x{original_bytes[diff_byte]:02x}")
+                print(f"    repro: 0x{reproduced_bytes[diff_byte]:02x}")
+            if diff_line > 0:
+                print(f"  first line diff at line {diff_line}:")
+                print(f"    orig:  {orig_lines[diff_line - 1][:120]!r}")
+                print(f"    repro: {repro_lines[diff_line - 1][:120]!r}")
+        return 1