diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..c834909 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,35 @@ +--- +name: Bug report +about: Report a reproducible bug in Context Drift +title: "[Bug]: " +labels: bug +--- + +## Summary + +Describe the bug in one or two sentences. + +## Steps to Reproduce + +1. +2. +3. + +## Expected Behavior + +What did you expect to happen? + +## Actual Behavior + +What happened instead? + +## Environment + +- OS: +- Node version: +- Command: +- Relevant branch or commit: + +## Additional Context + +Add logs, screenshots, or other details that help reproduce the issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..f6ee934 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,26 @@ +--- +name: Feature request +about: Suggest a focused improvement for Context Drift +title: "[Feature]: " +labels: enhancement +--- + +## Summary + +Describe the feature or improvement you want. + +## Problem Statement + +What issue does this solve? + +## Proposed Behavior + +What should the tool do? + +## Scope + +Keep the request focused on one problem. If there are follow-up ideas, list them separately. + +## Additional Context + +Add examples, mockups, or references if useful. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..d4da274 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ +## Summary + +Briefly describe the issue this PR solves. + +## Related Issue + +Link the issue this PR closes or references. + +## What Changed + +- + +## Validation + +- + +## Notes + +- Keep this PR focused on one issue. +- If other work surfaced during implementation, open a follow-up PR instead of bundling it here. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..016c59d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,35 @@ +name: CI + +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - name: Install dependencies + run: npm ci + + - name: Build + run: npm run build + + - name: Test + run: npm test + + - name: Typecheck + run: npm run typecheck diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d67c342 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +## [Unreleased] + +### Added + +- MIT `LICENSE` file for the project. +- `SECURITY.md` with a private vulnerability reporting path. +- `docs/architecture.md` and `docs/checks.md` for repository context. +- GitHub issue and pull request templates under `.github/`. +- A GitHub Actions CI workflow for build, test, and typecheck verification. +- Contributor guidance for keeping pull requests focused and low-noise. +- A pull request template in `CONTRIBUTING.md`. +- README contribution steps for local validation and PR preparation. + +## [0.1.0] - 2026-06-03 + +### Added + +- Initial CLI foundation for scanning supported source files. +- Git-based changed-file detection through `check --base`. +- Naming-style summary reporting for repository files. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..082f0dd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing + +Thanks for helping improve Context Drift. + +Keep changes focused, reviewable, and easy to verify. + +## Principles + +- Open one issue per pull request. +- Avoid noisy PRs that mix unrelated fixes, refactors, or formatting changes. +- Keep the scope small enough that a reviewer can understand the change quickly. +- Include validation steps in every PR. +- Use the repository PR template at [`.github/PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md). + +## Before You Open a PR + +1. Create a branch for the specific issue you are solving. +2. Make the smallest change that fully addresses that issue. +3. Run the relevant checks: + - `npm run build` + - `npm test` + - `npm run typecheck` +4. Confirm the diff contains only the files that belong in the PR. +5. Open the PR with a clear title and a short explanation of the change. + +## Pull Request Template + +Use this template when opening a PR: + +```md +## Summary +Briefly describe the issue and the fix. + +## Related Issue +Link the issue this PR closes or references. + +## What Changed +- List the user-visible or behavior changes. +- Keep this focused on the single issue the PR solves. + +## Validation +- List the commands or tests you ran. +- Mention any manual checks if they matter. + +## Notes +- Call out anything a reviewer should know. +- Mention follow-up work separately instead of bundling it here. +``` + +## Good PR Shape + +- One problem. +- One solution. +- One review path. + +If a change starts to expand, split it into a follow-up PR instead of letting the current one become noisy. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..10c36b6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Context Drift 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. diff --git a/README.md b/README.md index dc4ba04..b912d6a 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,61 @@ -# Context Drift +

+
+ Context Drift +

-Stop AI-generated code from making your repo weird. +

A small CLI for spotting when new code starts to drift from your repository's naming conventions.

-Context Drift is an open-source CLI and GitHub Action that detects when new code does not match your existing codebase conventions. +

+ Node 20+ + TypeScript + CLI utility +

-## Usage +

+ Context Drift scans supported source files, summarizes their naming styles, and highlights the files that changed relative to git or an explicit file list. +

+ + + + + +
+ +**What it checks** + +- `**/*.ts` +- `**/*.tsx` +- `**/*.js` +- `**/*.jsx` + +**What it ignores** + +- `node_modules` +- `.git` +- `.next` +- `dist` +- `build` +- `coverage` + +
+ +## Quick Start + +```bash +npm install +npm run build +npx context-drift check --base main +``` + +If you already know which files changed, you can pass them directly: ```bash -npx context-drift check +npx context-drift check --changed src/cli.ts,src/scanner.ts ``` -Example output: +## Output + +The default report is intentionally simple: ```txt Context Drift @@ -18,28 +63,79 @@ Context Drift Files scanned: 142 Changed files: 3 Format: markdown + +Naming conventions: +- PascalCase: 12% +- kebab-case: 18% +- camelCase: 41% +- snake_case: 9% +- lower-case: 20% +- upper-case: 0% ``` -## Local Development +## CLI + +The project exposes one command: ```bash -npm install -npm run build -npm run check +context-drift check ``` -The first milestone scans JavaScript and TypeScript source files: +Options: -- `**/*.ts` -- `**/*.tsx` -- `**/*.js` -- `**/*.jsx` +- `--base `: diff against `base...HEAD` and treat those files as changed. +- `--changed `: comma-separated, repo-relative paths to mark as changed. +- `--format `: accepts `markdown` or `json` and is reflected in the report header. -It ignores common generated or vendor folders: +Examples: + +```bash +npx context-drift check --base origin/main +npx context-drift check --format json +npx context-drift check --changed src/index.ts,src/cli.ts +``` + +## Development + +```bash +npm run dev +npm test +npm run typecheck +``` + +## Contributing + +Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. + +Typical contribution flow: + +1. Create a branch for one issue. +2. Make the smallest change that solves that issue. +3. Run the relevant checks: + - `npm run build` + - `npm test` + - `npm run typecheck` +4. Open a focused PR with a clear summary and validation notes. + +## How It Works + +1. Resolve changed files from `--changed` or `git diff --name-only ...HEAD`. +2. Scan the repository for supported source files. +3. Normalize paths and mark files that are part of the changed set. +4. Classify file names into naming styles such as PascalCase, camelCase, kebab-case, and snake_case. +5. Print a compact summary that is easy to read in a terminal or CI log. + +## Project Layout + +- `src/index.ts` bootstraps the CLI. +- `src/cli.ts` defines commands and output. +- `src/scanner.ts` finds supported files and normalizes paths. +- `src/git.ts` reads git diff output. +- `src/naming.ts` classifies file naming styles. +- `tests/` contains the Vitest coverage for the scanner, git helpers, and naming logic. + +## Requirements + +- Node.js `20` or newer +- Git for `--base` comparisons -- `node_modules` -- `.git` -- `.next` -- `dist` -- `build` -- `coverage` diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..66baa0b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,16 @@ +# Security Policy + +## Supported Versions + +This project tracks the current `main` branch and the latest released version. + +## Reporting a Vulnerability + +If you believe you found a security issue: + +1. Do not open a public issue. +2. Describe the problem and the affected area as clearly as you can. +3. Share any reproduction steps, logs, or proof of concept privately with the maintainers. +4. Allow time for triage before publishing details. + +For non-sensitive bugs, open a normal issue or pull request instead. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..fe80f64 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,51 @@ +# Architecture + +Context Drift is a small TypeScript CLI with a single runtime command: + +```bash +context-drift check +``` + +## Core Modules + +- `src/index.ts` starts the CLI entry point. +- `src/cli.ts` defines the `check` command, parses options, and prints output. +- `src/scanner.ts` finds supported source files and normalizes file paths. +- `src/git.ts` reads git diff output for `--base` comparisons. +- `src/naming.ts` classifies file names into naming styles and computes summaries. +- `src/types.ts` keeps the shared data shapes in one place. + +## Data Flow + +1. The CLI resolves changed files from `--changed` or `git diff --name-only ...HEAD`. +2. The scanner walks the repository with `fast-glob`. +3. Supported files are normalized to forward slashes and compared against the changed-file set. +4. The naming analyzer classifies file names and builds whole-repo percentages. +5. The CLI prints a compact summary for terminal and CI usage. + +## Design Goals + +- Keep the implementation small and easy to audit. +- Prefer deterministic output. +- Make changed-file detection match common pull request workflows. +- Avoid scanning generated output and vendor directories. + +## Current Scope + +The first milestone focuses on JavaScript and TypeScript source files: + +- `**/*.ts` +- `**/*.tsx` +- `**/*.js` +- `**/*.jsx` + +Ignored directories: + +- `node_modules` +- `.git` +- `.next` +- `dist` +- `build` +- `coverage` + +Future work can expand the scanner or add more analysis rules without changing the overall CLI shape. diff --git a/docs/checks.md b/docs/checks.md new file mode 100644 index 0000000..7395b73 --- /dev/null +++ b/docs/checks.md @@ -0,0 +1,40 @@ +# Checks + +This project currently exposes a single repository check: + +```bash +context-drift check +``` + +## What It Does + +- Scans supported source files in the current repository. +- Marks files as changed using either `--changed` or `--base`. +- Prints naming-style percentages for the scanned files. + +## Options + +- `--base `: compare the current branch against `...HEAD` and use the diff as the changed-file set. +- `--changed `: provide a comma-separated list of repo-relative paths to treat as changed. +- `--format `: choose `markdown` or `json` output formatting. + +## Examples + +```bash +npx context-drift check --base main +npx context-drift check --base origin/main +npx context-drift check --changed src/cli.ts,src/scanner.ts +npx context-drift check --format json +``` + +## Validation + +Use the standard project checks when changing the scanner, git integration, or CLI output: + +```bash +npm run build +npm test +npm run typecheck +``` + +If you only touch documentation, you can usually skip the code checks and verify the rendered Markdown instead.