Skip to content

Commit 300131d

Browse files
shouzeshouze
committed
config(github): add agents and instructions files
1 parent f0ba084 commit 300131d

4 files changed

Lines changed: 338 additions & 0 deletions

File tree

‎.github/instructions/bug-fixing.instructions.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
applyTo: "**"
3+
excludeAgent: "code-review"
4+
---
5+
6+
# Bug fixing — instructions for Copilot coding agent
7+
8+
Follow these steps when fixing a bug in this repository.
9+
10+
## 1. Reproduce the bug before writing any fix
11+
12+
A bug report should include:
13+
- The exact command that was run (with `GITHUB_TOKEN` redacted).
14+
- The observed vs. expected behaviour.
15+
- The `github-code-search --version` output (contains commit SHA, OS, architecture).
16+
17+
If the report is incomplete, do not guess. Review the relevant module(s) to locate the most likely root cause.
18+
19+
## 2. Locate the root cause
20+
21+
Use the module map in `AGENTS.md` to identify where the bug likely lives:
22+
23+
| Symptom | Look in |
24+
|---------|---------|
25+
| Wrong grouping / filtering of results | `src/aggregate.ts`, `src/group.ts` |
26+
| Incorrect markdown / JSON output | `src/output.ts` |
27+
| Wrong syntax highlighting | `src/render/highlight.ts` |
28+
| Bad row navigation or visibility | `src/render/rows.ts` |
29+
| Incorrect select-all / select-none | `src/render/selection.ts` |
30+
| Wrong stats / summary line | `src/render/summary.ts` |
31+
| Filter stats incorrect | `src/render/filter.ts` |
32+
| API pagination or rate-limit issue | `src/api.ts` |
33+
| TUI keyboard handling / display glitch | `src/tui.ts` |
34+
| Upgrade failure | `src/upgrade.ts` |
35+
| CLI option parsing / defaults | `github-code-search.ts` |
36+
37+
## 3. Write a failing test before fixing
38+
39+
For any bug in a pure-function module (`aggregate.ts`, `group.ts`, `output.ts`, `render/`):
40+
1. Open (or create) the companion `*.test.ts` file.
41+
2. Write a test case that reproduces the exact bug scenario and **fails** with the current code.
42+
3. Commit the failing test first (or keep it as part of the same commit with the fix, clearly noted).
43+
44+
This ensures the fix is verified and the regression cannot reappear undetected.
45+
46+
For bugs in `tui.ts` or `api.ts` (side-effectful code), a test may not be practical — document the manual reproduction steps in the PR instead.
47+
48+
## 4. Apply the minimal fix
49+
50+
- Fix only the root cause. Do not refactor unrelated code in the same PR.
51+
- Respect the layering: pure functions stay pure, I/O stays in `api.ts` / `tui.ts` / entry point.
52+
- If fixing the bug requires a type change in `src/types.ts`, update all usages across the codebase.
53+
54+
## 5. Verify the fix
55+
56+
```bash
57+
bun test # the previously failing test now passes; full suite still green
58+
bun run lint # oxlint — zero errors
59+
bun run format:check # oxfmt — no formatting diff
60+
bun run knip # no unused exports or imports
61+
bun run build.ts # binary compiles without errors
62+
```
63+
64+
## 6. Regression note
65+
66+
Add a one-line comment above the fix if the root cause is non-obvious:
67+
```typescript
68+
// Fix: <what was wrong and why> — see issue #<N>
69+
```
70+
71+
## 7. Commit & pull request
72+
73+
- Branch name: `fix/<short-description>` (e.g. `fix/exclude-repos-with-org-prefix`).
74+
- Commit message: imperative mood, e.g. `Fix --exclude-repositories ignoring org-prefixed names`.
75+
- PR description:
76+
- Root cause explanation.
77+
- Steps to reproduce (before the fix).
78+
- Steps to verify (after the fix).
79+
- Reference to the issue number.

‎.github/instructions/implement-feature.instructions.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
applyTo: "**"
3+
excludeAgent: "code-review"
4+
---
5+
6+
# Implement feature — instructions for Copilot coding agent
7+
8+
Follow these steps when implementing a new feature in this repository.
9+
10+
## 1. Understand the task scope before writing code
11+
12+
- Read the issue description and acceptance criteria carefully.
13+
- Identify which modules will host the new logic (check `src/types.ts`, `AGENTS.md` and existing modules for context).
14+
- If the feature introduces a new shared type, add it to `src/types.ts` before touching anything else.
15+
- If the feature touches the CLI surface, the entry point is `github-code-search.ts` (Commander subcommands).
16+
17+
## 2. Follow the architectural boundaries
18+
19+
| Layer | Location | Rule |
20+
|-------|----------|------|
21+
| Shared types | `src/types.ts` | All new interfaces go here |
22+
| Pure business logic | `src/aggregate.ts`, `src/group.ts`, `src/render/` | Pure functions only — no I/O |
23+
| Output formatting | `src/output.ts` | Markdown and JSON renderers |
24+
| Rendering façade | `src/render.ts` | Re-export new sub-module symbols here |
25+
| API calls | `src/api.ts` | Only place allowed to call GitHub REST API |
26+
| TUI interaction | `src/tui.ts` | Only place allowed to read stdin / write to TTY |
27+
| CLI parsing | `github-code-search.ts` | Commander options and subcommands |
28+
| Auto-upgrade | `src/upgrade.ts` | Binary self-replacement logic |
29+
30+
Never mix pure logic with I/O. If a new feature requires both, split it: write a pure function in the appropriate module and call it from `api.ts`, `tui.ts` or `github-code-search.ts`.
31+
32+
## 3. Adding a new render sub-module
33+
34+
If the feature introduces a new rendering concern (e.g. a new display component):
35+
1. Create `src/render/<name>.ts` with pure functions.
36+
2. Export the new symbols from `src/render.ts` (the façade).
37+
3. Import from `src/render.ts` in consumers — never directly from `src/render/<name>.ts`.
38+
39+
## 4. Write tests for every new pure function
40+
41+
- Create or update `src/<module>.test.ts` (co-located with the source file).
42+
- Use `describe` / `it` / `expect` from Bun's built-in test runner.
43+
- Tests must be self-contained: no network calls, no filesystem side effects.
44+
- Cover edge cases: empty arrays, undefined/null guards, boundary values.
45+
- Run `bun test` to verify the full suite passes before considering the implementation done.
46+
47+
## 5. Update the CLI documentation if the public interface changes
48+
49+
- If a new CLI option or subcommand is added, update `README.md` (usage section, options table, examples).
50+
- If a new flag requires additional GitHub token scopes, document them in `README.md` and `AGENTS.md`.
51+
52+
## 6. Validation checklist
53+
54+
Before opening the pull request, ensure every item passes:
55+
56+
```bash
57+
bun test # all tests green
58+
bun run lint # oxlint — zero errors
59+
bun run format:check # oxfmt — no formatting diff
60+
bun run knip # no unused exports or imports
61+
bun run build.ts # binary compiles without errors
62+
```
63+
64+
## 7. Commit & pull request
65+
66+
- Branch name: `feat/<short-description>` (e.g. `feat/json-output-type`).
67+
- Commit message: imperative mood, e.g. `Add --output-type flag for JSON format`.
68+
- PR description: motivation, what changed, how to test manually.

‎.github/instructions/refactoring.instructions.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
applyTo: "**"
3+
excludeAgent: "code-review"
4+
---
5+
6+
# Refactoring — instructions for Copilot coding agent
7+
8+
Follow these steps when refactoring existing code in this repository.
9+
10+
## 1. Define the goal and scope
11+
12+
A good refactoring task has a clearly bounded scope. Before making any change, identify:
13+
- Which module(s) are affected (consult `AGENTS.md` for the layer map).
14+
- Whether the public API (exported symbols, CLI options) is changing or staying the same.
15+
- Whether the refactoring is purely internal (no behavior change) or also simplifies the API.
16+
17+
**Prefer behaviour-preserving refactorings.** If the public API must change, document it explicitly in the PR.
18+
19+
## 2. Do not break the architectural boundaries
20+
21+
This codebase enforces a strict layering:
22+
23+
- **Pure functions** must stay pure — do not introduce side effects (I/O, global state, `Date.now()`, `Math.random()`) into `aggregate.ts`, `group.ts`, `output.ts`, or `render/` sub-modules.
24+
- **I/O is isolated** in `api.ts`, `tui.ts` and `github-code-search.ts`. Keep it there.
25+
- **`render.ts` is a façade** — if you move or rename symbols in `render/`, update the re-exports in `render.ts` accordingly.
26+
- **`types.ts` is the single source of truth** — if you merge or rename interfaces, update all usages across the codebase.
27+
28+
## 3. Verify test coverage first
29+
30+
Before touching code:
31+
```bash
32+
bun test # baseline — all tests must be green before you start
33+
```
34+
35+
If the area you are refactoring lacks tests, **add tests before refactoring** (characterisation tests). This ensures you can verify the refactoring is behaviour-preserving.
36+
37+
## 4. Make changes incrementally
38+
39+
- Refactor one logical unit at a time (one function, one module boundary).
40+
- Run `bun test` after each meaningful step to catch regressions early.
41+
- Avoid mixing a refactoring with a feature addition in the same commit; separate concerns.
42+
43+
## 5. Update all usages when renaming
44+
45+
If you rename an exported function, type or constant:
46+
- Update every import site across the codebase — use a global search before renaming.
47+
- Update `render.ts` if the renamed symbol is re-exported there.
48+
- Update `src/types.ts` if it's a shared type.
49+
- Run `bun run knip` to detect any forgotten reference.
50+
51+
## 6. Keep `knip` clean
52+
53+
Every exported symbol must be used. After a refactoring:
54+
```bash
55+
bun run knip # zero unused exports / imports
56+
```
57+
58+
Remove dead code rather than leaving it commented out.
59+
60+
## 7. Validation checklist
61+
62+
```bash
63+
bun test # full suite passes — same behaviour before and after
64+
bun run lint # oxlint — zero errors
65+
bun run format:check # oxfmt — no formatting diff
66+
bun run knip # no unused exports or imports
67+
bun run build.ts # binary compiles without errors
68+
```
69+
70+
## 8. Commit & pull request
71+
72+
- Branch name: `refactor/<short-description>` (e.g. `refactor/extract-filter-module`).
73+
- Commit message: imperative mood, e.g. `Extract FilterStats helpers into render/filter.ts`.
74+
- PR description: what was restructured, why, and a note confirming no behaviour change.

‎AGENTS.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# github-code-search — Agent instructions
2+
3+
This file provides context for AI coding agents (GitHub Copilot, Claude, Gemini, etc.) working in this repository.
4+
5+
## What this project does
6+
7+
`github-code-search` is an interactive CLI (powered by [Bun](https://bun.sh)) to search GitHub code across an organisation. It aggregates results per repository, displays a keyboard-driven TUI and lets the user select extracts before printing structured markdown or JSON output. A `query` subcommand and an `upgrade` subcommand are exposed via [Commander](https://github.com/tj/commander.js).
8+
9+
## Runtime & toolchain
10+
11+
| Tool | Version |
12+
|------|---------|
13+
| **Bun** | ≥ 1.0 (runtime, bundler, test runner, package manager) |
14+
| **TypeScript** | via Bun (no separate `tsc` invocation needed at runtime) |
15+
| **oxlint** | linter (`bun run lint`) |
16+
| **oxfmt** | formatter (`bun run format`) |
17+
| **knip** | dead-code detector (`bun run knip`) |
18+
19+
There is **no Node.js / npm** involved. Always use `bun` commands.
20+
21+
## Bootstrap
22+
23+
```bash
24+
bun install # install dependencies (reads bunfig.toml + package.json)
25+
```
26+
27+
`bunfig.toml` sets `smol = true` (lighter install). No additional setup step is needed.
28+
29+
## Build commands
30+
31+
```bash
32+
bun run build.ts # compile a self-contained binary → dist/github-code-search
33+
bun run build.ts --target=bun-darwin-arm64 # cross-compile (see CONTRIBUTING.md for all targets)
34+
```
35+
36+
The build script (`build.ts`) injects the git commit SHA, target OS and architecture into the binary. The produced binary has no runtime dependency and can be distributed as a single file.
37+
38+
## Running tests
39+
40+
```bash
41+
bun test # run the whole test suite
42+
bun test --watch # re-run on file changes (development)
43+
```
44+
45+
All tests use Bun's built-in test runner (`@jest/globals`-compatible API: `describe`, `it`, `expect`). No additional testing library is needed. The setup file is `src/test-setup.ts` (referenced in `bunfig.toml`).
46+
47+
## Linting & formatting
48+
49+
```bash
50+
bun run lint # oxlint — must pass before submitting
51+
bun run format # oxfmt write (auto-fix)
52+
bun run format:check # oxfmt check (CI check)
53+
bun run knip # detect unused exports / files
54+
```
55+
56+
Always run `bun run lint` and `bun run format:check` before considering a change complete.
57+
58+
## Project layout
59+
60+
```
61+
github-code-search.ts # CLI entry point — Commander subcommands: query, upgrade
62+
build.ts # Build script (Bun.build)
63+
bunfig.toml # Bun configuration (smol install, test preload)
64+
tsconfig.json # TypeScript configuration
65+
knip.json # knip (dead-code) configuration
66+
67+
src/
68+
types.ts # All shared TypeScript interfaces (TextMatchSegment,
69+
# TextMatch, CodeMatch, RepoGroup, Row, TeamSection,
70+
# OutputFormat, OutputType)
71+
api.ts # GitHub REST API client (search, team fetching)
72+
aggregate.ts # Result grouping & filtering (applyFiltersAndExclusions)
73+
group.ts # groupByTeamPrefix — team-prefix grouping logic
74+
render.ts # Façade re-exporting sub-modules + top-level
75+
# renderGroups() / renderHelpOverlay()
76+
tui.ts # Interactive keyboard-driven UI (navigation, filter mode,
77+
# help overlay, selection)
78+
output.ts # Text (markdown) and JSON output formatters
79+
upgrade.ts # Auto-upgrade logic (fetch latest GitHub release, replace binary)
80+
81+
render/
82+
highlight.ts # Syntax highlighting (language detection + token rules)
83+
filter.ts # FilterStats + buildFilterStats
84+
rows.ts # buildRows, rowTerminalLines, isCursorVisible
85+
summary.ts # buildSummary, buildSummaryFull, buildSelectionSummary
86+
selection.ts # applySelectAll, applySelectNone
87+
88+
*.test.ts # Unit tests co-located with source files
89+
test-setup.ts # Global test setup (Bun preload)
90+
```
91+
92+
## Key architectural principles
93+
94+
- **Pure functions first.** All business logic lives in pure, side-effect-free functions (`aggregate.ts`, `group.ts`, `output.ts`, `render/` sub-modules). This makes them straightforward to unit-test.
95+
- **Side effects are isolated.** API calls (`api.ts`), TTY interaction (`tui.ts`) and CLI parsing (`github-code-search.ts`) are the only side-effectful surfaces.
96+
- **`render.ts` is a façade.** It re-exports everything from `render/` and adds two top-level rendering functions. Consumers import from `render.ts`, not directly from sub-modules.
97+
- **`types.ts` is the single source of truth** for all shared interfaces. Any new shared type must go there.
98+
- **No classes** — the codebase uses plain TypeScript interfaces and functions throughout.
99+
100+
## Writing tests
101+
102+
- Test files are named `<module>.test.ts` and sit next to their source file.
103+
- Use `describe` / `it` / `expect` from Bun's test runner.
104+
- Only pure functions need tests; `tui.ts` and `api.ts` are not unit-tested.
105+
- When adding a function to an existing module, add the corresponding test case in the existing `<module>.test.ts`.
106+
- When creating a new module that contains pure functions, create a companion `<module>.test.ts`.
107+
- Tests must be self-contained: no network calls, no filesystem side effects.
108+
109+
## Development notes
110+
111+
- **TypeScript throughout** — no `.js` files in `src/`.
112+
- Bun executes `.ts` files directly; no transpilation step is needed to run the CLI locally (`bun github-code-search.ts query ...`).
113+
- The `--exclude-repositories` and `--exclude-extracts` options accept both short (`repoName`) and long (`org/repoName`) forms — this normalisation happens in `aggregate.ts`.
114+
- The `--group-by-team-prefix` option requires a `read:org` GitHub token scope; this is documented in `README.md`.
115+
- The `upgrade` subcommand replaces the running binary in-place using `src/upgrade.ts`; be careful with filesystem operations there.
116+
- `picocolors` is the only styling dependency; do not add `chalk` or similar.
117+
- Keep `knip` clean: every exported symbol must be used; every import must resolve.

0 commit comments

Comments
 (0)