Skip to content

Commit 78a23b3

Browse files
bntvllntbntvllnt
authored
docs: improve OSS readiness basics (#32)
## Summary - align README release docs with the actual GitHub Actions release flow - add core OSS contributor documents and templates - ignore local `.vllnt/` state to reduce accidental leakage ## Changes - add `CONTRIBUTING.md` - add `SECURITY.md` - add `CODE_OF_CONDUCT.md` - add GitHub issue templates and a PR template - update `README.md` release, security, and contributing sections - add `.vllnt/` to `.gitignore` ## Validation - `pnpm lint` - `pnpm typecheck` - `pnpm build` - `pnpm test`
1 parent 6fc5287 commit 78a23b3

8 files changed

Lines changed: 241 additions & 1 deletion

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: Bug report
3+
about: Report incorrect behavior, broken analysis, or regressions
4+
labels: bug
5+
---
6+
7+
## Summary
8+
9+
Describe the bug clearly.
10+
11+
## Reproduction
12+
13+
- command or MCP tool used:
14+
- target codebase shape:
15+
- exact input:
16+
- expected result:
17+
- actual result:
18+
19+
## Environment
20+
21+
- package version:
22+
- node version:
23+
- OS:
24+
25+
## Validation
26+
27+
Include logs, JSON output, screenshots, or minimal repro files when possible.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
name: Feature request
3+
about: Propose a new capability or improvement
4+
labels: enhancement
5+
---
6+
7+
## Problem
8+
9+
What problem are you trying to solve?
10+
11+
## Proposed change
12+
13+
Describe the feature or improvement.
14+
15+
## CLI / MCP impact
16+
17+
If relevant, describe:
18+
- CLI commands or flags affected
19+
- MCP tools or output shape affected
20+
- docs that would need updates
21+
22+
## Alternatives considered
23+
24+
List simpler alternatives if any.

‎.github/pull_request_template.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## Summary
2+
-
3+
4+
## Why
5+
-
6+
7+
## Changes
8+
-
9+
10+
## Validation
11+
- [ ] lint
12+
- [ ] typecheck
13+
- [ ] build
14+
- [ ] test
15+
16+
## Docs impact
17+
- [ ] README updated
18+
- [ ] docs/ updated
19+
- [ ] no docs changes needed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@ next-env.d.ts
77
.npmrc
88
.mcp.json
99
.worktrees/
10+
.vllnt/
1011
test-results/
1112
scripts/

‎CODE_OF_CONDUCT.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Code of Conduct
2+
3+
## Our commitment
4+
5+
We want this project to be open, respectful, and useful to contributors of different backgrounds and experience levels.
6+
7+
## Expected behavior
8+
9+
Examples of positive behavior:
10+
- be respectful and constructive
11+
- assume good intent
12+
- give actionable technical feedback
13+
- keep discussions focused on the work
14+
- accept correction gracefully
15+
16+
## Unacceptable behavior
17+
18+
Examples of unacceptable behavior:
19+
- harassment or personal attacks
20+
- discriminatory language or behavior
21+
- bad-faith trolling or deliberate disruption
22+
- doxxing or sharing private information without permission
23+
- repeated hostile or unconstructive review behavior
24+
25+
## Enforcement
26+
27+
Project maintainers may remove, edit, or reject comments, issues, pull requests, or other contributions that violate this code of conduct.
28+
29+
## Reporting
30+
31+
If you experience or witness unacceptable behavior, contact the maintainers privately when possible.
32+
For security-sensitive matters, use [SECURITY.md](SECURITY.md).
33+
34+
## Scope
35+
36+
This code of conduct applies in project spaces, including issues, pull requests, discussions, and review conversations.

‎CONTRIBUTING.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Contributing
2+
3+
Thanks for contributing to `codebase-intelligence`.
4+
5+
## Development setup
6+
7+
```bash
8+
git clone https://github.com/bntvllnt/codebase-intelligence.git
9+
cd codebase-intelligence
10+
pnpm install
11+
```
12+
13+
Useful commands:
14+
15+
```bash
16+
pnpm dev
17+
pnpm lint
18+
pnpm typecheck
19+
pnpm build
20+
pnpm test
21+
```
22+
23+
## Workflow
24+
25+
- Create a feature branch from `main`
26+
- Keep changes focused and atomic
27+
- Prefer one concern per pull request
28+
- Open a PR early if you want feedback on scope
29+
30+
## Commit conventions
31+
32+
This repository uses conventional-style commit subjects.
33+
34+
Examples:
35+
- `feat: add module-depth CLI command`
36+
- `fix: normalize Windows paths in MCP handlers`
37+
- `docs: clarify MCP setup`
38+
- `test: add regression coverage for dead exports`
39+
40+
The release workflow generates changelog sections from commit prefixes, so prefer:
41+
- `feat:` for user-visible features
42+
- `fix:` for user-visible fixes
43+
- `docs:` / `test:` / `chore:` for non-feature work
44+
45+
## Testing expectations
46+
47+
Before opening a PR, run:
48+
49+
```bash
50+
pnpm lint
51+
pnpm typecheck
52+
pnpm build
53+
pnpm test
54+
```
55+
56+
Testing guidance:
57+
- prefer real integration coverage over isolated mocking
58+
- add regression tests for bug fixes
59+
- update docs when CLI, MCP, or metrics behavior changes
60+
61+
## Pull requests
62+
63+
Please include:
64+
- what changed
65+
- why it changed
66+
- any CLI or MCP surface changes
67+
- validation performed
68+
69+
If your change affects users, update the relevant docs in `docs/` and `README.md`.
70+
71+
## Security
72+
73+
Do not open public issues for suspected vulnerabilities.
74+
See [SECURITY.md](SECURITY.md).
75+
76+
## Code of conduct
77+
78+
By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).

‎README.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
4848
- [Requirements](#requirements)
4949
- [Limitations](#limitations)
5050
- [Release](#release)
51+
- [Security](#security)
5152
- [Contributing](#contributing)
5253
- [License](#license)
5354

@@ -233,9 +234,23 @@ Publishing is automated through GitHub Actions.
233234

234235
No PAT is required for npm publish. The workflow uses GitHub repository permissions for tagging and OIDC for npm publishing.
235236

237+
## Security
238+
239+
Please do not report security vulnerabilities in public issues.
240+
241+
- Read [`SECURITY.md`](SECURITY.md) for supported versions and disclosure guidance.
242+
- Use GitHub Security Advisories or private maintainer contact for sensitive reports.
243+
236244
## Contributing
237245

238-
Contributions are welcome. Please open an issue first to discuss what you'd like to change.
246+
Contributions are welcome.
247+
248+
Start here:
249+
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, workflow, testing, and PR expectations
250+
- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — community standards
251+
- [`SECURITY.md`](SECURITY.md) — vulnerability reporting
252+
253+
Quick setup:
239254

240255
```bash
241256
git clone https://github.com/bntvllnt/codebase-intelligence.git

‎SECURITY.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Security Policy
2+
3+
## Supported versions
4+
5+
Security fixes are supported for the latest published release on the `main` line.
6+
7+
| Version | Supported |
8+
|---------|-----------|
9+
| latest release | yes |
10+
| older releases | no |
11+
| prerelease / canary | best effort |
12+
13+
## Reporting a vulnerability
14+
15+
Please do not report vulnerabilities in public GitHub issues.
16+
17+
Use one of these private channels:
18+
- GitHub Security Advisories for this repository
19+
- direct maintainer contact if a private channel is available
20+
21+
When reporting, include:
22+
- affected version
23+
- impact summary
24+
- reproduction steps or proof of concept
25+
- suggested mitigation if known
26+
27+
You can expect:
28+
- acknowledgement as soon as practical
29+
- triage and severity assessment
30+
- a coordinated fix/release plan when confirmed
31+
32+
## Scope
33+
34+
This project analyzes local TypeScript codebases and exposes results through CLI and MCP interfaces.
35+
Security-relevant reports may include:
36+
- command execution risks
37+
- unsafe path handling
38+
- unintended filesystem access
39+
- data exposure through MCP responses
40+
- dependency vulnerabilities with practical impact

0 commit comments

Comments
 (0)