Merge pull request #121 from codellm-devkit/fix/issue-118-119-emit-gates

feat(cli)!: drop msgpack output; enforce --emit neo4j full-depth contract

Author: rahlk

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **BREAKING: the msgpack output format is removed** (#118, TS parity): the
+  `--format msgpack` CLI choice, the `analysis.msgpack` artifact, the msgpack
+  serialization mixin on schema models, and the `msgpack` dependency are gone.
+  `analysis.json` is the single wire format; anyone passing `--format msgpack`
+  must drop the flag. `--format json` still works unchanged.
+- **`--emit neo4j` now enforces its always-full-depth contract** (#119): it
+  runs at level 4 with every graph section regardless of defaults, and
+  explicitly passing `-a`/`--graphs` alongside it is now the documented
+  explicit error (previously accepted silently — and worse, the emission
+  actually ran at the default level 1, producing a partial graph). Passing
+  `--graphs` below `-a 3` is also now consistently rejected even when the
+  value equals the default.
+
 ## [1.1.1] - 2026-07-27
 
 ### Fixed

CLAUDE.md

@@ -135,8 +135,8 @@ declared callables by their `can://` tree id, imported/builtin targets by a
 
 ### Two projections
 
-1. **`analysis.json`** — the tree itself (the `Analysis` envelope above), also
-   available as gzip'd msgpack.
+1. **`analysis.json`** — the tree itself (the `Analysis` envelope above); the
+   single wire format (the msgpack variant was removed in 1.2.0, #118).
 2. **Neo4j** (`codeanalyzer/neo4j/`) — a near-identity projection, keyed on the
    same `can://` / global ordinal ids: containment → typed `PY_HAS_*` /
    `PY_DECLARES` edges (`PY_HAS_MODULE`, `PY_DECLARES`, `PY_HAS_METHOD`,

README.md

@@ -70,7 +70,7 @@ needs.
   checked in as `schema.neo4j.json` (`2.0.0`) and shipped with every release.
 - **Incremental cache** — per-file results are cached under `.codeanalyzer`; `--lazy` (default)
   reuses them, `--eager` forces a clean rebuild. `--ray` distributes the work across cores.
-- **Compact output** — canonical `analysis.json`, or binary `analysis.msgpack` for smaller artifacts.
+- **Compact output** — one canonical `analysis.json` per run.
 
 ## Installation
 
@@ -143,8 +143,7 @@ canpy --input /path/to/python/project
 ```
 
 With no `--output`, the analysis is printed to stdout as compact JSON; with `--output <dir>` it is
-written to `analysis.json` (or `graph.cypher` for `--emit neo4j`, or `analysis.msgpack` with
-`--format msgpack`) in that directory.
+written to `analysis.json` (or `graph.cypher` for `--emit neo4j`) in that directory.
 
 ### Options
 

codeanalyzer/__main__.py

@@ -85,7 +85,7 @@ def main(
         typer.Option(
             "-f",
             "--format",
-            help="Output format for --emit json: json or msgpack.",
+            help="Output format for --emit json: json.",
             case_sensitive=False,
         ),
     ] = OutputFormat.JSON,
@@ -141,26 +141,31 @@ def main(
         ),
     ] = None,
     analysis_level: Annotated[
-        int,
+        Optional[int],
         typer.Option(
             "-a",
             "--analysis-level",
             help="Analysis depth: 1=symbol table+Jedi call graph, 2=+PyCG call "
             "graph, 3=+native intraprocedural dataflow (CFG/PDG), "
-            "4=+interprocedural SDG (param/summary edges, alias-aware DDG).",
+            "4=+interprocedural SDG (param/summary edges, alias-aware DDG). "
+            "[default: 1; incompatible with --emit neo4j, which is always "
+            "full-depth]",
             min=1,
             max=4,
+            show_default="1",
         ),
-    ] = 1,
+    ] = None,
     graphs: Annotated[
-        str,
+        Optional[str],
         typer.Option(
             "--graphs",
             help="Level 3+ only: comma-separated program-graph sections to emit "
             "(cfg, dfg, pdg, sdg). Default: cfg,dfg,pdg. `dfg` emits the PDG's data "
-            "edges only; `sdg` requires -a 4.",
+            "edges only; `sdg` requires -a 4. Incompatible with --emit neo4j "
+            "(always full-depth).",
+            show_default="cfg,dfg,pdg",
         ),
-    ] = "cfg,dfg,pdg",
+    ] = None,
     graph_field_depth: Annotated[
         int,
         typer.Option(
@@ -300,9 +305,40 @@ def main(
     _pin_hash_seed()
 
     # Flag validation (strict: unrecognized values error out, never fall back).
-    selected_graphs = [g.strip() for g in graphs.split(",") if g.strip()]
+    # -a and --graphs use None sentinels so an explicitly-passed flag is
+    # distinguishable from the default (#119).
+    explicit_level = analysis_level is not None
+    explicit_graphs = graphs is not None
+
+    # Neo4j is always full-depth (#119): the graph carries every level's
+    # facts, so depth/section selectors cannot be combined with it — reject
+    # explicitly-passed flags and force level 4 with every graph section.
     from codeanalyzer.dataflow.builder import VALID_GRAPHS
 
+    if emit == EmitTarget.NEO4J:
+        explicit = [
+            flag
+            for flag, was_explicit in (
+                ("-a/--analysis-level", explicit_level),
+                ("--graphs", explicit_graphs),
+            )
+            if was_explicit
+        ]
+        if explicit:
+            logger.error(
+                "--emit neo4j is always full-depth (level 4, all graph "
+                f"sections); {' and '.join(explicit)} cannot be combined with it."
+            )
+            raise typer.Exit(code=2)
+        analysis_level = 4
+        graphs = ",".join(VALID_GRAPHS)
+
+    if analysis_level is None:
+        analysis_level = 1
+    if graphs is None:
+        graphs = "cfg,dfg,pdg"
+    selected_graphs = [g.strip() for g in graphs.split(",") if g.strip()]
+
     unknown_graphs = [g for g in selected_graphs if g not in VALID_GRAPHS]
     if unknown_graphs:
         logger.error(
@@ -316,7 +352,7 @@ def main(
     if "sdg" in selected_graphs and analysis_level < 4:
         logger.error("--graphs sdg requires -a 4 (interprocedural SDG).")
         raise typer.Exit(code=2)
-    if analysis_level < 3 and graphs != "cfg,dfg,pdg":
+    if analysis_level < 3 and explicit_graphs:
         logger.error("--graphs is a level-3 option; pass -a 3 to emit program graphs.")
         raise typer.Exit(code=2)
     if analysis_level < 3 and graph_field_depth != 3:
@@ -408,16 +444,6 @@ def _write_output(artifacts, output_dir: Path, format: OutputFormat):
             f.write(json_str)
         logger.info(f"Analysis saved to {output_file}")
 
-    elif format == OutputFormat.MSGPACK:
-        output_file = output_dir / "analysis.msgpack"
-        msgpack_data = artifacts.to_msgpack_bytes()
-        with output_file.open("wb") as f:
-            f.write(msgpack_data)
-        logger.info(f"Analysis saved to {output_file}")
-        logger.info(
-            f"Compression ratio: {artifacts.get_compression_ratio():.1%} of JSON size"
-        )
-
 
 app = typer.Typer(
     callback=main,

codeanalyzer/config/config.py

@@ -5,4 +5,3 @@ class OutputFormat(str, Enum):
     """String-based enum for output formats to support typer case-insensitive options."""
 
     JSON = "json"
-    MSGPACK = "msgpack"

codeanalyzer/options/options.py

@@ -6,7 +6,6 @@
 
 class OutputFormat(str, Enum):
     JSON = "json"
-    MSGPACK = "msgpack"
 
 
 class EmitTarget(str, Enum):