Skip to content

Commit 83046f1

Browse files
TomerFiTomerFi
authored
chore: enhance project for AI-assisted development (#256)
* chore: enhance project for AI-assisted development - Enhanced CodeRabbit config with tone and path-specific instructions - Added Cursor agents (code-reviewer, docs-writer) - Added Cursor skill for adding stats modules - Created CONTRIBUTING.md with Cursor IDE documentation - Added workflow concurrency groups to prevent duplicate runs - Added path filters to lint workflow - Enhanced .gitignore with OS, IDE, and environment patterns - Removed .gitattributes (not needed for Node.js project) - Cleaned up project rules (removed Git-specific sections) * chore: improve test-org command documentation * fix: prevent canceling in-progress releases
1 parent c6b7a13 commit 83046f1

File tree

15 files changed

+563
-138
lines changed

15 files changed

+563
-138
lines changed

‎.coderabbit.yaml‎

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,42 @@
11
# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
22
---
33
reviews:
4+
tone_instructions: "Be direct and concise. Focus on correctness of async/await patterns, error handling, and GraphQL API usage."
5+
46
path_instructions:
5-
- path: src/**/*.js
7+
- path: src/api.js
68
instructions: |
7-
Review JavaScript code for:
8-
- Proper async/await and Promise handling
9-
- Error handling and graceful failures
10-
- GitHub API usage patterns
11-
- SVG generation best practices
9+
GraphQL client singleton. Review for:
10+
- Token validation before API calls
11+
- Error handling patterns
12+
- Singleton pattern correctness
13+
14+
- path: src/cli.js
15+
instructions: |
16+
CLI entrypoint. Review for:
17+
- Argument parsing correctness
18+
- Error messaging clarity
19+
- User experience
20+
21+
- path: src/{contribs,repo,org}.js
22+
instructions: |
23+
Statistics collection modules. Review for:
24+
- GraphQL query correctness
25+
- Data transformation accuracy
26+
- Error handling for API failures
27+
28+
- path: .github/workflows/*.yml
29+
instructions: |
30+
Review workflows for:
31+
32+
Security:
33+
- Proper secret handling via ${{ secrets.* }}
34+
- SSH signing configured correctly
35+
36+
Efficiency:
37+
- Concurrency groups prevent duplicate runs
38+
- Path filters for relevant changes
39+
40+
Correctness:
41+
- Proper trigger conditions
42+
- Fetch depth appropriate for git operations

‎.cursor/agents/code-reviewer.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: code-reviewer
3+
description: Pre-commit code review checklist
4+
---
5+
6+
# Pre-Commit Code Review
7+
8+
Review the code changes:
9+
10+
## Code Quality
11+
12+
- [ ] All async functions use `await` (no floating promises)
13+
- [ ] GraphQL queries are syntactically correct
14+
- [ ] Error handling wraps all API calls with try/catch
15+
- [ ] No hardcoded tokens, secrets, or credentials in code
16+
- [ ] ESLint passes: `npm run lint`
17+
18+
## API Client Usage
19+
20+
- [ ] Uses `require('./api')` singleton for GraphQL client
21+
- [ ] Token comes from environment variable only
22+
- [ ] Error messages are clear and actionable
23+
24+
## Testing
25+
26+
Test manually:
27+
28+
```bash
29+
npm run contribs
30+
npm run repo <repo-name>
31+
npm run org <org-name>
32+
```

‎.cursor/agents/docs-writer.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
name: docs-writer
3+
description: Documentation update assistant
4+
---
5+
6+
# Documentation Updates
7+
8+
When updating documentation:
9+
10+
## README.md Updates
11+
12+
- Update version examples if API changes
13+
- Update token scope requirements if queries change
14+
- Keep examples between `<!--START OF STATS-->` and `<!--END OF STATS-->` unchanged (auto-updated by workflow)
15+
- Keep examples between `<!--START OF REPO-->` and `<!--END OF REPO-->` unchanged (auto-updated by workflow)
16+
- Verify all code examples are tested
17+
18+
## CONTRIBUTING.md Updates
19+
20+
- Keep development setup instructions current
21+
- Update Cursor IDE section if agents/commands/skills change
22+
- Verify all commands work
23+
24+
## Code Comments
25+
26+
- Focus on "why" not "what"
27+
- Document GraphQL query structure
28+
- Explain non-obvious error handling
29+
- Document token scope requirements for API calls

‎.cursor/commands/lint.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
name: lint
3+
description: Run ESLint on source files
4+
---
5+
6+
```bash
7+
npm run lint
8+
```
9+
10+
Runs ESLint with the configuration in `eslint.config.mjs`.
11+
12+
Checks all JavaScript files in the `src/` directory for code quality issues.

‎.cursor/commands/test-contribs.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
name: test-contribs
3+
description: Test the contribs command locally (requires GITHUB_TOKEN)
4+
---
5+
6+
Test the user contributions statistics command:
7+
8+
```bash
9+
npm run contribs
10+
```
11+
12+
**Prerequisites:**
13+
- `GITHUB_TOKEN` environment variable must be set
14+
- Token requires scopes: `repo`, `read:packages`, `read:user`, `read:discussion`
15+
16+
The command will print your GitHub user statistics as JSON.

‎.cursor/commands/test-org.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
name: test-org
3+
description: Test the org command locally (requires GITHUB_TOKEN)
4+
---
5+
6+
Test the organization statistics command.
7+
8+
**Usage:**
9+
10+
```bash
11+
npm run org <org-name>
12+
```
13+
14+
**Prerequisites:**
15+
- `GITHUB_TOKEN` environment variable must be set
16+
- Token requires scopes: `read:org` (or `admin:org` for admin-level stats like 2FA and pending members)
17+
18+
The command will print organization statistics as JSON.
19+
20+
**Example:**
21+
22+
```bash
23+
npm run org my-org-name
24+
```

‎.cursor/commands/test-repo.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
name: test-repo
3+
description: Test the repo command locally (requires GITHUB_TOKEN)
4+
---
5+
6+
Test the repository statistics command:
7+
8+
```bash
9+
npm run repo <repo-name>
10+
```
11+
12+
Replace `<repo-name>` with the name of one of your repositories (e.g., `aioswitcher`).
13+
14+
**Prerequisites:**
15+
- `GITHUB_TOKEN` environment variable must be set
16+
- Token requires scopes: `repo`, `read:packages`
17+
18+
The command will print repository statistics as JSON.

‎.cursor/rules/project-rules.mdc‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
description: github-viewer-stats project conventions and development guidelines
3+
alwaysApply: true
4+
---
5+
6+
# github-viewer-stats Project Rules
7+
8+
## Project Overview
9+
10+
A lightweight Node.js CLI tool and library for collecting GitHub statistics using the GraphQL API.
11+
12+
## Coding Conventions
13+
14+
### JavaScript Style
15+
- Use CommonJS modules (`module.exports`, `require`)
16+
- Prefer `async`/`await` over raw Promises
17+
- Use template literals for string interpolation
18+
- Follow existing indentation (2 spaces, per `.editorconfig`)
19+
20+
### Error Handling
21+
- Validate `GITHUB_TOKEN` environment variable before API calls
22+
- Provide clear, actionable error messages
23+
- Handle GraphQL API errors gracefully
24+
25+
### API Usage
26+
- Use `@octokit/graphql` for GitHub GraphQL API calls
27+
- Singleton pattern for API client (see `src/api.js`)
28+
- Token authentication via `GITHUB_TOKEN` environment variable
29+
30+
## Architecture Constraints
31+
32+
### File Organization
33+
- `src/index.js` - Main module exports
34+
- `src/api.js` - GraphQL client factory
35+
- `src/cli.js` - CLI entrypoint
36+
- `src/contribs.js` - User contribution stats
37+
- `src/repo.js` - Repository stats
38+
- `src/org.js` - Organization stats
39+
40+
### Dependencies
41+
- Keep dependencies minimal
42+
- Only `@octokit/graphql` for runtime
43+
- Dev dependencies for linting only
44+
45+
## Development Tools
46+
47+
### Linting
48+
```bash
49+
npm run lint
50+
```
51+
52+
ESLint is configured via `eslint.config.mjs` with recommended rules for Node.js/CommonJS.
53+
54+
### Testing Locally
55+
Requires a `GITHUB_TOKEN` environment variable with scopes: `repo`, `read:packages`, `read:user`, `read:discussion`, `read:org` (or `admin:org` for full org stats).
56+
57+
Test commands:
58+
```bash
59+
npm run contribs
60+
npm run repo <repo-name>
61+
npm run org <org-name>
62+
```

‎.cursor/skills/add-stats-module/SKILL.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
name: add-stats-module
3+
description: Guide for adding new GitHub statistics collection modules
4+
---
5+
6+
# Adding a New Statistics Module
7+
8+
Follow these steps to add a new statistics collection module:
9+
10+
## 1. Create the Module File
11+
12+
Create `src/new-module.js`:
13+
14+
```javascript
15+
const { graphql } = require('./api');
16+
17+
module.exports = async function(arg) {
18+
// Validate argument if needed
19+
if (!arg) {
20+
throw new Error('Argument required');
21+
}
22+
23+
// GraphQL query
24+
const query = `
25+
query($arg: String!) {
26+
# Your GraphQL query here
27+
}
28+
`;
29+
30+
try {
31+
const result = await graphql(query, { arg });
32+
33+
// Transform and return data
34+
return {
35+
// Your data structure
36+
};
37+
} catch (error) {
38+
throw new Error(`Failed to fetch stats: ${error.message}`);
39+
}
40+
};
41+
```
42+
43+
## 2. Export from Index
44+
45+
Add to `src/index.js`:
46+
47+
```javascript
48+
exports.newModule = require('./new-module');
49+
```
50+
51+
## 3. Add CLI Command
52+
53+
Update `src/cli.js` to add the command:
54+
55+
```javascript
56+
case 'newmodule':
57+
return require('./new-module')(process.argv[3]);
58+
```
59+
60+
## 4. Add npm Script
61+
62+
Update `package.json` scripts section:
63+
64+
```json
65+
"newmodule": "run(){ node -e \"async function run() { console.log(JSON.stringify(await require('./src/new-module')('$1'), null, 2)) } run()\"; }; run"
66+
```
67+
68+
## 5. Add Test Command
69+
70+
Create `.cursor/commands/test-newmodule.md`:
71+
72+
```markdown
73+
---
74+
name: test-newmodule
75+
description: Test the new module command
76+
---
77+
78+
Test the new module command:
79+
80+
\`\`\`bash
81+
npm run newmodule <arg>
82+
\`\`\`
83+
84+
**Prerequisites:**
85+
- `GITHUB_TOKEN` environment variable must be set
86+
- Token requires appropriate scopes
87+
88+
The command will print statistics as JSON.
89+
```
90+
91+
## 6. Update Documentation
92+
93+
Update README.md with usage example:
94+
95+
```markdown
96+
\`\`\`shell
97+
npx github-viewer-stats newmodule <arg>
98+
\`\`\`
99+
100+
\`\`\`json
101+
{
102+
"example": "output"
103+
}
104+
\`\`\`
105+
```
106+
107+
## GraphQL Query Tips
108+
109+
- Use the GitHub GraphQL Explorer: https://docs.github.com/en/graphql/overview/explorer
110+
- Test queries before implementing
111+
- Handle pagination if needed
112+
- Include error handling for rate limits

0 commit comments

Comments
 (0)