@reallavo/clonecheck 0.1.0

package/.env.example

@@ -0,0 +1,2 @@
+DEBUG=
+NO_COLOR=

package/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.23.0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install
+      - run: pnpm lint
+      - run: pnpm test
+      - run: pnpm build

package/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Thanks for helping improve clonecheck.
+
+## Local Setup
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm lint
+```
+
+Run the CLI against an example fixture:
+
+```bash
+pnpm --filter @clonecheck/cli dev -- scan ./examples/node-missing-env
+```
+
+## Pull Requests
+
+Keep changes focused, add or update tests for scanner behavior, and document new checks in `docs/checks.md`.

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

@@ -0,0 +1,205 @@
+# clonecheck
+
+Know if your repo is actually cloneable.
+
+Most tools tell you whether your code is secure or formatted.
+clonecheck tells you whether your repo is actually usable by a new contributor.
+
+clonecheck is a CLI and GitHub Action that checks whether a repository is cloneable, runnable, and contributor-friendly. It answers one concrete question:
+
+> Can a new developer clone this repo and understand how to run it within 10 minutes?
+
+It does not run installs, execute Docker, or call external APIs. The MVP is static analysis for repository usability.
+
+## Example Output
+
+```txt
+clonecheck v0.1.0
+
+Repository: my-app
+Path: /Users/me/my-app
+
+Score: 72/100
+Status: Needs work
+
+Checks:
+  ✅ package-manager-consistency
+     package manager is consistent: pnpm
+
+  ✅ scripts-availability
+     package scripts include an obvious local workflow
+
+  ⚠️ env-example
+     Environment variable DATABASE_URL is used but missing from .env.example or another env template.
+     Environment variable JWT_SECRET is used but missing from .env.example or another env template.
+
+  ⚠️ readme-commands
+     README uses npm commands, but the detected package manager is pnpm.
+
+Suggestions:
+  1. Add DATABASE_URL= to .env.example.
+  2. Add JWT_SECRET= to .env.example.
+  3. Update README commands to use pnpm.
+```
+
+## Installation
+
+```bash
+npm install --save-dev clonecheck
+```
+
+Run without installing:
+
+```bash
+npx clonecheck scan
+```
+
+Scoped package users can also run:
+
+```bash
+npx @clonecheck/cli scan
+```
+
+pnpm users:
+
+```bash
+pnpm add -D clonecheck
+pnpm dlx clonecheck scan
+```
+
+From this repository:
+
+```bash
+pnpm install
+pnpm build
+pnpm --filter clonecheck scan
+```
+
+## CLI Usage
+
+```bash
+clonecheck scan
+clonecheck scan .
+clonecheck scan ./some-repo
+clonecheck scan --format text
+clonecheck scan --format json
+clonecheck scan --format markdown
+clonecheck scan --output clonecheck-report.md
+clonecheck scan --strict
+clonecheck generate-env-example
+clonecheck generate-env-example --write
+clonecheck init
+clonecheck --version
+clonecheck --help
+```
+
+During local development:
+
+```bash
+pnpm --filter @clonecheck/cli dev -- scan ./examples/node-missing-env
+```
+
+## GitHub Action
+
+```yaml
+name: Clonecheck
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  clonecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: reallav0/clonecheck@v1
+        with:
+          format: markdown
+          output: clonecheck-report.md
+          strict: false
+```
+
+## Checks
+
+| Check | What it finds |
+|---|---|
+| `package-manager-consistency` | README commands that do not match the detected lockfile. |
+| `scripts-availability` | Missing `dev`, `start`, `test`, or `build` scripts in Node projects. |
+| `env-example` | Environment variables used in code but missing from env example files. |
+| `readme-commands` | Missing setup commands or README commands that conflict with the package manager. |
+| `port-documentation` | README localhost ports that do not match likely app ports. |
+| `docker-compose-env` | Compose `${VARIABLE}` references missing from env examples. |
+| `project-files` | Missing README, `.gitignore`, contributing guide, or license. |
+| `ci-presence` | Missing GitHub Actions workflow. |
+
+See [docs/checks.md](docs/checks.md) for details.
+
+## Configuration
+
+Create a config file:
+
+```bash
+clonecheck init
+```
+
+Example:
+
+```json
+{
+  "ignore": ["examples/**", "fixtures/**"],
+  "ignoreEnvVars": ["NODE_ENV", "CUSTOM_IGNORE"],
+  "checks": {
+    "ci-presence": false,
+    "license": false
+  }
+}
+```
+
+Supported filenames:
+
+- `clonecheck.config.json`
+- `.clonecheckrc`
+- `.clonecheckrc.json`
+
+See [docs/config.md](docs/config.md).
+
+## Environment Examples
+
+Generate a suggested env example:
+
+```bash
+clonecheck generate-env-example
+```
+
+Write missing variables to `.env.example`:
+
+```bash
+clonecheck generate-env-example --write
+```
+
+Existing variables and comments are preserved.
+
+## Roadmap
+
+- More language-specific detectors for Rails, Laravel, Django, and Phoenix.
+- Package-manager-aware README command suggestions.
+- Optional PR comments for the GitHub Action.
+- Repository templates for common project types.
+- Future opt-in command execution mode for smoke tests.
+
+## Contributing
+
+Issues and pull requests are welcome. Before opening a PR, run:
+
+```bash
+pnpm install
+pnpm lint
+pnpm test
+pnpm build
+```
+
+## License
+
+MIT

package/action/README.md

@@ -0,0 +1,34 @@
+# Clonecheck GitHub Action
+
+Run clonecheck in CI to catch repository usability problems before contributors hit them.
+
+```yaml
+name: Clonecheck
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  clonecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: reallav0/clonecheck@v1
+        with:
+          format: markdown
+          output: clonecheck-report.md
+          strict: false
+```
+
+## Inputs
+
+| Input | Default | Description |
+|---|---:|---|
+| `path` | `.` | Repository path to scan. |
+| `format` | `markdown` | Report format: `text`, `json`, or `markdown`. |
+| `output` | empty | Optional file path for the generated report. |
+| `strict` | `false` | Exit with code `1` when the score is below `75`. |
+
+The MVP action installs dependencies and builds the local CLI before running it with Node.

package/action/action.yml

@@ -0,0 +1,50 @@
+name: Clonecheck
+description: Know if your repo is actually cloneable.
+author: clonecheck contributors
+
+inputs:
+  path:
+    description: Repository path to scan.
+    required: false
+    default: "."
+  format:
+    description: Report format. One of text, json, or markdown.
+    required: false
+    default: markdown
+  output:
+    description: Optional output file path.
+    required: false
+    default: ""
+  strict:
+    description: Exit with code 1 when the clonecheck score is below 75.
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - name: Enable pnpm
+      shell: bash
+      run: corepack enable
+
+    - name: Install clonecheck dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile
+      working-directory: ${{ github.action_path }}/..
+
+    - name: Build clonecheck
+      shell: bash
+      run: pnpm build
+      working-directory: ${{ github.action_path }}/..
+
+    - name: Run clonecheck
+      shell: bash
+      run: |
+        args=(scan "${{ inputs.path }}" --format "${{ inputs.format }}")
+        if [ -n "${{ inputs.output }}" ]; then
+          args+=(--output "${{ inputs.output }}")
+        fi
+        if [ "${{ inputs.strict }}" = "true" ]; then
+          args+=(--strict)
+        fi
+        node "${{ github.action_path }}/../packages/cli/dist/index.js" "${args[@]}"

package/clonecheck.config.json

@@ -0,0 +1,5 @@
+{
+  "ignore": ["examples/**", "packages/**/tests/**"],
+  "ignoreEnvVars": ["INIT_CWD"],
+  "checks": {}
+}

package/docs/checks.md

@@ -0,0 +1,44 @@
+# Checks
+
+clonecheck ships with practical static checks focused on whether a new contributor can clone, configure, and run a repository quickly.
+
+## package-manager-consistency
+
+Detects the package manager from lockfiles and compares it with package-manager commands in README shell blocks.
+
+- `pnpm-lock.yaml` means `pnpm`
+- `yarn.lock` means `yarn`
+- `package-lock.json` means `npm`
+- `bun.lockb` or `bun.lock` means `bun`
+
+## scripts-availability
+
+For Node projects, checks `package.json` for `dev`, `start`, `test`, and `build` scripts.
+
+- Missing all run scripts is an error.
+- Missing `test` is a warning.
+- Having `dev` or `start` is enough for a basic local run path.
+
+## env-example
+
+Scans JavaScript, TypeScript, Python, Go, and Rust files for environment variable usage and compares detected variables against `.env.example`, `.env.sample`, `.env.template`, and `example.env`.
+
+## readme-commands
+
+Extracts shell code blocks from README files and checks for setup and run commands. It warns when README commands conflict with the detected package manager.
+
+## port-documentation
+
+Detects likely app ports from source files and common config files, then compares them with README localhost URLs.
+
+## docker-compose-env
+
+Scans Compose files for `${VARIABLE}` references and verifies that each variable is documented in an env example file.
+
+## project-files
+
+Checks for `README.md`, `CONTRIBUTING.md`, `LICENSE`, and `.gitignore`.
+
+## ci-presence
+
+Checks for at least one `.github/workflows/*.yml` or `.github/workflows/*.yaml` file.

package/docs/config.md

@@ -0,0 +1,36 @@
+# Configuration
+
+clonecheck looks for config files in this order:
+
+1. `clonecheck.config.json`
+2. `.clonecheckrc`
+3. `.clonecheckrc.json`
+
+You can also pass a specific file:
+
+```bash
+clonecheck scan --config ./clonecheck.config.json
+```
+
+## Example
+
+```json
+{
+  "ignore": ["examples/**", "fixtures/**"],
+  "ignoreEnvVars": ["NODE_ENV", "CUSTOM_IGNORE"],
+  "checks": {
+    "ci-presence": false,
+    "license": false
+  }
+}
+```
+
+## Fields
+
+| Field | Description |
+|---|---|
+| `ignore` | Additional glob patterns to exclude from file discovery. |
+| `ignoreEnvVars` | Environment variable names that should not require documentation. |
+| `checks` | Map of check IDs to booleans. `false` disables a check. |
+
+`license` and `contributing` can be disabled as sub-checks of `project-files`.

package/docs/scoring.md

@@ -0,0 +1,20 @@
+# Scoring
+
+clonecheck starts every repository at `100` and subtracts points for issues.
+
+| Severity | Default | Strict |
+|---|---:|---:|
+| `error` | 15 | 15 |
+| `warning` | 7 | 10 |
+| `info` | 2 | 3 |
+
+Scores never go below `0`.
+
+| Score | Status |
+|---:|---|
+| 90-100 | Excellent |
+| 75-89 | Good |
+| 50-74 | Needs work |
+| 0-49 | Poor |
+
+`--strict` does not make the scanner run commands. It only makes warnings and info issues cost more and exits with code `1` when the score is below `75`.

package/eslint.config.js

@@ -0,0 +1,29 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: ["**/dist/**", "**/coverage/**", "**/tests/fixtures/**", "node_modules/**"]
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ["**/*.ts"],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname
+      }
+    },
+    rules: {
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          "argsIgnorePattern": "^_",
+          "varsIgnorePattern": "^_"
+        }
+      ]
+    }
+  }
+);

package/examples/docker-compose-missing-env/.env.example

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

package/examples/docker-compose-missing-env/README.md

@@ -0,0 +1,5 @@
+# Docker Compose Missing Env
+
+```bash
+docker compose up
+```

package/examples/docker-compose-missing-env/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: app
+  web:
+    image: node:20
+    environment:
+      DATABASE_URL: ${DATABASE_URL:-postgres://postgres:postgres@db:5432/app}
+    ports:
+      - "3000:3000"

package/examples/node-basic/.env.example

@@ -0,0 +1 @@
+VITE_API_URL=

package/examples/node-basic/README.md

@@ -0,0 +1,8 @@
+# Node Basic
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open http://localhost:5173.

package/examples/node-basic/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "node-basic",
+  "private": true,
+  "scripts": {
+    "dev": "vite --host 0.0.0.0 --port 5173",
+    "build": "vite build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "vite": "^6.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.8"
+  }
+}

package/examples/node-basic/pnpm-lock.yaml

@@ -0,0 +1,5 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false

package/examples/node-basic/src-index.ts

@@ -0,0 +1 @@
+console.log(import.meta.env.VITE_API_URL);

package/examples/node-missing-env/.env.example

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

package/examples/node-missing-env/README.md

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

package/examples/node-missing-env/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "node-missing-env",
+  "private": true,
+  "scripts": {
+    "dev": "vite --port 5173",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "vite": "^6.0.0"
+  }
+}

package/examples/node-missing-env/pnpm-lock.yaml

@@ -0,0 +1,5 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false

package/examples/node-missing-env/src/app.ts

@@ -0,0 +1,14 @@
+const databaseUrl = process.env.DATABASE_URL;
+const jwtSecret = process.env["JWT_SECRET"];
+const stripeSecretKey = process.env['STRIPE_SECRET_KEY'];
+const apiUrl = import.meta.env.NEXT_PUBLIC_API_URL;
+
+export function config() {
+  return {
+    databaseUrl,
+    jwtSecret,
+    stripeSecretKey,
+    apiUrl,
+    port: 5173
+  };
+}

package/examples/python-basic/.env.example

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

package/examples/python-basic/README.md

@@ -0,0 +1,8 @@
+# Python Basic
+
+```bash
+python -m venv .venv
+python app.py
+```
+
+Open http://localhost:8000.

package/examples/python-basic/app.py

@@ -0,0 +1,6 @@
+import os
+
+DATABASE_URL = os.getenv("DATABASE_URL")
+PORT = 8000
+
+print(f"Running with {DATABASE_URL} on port {PORT}")

package/examples/python-basic/requirements.txt

@@ -0,0 +1 @@
+flask==3.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@reallavo/clonecheck",
+  "version": "0.1.0",
+  "description": "Know if your repo is actually cloneable.",
+  "type": "module",
+  "packageManager": "pnpm@10.23.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "pnpm -r build",
+    "dev": "pnpm --filter @clonecheck/cli dev",
+    "lint": "pnpm -r lint",
+    "scan": "pnpm --filter clonecheck scan",
+    "test": "pnpm -r test",
+    "typecheck": "pnpm -r typecheck",
+    "format": "prettier --check .",
+    "format:write": "prettier --write ."
+  },
+  "keywords": [
+    "cli",
+    "developer-experience",
+    "repository",
+    "readme",
+    "github-action"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.7",
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.2",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0",
+    "vitest": "^2.1.8"
+  }
+}