codeanalyzer-python 1.0.0__tar.gz → 1.0.2__tar.gz

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeanalyzer-python
-Version: 1.0.0
+Version: 1.0.2
 Summary: Static analysis for Python — canonical schema v2 (symbol table, call graph, and native CFG/PDG/SDG dataflow) as analysis.json or a Neo4j property graph.
 Author-email: Rahul Krishna <i.m.ralk@gmail.com>
 License-File: LICENSE
@@ -203,19 +203,19 @@ $ canpy --help
 │ --version                                                   Show the canpy   │
 │                                                             version and      │
 │                                                             exit.            │
-│ --input            -i                     PATH              Path to the      │
+│ --input            -i                     <path>            Path to the      │
 │                                                             project root     │
 │                                                             directory (not   │
 │                                                             required for     │
 │                                                             --emit schema).  │
-│ --output           -o                     PATH              Output directory │
+│ --output           -o                     <path>            Output directory │
 │                                                             for artifacts.   │
-│ --format           -f                     [json|msgpack]    Output format    │
+│ --format           -f                     <json|msgpack>    Output format    │
 │                                                             for --emit json: │
 │                                                             json or msgpack. │
 │                                                             [default: json]  │
-│ --emit                                    [json|neo4j|sche  Output target:   │
-│                                           ma]               json             │
+│ --emit                                    <json|neo4j|sche  Output target:   │
+│                                           ma>               json             │
 │                                                             (analysis.json,  │
 │                                                             default) | neo4j │
 │                                                             (graph.cypher or │
@@ -225,13 +225,13 @@ $ canpy --help
 │                                                             schema.json      │
 │                                                             contract).       │
 │                                                             [default: json]  │
-│ --app-name                                TEXT              Logical          │
+│ --app-name                                <str>             Logical          │
 │                                                             application name │
 │                                                             for the graph    │
 │                                                             :PyApplication   │
 │                                                             anchor (default: │
 │                                                             input dir name). │
-│ --neo4j-uri                               TEXT              Push the graph   │
+│ --neo4j-uri                               <str>             Push the graph   │
 │                                                             to a live Neo4j  │
 │                                                             over Bolt        │
 │                                                             (incremental);   │
@@ -239,11 +239,11 @@ $ canpy --help
 │                                                             graph.cypher.    │
 │                                                             [env var:        │
 │                                                             NEO4J_URI]       │
-│ --neo4j-user                              TEXT              Neo4j username.  │
+│ --neo4j-user                              <str>             Neo4j username.  │
 │                                                             [env var:        │
 │                                                             NEO4J_USERNAME]  │
 │                                                             [default: neo4j] │
-│ --neo4j-password                          TEXT              Neo4j password.  │
+│ --neo4j-password                          <str>             Neo4j password.  │
 │                                                             Prefer the env   │
 │                                                             var over the     │
 │                                                             flag (the flag   │
@@ -253,12 +253,12 @@ $ canpy --help
 │                                                             [env var:        │
 │                                                             NEO4J_PASSWORD]  │
 │                                                             [default: neo4j] │
-│ --neo4j-database                          TEXT              Neo4j database   │
+│ --neo4j-database                          <str>             Neo4j database   │
 │                                                             name (default:   │
 │                                                             server default). │
 │                                                             [env var:        │
 │                                                             NEO4J_DATABASE]  │
-│ --analysis-level   -a                     INTEGER RANGE     Analysis depth:  │
+│ --analysis-level   -a                     <int range>       Analysis depth:  │
 │                                           [1<=x<=4]         1=symbol         │
 │                                                             table+Jedi call  │
 │                                                             graph, 2=+PyCG   │
@@ -274,7 +274,7 @@ $ canpy --help
 │                                                             alias-aware      │
 │                                                             DDG).            │
 │                                                             [default: 1]     │
-│ --graphs                                  TEXT              Level 3+ only:   │
+│ --graphs                                  <str>             Level 3+ only:   │
 │                                                             comma-separated  │
 │                                                             program-graph    │
 │                                                             sections to emit │
@@ -287,7 +287,7 @@ $ canpy --help
 │                                                             requires -a 4.   │
 │                                                             [default:        │
 │                                                             cfg,dfg,pdg]     │
-│ --graph-field-de…                         INTEGER RANGE     Level 3 only:    │
+│ --graph-field-de…                         <int range>       Level 3 only:    │
 │                                           [x>=1]            k-limit on       │
 │                                                             access-path      │
 │                                                             depth (x.f.g.h   │
@@ -324,12 +324,12 @@ $ canpy --help
 │                                                             environment      │
 │                                                             instead.         │
 │                                                             [default: venv]  │
-│ --file-name                               PATH              Analyze only the │
+│ --file-name                               <path>            Analyze only the │
 │                                                             specified file   │
 │                                                             (relative to     │
 │                                                             input            │
 │                                                             directory).      │
-│ --cache-dir        -c                     PATH              Directory to     │
+│ --cache-dir        -c                     <path>            Directory to     │
 │                                                             store analysis   │
 │                                                             cache. Defaults  │
 │                                                             to               │
@@ -343,7 +343,7 @@ $ canpy --help
 │                                                             retained.        │
 │                                                             [default:        │
 │                                                             keep-cache]      │
-│                    -v                     INTEGER           Increase         │
+│                    -v                     <int>             Increase         │
 │                                                             verbosity: -v,   │
 │                                                             -vv, -vvv        │
 │                                                             [default: 0]     │
@@ -370,7 +370,7 @@ $ canpy --help
 │                                                             Jedi-only edges. │
 │                                                             [default:        │
 │                                                             no-pycg-shard]   │
-│ --pycg-shard-cei…                         INTEGER RANGE     Maximum files    │
+│ --pycg-shard-cei…                         <int range>       Maximum files    │
 │                                           [x>=1]            per shard when   │
 │                                                             --pycg-shard is  │
 │                                                             active (default  │
@@ -392,7 +392,7 @@ $ canpy --help
 │                                                             heavy import     │
 │                                                             graphs.          │
 │                                                             [default: 100]   │
-│ --pycg-shard-tim…                         INTEGER RANGE     Per-shard        │
+│ --pycg-shard-tim…                         <int range>       Per-shard        │
 │                                           [x>=0]            wall-clock       │
 │                                                             timeout in       │
 │                                                             seconds when     │
@@ -420,7 +420,7 @@ $ canpy --help
 │                                                             ignored on       │
 │                                                             Windows.         │
 │                                                             [default: 120]   │
-│ --pycg-shard-str…                         [jedi|package]    How --pycg-shard │
+│ --pycg-shard-str…                         <jedi|package>    How --pycg-shard │
 │                                                             groups files     │
 │                                                             (level 2 only).  │
 │                                                             'jedi' (default) │
@@ -442,7 +442,7 @@ $ canpy --help
 │                                                             one-shard-per-p… │
 │                                                             grouping.        │
 │                                                             [default: jedi]  │
-│ --pycg-max-iter                           INTEGER RANGE     Cap on PyCG's    │
+│ --pycg-max-iter                           <int range>       Cap on PyCG's    │
 │                                           [x>=-1]           fixpoint passes  │
 │                                                             per              │
 │                                                             shard/project    │

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/README.md

@@ -164,19 +164,19 @@ $ canpy --help
 │ --version                                                   Show the canpy   │
 │                                                             version and      │
 │                                                             exit.            │
-│ --input            -i                     PATH              Path to the      │
+│ --input            -i                     <path>            Path to the      │
 │                                                             project root     │
 │                                                             directory (not   │
 │                                                             required for     │
 │                                                             --emit schema).  │
-│ --output           -o                     PATH              Output directory │
+│ --output           -o                     <path>            Output directory │
 │                                                             for artifacts.   │
-│ --format           -f                     [json|msgpack]    Output format    │
+│ --format           -f                     <json|msgpack>    Output format    │
 │                                                             for --emit json: │
 │                                                             json or msgpack. │
 │                                                             [default: json]  │
-│ --emit                                    [json|neo4j|sche  Output target:   │
-│                                           ma]               json             │
+│ --emit                                    <json|neo4j|sche  Output target:   │
+│                                           ma>               json             │
 │                                                             (analysis.json,  │
 │                                                             default) | neo4j │
 │                                                             (graph.cypher or │
@@ -186,13 +186,13 @@ $ canpy --help
 │                                                             schema.json      │
 │                                                             contract).       │
 │                                                             [default: json]  │
-│ --app-name                                TEXT              Logical          │
+│ --app-name                                <str>             Logical          │
 │                                                             application name │
 │                                                             for the graph    │
 │                                                             :PyApplication   │
 │                                                             anchor (default: │
 │                                                             input dir name). │
-│ --neo4j-uri                               TEXT              Push the graph   │
+│ --neo4j-uri                               <str>             Push the graph   │
 │                                                             to a live Neo4j  │
 │                                                             over Bolt        │
 │                                                             (incremental);   │
@@ -200,11 +200,11 @@ $ canpy --help
 │                                                             graph.cypher.    │
 │                                                             [env var:        │
 │                                                             NEO4J_URI]       │
-│ --neo4j-user                              TEXT              Neo4j username.  │
+│ --neo4j-user                              <str>             Neo4j username.  │
 │                                                             [env var:        │
 │                                                             NEO4J_USERNAME]  │
 │                                                             [default: neo4j] │
-│ --neo4j-password                          TEXT              Neo4j password.  │
+│ --neo4j-password                          <str>             Neo4j password.  │
 │                                                             Prefer the env   │
 │                                                             var over the     │
 │                                                             flag (the flag   │
@@ -214,12 +214,12 @@ $ canpy --help
 │                                                             [env var:        │
 │                                                             NEO4J_PASSWORD]  │
 │                                                             [default: neo4j] │
-│ --neo4j-database                          TEXT              Neo4j database   │
+│ --neo4j-database                          <str>             Neo4j database   │
 │                                                             name (default:   │
 │                                                             server default). │
 │                                                             [env var:        │
 │                                                             NEO4J_DATABASE]  │
-│ --analysis-level   -a                     INTEGER RANGE     Analysis depth:  │
+│ --analysis-level   -a                     <int range>       Analysis depth:  │
 │                                           [1<=x<=4]         1=symbol         │
 │                                                             table+Jedi call  │
 │                                                             graph, 2=+PyCG   │
@@ -235,7 +235,7 @@ $ canpy --help
 │                                                             alias-aware      │
 │                                                             DDG).            │
 │                                                             [default: 1]     │
-│ --graphs                                  TEXT              Level 3+ only:   │
+│ --graphs                                  <str>             Level 3+ only:   │
 │                                                             comma-separated  │
 │                                                             program-graph    │
 │                                                             sections to emit │
@@ -248,7 +248,7 @@ $ canpy --help
 │                                                             requires -a 4.   │
 │                                                             [default:        │
 │                                                             cfg,dfg,pdg]     │
-│ --graph-field-de…                         INTEGER RANGE     Level 3 only:    │
+│ --graph-field-de…                         <int range>       Level 3 only:    │
 │                                           [x>=1]            k-limit on       │
 │                                                             access-path      │
 │                                                             depth (x.f.g.h   │
@@ -285,12 +285,12 @@ $ canpy --help
 │                                                             environment      │
 │                                                             instead.         │
 │                                                             [default: venv]  │
-│ --file-name                               PATH              Analyze only the │
+│ --file-name                               <path>            Analyze only the │
 │                                                             specified file   │
 │                                                             (relative to     │
 │                                                             input            │
 │                                                             directory).      │
-│ --cache-dir        -c                     PATH              Directory to     │
+│ --cache-dir        -c                     <path>            Directory to     │
 │                                                             store analysis   │
 │                                                             cache. Defaults  │
 │                                                             to               │
@@ -304,7 +304,7 @@ $ canpy --help
 │                                                             retained.        │
 │                                                             [default:        │
 │                                                             keep-cache]      │
-│                    -v                     INTEGER           Increase         │
+│                    -v                     <int>             Increase         │
 │                                                             verbosity: -v,   │
 │                                                             -vv, -vvv        │
 │                                                             [default: 0]     │
@@ -331,7 +331,7 @@ $ canpy --help
 │                                                             Jedi-only edges. │
 │                                                             [default:        │
 │                                                             no-pycg-shard]   │
-│ --pycg-shard-cei…                         INTEGER RANGE     Maximum files    │
+│ --pycg-shard-cei…                         <int range>       Maximum files    │
 │                                           [x>=1]            per shard when   │
 │                                                             --pycg-shard is  │
 │                                                             active (default  │
@@ -353,7 +353,7 @@ $ canpy --help
 │                                                             heavy import     │
 │                                                             graphs.          │
 │                                                             [default: 100]   │
-│ --pycg-shard-tim…                         INTEGER RANGE     Per-shard        │
+│ --pycg-shard-tim…                         <int range>       Per-shard        │
 │                                           [x>=0]            wall-clock       │
 │                                                             timeout in       │
 │                                                             seconds when     │
@@ -381,7 +381,7 @@ $ canpy --help
 │                                                             ignored on       │
 │                                                             Windows.         │
 │                                                             [default: 120]   │
-│ --pycg-shard-str…                         [jedi|package]    How --pycg-shard │
+│ --pycg-shard-str…                         <jedi|package>    How --pycg-shard │
 │                                                             groups files     │
 │                                                             (level 2 only).  │
 │                                                             'jedi' (default) │
@@ -403,7 +403,7 @@ $ canpy --help
 │                                                             one-shard-per-p… │
 │                                                             grouping.        │
 │                                                             [default: jedi]  │
-│ --pycg-max-iter                           INTEGER RANGE     Cap on PyCG's    │
+│ --pycg-max-iter                           <int range>       Cap on PyCG's    │
 │                                           [x>=-1]           fixpoint passes  │
 │                                                             per              │
 │                                                             shard/project    │

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/codeanalyzer/__main__.py

@@ -1,9 +1,40 @@
+import os
+import sys
 from importlib.metadata import version as _pkg_version, PackageNotFoundError
 from pathlib import Path
 from typing import Optional, Annotated
 
 import typer
 
+
+def _pin_hash_seed() -> None:
+    """Re-exec once with ``PYTHONHASHSEED=0`` unless the caller pinned one.
+
+    PyCG's capped fixpoint (``--pycg-max-iter``) iterates hash-ordered sets
+    keyed on module/access-path strings, so an unpinned per-interpreter hash
+    seed makes the emitted L2+ call graph vary run to run (issue #99). The
+    seed cannot be set after interpreter start, hence the exec. Export
+    PYTHONHASHSEED (any value) to opt out or pin a different seed.
+
+    Only fires when this process really is the CLI (canpy / python -m
+    codeanalyzer): in-process invocations — e.g. Typer's CliRunner in the
+    test suite, or a host app calling the callback — must never have their
+    own process exec'd out from under them."""
+    if os.environ.get("PYTHONHASHSEED") is not None:
+        return
+    argv0 = os.path.basename(sys.argv[0]) if sys.argv else ""
+    is_cli = argv0 in ("canpy", "codeanalyzer") or sys.argv[0].endswith(
+        os.path.join("codeanalyzer", "__main__.py")
+    )
+    if not is_cli:
+        return
+    env = dict(os.environ, PYTHONHASHSEED="0")
+    os.execvpe(
+        sys.executable,
+        [sys.executable, "-m", "codeanalyzer", *sys.argv[1:]],
+        env,
+    )
+
 from codeanalyzer.core import Codeanalyzer
 from codeanalyzer.utils import _set_log_level, logger
 from codeanalyzer.config import OutputFormat
@@ -264,6 +295,10 @@ def main(
         ),
     ] = 50,
 ):
+    # Determinism: pin the interpreter hash seed before any analysis (no-op
+    # when PYTHONHASHSEED is already set; --version exits before this).
+    _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()]
     from codeanalyzer.dataflow.builder import VALID_GRAPHS

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/codeanalyzer/core.py

@@ -37,6 +37,22 @@ from codeanalyzer.utils import ProgressBar
 from codeanalyzer.options import AnalysisOptions
 from codeanalyzer.provenance import analyzer_info, repository_info
 
+def _ensure_ray() -> None:
+    """Initialize Ray with the driver's pinned hash seed in the workers.
+
+    An implicit auto-init would not carry PYTHONHASHSEED into worker
+    interpreters, so PyCG shards (and Jedi inference) run there with random
+    set-iteration order and the emitted edges vary run to run (issue #99)."""
+    if not ray.is_initialized():
+        ray.init(
+            runtime_env={
+                "env_vars": {
+                    "PYTHONHASHSEED": os.environ.get("PYTHONHASHSEED", "0")
+                }
+            },
+        )
+
+
 @ray.remote
 def _process_file_with_ray(py_file: Union[Path, str], project_dir: Union[Path, str], virtualenv: Union[Path, str, None]) -> Dict[str, PyModule]:
     """Processes files in the project directory using Ray for distributed processing.
@@ -438,6 +454,11 @@ class Codeanalyzer:
             call_graph = merge_edges(call_graph, pycg_edges)
 
         call_graph = filter_external_edges(call_graph, symbol_table)
+        # Canonical edge order: backend iteration order (PyCG dicts, Counter
+        # insertion) is not a contract — sort so identical edge SETS always
+        # serialize identically (issue #99 determinism gate), and so the
+        # external-symbol homing below assigns ids in a stable order.
+        call_graph.sort(key=lambda e: (e.src, e.dst))
 
         # Recreate pyapplication
         app = (
@@ -716,6 +737,7 @@ class Codeanalyzer:
             
             # Process only new/changed files with Ray
             if files_to_process:
+                _ensure_ray()
                 futures = [_process_file_with_ray.remote(py_file, self.project_dir, str(self.virtualenv) if self.virtualenv else None) for py_file in files_to_process]
                 
                 with ProgressBar(len(futures), "Building symbol table (parallel)") as progress:

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/codeanalyzer/neo4j/project.py

@@ -290,9 +290,11 @@ def _project_module_body(
     externals: dict, sig_to_id: dict, module_id_by_key: dict,
 ) -> None:
     for fn in (mod.functions or {}).values():
-        _project_callable(b, file_key, mod_ref, "PY_DECLARES", fn, externals, sig_to_id)
+        _project_callable(b, file_key, mod_ref, "PY_DECLARES", fn, externals, sig_to_id,
+                          mod.source)
     for cl in (mod.types or {}).values():
-        _project_class(b, file_key, mod_ref, "PY_DECLARES", cl, externals, sig_to_id)
+        _project_class(b, file_key, mod_ref, "PY_DECLARES", cl, externals, sig_to_id,
+                       mod.source)
     for v in mod.variables or []:
         _project_variable(b, file_key, mod_ref, file_key, v)
     _project_imports(b, mod_ref, mod, module_id_by_key)
@@ -360,10 +362,10 @@ def _project_imports(b: RowBuilder, mod_ref: NodeRef, mod: PyModule,
 
 def _project_class(
     b: RowBuilder, file_key: str, parent: NodeRef, parent_rel: str, cl: PyClass,
-    externals: dict, sig_to_id: dict,
+    externals: dict, sig_to_id: dict, source: str,
 ) -> None:
     ref = b.node(
-        ["PySymbol", "PyClass"], "id", cl.id, _class_props(cl, file_key)
+        ["PySymbol", "PyClass"], "id", cl.id, _class_props(cl, file_key, source)
     )
     b.edge(parent_rel, parent, ref)
 
@@ -372,22 +374,23 @@ def _project_class(
             b.edge_to_symbol("PY_EXTENDS", ref, _symbol_ref(base, externals, sig_to_id))
 
     for m in (cl.callables or {}).values():
-        _project_callable(b, file_key, ref, "PY_HAS_METHOD", m, externals, sig_to_id)
+        _project_callable(b, file_key, ref, "PY_HAS_METHOD", m, externals, sig_to_id,
+                          source)
     for a in (cl.attributes or {}).values():
         _project_attribute(b, file_key, ref, cl.signature, a)
     for ic in (cl.types or {}).values():
-        _project_class(b, file_key, ref, "PY_DECLARES", ic, externals, sig_to_id)
+        _project_class(b, file_key, ref, "PY_DECLARES", ic, externals, sig_to_id, source)
 
 
 def _project_callable(
     b: RowBuilder, file_key: str, owner: NodeRef, owner_rel: str, c: PyCallable,
-    externals: dict, sig_to_id: dict,
+    externals: dict, sig_to_id: dict, source: str,
 ) -> None:
     ref = b.node(
         ["PySymbol", "PyCallable"],
         "id",
         c.id,
-        _callable_props(c, file_key),
+        _callable_props(c, file_key, source),
     )
     b.edge(owner_rel, owner, ref)
 
@@ -410,9 +413,10 @@ def _project_callable(
     for v in c.local_variables or []:
         _project_variable(b, file_key, ref, c.signature, v)
     for ic in (c.callables or {}).values():
-        _project_callable(b, file_key, ref, "PY_DECLARES", ic, externals, sig_to_id)
+        _project_callable(b, file_key, ref, "PY_DECLARES", ic, externals, sig_to_id,
+                          source)
     for cl in (c.types or {}).values():
-        _project_class(b, file_key, ref, "PY_DECLARES", cl, externals, sig_to_id)
+        _project_class(b, file_key, ref, "PY_DECLARES", cl, externals, sig_to_id, source)
 
 
 def _project_attribute(
@@ -459,13 +463,24 @@ def _module_props(mod: PyModule, file_key: str) -> Props:
     )
 
 
-def _class_props(cl: PyClass, file_key: str) -> Props:
+def _span_code(source: str, span) -> str | None:
+    """A declaration's text: the owning module's ``source`` sliced by the node's
+    utf-8 byte span. Schema v2 stores source once per module, so the graph's
+    ``code`` property (declared on :PyClass/:PyCallable and indexed by
+    ``py_code_fts``) is derived here at projection time (#104)."""
+    if span is None or not source:
+        return None
+    lo, hi = span.bytes
+    return source.encode("utf-8")[lo:hi].decode("utf-8")
+
+
+def _class_props(cl: PyClass, file_key: str, source: str) -> Props:
     return prune(
         {
             "id": cl.id,
             "signature": cl.signature,
             "name": cl.name,
-            "code": getattr(cl, "code", None),
+            "code": _span_code(source, cl.span),
             "base_classes": list(cl.base_classes or []),
             "docstring": _docstring_of(cl.comments),
             "start_line": cl.start_line,
@@ -475,7 +490,7 @@ def _class_props(cl: PyClass, file_key: str) -> Props:
     )
 
 
-def _callable_props(c: PyCallable, file_key: str) -> Props:
+def _callable_props(c: PyCallable, file_key: str, source: str) -> Props:
     return prune(
         {
             "id": c.id,
@@ -484,7 +499,7 @@ def _callable_props(c: PyCallable, file_key: str) -> Props:
             "path": c.path,
             "return_type": c.return_type,
             "cyclomatic_complexity": c.cyclomatic_complexity,
-            "code": getattr(c, "code", None),
+            "code": _span_code(source, c.span),
             "code_start_line": c.code_start_line,
             "start_line": c.start_line,
             "end_line": c.end_line,

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/codeanalyzer/semantic_analysis/pycg/pycg_analysis.py

@@ -39,9 +39,12 @@ project-relative dotted paths so they align with the symbol table.
 # re-enters PyCG's hook before its import graph is ready.  Pre-importing
 # these modules at import time ensures they're already in sys.modules when
 # PyCG's hook is active, preventing the re-entrant ImportManagerError.
+import fcntl
+import hashlib
 import importlib.metadata  # noqa: F401
 import importlib.util  # noqa: F401
 import contextlib
+import os
 import json  # noqa: F401
 import shutil
 import signal
@@ -85,6 +88,15 @@ from codeanalyzer.semantic_analysis.pycg.shard_planner import plan_shards
 from codeanalyzer.utils import ProgressBar, logger
 
 
+def _shard_root_path(files: List[str], project_dir: Path) -> Path:
+    """Content-derived mini-project root for a shard: same project + same file
+    set → same path on every run (determinism, issue #99)."""
+    digest = hashlib.sha1(
+        "\0".join([str(project_dir), *sorted(files)]).encode("utf-8")
+    ).hexdigest()[:16]
+    return Path(tempfile.gettempdir()) / f"canpy_pycg_shard_{digest}"
+
+
 def _materialize_shard_root(
     files: List[str],
     project_dir: Path,
@@ -103,10 +115,21 @@ def _materialize_shard_root(
 
     The caller owns the returned *root* and must ``shutil.rmtree`` it.
     """
-    root = Path(tempfile.mkdtemp(prefix="canpy_pycg_shard_"))
+    # Deterministic root: PyCG's capped fixpoint (--pycg-max-iter) is
+    # order-sensitive, and its internal state keys on absolute module paths —
+    # a random mkdtemp suffix changes those strings every run and shifts the
+    # iteration frontier, making the emitted edge set vary run-to-run
+    # (issue #99). Deriving the directory name from the shard's content keeps
+    # the path (and thus the analysis input) identical across runs. Callers
+    # that may run concurrently on the same shard serialize on the sidecar
+    # lock (see _shard_symlink_root).
+    root = _shard_root_path(files, project_dir)
+    if root.exists():
+        shutil.rmtree(root, ignore_errors=True)
+    root.mkdir(parents=True, exist_ok=True)
     entry_points: List[str] = []
     linked_inits: Set[Path] = set()
-    for f in files:
+    for f in sorted(files):
         src = Path(f).resolve()
         try:
             rel = src.relative_to(project_dir)
@@ -142,12 +165,27 @@ def _shard_symlink_root(
     """Context-manager wrapper around :func:`_materialize_shard_root`.
 
     Yields ``(root, entry_points)`` and removes the temp tree on exit.
+
+    The root path is content-derived (determinism, issue #99), so two
+    concurrent analyses of the same shard — e.g. a test suite and a manual
+    run on one project — would collide on it (one rmtree's the tree the
+    other is mid-analysis on). An exclusive flock on a sidecar lockfile
+    serializes them; distinct projects/shards hash to distinct roots and
+    never contend.
     """
-    root, entry_points = _materialize_shard_root(files, project_dir)
+    digest_root = _shard_root_path(files, project_dir)
+    lock_path = digest_root.with_name(digest_root.name + ".lock")
+    lock_fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR)
     try:
-        yield root, entry_points
+        fcntl.flock(lock_fd, fcntl.LOCK_EX)
+        root, entry_points = _materialize_shard_root(files, project_dir)
+        try:
+            yield root, entry_points
+        finally:
+            shutil.rmtree(root, ignore_errors=True)
     finally:
-        shutil.rmtree(root, ignore_errors=True)
+        fcntl.flock(lock_fd, fcntl.LOCK_UN)
+        os.close(lock_fd)
 
 
 def _pycg_shard_worker(
@@ -469,7 +507,9 @@ class PyCG:
             ):
                 continue
             paths.append(str(p))
-        return paths
+        # Sorted for run-to-run stability: rglob yields filesystem order, and
+        # PyCG's capped fixpoint is sensitive to entry-point order (issue #99).
+        return sorted(paths)
 
     # ------------------------------------------------------------------
     # Package-root helpers for sharding
@@ -712,11 +752,14 @@ class PyCG:
         """
         import os
         import ray
+        from codeanalyzer.core import _ensure_ray
+        _ensure_ray()
 
         os.environ.setdefault("RAY_IGNORE_UNHANDLED_ERRORS", "1")
         remote_fn = ray.remote(_pycg_shard_worker)
 
         roots: List[Path] = []
+        lock_fds: List[int] = []
         futures: List[Any] = []
         meta: Dict[Any, List[str]] = {}  # ObjectRef -> shard file list
         edges_all: List[PyCallEdge] = []
@@ -724,6 +767,16 @@ class PyCG:
         try:
             with ProgressBar(len(shards), "Building call graph shards (parallel)", item_label="shards") as progress:
                 for files in shards:
+                    # Deterministic roots can collide across concurrent
+                    # analyses of the same project — the driver holds each
+                    # shard's sidecar lock for the whole Ray fan-out (released
+                    # in the finally below with the root cleanup).
+                    lock_fd = os.open(
+                        str(_shard_root_path(files, self.project_dir).with_suffix(".lock")),
+                        os.O_CREAT | os.O_RDWR,
+                    )
+                    fcntl.flock(lock_fd, fcntl.LOCK_EX)
+                    lock_fds.append(lock_fd)
                     root, eps = _materialize_shard_root(files, self.project_dir)
                     roots.append(root)
                     fut = remote_fn.remote(eps, str(root), "", self.max_iter)
@@ -765,6 +818,12 @@ class PyCG:
         finally:
             for root in roots:
                 shutil.rmtree(root, ignore_errors=True)
+            for fd in lock_fds:
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+                    os.close(fd)
+                except OSError:
+                    pass
         return edges_all, runaways
 
     def _build_sharded(
@@ -870,6 +929,8 @@ class PyCG:
         """
         import os
         import ray
+        from codeanalyzer.core import _ensure_ray
+        _ensure_ray()
 
         # force-cancel kills worker processes; suppress Ray's "worker died
         # unexpectedly" noise since the death is intentional here.

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/codeanalyzer/syntactic_analysis/symbol_table_builder.py

@@ -57,13 +57,26 @@ class SymbolTableBuilder:
         relative = Path(script_path).relative_to(self.project_dir)
         return ".".join(relative.with_suffix("").parts) + f".{name}"
 
+    @staticmethod
+    def _first_definition(definitions):
+        """Deterministic pick from Jedi's inference candidates.
+
+        On a union-typed receiver Jedi may return several candidates whose
+        ORDER varies run to run (issue #99 — e.g. ``o.seek`` on
+        ``_IOBase | BufferedRandom | TextIOWrapper``); taking whichever came
+        first made the emitted call graph nondeterministic. Sort on the
+        stable identity (full_name, then name) and take the smallest."""
+        if not definitions:
+            return None
+        return min(definitions, key=lambda d: (d.full_name or "", d.name or ""))
+
     @staticmethod
     def _infer_type(script: Script, line: int, column: int) -> str:
         """Tries to infer the type at a given position using Jedi."""
         try:
-            inference = script.infer(line=line, column=column)
-            if inference:
-                return inference[0].name  # or .full_name
+            d = SymbolTableBuilder._first_definition(script.infer(line=line, column=column))
+            if d is not None:
+                return d.name  # or .full_name
         except Exception:
             pass
         return None
@@ -82,9 +95,9 @@ class SymbolTableBuilder:
             Optional[str]: The fully qualified name if available, else None.
         """
         try:
-            definitions = script.infer(line=line, column=column)
-            if definitions:
-                return definitions[0].full_name
+            d = SymbolTableBuilder._first_definition(script.infer(line=line, column=column))
+            if d is not None:
+                return d.full_name
         except Exception:
             pass
         return None
@@ -103,10 +116,9 @@ class SymbolTableBuilder:
         the call graph.
         """
         try:
-            definitions = script.infer(line=line, column=column)
-            if not definitions:
+            d = SymbolTableBuilder._first_definition(script.infer(line=line, column=column))
+            if d is None:
                 return None, False
-            d = definitions[0]
             is_class = (d.type == "class")
             full = d.full_name
             if is_class and full:
@@ -144,11 +156,17 @@ class SymbolTableBuilder:
         as the callee's own name.
         """
         try:
-            definitions = script.infer(line=line, column=column)
-            if definitions:
-                results = definitions[0].execute()
-                if results:
-                    return results[0].name
+            d = SymbolTableBuilder._first_definition(script.infer(line=line, column=column))
+            if d is not None:
+                # Drop NoneType results before picking: Jedi flaps between
+                # yielding {NoneType} and {} for the None arm of an Optional
+                # return (issue #99), and when a real type is also in the
+                # union it is the informative choice — a bare NoneType says
+                # nothing a missing return_type doesn't.
+                results = [r for r in d.execute() if r.name != "NoneType"]
+                r = SymbolTableBuilder._first_definition(results)
+                if r is not None:
+                    return r.name
         except Exception:
             pass
         return None
@@ -974,9 +992,10 @@ class SymbolTableBuilder:
 
         if script:
             try:
-                definitions = script.infer(line=lineno, column=col_offset)
-                if definitions:
-                    d = definitions[0]
+                d = SymbolTableBuilder._first_definition(
+                    script.infer(line=lineno, column=col_offset)
+                )
+                if d is not None:
                     inferred_type = d.name
                     qname = d.full_name
                     if d.type == "function":

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/docs/handoff/README.md

@@ -13,14 +13,14 @@ the contract lives in the spec, the decision log, and `schema.neo4j.json`.
 Pin the analyzer that produced these samples:
 
 ```
-pip install "codeanalyzer-python==1.0.0"
+pip install "codeanalyzer-python==1.0.1"
 ```
 
 For L4 alias analysis (the Scalpel points-to oracle), install the optional extra —
 without it, L4 degrades to the type-based fallback oracle (still sound, coarser):
 
 ```
-pip install "codeanalyzer-python[scalpel]==1.0.0"
+pip install "codeanalyzer-python[scalpel]==1.0.1"
 ```
 
 ## Schema contract

{codeanalyzer_python-1.0.0 → codeanalyzer_python-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codeanalyzer-python"
-version = "1.0.0"
+version = "1.0.2"
 description = "Static analysis for Python — canonical schema v2 (symbol table, call graph, and native CFG/PDG/SDG dataflow) as analysis.json or a Neo4j property graph."
 readme = "README.md"
 authors = [