Metadata-Version: 2.4
Name: pc-init
Version: 0.4.0
Summary: Generate .pre-commit-config.yaml from language and framework presets
Author-email: Christian Ledermann <christian.ledermann@gmail.com>
License-Expression: GPL-3.0-only
Project-URL: Bug Tracker, https://github.com/cleder/gpc-init/issues
Project-URL: Changelog, https://github.com/cleder/gpc-init/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/cleder/gpc-init
Project-URL: Repository, https://github.com/cleder/gpc-init
Keywords: cli,code-quality,linting,pre-commit,presets
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.26.7
Dynamic: license-file

# pc-init

[![Tests](https://github.com/cleder/gpc-init/actions/workflows/test-build-publish.yml/badge.svg?branch=main)](https://github.com/cleder/gpc-init/actions/workflows/test-build-publish.yml) [![codecov](https://codecov.io/gh/cleder/gpc-init/graph/badge.svg?token=3enkN1Q8JM)](https://codecov.io/gh/cleder/gpc-init) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![pyrefly](https://img.shields.io/badge/type_checker-pyrefly-blue)](https://github.com/facebook/pyrefly) [![ty](https://img.shields.io/badge/type_checker-ty-blue)](https://github.com/astral-sh/ty) [![GPLv3 License](https://img.shields.io/pypi/l/pc-init)](https://opensource.org/license/gpl-3-0/) [![Python Version](https://img.shields.io/pypi/pyversions/pc-init)](https://www.python.org/) [![PyPI - Version](https://img.shields.io/pypi/v/pc-init)](https://pypi.org/project/pc-init/) [![Status](https://img.shields.io/pypi/status/pc-init)](https://pypi.org/project/pc-init/)

Generate a [pre-commit](https://pre-commit.com/) or [prek](https://github.com/j178/prek/) `.pre-commit-config.yaml` for your project from curated language and framework presets — so you get the right linters, formatters, and quality tools wired up with a single command instead of copying configs between repos.
Works with [prek](https://github.com/j178/prek/) and [pre-commit](https://pre-commit.com/)

## Motivation

Every new repository needs a `.pre-commit-config.yaml`.
Each language and framework has its own recommended linters, formatters, and quality tools, each with its own hook URL and revision.
`pc-init` encodes those choices in version-controlled presets so you run one command instead of copying configs and looking up hook URLs.
The bundled presets pin specific hook revisions — run `pre-commit autoupdate` or `prek autoupdate` after generation to pull in the latest versions.

## Awesome Pre-commit Hooks

The curated hooks bundled with `pc-init` are also published as a standalone reference at [awesome-pre-commit-hooks](https://github.com/cleder/awesome-pre-commit-hooks) — a browsable list of every hook organised by language and framework.

## Installation

```bash
uv tool install pc-init
```

## Quickstart

In an existing repository, let `pc-init` detect what's there and generate a config in one command:

```bash
cd my-project
pc-init --detect
```

Or specify languages and frameworks explicitly:

```bash
pc-init --lang py --framework django
```

Then install the hooks:

```bash
pre-commit install
# or
prek install
```

## Usage

```text
Usage: pc-init [OPTIONS] COMMAND [ARGS]...

  Generate a .pre-commit-config.yaml for your project.

Options:
  --lang       TEXT  Language preset to include (repeatable, or
                     comma-delimited: --lang=py,js). Run `pc-init list` to
                     see supported values from the active catalog.
  --framework  TEXT  Framework preset to layer on top of language baselines
                     (repeatable, or comma-delimited: --framework=react,django).
                     Run `pc-init list` to see supported values from the
                     active catalog.
  --force            Overwrite existing .pre-commit-config.yaml without
                     prompting.
  --detect           Auto-detect languages and frameworks from the current
                     directory and merge them with any explicitly supplied
                     --lang/--framework values.
  --output     TEXT  Output file path.  [default: .pre-commit-config.yaml]
  --presets    TEXT  Preset catalog to use. Accepts a local directory path or
                     a git repository URL (https://, git@, git://, ssh://).
                     The directory / repo root must contain lang/ and
                     framework/ subdirectories. Defaults to the bundled
                     presets.
  --version          Show version and exit.
  --help             Show this message and exit.

Commands:
  list  List available language and framework presets in the active catalog.
```

### List available presets

Run `pc-init list` to discover all supported languages and frameworks in the active catalog (bundled or custom):

```bash
pc-init list
```

```text
Languages:
  docker, go, img, js, md, nb, py, ru, sh, sql, tf, toml, ts, yaml

Frameworks:
  django, git, k8s, react, sphinx
```

Use `--presets` to list what a custom catalog provides:

```bash
pc-init list --presets /path/to/my-presets
pc-init list --presets https://github.com/org/my-presets
```

## Supported presets

**Languages** — pass as `--lang`:

| ID | Language |
|----|----------|
| `py` | Python |
| `js` | JavaScript |
| `go` | Go |
| `ru` | Rust |
| `sh` | Shell / Bash |
| `ts` | TypeScript |
| `nb` | Jupyter Notebooks |
| `md` | Markdown |
| `img` | Images |
| `docker` | Docker |
| `sql` | SQL |
| `tf` | Terraform |
| `toml` | TOML |
| `yaml` | YAML |

Language aliases `python`, `javascript`, `typescript`, `rust`, `golang`, `shell`, `bash`, `image`, `notebook`, `jupyter`, `dockerfile`, and `terraform` are also accepted.

**Frameworks** — pass as `--framework`:

| ID | Framework |
|----|-----------|
| `react` | React |
| `django` | Django |
| `sphinx` | Sphinx documentation |
| `git` | Commit message linting |
| `k8s` | Kubernetes |

## Auto-detecting languages and frameworks

`--detect` scans the current directory, infers languages from file extensions and frameworks from indicator files, and uses the results exactly as if you had passed them with `--lang` and `--framework`.

```bash
pc-init --detect
```

```text
Detected languages: md, py, yaml, sh, js
Detected frameworks: git
Generated .pre-commit-config.yaml with languages: md, py, yaml, sh, js and frameworks: git
```

Detected values are merged with any explicitly supplied flags — duplicates are dropped:

```bash
pc-init --detect --lang sql   # adds sql on top of whatever is detected
```

If the file already exists and differs, the suggested overwrite command uses explicit `--lang` and `--framework` values so the re-run is fully deterministic:

```text
Run with --force to overwrite '.pre-commit-config.yaml'.
  Try: pc-init --lang=md,py,yaml,sh,js --framework=git --force
```

**Language detection** is based on file extensions (common vendored directories such as `.git`, `node_modules`, `.venv`, `__pycache__`, and `dist` are skipped):

| Extension(s) | Language |
|---|---|
| `.py`, `.pyi` | `py` |
| `.js`, `.mjs`, `.cjs`, `.jsx` | `js` |
| `.ts`, `.tsx` | `ts` |
| `.go` | `go` |
| `.rs` | `ru` |
| `.sh`, `.bash` | `sh` |
| `.sql` | `sql` |
| `.tf`, `.tfvars` | `tf` |
| `.md`, `.markdown` | `md` |
| `.ipynb` | `nb` |
| `.yaml`, `.yml` | `yaml` |
| `.r` | `r` |
| `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg` | `img` |
| `Dockerfile` (filename) | `docker` |

**Framework detection** is based on indicator files:

| Indicator | Framework |
|---|---|
| `manage.py` at the repo root | `django` |
| `package.json` with `react` in `dependencies` or `devDependencies` | `react` |
| `conf.py` (root or `docs/`) containing `sphinx` | `sphinx` |
| Any `.yaml`/`.yml` file outside `.github/` containing `apiVersion:` and `kind:` | `k8s` |
| `.github/workflows/` directory with at least one `.yml` file | `git` |

## Language suggestions for frameworks

Some framework presets declare the languages they are typically used with.
If none of your `--lang` selections match, `pc-init` prints an informational note and a ready-to-run command that adds the missing languages:

```text
Note: preset 'react' recommends adding: --lang=js,ts
      Try: pc-init --lang=go,js,ts --framework=react
```

The suggested command preserves your existing `--lang` values so it is safe to run with `--force` — no hooks you already selected will be removed.

Pass `--recommended` to apply all suggestions automatically in a single run:

```bash
pc-init --lang go --framework react --recommended
```

You can also omit `--lang` entirely when using `--recommended` with at least one framework — the recommended languages are used as the starting set:

```bash
pc-init --framework django --recommended
```

## Examples

Auto-detect everything:

```bash
pc-init --detect
```

Auto-detect and add an extra language:

```bash
pc-init --detect --lang sql
```

Python project:

```bash
pc-init --lang py
```

JavaScript project with React:

```bash
pc-init --lang js --framework react
```

Python + Django, overwriting an existing config:

```bash
pc-init --lang py --framework django --force
```

Multiple languages (two equivalent forms):

```bash
pc-init --lang py --lang js
pc-init --lang=py,js
```

Django project, letting `pc-init` pick the language automatically:

```bash
pc-init --framework django --recommended
```

## Custom presets

Point `--presets` at a local directory or a git repository that contains `lang/` and `framework/` subdirectories in the same layout as the bundled presets.

Local directory:

```bash
pc-init --lang py --presets /path/to/my-presets
```

Git repository:

```bash
pc-init --lang py --presets https://github.com/org/my-presets
```

## Check the config files

To check the config files with `pre-commit` and `prek` for a specific language or framework:

```bash
pre-commit validate-config lang/py/preset.yaml
prek validate-config lang/py/preset.yaml
```

## Update bundled presets

Update a config file with the command:

```bash
pre-commit autoupdate lang/py/preset.yaml
prek autoupdate lang/py/preset.yaml
```

## Check and update all presets

To pull the latest hook revisions into all bundled preset files:

```bash
find . -name "preset*.yaml" | xargs -I{} prek validate-config {}
find . -name "preset*.yaml" | xargs -I{} prek autoupdate -c {}
find . -name "preset*.yaml" | xargs -I{} pre-commit validate-config {}
find . -name "preset*.yaml" | xargs -I{} pre-commit autoupdate -c {}
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, preset guidelines, and the pull request checklist.
