@reallavo/clonecheck 0.1.0

package/packages/core/src/detectors/ports.ts

@@ -0,0 +1,99 @@
+import path from "node:path";
+import { readTextFile } from "../utils/files.js";
+
+export interface PortDetection {
+  port: number;
+  file: string;
+}
+
+const CODE_PORT_PATTERNS = [
+  /\b(?:app|server)?\.?listen\(\s*(\d{2,5})\b/g,
+  /\blisten\(\s*(\d{2,5})\b/g,
+  /\bport\s*[:=]\s*["']?(\d{2,5})\b/gi,
+  /\b(?:PORT|VITE_PORT)\s*=\s*(\d{2,5})\b/g,
+  /\bPORT\s*\|\|\s*(\d{2,5})\b/g,
+  /--port\s+(\d{2,5})\b/g,
+  /["']\d{2,5}:(\d{2,5})["']/g
+];
+
+const README_PORT_PATTERNS = [
+  /\blocalhost:(\d{2,5})\b/gi,
+  /\b127\.0\.0\.1:(\d{2,5})\b/gi,
+  /\b0\.0\.0\.0:(\d{2,5})\b/gi
+];
+
+const PORT_FILES = new Set([
+  "package.json",
+  ".env.example",
+  ".env.sample",
+  ".env.template",
+  "example.env",
+  "vite.config.ts",
+  "vite.config.js",
+  "next.config.js",
+  "docker-compose.yml",
+  "docker-compose.yaml",
+  "compose.yml",
+  "compose.yaml"
+]);
+
+const PORT_EXTENSIONS = new Set([".cjs", ".js", ".jsx", ".mjs", ".ts", ".tsx", ".py", ".go", ".rs"]);
+
+function collectPorts(text: string, file: string, patterns: RegExp[]): PortDetection[] {
+  const ports: PortDetection[] = [];
+  for (const pattern of patterns) {
+    pattern.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(text)) !== null) {
+      const raw = match[1];
+      if (!raw) {
+        continue;
+      }
+      const port = Number.parseInt(raw, 10);
+      if (Number.isInteger(port) && port > 0 && port <= 65535) {
+        ports.push({ port, file });
+      }
+    }
+  }
+
+  return ports;
+}
+
+function isPortSourceFile(file: string): boolean {
+  return PORT_FILES.has(file) || PORT_EXTENSIONS.has(path.extname(file));
+}
+
+export async function detectRepoPorts(
+  repoPath: string,
+  files: string[],
+  readmeText?: string
+): Promise<{ codePorts: PortDetection[]; readmePorts: number[] }> {
+  const codePorts: PortDetection[] = [];
+
+  for (const file of files) {
+    if (!isPortSourceFile(file)) {
+      continue;
+    }
+
+    const text = await readTextFile(repoPath, file);
+    if (!text) {
+      continue;
+    }
+
+    codePorts.push(...collectPorts(text, file, CODE_PORT_PATTERNS));
+  }
+
+  const readmePorts = readmeText
+    ? Array.from(new Set(collectPorts(readmeText, "README.md", README_PORT_PATTERNS).map((entry) => entry.port)))
+    : [];
+
+  const uniqueCodePorts = new Map<string, PortDetection>();
+  for (const detection of codePorts) {
+    uniqueCodePorts.set(`${detection.file}:${detection.port}`, detection);
+  }
+
+  return {
+    codePorts: Array.from(uniqueCodePorts.values()),
+    readmePorts
+  };
+}

package/packages/core/src/detectors/project.ts

@@ -0,0 +1,50 @@
+import type { PackageJson, ProjectType } from "../types.js";
+
+export function parsePackageJson(text: string | undefined): PackageJson | undefined {
+  if (!text) {
+    return undefined;
+  }
+
+  try {
+    const value = JSON.parse(text) as unknown;
+    if (typeof value === "object" && value !== null) {
+      return value as PackageJson;
+    }
+  } catch {
+    return undefined;
+  }
+
+  return undefined;
+}
+
+export function detectProjectTypes(files: string[]): ProjectType[] {
+  const types = new Set<ProjectType>();
+
+  if (files.includes("package.json")) {
+    types.add("node");
+  }
+  if (files.some((file) => file === "pyproject.toml" || file === "requirements.txt" || file.endsWith(".py"))) {
+    types.add("python");
+  }
+  if (files.includes("go.mod") || files.some((file) => file.endsWith(".go"))) {
+    types.add("go");
+  }
+  if (files.includes("Cargo.toml") || files.some((file) => file.endsWith(".rs"))) {
+    types.add("rust");
+  }
+  if (
+    files.some(
+      (file) =>
+        file === "Dockerfile" ||
+        file.endsWith("/Dockerfile") ||
+        file === "docker-compose.yml" ||
+        file === "docker-compose.yaml" ||
+        file === "compose.yml" ||
+        file === "compose.yaml"
+    )
+  ) {
+    types.add("docker");
+  }
+
+  return Array.from(types);
+}

package/packages/core/src/detectors/readme.ts

@@ -0,0 +1,131 @@
+import type { PackageManager } from "../types.js";
+import { findAnyCaseInsensitive } from "../utils/files.js";
+import { isPackageManager } from "./packageManager.js";
+
+export const README_FILENAMES = ["README.md", "readme.md", "Readme.md"];
+
+export interface ReadmeCommand {
+  command: string;
+  packageManager?: PackageManager;
+  kind: "install" | "run" | "test" | "build" | "docker" | "other";
+}
+
+const SHELL_LANGUAGES = new Set(["", "bash", "sh", "shell", "zsh", "console", "terminal"]);
+
+export function findReadmeFile(files: string[]): string | undefined {
+  return findAnyCaseInsensitive(files, README_FILENAMES);
+}
+
+function normalizeCommand(line: string): string {
+  return line
+    .trim()
+    .replace(/^(?:\$|>|❯)\s*/, "")
+    .replace(/^sudo\s+/, "");
+}
+
+export function extractShellBlocks(markdown: string): string[] {
+  const blocks: string[] = [];
+  const fenceRegex = /```([A-Za-z0-9_-]*)[^\n]*\n([\s\S]*?)```/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = fenceRegex.exec(markdown)) !== null) {
+    const language = (match[1] ?? "").toLowerCase();
+    const body = match[2] ?? "";
+    if (SHELL_LANGUAGES.has(language)) {
+      blocks.push(body);
+    }
+  }
+
+  return blocks;
+}
+
+function detectKind(command: string): ReadmeCommand["kind"] {
+  if (/\bdocker(?:\s+compose|-compose)\s+up\b/.test(command)) {
+    return "docker";
+  }
+  if (/\b(?:npm|pnpm|yarn|bun)\s+(?:install|i)\b/.test(command)) {
+    return "install";
+  }
+  if (hasPackageScriptCommand(command, "test")) {
+    return "test";
+  }
+  if (hasPackageScriptCommand(command, "build")) {
+    return "build";
+  }
+  if (
+    hasPackageScriptCommand(command, "dev") ||
+    hasPackageScriptCommand(command, "start") ||
+    hasPackageScriptCommand(command, "serve")
+  ) {
+    return "run";
+  }
+
+  return "other";
+}
+
+function hasPackageScriptCommand(command: string, scriptName: string): boolean {
+  const escaped = scriptName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const npmPattern = new RegExp(`\\bnpm\\s+run\\s+${escaped}\\b`);
+  const directPattern = new RegExp(
+    `\\b(?:pnpm|yarn|bun)\\b(?:\\s+(?:--filter|-F)\\s+\\S+)?\\s+(?:run\\s+)?${escaped}\\b`
+  );
+  const bunRunPattern = new RegExp(`\\bbun\\s+run\\s+${escaped}\\b`);
+
+  return npmPattern.test(command) || directPattern.test(command) || bunRunPattern.test(command);
+}
+
+function detectPackageManagerFromCommand(command: string): PackageManager | undefined {
+  const match = command.match(/\b(npm|pnpm|yarn|bun)\b/);
+  const manager = match?.[1];
+  return manager && isPackageManager(manager) ? manager : undefined;
+}
+
+export function extractReadmeCommands(markdown: string): ReadmeCommand[] {
+  const commands: ReadmeCommand[] = [];
+
+  for (const block of extractShellBlocks(markdown)) {
+    for (const rawLine of block.split(/\r?\n/)) {
+      const command = normalizeCommand(rawLine);
+      if (!command || command.startsWith("#")) {
+        continue;
+      }
+
+      const packageManager = detectPackageManagerFromCommand(command);
+      const kind = detectKind(command);
+      if (packageManager || kind !== "other") {
+        commands.push({ command, packageManager, kind });
+      }
+    }
+  }
+
+  return commands;
+}
+
+export function readmeMentionsRunCommand(commands: ReadmeCommand[]): boolean {
+  return commands.some((command) => command.kind === "run" || command.kind === "docker");
+}
+
+export function readmeMentionsSetupCommand(commands: ReadmeCommand[]): boolean {
+  return commands.some(
+    (command) =>
+      command.kind === "docker" ||
+      (command.kind === "install" && !isPackageInstallCommand(command.command))
+  );
+}
+
+export function isPackageInstallCommand(command: string): boolean {
+  const parts = command.trim().split(/\s+/);
+  const managerIndex = parts.findIndex((part) => part === "npm" || part === "pnpm" || part === "yarn" || part === "bun");
+  if (managerIndex < 0) {
+    return false;
+  }
+
+  const installIndex = parts.findIndex(
+    (part, index) => index > managerIndex && (part === "install" || part === "i")
+  );
+  if (installIndex < 0) {
+    return false;
+  }
+
+  return parts.slice(installIndex + 1).some((part) => !part.startsWith("-") && !part.includes("="));
+}

package/packages/core/src/index.ts

@@ -0,0 +1,31 @@
+export {
+  CLONECHECK_VERSION,
+  DEFAULT_CONFIG,
+  type CheckStatus,
+  type ClonecheckCheck,
+  type ClonecheckCheckResult,
+  type ClonecheckConfig,
+  type ClonecheckContext,
+  type ClonecheckIssue,
+  type ClonecheckReport,
+  type PackageJson,
+  type PackageManager,
+  type ProjectType,
+  type RunClonecheckOptions,
+  type Severity
+} from "./types.js";
+export { ClonecheckConfigError, initConfig, loadConfig } from "./config.js";
+export { createClonecheckContext, runClonecheck } from "./run.js";
+export { getChecks } from "./checks/index.js";
+export { detectPackageManager } from "./detectors/packageManager.js";
+export {
+  detectEnvVarUsages,
+  extractEnvVarUsages,
+  findMissingEnvVars,
+  generateEnvExample,
+  parseEnvExampleVars
+} from "./detectors/env.js";
+export { extractReadmeCommands, extractShellBlocks, isPackageInstallCommand } from "./detectors/readme.js";
+export { detectDockerComposeEnvVars, extractDockerComposeEnvVars } from "./detectors/dockerCompose.js";
+export { collectSuggestions, scoreChecks, scoreImpactForIssues, statusFromScore } from "./scoring.js";
+export { formatJsonReport, formatMarkdownReport, formatTextReport } from "./reporters/index.js";

package/packages/core/src/reporters/index.ts

@@ -0,0 +1,3 @@
+export { formatJsonReport } from "./json.js";
+export { formatMarkdownReport } from "./markdown.js";
+export { formatTextReport, type TextReporterOptions } from "./text.js";

package/packages/core/src/reporters/json.ts

@@ -0,0 +1,5 @@
+import type { ClonecheckReport } from "../types.js";
+
+export function formatJsonReport(report: ClonecheckReport): string {
+  return JSON.stringify(report, null, 2);
+}

package/packages/core/src/reporters/labels.ts

@@ -0,0 +1,40 @@
+import type { CheckStatus, ClonecheckReport } from "../types.js";
+
+export function statusSymbol(status: CheckStatus): string {
+  switch (status) {
+    case "pass":
+      return "✅";
+    case "warning":
+      return "⚠️";
+    case "fail":
+      return "❌";
+    case "skip":
+      return "⏭️";
+  }
+}
+
+export function checkStatusLabel(status: CheckStatus): string {
+  switch (status) {
+    case "pass":
+      return "Pass";
+    case "warning":
+      return "Warning";
+    case "fail":
+      return "Fail";
+    case "skip":
+      return "Skip";
+  }
+}
+
+export function reportStatusLabel(status: ClonecheckReport["status"]): string {
+  switch (status) {
+    case "excellent":
+      return "Excellent";
+    case "good":
+      return "Good";
+    case "needs-work":
+      return "Needs work";
+    case "poor":
+      return "Poor";
+  }
+}

package/packages/core/src/reporters/markdown.ts

@@ -0,0 +1,63 @@
+import type { ClonecheckIssue, ClonecheckReport } from "../types.js";
+import { checkStatusLabel, reportStatusLabel, statusSymbol } from "./labels.js";
+
+function escapeTableCell(value: string): string {
+  return value.replace(/\|/g, "\\|");
+}
+
+function formatIssue(issue: ClonecheckIssue): string {
+  const location = issue.file ? ` (${issue.file}${issue.line ? `:${issue.line}` : ""})` : "";
+  return `- **${issue.title}**${location}: ${issue.message}`;
+}
+
+export function formatMarkdownReport(report: ClonecheckReport): string {
+  const lines: string[] = [
+    "# Clonecheck Report",
+    "",
+    `Score: ${report.score}/100  `,
+    `Status: ${reportStatusLabel(report.status)}`,
+    "",
+    "## Summary",
+    "",
+    "| Check | Status | Issues |",
+    "|---|---:|---:|"
+  ];
+
+  for (const check of report.checks) {
+    lines.push(
+      `| ${escapeTableCell(check.id)} | ${statusSymbol(check.status)} ${checkStatusLabel(check.status)} | ${check.issues.length} |`
+    );
+  }
+
+  const checksWithIssues = report.checks.filter((check) => check.issues.length > 0);
+  if (checksWithIssues.length > 0) {
+    lines.push("", "## Issues", "");
+    for (const check of checksWithIssues) {
+      lines.push(`### ${check.id}`, "");
+      for (const issue of check.issues) {
+        lines.push(formatIssue(issue));
+      }
+      lines.push("");
+    }
+  }
+
+  if (report.suggestions.length > 0) {
+    lines.push("## Suggestions", "");
+    report.suggestions.forEach((suggestion, index) => {
+      lines.push(`${index + 1}. ${suggestion}`);
+    });
+    lines.push("");
+  }
+
+  lines.push(
+    "## Metadata",
+    "",
+    `- Repository: \`${report.projectName}\``,
+    `- Path: \`${report.repoPath}\``,
+    `- Project types: ${report.metadata.detectedProjectTypes.join(", ") || "unknown"}`,
+    `- Package manager: ${report.metadata.detectedPackageManager ?? "unknown"}`,
+    `- Generated at: ${report.metadata.generatedAt}`
+  );
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/packages/core/src/reporters/text.ts

@@ -0,0 +1,108 @@
+import pc from "picocolors";
+import type { CheckStatus, ClonecheckCheckResult, ClonecheckReport } from "../types.js";
+import { reportStatusLabel, statusSymbol } from "./labels.js";
+
+export interface TextReporterOptions {
+  color?: boolean;
+}
+
+function colorizeStatus(status: CheckStatus, text: string, useColor: boolean): string {
+  if (!useColor) {
+    return text;
+  }
+
+  switch (status) {
+    case "pass":
+      return pc.green(text);
+    case "warning":
+      return pc.yellow(text);
+    case "fail":
+      return pc.red(text);
+    case "skip":
+      return pc.dim(text);
+  }
+}
+
+function defaultPassMessage(check: ClonecheckCheckResult, report: ClonecheckReport): string {
+  if (check.status === "skip") {
+    return "not applicable for this repository";
+  }
+
+  switch (check.id) {
+    case "package-manager-consistency":
+      return report.metadata.detectedPackageManager
+        ? `package manager is consistent: ${report.metadata.detectedPackageManager}`
+        : "no package manager mismatch found";
+    case "scripts-availability":
+      return "package scripts include an obvious local workflow";
+    case "env-example":
+      return "environment variables used in code are documented";
+    case "readme-commands":
+      return "README setup commands look consistent";
+    case "port-documentation":
+      return "README port documentation looks consistent";
+    case "docker-compose-env":
+      return "Docker Compose environment variables are documented";
+    case "project-files":
+      return "core project files are present";
+    case "ci-presence":
+      return "found at least one GitHub Actions workflow";
+    default:
+      return "no issues found";
+  }
+}
+
+function formatIssueLocation(file?: string, line?: number): string {
+  if (!file) {
+    return "";
+  }
+
+  return line ? ` (${file}:${line})` : ` (${file})`;
+}
+
+function formatCheck(check: ClonecheckCheckResult, report: ClonecheckReport, useColor: boolean): string[] {
+  const symbol = statusSymbol(check.status);
+  const label = colorizeStatus(check.status, check.id, useColor);
+  const lines = [`  ${symbol} ${label}`];
+
+  if (check.issues.length === 0) {
+    lines.push(`     ${defaultPassMessage(check, report)}`);
+    return lines;
+  }
+
+  for (const issue of check.issues) {
+    const location = formatIssueLocation(issue.file, issue.line);
+    lines.push(`     ${issue.message}${location}`);
+  }
+
+  return lines;
+}
+
+export function formatTextReport(report: ClonecheckReport, options: TextReporterOptions = {}): string {
+  const useColor = options.color ?? Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
+  const lines = [
+    `clonecheck v${report.metadata.clonecheckVersion}`,
+    "",
+    `Repository: ${report.projectName}`,
+    `Path: ${report.repoPath}`,
+    "",
+    `Score: ${report.score}/100`,
+    `Status: ${reportStatusLabel(report.status)}`,
+    "",
+    "Checks:"
+  ];
+
+  for (const check of report.checks) {
+    lines.push(...formatCheck(check, report, useColor), "");
+  }
+
+  if (report.suggestions.length > 0) {
+    lines.push("Suggestions:");
+    report.suggestions.forEach((suggestion, index) => {
+      lines.push(`  ${index + 1}. ${suggestion}`);
+    });
+    lines.push("");
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/packages/core/src/run.ts

@@ -0,0 +1,111 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { getChecks } from "./checks/index.js";
+import { createResult } from "./checks/helpers.js";
+import { loadConfig } from "./config.js";
+import { loadEnvExampleFiles } from "./detectors/env.js";
+import { detectPackageManager } from "./detectors/packageManager.js";
+import { detectProjectTypes, parsePackageJson } from "./detectors/project.js";
+import { findReadmeFile } from "./detectors/readme.js";
+import { collectSuggestions, scoreChecks, statusFromScore } from "./scoring.js";
+import {
+  CLONECHECK_VERSION,
+  type ClonecheckContext,
+  type ClonecheckReport,
+  type RunClonecheckOptions
+} from "./types.js";
+import { discoverFiles, readTextFile } from "./utils/files.js";
+
+async function assertDirectory(repoPath: string): Promise<void> {
+  try {
+    const info = await stat(repoPath);
+    if (!info.isDirectory()) {
+      throw new Error(`${repoPath} is not a directory.`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.endsWith("is not a directory.")) {
+      throw error;
+    }
+    throw new Error(`Repository path does not exist or cannot be read: ${repoPath}`);
+  }
+}
+
+function projectNameFromPackageJson(packageJson: unknown): string | undefined {
+  if (!packageJson || typeof packageJson !== "object") {
+    return undefined;
+  }
+
+  const name = (packageJson as { name?: unknown }).name;
+  return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+
+export async function createClonecheckContext(options: RunClonecheckOptions): Promise<{
+  context: ClonecheckContext;
+  projectName: string;
+}> {
+  const repoPath = path.resolve(options.repoPath);
+  await assertDirectory(repoPath);
+
+  const { config } = await loadConfig(repoPath, options.configPath);
+  const files = await discoverFiles(repoPath, config.ignore);
+  const packageJson = parsePackageJson(await readTextFile(repoPath, "package.json"));
+  const readmeFile = findReadmeFile(files);
+  const readmeText = readmeFile ? await readTextFile(repoPath, readmeFile) : undefined;
+  const envExamples = await loadEnvExampleFiles(repoPath, files);
+  const detectedProjectTypes = detectProjectTypes(files);
+  const packageManager = detectPackageManager(files, packageJson);
+
+  return {
+    projectName: projectNameFromPackageJson(packageJson) ?? path.basename(repoPath),
+    context: {
+      repoPath,
+      files,
+      config,
+      packageJson,
+      readmeText,
+      envExampleText: envExamples.text,
+      envExampleVars: envExamples.vars,
+      detectedProjectTypes,
+      detectedPackageManager: packageManager.manager,
+      strict: Boolean(options.strict)
+    }
+  };
+}
+
+export async function runClonecheck(options: RunClonecheckOptions): Promise<ClonecheckReport> {
+  const { context, projectName } = await createClonecheckContext(options);
+  const rawResults = [];
+
+  for (const check of getChecks()) {
+    if (context.config.checks[check.id] === false) {
+      rawResults.push(
+        createResult({
+          id: check.id,
+          title: check.title,
+          status: "skip"
+        })
+      );
+      continue;
+    }
+
+    rawResults.push(await check.run(context));
+  }
+
+  const scored = scoreChecks(rawResults, context.strict);
+  const suggestions = collectSuggestions(scored.checks);
+
+  return {
+    repoPath: context.repoPath,
+    projectName,
+    score: scored.score,
+    status: statusFromScore(scored.score),
+    checks: scored.checks,
+    suggestions,
+    metadata: {
+      detectedProjectTypes: context.detectedProjectTypes,
+      detectedPackageManager: context.detectedPackageManager,
+      generatedAt: new Date().toISOString(),
+      clonecheckVersion: CLONECHECK_VERSION
+    }
+  };
+}