@reallavo/clonecheck 0.1.0

package/packages/core/src/scoring.ts

@@ -0,0 +1,60 @@
+import type { ClonecheckCheckResult, ClonecheckIssue, ClonecheckReport, Severity } from "./types.js";
+
+const DEFAULT_PENALTIES: Record<Severity, number> = {
+  error: 15,
+  warning: 7,
+  info: 2
+};
+
+const STRICT_PENALTIES: Record<Severity, number> = {
+  error: 15,
+  warning: 10,
+  info: 3
+};
+
+export function scoreImpactForIssues(issues: ClonecheckIssue[], strict = false): number {
+  const penalties = strict ? STRICT_PENALTIES : DEFAULT_PENALTIES;
+  return issues.reduce((total, issue) => total + penalties[issue.severity], 0);
+}
+
+export function scoreChecks(
+  checks: ClonecheckCheckResult[],
+  strict = false
+): { score: number; checks: ClonecheckCheckResult[] } {
+  const scoredChecks = checks.map((check) => ({
+    ...check,
+    scoreImpact: check.status === "skip" ? 0 : scoreImpactForIssues(check.issues, strict)
+  }));
+  const totalImpact = scoredChecks.reduce((total, check) => total + check.scoreImpact, 0);
+  return {
+    score: Math.max(0, 100 - totalImpact),
+    checks: scoredChecks
+  };
+}
+
+export function statusFromScore(score: number): ClonecheckReport["status"] {
+  if (score >= 90) {
+    return "excellent";
+  }
+  if (score >= 75) {
+    return "good";
+  }
+  if (score >= 50) {
+    return "needs-work";
+  }
+
+  return "poor";
+}
+
+export function collectSuggestions(checks: ClonecheckCheckResult[]): string[] {
+  const suggestions = new Set<string>();
+  for (const check of checks) {
+    for (const issue of check.issues) {
+      if (issue.suggestion) {
+        suggestions.add(issue.suggestion);
+      }
+    }
+  }
+
+  return Array.from(suggestions);
+}

package/packages/core/src/types.ts

@@ -0,0 +1,85 @@
+export const CLONECHECK_VERSION = "0.1.0";
+
+export type Severity = "info" | "warning" | "error";
+export type CheckStatus = "pass" | "warning" | "fail" | "skip";
+export type ProjectType = "node" | "python" | "go" | "rust" | "docker";
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+
+export interface ClonecheckIssue {
+  id: string;
+  title: string;
+  message: string;
+  severity: Severity;
+  file?: string;
+  line?: number;
+  suggestion?: string;
+}
+
+export interface ClonecheckCheckResult {
+  id: string;
+  title: string;
+  status: CheckStatus;
+  issues: ClonecheckIssue[];
+  scoreImpact: number;
+}
+
+export interface ClonecheckReport {
+  repoPath: string;
+  projectName: string;
+  score: number;
+  status: "excellent" | "good" | "needs-work" | "poor";
+  checks: ClonecheckCheckResult[];
+  suggestions: string[];
+  metadata: {
+    detectedProjectTypes: string[];
+    detectedPackageManager?: string;
+    generatedAt: string;
+    clonecheckVersion: string;
+  };
+}
+
+export interface RunClonecheckOptions {
+  repoPath: string;
+  configPath?: string;
+  strict?: boolean;
+}
+
+export interface ClonecheckConfig {
+  ignore: string[];
+  ignoreEnvVars: string[];
+  checks: Record<string, boolean>;
+}
+
+export interface PackageJson {
+  name?: string;
+  packageManager?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+export interface ClonecheckContext {
+  repoPath: string;
+  files: string[];
+  config: ClonecheckConfig;
+  packageJson?: unknown;
+  readmeText?: string;
+  envExampleText?: string;
+  envExampleVars: Set<string>;
+  detectedProjectTypes: ProjectType[];
+  detectedPackageManager?: PackageManager;
+  strict: boolean;
+}
+
+export interface ClonecheckCheck {
+  id: string;
+  title: string;
+  description: string;
+  run(context: ClonecheckContext): Promise<ClonecheckCheckResult>;
+}
+
+export const DEFAULT_CONFIG: ClonecheckConfig = {
+  ignore: [],
+  ignoreEnvVars: [],
+  checks: {}
+};

package/packages/core/src/utils/files.ts

@@ -0,0 +1,109 @@
+import { access, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+
+export const DEFAULT_FILE_IGNORE = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/coverage/**"
+];
+
+const TEXT_EXTENSIONS = new Set([
+  ".cjs",
+  ".go",
+  ".js",
+  ".json",
+  ".jsx",
+  ".mjs",
+  ".md",
+  ".py",
+  ".rs",
+  ".sh",
+  ".toml",
+  ".ts",
+  ".tsx",
+  ".txt",
+  ".yaml",
+  ".yml"
+]);
+
+export function normalizeRelativePath(filePath: string): string {
+  return filePath.split(path.sep).join("/");
+}
+
+export function absolutePath(repoPath: string, relativePath: string): string {
+  return path.join(repoPath, relativePath);
+}
+
+export async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function discoverFiles(repoPath: string, ignore: string[] = []): Promise<string[]> {
+  const files = await fg(["**/*"], {
+    cwd: repoPath,
+    dot: true,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    unique: true,
+    ignore: [...DEFAULT_FILE_IGNORE, ...ignore]
+  });
+
+  return files.map(normalizeRelativePath).sort((a, b) => a.localeCompare(b));
+}
+
+export async function readTextFile(repoPath: string, relativePath: string): Promise<string | undefined> {
+  const target = absolutePath(repoPath, relativePath);
+  try {
+    const info = await stat(target);
+    if (info.size > 1_000_000) {
+      return undefined;
+    }
+
+    return await readFile(target, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+export function isLikelyTextFile(relativePath: string): boolean {
+  const baseName = path.basename(relativePath);
+  if (
+    baseName === ".env.example" ||
+    baseName === ".env.sample" ||
+    baseName === ".env.template" ||
+    baseName === "example.env"
+  ) {
+    return true;
+  }
+
+  return TEXT_EXTENSIONS.has(path.extname(relativePath));
+}
+
+export function findCaseInsensitive(files: string[], expected: string): string | undefined {
+  const expectedLower = expected.toLowerCase();
+  return files.find((file) => file.toLowerCase() === expectedLower);
+}
+
+export function findAnyCaseInsensitive(files: string[], expected: string[]): string | undefined {
+  for (const filename of expected) {
+    const match = findCaseInsensitive(files, filename);
+    if (match) {
+      return match;
+    }
+  }
+
+  return undefined;
+}
+
+export function lineNumberFromIndex(text: string, index: number): number {
+  return text.slice(0, index).split(/\r?\n/).length;
+}

package/packages/core/tests/config.test.ts

@@ -0,0 +1,53 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { ClonecheckConfigError, initConfig, loadConfig } from "../src/index.js";
+
+describe("config loading", () => {
+  it("loads default config when no file exists", async () => {
+    const repoPath = await mkdtemp(path.join(os.tmpdir(), "clonecheck-config-"));
+    const { config } = await loadConfig(repoPath);
+
+    expect(config).toEqual({
+      ignore: [],
+      ignoreEnvVars: [],
+      checks: {}
+    });
+  });
+
+  it("validates clonecheck config files", async () => {
+    const repoPath = await mkdtemp(path.join(os.tmpdir(), "clonecheck-config-"));
+    await writeFile(
+      path.join(repoPath, "clonecheck.config.json"),
+      JSON.stringify({
+        ignore: ["examples/**"],
+        ignoreEnvVars: ["CUSTOM_IGNORE"],
+        checks: { "ci-presence": false }
+      }),
+      "utf8"
+    );
+
+    const { config } = await loadConfig(repoPath);
+
+    expect(config.ignore).toEqual(["examples/**"]);
+    expect(config.ignoreEnvVars).toEqual(["CUSTOM_IGNORE"]);
+    expect(config.checks["ci-presence"]).toBe(false);
+  });
+
+  it("throws a friendly error for invalid config", async () => {
+    const repoPath = await mkdtemp(path.join(os.tmpdir(), "clonecheck-config-"));
+    await writeFile(path.join(repoPath, "clonecheck.config.json"), JSON.stringify({ ignore: "nope" }), "utf8");
+
+    await expect(loadConfig(repoPath)).rejects.toBeInstanceOf(ClonecheckConfigError);
+  });
+
+  it("creates a default config without overwriting existing files", async () => {
+    const repoPath = await mkdtemp(path.join(os.tmpdir(), "clonecheck-config-"));
+    const first = await initConfig(repoPath);
+    const second = await initConfig(repoPath);
+
+    expect(first.created).toBe(true);
+    expect(second.created).toBe(false);
+  });
+});

package/packages/core/tests/detectors.test.ts

@@ -0,0 +1,127 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  detectPackageManager,
+  extractDockerComposeEnvVars,
+  extractEnvVarUsages,
+  extractReadmeCommands,
+  findMissingEnvVars,
+  isPackageInstallCommand,
+  parseEnvExampleVars
+} from "../src/index.js";
+import { discoverFiles, readTextFile } from "../src/utils/files.js";
+
+const fixturesPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures");
+
+describe("package manager detection", () => {
+  it("detects pnpm from lockfiles", () => {
+    const detection = detectPackageManager(["package.json", "pnpm-lock.yaml"]);
+
+    expect(detection.manager).toBe("pnpm");
+    expect(detection.lockfiles).toEqual(["pnpm-lock.yaml"]);
+  });
+});
+
+describe("README command extraction", () => {
+  it("extracts package manager and docker commands from shell blocks", () => {
+    const commands = extractReadmeCommands(`
+# App
+
+\`\`\`bash
+pnpm install
+pnpm dev
+pnpm --filter @clonecheck/cli dev -- scan .
+docker compose up
+\`\`\`
+`);
+
+    expect(commands.map((command) => command.command)).toEqual([
+      "pnpm install",
+      "pnpm dev",
+      "pnpm --filter @clonecheck/cli dev -- scan .",
+      "docker compose up"
+    ]);
+    expect(commands.map((command) => command.kind)).toEqual(["install", "run", "run", "docker"]);
+  });
+
+  it("distinguishes repo installs from package installation examples", () => {
+    expect(isPackageInstallCommand("npm install")).toBe(false);
+    expect(isPackageInstallCommand("pnpm install --frozen-lockfile")).toBe(false);
+    expect(isPackageInstallCommand("npm install --save-dev clonecheck")).toBe(true);
+    expect(isPackageInstallCommand("pnpm add -D clonecheck")).toBe(false);
+  });
+});
+
+describe("environment variable detection", () => {
+  it("detects supported JS, Python, Go, and Rust env patterns", () => {
+    const usages = extractEnvVarUsages(
+      `
+process.env.DATABASE_URL
+process.env["JWT_SECRET"]
+process.env['STRIPE_SECRET_KEY']
+import.meta.env.VITE_API_URL
+os.environ["PYTHON_SECRET"]
+os.getenv("PYTHON_OPTIONAL")
+os.Getenv("GO_SECRET")
+std::env::var("RUST_SECRET")
+`,
+      "src/config.ts"
+    );
+
+    expect(usages.map((usage) => usage.name)).toEqual([
+      "DATABASE_URL",
+      "JWT_SECRET",
+      "STRIPE_SECRET_KEY",
+      "VITE_API_URL",
+      "PYTHON_SECRET",
+      "PYTHON_OPTIONAL",
+      "GO_SECRET",
+      "RUST_SECRET"
+    ]);
+  });
+
+  it("compares detected env vars with documented examples", () => {
+    const documented = parseEnvExampleVars(`
+DATABASE_URL=
+# Comment
+export VITE_API_URL=
+`);
+    const missing = findMissingEnvVars(
+      [
+        { name: "DATABASE_URL", file: "src/app.ts", line: 1 },
+        { name: "JWT_SECRET", file: "src/app.ts", line: 2 },
+        { name: "VITE_API_URL", file: "src/app.ts", line: 3 }
+      ],
+      documented
+    );
+
+    expect(missing).toEqual(["JWT_SECRET"]);
+  });
+});
+
+describe("Docker Compose env detection", () => {
+  it("extracts variable references with and without defaults", () => {
+    const refs = extractDockerComposeEnvVars(
+      `
+services:
+  db:
+    environment:
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:-postgres}
+      DATABASE_URL: \${DATABASE_URL}
+`,
+      "docker-compose.yml"
+    );
+
+    expect(refs.map((ref) => ref.name)).toEqual(["POSTGRES_PASSWORD", "DATABASE_URL"]);
+  });
+
+  it("discovers compose fixtures from disk", async () => {
+    const repoPath = path.join(fixturesPath, "docker-compose-missing-env");
+    const files = await discoverFiles(repoPath);
+    const compose = await readTextFile(repoPath, "docker-compose.yml");
+
+    expect(files).toContain("docker-compose.yml");
+    expect(compose).toContain("POSTGRES_PASSWORD");
+  });
+});

package/packages/core/tests/fixtures/docker-compose-missing-env/.env.example

@@ -0,0 +1 @@
+DATABASE_URL=

package/packages/core/tests/fixtures/docker-compose-missing-env/README.md

@@ -0,0 +1,5 @@
+# Compose Fixture
+
+```bash
+docker compose up
+```

package/packages/core/tests/fixtures/docker-compose-missing-env/docker-compose.yml

@@ -0,0 +1,6 @@
+services:
+  api:
+    image: node:20
+    environment:
+      DATABASE_URL: ${DATABASE_URL}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}

package/packages/core/tests/fixtures/env-missing/.env.example

@@ -0,0 +1 @@
+DATABASE_URL=

package/packages/core/tests/fixtures/env-missing/README.md

@@ -0,0 +1,6 @@
+# Env Missing
+
+```bash
+npm install
+npm run dev
+```

package/packages/core/tests/fixtures/env-missing/package-lock.json

@@ -0,0 +1,4 @@
+{
+  "name": "env-missing",
+  "lockfileVersion": 3
+}

package/packages/core/tests/fixtures/env-missing/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "env-missing",
+  "private": true,
+  "scripts": {
+    "dev": "node src/app.js",
+    "test": "node --test"
+  }
+}

package/packages/core/tests/fixtures/env-missing/src.py

@@ -0,0 +1,4 @@
+import os
+
+database_url = os.environ["DATABASE_URL"]
+jwt_secret = os.getenv("JWT_SECRET")

package/packages/core/tests/fixtures/node-pnpm-readme-npm/.env.example

@@ -0,0 +1 @@
+DATABASE_URL=

package/packages/core/tests/fixtures/node-pnpm-readme-npm/README.md

@@ -0,0 +1,8 @@
+# Fixture
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:3000.

package/packages/core/tests/fixtures/node-pnpm-readme-npm/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "node-pnpm-readme-npm",
+  "private": true,
+  "scripts": {
+    "dev": "vite --port 5173",
+    "test": "vitest run"
+  }
+}

package/packages/core/tests/fixtures/node-pnpm-readme-npm/pnpm-lock.yaml

@@ -0,0 +1 @@
+lockfileVersion: '9.0'

package/packages/core/tests/fixtures/node-pnpm-readme-npm/src.ts

@@ -0,0 +1,3 @@
+const url = process.env.DATABASE_URL;
+const secret = process.env.JWT_SECRET;
+const port = 5173;

package/packages/core/tests/reporters.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { formatMarkdownReport, type ClonecheckReport } from "../src/index.js";
+
+describe("markdown reporter", () => {
+  it("renders a GitHub-friendly report", () => {
+    const report: ClonecheckReport = {
+      repoPath: "/tmp/app",
+      projectName: "app",
+      score: 72,
+      status: "needs-work",
+      checks: [
+        {
+          id: "env-example",
+          title: "Environment example",
+          status: "warning",
+          issues: [
+            {
+              id: "env-example.JWT_SECRET",
+              title: "Environment variable is undocumented",
+              message: "Environment variable JWT_SECRET is used but missing from .env.example.",
+              severity: "warning",
+              suggestion: "Add JWT_SECRET= to .env.example."
+            }
+          ],
+          scoreImpact: 7
+        }
+      ],
+      suggestions: ["Add JWT_SECRET= to .env.example."],
+      metadata: {
+        detectedProjectTypes: ["node"],
+        detectedPackageManager: "pnpm",
+        generatedAt: "2026-07-08T00:00:00.000Z",
+        clonecheckVersion: "0.1.0"
+      }
+    };
+
+    const markdown = formatMarkdownReport(report);
+
+    expect(markdown).toContain("# Clonecheck Report");
+    expect(markdown).toContain("| env-example |");
+    expect(markdown).toContain("## Suggestions");
+  });
+});

package/packages/core/tests/run.test.ts

@@ -0,0 +1,37 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { formatJsonReport, runClonecheck } from "../src/index.js";
+
+const fixturesPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures");
+
+describe("runClonecheck", () => {
+  it("reports package-manager and port mismatches", async () => {
+    const report = await runClonecheck({
+      repoPath: path.join(fixturesPath, "node-pnpm-readme-npm")
+    });
+
+    expect(report.metadata.detectedPackageManager).toBe("pnpm");
+    expect(report.checks.find((check) => check.id === "readme-commands")?.status).toBe("warning");
+    expect(report.checks.find((check) => check.id === "port-documentation")?.status).toBe("warning");
+  });
+
+  it("reports missing env example variables", async () => {
+    const report = await runClonecheck({
+      repoPath: path.join(fixturesPath, "env-missing")
+    });
+
+    const envCheck = report.checks.find((check) => check.id === "env-example");
+    expect(envCheck?.issues.map((issue) => issue.id)).toContain("env-example.JWT_SECRET");
+  });
+
+  it("emits valid JSON", async () => {
+    const report = await runClonecheck({
+      repoPath: path.join(fixturesPath, "env-missing")
+    });
+
+    expect(JSON.parse(formatJsonReport(report))).toMatchObject({
+      projectName: "env-missing"
+    });
+  });
+});

package/packages/core/tests/scoring.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { scoreImpactForIssues, statusFromScore } from "../src/index.js";
+
+describe("scoring", () => {
+  it("scores normal mode severities", () => {
+    expect(
+      scoreImpactForIssues([
+        { id: "a", title: "A", message: "A", severity: "error" },
+        { id: "b", title: "B", message: "B", severity: "warning" },
+        { id: "c", title: "C", message: "C", severity: "info" }
+      ])
+    ).toBe(24);
+  });
+
+  it("scores strict mode severities", () => {
+    expect(
+      scoreImpactForIssues(
+        [
+          { id: "a", title: "A", message: "A", severity: "warning" },
+          { id: "b", title: "B", message: "B", severity: "info" }
+        ],
+        true
+      )
+    ).toBe(13);
+  });
+
+  it("maps scores to statuses", () => {
+    expect(statusFromScore(95)).toBe("excellent");
+    expect(statusFromScore(80)).toBe("good");
+    expect(statusFromScore(60)).toBe("needs-work");
+    expect(statusFromScore(40)).toBe("poor");
+  });
+});

package/packages/core/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

package/packages/npm/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/npm/README.md

@@ -0,0 +1,17 @@
+# clonecheck
+
+Know if your repo is actually cloneable.
+
+Run without installing:
+
+```bash
+npx clonecheck scan
+```
+
+Install locally:
+
+```bash
+npm install --save-dev clonecheck
+```
+
+Full documentation: https://github.com/reallav0/clonecheck