devready-cli 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

devready/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.2.0"

devready/baseline.py

@@ -0,0 +1,43 @@
+"""Compare a run with a saved report (`devready check --format json > baseline.json`).
+
+DevReady only reads the baseline; saving or committing it is up to you. That covers both a
+shared team baseline (committed file) and diffing against an earlier local run.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from devready.checks.project import _read
+from devready.models import Result, Status
+
+_ID = re.compile(r"^[a-z_]+(\.[a-z_]+)+$")
+_RANK = {Status.PASS: 0, Status.SKIP: 0, Status.WARN: 1, Status.ERROR: 2, Status.FAIL: 3}
+
+
+def load_baseline(path: Path) -> dict[str, Status] | None:
+    """check_id -> status, or None if the file is missing, too big, or not a v1 report."""
+    text = _read(path)
+    try:
+        data = json.loads(text) if text else None
+        if data["schema_version"] != 1:
+            return None
+        return {
+            r["check_id"]: Status(r["status"])
+            for r in data["results"]
+            if isinstance(r["check_id"], str) and _ID.match(r["check_id"])
+        }
+    except (ValueError, KeyError, TypeError):
+        return None
+
+
+def diff(results: list[Result], base: dict[str, Status]) -> tuple[list[Result], bool]:
+    """(results that are new or changed status, whether any FAIL got worse)."""
+    changed = [r for r in results if base.get(r.check_id) is not r.status]
+    worse = any(
+        r.status is Status.FAIL and _RANK[r.status] > _RANK.get(base.get(r.check_id), 0)
+        for r in changed
+    )
+    return changed, worse

devready/checks/config.py

@@ -0,0 +1,102 @@
+"""Optional `.devready.json`: extra requirements, required env var names, checks to skip.
+
+{"skip": ["project.ports"], "require": {"node": ">=20", "python": ">=3.11"}, "env": ["API_KEY"]}
+
+Read-only, same file rules as project.py. Env vars are tested for presence only; values are
+never read. Invalid files give one ERROR result and never echo file content.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from devready.checks.project import _compare, _read
+from devready.models import Result, Status
+from devready.versions import SAFE_SPEC, parse_version
+
+CONFIG_FILE = ".devready.json"
+_ID = re.compile(r"^[a-z_]+(\.[a-z_]+)*$")
+_ENV_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+_RUNTIMES = {"node": "Node", "python": "Python"}
+
+
+def _valid(cfg: object) -> bool:
+    if not isinstance(cfg, dict) or not set(cfg) <= {"skip", "require", "env"}:
+        return False
+    skip, req, env = cfg.get("skip", []), cfg.get("require", {}), cfg.get("env", [])
+    return (
+        isinstance(skip, list)
+        and all(isinstance(i, str) and _ID.match(i) for i in skip)
+        and isinstance(req, dict)
+        and all(
+            k in _RUNTIMES and isinstance(v, str) and SAFE_SPEC.match(v) for k, v in req.items()
+        )
+        and isinstance(env, list)
+        and all(isinstance(n, str) and _ENV_NAME.match(n) for n in env)
+    )
+
+
+def load_config(root: Path) -> tuple[dict | None, Result | None]:
+    """(config, None) if absent/valid ({} when absent), (None, error result) if invalid."""
+    text = _read(root / CONFIG_FILE)
+    if text is None:
+        return {}, None
+    try:
+        cfg = json.loads(text)
+    except ValueError:
+        cfg = None
+    if _valid(cfg):
+        return cfg, None
+    return None, Result(
+        "project.config.file",
+        "Config",
+        Status.ERROR,
+        f"{CONFIG_FILE} is invalid; it was ignored",
+        'Allowed keys: "skip" (check ids), "require" (node/python specs), "env" (variable names).',
+    )
+
+
+def check_config(
+    cfg: dict, node: str | None, python: str | None, environ: Mapping[str, str] = os.environ
+) -> list[Result]:
+    out: list[Result] = []
+    versions = {
+        "node": parse_version(node) if node else None,
+        "python": parse_version(python or ""),
+    }
+    for key, spec in cfg.get("require", {}).items():
+        out.append(
+            _compare(
+                f"project.{key}.config",
+                f"{_RUNTIMES[key]} required",
+                CONFIG_FILE,
+                spec,
+                versions[key],
+                Status.FAIL,
+            )
+        )
+    wanted = cfg.get("env", [])
+    if wanted:
+        missing = [n for n in wanted if n not in environ]
+        cid, title = "project.env.required", "Required env"
+        if missing:
+            out.append(
+                Result(
+                    cid,
+                    title,
+                    Status.FAIL,
+                    f"{len(missing)} of {len(wanted)} not set: {', '.join(missing[:10])}",
+                    "Set these variables in your shell or CI (values are never read).",
+                )
+            )
+        else:
+            out.append(Result(cid, title, Status.PASS, f"all {len(wanted)} variables are set"))
+    return out
+
+
+# Empty on purpose: pre-filling "env" from .env.example would make optional variables fail.
+TEMPLATE = json.dumps({"skip": [], "require": {}, "env": []}, indent=2)

devready/cli.py

@@ -6,9 +6,10 @@ import sys
 from pathlib import Path
 
 from devready import __version__
+from devready.baseline import diff, load_baseline
 from devready.formats import fix_plan, junit, sarif
 from devready.models import Result, Status
-from devready.runner import report, run_checks
+from devready.runner import matches, report, run_checks
 
 EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_INTERNAL = 0, 1, 2, 3
 
@@ -20,12 +21,8 @@ def _text(results: list[Result]) -> str:
     return "\n".join(lines)
 
 
-def _matches(check_id: str, ids: list[str]) -> bool:
-    return any(check_id == i or check_id.startswith(i + ".") for i in ids)
-
-
 def _selected(check_id: str, only: list[str], skip: list[str]) -> bool:
-    return (not only or _matches(check_id, only)) and not _matches(check_id, skip)
+    return (not only or matches(check_id, only)) and not matches(check_id, skip)
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -34,10 +31,14 @@ def main(argv: list[str] | None = None) -> int:
     sub = parser.add_subparsers(dest="command", required=True)
     check = sub.add_parser("check", help="run read-only environment checks")
     check.add_argument("--format", choices=["text", "json", "junit", "sarif"], default="text")
+    check.add_argument(
+        "--baseline", metavar="FILE", help="saved --format json report; show only what changed"
+    )
     fix = sub.add_parser("fix", help="print suggested fixes (never runs them)")
     fix.add_argument("--plan", action="store_true", help="required: list steps without running")
     explain = sub.add_parser("explain", help="explain what a check id means")
     explain.add_argument("check_id")
+    sub.add_parser("init", help="print a starter .devready.json (does not write it)")
     sub.add_parser("mcp", help="run as an MCP server over stdio")
     for p in (check, fix):
         p.add_argument("--project", default=".", help="directory whose version pins to compare")
@@ -54,6 +55,12 @@ def main(argv: list[str] | None = None) -> int:
 
         return serve()
 
+    if args.command == "init":
+        from devready.checks.config import TEMPLATE
+
+        print(TEMPLATE)
+        return EXIT_OK
+
     if args.command == "explain":
         from devready.explain import EXPLANATIONS
 
@@ -86,12 +93,24 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "fix":
         print(fix_plan(results))
         return EXIT_OK
+
+    regressed = None
+    if args.baseline:
+        base = load_baseline(Path(args.baseline))
+        if base is None:
+            print("devready: baseline is not a readable devready JSON report", file=sys.stderr)
+            return EXIT_USAGE
+        total = len(results)
+        results, regressed = diff(results, base)
+        print(f"Compared with baseline: {len(results)} of {total} changed.", file=sys.stderr)
     if args.format == "json":
         print(json.dumps(report(results), indent=2))
     elif args.format in ("junit", "sarif"):
         print(junit(results) if args.format == "junit" else sarif(results))
     else:
         print(_text(results))
+    if regressed is not None:  # with a baseline only a new or worse FAIL breaks the build
+        return EXIT_FAILED if regressed else EXIT_OK
     return EXIT_FAILED if any(r.status is Status.FAIL for r in results) else EXIT_OK
 
 

devready/explain.py

@@ -43,4 +43,8 @@ EXPLANATIONS = {
     "project.env.ignored": "Warns when .env exists but git would commit it (not ignored, or already tracked). Values are never shown.",
     "project.node.modules": "Checked when package.json lists dependencies: node_modules must exist and not be older than a lockfile.",
     "project.ports.free": "Ports declared in compose files (host side) or *PORT= lines in .env.example, tested by connecting to localhost. A busy port may be this project already running.",
+    "project.config.file": ".devready.json is optional. With unknown keys or invalid values it is ignored entirely. Run `devready init` for a starter.",
+    "project.node.config": "require.node in .devready.json is a hard requirement (fails when unmet).",
+    "project.python.config": "require.python in .devready.json is a hard requirement (fails when unmet).",
+    "project.env.required": "Variable NAMES listed under env in .devready.json must be set in the environment. Values are never read.",
 }

devready/runner.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import platform
 from pathlib import Path
 
+from devready.checks.config import check_config, load_config
 from devready.checks.extras import check_disk, check_docker, check_git_identity
 from devready.checks.health import check_health
 from devready.checks.project import check_project
@@ -12,7 +13,12 @@ from devready.checks.tools import TOOLS, check_tool
 from devready.models import Result
 
 
+def matches(check_id: str, ids: list[str]) -> bool:
+    return any(check_id == i or check_id.startswith(i + ".") for i in ids)
+
+
 def run_checks(root: Path) -> list[Result]:
+    cfg, cfg_error = load_config(root)
     results = [check_python()]
     versions = {}
     for tool in TOOLS:
@@ -21,7 +27,12 @@ def run_checks(root: Path) -> list[Result]:
     results += check_git_identity()
     results += check_project(root, versions["node"], platform.python_version())
     results += check_runtimes(root) + check_health(root)
-    return results + check_docker(root) + check_disk(root)
+    results += check_docker(root) + check_disk(root)
+    results += (
+        [cfg_error] if cfg_error else check_config(cfg, versions["node"], platform.python_version())
+    )
+    skip = (cfg or {}).get("skip", [])
+    return [r for r in results if not matches(r.check_id, skip)]
 
 
 def report(results: list[Result]) -> dict:

{devready_cli-0.1.0.dist-info → devready_cli-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: devready-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: A local-first, read-only CLI that checks a project's environment requirements against what is installed.
 Project-URL: Homepage, https://devready-ten.vercel.app/
 Project-URL: Repository, https://github.com/Evalogical-Inc/devReady
@@ -114,6 +114,9 @@ devready explain docker.daemon    # what a check means and how to fix it
 devready check --format junit     # or sarif, for CI
 devready check --only project --skip project.ports   # filter by id or prefix
 devready fix --plan               # suggested steps only; never runs them
+devready check --format json > baseline.json   # save a snapshot (commit it for a team baseline)
+devready check --baseline baseline.json          # show only what changed; fail only on new/worse failures
+devready init > .devready.json    # optional config: skip ids, require node/python, required env names
 devready mcp                      # run as an MCP server over stdio
 devready --version
 ```
@@ -202,7 +205,8 @@ See [SECURITY.md](SECURITY.md) to report a vulnerability.
 
 - [x] Docker CLI + daemon reachability, `.tool-versions`, `.env` key-name diff, disk space, git identity, `devready explain`
 - [x] Port-in-use checks, more ecosystems (Go, Rust, Java, Ruby, .NET, pnpm/yarn/bun), JUnit/SARIF output, `fix --plan`, GitHub Action
-- [ ] Config file, shared baseline (see [ROADMAP.md](ROADMAP.md))
+- [x] `.devready.json` config, `--baseline` snapshots
+- [ ] Platform-specific checks (see [ROADMAP.md](ROADMAP.md))
 - [ ] Standalone binaries
 
 Have a setup problem DevReady should catch? [Open an issue](https://github.com/Evalogical-Inc/devReady/issues/new/choose). Early feedback shapes the roadmap.

{devready_cli-0.1.0.dist-info → devready_cli-0.2.0.dist-info}/RECORD

@@ -1,21 +1,23 @@
-devready/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+devready/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
 devready/__main__.py,sha256=c-4qpm2SKZs1nENGzSnPnChNTo8iMwjY0XaPyAApn4I,60
-devready/cli.py,sha256=OucYELHjvcFY2qw96Kc6yi4lp1RX9GnSif3MlelJ3ks,3787
-devready/explain.py,sha256=UbYKUdfdVsITUtuFIvG4vJ21SP8GI-HNPKh9xp6LCRE,4641
+devready/baseline.py,sha256=pfVzZ695bLEiSWKUBK0PNDp1S2UWTWj9lfUCDAsVS4g,1524
+devready/cli.py,sha256=RPijit2MT_ouZgD2TOUu1x-6YJevRIkh_a1wTWbMeuY,4619
+devready/explain.py,sha256=nYzzwtZGpn-FQQR8_KxC61_FLf7jCuQEv4iX-Fvqqr0,5140
 devready/formats.py,sha256=akN62ouKLeZQB6POcXNzINYKHwpUd4im0n2-9rtB8eE,3129
 devready/mcp_server.py,sha256=zVm89kZL_-pZwTSWkt6rxKonytNklUSa0RCQkX0lzFk,3177
 devready/models.py,sha256=KyGp3ie2LVQmuSfzLV8tbEH_hJyU5-Vi11d0JcQPAuE,646
-devready/runner.py,sha256=3OLWash5jGZKQM30iA1ObAzF2FTmM7STsiDD3LMO9Qs,1005
+devready/runner.py,sha256=MVQh-dlsXnihWSbvbF4XKuFxgIyoywtL-9I-y0XrPpc,1456
 devready/versions.py,sha256=dXKIl1-qvcfadRNaCURMoftwx7YtadDZ-YfUp-85XZc,2112
 devready/checks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devready/checks/config.py,sha256=SGyIot_QXmZtPLIybtxnyJEFL2aV1NemSqX_fXbFI6A,3471
 devready/checks/extras.py,sha256=pDJbFaAwjkLc92tcFagOmj-5c_vMx32_MtYa_DBfCz8,3428
 devready/checks/health.py,sha256=woaaUL2TJ_biRuiStXqJtnvPua_y69bW2quNPlwd7tQ,4235
 devready/checks/project.py,sha256=UnnjuZmG2aXXBAY45wTEP-bj4CWODMv3DPfEi1V_QDE,5983
 devready/checks/python_check.py,sha256=uQCd-N0LEwt9R5gwZm5mlYiPMST1JXVDNQOdZ5xpako,328
 devready/checks/runtimes.py,sha256=OiC5LEhmfkiMseP2PbQS6Dc6TC2JhYNICU6LmdFFvqk,4446
 devready/checks/tools.py,sha256=AiL9TdIREmY7tEkkpt62DELKuJ2lhu3XcA2yGak9QkA,1616
-devready_cli-0.1.0.dist-info/METADATA,sha256=jlbjbIv1omn0U0G-ZlgrrHdDMP-O33GC4tMmAJC8pdE,10176
-devready_cli-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-devready_cli-0.1.0.dist-info/entry_points.txt,sha256=7oAecSWtsIt7qLOP8PipOeDqhXCkEJat0oxhD4T1RpY,47
-devready_cli-0.1.0.dist-info/licenses/LICENSE,sha256=S_AQsEw289FIsOgT-OPWL5JZeV8nn5kicwEq0r9qu7s,1071
-devready_cli-0.1.0.dist-info/RECORD,,
+devready_cli-0.2.0.dist-info/METADATA,sha256=b76wbK0qZnoG8aNy66wxg8QmFDPENvL3GhzAwa2-RMQ,10533
+devready_cli-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+devready_cli-0.2.0.dist-info/entry_points.txt,sha256=7oAecSWtsIt7qLOP8PipOeDqhXCkEJat0oxhD4T1RpY,47
+devready_cli-0.2.0.dist-info/licenses/LICENSE,sha256=S_AQsEw289FIsOgT-OPWL5JZeV8nn5kicwEq0r9qu7s,1071
+devready_cli-0.2.0.dist-info/RECORD,,