agent-capmap 0.1.0__tar.gz → 0.1.1__tar.gz

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/CHANGELOG.md

@@ -6,6 +6,19 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-11-08
+
+### Added
+
+- **Pull request comment** (`comment: "true"` in the GitHub Action): scans the base commit
+  too and posts one updating comment with new findings, newly unassessed servers, gained
+  capabilities and resolved findings. Config-only (never starts servers), never combined
+  with `enumerate`, skipped gracefully on forks. `agentcapmap diff` now also reports
+  `new_not_assessed` and starts its Markdown with a summary line.
+- `scripts/prepare_release.py` bumps the version everywhere and dates the changelog;
+  a test keeps `pyproject.toml` and `__version__` equal. The releasing steps in
+  CONTRIBUTING.md now cover patch releases and the PyPI/GitHub setup.
+
 ## [0.1.0] - 2026-11-08
 
 First release, newest first within each section. Accuracy is not benchmarked yet and the

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/CONTRIBUTING.md

@@ -154,19 +154,42 @@ Adding, removing or redefining an axis or value is a breaking change:
 
 ## Releasing (maintainers)
 
-1. Set `version` in `pyproject.toml` and move the `[Unreleased]` entries in
-   `CHANGELOG.md` under a new `[X.Y.Z] - YYYY-MM-DD` heading. Merge that to `main`.
-2. Tag the merge commit and push the tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
-3. `.github/workflows/release.yml` checks that the tag matches the version, runs the
-   tests and pip-audit, builds the sdist and wheel from the hash-pinned build lock,
-   and waits for approval on the `pypi` environment. After approval it publishes to
-   PyPI with trusted publishing (no stored token; PyPI attestations are generated
-   automatically) and creates the GitHub release with the same files.
-4. Update the `uses: NKwolv/agent-capmap@<sha>` pin in
-   `docs/examples/agentcapmap.yml` to the tagged commit.
+One-time setup (already done for the 0.1.0 release):
+
+- On PyPI, a trusted publisher for this repository: workflow `release.yml`,
+  environment `pypi`.
+- On GitHub, a `pypi` environment with a **required reviewer**, so every release needs
+  an explicit approval before it is published.
+
+For every release, including patch releases:
+
+1. Put the changes under `## [Unreleased]` in `CHANGELOG.md`. If you reviewed or changed
+   eval labels, run `python scripts/build_reference_labels.py` and commit the result:
+   the labels ship in the package, so a label change needs a new release.
+2. `python scripts/prepare_release.py X.Y.Z` bumps the version in `pyproject.toml` and
+   `src/agentcapmap/__init__.py` (a test keeps them equal) and dates the changelog. It
+   refuses on a dirty tree, a version that is not higher, an empty `[Unreleased]`, or
+   stale reference labels, and it never commits or pushes (add `--dry-run` to preview).
+3. Regenerate the demo inventory, which stamps the version:
+   `AGENTCAPMAP_UPDATE_GOLDEN=1 python -m pytest tests/test_fixtures.py` (PowerShell:
+   `$env:AGENTCAPMAP_UPDATE_GOLDEN=1; python -m pytest tests/test_fixtures.py`). Then
+   `python scripts/check.py`, then commit, push, and wait for CI on that commit.
+4. Tag that exact commit and push the tag:
+   `git tag -a vX.Y.Z -m "agent-capmap X.Y.Z" && git push origin vX.Y.Z`.
+5. `.github/workflows/release.yml` checks that the tag matches the version, runs the
+   tests and pip-audit, builds the sdist and wheel from the hash-pinned build lock, and
+   waits for approval on the `pypi` environment. After approval it publishes to PyPI
+   with trusted publishing (no stored token; attestations are automatic) and creates
+   the GitHub release with the same files.
+6. Check the result: the version is on PyPI, and `pip install agent-capmap==X.Y.Z` in a
+   fresh virtual environment runs `python -m agentcapmap --version`.
+7. Update the `uses: NKwolv/agent-capmap@<sha>` pin in `docs/examples/agentcapmap.yml`
+   to the tagged commit.
 
 A version on PyPI can never be re-uploaded. If a release is broken, yank it on PyPI
-and publish a new patch version.
+and publish a new patch version. If only the publish step failed (for example the
+trusted publisher was not set up yet), fix the cause and re-run the failed job; the tag
+does not need to change.
 
 ## Reporting security issues
 

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-capmap
-Version: 0.1.0
+Version: 0.1.1
 Summary: Inventory the MCP tools reachable by AI agents and flag dangerous capability combinations with policy-as-code.
 Project-URL: Homepage, https://github.com/NKwolv/agent-capmap
 Project-URL: Documentation, https://github.com/NKwolv/agent-capmap#readme
@@ -234,6 +234,8 @@ agentcapmap evaluate inventory.json --format sarif -o agentcapmap.sarif --fail-o
 ```
 
 Exit codes: `0` passed, `1` findings at or above `--fail-on`, `2` usage or input error.
+On pull requests the action can also post one comment that shows only what the PR
+changed (`comment: "true"`; see the action docs).
 The repository is also a GitHub Action: see [docs/github-action.md](https://github.com/NKwolv/agent-capmap/blob/main/docs/github-action.md)
 and the [example workflow](https://github.com/NKwolv/agent-capmap/blob/main/docs/examples/agentcapmap.yml). By default the Action reads
 configs only, which is safe for pull requests from forks.

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/README.md

@@ -191,6 +191,8 @@ agentcapmap evaluate inventory.json --format sarif -o agentcapmap.sarif --fail-o
 ```
 
 Exit codes: `0` passed, `1` findings at or above `--fail-on`, `2` usage or input error.
+On pull requests the action can also post one comment that shows only what the PR
+changed (`comment: "true"`; see the action docs).
 The repository is also a GitHub Action: see [docs/github-action.md](https://github.com/NKwolv/agent-capmap/blob/main/docs/github-action.md)
 and the [example workflow](https://github.com/NKwolv/agent-capmap/blob/main/docs/examples/agentcapmap.yml). By default the Action reads
 configs only, which is safe for pull requests from forks.

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/action.yml

@@ -40,6 +40,17 @@ inputs:
   cache-dir:
     description: Classification cache directory (restore it with actions/cache).
     default: ""
+  comment:
+    description: >-
+      On pull_request events, compare with the base branch and post what changed (new
+      findings, newly unassessed servers, gained capabilities) as one comment that is
+      updated on later pushes (true/false). Config-only: it cannot be combined with
+      enumerate. Needs `pull-requests: write` and a checkout with `fetch-depth: 0`.
+      Forks get a read-only token, so there the diff goes to the job summary only.
+    default: "false"
+  github-token:
+    description: Token used to post the comment (only needs pull-requests write).
+    default: ${{ github.token }}
   sarif-file:
     description: Where to write the SARIF report, relative to the workspace.
     default: agentcapmap.sarif
@@ -135,3 +146,84 @@ runs:
         gate=(report "$evaluation" --fail-on "$INPUT_FAIL_ON" -o "${RUNNER_TEMP}/agentcapmap-gate.json")
         [[ "$INPUT_FAIL_ON_NOT_ASSESSED" == "true" ]] && gate+=(--fail-on-not-assessed)
         "$PY" -m agentcapmap "${gate[@]}"
+
+    - name: Compare with the base branch and comment
+      if: ${{ always() && inputs.comment == 'true' && github.event_name == 'pull_request' }}
+      shell: bash
+      env:
+        PY: ${{ steps.install.outputs.python }}
+        GH_TOKEN: ${{ inputs.github-token }}
+        BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+        REPO: ${{ github.repository }}
+        WORKSPACE: ${{ github.workspace }}
+        INPUT_PATH: ${{ inputs.path }}
+        INPUT_POLICY: ${{ inputs.policy }}
+        INPUT_BASELINE: ${{ inputs.baseline }}
+        INPUT_ENUMERATE: ${{ inputs.enumerate }}
+      run: |
+        set -uo pipefail
+        fail() { echo "::error title=agent-capmap::$1"; exit 2; }
+        soft() { echo "::warning title=agent-capmap::$1"; exit 0; }
+        [[ "$INPUT_ENUMERATE" == "false" ]] || fail "comment is for config-only pull request checks: enumerate runs the commands in the configs"
+        [[ "$BASE_SHA" =~ ^[0-9a-f]{40}$ ]] || fail "unexpected base commit"
+        [[ "$PR_NUMBER" =~ ^[0-9]+$ ]] || fail "unexpected pull request number"
+        [[ "$REPO" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$ ]] || fail "unexpected repository name"
+
+        head_eval="${RUNNER_TEMP}/agentcapmap-evaluation.json"
+        base_dir="${RUNNER_TEMP}/agentcapmap-base"
+        empty_dir="${RUNNER_TEMP}/agentcapmap-empty"
+        base_eval="${RUNNER_TEMP}/agentcapmap-base-evaluation.json"
+        diff_json="${RUNNER_TEMP}/agentcapmap-diff.json"
+        diff_md="${RUNNER_TEMP}/agentcapmap-diff.md"
+        body="${RUNNER_TEMP}/agentcapmap-comment.md"
+        abs() { if [[ "$1" == /* ]]; then printf '%s' "$1"; else printf '%s/%s' "$WORKSPACE" "$1"; fi; }
+
+        [[ -f "$head_eval" ]] || soft "no evaluation to compare (the scan step did not finish)"
+        git -C "$WORKSPACE" cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null           || soft "base commit not available: use actions/checkout with fetch-depth: 0 to enable the comparison"
+        git -C "$WORKSPACE" worktree add --detach "$base_dir" "$BASE_SHA" >/dev/null 2>&1           || soft "could not check out the base commit"
+        trap 'git -C "$WORKSPACE" worktree remove --force "$base_dir" >/dev/null 2>&1 || true' EXIT
+
+        # The head's policy and baseline are used for both sides, so only the pull
+        # request's own changes show up. A path that does not exist on the base yet
+        # (the PR adds the first MCP config there) is compared against nothing.
+        scan_target="$INPUT_PATH"
+        if [[ ! -e "$base_dir/$INPUT_PATH" ]]; then mkdir -p "$empty_dir"; scan_target="$empty_dir"; fi
+        args=(scan "$scan_target" --evaluate -o "$base_eval")
+        [[ -n "$INPUT_POLICY" ]] && args+=(--policy "$(abs "$INPUT_POLICY")")
+        [[ -n "$INPUT_BASELINE" ]] && args+=(--baseline "$(abs "$INPUT_BASELINE")")
+        (cd "$base_dir" && "$PY" -m agentcapmap "${args[@]}") || soft "could not scan the base commit"
+
+        "$PY" -m agentcapmap diff "$base_eval" "$head_eval" --format json -o "$diff_json" || fail "diff failed"
+        "$PY" -m agentcapmap diff "$base_eval" "$head_eval" --format markdown -o "$diff_md" || fail "diff failed"
+        cat "$diff_md" >> "$GITHUB_STEP_SUMMARY"
+
+        # Build the comment body (marker first, trimmed to GitHub's size limit) and say
+        # whether anything changed.
+        changed=$("$PY" - "$diff_json" "$diff_md" "$body" <<'EOF'
+        import json, sys
+        data = json.load(open(sys.argv[1], encoding="utf-8"))
+        text = open(sys.argv[2], encoding="utf-8").read()
+        if len(text) > 60000:
+            text = text[:60000] + "\n\n_Truncated; see the job summary._\n"
+        marker = "<!-- agent-capmap-diff -->"
+        open(sys.argv[3], "w", encoding="utf-8").write(marker + "\n" + text)
+        keys = ("new_findings", "resolved_findings", "gained_capabilities",
+                "lost_capabilities", "new_not_assessed")
+        print(1 if any(data[k] for k in keys) else 0)
+        EOF
+        )
+
+        command -v gh >/dev/null 2>&1 || soft "gh is not installed on this runner; the diff is in the job summary"
+        # Only update a comment this action's own bot wrote, never one that merely
+        # contains the marker.
+        existing=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments?per_page=100" --paginate           --jq '.[] | select(.user.login == "github-actions[bot]" and (.body | contains("<!-- agent-capmap-diff -->"))) | .id'           2>/dev/null | head -n1 || true)
+        if [[ "$changed" != "1" && -z "$existing" ]]; then
+          echo "No changes compared with the base; not commenting."
+          exit 0
+        fi
+        if [[ -n "$existing" && "$existing" =~ ^[0-9]+$ ]]; then
+          gh api --method PATCH "repos/${REPO}/issues/comments/${existing}" -F body=@"$body" >/dev/null             || soft "could not update the comment (forks get a read-only token); the diff is in the job summary"
+        else
+          gh api --method POST "repos/${REPO}/issues/${PR_NUMBER}/comments" -F body=@"$body" >/dev/null             || soft "could not post the comment (forks get a read-only token); the diff is in the job summary"
+        fi

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/docs/examples/agentcapmap.yml

@@ -31,15 +31,18 @@ jobs:
     permissions:
       contents: read # check out the code
       security-events: write # upload SARIF to code scanning
+      pull-requests: write # post the "what changed" comment
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          fetch-depth: 0 # the comment compares with the base commit
       - id: capmap
         uses: NKwolv/agent-capmap@<AGENT_CAPMAP_SHA>
         with:
           path: .
           fail-on: high
+          comment: "true" # posts new findings and newly added servers on the PR
       - name: Upload SARIF
         if: always() && steps.capmap.outputs.sarif-file != ''
         uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/docs/github-action.md

@@ -20,6 +20,8 @@ A complete example is in [`examples/agentcapmap.yml`](examples/agentcapmap.yml).
 | `classify` | `false` | Classify tools with the LLM. Needs `enumerate: true` and `ANTHROPIC_API_KEY` (unless `offline`). |
 | `offline` | `false` | Classify from the cache only. |
 | `cache-dir` | none | Classification cache directory; restore it with `actions/cache`. |
+| `comment` | `false` | On `pull_request`, post what changed against the base branch as one comment (see below). Config-only; cannot be combined with `enumerate`. |
+| `github-token` | `github.token` | Token used to post the comment. |
 | `sarif-file` | `agentcapmap.sarif` | Where to write SARIF (relative path inside the workspace). |
 | `python-version` | `3.12` | Python used to run agent-capmap. |
 
@@ -29,6 +31,30 @@ Exit status: the action fails when a finding is at or above `fail-on` (or, with
 `fail-on-not-assessed`, when anything was not assessed). The SARIF file and summary
 are written first, so upload them in a step with `if: always()`.
 
+## Pull request comment
+
+With `comment: "true"`, the action scans the base commit as well, compares the two with
+`agentcapmap diff`, and posts a single comment that lists **new findings**, **newly
+unassessed servers** (in config-only mode this is how an added MCP server shows up),
+gained capabilities and resolved findings. The comment is updated on every push instead
+of adding new ones, and nothing is posted when nothing changed and there is no earlier
+comment. The same text goes to the job summary.
+
+Requirements:
+
+- `permissions: pull-requests: write` on the job (plus `contents: read`).
+- `actions/checkout` with `fetch-depth: 0`, so the base commit is available. Without it
+  the comparison is skipped with a warning.
+- The `pull_request` event. Do not use `pull_request_target` to get write access on
+  forks: that runs with secrets against untrusted code. On a fork the token is read-only,
+  so the comment cannot be posted and the diff appears in the job summary only.
+- Not with `enumerate: "true"`: the comment mode never starts servers, so it is safe on
+  pull requests.
+
+The head's policy and baseline are used for both sides, so only the pull request's own
+changes appear. A bot comment is only ever updated if the `github-actions[bot]` user
+wrote it and it carries the action's hidden marker.
+
 ## Choosing a mode
 
 | Mode | When | What it catches |

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/examples/demo/inventory.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1",
-  "tool_version": "0.1.0",
+  "tool_version": "0.1.1",
   "agents": [
     {
       "id": "generic:fixtures/clean/mcp.json",

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-capmap"
-version = "0.1.0"
+version = "0.1.1"
 description = "Inventory the MCP tools reachable by AI agents and flag dangerous capability combinations with policy-as-code."
 readme = "README.md"
 license = "MIT"

agent_capmap-0.1.1/scripts/prepare_release.py

@@ -0,0 +1,158 @@
+"""Prepare a release: bump the version everywhere and date the changelog.
+
+    python scripts/prepare_release.py 0.1.1            # edit the files
+    python scripts/prepare_release.py 0.1.1 --dry-run  # only report what would change
+
+It refuses to run unless the working tree is clean, the version is a plain X.Y.Z that
+is higher than the current one, `[Unreleased]` in CHANGELOG.md has entries, and the
+bundled reference labels match `eval/labeled_servers/`. It never commits, tags or
+pushes: it prints the remaining steps for you to run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import re
+import subprocess  # nosec B404
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PYPROJECT = ROOT / "pyproject.toml"
+INIT = ROOT / "src" / "agentcapmap" / "__init__.py"
+CHANGELOG = ROOT / "CHANGELOG.md"
+
+_SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
+_PYPROJECT_VERSION = re.compile(r'^version = "([^"]+)"$', re.MULTILINE)
+_INIT_VERSION = re.compile(r'^__version__ = "([^"]+)"$', re.MULTILINE)
+_UNRELEASED = "## [Unreleased]\n"
+
+
+class ReleaseError(ValueError):
+    pass
+
+
+def parse_version(text: str) -> tuple[int, int, int]:
+    match = _SEMVER.match(text)
+    if not match:
+        raise ReleaseError(f"{text!r} is not a plain X.Y.Z version")
+    major, minor, patch = (int(part) for part in match.groups())
+    return major, minor, patch
+
+
+def current_version(pyproject: str, init: str) -> str:
+    in_pyproject = _PYPROJECT_VERSION.search(pyproject)
+    in_init = _INIT_VERSION.search(init)
+    if not in_pyproject or not in_init:
+        raise ReleaseError("cannot find the version in pyproject.toml or __init__.py")
+    if in_pyproject.group(1) != in_init.group(1):
+        raise ReleaseError(
+            f"pyproject.toml says {in_pyproject.group(1)} but __init__.py says "
+            f"{in_init.group(1)}: fix that first"
+        )
+    return in_pyproject.group(1)
+
+
+def unreleased_entries(changelog: str) -> str:
+    """The text under `## [Unreleased]`, up to the next `## ` heading."""
+    start = changelog.find(_UNRELEASED)
+    if start == -1:
+        raise ReleaseError("CHANGELOG.md has no '## [Unreleased]' heading")
+    body = changelog[start + len(_UNRELEASED) :]
+    end = body.find("\n## ")
+    return (body if end == -1 else body[:end]).strip()
+
+
+def bump(
+    version: str, date: str, pyproject: str, init: str, changelog: str
+) -> tuple[str, str, str]:
+    """Return the new text of (pyproject.toml, __init__.py, CHANGELOG.md)."""
+    old = current_version(pyproject, init)
+    if parse_version(version) <= parse_version(old):
+        raise ReleaseError(f"{version} is not higher than the current version {old}")
+    if not unreleased_entries(changelog):
+        raise ReleaseError("nothing under '## [Unreleased]' in CHANGELOG.md: describe the changes")
+    if f"## [{version}]" in changelog:
+        raise ReleaseError(f"CHANGELOG.md already has a section for {version}")
+    return (
+        _PYPROJECT_VERSION.sub(f'version = "{version}"', pyproject, count=1),
+        _INIT_VERSION.sub(f'__version__ = "{version}"', init, count=1),
+        changelog.replace(_UNRELEASED, f"{_UNRELEASED}\n## [{version}] - {date}\n", 1),
+    )
+
+
+def _git(*args: str) -> str:
+    # Fixed argument lists, no shell, no user input.
+    result = subprocess.run(  # noqa: S603  # nosec B603
+        ["git", *args],  # noqa: S607  # nosec B607
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout
+
+
+def _reference_labels_stale() -> bool:
+    sys.path.insert(0, str(ROOT / "scripts"))
+    import build_reference_labels as build  # type: ignore[import-not-found]
+
+    from agentcapmap.classify.reference import dump_bundle
+    from agentcapmap.evaluation import load_labeled_servers
+
+    expected = dump_bundle(build.build_bundle(load_labeled_servers(build.LABELS_DIR)))
+    current = build.BUNDLE_PATH.read_text(encoding="utf-8") if build.BUNDLE_PATH.is_file() else ""
+    return bool(current != expected)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0] if __doc__ else None)
+    parser.add_argument("version", help="new version, X.Y.Z")
+    parser.add_argument("--date", default=datetime.date.today().isoformat(), help="YYYY-MM-DD")
+    parser.add_argument("--dry-run", action="store_true", help="report only; change nothing")
+    args = parser.parse_args()
+
+    try:
+        if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", args.date):
+            raise ReleaseError("--date must be YYYY-MM-DD")
+        if _git("status", "--porcelain").strip():
+            raise ReleaseError("the working tree is not clean: commit or stash first")
+        if _reference_labels_stale():
+            raise ReleaseError(
+                "reference_labels.json is out of date: run scripts/build_reference_labels.py"
+            )
+        new = bump(
+            args.version,
+            args.date,
+            PYPROJECT.read_text(encoding="utf-8"),
+            INIT.read_text(encoding="utf-8"),
+            CHANGELOG.read_text(encoding="utf-8"),
+        )
+    except (ReleaseError, subprocess.CalledProcessError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.dry_run:
+        print(
+            f"would release {args.version} ({args.date}): pyproject.toml, __init__.py, CHANGELOG.md"
+        )
+        return 0
+    for path, text in zip((PYPROJECT, INIT, CHANGELOG), new, strict=True):
+        path.write_text(text, encoding="utf-8", newline="\n")
+    print(
+        f"Prepared {args.version}. Next:\n"
+        "  1. AGENTCAPMAP_UPDATE_GOLDEN=1 python -m pytest tests/test_fixtures.py   "
+        "(the demo inventory stamps the version), then python scripts/check.py\n"
+        f'  2. git commit -am "Release {args.version}" && git push origin main\n'
+        "  3. wait for CI on that commit to pass\n"
+        f'  4. git tag -a v{args.version} -m "agent-capmap {args.version}" '
+        f"&& git push origin v{args.version}\n"
+        "  5. approve the 'pypi' deployment, then confirm the release on PyPI\n"
+        "  6. update the NKwolv/agent-capmap@<sha> pin in docs/examples/agentcapmap.yml"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/src/agentcapmap/__init__.py

@@ -1,3 +1,3 @@
 """agent-capmap: map the MCP capabilities reachable by AI agents."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/src/agentcapmap/diff.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from pydantic import BaseModel, Field
 
-from agentcapmap.findings import Evaluation, Finding, Severity
+from agentcapmap.findings import Evaluation, Finding, NotAssessed, Severity
 from agentcapmap.report._text import md_code
 
 _MAX_ROWS = 100
@@ -25,6 +25,19 @@ class EvaluationDiff(BaseModel):
     resolved_findings: list[Finding] = Field(default_factory=list)
     gained_capabilities: list[CapabilityChange] = Field(default_factory=list)
     lost_capabilities: list[CapabilityChange] = Field(default_factory=list)
+    # Servers or tools that could not be assessed now but were not before: in config-only
+    # mode this is how a newly added MCP server shows up.
+    new_not_assessed: list[NotAssessed] = Field(default_factory=list)
+
+    @property
+    def changed(self) -> bool:
+        return bool(
+            self.new_findings
+            or self.resolved_findings
+            or self.gained_capabilities
+            or self.lost_capabilities
+            or self.new_not_assessed
+        )
 
 
 def _capabilities(evaluation: Evaluation) -> dict[tuple[str, str], list[str]]:
@@ -49,11 +62,15 @@ def diff_evaluations(old: Evaluation, new: Evaluation) -> EvaluationDiff:
     old_prints = {f.fingerprint for f in old.findings}
     new_prints = {f.fingerprint for f in new.findings}
     old_caps, new_caps = _capabilities(old), _capabilities(new)
+    seen = {(n.agent_id, n.server, n.tool) for n in old.not_assessed}
     return EvaluationDiff(
         new_findings=[f for f in new.findings if f.fingerprint not in old_prints],
         resolved_findings=[f for f in old.findings if f.fingerprint not in new_prints],
         gained_capabilities=_changes(new_caps, old_caps),
         lost_capabilities=_changes(old_caps, new_caps),
+        new_not_assessed=[
+            n for n in new.not_assessed if (n.agent_id, n.server, n.tool) not in seen
+        ],
     )
 
 
@@ -94,10 +111,33 @@ def _finding_lines(title: str, findings: list[Finding]) -> list[str]:
     return [*lines, ""]
 
 
+def _not_assessed_lines(items: list[NotAssessed]) -> list[str]:
+    lines = [f"## Newly not assessed ({len(items)})", ""]
+    if not items:
+        return [*lines, "None.", ""]
+    for item in items[:_MAX_ROWS]:
+        where = f"{item.server}/{item.tool}" if item.tool else item.server
+        lines.append(f"- {md_code(where, 160)}: {md_code(item.reason, 200)}")
+    if len(items) > _MAX_ROWS:
+        lines.append(f"- ... and {len(items) - _MAX_ROWS} more")
+    return [*lines, ""]
+
+
 def render_markdown(diff: EvaluationDiff) -> str:
     lines = ["# agent-capmap diff", ""]
+    if diff.changed:
+        lines += [
+            f"{len(diff.new_findings)} new finding(s), "
+            f"{len(diff.gained_capabilities)} gained capability(ies), "
+            f"{len(diff.new_not_assessed)} newly not assessed, "
+            f"{len(diff.resolved_findings)} resolved.",
+            "",
+        ]
+    else:
+        lines += ["No changes compared with the base.", ""]
     lines += _finding_lines("New findings", diff.new_findings)
     lines += _capability_lines("Gained capabilities", diff.gained_capabilities)
+    lines += _not_assessed_lines(diff.new_not_assessed)
     lines += _finding_lines("Resolved findings", diff.resolved_findings)
     lines += _capability_lines("Lost capabilities", diff.lost_capabilities)
     return "\n".join(lines)

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/tests/test_diff.py

@@ -92,3 +92,29 @@ def test_markdown_renders_hostile_text_inertly(risky: Evaluation) -> None:
     text = render_markdown(diff)
     assert "`[click](http://evil) <b>x</b>`" in text
     assert text.startswith("# agent-capmap diff")
+
+
+def test_newly_not_assessed_servers_are_reported(risky: Evaluation) -> None:
+    from agentcapmap.findings import NotAssessed
+
+    base = risky.model_copy(update={"not_assessed": []})
+    added = NotAssessed(
+        agent_id="a", server="new-server", reason="tools not enumerated (run scan with --enumerate)"
+    )
+    head = risky.model_copy(update={"not_assessed": [added]})
+    diff = diff_evaluations(base, head)
+    assert diff.new_not_assessed == [added]
+    # Already-unassessed items are not "new".
+    assert diff_evaluations(head, head).new_not_assessed == []
+    assert "`new-server`" in render_markdown(diff)
+    assert not should_fail_diff(diff, Severity.INFO, True)  # informational only
+
+
+def test_changed_flag_and_summary_line(risky: Evaluation) -> None:
+    same = diff_evaluations(risky, risky)
+    assert same.changed is False
+    assert "No changes compared with the base." in render_markdown(same)
+    different = diff_evaluations(_emptied(risky), risky)
+    assert different.changed is True
+    summary = render_markdown(different).splitlines()[2]
+    assert summary.startswith(f"{len(different.new_findings)} new finding(s), ")

{agent_capmap-0.1.0 → agent_capmap-0.1.1}/tests/test_fixtures.py

@@ -60,7 +60,7 @@ def test_golden_findings(name: str) -> None:
     actual = _golden_view(_evaluate(name))
     golden = FIXTURES / name / "expected.json"
     if UPDATE_GOLDEN:
-        golden.write_text(json.dumps(actual, indent=2) + "\n", encoding="utf-8")
+        golden.write_text(json.dumps(actual, indent=2) + "\n", encoding="utf-8", newline="\n")
     assert actual == json.loads(golden.read_text(encoding="utf-8"))
 
 
@@ -163,7 +163,7 @@ def build_demo_inventory() -> str:
 def test_demo_inventory_is_current() -> None:
     expected = build_demo_inventory()
     if UPDATE_GOLDEN:
-        DEMO.write_text(expected, encoding="utf-8")
+        DEMO.write_text(expected, encoding="utf-8", newline="\n")
     assert DEMO.read_text(encoding="utf-8") == expected, "run with AGENTCAPMAP_UPDATE_GOLDEN=1"