specsmith 0.18.0.dev690__tar.gz → 0.18.0.dev692__tar.gz

{specsmith-0.18.0.dev690/src/specsmith.egg-info → specsmith-0.18.0.dev692}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.18.0.dev690
+Version: 0.18.0.dev692
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT

{specsmith-0.18.0.dev690 → specsmith-0.18.0.dev692}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.18.0.dev690"
+version = "0.18.0.dev692"
 description = "AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider."
 readme = "README.md"
 license = "MIT"

{specsmith-0.18.0.dev690 → specsmith-0.18.0.dev692}/src/specsmith/esdb/__init__.py

@@ -136,7 +136,10 @@ def open_default_store(
 
     from pathlib import Path
 
-    root = Path(str(project_root)).resolve()
+    # CodeQL py/path-injection: use os.path.realpath (recognised normaliser);
+    # the filesystem-path containment checks live in SqliteStore.__init__ and
+    # _maybe_promote_sqlite_to_chrono where the actual sinks are.
+    root = Path(_os.path.realpath(str(project_root)))
 
     # Priority 1: explicit override
     if _os.environ.get("SPECSMITH_ESDB_BACKEND", "").strip().lower() == "sqlite":
@@ -172,7 +175,11 @@ def _maybe_promote_sqlite_to_chrono(root: "object", chrono: "object") -> None:
     from pathlib import Path as _Path
 
     try:
-        sqlite_path = _Path(str(root)) / ".specsmith" / "esdb.sqlite3"
+        _r = os.path.realpath(str(root))
+        _sp = os.path.realpath(os.path.join(_r, ".specsmith", "esdb.sqlite3"))
+        if _sp != _r and not _sp.startswith(_r + os.sep):
+            return
+        sqlite_path = _Path(_sp)
         if not sqlite_path.exists():
             return
 

{specsmith-0.18.0.dev690 → specsmith-0.18.0.dev692}/src/specsmith/esdb/sqlite_store.py

@@ -150,8 +150,15 @@ class SqliteStore:
     """
 
     def __init__(self, project_root: str | Path) -> None:
-        self.root = Path(project_root).resolve()
-        self._db_path = self.root / ".specsmith" / _DB_FILENAME
+        # CodeQL py/path-injection: normalize with os.path.realpath AND assert the
+        # DB path stays within the project root (containment), then store the
+        # sanitised values so the open() sinks (mkdir/connect) receive clean paths.
+        _root = os.path.realpath(str(project_root))
+        _db = os.path.realpath(os.path.join(_root, ".specsmith", _DB_FILENAME))
+        if _db != _root and not _db.startswith(_root + os.sep):
+            raise ValueError(f"Database path escapes project root: {_db!r}")
+        self.root = Path(_root)
+        self._db_path = Path(_db)
         self._conn: sqlite3.Connection | None = None
         self._open: bool = False
 
@@ -415,10 +422,15 @@ class SqliteStore:
         Returns a dict with counts: ``{"requirements": N, "testcases": M, "skipped": K}``.
         Already-present records (by ID) are updated in-place.
         """
-        state_dir = Path(specsmith_dir)
+        # CodeQL py/path-injection: normalize + containment-check each JSON path
+        # before the .exists()/.read_text() sinks below.
+        _state = os.path.realpath(str(specsmith_dir))
         counts: dict[str, int] = {"requirements": 0, "testcases": 0, "skipped": 0}
 
-        req_path = state_dir / "requirements.json"
+        _req = os.path.realpath(os.path.join(_state, "requirements.json"))
+        if _req != _state and not _req.startswith(_state + os.sep):
+            raise ValueError(f"Path escapes state directory: {_req!r}")
+        req_path = Path(_req)
         if req_path.exists():
             try:
                 reqs = json.loads(req_path.read_text(encoding="utf-8"))
@@ -439,7 +451,10 @@ class SqliteStore:
             except (OSError, ValueError):
                 counts["skipped"] += 1  # file unreadable or invalid JSON
 
-        test_path = state_dir / "testcases.json"
+        _test = os.path.realpath(os.path.join(_state, "testcases.json"))
+        if _test != _state and not _test.startswith(_state + os.sep):
+            raise ValueError(f"Path escapes state directory: {_test!r}")
+        test_path = Path(_test)
         if test_path.exists():
             try:
                 tests = json.loads(test_path.read_text(encoding="utf-8"))

{specsmith-0.18.0.dev690 → specsmith-0.18.0.dev692}/src/specsmith/governance_logic.py

@@ -98,10 +98,23 @@ def run_preflight(
     # traces the py/path-injection sanitiser inline; selecting between two
     # already-sanitised Paths does not re-taint.  infer_scope handles a
     # non-existent path gracefully (returns an empty scope).
-    _req_md_docs = Path(os.path.realpath(os.path.join(_safe_root, "docs", "REQUIREMENTS.md")))
-    _req_md_root = Path(os.path.realpath(os.path.join(_safe_root, "REQUIREMENTS.md")))
+    # CodeQL py/path-injection requires normalize (realpath) AND containment
+    # (startswith root), not normalization alone. Build each candidate as a
+    # realpath string, assert it stays within _safe_root, then wrap in Path so
+    # the sanitised value flows into infer_scope() and the .is_file() sinks.
+    _docs_str = os.path.realpath(os.path.join(_safe_root, "docs", "REQUIREMENTS.md"))
+    if _docs_str != _safe_root and not _docs_str.startswith(_safe_root + os.sep):
+        raise ValueError(f"Path escapes project root: {_docs_str!r}")
+    _root_md_str = os.path.realpath(os.path.join(_safe_root, "REQUIREMENTS.md"))
+    if _root_md_str != _safe_root and not _root_md_str.startswith(_safe_root + os.sep):
+        raise ValueError(f"Path escapes project root: {_root_md_str!r}")
+    _repo_idx_str = os.path.realpath(os.path.join(_safe_root, ".repo-index", "files.json"))
+    if _repo_idx_str != _safe_root and not _repo_idx_str.startswith(_safe_root + os.sep):
+        raise ValueError(f"Path escapes project root: {_repo_idx_str!r}")
+    _req_md_docs = Path(_docs_str)
+    _req_md_root = Path(_root_md_str)
     _req_md = _req_md_docs if _req_md_docs.is_file() else _req_md_root
-    _repo_idx = Path(os.path.realpath(os.path.join(_safe_root, ".repo-index", "files.json")))
+    _repo_idx = Path(_repo_idx_str)
     scope = infer_scope(
         utterance,
         _req_md,
@@ -122,7 +135,10 @@ def run_preflight(
     # Read requirements machine-state using os.path.join on the clean _root_str
     # so CodeQL traces the full sanitisation chain without re-tainting via Path.
     rq_records: list[Any] = []
-    rq_path = Path(os.path.realpath(os.path.join(_safe_root, ".specsmith", "requirements.json")))
+    rq_str = os.path.realpath(os.path.join(_safe_root, ".specsmith", "requirements.json"))
+    if rq_str != _safe_root and not rq_str.startswith(_safe_root + os.sep):
+        raise ValueError(f"Path escapes project root: {rq_str!r}")
+    rq_path = Path(rq_str)
     if rq_path.is_file():
         try:
             _rq = _json.loads(rq_path.read_text(encoding="utf-8"))
@@ -139,7 +155,10 @@ def run_preflight(
     # Read test-case machine-state (same rationale as above).
     test_case_ids: list[str] = []
     tc_records: list[Any] = []
-    tc_path = Path(os.path.realpath(os.path.join(_safe_root, ".specsmith", "testcases.json")))
+    tc_str = os.path.realpath(os.path.join(_safe_root, ".specsmith", "testcases.json"))
+    if tc_str != _safe_root and not tc_str.startswith(_safe_root + os.sep):
+        raise ValueError(f"Path escapes project root: {tc_str!r}")
+    tc_path = Path(tc_str)
     if tc_path.is_file():
         try:
             _tc = _json.loads(tc_path.read_text(encoding="utf-8"))

{specsmith-0.18.0.dev690 → specsmith-0.18.0.dev692}/src/specsmith/releaser.py

@@ -71,22 +71,57 @@ def bump_version(root: Path, new_version: str) -> list[str]:
     return updated
 
 
+# Context tokens that mark a *legitimate* "--pre specsmith" reference rather
+# than a stale stable-install instruction. The dev/pre-release channel is a
+# supported feature (see channel.py and docs/site/releasing.md), so docs that
+# describe it -- and explicit prohibitions ("NEVER run pip install --pre
+# specsmith") -- must not be flagged. Only a reference that recommends
+# installing the *stable* package with the pre-release flag is stale.
+_PRE_OK_CONTEXT: tuple[str, ...] = ("dev", "pre-release", "prerelease", "never", "badge")
+
+
+def _has_stale_pre_flag(content: str) -> bool:
+    """Return True if *content* has a stale ``--pre specsmith`` install hint.
+
+    The scan is line-aware and tracks the nearest Markdown heading so a
+    legitimate ``--pre specsmith`` reference inside a dev/pre-release section or
+    a prohibition line is ignored. An occurrence is only treated as stale when
+    neither its line nor the enclosing section carries a :data:`_PRE_OK_CONTEXT`
+    token.
+    """
+    current_heading = ""
+    for line in content.splitlines():
+        stripped = line.lstrip()
+        if stripped.startswith("#"):
+            current_heading = stripped
+        if "--pre specsmith" not in line:
+            continue
+        context = f"{line} {current_heading}".lower()
+        if any(token in context for token in _PRE_OK_CONTEXT):
+            continue
+        return True
+    return False
+
+
 def scan_stale_refs(root: Path, current_version: str) -> list[str]:
-    """Scan docs for stale version references."""
+    """Scan docs for stale version references.
+
+    The ``--pre specsmith`` check is context-aware (see
+    :func:`_has_stale_pre_flag`) so the supported dev/pre-release channel docs
+    and prohibitions do not produce false positives; only stale *stable*-install
+    hints are reported.
+    """
     issues: list[str] = []
     scan_dirs = [root / "docs" / "site", root]
-    scan_patterns = [
-        (r"--pre specsmith", "stale --pre flag"),
-        (r"0\.1\.0a\d+", "alpha version reference"),
-    ]
 
     for scan_dir in scan_dirs:
         for md_file in scan_dir.glob("*.md"):
             content = md_file.read_text(encoding="utf-8")
-            for pattern, desc in scan_patterns:
-                if re.search(pattern, content):
-                    rel = md_file.relative_to(root)
-                    issues.append(f"{rel}: {desc}")
+            rel = md_file.relative_to(root)
+            if _has_stale_pre_flag(content):
+                issues.append(f"{rel}: stale --pre flag")
+            if re.search(r"0\.1\.0a\d+", content):
+                issues.append(f"{rel}: alpha version reference")
 
     # Check classifier
     pyproject = root / "pyproject.toml"

{specsmith-0.18.0.dev690 → specsmith-0.18.0.dev692/src/specsmith.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.18.0.dev690
+Version: 0.18.0.dev692
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT

{specsmith-0.18.0.dev690 → specsmith-0.18.0.dev692}/src/specsmith.egg-info/SOURCES.txt

@@ -333,6 +333,7 @@ tests/test_phase34_completion.py
 tests/test_project_metrics.py
 tests/test_quality_report.py
 tests/test_rate_limits.py
+tests/test_releaser.py
 tests/test_repl.py
 tests/test_repl_extended.py
 tests/test_reporting_commands.py

specsmith-0.18.0.dev692/tests/test_releaser.py

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. All rights reserved.
+"""Tests for the release-tooling stale-reference scanner (REQ-050).
+
+These cover the context-aware ``--pre specsmith`` check so the supported
+dev/pre-release channel docs and explicit prohibitions are not reported as
+stale, while genuine stable-install hints still are.
+"""
+
+from pathlib import Path
+
+from specsmith.releaser import _has_stale_pre_flag, scan_stale_refs
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def test_dev_channel_pre_reference_not_flagged(tmp_path: Path) -> None:
+    """A dev-docs note mapping dev docs to the pre-release install is legitimate."""
+    _write(
+        tmp_path / "docs" / "site" / "index.md",
+        "# Docs\n\n**Dev (latest):** matches `pip install --pre specsmith`\n",
+    )
+    assert scan_stale_refs(tmp_path, "0.18.0") == []
+
+
+def test_dev_release_section_pre_reference_not_flagged(tmp_path: Path) -> None:
+    """An install hint under a 'Dev Releases' heading is legitimate dev-channel docs."""
+    _write(
+        tmp_path / "docs" / "site" / "releasing.md",
+        "## Dev Releases (develop branch)\n\nInstall: `pip install --pre specsmith`\n",
+    )
+    assert scan_stale_refs(tmp_path, "0.18.0") == []
+
+
+def test_prohibition_pre_reference_not_flagged(tmp_path: Path) -> None:
+    """A prohibition must not be read as a stale install hint."""
+    _write(
+        tmp_path / "AGENTS.md",
+        "## Install policy\n\n- NEVER run `pip install --pre specsmith` in any environment.\n",
+    )
+    assert scan_stale_refs(tmp_path, "0.18.0") == []
+
+
+def test_stale_stable_install_hint_is_flagged(tmp_path: Path) -> None:
+    """Recommending --pre for a normal install under a neutral heading is stale."""
+    _write(
+        tmp_path / "docs" / "site" / "getting-started.md",
+        "## Quick Start\n\nInstall specsmith: `pip install --pre specsmith`\n",
+    )
+    rel = Path("docs") / "site" / "getting-started.md"
+    assert scan_stale_refs(tmp_path, "0.18.0") == [f"{rel}: stale --pre flag"]
+
+
+def test_alpha_version_reference_flagged(tmp_path: Path) -> None:
+    """The narrow 0.1.0aN alpha pattern is still reported."""
+    _write(tmp_path / "README.md", "# x\n\nsee 0.1.0a3 builds\n")
+    assert scan_stale_refs(tmp_path, "0.18.0") == ["README.md: alpha version reference"]
+
+
+def test_alpha_classifier_flagged(tmp_path: Path) -> None:
+    """A '3 - Alpha' classifier in pyproject.toml is still reported."""
+    (tmp_path / "pyproject.toml").write_text(
+        '[project]\nclassifiers = ["Development Status :: 3 - Alpha"]\n',
+        encoding="utf-8",
+    )
+    assert "pyproject.toml: classifier still says Alpha" in scan_stale_refs(tmp_path, "0.18.0")
+
+
+def test_clean_docs_no_issues(tmp_path: Path) -> None:
+    """Stable install instructions and a non-alpha classifier produce no issues."""
+    _write(tmp_path / "docs" / "site" / "index.md", "# Docs\n\n`pip install specsmith`\n")
+    (tmp_path / "pyproject.toml").write_text(
+        '[project]\nclassifiers = ["Development Status :: 5 - Production/Stable"]\n',
+        encoding="utf-8",
+    )
+    assert scan_stale_refs(tmp_path, "0.18.0") == []
+
+
+def test_has_stale_pre_flag_unit() -> None:
+    """Direct checks of the line+heading-aware helper."""
+    # Neutral install hint with no qualifying context -> stale.
+    assert _has_stale_pre_flag("Install: `pip install --pre specsmith`") is True
+    # Heading context marks the section as dev -> legitimate.
+    assert _has_stale_pre_flag("## Dev Releases\nrun `pip install --pre specsmith`") is False
+    # Prohibition -> legitimate.
+    assert _has_stale_pre_flag("NEVER `pip install --pre specsmith`") is False
+    # No pre-release flag at all.
+    assert _has_stale_pre_flag("`pip install specsmith`") is False