sourcecode 1.32.3__tar.gz → 1.32.5__tar.gz

{sourcecode-1.32.3 → sourcecode-1.32.5}/PKG-INFO

@@ -1,193 +1,7 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.32.3
+Version: 1.32.5
 Summary: Deterministic codebase context for AI coding agents
-License:                                  Apache License
-                                   Version 2.0, January 2004
-                                http://www.apache.org/licenses/
-        
-           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-        
-           1. Definitions.
-        
-              "License" shall mean the terms and conditions for use, reproduction,
-              and distribution as defined by Sections 1 through 9 of this document.
-        
-              "Licensor" shall mean the copyright owner or entity authorized by
-              the copyright owner that is granting the License.
-        
-              "Legal Entity" shall mean the union of the acting entity and all
-              other entities that control, are controlled by, or are under common
-              control with that entity. For the purposes of this definition,
-              "control" means (i) the power, direct or indirect, to cause the
-              direction or management of such entity, whether by contract or
-              otherwise, or (ii) ownership of fifty percent (50%) or more of the
-              outstanding shares, or (iii) beneficial ownership of such entity.
-        
-              "You" (or "Your") shall mean an individual or Legal Entity
-              exercising permissions granted by this License.
-        
-              "Source" form shall mean the preferred form for making modifications,
-              including but not limited to software source code, documentation
-              source, and configuration files.
-        
-              "Object" form shall mean any form resulting from mechanical
-              transformation or translation of a Source form, including but
-              not limited to compiled object code, generated documentation,
-              and conversions to other formats.
-        
-              "Work" shall mean the work of authorship made available under
-              the License, as indicated by a copyright notice that is included in
-              or attached to the work (an example is provided in the Appendix below).
-        
-              "Derivative Works" shall mean any work, whether in Source or Object
-              form, that is based on (or derived from) the Work and for which the
-              editorial revisions, annotations, elaborations, or other transformations
-              represent, as a whole, an original work of authorship. For the purposes
-              of this License, Derivative Works shall not include works that remain
-              separable from, or merely link (or bind by name) to the interfaces of,
-              the Work and Derivative Works thereof.
-        
-              "Contribution" shall mean, as submitted to the Licensor for inclusion
-              in the Work by the copyright owner or by an individual or Legal Entity
-              authorized to submit on behalf of the copyright owner. For the purposes
-              of this definition, "submit" means any form of electronic, verbal, or
-              written communication sent to the Licensor or its representatives,
-              including but not limited to communication on electronic mailing lists,
-              source code control systems, and issue tracking systems that are managed
-              by, or on behalf of, the Licensor for the purpose of discussing and
-              improving the Work, but excluding communication that is conspicuously
-              marked or designated in writing by the copyright owner as "Not a
-              Contribution."
-        
-              "Contributor" shall mean Licensor and any Legal Entity on behalf of
-              whom a Contribution has been received by the Licensor and included
-              within the Work.
-        
-           2. Grant of Copyright License. Subject to the terms and conditions of
-              this License, each Contributor hereby grants to You a perpetual,
-              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-              copyright license to reproduce, prepare Derivative Works of,
-              publicly display, publicly perform, sublicense, and distribute the
-              Work and such Derivative Works in Source or Object form.
-        
-           3. Grant of Patent License. Subject to the terms and conditions of
-              this License, each Contributor hereby grants to You a perpetual,
-              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-              (except as stated in this section) patent license to make, have made,
-              use, offer to sell, sell, import, and otherwise transfer the Work,
-              where such license applies only to those patent claims licensable
-              by such Contributor that are necessarily infringed by their
-              Contribution(s) alone or by the combination of their Contribution(s)
-              with the Work to which such Contribution(s) was submitted. If You
-              institute patent litigation against any entity (including a cross-claim
-              or counterclaim in a lawsuit) alleging that the Work or any Contributor
-              Contribution constitutes direct or contributory patent infringement,
-              then any patent rights granted to You under this License for that Work
-              shall terminate as of the date such litigation is filed.
-        
-           4. Redistribution. You may reproduce and distribute copies of the
-              Work or Derivative Works thereof in any medium, with or without
-              modifications, and in Source or Object form, provided that You
-              meet the following conditions:
-        
-              (a) You must give any other recipients of the Work or Derivative
-                  Works a copy of this License; and
-        
-              (b) You must cause any modified files to carry prominent notices
-                  stating that You changed the files; and
-        
-              (c) You must retain, in the Source form of any Derivative Works
-                  that You distribute, all copyright, patent, trademark, and
-                  attribution notices from the Source form of the Work,
-                  excluding those notices that do not pertain to any part of
-                  the Derivative Works; and
-        
-              (d) If the Work includes a "NOTICE" text file as part of its
-                  distribution, You must include a readable copy of the
-                  attribution notices contained within such NOTICE file, in
-                  at least one of the following places: within a NOTICE text
-                  file distributed as part of the Derivative Works; within
-                  the Source form or documentation, if provided along with the
-                  Derivative Works; or, within a display generated by the
-                  Derivative Works, if and wherever such third-party notices
-                  normally appear. The contents of the NOTICE file are for
-                  informational purposes only and do not modify the License.
-                  You may add Your own attribution notices within Derivative
-                  Works that You distribute, alongside or in addition to the
-                  NOTICE text from the Work, provided that such additional
-                  attribution notices cannot be construed as modifying the License.
-        
-              You may add Your own license statement for Your modifications and
-              may provide additional grant of rights to use, copy, modify, merge,
-              publish, distribute, sublicense, and/or sell copies of the
-              Derivative Works, as separate terms and conditions for their use,
-              reproduction, and distribution, or alongside or as supplement to
-              any license terms for such Derivative Works as a whole, provided
-              Your use, reproduction, and distribution of the Work otherwise
-              complies with the conditions stated in this License.
-        
-           5. Submission of Contributions. Unless You explicitly state otherwise,
-              any Contribution intentionally submitted for inclusion in the Work
-              by You to the Licensor shall be under the terms and conditions of
-              this License, without any additional terms or conditions.
-              Notwithstanding the above, nothing herein shall supersede or modify
-              the terms of any separate license agreement you may have executed
-              with Licensor regarding such Contributions.
-        
-           6. Trademarks. This License does not grant permission to use the trade
-              names, trademarks, service marks, or product names of the Licensor,
-              except as required for reasonable and customary use in describing the
-              origin of the Work and reproducing the content of the NOTICE file.
-        
-           7. Disclaimer of Warranty. Unless required by applicable law or
-              agreed to in writing, Licensor provides the Work (and each
-              Contributor provides its Contributions) on an "AS IS" BASIS,
-              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-              implied, including, without limitation, any warranties or conditions
-              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-              PARTICULAR PURPOSE. You are solely responsible for determining the
-              appropriateness of using or reproducing the Work and assume any
-              risks associated with Your exercise of permissions under this License.
-        
-           8. Limitation of Liability. In no event and under no legal theory,
-              whether in tort (including negligence), contract, or otherwise,
-              unless required by applicable law (such as deliberate and grossly
-              negligent acts) or agreed to in writing, shall any Contributor be
-              liable to You for damages, including any direct, indirect, special,
-              incidental, or exemplary damages of any character arising as a
-              result of this License or out of the use or inability to use the
-              Work (including but not limited to damages for loss of goodwill,
-              work stoppage, computer failure or malfunction, or all other
-              commercial damages or losses), even if such Contributor has been
-              advised of the possibility of such damages.
-        
-           9. Accepting Warranty or Liability. While redistributing the Work or
-              Derivative Works thereof, You may choose to offer, and charge a fee
-              for, acceptance of support, warranty, indemnity, or other liability
-              obligations and/or rights consistent with this License. However, in
-              accepting such obligations, You may offer such obligations only on
-              Your own behalf and on Your sole responsibility, not on behalf of
-              any other Contributor, and only if You agree to indemnify, defend,
-              and hold each Contributor harmless for any liability incurred by,
-              or claims asserted against, such Contributor by reason of your
-              accepting any warranty or additional liability.
-        
-           END OF TERMS AND CONDITIONS
-        
-           Copyright 2024 sourcecode contributors
-        
-           Licensed under the Apache License, Version 2.0 (the "License");
-           you may not use this file except in compliance with the License.
-           You may obtain a copy of the License at
-        
-               http://www.apache.org/licenses/LICENSE-2.0
-        
-           Unless required by applicable law or agreed to in writing, software
-           distributed under the License is distributed on an "AS IS" BASIS,
-           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-           See the License for the specific language governing permissions and
-           limitations under the License.
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
 Classifier: Development Status :: 4 - Beta

{sourcecode-1.32.3 → sourcecode-1.32.5}/pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.32.3"
+version = "1.32.5"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"
-license = { file = "LICENSE" }
+license-expression = "Apache-2.0"
+license-files = ["LICENSE"]
 keywords = ["ai", "llm", "agents", "context", "codebase", "developer-tools"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -55,6 +56,17 @@ mcp = [
 module = ["tree_sitter", "tree_sitter_typescript", "tree_sitter_javascript"]
 ignore_missing_imports = true
 
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "tests/",
+    "docs/",
+    "/AUDIT*.md",
+    "/.agents",
+    "/.continue-here.md",
+    "/.sourcecode-cache",
+    "/run_cli.py",
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/sourcecode"]
 

{sourcecode-1.32.3 → sourcecode-1.32.5}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.32.3"
+__version__ = "1.32.5"

{sourcecode-1.32.3 → sourcecode-1.32.5}/src/sourcecode/cache.py

@@ -72,6 +72,11 @@ SCHEMA_VERSION: str = "2"
 #: Bump to invalidate all L1 core caches (independent of snapshot version).
 CORE_SCHEMA_VERSION: str = "1"
 
+#: Bump when analysis logic or output schema changes — NOT on every package release.
+#: This is the stable part of the L1 core cache key.  Package version bumps (patch,
+#: minor) must NOT bump this value unless the cached data format actually changed.
+ANALYZER_CACHE_VERSION: str = "1"
+
 #: Fields eligible for CAS deduplication (applied to top-level JSON dict keys).
 _CAS_FIELDS: frozenset[str] = frozenset([
     "file_paths",
@@ -92,6 +97,8 @@ _CAS_FIELDS: frozenset[str] = frozenset([
 _CAS_THRESHOLD: int = 4096
 
 _DEFAULT_KEEP_COMMITS: int = 5
+_DEFAULT_MAX_CORES: int = 20
+_DEFAULT_MAX_SIZE_MB: int = 50
 
 # Matches "snapshot-<hex_commit>-<hex_flags>.json.gz"
 _SNAPSHOT_RE = re.compile(r"^snapshot-([0-9a-f]+)-[0-9a-f]+\.json\.gz$")
@@ -124,6 +131,58 @@ def cache_dir(repo_root: Path) -> Path:
     return base / repo_id(repo_root)
 
 
+# ---------------------------------------------------------------------------
+# Public API — observability
+# ---------------------------------------------------------------------------
+
+def status(repo_root: Path) -> dict[str, Any]:
+    """Return a stats dict describing the current cache state for *repo_root*.
+
+    Keys: ``cache_dir``, ``cores``, ``snapshots``, ``views``, ``cas_blobs``,
+    ``total_size_bytes``, ``total_size_mb``.
+    """
+    cache_d = cache_dir(repo_root)
+    if not cache_d.exists():
+        return {
+            "cache_dir": str(cache_d),
+            "cores": 0, "snapshots": 0, "views": 0, "cas_blobs": 0,
+            "total_size_bytes": 0, "total_size_mb": 0.0,
+        }
+    cores = list(cache_d.glob("core-*.json.gz"))
+    snapshots = list(cache_d.glob("snapshot-*.json.gz"))
+    views = list(cache_d.glob("view-*.json.gz"))
+    cas_blobs = list((_cas_dir(cache_d)).glob("*.gz")) if _cas_dir(cache_d).exists() else []
+    all_files = cores + snapshots + views + cas_blobs
+    total_bytes = sum(f.stat().st_size for f in all_files if f.exists())
+    return {
+        "cache_dir": str(cache_d),
+        "cores": len(cores),
+        "snapshots": len(snapshots),
+        "views": len(views),
+        "cas_blobs": len(cas_blobs),
+        "total_size_bytes": total_bytes,
+        "total_size_mb": round(total_bytes / (1024 * 1024), 2),
+    }
+
+
+def clear(repo_root: Path) -> int:
+    """Delete all cache files for *repo_root*.  Returns the number of files removed."""
+    cache_d = cache_dir(repo_root)
+    if not cache_d.exists():
+        return 0
+    removed = 0
+    for pattern in ("core-*.json.gz", "snapshot-*.json.gz", "view-*.json.gz"):
+        for f in cache_d.glob(pattern):
+            _safe_unlink(f)
+            removed += 1
+    cas_d = _cas_dir(cache_d)
+    if cas_d.exists():
+        for f in cas_d.glob("*.gz"):
+            _safe_unlink(f)
+            removed += 1
+    return removed
+
+
 # ---------------------------------------------------------------------------
 # Public API — read / write
 # ---------------------------------------------------------------------------
@@ -193,7 +252,7 @@ def write(
     try:
         cache_d.mkdir(parents=True, exist_ok=True)
         payload = _build_envelope(cache_key, content, fmt, layers or {}, cache_d)
-        dest.write_bytes(payload)
+        _atomic_write(dest, payload)
     except Exception:
         return  # non-fatal
 
@@ -275,7 +334,7 @@ def write_core(repo_root: Path, core_key: str, core_data: dict[str, Any]) -> str
             json.dumps(envelope, ensure_ascii=False).encode("utf-8"),
             compresslevel=6,
         )
-        dest.write_bytes(payload)
+        _atomic_write(dest, payload)
     except Exception:
         pass
 
@@ -327,7 +386,7 @@ def write_view(
     try:
         cache_d.mkdir(parents=True, exist_ok=True)
         payload = _build_envelope(view_key, content, fmt, layers or {}, cache_d)
-        dest.write_bytes(payload)
+        _atomic_write(dest, payload)
     except Exception:
         pass
 
@@ -457,7 +516,7 @@ def _cas_store_blob(cache_d: Path, serialised: str) -> str:
     path = _cas_path(cache_d, blob_hash)
     if not path.exists():
         path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_bytes(gzip.compress(raw, compresslevel=6))
+        _atomic_write(path, gzip.compress(raw, compresslevel=6))
     return blob_hash
 
 
@@ -529,12 +588,16 @@ def _cas_restore(
 def _gc(cache_d: Path) -> None:
     """Evict old snapshots/cores/views and sweep orphaned CAS blobs.
 
-    Keeps snapshots and cores from the last ``SOURCECODE_CACHE_KEEP_COMMITS``
-    distinct git commits (determined by newest mtime within each commit group).
-    Views are then pruned: a view survives only when its core-hash prefix
-    matches a core file in the surviving set.
+    Three eviction passes (all non-fatal):
+    1. Commit-based: keep only last SOURCECODE_CACHE_KEEP_COMMITS distinct SHAs.
+    2. Core-count: keep at most SOURCECODE_CACHE_MAX_CORES core files (LRU).
+    3. Size-based: if total cache exceeds SOURCECODE_CACHE_MAX_SIZE_MB, evict
+       oldest core+snapshot files until under budget.
+    Views and CAS blobs are swept after each pass.
     """
     keep = int(os.environ.get("SOURCECODE_CACHE_KEEP_COMMITS", _DEFAULT_KEEP_COMMITS))
+    max_cores = int(os.environ.get("SOURCECODE_CACHE_MAX_CORES", _DEFAULT_MAX_CORES))
+    max_size_bytes = int(os.environ.get("SOURCECODE_CACHE_MAX_SIZE_MB", _DEFAULT_MAX_SIZE_MB)) * 1024 * 1024
 
     try:
         all_snapshots = list(cache_d.glob("snapshot-*.json.gz"))
@@ -544,7 +607,7 @@ def _gc(cache_d: Path) -> None:
         if not all_snapshots and not all_cores and not all_views:
             return
 
-        # Group snapshot + core files by commit SHA
+        # ── Pass 1: commit-based eviction ──────────────────────────────────
         groups: dict[str, list[Path]] = {}
         for f in all_snapshots:
             m = _SNAPSHOT_RE.match(f.name)
@@ -558,7 +621,6 @@ def _gc(cache_d: Path) -> None:
         surviving: list[Path]
 
         if keep <= 0 or len(groups) <= keep:
-            # No eviction needed — but still sweep views + CAS
             surviving = all_snapshots + all_cores
         else:
             def _newest_mtime(commit: str) -> float:
@@ -573,7 +635,37 @@ def _gc(cache_d: Path) -> None:
                     for f in groups[commit]:
                         _safe_unlink(f)
 
+        # ── Pass 2: per-repo core count cap ────────────────────────────────
+        if max_cores > 0:
+            surviving_cores = [p for p in surviving if p.name.startswith("core-") and p.exists()]
+            if len(surviving_cores) > max_cores:
+                surviving_cores.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+                for evict in surviving_cores[max_cores:]:
+                    _safe_unlink(evict)
+                    surviving = [p for p in surviving if p != evict]
+
+        # ── Pass 3: total size cap ──────────────────────────────────────────
+        if max_size_bytes > 0:
+            size_candidates = [p for p in surviving if p.exists()]
+            # Include CAS blobs in the size budget calculation
+            cas_d_sz = _cas_dir(cache_d)
+            cas_files = list(cas_d_sz.glob("*.gz")) if cas_d_sz.exists() else []
+            total = sum(p.stat().st_size for p in size_candidates if not p.name.startswith("view-"))
+            total += sum(p.stat().st_size for p in cas_files if p.exists())
+            if total > max_size_bytes:
+                # Sort oldest-first; evict core+snapshot files until under budget
+                size_candidates.sort(key=lambda p: p.stat().st_mtime)
+                for evict in size_candidates:
+                    if evict.name.startswith("view-"):
+                        continue
+                    total -= evict.stat().st_size if evict.exists() else 0
+                    _safe_unlink(evict)
+                    surviving = [p for p in surviving if p != evict]
+                    if total <= max_size_bytes:
+                        break
+
         # Prune view files whose core hash is no longer in the surviving set
+        all_views = list(cache_d.glob("view-*.json.gz"))
         _gc_views(cache_d, surviving, all_views)
 
         # Sweep orphaned CAS blobs (surviving snapshots + view files may ref them)
@@ -648,6 +740,23 @@ def _gc_cas(cache_d: Path, surviving_snapshots: list[Path]) -> None:
 # Utilities
 # ---------------------------------------------------------------------------
 
+def _atomic_write(dest: Path, data: bytes) -> None:
+    """Write *data* to *dest* atomically via a sibling .tmp file + rename.
+
+    On POSIX, ``Path.replace()`` is a single ``rename(2)`` syscall — the
+    destination either has the old content or the new content, never a partial
+    write.  The .tmp suffix keeps the partial file out of glob patterns used
+    by the cache reader and GC.
+    """
+    tmp = dest.with_suffix(".tmp")
+    try:
+        tmp.write_bytes(data)
+        tmp.replace(dest)
+    except Exception:
+        _safe_unlink(tmp)
+        raise
+
+
 def _safe_unlink(path: Path) -> None:
     try:
         path.unlink(missing_ok=True)