clonecheck-monorepo 0.1.0

package/packages/core/src/checks/portDocumentation.ts

@@ -0,0 +1,62 @@
+import type { ClonecheckCheck, ClonecheckIssue } from "../types.js";
+import { detectRepoPorts } from "../detectors/ports.js";
+import { createIssue, createResult } from "./helpers.js";
+
+export const portDocumentationCheck: ClonecheckCheck = {
+  id: "port-documentation",
+  title: "Port documentation",
+  description: "Checks whether README localhost ports match likely ports used by the app.",
+  async run(context) {
+    if (!context.readmeText) {
+      return createResult({
+        id: this.id,
+        title: this.title,
+        status: "skip"
+      });
+    }
+
+    const { codePorts, readmePorts } = await detectRepoPorts(context.repoPath, context.files, context.readmeText);
+    const uniqueCodePorts = Array.from(new Set(codePorts.map((entry) => entry.port))).sort((a, b) => a - b);
+    const issues: ClonecheckIssue[] = [];
+
+    if (uniqueCodePorts.length === 0) {
+      return createResult({
+        id: this.id,
+        title: this.title,
+        issues
+      });
+    }
+
+    if (readmePorts.length === 0) {
+      const first = codePorts[0];
+      issues.push(
+        createIssue({
+          id: "port-documentation.missing-readme-port",
+          title: "README does not mention the app port",
+          message: `The app appears to use port ${uniqueCodePorts.join(", ")}, but README does not mention a localhost port.`,
+          severity: "warning",
+          file: first?.file,
+          suggestion: `Mention http://localhost:${uniqueCodePorts[0]} in the README quickstart.`
+        })
+      );
+    } else if (!uniqueCodePorts.some((port) => readmePorts.includes(port))) {
+      const first = codePorts[0];
+      issues.push(
+        createIssue({
+          id: "port-documentation.mismatch",
+          title: "README mentions a different port",
+          message: `The app appears to use port ${uniqueCodePorts.join(", ")}, but README mentions ${readmePorts.join(", ")}.`,
+          severity: "warning",
+          file: first?.file,
+          suggestion: `Update README quickstart port from ${readmePorts[0]} to ${uniqueCodePorts[0]}.`
+        })
+      );
+    }
+
+    return createResult({
+      id: this.id,
+      title: this.title,
+      issues
+    });
+  }
+};

package/packages/core/src/checks/projectFiles.ts

@@ -0,0 +1,77 @@
+import type { ClonecheckCheck } from "../types.js";
+import { findReadmeFile } from "../detectors/readme.js";
+import { findAnyCaseInsensitive } from "../utils/files.js";
+import { createIssue, createResult } from "./helpers.js";
+
+export const projectFilesCheck: ClonecheckCheck = {
+  id: "project-files",
+  title: "Project files",
+  description: "Checks for README, contributing, license, and gitignore files.",
+  async run(context) {
+    const issues = [];
+
+    if (!findReadmeFile(context.files)) {
+      issues.push(
+        createIssue({
+          id: "project-files.readme",
+          title: "README is missing",
+          message: "Repository does not include a README.md file.",
+          severity: "error",
+          suggestion: "Add a README with setup, run, and contribution instructions."
+        })
+      );
+    }
+
+    if (!context.files.includes(".gitignore")) {
+      issues.push(
+        createIssue({
+          id: "project-files.gitignore",
+          title: ".gitignore is missing",
+          message: "Repository does not include a .gitignore file.",
+          severity: "warning",
+          suggestion: "Add a .gitignore for generated files and local secrets."
+        })
+      );
+    }
+
+    if (context.config.checks.contributing !== false) {
+      const contributing = findAnyCaseInsensitive(context.files, [
+        "CONTRIBUTING.md",
+        ".github/CONTRIBUTING.md",
+        "docs/CONTRIBUTING.md"
+      ]);
+      if (!contributing) {
+        issues.push(
+          createIssue({
+            id: "project-files.contributing",
+            title: "Contributing guide is missing",
+            message: "Repository does not include a CONTRIBUTING.md file.",
+            severity: "info",
+            suggestion: "Add CONTRIBUTING.md with local setup and pull request guidance."
+          })
+        );
+      }
+    }
+
+    if (context.config.checks.license !== false) {
+      const license = findAnyCaseInsensitive(context.files, ["LICENSE", "LICENSE.md", "COPYING"]);
+      if (!license) {
+        issues.push(
+          createIssue({
+            id: "project-files.license",
+            title: "License is missing",
+            message: "Repository does not include a license file.",
+            severity: "info",
+            suggestion: "Add a LICENSE file so contributors know how the project can be used."
+          })
+        );
+      }
+    }
+
+    return createResult({
+      id: this.id,
+      title: this.title,
+      issues
+    });
+  }
+};

package/packages/core/src/checks/readmeCommands.ts

@@ -0,0 +1,87 @@
+import type { ClonecheckCheck } from "../types.js";
+import {
+  extractReadmeCommands,
+  isPackageInstallCommand,
+  readmeMentionsRunCommand,
+  readmeMentionsSetupCommand
+} from "../detectors/readme.js";
+import { asPackageJson, createIssue, createResult } from "./helpers.js";
+
+export const readmeCommandsCheck: ClonecheckCheck = {
+  id: "readme-commands",
+  title: "README commands",
+  description: "Checks whether README setup and run commands are present and aligned with the repo.",
+  async run(context) {
+    if (!context.readmeText) {
+      return createResult({
+        id: this.id,
+        title: this.title,
+        status: "skip"
+      });
+    }
+
+    const commands = extractReadmeCommands(context.readmeText);
+    const issues = [];
+
+    if (!readmeMentionsSetupCommand(commands)) {
+      issues.push(
+        createIssue({
+          id: "readme-commands.no-setup-command",
+          title: "README has no setup command",
+          message: "README does not include an obvious install or docker compose setup command.",
+          severity: "warning",
+          file: "README.md",
+          suggestion: "Add a quickstart command such as pnpm install or docker compose up."
+        })
+      );
+    }
+
+    if (context.detectedPackageManager) {
+      const mismatchedManagers = Array.from(
+        new Set(
+          commands
+            .filter((command) => !(command.kind === "install" && isPackageInstallCommand(command.command)))
+            .map((command) => command.packageManager)
+            .filter((manager) => manager && manager !== context.detectedPackageManager)
+        )
+      );
+
+      for (const manager of mismatchedManagers) {
+        if (!manager) {
+          continue;
+        }
+        issues.push(
+          createIssue({
+            id: `readme-commands.${manager}`,
+            title: "README command conflicts with lockfile",
+            message: `README uses ${manager} commands, but the detected package manager is ${context.detectedPackageManager}.`,
+            severity: "warning",
+            file: "README.md",
+            suggestion: `Update README commands to use ${context.detectedPackageManager}.`
+          })
+        );
+      }
+    }
+
+    const scripts = asPackageJson(context.packageJson)?.scripts ?? {};
+    const hasRunScript = Boolean(scripts.dev || scripts.start);
+    if (hasRunScript && !readmeMentionsRunCommand(commands)) {
+      issues.push(
+        createIssue({
+          id: "readme-commands.no-run-command",
+          title: "README does not show how to run the app",
+          message: "package.json has a dev or start script, but README does not include a matching run command.",
+          severity: "warning",
+          file: "README.md",
+          suggestion: "Add a README quickstart step for running the app locally."
+        })
+      );
+    }
+
+    return createResult({
+      id: this.id,
+      title: this.title,
+      issues
+    });
+  }
+};

package/packages/core/src/checks/scriptsAvailability.ts

@@ -0,0 +1,69 @@
+import type { ClonecheckCheck } from "../types.js";
+import { asPackageJson, createIssue, createResult } from "./helpers.js";
+
+export const scriptsAvailabilityCheck: ClonecheckCheck = {
+  id: "scripts-availability",
+  title: "Scripts availability",
+  description: "Checks whether Node projects expose obvious scripts for running, testing, and building.",
+  async run(context) {
+    if (!context.detectedProjectTypes.includes("node")) {
+      return createResult({
+        id: this.id,
+        title: this.title,
+        status: "skip"
+      });
+    }
+
+    const packageJson = asPackageJson(context.packageJson);
+    const scripts = packageJson?.scripts ?? {};
+    const hasDev = Boolean(scripts.dev);
+    const hasStart = Boolean(scripts.start);
+    const hasTest = Boolean(scripts.test);
+    const hasBuild = Boolean(scripts.build);
+    const hasAnyRunScript = hasDev || hasStart || hasTest || hasBuild;
+    const issues = [];
+
+    if (!hasAnyRunScript) {
+      issues.push(
+        createIssue({
+          id: "scripts-availability.no-run-scripts",
+          title: "No runnable package scripts",
+          message: "package.json does not define dev, start, test, or build scripts.",
+          severity: "error",
+          file: "package.json",
+          suggestion: "Add at least one obvious script such as dev, start, test, or build."
+        })
+      );
+    } else if (!hasDev && !hasStart && !hasBuild) {
+      issues.push(
+        createIssue({
+          id: "scripts-availability.no-app-run-script",
+          title: "No app run script",
+          message: "package.json has scripts, but no dev, start, or build script tells contributors how to run the app.",
+          severity: "warning",
+          file: "package.json",
+          suggestion: "Add a dev or start script for the main local workflow."
+        })
+      );
+    }
+
+    if (!hasTest) {
+      issues.push(
+        createIssue({
+          id: "scripts-availability.no-test-script",
+          title: "No test script",
+          message: "package.json does not define a test script.",
+          severity: "warning",
+          file: "package.json",
+          suggestion: "Add a test script, even if it only runs a small smoke test at first."
+        })
+      );
+    }
+
+    return createResult({
+      id: this.id,
+      title: this.title,
+      issues
+    });
+  }
+};

package/packages/core/src/config.ts

@@ -0,0 +1,96 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { DEFAULT_CONFIG, type ClonecheckConfig } from "./types.js";
+
+export const CONFIG_FILENAMES = [
+  "clonecheck.config.json",
+  ".clonecheckrc",
+  ".clonecheckrc.json"
+] as const;
+
+const configSchema = z
+  .object({
+    ignore: z.array(z.string()).default([]),
+    ignoreEnvVars: z.array(z.string()).default([]),
+    checks: z.record(z.boolean()).default({})
+  })
+  .strict();
+
+export class ClonecheckConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ClonecheckConfigError";
+  }
+}
+
+export interface LoadedConfig {
+  config: ClonecheckConfig;
+  configPath?: string;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function findConfigPath(repoPath: string, configPath?: string): Promise<string | undefined> {
+  if (configPath) {
+    const resolved = path.isAbsolute(configPath) ? configPath : path.join(repoPath, configPath);
+    if (!(await fileExists(resolved))) {
+      throw new ClonecheckConfigError(`Config file was not found: ${resolved}`);
+    }
+    return resolved;
+  }
+
+  for (const filename of CONFIG_FILENAMES) {
+    const candidate = path.join(repoPath, filename);
+    if (await fileExists(candidate)) {
+      return candidate;
+    }
+  }
+
+  return undefined;
+}
+
+export async function loadConfig(repoPath: string, configPath?: string): Promise<LoadedConfig> {
+  const foundPath = await findConfigPath(repoPath, configPath);
+  if (!foundPath) {
+    return { config: { ...DEFAULT_CONFIG } };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(foundPath, "utf8"));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new ClonecheckConfigError(`Could not parse clonecheck config at ${foundPath}: ${detail}`);
+  }
+
+  const result = configSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => {
+      const key = issue.path.length > 0 ? issue.path.join(".") : "config";
+      return `${key}: ${issue.message}`;
+    });
+    throw new ClonecheckConfigError(
+      `Invalid clonecheck config at ${foundPath}:\n${issues.map((issue) => `- ${issue}`).join("\n")}`
+    );
+  }
+
+  return { config: result.data, configPath: foundPath };
+}
+
+export async function initConfig(repoPath: string, force = false): Promise<{ path: string; created: boolean }> {
+  const target = path.join(repoPath, "clonecheck.config.json");
+  if (!force && (await fileExists(target))) {
+    return { path: target, created: false };
+  }
+
+  await writeFile(`${target}`, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf8");
+  return { path: target, created: true };
+}

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

@@ -0,0 +1,62 @@
+import yaml from "js-yaml";
+import { readTextFile } from "../utils/files.js";
+
+export const COMPOSE_FILES = [
+  "docker-compose.yml",
+  "docker-compose.yaml",
+  "compose.yml",
+  "compose.yaml"
+];
+
+export interface DockerComposeEnvReference {
+  name: string;
+  file: string;
+}
+
+export interface DockerComposeScanResult {
+  refs: DockerComposeEnvReference[];
+  parseErrors: Array<{ file: string; message: string }>;
+}
+
+export function extractDockerComposeEnvVars(text: string, file: string): DockerComposeEnvReference[] {
+  const refs: DockerComposeEnvReference[] = [];
+  const regex = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(text)) !== null) {
+    const name = match[1];
+    if (name) {
+      refs.push({ name, file });
+    }
+  }
+
+  return refs;
+}
+
+export async function detectDockerComposeEnvVars(
+  repoPath: string,
+  files: string[]
+): Promise<DockerComposeScanResult> {
+  const refs: DockerComposeEnvReference[] = [];
+  const parseErrors: Array<{ file: string; message: string }> = [];
+
+  for (const file of files.filter((candidate) => COMPOSE_FILES.includes(candidate))) {
+    const text = await readTextFile(repoPath, file);
+    if (!text) {
+      continue;
+    }
+
+    try {
+      yaml.load(text);
+    } catch (error) {
+      parseErrors.push({
+        file,
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+
+    refs.push(...extractDockerComposeEnvVars(text, file));
+  }
+
+  return { refs, parseErrors };
+}

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

@@ -0,0 +1,189 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { ClonecheckConfig } from "../types.js";
+import { absolutePath, isLikelyTextFile, lineNumberFromIndex, readTextFile } from "../utils/files.js";
+
+export const ENV_EXAMPLE_FILES = [".env.example", ".env.sample", ".env.template", "example.env"];
+
+export const DEFAULT_IGNORE_ENV_VARS = new Set(["NODE_ENV", "PATH", "HOME", "PWD", "CI", "PORT"]);
+
+const ENV_SOURCE_EXTENSIONS = new Set([
+  ".cjs",
+  ".go",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".py",
+  ".rs",
+  ".ts",
+  ".tsx"
+]);
+
+export interface EnvVarUsage {
+  name: string;
+  file: string;
+  line: number;
+}
+
+const ENV_PATTERNS = [
+  /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+  /process\.env\[['"`]([A-Za-z_][A-Za-z0-9_]*)['"`]\]/g,
+  /import\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+  /os\.environ\[['"`]([A-Za-z_][A-Za-z0-9_]*)['"`]\]/g,
+  /os\.getenv\(['"`]([A-Za-z_][A-Za-z0-9_]*)['"`]\)/g,
+  /os\.Getenv\(['"`]([A-Za-z_][A-Za-z0-9_]*)['"`]\)/g,
+  /std::env::var\(['"`]([A-Za-z_][A-Za-z0-9_]*)['"`]\)/g
+];
+
+function isEnvSourceFile(file: string): boolean {
+  if (!isLikelyTextFile(file)) {
+    return false;
+  }
+
+  return ENV_SOURCE_EXTENSIONS.has(path.extname(file));
+}
+
+export function parseEnvExampleVars(text: string | undefined): Set<string> {
+  const vars = new Set<string>();
+  if (!text) {
+    return vars;
+  }
+
+  const regex = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/gm;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(text)) !== null) {
+    const name = match[1];
+    if (name) {
+      vars.add(name);
+    }
+  }
+
+  return vars;
+}
+
+export function extractEnvVarUsages(text: string, file: string): EnvVarUsage[] {
+  const usages: EnvVarUsage[] = [];
+
+  for (const pattern of ENV_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(text)) !== null) {
+      const name = match[1];
+      if (!name) {
+        continue;
+      }
+
+      usages.push({
+        name,
+        file,
+        line: lineNumberFromIndex(text, match.index)
+      });
+    }
+  }
+
+  return usages;
+}
+
+export async function detectEnvVarUsages(
+  repoPath: string,
+  files: string[],
+  config: ClonecheckConfig
+): Promise<EnvVarUsage[]> {
+  const ignored = new Set([...DEFAULT_IGNORE_ENV_VARS, ...config.ignoreEnvVars]);
+  const usages: EnvVarUsage[] = [];
+
+  for (const file of files) {
+    if (!isEnvSourceFile(file)) {
+      continue;
+    }
+
+    const text = await readTextFile(repoPath, file);
+    if (!text) {
+      continue;
+    }
+
+    for (const usage of extractEnvVarUsages(text, file)) {
+      if (!ignored.has(usage.name)) {
+        usages.push(usage);
+      }
+    }
+  }
+
+  return usages;
+}
+
+export async function loadEnvExampleFiles(
+  repoPath: string,
+  files: string[]
+): Promise<{ text?: string; vars: Set<string>; files: string[] }> {
+  const foundFiles = ENV_EXAMPLE_FILES.filter((file) => files.includes(file));
+  const vars = new Set<string>();
+  let firstText: string | undefined;
+
+  for (const file of foundFiles) {
+    const text = await readTextFile(repoPath, file);
+    if (text === undefined) {
+      continue;
+    }
+    firstText ??= text;
+    for (const name of parseEnvExampleVars(text)) {
+      vars.add(name);
+    }
+  }
+
+  return { text: firstText, vars, files: foundFiles };
+}
+
+export function findMissingEnvVars(usages: EnvVarUsage[], documentedVars: Set<string>): string[] {
+  const used = new Set(usages.map((usage) => usage.name));
+  return Array.from(used)
+    .filter((name) => !documentedVars.has(name))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+export interface GenerateEnvExampleOptions {
+  repoPath: string;
+  files: string[];
+  config: ClonecheckConfig;
+  write?: boolean;
+}
+
+export interface GenerateEnvExampleResult {
+  content: string;
+  missingVars: string[];
+  writtenPath?: string;
+}
+
+function appendEnvLines(existing: string, missingVars: string[]): string {
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? `${existing}\n` : existing;
+  const needsSpacer = prefix.trim().length > 0 && missingVars.length > 0 ? "\n" : "";
+  return `${prefix}${needsSpacer}${missingVars.map((name) => `${name}=`).join("\n")}${missingVars.length > 0 ? "\n" : ""}`;
+}
+
+export async function generateEnvExample(
+  options: GenerateEnvExampleOptions
+): Promise<GenerateEnvExampleResult> {
+  const envExamples = await loadEnvExampleFiles(options.repoPath, options.files);
+  const usages = await detectEnvVarUsages(options.repoPath, options.files, options.config);
+  const missingVars = findMissingEnvVars(usages, envExamples.vars);
+  const target = absolutePath(options.repoPath, ".env.example");
+
+  let existing = "";
+  try {
+    existing = await readFile(target, "utf8");
+  } catch {
+    existing = "";
+  }
+
+  const content = appendEnvLines(existing, missingVars);
+
+  if (options.write) {
+    await writeFile(target, content, "utf8");
+  }
+
+  return {
+    content,
+    missingVars,
+    writtenPath: options.write ? target : undefined
+  };
+}

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

@@ -0,0 +1,54 @@
+import type { PackageJson, PackageManager } from "../types.js";
+
+const LOCKFILE_MANAGERS: Array<{ file: string; manager: PackageManager }> = [
+  { file: "pnpm-lock.yaml", manager: "pnpm" },
+  { file: "yarn.lock", manager: "yarn" },
+  { file: "package-lock.json", manager: "npm" },
+  { file: "bun.lockb", manager: "bun" },
+  { file: "bun.lock", manager: "bun" }
+];
+
+export interface PackageManagerDetection {
+  manager?: PackageManager;
+  lockfiles: string[];
+  managers: PackageManager[];
+}
+
+export function detectPackageManager(
+  files: string[],
+  packageJson?: PackageJson
+): PackageManagerDetection {
+  const matches = LOCKFILE_MANAGERS.filter(({ file }) => files.includes(file));
+  const lockManagers = Array.from(new Set(matches.map((match) => match.manager)));
+
+  if (lockManagers.length > 0) {
+    return {
+      manager: lockManagers[0],
+      lockfiles: matches.map((match) => match.file),
+      managers: lockManagers
+    };
+  }
+
+  const packageManager = packageJson?.packageManager?.split("@")[0];
+  if (
+    packageManager === "pnpm" ||
+    packageManager === "npm" ||
+    packageManager === "yarn" ||
+    packageManager === "bun"
+  ) {
+    return {
+      manager: packageManager,
+      lockfiles: [],
+      managers: [packageManager]
+    };
+  }
+
+  return {
+    lockfiles: [],
+    managers: []
+  };
+}
+
+export function isPackageManager(value: string): value is PackageManager {
+  return value === "pnpm" || value === "npm" || value === "yarn" || value === "bun";
+}