projectmedic 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+
+ISC License
+
+Copyright (c) 2026 Akhil Pal
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# Project 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.
+A Node.js project health checker that identifies missing or misconfigured project metadata and files.
+
+## Features
+
+- Validates `package.json`
+- Checks package name, version, and description
+- Checks for a README, `.gitignore`, and license
+- Checks for a test script and repository metadata
+- Checks for a Node.js version requirement
+- Provides a JavaScript API and command-line interface
+- Supports JSON output
+
+## Requirements
+
+- Node.js
+
+## Usage
+
+Run the checker against the current directory:
+
+```bash
+node bin/doctor.js .
+```
+
+Check another project:
+
+```bash
+node bin/doctor.js /path/to/project
+```
+
+Output a JSON report:
+
+```bash
+node bin/doctor.js . --json
+```
+
+## Library API
+
+```js
+import { inspectProject } from "project-doctor";
+
+const report = await inspectProject("./my-project");
+
+console.log(report.summary);
+console.log(report.findings);
+```
+
+The report contains the project path, a summary of check results, and individual findings.
+
+## Development
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+## License
+
+ISC

package/bin/doctor.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { inspectProject } from "../src/index.js";
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes("--json");
+const projectPath = args.find((arg) => !arg.startsWith("--")) || ".";
+
+try {
+  const report = await inspectProject(projectPath);
+
+  if (report.summary.failed > 0) {
+    process.exitCode = 1;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log("\nProject Doctor\n");
+
+    for (const finding of report.findings) {
+      const symbol =
+        finding.status === "pass"
+          ? "✓"
+          : finding.status === "warn"
+            ? "⚠"
+            : "✗";
+
+      console.log(`${symbol} ${finding.message}`);
+    }
+
+    console.log(`\n${report.summary.total} checks completed`);
+    console.log(
+      `${report.summary.passed} passed, ` +
+      `${report.summary.warnings} warnings, ` +
+      `${report.summary.failed} failed`
+    );
+  }
+} catch (error) {
+  if (jsonMode) {
+    console.log(JSON.stringify({ error: error.message }, null, 2));
+  } else {
+    console.error(`Project Doctor: ${error.message}`);
+  }
+
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "projectmedic",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "A Node.js project health checker that identifies missing or misconfigured project metadata and files.",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "project-doctor": "bin/doctor.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "nodejs",
+    "project-health",
+    "cli",
+    "developer-tools",
+    "project-checker"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amethystakira/project-doctor.git"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/src/finding.js

@@ -0,0 +1,14 @@
+// Create a standardized result for every project check.
+export function createFinding(id, name, status, message) {
+  return { id, name, status, message };
+}
+
+// Report a check that could not run because package.json is unavailable.
+export function createSkippedFinding(id, name) {
+  return createFinding(
+    id,
+    name,
+    "warn",
+    "Check skipped because package.json is missing or invalid"
+  );
+}

package/src/index.js

@@ -0,0 +1,71 @@
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { scanProject } from "./scanner.js";
+
+// Import all project checks.
+import { checkPackageJson } from "./rules/package-json.js";
+import { checkPackageName } from "./rules/package-name.js";
+import { checkPackageVersion } from "./rules/package-version.js";
+import { checkDescription } from "./rules/description.js";
+import { checkReadme } from "./rules/readme.js";
+import { checkGitignore } from "./rules/gitignore.js";
+import { checkLicense } from "./rules/license.js";
+import { checkTestScript } from "./rules/test-script.js";
+import { checkRepository } from "./rules/repository.js";
+import { checkNodeVersion } from "./rules/node-version.js";
+
+const rules = [
+  checkPackageJson,
+  checkPackageName,
+  checkPackageVersion,
+  checkDescription,
+  checkReadme,
+  checkGitignore,
+  checkLicense,
+  checkTestScript,
+  checkRepository,
+  checkNodeVersion
+];
+
+// Inspect a project and return its complete health report.
+export async function inspectProject(projectPath = ".") {
+  if (typeof projectPath !== "string" || !projectPath.trim()) {
+    throw new TypeError("Project path must be a non-empty string");
+  }
+
+  const absolutePath = path.resolve(projectPath);
+
+  // Reject missing paths and paths that are not directories.
+  let stats;
+
+  try {
+    stats = await import("node:fs/promises").then(
+      ({ stat }) => stat(absolutePath)
+    );
+  } catch {
+    throw new Error(`Project path does not exist: ${absolutePath}`);
+  }
+
+  if (!stats.isDirectory()) {
+    throw new Error(`Project path is not a directory: ${absolutePath}`);
+  }
+
+  const findings = await scanProject(absolutePath, rules);
+
+  const summary = {
+    total: findings.length,
+    passed: findings.filter((item) => item.status === "pass").length,
+    warnings: findings.filter((item) => item.status === "warn").length,
+    failed: findings.filter((item) => item.status === "fail").length
+  };
+
+  return {
+    path: absolutePath,
+    summary,
+    findings
+  };
+}
+
+// Allow the package to be imported without running the CLI.
+export { rules };

package/src/package.js

@@ -0,0 +1,19 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// Read and validate the project's package.json.
+export async function readPackageJson(projectPath) {
+  const packagePath = path.join(projectPath, "package.json");
+  const content = await fs.readFile(packagePath, "utf8");
+  const data = JSON.parse(content);
+
+  if (
+    data === null ||
+    typeof data !== "object" ||
+    Array.isArray(data)
+  ) {
+    throw new Error("package.json must contain a JSON object");
+  }
+
+  return data;
+}

package/src/rules/description.js

@@ -0,0 +1,25 @@
+
+import { createFinding, createSkippedFinding } from "../finding.js";
+
+// Check whether package.json has a description.
+export async function checkDescription(context) {
+  if (context.packageJsonError) {
+    return createSkippedFinding("description", "description");
+  }
+
+  if (context.packageJson.description) {
+    return createFinding(
+      "description",
+      "description",
+      "pass",
+      "Package description exists"
+    );
+  }
+
+  return createFinding(
+    "description",
+    "description",
+    "warn",
+    "Package description is missing"
+  );
+}

package/src/rules/gitignore.js

@@ -0,0 +1,18 @@
+
+import path from "node:path";
+import { pathExists } from "../scanner.js";
+import { createFinding } from "../finding.js";
+
+// Check whether .gitignore exists.
+export async function checkGitignore(context) {
+  const exists = await pathExists(
+    path.join(context.projectPath, ".gitignore")
+  );
+
+  return createFinding(
+    "gitignore",
+    ".gitignore",
+    exists ? "pass" : "warn",
+    exists ? ".gitignore exists" : ".gitignore is missing"
+  );
+}

package/src/rules/license.js

@@ -0,0 +1,18 @@
+
+import path from "node:path";
+import { pathExists } from "../scanner.js";
+import { createFinding } from "../finding.js";
+
+// Check whether LICENSE exists.
+export async function checkLicense(context) {
+  const exists = await pathExists(
+    path.join(context.projectPath, "LICENSE")
+  );
+
+  return createFinding(
+    "license",
+    "LICENSE",
+    exists ? "pass" : "warn",
+    exists ? "LICENSE exists" : "LICENSE is missing"
+  );
+}

package/src/rules/node-version.js

@@ -0,0 +1,21 @@
+
+import { createFinding, createSkippedFinding } from "../finding.js";
+
+// Check whether a Node.js version requirement is configured.
+export async function checkNodeVersion(context) {
+  if (context.packageJsonError) {
+    return createSkippedFinding("node-version", "Node.js version");
+  }
+
+  const nodeVersion = context.packageJson.engines?.node?.trim();
+  const exists = Boolean(nodeVersion);
+
+  return createFinding(
+    "node-version",
+    "Node.js version",
+    exists ? "pass" : "warn",
+    exists
+      ? `Node.js requirement is "${nodeVersion}"`
+      : "Node.js version requirement is missing"
+  );
+}

package/src/rules/package-json.js

@@ -0,0 +1,15 @@
+import { createFinding } from "../finding.js";
+
+// Check whether package.json exists and contains valid JSON.
+export async function checkPackageJson(context) {
+  const valid = !context.packageJsonError;
+
+  return createFinding(
+    "package-json",
+    "package.json",
+    valid ? "pass" : "fail",
+    valid
+      ? "package.json exists and is valid"
+      : "package.json is missing or invalid"
+  );
+}

package/src/rules/package-name.js

@@ -0,0 +1,27 @@
+
+import { createFinding, createSkippedFinding } from "../finding.js";
+
+// Check whether package.json has a name.
+export async function checkPackageName(context) {
+  const { packageJson, packageJsonError } = context;
+
+  if (context.packageJsonError) {
+  return createSkippedFinding("package-name", "package name");
+}
+
+  if (packageJson.name) {
+    return createFinding(
+      "package-name",
+      "package name",
+      "pass",
+      `Package name is "${packageJson.name}"`
+    );
+  }
+
+  return createFinding(
+    "package-name",
+    "package name",
+    "fail",
+    "Package name is missing"
+  );
+}

package/src/rules/package-version.js

@@ -0,0 +1,27 @@
+
+import { createFinding, createSkippedFinding } from "../finding.js";
+
+// Check whether package.json has a version.
+export async function checkPackageVersion(context) {
+  const { packageJson, packageJsonError } = context;
+
+  if (packageJsonError) {
+    return createSkippedFinding("package-version", "package version");
+  }
+
+  if (packageJson.version) {
+    return createFinding(
+      "package-version",
+      "package version",
+      "pass",
+      `Package version is "${packageJson.version}"`
+    );
+  }
+
+  return createFinding(
+    "package-version",
+    "package version",
+    "fail",
+    "Package version is missing"
+  );
+}

package/src/rules/readme.js

@@ -0,0 +1,18 @@
+
+import path from "node:path";
+import { pathExists } from "../scanner.js";
+import { createFinding } from "../finding.js";
+
+// Check whether README.md exists.
+export async function checkReadme(context) {
+  const exists = await pathExists(
+    path.join(context.projectPath, "README.md")
+  );
+
+  return createFinding(
+    "readme",
+    "README",
+    exists ? "pass" : "warn",
+    exists ? "README.md exists" : "README.md is missing"
+  );
+}

package/src/rules/repository.js

@@ -0,0 +1,26 @@
+
+import { createFinding, createSkippedFinding } from "../finding.js";
+
+// Check whether repository metadata is configured.
+export async function checkRepository(context) {
+  if (context.packageJsonError) {
+    return createSkippedFinding("repository", "repository");
+  }
+
+  const repository = context.packageJson.repository;
+
+  const exists = Boolean(
+    typeof repository === "string"
+      ? repository.trim()
+      : repository?.url?.trim()
+  );
+
+  return createFinding(
+    "repository",
+    "repository",
+    exists ? "pass" : "warn",
+    exists
+      ? "Repository metadata exists"
+      : "Repository metadata is missing"
+  );
+}

package/src/rules/test-script.js

@@ -0,0 +1,18 @@
+
+import { createFinding, createSkippedFinding } from "../finding.js";
+
+// Check whether a test script is configured.
+export async function checkTestScript(context) {
+  if (context.packageJsonError) {
+    return createSkippedFinding("test-script", "test script");
+  }
+
+  const exists = Boolean(context.packageJson.scripts?.test);
+
+  return createFinding(
+    "test-script",
+    "test script",
+    exists ? "pass" : "warn",
+    exists ? "Test script exists" : "Test script is missing"
+  );
+}

package/src/scanner.js

@@ -0,0 +1,45 @@
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readPackageJson } from "./package.js";
+
+// Check whether a path exists.
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Load reusable project data once.
+export async function createProjectContext(projectPath) {
+  const absolutePath = path.resolve(projectPath);
+  let packageJson = null;
+  let packageJsonError = null;
+
+  try {
+    packageJson = await readPackageJson(absolutePath);
+  } catch (error) {
+    packageJsonError = error;
+  }
+
+  return {
+    projectPath: absolutePath,
+    packageJson,
+    packageJsonError
+  };
+}
+
+// Run all checks using the same project context.
+export async function scanProject(projectPath, rules) {
+  const context = await createProjectContext(projectPath);
+  const findings = [];
+
+  for (const rule of rules) {
+    findings.push(await rule(context));
+  }
+
+  return findings;
+}