devready-cli 0.0.4__tar.gz → 0.2.0__tar.gz

{devready_cli-0.0.4 → devready_cli-0.2.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "devready",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "homepage": "https://devready-ten.vercel.app/",
   "description": "Read-only environment preflight: compares a project's declared Node/Python versions with what is installed.",
   "author": { "name": "DevReady contributors" },

{devready_cli-0.0.4 → devready_cli-0.2.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.0 - 2026-10-16
+- `check --baseline FILE` (and `baseline:` Action input): show only results that changed since a saved JSON report.
+- Optional `.devready.json` (`skip`, `require`, `env`) and `devready init` (prints a starter).
+
+## 0.1.0 - 2026-10-16
+- GitHub Action (`action.yml`) wrapping `devready check`.
+- `--format junit|sarif`, `--only`/`--skip` filters, and `devready fix --plan` (suggestions only).
+- Project health: `.env` not git-ignored, `node_modules` missing/older than lockfile, declared ports already in use.
+- pnpm, Yarn and Bun checks when `package.json` `packageManager` names them.
+- Go, Ruby, Java, Rust and .NET checks, run only when the project pins them (`go.mod`, `.ruby-version`, `.java-version`, `rust-toolchain[.toml]`, `global.json`, `.tool-versions`).
+
 ## 0.0.4 - 2026-10-16
 - `python -m devready` entry point.
 - Skill, `/devready:doctor` and `AGENTS.md` now fall back to `python -m devready`, `uvx`, then `pipx run`, and tell the user how to install instead of failing.

{devready_cli-0.0.4 → devready_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: devready-cli
-Version: 0.0.4
+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
@@ -111,6 +111,12 @@ devready check                    # human-readable report for the current direct
 devready check --project ../app   # inspect another project's pins
 devready check --format json      # machine-readable (see docs/schema.json)
 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
 ```
@@ -148,6 +154,16 @@ devready --version
 }
 ```
 
+## Use it in CI (GitHub Actions)
+
+```yaml
+- uses: Evalogical-Inc/devReady@main   # pin a release tag once published
+  with:
+    skip: project.ports                  # optional; also: only, format, project, version
+```
+
+The job fails when a declared requirement is unmet (`fail`). It installs `devready-cli` from PyPI, so flags added after your installed release (`--only`, `--skip`, junit/sarif) need a release that includes them; set `version:` to pin one.
+
 ## Use it with AI coding agents
 
 DevReady ships the same engine three ways, so your agent can verify the environment *before* it installs, builds or tests.
@@ -181,15 +197,16 @@ See [SECURITY.md](SECURITY.md) to report a vulnerability.
 
 ## Limitations (alpha)
 
-- Checks today: Python, Git (+ identity set), Node.js, npm, project pins (`.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `package.json` engines, `pyproject.toml` requires-python), `.env.example` vs `.env` key names, Docker CLI + daemon (only when the project has a Dockerfile/compose file), and free disk space.
+- Checks today: Python, Git (+ identity set), Node.js, npm, project pins (`.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `package.json` engines, `pyproject.toml` requires-python), `.env.example` vs `.env` key names, Docker CLI + daemon (only when the project has a Dockerfile/compose file), free disk space, and (only when the project declares them) Go, Ruby, Java, Rust, .NET, pnpm, Yarn and Bun pins, `.env` not git-ignored, `node_modules` vs lockfile, and declared ports already in use.
 - The version-range matcher covers common npm/PEP 440 syntax; pre-releases and exotic ranges report `skip` rather than guess.
 - The Python version compared is the interpreter running DevReady, not necessarily your project's virtualenv.
 
 ## Roadmap
 
 - [x] Docker CLI + daemon reachability, `.tool-versions`, `.env` key-name diff, disk space, git identity, `devready explain`
-- [ ] Port-in-use checks (ports read from compose files)
-- [ ] More ecosystems (Go, Rust, Java, Ruby pins)
+- [x] Port-in-use checks, more ecosystems (Go, Rust, Java, Ruby, .NET, pnpm/yarn/bun), JUnit/SARIF output, `fix --plan`, GitHub Action
+- [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.
@@ -202,6 +219,10 @@ PRs welcome, especially new read-only checks and platform fixes. Start with [CON
 ruff check . && pytest
 ```
 
+## About Evalogical
+
+DevReady is built and maintained by [Evalogical](https://evalogical.com/), a software company offering AI-enabled product engineering, custom software and IT services. Need help with a product or an engineering team? [Talk to us](https://evalogical.com/contactus).
+
 ## License
 
 [MIT](LICENSE) © Evalogical Inc

{devready_cli-0.0.4 → devready_cli-0.2.0}/README.md

@@ -87,6 +87,12 @@ devready check                    # human-readable report for the current direct
 devready check --project ../app   # inspect another project's pins
 devready check --format json      # machine-readable (see docs/schema.json)
 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
 ```
@@ -124,6 +130,16 @@ devready --version
 }
 ```
 
+## Use it in CI (GitHub Actions)
+
+```yaml
+- uses: Evalogical-Inc/devReady@main   # pin a release tag once published
+  with:
+    skip: project.ports                  # optional; also: only, format, project, version
+```
+
+The job fails when a declared requirement is unmet (`fail`). It installs `devready-cli` from PyPI, so flags added after your installed release (`--only`, `--skip`, junit/sarif) need a release that includes them; set `version:` to pin one.
+
 ## Use it with AI coding agents
 
 DevReady ships the same engine three ways, so your agent can verify the environment *before* it installs, builds or tests.
@@ -157,15 +173,16 @@ See [SECURITY.md](SECURITY.md) to report a vulnerability.
 
 ## Limitations (alpha)
 
-- Checks today: Python, Git (+ identity set), Node.js, npm, project pins (`.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `package.json` engines, `pyproject.toml` requires-python), `.env.example` vs `.env` key names, Docker CLI + daemon (only when the project has a Dockerfile/compose file), and free disk space.
+- Checks today: Python, Git (+ identity set), Node.js, npm, project pins (`.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `package.json` engines, `pyproject.toml` requires-python), `.env.example` vs `.env` key names, Docker CLI + daemon (only when the project has a Dockerfile/compose file), free disk space, and (only when the project declares them) Go, Ruby, Java, Rust, .NET, pnpm, Yarn and Bun pins, `.env` not git-ignored, `node_modules` vs lockfile, and declared ports already in use.
 - The version-range matcher covers common npm/PEP 440 syntax; pre-releases and exotic ranges report `skip` rather than guess.
 - The Python version compared is the interpreter running DevReady, not necessarily your project's virtualenv.
 
 ## Roadmap
 
 - [x] Docker CLI + daemon reachability, `.tool-versions`, `.env` key-name diff, disk space, git identity, `devready explain`
-- [ ] Port-in-use checks (ports read from compose files)
-- [ ] More ecosystems (Go, Rust, Java, Ruby pins)
+- [x] Port-in-use checks, more ecosystems (Go, Rust, Java, Ruby, .NET, pnpm/yarn/bun), JUnit/SARIF output, `fix --plan`, GitHub Action
+- [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.
@@ -178,6 +195,10 @@ PRs welcome, especially new read-only checks and platform fixes. Start with [CON
 ruff check . && pytest
 ```
 
+## About Evalogical
+
+DevReady is built and maintained by [Evalogical](https://evalogical.com/), a software company offering AI-enabled product engineering, custom software and IT services. Need help with a product or an engineering team? [Talk to us](https://evalogical.com/contactus).
+
 ## License
 
 [MIT](LICENSE) © Evalogical Inc

devready_cli-0.2.0/ROADMAP.md

@@ -0,0 +1,68 @@
+# Roadmap
+
+Principles (unchanged): read-only, local-first, zero runtime dependencies, Python >= 3.10, never print env values or raw command output.
+
+## Where we are (0.2.0)
+
+- Tools: Git, Node, npm, Python. Docker, Go, Ruby, Java, Rust, .NET, pnpm, Yarn, Bun only when the project declares them (details in the sections below).
+- Pins compared: `.nvmrc`, `.node-version`, `.python-version`, `package.json` engines.node, `pyproject.toml` requires-python, `.tool-versions` (node/python only).
+- Also: `.env.example` vs `.env` key names, git identity presence, free disk space.
+- Interfaces: `check` (text/JSON/JUnit/SARIF, `--only`/`--skip`/`--baseline`, exit 1 on `fail`), `fix --plan`, `init`, `explain`, `mcp`, GitHub Action, Claude Code plugin, `AGENTS.md`.
+- CI and PyPI publish workflows exist.
+
+## Decisions (from the docs review)
+
+- Keep `check` + `explain`; no separate `doctor` command.
+- JSON schema stays at v1. No `details` field; new fields need a version bump (revisit at 1.0).
+- Check ids must match `^[a-z_]+(\.[a-z_]+)+$`: no digits or hyphens.
+- Anything echoing project file content only uses validated strings (`SAFE_SPEC`, extracted digits).
+- Docs gaps: `docs/architecture.md`, `docs/security.md`, `tests/integration/`, `tests/fixtures/`.
+
+## 0.1 - More runtimes (in progress)
+
+- [x] Go (`go.mod`), Ruby (`.ruby-version`), Java (`.java-version`), Rust (`rust-toolchain[.toml]`), .NET (`global.json`), plus their `.tool-versions` lines. Checked only when the project declares them, so no noise on other projects. (`checks/runtimes.py`)
+- [x] `explain` entries and tests for every new id.
+- [x] pnpm/yarn/bun via the `packageManager` field in `package.json`.
+- [ ] `uv`/`pip` (no pin file to compare against yet).
+- [ ] Table-drive the existing Node/Python pins in `project.py` the same way.
+- [ ] Add `pom.xml` / `build.gradle` Java targets, `Gemfile` ruby version.
+- [ ] Fixture-based integration tests with real tools on CI.
+
+## 0.2 - Project health (in progress)
+
+- [x] Node dependency drift: `node_modules` missing or older than a lockfile (directory mtime).
+- [ ] Python drift (venv present, `pip check`); skipped for now since conda/global envs make "no venv" noisy.
+- [x] Port conflicts for ports declared in compose files and `*PORT=` in `.env.example` (`package.json` scripts not parsed).
+- [x] `.env` hygiene: warn if `.env` is not gitignored or is tracked.
+- [ ] Docker: compose file validity, image platform mismatch (arm64 vs amd64).
+
+## 0.3 - Actionable output (in progress)
+
+- [x] `devready fix --plan`: prints each `fail`/`warn` with its suggestion. Never runs anything. (Suggestions are prose today, not exact commands.)
+- [x] `--format sarif` and `junit` (SARIF has no file locations yet, so GitHub code scanning may not show alerts).
+- [x] `--only` / `--skip` filters by check id or dotted prefix (repeatable).
+- [x] Optional `.devready.json` (JSON, so no parser dependency): `skip` ids, `require` node/python, required `env` names.
+- [x] `devready init` prints a starter file (does not write it; DevReady stays read-only).
+
+## 0.4 - Team and CI
+
+- [x] GitHub Action (`action.yml`, composite). Untested on a real runner; needs a release with the new flags.
+- [x] `--baseline FILE`: compare with a saved `--format json` report (commit it for a team baseline). Shows new/changed results; exit 1 only for a new or worse `fail`. Results that disappeared are not reported.
+- [x] Diff mode = `--baseline` against your own saved snapshot. DevReady never writes the snapshot (read-only), and there is no `--watch` loop.
+
+## 0.5 - Platform specifics
+
+- [ ] Windows: long paths enabled, execution policy, `core.autocrlf`.
+- [ ] WSL version and Docker Desktop backend.
+- [ ] macOS: Xcode CLT; Linux: common missing build deps.
+
+## 1.0 - Stabilize
+
+- [ ] Freeze JSON schema (`docs/schema.json`) with a versioning policy.
+- [ ] Test matrix on Windows/macOS/Linux x Python 3.10-3.13.
+- [ ] Docs pass: check catalog, plugin/MCP setup, contributing guide for adding a check.
+
+## Opt-in only (needs explicit design review)
+
+- Network reachability checks (registry, DB host): off by default, strict timeouts.
+- Anything that executes project code or installs software: out of scope.

devready_cli-0.2.0/action.yml

@@ -0,0 +1,50 @@
+name: DevReady check
+description: Read-only environment preflight. Fails the job when a declared requirement is unmet.
+branding:
+  icon: check-circle
+  color: green
+inputs:
+  project:
+    description: Directory whose version pins to compare.
+    default: "."
+  format:
+    description: text, json, junit or sarif.
+    default: text
+  only:
+    description: Space-separated check ids or prefixes to run (empty = all).
+    default: ""
+  skip:
+    description: Space-separated check ids or prefixes to skip.
+    default: ""
+  baseline:
+    description: Path to a committed `--format json` report; only changes are shown and only a new or worse failure fails the job.
+    default: ""
+  version:
+    description: devready-cli version to install (empty = latest).
+    default: ""
+  python-version:
+    description: Python used to run DevReady (not your project's Python).
+    default: "3.12"
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+    # Inputs go through env vars, never interpolated into the script, to avoid shell injection.
+    - shell: bash
+      env:
+        DR_PROJECT: ${{ inputs.project }}
+        DR_FORMAT: ${{ inputs.format }}
+        DR_ONLY: ${{ inputs.only }}
+        DR_SKIP: ${{ inputs.skip }}
+        DR_VERSION: ${{ inputs.version }}
+        DR_BASELINE: ${{ inputs.baseline }}
+      run: |
+        set -eu
+        python -m pip install --quiet "devready-cli${DR_VERSION:+==$DR_VERSION}"
+        args=(check --project "$DR_PROJECT" --format "$DR_FORMAT")
+        for id in $DR_ONLY; do args+=(--only "$id"); done
+        for id in $DR_SKIP; do args+=(--skip "$id"); done
+        if [ -n "$DR_BASELINE" ]; then args+=(--baseline "$DR_BASELINE"); fi
+        python -m devready "${args[@]}"

{devready_cli-0.0.4 → devready_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devready-cli"
-version = "0.0.4"
+version = "0.2.0"
 description = "A local-first, read-only CLI that checks a project's environment requirements against what is installed."
 readme = "README.md"
 requires-python = ">=3.10"

devready_cli-0.2.0/src/devready/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

devready_cli-0.2.0/src/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_cli-0.2.0/src/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-0.2.0/src/devready/checks/health.py

@@ -0,0 +1,116 @@
+"""Project health: .env ignored by git, node_modules vs lockfile, ports the project declares.
+
+Read-only. Only numbers and fixed phrases reach the report, never file content.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import socket
+from collections.abc import Callable
+from pathlib import Path
+
+from devready.checks.extras import DOCKER_FILES, _run
+from devready.checks.project import _read
+from devready.models import Result, Status
+
+LOCKFILES = ("package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb", "bun.lock")
+_COMPOSE_PORT = re.compile(r"^\s*-\s*[\"']?(?:[\d.]+:)?(\d{2,5}):\d+", re.M)
+_ENV_PORT = re.compile(r"^\s*(?:export\s+)?[A-Z_]*PORT\s*=\s*[\"']?(\d{2,5})\b", re.M)
+MAX_PORTS = 20
+
+
+def _listening(port: int) -> bool:
+    with socket.socket() as s:
+        s.settimeout(0.3)
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+
+def check_env_ignored(root: Path, run: Callable = _run) -> list[Result]:
+    """A .env that git would commit is a leak risk. Silent outside a git repo."""
+    git = shutil.which("git")
+    if not (root / ".env").is_file() or not git:
+        return []
+    p = run([git, "-C", str(root), "check-ignore", "-q", ".env"])
+    if p is None or p.returncode not in (0, 1):
+        return []
+    if p.returncode == 0:
+        return [Result("project.env.ignored", "Env ignored", Status.PASS, ".env is git-ignored")]
+    return [
+        Result(
+            "project.env.ignored",
+            "Env ignored",
+            Status.WARN,
+            ".env is not ignored by git (or is already tracked)",
+            "Add .env to .gitignore; if it is tracked, untrack it and rotate its secrets.",
+        )
+    ]
+
+
+def check_node_modules(root: Path) -> list[Result]:
+    text = _read(root / "package.json")
+    try:
+        data = json.loads(text) if text else None
+    except ValueError:
+        return []  # project.py already reports the parse error
+    if not isinstance(data, dict) or not any(
+        isinstance(data.get(k), dict) and data[k] for k in ("dependencies", "devDependencies")
+    ):
+        return []
+    cid, title = "project.node.modules", "node_modules"
+    nm = root / "node_modules"
+    if not nm.is_dir():
+        return [
+            Result(
+                cid,
+                title,
+                Status.WARN,
+                "node_modules not found",
+                "Install dependencies with your package manager (npm, pnpm, yarn or bun).",
+            )
+        ]
+    # ponytail: directory mtime, not a content comparison; upgrade if it proves noisy.
+    locks = [root / f for f in LOCKFILES if (root / f).is_file()]
+    if any(lock.stat().st_mtime > nm.stat().st_mtime for lock in locks):
+        return [
+            Result(
+                cid,
+                title,
+                Status.WARN,
+                "a lockfile is newer than node_modules",
+                "Re-run your package manager's install to sync dependencies.",
+            )
+        ]
+    return [Result(cid, title, Status.PASS, "node_modules is present and not older than lockfiles")]
+
+
+def check_ports(root: Path, in_use: Callable[[int], bool] = _listening) -> list[Result]:
+    ports: set[int] = set()
+    for name in DOCKER_FILES[1:]:  # compose files only
+        if (text := _read(root / name)) is not None:
+            ports.update(int(p) for p in _COMPOSE_PORT.findall(text))
+    if (text := _read(root / ".env.example")) is not None:
+        ports.update(int(p) for p in _ENV_PORT.findall(text))
+    ports = {p for p in ports if 0 < p < 65536}
+    if not ports:
+        return []
+    cid, title = "project.ports.free", "Ports"
+    shown = sorted(ports)[:MAX_PORTS]
+    busy = [p for p in shown if in_use(p)]
+    if busy:
+        return [
+            Result(
+                cid,
+                title,
+                Status.WARN,
+                f"already in use on localhost: {', '.join(map(str, busy))}",
+                "Stop the other process or change the port; it may be this project running.",
+            )
+        ]
+    return [Result(cid, title, Status.PASS, f"{len(shown)} declared port(s) are free")]
+
+
+def check_health(root: Path) -> list[Result]:
+    return check_env_ignored(root) + check_node_modules(root) + check_ports(root)

devready_cli-0.2.0/src/devready/checks/runtimes.py

@@ -0,0 +1,103 @@
+"""Go, Ruby, Java, Rust, .NET, pnpm, Yarn, Bun: checked only when the project pins them.
+
+Same read-only rules as project.py. Only digits/validated specs ever reach the report.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+from devready.checks.project import _compare, _read
+from devready.checks.tools import check_tool
+from devready.models import Result, Status
+from devready.versions import parse_version
+
+
+def _first_version(text: str) -> str | None:
+    m = re.search(r"\d+(?:\.\d+){0,2}", text.strip().split("\n", 1)[0])
+    return m.group() if m else None
+
+
+def _go_mod(text: str) -> str | None:
+    m = re.search(r"^go\s+(\d+(?:\.\d+){1,2})", text, re.M)
+    return f">={m.group(1)}" if m else None
+
+
+def _rust(text: str) -> str | None:
+    m = re.search(r"^\s*channel\s*=\s*[\"']([^\"']*)[\"']", text, re.M)
+    return m.group(1) if m else text.strip().split("\n", 1)[0] or None
+
+
+def _global_json(text: str) -> str | None:
+    try:
+        spec = json.loads(text).get("sdk", {}).get("version")
+    except (ValueError, AttributeError):
+        return None
+    return spec if isinstance(spec, str) else None
+
+
+def _pkg_manager(name: str) -> Callable[[str], str | None]:
+    def extract(text: str) -> str | None:
+        try:
+            value = json.loads(text).get("packageManager")
+        except (ValueError, AttributeError):
+            return None
+        m = (
+            re.fullmatch(rf"{name}@(\d+(?:\.\d+){{0,2}})(?:\+.*)?", value)
+            if isinstance(value, str)
+            else None
+        )
+        return m.group(1) if m else None
+
+    return extract
+
+
+# key -> (title, exe, version args, docs, .tool-versions name, [(id, file, extractor, miss)])
+RUNTIMES: dict[str, tuple] = {
+    "go": ("Go", "go", ("version",), "https://go.dev/doc/install", "golang",
+           [("project.go.mod", "go.mod", _go_mod, Status.FAIL)]),
+    "ruby": ("Ruby", "ruby", ("--version",), "https://www.ruby-lang.org/en/downloads/", "ruby",
+             [("project.ruby.pin", ".ruby-version", _first_version, Status.WARN)]),
+    "java": ("Java", "java", ("-version",), "https://adoptium.net/", "java",
+             [("project.java.pin", ".java-version", _first_version, Status.WARN)]),
+    "rust": ("Rust", "rustc", ("--version",), "https://rustup.rs/", "rust",
+             [("project.rust.toolchain", "rust-toolchain.toml", _rust, Status.WARN),
+              ("project.rust.toolchain", "rust-toolchain", _rust, Status.WARN)]),
+    "dotnet": ("dotnet", "dotnet", ("--version",), "https://dotnet.microsoft.com/download",
+               "dotnet", [("project.dotnet.global", "global.json", _global_json, Status.WARN)]),
+    # packageManager in package.json pins one manager, e.g. "pnpm@9.1.0"
+    "pnpm": ("pnpm", "pnpm", ("--version",), "https://pnpm.io/installation", "pnpm",
+             [("project.pnpm.pin", "package.json", _pkg_manager("pnpm"), Status.WARN)]),
+    "yarn": ("Yarn", "yarn", ("--version",), "https://yarnpkg.com/getting-started/install", "yarn",
+             [("project.yarn.pin", "package.json", _pkg_manager("yarn"), Status.WARN)]),
+    "bun": ("Bun", "bun", ("--version",), "https://bun.sh/docs/installation", "bun",
+            [("project.bun.pin", "package.json", _pkg_manager("bun"), Status.WARN)]),
+}  # fmt: skip
+
+
+def check_runtimes(
+    root: Path, tool: Callable = check_tool, runtimes: dict[str, tuple] = RUNTIMES
+) -> list[Result]:
+    tv = _read(root / ".tool-versions") or ""
+    tv_pins = {p[0]: p[1] for line in tv.splitlines() if len(p := line.split("#")[0].split()) >= 2}
+    out: list[Result] = []
+    for key, (title, exe, args, docs, tv_name, pins) in runtimes.items():
+        found: list[tuple[str, str, str, Status]] = []
+        for cid, fname, extract, miss in pins:
+            text = _read(root / fname)
+            if text is not None and (spec := extract(text)):
+                found.append((cid, fname, spec, miss))
+                break
+        if tv_name in tv_pins:
+            found.append((f"project.{key}.tool_versions", ".tool-versions", tv_pins[tv_name],
+                          Status.WARN))  # fmt: skip
+        if not found:
+            continue
+        res, ver = tool(f"{key}.version", title, exe, docs, args)
+        out.append(res)
+        v = parse_version(ver) if ver else None
+        out += [_compare(c, f"{title} pin", src, spec, v, miss) for c, src, spec, miss in found]
+    return out