arcgraph 0.2.0__tar.gz → 0.2.1__tar.gz

{arcgraph-0.2.0 → arcgraph-0.2.1}/.github/workflows/ci.yml

@@ -37,7 +37,7 @@ jobs:
           python-version: '3.11'
           cache: pip
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
           node-version: '20'
           cache: npm
@@ -78,7 +78,7 @@ jobs:
 
       - name: Upload coverage evidence
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         with:
           name: coverage-python-3.11
           path: output/arcgraph/coverage.xml
@@ -118,7 +118,7 @@ jobs:
           python-version: ${{ matrix.python }}
           cache: pip
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
           node-version: '20'
           cache: npm
@@ -178,7 +178,7 @@ jobs:
           python-version: ${{ matrix.python }}
           cache: pip
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
           node-version: '20'
           cache: npm
@@ -195,7 +195,7 @@ jobs:
 
       - name: Upload package provenance
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         with:
           name: package-readiness-${{ matrix.os }}-py${{ matrix.python }}-${{ matrix.mcp_line }}
           path: output/release/package-readiness.json
@@ -225,7 +225,7 @@ jobs:
           python-version: '3.11'
           cache: pip
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
           node-version: ${{ matrix.node }}
           cache: npm
@@ -259,7 +259,7 @@ jobs:
           python-version: '3.12'
           cache: pip
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
           node-version: '20'
           cache: npm
@@ -290,7 +290,7 @@ jobs:
 
       - name: Upload security evidence
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         with:
           name: security-evidence
           path: output/security

{arcgraph-0.2.0 → arcgraph-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arcgraph
-Version: 0.2.0
+Version: 0.2.1
 Summary: Local-first code semantic graph engine for AI agents and code intelligence.
 Project-URL: Homepage, https://github.com/glyphevo/arcgraph
 Project-URL: Repository, https://github.com/glyphevo/arcgraph
@@ -80,7 +80,7 @@ With ArcGraph:
 
 ArcGraph is published on PyPI, and
 [RELEASE_NOTES.md](https://github.com/glyphevo/arcgraph/blob/main/RELEASE_NOTES.md)
-lists the published versions. This source version, 0.2.0, is a beta release.
+lists the published versions. This source version, 0.2.1, is a beta release.
 Install ArcGraph into a dedicated virtual environment or tool environment and
 reuse that one `arcgraph` executable across projects:
 
@@ -94,13 +94,13 @@ or, with uv:
 uv tool install --python 3.11 "arcgraph[mcp]"
 ```
 
-0.1.0 on PyPI requires Python 3.11 or 3.12; pip refuses other versions. The
-source on `main` (0.2.0) is tested on and requires 3.11–3.14. Pin the exact version you tested, for example `arcgraph[mcp]==0.1.0`. An unpinned install
+0.2.0 requires Python 3.11 to 3.14; pip refuses other versions (0.1.0 required
+3.11 or 3.12). Pin the exact version you tested, for example `arcgraph[mcp]==0.2.0`. An unpinned install
 picks the newest version on PyPI that is not a pre-release; pip installs one of the earlier 0.1.0rc7–0.1.0rc10 pre-releases
 only when you name its version or pass `--pre`. The `mcp` extra is only needed
-to run the MCP server. Installs of 0.1.0 from PyPI were tested: pip with the
+to run the MCP server. Installs of 0.2.0 from PyPI were tested: pip with the
 `mcp` extra on macOS, Windows and Linux (Ubuntu 24.04 under WSL), each with
-Python 3.11 and 3.12, and `uv tool install --python 3.11` on macOS.
+Python 3.11, 3.12, 3.13 and 3.14, and `uv tool install --python 3.11` on macOS.
 `arcgraph version --json` reports the commit the installed copy was built from.
 
 To install the development version from this repository instead, replace the
@@ -121,8 +121,8 @@ commit you are using.
 
 Requirements:
 
-- Python 3.11 or 3.12 for 0.1.0 from PyPI; 3.11 to 3.14 for the source on
-  `main`.
+- Python 3.11 to 3.14 for 0.2.0 and the source on `main`; 3.11 or 3.12 for
+  0.1.0 from PyPI.
 - Node.js and a resolvable TypeScript compiler API when analyzing
   TypeScript/JavaScript projects. The Python wheel includes ArcGraph's `.mjs`
   extractor but does not include `node_modules/typescript`; provide the runtime
@@ -240,7 +240,10 @@ python scripts/arcgraph.py <command>
 ```
 
 On a clean Windows machine, install Python 3.11 to 3.14 and Node.js/npm first. Optional
-precision tools can be installed with:
+precision tools can be installed with the script below. It installs `pyright` and, since
+scip v0.7.1 publishes no Windows binary, builds `scip.exe` from a clone of the v0.7.1 tag,
+so it also needs Go and Git. `scip-python` 0.6.6 fails while loading on native Windows;
+run `arcgraph precision scip-python` in WSL with the macOS/Linux steps below.
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts\install-arcgraph-precision-tools.ps1
@@ -252,14 +255,28 @@ tools directly:
 
 ```bash
 npm install -g @sourcegraph/scip-python@0.6.6 pyright@1.1.409
-go install github.com/scip-code/scip/cmd/scip@v0.7.1
 ```
 
-The first command provides `scip-python`, `pyright`, and `pyright-langserver`;
-the second requires a local Go toolchain and provides `scip`. Then pass the
-generated JSON artifacts to `arcgraph build`. The GitHub Actions `CI`
-workflow does not install these tools, so it is not a fallback for generating
-this evidence.
+The first command provides `scip-python`, `pyright`, and `pyright-langserver`.
+`scip` is not installable with `go install package@version`: scip v0.7.1
+declares a `replace` directive in its `go.mod`, and the Go toolchain refuses
+that for a versioned install. Download the prebuilt binary for your platform
+from the [scip v0.7.1 release](https://github.com/scip-code/scip/releases/tag/v0.7.1)
+and verify the published checksum:
+
+```bash
+curl -fsSLO https://github.com/scip-code/scip/releases/download/v0.7.1/scip-darwin-arm64.tar.gz
+curl -fsSLO https://github.com/scip-code/scip/releases/download/v0.7.1/scip-darwin-arm64.tar.gz.sha256
+shasum -a 256 -c scip-darwin-arm64.tar.gz.sha256
+tar -xzf scip-darwin-arm64.tar.gz
+```
+
+The same release publishes `scip-darwin-amd64.tar.gz`,
+`scip-linux-amd64.tar.gz` and `scip-linux-arm64.tar.gz`, each with its own
+`.sha256` file; use `sha256sum -c` instead of `shasum -a 256 -c` on Linux.
+The extracted `scip` binary provides `scip`. Then pass the generated JSON
+artifacts to `arcgraph build`. The GitHub Actions `CI` workflow does not
+install these tools, so it is not a fallback for generating this evidence.
 
 ## Quickstart
 

{arcgraph-0.2.0 → arcgraph-0.2.1}/README.md

@@ -38,7 +38,7 @@ With ArcGraph:
 
 ArcGraph is published on PyPI, and
 [RELEASE_NOTES.md](https://github.com/glyphevo/arcgraph/blob/main/RELEASE_NOTES.md)
-lists the published versions. This source version, 0.2.0, is a beta release.
+lists the published versions. This source version, 0.2.1, is a beta release.
 Install ArcGraph into a dedicated virtual environment or tool environment and
 reuse that one `arcgraph` executable across projects:
 
@@ -52,13 +52,13 @@ or, with uv:
 uv tool install --python 3.11 "arcgraph[mcp]"
 ```
 
-0.1.0 on PyPI requires Python 3.11 or 3.12; pip refuses other versions. The
-source on `main` (0.2.0) is tested on and requires 3.11–3.14. Pin the exact version you tested, for example `arcgraph[mcp]==0.1.0`. An unpinned install
+0.2.0 requires Python 3.11 to 3.14; pip refuses other versions (0.1.0 required
+3.11 or 3.12). Pin the exact version you tested, for example `arcgraph[mcp]==0.2.0`. An unpinned install
 picks the newest version on PyPI that is not a pre-release; pip installs one of the earlier 0.1.0rc7–0.1.0rc10 pre-releases
 only when you name its version or pass `--pre`. The `mcp` extra is only needed
-to run the MCP server. Installs of 0.1.0 from PyPI were tested: pip with the
+to run the MCP server. Installs of 0.2.0 from PyPI were tested: pip with the
 `mcp` extra on macOS, Windows and Linux (Ubuntu 24.04 under WSL), each with
-Python 3.11 and 3.12, and `uv tool install --python 3.11` on macOS.
+Python 3.11, 3.12, 3.13 and 3.14, and `uv tool install --python 3.11` on macOS.
 `arcgraph version --json` reports the commit the installed copy was built from.
 
 To install the development version from this repository instead, replace the
@@ -79,8 +79,8 @@ commit you are using.
 
 Requirements:
 
-- Python 3.11 or 3.12 for 0.1.0 from PyPI; 3.11 to 3.14 for the source on
-  `main`.
+- Python 3.11 to 3.14 for 0.2.0 and the source on `main`; 3.11 or 3.12 for
+  0.1.0 from PyPI.
 - Node.js and a resolvable TypeScript compiler API when analyzing
   TypeScript/JavaScript projects. The Python wheel includes ArcGraph's `.mjs`
   extractor but does not include `node_modules/typescript`; provide the runtime
@@ -198,7 +198,10 @@ python scripts/arcgraph.py <command>
 ```
 
 On a clean Windows machine, install Python 3.11 to 3.14 and Node.js/npm first. Optional
-precision tools can be installed with:
+precision tools can be installed with the script below. It installs `pyright` and, since
+scip v0.7.1 publishes no Windows binary, builds `scip.exe` from a clone of the v0.7.1 tag,
+so it also needs Go and Git. `scip-python` 0.6.6 fails while loading on native Windows;
+run `arcgraph precision scip-python` in WSL with the macOS/Linux steps below.
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts\install-arcgraph-precision-tools.ps1
@@ -210,14 +213,28 @@ tools directly:
 
 ```bash
 npm install -g @sourcegraph/scip-python@0.6.6 pyright@1.1.409
-go install github.com/scip-code/scip/cmd/scip@v0.7.1
 ```
 
-The first command provides `scip-python`, `pyright`, and `pyright-langserver`;
-the second requires a local Go toolchain and provides `scip`. Then pass the
-generated JSON artifacts to `arcgraph build`. The GitHub Actions `CI`
-workflow does not install these tools, so it is not a fallback for generating
-this evidence.
+The first command provides `scip-python`, `pyright`, and `pyright-langserver`.
+`scip` is not installable with `go install package@version`: scip v0.7.1
+declares a `replace` directive in its `go.mod`, and the Go toolchain refuses
+that for a versioned install. Download the prebuilt binary for your platform
+from the [scip v0.7.1 release](https://github.com/scip-code/scip/releases/tag/v0.7.1)
+and verify the published checksum:
+
+```bash
+curl -fsSLO https://github.com/scip-code/scip/releases/download/v0.7.1/scip-darwin-arm64.tar.gz
+curl -fsSLO https://github.com/scip-code/scip/releases/download/v0.7.1/scip-darwin-arm64.tar.gz.sha256
+shasum -a 256 -c scip-darwin-arm64.tar.gz.sha256
+tar -xzf scip-darwin-arm64.tar.gz
+```
+
+The same release publishes `scip-darwin-amd64.tar.gz`,
+`scip-linux-amd64.tar.gz` and `scip-linux-arm64.tar.gz`, each with its own
+`.sha256` file; use `sha256sum -c` instead of `shasum -a 256 -c` on Linux.
+The extracted `scip` binary provides `scip`. Then pass the generated JSON
+artifacts to `arcgraph build`. The GitHub Actions `CI` workflow does not
+install these tools, so it is not a fallback for generating this evidence.
 
 ## Quickstart
 

{arcgraph-0.2.0 → arcgraph-0.2.1}/RELEASE_NOTES.md

@@ -5,7 +5,8 @@ notes themselves are the only place their content is written down.
 
 | Version | Status | Notes |
 | --- | --- | --- |
-| 0.2.0 | Declared source version on `main`; not yet published | [v0.2.0](docs/release_notes/v0.2.0.md) |
+| 0.2.1 | Declared source version on `main`; not yet published | [v0.2.1](docs/release_notes/v0.2.1.md) |
+| 0.2.0 | Published on PyPI on 2026-10-21 as a beta release | [v0.2.0](docs/release_notes/v0.2.0.md) |
 | 0.1.0 | Published on PyPI on 2026-10-05 as a beta release | [v0.1.0](docs/release_notes/v0.1.0.md) |
 | 0.1.0rc10 | Published on PyPI on 2026-10-04 as an alpha developer-preview pre-release | [v0.1.0-rc10](docs/release_notes/v0.1.0-rc10.md) |
 | 0.1.0rc9 | Published on PyPI on 2026-10-03 as an alpha developer-preview pre-release | [v0.1.0-rc9](docs/release_notes/v0.1.0-rc9.md) |

{arcgraph-0.2.0 → arcgraph-0.2.1}/arcgraph/_build_provenance.json

@@ -1,9 +1,9 @@
 {
-  "build_version": "0.2.0",
+  "build_version": "0.2.1",
   "schema_version": "1.0.0",
   "source": {
-    "commit_sha": "6f5cd85c40774990838dbf62b9ae7f80af0feb64",
-    "tree_sha": "9e7d20b129c47dab9c90496e68adb461917eeff3",
+    "commit_sha": "282eb8a89ecb063c573d40e32b65b794c32d1664",
+    "tree_sha": "aaa5ce029ba8d0a08d40933498eeffcbdc235544",
     "working_tree_clean": true,
     "working_tree_status_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
   }

{arcgraph-0.2.0 → arcgraph-0.2.1}/arcgraph/analyzers/coverage.py

@@ -26,6 +26,10 @@ class CoverageAnalysis:
     warnings: list[BuildWarning] = field(default_factory=list)
     status: str = "unavailable"
     metrics: dict[str, Any] = field(default_factory=dict)
+    # True when a file's test contexts all failed to match an indexed test
+    # node: the per-test evidence for that file is missing, so the coverage
+    # status is partial even when aggregate edges exist.
+    test_contexts_unmatched: bool = False
 
 
 class CoverageCollector:
@@ -209,10 +213,14 @@ class CoverageCollector:
                 metrics={"format": "coverage.py"},
             )
         symbols = self._symbol_nodes(nodes)
+        context_index = self._coverage_context_index(nodes)
+        resolved_contexts: dict[str, Node | None] = {}
         aggregate = self._coverage_node(path, "coverage.py")
         edges = {}
         unmatched = malformed = 0
         unknown_contexts = set()
+        unmatched_test_contexts = set()
+        matched_test_contexts = set()
         for raw_path, item in payload["files"].items():
             if not isinstance(item, dict) or not isinstance(
                 item.get("executed_lines"), list
@@ -246,14 +254,20 @@ class CoverageCollector:
                     if isinstance(name, str) and name:
                         contexts.setdefault(name, set()).add(int(number))
             for name, covered in contexts.items():
-                source = (
-                    aggregate
-                    if not name
-                    else self._coverage_test_context(name, nodes, module_by_path)
-                )
-                if source is None:
-                    unknown_contexts.add(name)
-                    continue
+                if not name:
+                    source = aggregate
+                else:
+                    is_test_context = self._coverage_context_parts(name) is not None
+                    source = self._coverage_test_context(
+                        name, context_index, module_by_path, resolved_contexts
+                    )
+                    if source is None:
+                        unknown_contexts.add(name)
+                        if is_test_context:
+                            unmatched_test_contexts.add(name)
+                        continue
+                    if is_test_context:
+                        matched_test_contexts.add(name)
                 targets = [
                     module_by_path[file_path],
                     *[
@@ -297,9 +311,25 @@ class CoverageCollector:
                         properties["contexts"] = sorted(
                             set(properties["contexts"]) | {name}
                         )
+        warnings = []
+        if unmatched_test_contexts:
+            examples = sorted(unmatched_test_contexts)[:5]
+            warnings.append(
+                BuildWarning(
+                    kind="coverage_python_unmatched_contexts",
+                    path=self._display_path(path),
+                    message=(
+                        f"{len(unmatched_test_contexts)} coverage.py test context(s) "
+                        "did not match an indexed test node: " + ", ".join(examples)
+                    ),
+                )
+            )
         return CoverageAnalysis(
             nodes=[aggregate] if edges else [],
             edges=sorted(edges.values(), key=lambda e: (e.source, e.target, e.kind)),
+            warnings=warnings,
+            test_contexts_unmatched=bool(unmatched_test_contexts)
+            and not matched_test_contexts,
             metrics={
                 "format": "coverage.py",
                 "entries_total": len(payload["files"]),
@@ -309,24 +339,83 @@ class CoverageCollector:
             },
         )
 
-    def _coverage_test_context(self, context, nodes, modules):
-        # pytest-cov node ids may have static prefixes and phase suffixes.
+    @staticmethod
+    def _coverage_context_index(nodes: list[Node]) -> dict[tuple[str, str], list[Node]]:
+        """Index the nodes a coverage.py test context can name, once per analysis.
+
+        Keyed by (path, qualname): the pytest adapter adds a ``test_case`` node
+        with the same path and qualname as the test function, so one key can
+        hold both.
+        """
+        index: dict[tuple[str, str], list[Node]] = {}
+        for node in nodes:
+            if (
+                node.kind not in {"function", "method", "test_case"}
+                or not node.path
+                or not node.qualname
+            ):
+                continue
+            index.setdefault((node.path, node.qualname), []).append(node)
+        return index
+
+    @staticmethod
+    def _coverage_context_parts(context: str) -> tuple[str, list[str]] | None:
+        """Split a pytest-cov context name into (path, qualname parts).
+
+        Returns None for a name that is not a single pytest node id: static
+        contexts (``""``, ``production``) and names with several node ids are
+        not test contexts and are never matched to a test node.
+        """
         identifiers = [part for part in context.split("|") if "::" in part]
         if len(identifiers) != 1:
             return None
         path, *parts = identifiers[0].split("::")
-        file_path = self._match_file_path(self._normalized_path(path), modules)
-        if file_path is None or not parts:
+        if not path or not parts:
             return None
-        qualname = ".".join(part.split("[", 1)[0] for part in parts)
-        matches = [
-            node
-            for node in nodes
-            if node.path == file_path
-            and node.kind in {"function", "method", "test_case"}
-            and node.qualname == modules[file_path].qualname + "." + qualname
-        ]
-        return matches[0] if len(matches) == 1 else None
+        return path, parts
+
+    def _coverage_test_context(
+        self,
+        context: str,
+        index: dict[tuple[str, str], list[Node]],
+        modules: dict[str, Node],
+        resolved: dict[str, Node | None],
+    ) -> Node | None:
+        # pytest-cov node ids may have static prefixes and phase suffixes.
+        if context in resolved:
+            return resolved[context]
+        parts = self._coverage_context_parts(context)
+        node: Node | None = None
+        if parts is not None:
+            path, qualname_parts = parts
+            file_path = self._match_file_path(self._normalized_path(path), modules)
+            if file_path is not None:
+                qualname = ".".join(part.split("[", 1)[0] for part in qualname_parts)
+                node = self._match_context_node(
+                    index, file_path, modules[file_path].qualname + "." + qualname
+                )
+        resolved[context] = node
+        return node
+
+    @staticmethod
+    def _match_context_node(
+        index: dict[tuple[str, str], list[Node]], file_path: str, qualname: str
+    ) -> Node | None:
+        """Pick the node a context names: the test case first, then the function.
+
+        The pytest adapter registers a ``test_case`` node with the same path and
+        qualname as the test function; the test case is the node that carries
+        the per-test evidence, so it wins. Without one, a single function or
+        method is the only unambiguous match.
+        """
+        matches = index.get((file_path, qualname), [])
+        test_cases = [node for node in matches if node.kind == "test_case"]
+        if len(test_cases) == 1:
+            return test_cases[0]
+        if test_cases:
+            return None
+        functions = [node for node in matches if node.kind in {"function", "method"}]
+        return functions[0] if len(functions) == 1 else None
 
     def _analyze_istanbul_json(
         self,
@@ -657,6 +746,10 @@ class CoverageCollector:
                     ),
                 )
             )
+        if analysis.test_contexts_unmatched:
+            # The report has test contexts and none of them matched, so the
+            # per-test evidence is missing even if aggregate edges exist.
+            status = "partial"
 
         covered_files = sorted(
             {

{arcgraph-0.2.0 → arcgraph-0.2.1}/arcgraph/interfaces/cli.py

@@ -132,6 +132,7 @@ from arcgraph.interfaces.cli_visual import (  # noqa: F401
 from arcgraph.interfaces.cli_support import (  # noqa: F401
     output_location,
     handle_export,
+    precision_tools_fix,
     print_json,
     python_checks,
     query_engine,
@@ -1860,11 +1861,7 @@ def handle_doctor(args: argparse.Namespace) -> dict[str, Any]:
                 "name": "precision_tools",
                 "status": "warn",
                 "message": f"Missing: {', '.join(missing_tools)}.",
-                "fix": (
-                    "Run scripts/install-arcgraph-precision-tools.ps1 (Windows) or "
-                    "install scip-python, scip, pyright manually. "
-                    "Precision tools are optional; builds work without them."
-                ),
+                "fix": precision_tools_fix(),
             }
         )
 

{arcgraph-0.2.0 → arcgraph-0.2.1}/arcgraph/interfaces/cli_support.py

@@ -174,6 +174,31 @@ def python_checks(repo_root: Path, *, semantic_state=None) -> list[dict[str, Any
     return checks
 
 
+def precision_tools_fix() -> str:
+    """doctor's repair hint for missing precision tools, per platform.
+
+    Windows has a repository script that installs scip and pyright; scip-python
+    0.6.6 does not run on native Windows and is run in WSL. macOS and Linux
+    install the npm tools and take scip from its official release, which is
+    what the README documents for those platforms.
+    """
+
+    if platform.system() == "Windows":
+        return (
+            "Run scripts/install-arcgraph-precision-tools.ps1 to install scip "
+            "and pyright; scip-python 0.6.6 does not run on native Windows, so "
+            "run `arcgraph precision scip-python` in WSL. Precision tools are "
+            "optional; builds work without them."
+        )
+    return (
+        "Install scip-python and pyright with `npm install -g "
+        "@sourcegraph/scip-python@0.6.6 pyright@1.1.409`, and scip v0.7.1 from "
+        "the official release "
+        "(https://github.com/scip-code/scip/releases/tag/v0.7.1). "
+        "Precision tools are optional; builds work without them."
+    )
+
+
 def query_engine(args: argparse.Namespace) -> QueryEngine:
     repo_root = Path(args.repo_root).resolve()
     return QueryEngine((repo_root / args.output_dir).resolve())

{arcgraph-0.2.0 → arcgraph-0.2.1}/arcgraph/interfaces/docs.py

@@ -51,7 +51,7 @@ def _docs_payload(topic: str) -> dict[str, Any]:
                 {
                     "title": "Prepare One Project",
                     "items": [
-                        'Install ArcGraph in a persistent tool environment or venv; MCP clients require the mcp extra. ArcGraph is beta software; the repository\'s RELEASE_NOTES.md lists the published versions. ArcGraph is published on PyPI: install it with `uv tool install --python 3.11 "arcgraph[mcp]"` or `python -m pip install "arcgraph[mcp]"` (pip installs of 0.1.0 from PyPI were tested on macOS, Windows and Linux with Python 3.11 and 3.12; pin the exact version you tested, for example `arcgraph[mcp]==0.1.0`), or from the GitHub repository with `"arcgraph[mcp] @ git+https://github.com/glyphevo/arcgraph.git"`. A disposable uvx environment is not managed by setup. Git tags and GitHub releases carry the same files as the matching PyPI version; npm and Docker/GHCR are not published.',
+                        'Install ArcGraph in a persistent tool environment or venv; MCP clients require the mcp extra. ArcGraph is beta software; the repository\'s RELEASE_NOTES.md lists the published versions. ArcGraph is published on PyPI: install it with `uv tool install --python 3.11 "arcgraph[mcp]"` or `python -m pip install "arcgraph[mcp]"` (pip installs of 0.2.0 from PyPI were tested on macOS, Windows and Linux with Python 3.11 to 3.14; pin the exact version you tested, for example `arcgraph[mcp]==0.2.0`), or from the GitHub repository with `"arcgraph[mcp] @ git+https://github.com/glyphevo/arcgraph.git"`. A disposable uvx environment is not managed by setup. Git tags and GitHub releases carry the same files as the matching PyPI version; npm and Docker/GHCR are not published.',
                         "From the target project, run `arcgraph setup --client claude|codex|cursor|hermes|pi`, selecting one client. It explicitly builds or refreshes the index, probes the runtime, then writes one client entry.",
                         "Use `--dry-run` for a plan without writes, indexing or subprocesses; `--client-config PATH` overrides the destination, not client discovery; `--timeout SECONDS` sets a positive per-step timeout.",
                         "Global options precede setup: `arcgraph --repo-root /path/to/project --output-dir /path/to/index setup --client codex`. Default output is project/output/arcgraph. Indexing, MCP and CLI guidance share the same absolute paths. Source scope follows ordinary project configuration and detection; inspect it with doctor.",
@@ -209,7 +209,7 @@ def _docs_payload(topic: str) -> dict[str, Any]:
                     "title": "Local Install And Upgrade",
                     "items": [
                         "ArcGraph is on PyPI and can also be installed from a source checkout; ArcGraph is beta software. Git tags (`v` followed by the version) and GitHub releases carry the same two files as the matching version on PyPI. npm and Docker/GHCR package paths are not published.",
-                        "ArcGraph requires Python 3.11 to 3.14 (`requires-python >=3.11,<3.15`); 0.1.0 on PyPI requires 3.11 or 3.12. Create and activate a virtual environment before installing when you want an isolated local tool.",
+                        "ArcGraph requires Python 3.11 to 3.14 (`requires-python >=3.11,<3.15`); 0.1.0 required 3.11 or 3.12. Create and activate a virtual environment before installing when you want an isolated local tool.",
                         "From a source checkout, run `python -m pip install --upgrade -e .` in the ArcGraph project directory to install or refresh the `arcgraph` CLI.",
                         'For development and local validation, run `python -m pip install -e ".[dev]"`; use the analyzed project\'s locked npm install when TypeScript/JavaScript analysis is required.',
                         "Node.js and a resolvable TypeScript compiler API are runtime dependencies for TypeScript/JavaScript analysis, not merely test dependencies. The Python wheel includes the `.mjs` extractor but not `node_modules/typescript`.",
@@ -233,7 +233,7 @@ def _docs_payload(topic: str) -> dict[str, Any]:
                         "Pyright export metrics include total probes, requestable probes, skipped unmappable probes, request count, resolved type info, and unresolved probes.",
                         "The Windows precision-tools install script pins `pyright@1.1.409`; local full evidence profiles should use the same version unless intentionally testing compatibility. GitHub Actions does not currently install or run Pyright.",
                         "Pass the resulting JSON to `arcgraph build --scip-index output/arcgraph/scip-index.json --pyright-export output/arcgraph/pyright-export.json`; missing or invalid precision input remains explicit as `precision=ast_fallback_only` or `precision_partial`.",
-                        "On Windows, run `scripts/install-arcgraph-precision-tools.ps1` to install `@sourcegraph/scip-python@0.6.6`, `pyright@1.1.409`, and build `scip.exe v0.7.1` with Go. WSL remains a fallback (use the Linux install steps there); GitHub Actions is not currently a working fallback for this, since it neither installs these tools nor runs at all while disabled.",
+                        "On Windows, run `scripts/install-arcgraph-precision-tools.ps1` to install `pyright@1.1.409` and build `scip.exe v0.7.1` with Go from a clone of the v0.7.1 tag (Go and Git are required; scip publishes no Windows binary). `@sourcegraph/scip-python@0.6.6` does not run on native Windows (it fails while loading), so run `arcgraph precision scip-python` in WSL with the Linux install steps. On macOS and Linux, take `scip` v0.7.1 from the prebuilt binary on its official release and check the published checksum. GitHub Actions is not currently a working fallback for this, since it neither installs these tools nor runs at all while disabled.",
                     ],
                 },
                 {
@@ -749,7 +749,7 @@ def _docs_payload(topic: str) -> dict[str, Any]:
                         "`arcgraph precision scip-python`, `arcgraph precision scip-json`, and `arcgraph precision pyright` generate JSON artifacts accepted by `arcgraph build --scip-index ... --pyright-export ...`.",
                         "`runtime_trace=available|partial|unavailable` describes explicit runtime trace import status.",
                         "A small CI smoke trace proves the runtime evidence chain and stale detection only; broad dynamic behavior coverage requires an intentionally broader trace profile.",
-                        "`coverage=available|partial|unavailable` describes test coverage input status; `partial` means the file was stale, invalid, or produced only partial evidence.",
+                        "`coverage=available|partial|unavailable` describes test coverage input status; `partial` means the file was stale, invalid, or produced only partial evidence, including a coverage.py report whose test contexts all failed to match an indexed test.",
                     ],
                 },
                 {
@@ -849,11 +849,12 @@ def _docs_payload(topic: str) -> dict[str, Any]:
             "title": "ArcGraph Quickstart",
             "sections": [
                 {
-                    "title": "Install From A Checkout",
+                    "title": "Install",
                     "items": [
-                        "ArcGraph requires Python 3.11 to 3.14 (`requires-python >=3.11,<3.15`; 0.1.0 on PyPI requires 3.11 or 3.12) and is currently installed from a source checkout.",
-                        "Create and activate a virtual environment, then run `python -m pip install --upgrade pip`.",
-                        "Run `python -m pip install -e .` for the normal CLI install.",
+                        'ArcGraph requires Python 3.11 to 3.14 (`requires-python >=3.11,<3.15`; 0.1.0 required 3.11 or 3.12) and is published on PyPI: `python -m pip install "arcgraph[mcp]"` or `uv tool install --python 3.11 "arcgraph[mcp]"` installs the CLI, and the `mcp` extra is only needed to run the MCP server.',
+                        "Pin the exact version you tested, for example `arcgraph[mcp]==0.2.0`; `arcgraph version --json` reports the commit the installed copy was built from.",
+                        "From a source checkout, create and activate a virtual environment, then run `python -m pip install --upgrade pip`.",
+                        "Run `python -m pip install -e .` to install the CLI from that checkout.",
                         'Run `python -m pip install -e ".[dev]"` when you need development dependencies or local validation.',
                         "For TypeScript/JavaScript analysis, Node.js and a TypeScript compiler API must be resolvable at runtime. Use the analyzed project's locked npm install; the Python wheel includes the `.mjs` extractor but not `node_modules/typescript`.",
                         "For ArcGraph's own TypeScript golden tests from a source checkout, run `npm ci` in the ArcGraph checkout; that is development setup, not the analyzed project's product runtime.",
@@ -972,7 +973,7 @@ def _docs_payload(topic: str) -> dict[str, Any]:
                         "Run `python scripts/arcgraph.py build` to rebuild the self-index at the current commit.",
                         "Run `python scripts/arcgraph.py ci` and require 0 fail / 0 warn.",
                         "Run `python scripts/arcgraph_release_gate.py` to validate freshness, CI status, wheel buildability, and packaged release assets.",
-                        "Run `python scripts/arcgraph_release_candidate_check.py --wheel dist/arcgraph-0.2.0-py3-none-any.whl --sdist dist/arcgraph-0.2.0.tar.gz --repo-root . --output output/arcgraph/reports/v0.2.0-smoke.json` to smoke the installed wheel before tagging or publishing. Its `wheel-source-provenance` check records the wheel SHA-256 and passes only when the wheel's embedded build provenance names the same commit and tree as `--repo-root` HEAD and records a clean build working tree, so neither a stale `dist/` artifact from an earlier commit nor a wheel built over uncommitted edits can be validated under the current version label. Its `clean-rebuild-identical` check then clones that HEAD into a fresh directory, runs an isolated `python -m build` there, and requires the rebuilt wheel and sdist to carry the same file names and identical bytes as the two files given, so an archive edited after the build (a changed dependency declaration, entry point or script) is rejected even when its RECORD was regenerated to match. The build backend is pinned to an exact version in `pyproject.toml` to reduce drift between the two builds; the pin covers only that direct requirement, so a change in a transitive build dependency or in the environment can still make the comparison fail, which is the safe direction, and the check records the Python, build frontend and backend versions it used. A side carrying no provenance at all, or no repository head to rebuild, is reported as `warn` rather than claimed as bound, and `--allow-source-mismatch` downgrades a real disagreement to a disclosed warning; report `status` is then `warn`, never `pass`, and the bundle assembler accepts only `pass`.",
+                        "Run `python scripts/arcgraph_release_candidate_check.py --wheel dist/arcgraph-0.2.1-py3-none-any.whl --sdist dist/arcgraph-0.2.1.tar.gz --repo-root . --output output/arcgraph/reports/v0.2.1-smoke.json` to smoke the installed wheel before tagging or publishing. Its `wheel-source-provenance` check records the wheel SHA-256 and passes only when the wheel's embedded build provenance names the same commit and tree as `--repo-root` HEAD and records a clean build working tree, so neither a stale `dist/` artifact from an earlier commit nor a wheel built over uncommitted edits can be validated under the current version label. Its `clean-rebuild-identical` check then clones that HEAD into a fresh directory, runs an isolated `python -m build` there, and requires the rebuilt wheel and sdist to carry the same file names and identical bytes as the two files given, so an archive edited after the build (a changed dependency declaration, entry point or script) is rejected even when its RECORD was regenerated to match. The build backend is pinned to an exact version in `pyproject.toml` to reduce drift between the two builds; the pin covers only that direct requirement, so a change in a transitive build dependency or in the environment can still make the comparison fail, which is the safe direction, and the check records the Python, build frontend and backend versions it used. A side carrying no provenance at all, or no repository head to rebuild, is reported as `warn` rather than claimed as bound, and `--allow-source-mismatch` downgrades a real disagreement to a disclosed warning; report `status` is then `warn`, never `pass`, and the bundle assembler accepts only `pass`.",
                         "Maintainers can assemble a local external-trial bundle with `python scripts/arcgraph_external_trial_bundle.py`; run it with `--help` for its inputs. It publishes, tags and pushes nothing, and it requires saved evidence of a completed successful remote CI push run on `main` for the exact candidate commit.",
                         "Review `arcgraph docs schema-governance` before changing `SCHEMA_VERSION`, graph storage, resolver defaults, or evidence import schemas.",
                         "Review `arcgraph docs frontend-contract` before adding, removing, or changing a language frontend.",
@@ -1110,7 +1111,7 @@ def _docs_payload(topic: str) -> dict[str, Any]:
                     "title": "Partial Semantic Results",
                     "items": [
                         "When precision inputs are missing, `precision=ast_fallback_only` is expected and should be reported.",
-                        "If `arcgraph precision scip-python` fails on Windows because tools are missing, run `scripts/install-arcgraph-precision-tools.ps1`; if Go is missing, install it with `winget install --id GoLang.Go -e` or pass `-InstallGoWithWinget`.",
+                        "On native Windows, run `arcgraph precision scip-python` in WSL: `@sourcegraph/scip-python@0.6.6` fails while loading on Windows. If `scip` or `pyright` is missing on Windows, run `scripts/install-arcgraph-precision-tools.ps1`; if Go is missing, install it with `winget install --id GoLang.Go -e` or pass `-InstallGoWithWinget`, and if Git is missing, install it with `winget install --id Git.Git -e`.",
                         "If local `scip-python`, `scip`, or `pyright-langserver` is unavailable and cannot be installed, use WSL/Linux/CI for evidence generation or run fast `arcgraph ci` while reporting `precision=ast_fallback_only`, `precision_partial`, or `type_precision_complete=false` explicitly.",
                         "Unresolved callsites are diagnostics, not silent drops; inspect `arcgraph unresolved TARGET`, filter with `--category`, or use `--release-blocking-only` before a python_full release.",
                         "Do not infer unresolved risk from a callback-like name or a test path. `true_dynamic_call` requires analyzer-recorded dynamic dispatch (including a visible runtime local binding), while ordinary unresolved test calls remain `static_candidate`.",
@@ -1135,6 +1136,13 @@ def _docs_payload(topic: str) -> dict[str, Any]:
         "topic": topic,
         "title": "Schema Migration Notes",
         "sections": [
+            {
+                "title": "0.2.1",
+                "items": [
+                    "coverage.py test contexts resolve to the pytest test case node; rebuild with `--coverage` to replace the aggregate-only edges an earlier build imported. Unmatched test contexts raise coverage_python_unmatched_contexts; when none match, coverage is `partial` and the coverage_inputs check of `arcgraph ci` warns (fails with --require-coverage).",
+                    "On native Windows, run `arcgraph precision scip-python` in WSL; scripts/install-arcgraph-precision-tools.ps1 builds scip from source with Go and Git and no longer installs scip-python.",
+                ],
+            },
             {
                 "title": "0.2.0",
                 "items": [