dev-env-doctor 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-16
+
+### Added
+
+- `ports`: process inspection now includes command line (redacted), parent PID, user, working directory and project association (current project / another location / unknown) on macOS, Linux and Windows, with unavailable fields labelled.
+- `ports`: interactive Inspect / Stop / Skip workflow, with process selection when several ports are occupied, and a focused view for a single port.
+- `ports --kill`: `--pid` for an unambiguous target, re-check before signalling, force only as a separate step while the same process still holds the port, and handling of processes that exit early or ports taken over by another process.
+
+- `doctor` (default): full diagnostic report with PASS / WARN / FAIL / INFO statuses, `--verbose`, `--json`, `--ci`, `--fail-on` and `--cwd`.
+- `node`: checks the running Node.js version against `engines.node`, `.nvmrc` and `.node-version`.
+- `packages`: validates package.json, lockfiles, package manager availability and installed dependencies.
+- `env`: compares `.env*` files with `.env.example` by key name and finds `process.env` / `import.meta.env` references in source code. Never prints values.
+- `ports`: shows processes listening on ports (macOS, Linux, Windows adapters) and `--kill` with confirmation, graceful-first termination and release verification.
+- `services`: Docker CLI/daemon checks and PostgreSQL, MongoDB and Redis TCP reachability.
+- `fix`: previews and applies safe fixes (create `.env` from the template with empty values, add `.env` to `.gitignore`, stop a process blocking a project port) and re-verifies them.
+- Optional `.dev-doctor.json` configuration.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sameera_mhk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,304 @@
-# Temporary Holding Version
+# Dev Doctor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/dev-env-doctor.svg)](https://www.npmjs.com/package/dev-env-doctor)
+[![CI](https://github.com/Sameera-MHK/dev-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/Sameera-MHK/dev-doctor/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Node.js >= 22.12](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen.svg)
+
+Diagnose — and safely fix — the problems that stop a JavaScript or Node.js project from starting: busy ports, the wrong Node.js version, missing dependencies, `.env` files out of sync with `.env.example`, and local services that are not running.
+
+- **Offline.** No API key, no telemetry, nothing is uploaded.
+- **Read-only by default.** Changes only happen through `fix` or `ports --kill`, with a preview and confirmation.
+- **No secrets in output.** `.env` files are compared by key name only; command lines are redacted.
+- **Cross-platform.** macOS, Linux and Windows.
+
+```bash
+npx dev-env-doctor
+```
+
+## Contents
+
+- [Installation](#installation)
+- [Example](#example)
+- [Commands](#commands)
+- [Configuration](#configuration)
+- [Exit codes](#exit-codes)
+- [Security](#security)
+- [Supported operating systems](#supported-operating-systems)
+- [Limitations](#limitations)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Requires Node.js 22.12 or newer.
+
+Run it once in any project, without installing:
+
+```bash
+npx dev-env-doctor
+```
+
+Or install it, then use the `dev-doctor` command:
+
+```bash
+npm install -g dev-env-doctor
+dev-doctor
+```
+
+As a project dev dependency (for scripts and CI):
+
+```bash
+npm install -D dev-env-doctor
+npx dev-doctor --ci
+```
+
+From source:
+
+```bash
+git clone https://github.com/Sameera-MHK/dev-doctor.git
+cd dev-doctor
+npm install
+npm link
+```
+
+## Example
+
+```
+Dev Doctor
+Project: my-react-app (Vite)
+
+Project
+  PASS  package.json is valid (Vite project)
+
+Node.js
+  INFO  Node.js 22.12.0
+  INFO  npm 11.6.0
+  PASS  Node.js 22.12.0 satisfies engines.node (>=20)
+
+Packages
+  WARN  Multiple lockfiles detected
+  PASS  npm 11.6.0 is available
+  PASS  All 24 declared dependencies are installed
+
+Environment variables
+  INFO  Template: .env.example (6 keys)
+  FAIL  DATABASE_URL is missing
+        Documented in .env.example
+        Referenced in src/db.ts
+  WARN  API_BASE_URL is not documented in .env.example
+
+Ports
+  FAIL  Port 5173 is occupied by node (PID 8421)
+
+Services
+  PASS  Docker daemon is running (27.3.1)
+  WARN  PostgreSQL is not reachable at localhost:5432
+
+Summary
+  2 errors, 3 warnings, 5 passed
+
+Recommended next steps:
+  1. Agree on one package manager (likely npm) and remove the other lockfiles yourself.
+  2. Set DATABASE_URL in your local .env file.
+  3. Add API_BASE_URL (without its value) to .env.example.
+  4. Inspect the process using port 5173, or stop it with "dev-doctor ports --kill 5173".
+  5. Verify PostgreSQL is running if this project needs it (e.g. "docker compose up -d").
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `dev-doctor` / `dev-doctor doctor` | Full diagnosis of the current project |
+| `dev-doctor node` | Node.js version vs `engines.node`, `.nvmrc`, `.node-version` |
+| `dev-doctor packages` | package.json, lockfiles, package manager, installed dependencies |
+| `dev-doctor env` | `.env*` files vs `.env.example` and code references (keys only) |
+| `dev-doctor ports [ports...]` | Which processes listen on ports |
+| `dev-doctor ports --kill <port>` | Stop the process on a port, safely |
+| `dev-doctor services` | Docker, PostgreSQL, MongoDB, Redis availability |
+| `dev-doctor fix` | Preview and apply safe fixes |
+
+Common options (all diagnostic commands):
+
+| Option | Description |
+| --- | --- |
+| `--cwd <path>` | Project directory (default: current directory) |
+| `--json` | JSON on stdout only; errors go to stderr |
+| `-v, --verbose` | Show details for every finding (process command lines, sources) |
+| `--ci` | No prompts, no colors |
+| `--fail-on <fail\|warn>` | Exit 1 on failures only (default) or on warnings too |
+| `--no-color` | Disable colors (also disabled when piped or `NO_COLOR` is set) |
+
+### doctor
+
+Checks the project (package.json and project type), Node.js and npm versions, the package manager and lockfiles, dependency installation, environment variables, ports and local services.
+
+Ports: if the project declares ports (`.dev-doctor.json`, `PORT` in `.env`, `--port`/`-p` in scripts, or framework defaults such as 5173 for Vite, 3000 for Next.js, 4200 for Angular), a busy port is a **FAIL**. Otherwise common development ports (3000, 3001, 4200, 5000, 5173, 8000, 8080) are checked and a busy one is only a **WARN**.
+
+### env
+
+- Reads `.env`, `.env.local`, `.env.development`, `.env.development.local` and the first template found from `.env.example`, `.env.sample`, `.env.template`, `.env.dist`.
+- Compares **key names only**. Values are never printed or stored.
+- Finds `process.env.KEY`, `process.env['KEY']` and `import.meta.env.KEY` in `.js/.jsx/.ts/.tsx/.mjs/.cjs/.vue/.svelte/.astro` files, skipping `node_modules`, `.git`, build output (`dist`, `build`, `.next`, ...) and plain names from `.gitignore`.
+- A template key that is not set is a **FAIL** only when the code references it; otherwise it is a **WARN** ("may be optional"). Keys set in the shell environment count as set.
+- Keys in `.env` missing from the template, keys referenced in code but defined nowhere, and `.env` not in `.gitignore` are **WARN**s, each labelled with its source.
+- Lines that cannot be parsed are reported by line number, not guessed.
+
+### ports
+
+```bash
+dev-doctor ports                # common development ports (or "ports" in .dev-doctor.json)
+dev-doctor ports 3000           # focused view of one port
+dev-doctor ports 3000 5173      # specific ports; busy ones are FAIL (exit 1)
+dev-doctor ports --json
+dev-doctor ports --kill 3000                # stop the process on 3000, asks for confirmation
+dev-doctor ports --kill 3000 --pid 8421     # pick the exact process when several share the port
+dev-doctor ports --kill 3000 --yes          # non-interactive
+dev-doctor ports --kill 3000 --yes --force  # allow force termination if it survives a graceful stop
+```
+
+#### Process inspection
+
+For every occupied port Dev Doctor collects what the OS allows:
+
+| Field | macOS | Linux | Windows |
+| --- | --- | --- | --- |
+| PID, process name | `lsof` | `ss` (or `lsof`) | `netstat`, `tasklist` |
+| Command line | `ps` | `ps` | PowerShell `Win32_Process` |
+| Parent PID | `ps` | `ps` | PowerShell `Win32_Process` |
+| User | `ps` | `ps` | not collected |
+| Working directory | `lsof -d cwd` (own processes only) | `/proc/<pid>/cwd` | not available |
+| Project association | from working directory, else command line | same | command line only |
+
+Project association is **current project**, **another project or location**, or **unknown**. Anything the OS does not expose, or that permissions hide, is shown as `unavailable (reason)`; it is never guessed. If a port is busy but its owner cannot be seen at all, the report says so instead of calling the port free. IPv4 and IPv6 listeners of the same process are merged.
+
+Command lines are redacted before they reach any output (human or JSON): URL credentials, `--password=…`/`--token …`-style flags, `SECRET_KEY=…`-style assignments and `Bearer`/`Basic` tokens become `***`. Environment variables of other processes are never read.
+
+#### Interactive workflow
+
+In an interactive terminal, after the report you can pick a process (when several ports are occupied) and choose **Inspect process**, **Stop process** or **Skip**. Stopping uses the same safe flow as `--kill`. When stdin is not a terminal, in `--ci` mode or with `--json`, no prompt is ever shown.
+
+#### Safe termination (`--kill`)
+
+1. Validates the port (1–65535) and `--pid` (positive integer). PIDs are passed as arguments, never through a shell.
+2. Lists every listener on the port. The target must be unambiguous: a single listener, `--pid`, or an interactive choice. If any listener cannot be identified (for example another user's process), it refuses.
+3. Refuses to stop dev-doctor itself, the shell that started it, PIDs 0–4 and known system processes. It only ever targets that one PID; it never kills "all Node.js processes".
+4. Shows PID, name, command line and working directory, then asks for confirmation (declining cancels; non-interactive runs need `--yes`).
+5. Checks again that the same PID still holds the port, in case it exited or the port changed hands meanwhile.
+6. Sends a graceful stop (SIGTERM / `taskkill`).
+7. If the same process is still running and still holds the port, force termination (SIGKILL / `taskkill /F`) is offered as a separate step: a second confirmation, or `--force`.
+8. Re-scans the port. "Released" is only reported when that fresh check finds it free. If the process exited but something else now holds the port, it says so and touches nothing else.
+
+Permission errors are reported as-is; Dev Doctor never uses `sudo` or requests elevation.
+
+`--kill` exit codes: 0 when the port is free afterwards (or already was), 1 when it was refused, cancelled or the port is still in use, 2 for invalid input.
+
+### services
+
+Docker CLI and daemon, plus TCP reachability of PostgreSQL, MongoDB and Redis. Services are only checked when the project appears to need them: Compose files and images, dependencies (`pg`, `mongoose`, `ioredis`, ...), or connection variables (`DATABASE_URL`, `MONGODB_URI`, `REDIS_URL`, `PGHOST`, ...). Host and port are taken from those values; credentials are never shown. A successful TCP connection does **not** mean authentication or queries work, and the report says so.
+
+Nothing is started, stopped or reconfigured.
+
+### fix
+
+```bash
+dev-doctor fix --dry-run   # list fixes, change nothing
+dev-doctor fix             # confirm each fix
+dev-doctor fix --yes       # apply without prompts (required when non-interactive)
+```
+
+Each fix shows the problem, why it matters, the proposed change, whether it modifies files or terminates a process, the expected outcome and a preview. After applying, the relevant check is re-run and the result is reported.
+
+Available fixes:
+
+| Fix | Change |
+| --- | --- |
+| `.env` missing | Creates `.env` with the key names from the template and **empty values** (never copies template values, never overwrites) |
+| `.env` not ignored | Appends `.env` to `.gitignore` |
+| Project port busy | Stops the process on that port (same safety rules as `ports --kill`) |
+
+Everything else gets manual instructions. Dev Doctor never installs or upgrades packages, deletes lockfiles, changes Node.js versions, runs migrations or uses `sudo`.
+
+## Configuration
+
+Optional `.dev-doctor.json` in the project root:
+
+```json
+{
+  "ports": [3000, 5173],
+  "failOn": "fail",
+  "services": {
+    "docker": true,
+    "postgres": { "host": "localhost", "port": 5433 },
+    "redis": false
+  }
+}
+```
+
+- `ports`: ports the project uses (checked by `doctor` and `ports`).
+- `failOn`: `"fail"` (default) or `"warn"`; `--fail-on` overrides it.
+- `services`: `true`/object to require or point a check somewhere, `false` to skip it.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | No failures (or the requested action succeeded) |
+| 1 | Diagnostics found failures, or a requested action was refused or did not succeed |
+| 2 | Dev Doctor could not run (invalid arguments, bad config, unexpected error) |
+
+In CI:
+
+```bash
+dev-doctor --ci              # exit 1 on FAIL
+dev-doctor --ci --fail-on warn
+dev-doctor --ci --json > dev-doctor.json
+```
+
+## Security
+
+See [SECURITY.md](SECURITY.md). In short: offline, read-only by default, never prints secrets, never executes project scripts, no shell string interpolation, no `sudo`, and writes only inside the project directory.
+
+## Supported operating systems
+
+| OS | Process inspection |
+| --- | --- |
+| macOS | `lsof`, `ps` |
+| Linux | `ss` (falls back to `lsof`), `ps`, `/proc` |
+| Windows | `netstat`, `tasklist`, PowerShell, `taskkill` |
+
+When these tools are missing, Dev Doctor falls back to a bind test: it can still tell whether a port is busy, but not which process owns it.
+
+The test suite has been run locally on macOS. Linux and Windows support is covered by unit tests with mocked tool output and by the GitHub Actions matrix (ubuntu, macos, windows × Node 22, 24); treat them as verified only once that CI is green.
+
+## Limitations
+
+- Environment references are found with patterns; dynamic access (`process.env[name]`) and destructuring (`const { A } = process.env`) are not detected.
+- `.gitignore` support is basic: plain names are skipped during the scan; glob patterns are not evaluated.
+- Service checks are TCP-only and use default ports unless configured; ports remapped in Compose files are not parsed.
+- On macOS, `lsof` only shows your own processes without elevated permissions; other users' processes appear as "process details not accessible", and their working directory as unavailable.
+- Working directories are not available on Windows, so project association there relies on the command line.
+- On Windows, console programs such as `node.exe` cannot be stopped gracefully (`taskkill` without `/F` is refused), so stopping them always needs the separate force step (`--force` or a second confirmation).
+- Command-line redaction is pattern-based; unusual secret formats may not be recognized.
+- `.nvmrc` aliases such as `lts/*` cannot be verified offline.
+
+## Development
+
+```bash
+npm install
+npm test
+node bin/dev-doctor.js --help
+npm link            # makes "dev-doctor" available globally from this checkout
+npm pack --dry-run  # see what would be published
+```
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Please report security issues privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © sameera_mhk
+# dev-doctor

package/bin/dev-doctor.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv);

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "dev-env-doctor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Diagnose and safely fix common local development environment problems in JavaScript and Node.js projects: ports, Node version, dependencies, .env files and local services.",
+  "type": "module",
+  "bin": {
+    "dev-doctor": "bin/dev-doctor.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "start": "node bin/dev-doctor.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "cli",
+    "doctor",
+    "diagnostics",
+    "developer-tools",
+    "port",
+    "kill-port",
+    "env",
+    "dotenv",
+    "node-version",
+    "docker"
+  ],
+  "author": "sameera_mhk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sameera-MHK/dev-doctor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sameera-MHK/dev-doctor/issues"
+  },
+  "homepage": "https://github.com/Sameera-MHK/dev-doctor#readme",
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
+    "chalk": "^6.0.1",
+    "commander": "^15.0.0",
+    "semver": "^7.8.5"
+  }
+}

package/src/checks/environment.js

@@ -0,0 +1,212 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { result, STATUS } from '../core/diagnostics.js';
+import { parseEnv } from '../utils/env-parser.js';
+import { readTextIfExists } from '../utils/paths.js';
+
+const CATEGORY = 'Environment variables';
+
+export const TEMPLATE_FILES = ['.env.example', '.env.sample', '.env.template', '.env.dist'];
+export const LOCAL_FILES = ['.env', '.env.local', '.env.development', '.env.development.local'];
+
+export const IGNORED_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', 'coverage', '.next', '.nuxt', '.svelte-kit',
+  '.output', '.turbo', '.cache', '.vercel', '.netlify', '.parcel-cache', 'tmp', 'vendor',
+]);
+
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts', '.vue', '.svelte', '.astro']);
+
+// Set by the runtime, shell or build tool; not expected in .env files.
+const BUILTIN_KEYS = new Set([
+  'NODE_ENV', 'CI', 'HOME', 'PATH', 'PWD', 'USER', 'SHELL', 'TZ', 'LANG', 'TERM', 'NO_COLOR', 'DEBUG',
+  'MODE', 'DEV', 'PROD', 'SSR', 'BASE_URL', 'PORT', 'HOST',
+]);
+
+const REFERENCE_PATTERNS = [
+  /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+  /process\.env\[\s*['"`]([A-Za-z_][A-Za-z0-9_]*)['"`]\s*\]/g,
+  /import\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+];
+
+/** Plain names from .gitignore (no globs or nested paths); used to skip directories and files. */
+export function gitignoreNames(text) {
+  const names = new Set();
+  for (const raw of (text ?? '').split(/\r?\n/)) {
+    const line = raw.trim().replace(/^\//, '').replace(/\/$/, '');
+    if (!line || line.startsWith('#') || line.startsWith('!') || /[*?[\]/]/.test(line)) continue;
+    names.add(line);
+  }
+  return names;
+}
+
+export function isEnvGitignored(text) {
+  const patterns = new Set(['.env', '/.env', '.env*', '/.env*', '*.env', '.env.*']);
+  return (text ?? '').split(/\r?\n/).some((line) => patterns.has(line.trim()));
+}
+
+export function findReferences(source) {
+  const keys = new Set();
+  for (const pattern of REFERENCE_PATTERNS) {
+    for (const match of source.matchAll(pattern)) keys.add(match[1]);
+  }
+  return keys;
+}
+
+/** Find env variable references in source files. Returns key -> Set of relative file paths. */
+export async function scanEnvReferences(root, { maxFiles = 5000, ignoredNames = new Set() } = {}) {
+  const references = new Map();
+  let scanned = 0;
+  let truncated = false;
+  const queue = [root];
+
+  while (queue.length > 0) {
+    const dir = queue.shift();
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (IGNORED_DIRS.has(entry.name) || ignoredNames.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!entry.name.startsWith('.')) queue.push(full);
+        continue;
+      }
+      if (!entry.isFile() || !SOURCE_EXTENSIONS.has(path.extname(entry.name))) continue;
+      if (scanned >= maxFiles) {
+        truncated = true;
+        break;
+      }
+      scanned++;
+      const text = readTextIfExists(full);
+      if (text === null) continue;
+      const rel = path.relative(root, full).split(path.sep).join('/');
+      for (const key of findReferences(text)) {
+        if (!references.has(key)) references.set(key, new Set());
+        references.get(key).add(rel);
+      }
+    }
+    if (truncated) break;
+  }
+  return { references, scanned, truncated };
+}
+
+function readEnvFile(root, file) {
+  const text = readTextIfExists(path.join(root, file));
+  if (text === null) return null;
+  const { entries, issues } = parseEnv(text);
+  return { file, entries, issues };
+}
+
+/** Collect env data. Values stay in memory only and are never returned in results. */
+export async function analyzeEnvironment(root) {
+  const gitignoreText = readTextIfExists(path.join(root, '.gitignore'));
+  const template = TEMPLATE_FILES.map((f) => readEnvFile(root, f)).find(Boolean) ?? null;
+  const locals = LOCAL_FILES.map((f) => readEnvFile(root, f)).filter(Boolean);
+  const scan = await scanEnvReferences(root, { ignoredNames: gitignoreNames(gitignoreText) });
+  return { template, locals, ...scan, gitignoreText };
+}
+
+function sources(files, limit = 3) {
+  const list = [...files];
+  return list.slice(0, limit).join(', ') + (list.length > limit ? ` (+${list.length - limit} more)` : '');
+}
+
+export function environmentResults(data, { env = process.env } = {}) {
+  const { template, locals, references } = data;
+  const results = [];
+
+  if (!template && locals.length === 0 && references.size === 0) {
+    return [result(CATEGORY, STATUS.INFO, 'No environment files or variable references found')];
+  }
+
+  for (const file of [template, ...locals].filter(Boolean)) {
+    for (const issue of file.issues) {
+      results.push(result(CATEGORY, STATUS.WARN, `${file.file} line ${issue.line}: ${issue.message}`, {
+        hint: `Check line ${issue.line} of ${file.file}; dev-doctor does not guess ambiguous values.`,
+      }));
+    }
+  }
+
+  const localKeys = new Set(locals.flatMap((f) => [...f.entries.keys()]));
+  const isSet = (key) => localKeys.has(key) || Object.prototype.hasOwnProperty.call(env, key);
+  const templateKeys = template ? [...template.entries.keys()] : [];
+
+  if (template) {
+    results.push(result(CATEGORY, STATUS.INFO, `Template: ${template.file} (${templateKeys.length} keys)`));
+  } else if (locals.length > 0) {
+    results.push(result(CATEGORY, STATUS.WARN, 'No .env.example template found', {
+      hint: 'Create .env.example listing the required keys without real values.',
+    }));
+  }
+
+  if (template && locals.length === 0) {
+    const unset = templateKeys.filter((k) => !Object.prototype.hasOwnProperty.call(env, k));
+    if (unset.length > 0) {
+      results.push(result(CATEGORY, STATUS.FAIL, '.env file is missing', {
+        details: [`Keys from ${template.file} not set: ${unset.join(', ')}`],
+        hint: `Create .env from ${template.file} and fill in your own values.`,
+        fixId: 'create-env',
+        fixData: { template: template.file, keys: templateKeys },
+      }));
+    }
+  } else if (template) {
+    for (const key of templateKeys) {
+      if (isSet(key)) continue;
+      const usedIn = references.get(key);
+      if (usedIn) {
+        results.push(result(CATEGORY, STATUS.FAIL, `${key} is missing`, {
+          details: [`Documented in ${template.file}`, `Referenced in ${sources(usedIn)}`],
+          hint: `Set ${key} in your local .env file.`,
+        }));
+      } else {
+        results.push(result(CATEGORY, STATUS.WARN, `${key} is listed in ${template.file} but not set (may be optional)`, {
+          details: [`Documented in ${template.file}`],
+        }));
+      }
+    }
+    const templateSet = new Set(templateKeys);
+    for (const local of locals) {
+      for (const key of local.entries.keys()) {
+        if (!templateSet.has(key)) {
+          results.push(result(CATEGORY, STATUS.WARN, `${key} is not documented in ${template.file}`, {
+            details: [`Defined in ${local.file}`],
+            hint: `Add ${key} (without its value) to ${template.file}.`,
+          }));
+        }
+      }
+    }
+  }
+
+  const templateSet = new Set(templateKeys);
+  for (const [key, files] of references) {
+    if (BUILTIN_KEYS.has(key) || templateSet.has(key) || isSet(key)) continue;
+    results.push(result(CATEGORY, STATUS.WARN, `${key} is referenced in code but not defined`, {
+      details: [`Referenced in ${sources(files)}`],
+      hint: `Add ${key} to your .env file${template ? ` and ${template.file}` : ''} if the app needs it.`,
+    }));
+  }
+
+  if (locals.some((f) => f.file === '.env') && !isEnvGitignored(data.gitignoreText)) {
+    results.push(result(CATEGORY, STATUS.WARN, '.env is not listed in .gitignore', {
+      details: ['Secrets in .env could be committed by accident'],
+      hint: 'Add ".env" to .gitignore.',
+      fixId: 'gitignore-env',
+    }));
+  }
+
+  if (data.truncated) {
+    results.push(result(CATEGORY, STATUS.INFO, `Source scan stopped after ${data.scanned} files; some references may be missing`));
+  }
+
+  if (!results.some((r) => r.status === STATUS.FAIL || r.status === STATUS.WARN)) {
+    results.push(result(CATEGORY, STATUS.PASS, template ? `All keys from ${template.file} are set` : 'Environment variables look consistent'));
+  }
+  return results;
+}
+
+export async function checkEnvironment(root, options) {
+  return environmentResults(await analyzeEnvironment(root), options);
+}