clonecheck-monorepo 0.1.0

package/packages/cli/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 clonecheck contributors
+
+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/packages/cli/README.md

@@ -0,0 +1,15 @@
+# @clonecheck/cli
+
+CLI package for clonecheck.
+
+```bash
+npx @clonecheck/cli scan
+```
+
+Most users should install or run the unscoped `clonecheck` package:
+
+```bash
+npx clonecheck scan
+```
+
+Full documentation: https://github.com/reallav0/clonecheck

package/packages/cli/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@clonecheck/cli",
+  "version": "0.1.0",
+  "description": "CLI for clonecheck.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reallav0/clonecheck.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/reallav0/clonecheck/issues"
+  },
+  "homepage": "https://github.com/reallav0/clonecheck#readme",
+  "keywords": [
+    "clonecheck",
+    "cli",
+    "developer-experience",
+    "repository",
+    "readme"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "clonecheck": "./dist/index.js"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs .",
+    "dev": "tsx src/index.ts",
+    "lint": "eslint \"src/**/*.ts\"",
+    "scan": "tsx src/index.ts scan",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "@clonecheck/core": "workspace:*",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/packages/cli/src/index.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+import {
+  CLONECHECK_VERSION,
+  ClonecheckConfigError,
+  createClonecheckContext,
+  formatJsonReport,
+  formatMarkdownReport,
+  formatTextReport,
+  generateEnvExample,
+  initConfig,
+  runClonecheck
+} from "@clonecheck/core";
+
+type OutputFormat = "text" | "json" | "markdown";
+
+interface ScanOptions {
+  format: OutputFormat;
+  output?: string;
+  strict?: boolean;
+  config?: string;
+  color?: boolean;
+}
+
+interface GenerateEnvOptions {
+  write?: boolean;
+  config?: string;
+}
+
+interface InitOptions {
+  force?: boolean;
+}
+
+function shouldShowDebug(): boolean {
+  const value = process.env.DEBUG;
+  if (!value) {
+    return false;
+  }
+
+  return value === "*" || value.split(",").map((entry) => entry.trim()).includes("clonecheck");
+}
+
+function handleError(error: unknown): void {
+  if (shouldShowDebug()) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (error instanceof ClonecheckConfigError) {
+    console.error(pc.red(error.message));
+  } else if (error instanceof Error) {
+    console.error(pc.red(error.message));
+  } else {
+    console.error(pc.red(String(error)));
+  }
+
+  process.exitCode = 1;
+}
+
+function normalizeFormat(format: string): OutputFormat {
+  if (format === "text" || format === "json" || format === "markdown") {
+    return format;
+  }
+
+  throw new Error(`Unsupported format "${format}". Use text, json, or markdown.`);
+}
+
+function resolveUserPath(inputPath: string): string {
+  if (path.isAbsolute(inputPath)) {
+    return inputPath;
+  }
+
+  return path.resolve(process.env.INIT_CWD ?? process.cwd(), inputPath);
+}
+
+async function writeOutput(outputPath: string, content: string): Promise<void> {
+  const resolved = resolveUserPath(outputPath);
+  await mkdir(path.dirname(resolved), { recursive: true });
+  await writeFile(resolved, content, "utf8");
+}
+
+async function runScan(repoPath: string, options: ScanOptions): Promise<void> {
+  const format = normalizeFormat(options.format);
+  const report = await runClonecheck({
+    repoPath: resolveUserPath(repoPath),
+    configPath: options.config,
+    strict: Boolean(options.strict)
+  });
+
+  const output =
+    format === "json"
+      ? formatJsonReport(report)
+      : format === "markdown"
+        ? formatMarkdownReport(report)
+        : formatTextReport(report, { color: options.color });
+
+  if (options.output) {
+    await writeOutput(options.output, output);
+  } else {
+    process.stdout.write(output);
+  }
+
+  if (options.strict && report.score < 75) {
+    process.exitCode = 1;
+  }
+}
+
+async function runGenerateEnvExample(repoPath: string, options: GenerateEnvOptions): Promise<void> {
+  const { context } = await createClonecheckContext({
+    repoPath: resolveUserPath(repoPath),
+    configPath: options.config
+  });
+  const result = await generateEnvExample({
+    repoPath: context.repoPath,
+    files: context.files,
+    config: context.config,
+    write: Boolean(options.write)
+  });
+
+  if (options.write) {
+    const writtenPath = result.writtenPath ?? path.join(context.repoPath, ".env.example");
+    console.log(
+      `Updated ${writtenPath} with ${result.missingVars.length} missing environment variable${result.missingVars.length === 1 ? "" : "s"}.`
+    );
+    return;
+  }
+
+  process.stdout.write(result.content);
+}
+
+async function runInit(repoPath: string, options: InitOptions): Promise<void> {
+  const result = await initConfig(resolveUserPath(repoPath), Boolean(options.force));
+  if (!result.created) {
+    console.error(`Config already exists at ${result.path}. Use --force to overwrite it.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`Created ${result.path}`);
+}
+
+const program = new Command();
+
+program
+  .name("clonecheck")
+  .description("Know if your repo is actually cloneable.")
+  .version(CLONECHECK_VERSION)
+  .showHelpAfterError();
+
+program
+  .command("scan")
+  .description("Scan a repository for cloneability and contributor-readiness issues.")
+  .argument("[repoPath]", "repository path", ".")
+  .option("--format <format>", "output format: text, json, or markdown", "text")
+  .option("--output <file>", "write the report to a file")
+  .option("--strict", "exit with code 1 when score is below 75")
+  .option("--config <file>", "path to a clonecheck config file")
+  .option("--no-color", "disable terminal colors")
+  .action((repoPath: string, options: ScanOptions) => {
+    return runScan(repoPath, options).catch(handleError);
+  });
+
+program
+  .command("generate-env-example")
+  .description("Print or update a suggested .env.example based on environment variables used in code.")
+  .argument("[repoPath]", "repository path", ".")
+  .option("--write", "create or append missing variables to .env.example")
+  .option("--config <file>", "path to a clonecheck config file")
+  .action((repoPath: string, options: GenerateEnvOptions) => {
+    return runGenerateEnvExample(repoPath, options).catch(handleError);
+  });
+
+program
+  .command("init")
+  .description("Create a clonecheck.config.json file.")
+  .argument("[repoPath]", "repository path", ".")
+  .option("--force", "overwrite an existing config file")
+  .action((repoPath: string, options: InitOptions) => {
+    return runInit(repoPath, options).catch(handleError);
+  });
+
+program.parseAsync(process.argv).catch(handleError);

package/packages/cli/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@clonecheck/core": ["../core/src/index.ts"]
+    },
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}

package/packages/core/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 clonecheck contributors
+
+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/packages/core/README.md

@@ -0,0 +1,11 @@
+# @clonecheck/core
+
+Core TypeScript API for clonecheck.
+
+```ts
+import { runClonecheck } from "@clonecheck/core";
+
+const report = await runClonecheck({ repoPath: process.cwd() });
+```
+
+Full documentation: https://github.com/reallav0/clonecheck

package/packages/core/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@clonecheck/core",
+  "version": "0.1.0",
+  "description": "Core repository usability scanner for clonecheck.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reallav0/clonecheck.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/reallav0/clonecheck/issues"
+  },
+  "homepage": "https://github.com/reallav0/clonecheck#readme",
+  "keywords": [
+    "clonecheck",
+    "developer-experience",
+    "repository",
+    "readme",
+    "static-analysis"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs .",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "js-yaml": "^4.1.0",
+    "picocolors": "^1.1.1",
+    "zod": "^3.24.1"
+  }
+}

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

@@ -0,0 +1,35 @@
+import type { ClonecheckCheck } from "../types.js";
+import { createIssue, createResult } from "./helpers.js";
+
+export const ciPresenceCheck: ClonecheckCheck = {
+  id: "ci-presence",
+  title: "CI presence",
+  description: "Checks whether the repository has at least one GitHub Actions workflow.",
+  async run(context) {
+    const workflows = context.files.filter(
+      (file) =>
+        file.startsWith(".github/workflows/") && (file.endsWith(".yml") || file.endsWith(".yaml"))
+    );
+
+    if (workflows.length > 0) {
+      return createResult({
+        id: this.id,
+        title: this.title
+      });
+    }
+
+    return createResult({
+      id: this.id,
+      title: this.title,
+      issues: [
+        createIssue({
+          id: "ci-presence.missing",
+          title: "CI workflow is missing",
+          message: "Repository does not include a GitHub Actions workflow in .github/workflows.",
+          severity: "warning",
+          suggestion: "Add a CI workflow that installs dependencies, runs tests, and builds the project."
+        })
+      ]
+    });
+  }
+};

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

@@ -0,0 +1,61 @@
+import type { ClonecheckCheck } from "../types.js";
+import { DEFAULT_IGNORE_ENV_VARS } from "../detectors/env.js";
+import { COMPOSE_FILES, detectDockerComposeEnvVars } from "../detectors/dockerCompose.js";
+import { createIssue, createResult } from "./helpers.js";
+
+export const dockerComposeEnvCheck: ClonecheckCheck = {
+  id: "docker-compose-env",
+  title: "Docker Compose environment",
+  description: "Checks whether Docker Compose variable references are documented in env examples.",
+  async run(context) {
+    const hasCompose = context.files.some((file) => COMPOSE_FILES.includes(file));
+    if (!hasCompose) {
+      return createResult({
+        id: this.id,
+        title: this.title,
+        status: "skip"
+      });
+    }
+
+    const ignored = new Set([...DEFAULT_IGNORE_ENV_VARS, ...context.config.ignoreEnvVars]);
+    const scan = await detectDockerComposeEnvVars(context.repoPath, context.files);
+    const issues = scan.parseErrors.map((error) =>
+      createIssue({
+        id: `docker-compose-env.parse.${error.file}`,
+        title: "Docker Compose file could not be parsed",
+        message: `${error.file} could not be parsed as YAML: ${error.message}`,
+        severity: "warning",
+        file: error.file,
+        suggestion: "Fix the Docker Compose YAML syntax."
+      })
+    );
+
+    const uniqueMissing = Array.from(
+      new Set(
+        scan.refs
+          .map((ref) => ref.name)
+          .filter((name) => !ignored.has(name) && !context.envExampleVars.has(name))
+      )
+    ).sort((a, b) => a.localeCompare(b));
+
+    for (const name of uniqueMissing) {
+      const ref = scan.refs.find((entry) => entry.name === name);
+      issues.push(
+        createIssue({
+          id: `docker-compose-env.${name}`,
+          title: "Docker Compose variable is undocumented",
+          message: `Docker Compose references ${name}, but it is not documented in an env example file.`,
+          severity: "warning",
+          file: ref?.file,
+          suggestion: `Add ${name}= to .env.example.`
+        })
+      );
+    }
+
+    return createResult({
+      id: this.id,
+      title: this.title,
+      issues
+    });
+  }
+};

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

@@ -0,0 +1,31 @@
+import type { ClonecheckCheck } from "../types.js";
+import { detectEnvVarUsages, findMissingEnvVars } from "../detectors/env.js";
+import { createIssue, createResult } from "./helpers.js";
+
+export const envExampleCheck: ClonecheckCheck = {
+  id: "env-example",
+  title: "Environment example",
+  description: "Checks whether environment variables used in code are documented in an example env file.",
+  async run(context) {
+    const usages = await detectEnvVarUsages(context.repoPath, context.files, context.config);
+    const missing = findMissingEnvVars(usages, context.envExampleVars);
+    const issues = missing.map((name) => {
+      const firstUsage = usages.find((usage) => usage.name === name);
+      return createIssue({
+        id: `env-example.${name}`,
+        title: "Environment variable is undocumented",
+        message: `Environment variable ${name} is used but missing from .env.example or another env template.`,
+        severity: "warning",
+        file: firstUsage?.file,
+        line: firstUsage?.line,
+        suggestion: `Add ${name}= to .env.example.`
+      });
+    });
+
+    return createResult({
+      id: this.id,
+      title: this.title,
+      issues
+    });
+  }
+};

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

@@ -0,0 +1,54 @@
+import type {
+  CheckStatus,
+  ClonecheckCheckResult,
+  ClonecheckIssue,
+  PackageJson,
+  Severity
+} from "../types.js";
+
+export function statusFromIssues(issues: ClonecheckIssue[]): CheckStatus {
+  if (issues.some((issue) => issue.severity === "error")) {
+    return "fail";
+  }
+  if (issues.some((issue) => issue.severity === "warning")) {
+    return "warning";
+  }
+
+  return "pass";
+}
+
+export function createIssue(input: {
+  id: string;
+  title: string;
+  message: string;
+  severity: Severity;
+  file?: string;
+  line?: number;
+  suggestion?: string;
+}): ClonecheckIssue {
+  return input;
+}
+
+export function createResult(input: {
+  id: string;
+  title: string;
+  issues?: ClonecheckIssue[];
+  status?: CheckStatus;
+}): ClonecheckCheckResult {
+  const issues = input.issues ?? [];
+  return {
+    id: input.id,
+    title: input.title,
+    status: input.status ?? statusFromIssues(issues),
+    issues,
+    scoreImpact: 0
+  };
+}
+
+export function asPackageJson(value: unknown): PackageJson | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+
+  return value as PackageJson;
+}

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

@@ -0,0 +1,24 @@
+import type { ClonecheckCheck } from "../types.js";
+import { ciPresenceCheck } from "./ciPresence.js";
+import { dockerComposeEnvCheck } from "./dockerComposeEnv.js";
+import { envExampleCheck } from "./envExample.js";
+import { packageManagerConsistencyCheck } from "./packageManagerConsistency.js";
+import { portDocumentationCheck } from "./portDocumentation.js";
+import { projectFilesCheck } from "./projectFiles.js";
+import { readmeCommandsCheck } from "./readmeCommands.js";
+import { scriptsAvailabilityCheck } from "./scriptsAvailability.js";
+
+export const checks: ClonecheckCheck[] = [
+  packageManagerConsistencyCheck,
+  scriptsAvailabilityCheck,
+  envExampleCheck,
+  readmeCommandsCheck,
+  portDocumentationCheck,
+  dockerComposeEnvCheck,
+  projectFilesCheck,
+  ciPresenceCheck
+];
+
+export function getChecks(): ClonecheckCheck[] {
+  return checks;
+}

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

@@ -0,0 +1,65 @@
+import type { ClonecheckCheck } from "../types.js";
+import { detectPackageManager } from "../detectors/packageManager.js";
+import { extractReadmeCommands, isPackageInstallCommand } from "../detectors/readme.js";
+import { createIssue, createResult, asPackageJson } from "./helpers.js";
+
+export const packageManagerConsistencyCheck: ClonecheckCheck = {
+  id: "package-manager-consistency",
+  title: "Package manager consistency",
+  description: "Checks whether README package-manager commands match the detected lockfile.",
+  async run(context) {
+    const detection = detectPackageManager(context.files, asPackageJson(context.packageJson));
+    const issues = [];
+
+    if (!detection.manager) {
+      return createResult({
+        id: this.id,
+        title: this.title,
+        status: "skip"
+      });
+    }
+
+    if (detection.managers.length > 1) {
+      issues.push(
+        createIssue({
+          id: "package-manager-consistency.multiple-lockfiles",
+          title: "Multiple package managers detected",
+          message: `Multiple package-manager lockfiles were found: ${detection.lockfiles.join(", ")}.`,
+          severity: "warning",
+          suggestion: "Keep only the lockfile for the package manager contributors should use."
+        })
+      );
+    }
+
+    const commands = context.readmeText ? extractReadmeCommands(context.readmeText) : [];
+    const mismatches = commands.filter(
+      (command) =>
+        command.packageManager &&
+        command.packageManager !== detection.manager &&
+        !(command.kind === "install" && isPackageInstallCommand(command.command))
+    );
+
+    const seen = new Set<string>();
+    for (const mismatch of mismatches) {
+      if (!mismatch.packageManager || seen.has(mismatch.packageManager)) {
+        continue;
+      }
+      seen.add(mismatch.packageManager);
+      issues.push(
+        createIssue({
+          id: `package-manager-consistency.${mismatch.packageManager}`,
+          title: "README uses a different package manager",
+          message: `README uses ${mismatch.packageManager} commands, but the repository appears to use ${detection.manager}.`,
+          severity: "warning",
+          suggestion: `Replace ${mismatch.packageManager} commands in README with ${detection.manager} equivalents.`
+        })
+      );
+    }
+
+    return createResult({
+      id: this.id,
+      title: this.title,
+      issues
+    });
+  }
+};