Skip to content

Commit c9226f9

Browse files
shouzeshouze
committed
chore(review): take into account some feedback
1 parent aa08d48 commit c9226f9

File tree

8 files changed

+161
-141
lines changed

8 files changed

+161
-141
lines changed

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

Lines changed: 26 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,28 @@ This skill complements `.github/instructions/bug-fixing.instructions.md`.
77

88
## Symptom → module diagnostic table
99

10-
| Symptom | Primary suspect | Secondary suspect |
11-
| --------------------------------------------------- | -------------------------------------- | ----------------------------- |
12-
| Results missing or duplicated | `src/aggregate.ts` | `src/api.ts` (pagination) |
13-
| Wrong repository grouping | `src/group.ts` | `src/aggregate.ts` |
14-
| `--exclude-repositories` / `--exclude-extracts` not working | `src/aggregate.ts` | `github-code-search.ts` (parsing) |
15-
| Markdown output malformed | `src/output.ts` | — |
16-
| JSON output missing fields or wrong shape | `src/output.ts` | `src/types.ts` (interface) |
17-
| Syntax highlighting wrong colour / wrong language | `src/render/highlight.ts` | — |
18-
| Row navigation skips or wraps incorrectly | `src/render/rows.ts` | `src/tui.ts` (key handler) |
19-
| Select-all / select-none inconsistent | `src/render/selection.ts` | `src/tui.ts` |
20-
| Filter count / stats incorrect | `src/render/filter.ts`, `src/render/summary.ts` | — |
21-
| Path filter (`/regex/`) doesn't match expected | `src/render/filter-match.ts` | `src/tui.ts` (filter state) |
22-
| API returns 0 results or stops paginating | `src/api.ts` | `src/api-utils.ts` |
23-
| Rate limit hit / 429 not retried | `src/api-utils.ts` (`fetchWithRetry`) | — |
24-
| TUI shows blank screen or wrong row | `src/tui.ts` | `src/render/rows.ts` |
25-
| Help overlay doesn't appear / has wrong keys | `src/render.ts` (`renderHelpOverlay`) | `src/tui.ts` |
26-
| Upgrade fails or replaces wrong binary | `src/upgrade.ts` | — |
27-
| Completion script wrong content | `src/completions.ts` | — |
28-
| Completion file written to wrong path | `src/completions.ts` (`getCompletionFilePath`) | env vars (`XDG_*`, `ZDOTDIR`) |
29-
| Completion not refreshed after upgrade | `src/upgrade.ts` (`refreshCompletions`) | — |
30-
| `--version` shows wrong info | `build.ts` (SHA injection) | — |
31-
| CLI option ignored or parsed wrong | `github-code-search.ts` | `src/types.ts` (`OutputType`) |
10+
| Symptom | Primary suspect | Secondary suspect |
11+
| ----------------------------------------------------------- | ----------------------------------------------- | --------------------------------- |
12+
| Results missing or duplicated | `src/aggregate.ts` | `src/api.ts` (pagination) |
13+
| Wrong repository grouping | `src/group.ts` | `src/aggregate.ts` |
14+
| `--exclude-repositories` / `--exclude-extracts` not working | `src/aggregate.ts` | `github-code-search.ts` (parsing) |
15+
| Markdown output malformed | `src/output.ts` | — |
16+
| JSON output missing fields or wrong shape | `src/output.ts` | `src/types.ts` (interface) |
17+
| Syntax highlighting wrong colour / wrong language | `src/render/highlight.ts` | — |
18+
| Row navigation skips or wraps incorrectly | `src/render/rows.ts` | `src/tui.ts` (key handler) |
19+
| Select-all / select-none inconsistent | `src/render/selection.ts` | `src/tui.ts` |
20+
| Filter count / stats incorrect | `src/render/filter.ts`, `src/render/summary.ts` | — |
21+
| Path filter (`/regex/`) doesn't match expected | `src/render/filter-match.ts` | `src/tui.ts` (filter state) |
22+
| API returns 0 results or stops paginating | `src/api.ts` | `src/api-utils.ts` |
23+
| Rate limit hit / 429 not retried | `src/api-utils.ts` (`fetchWithRetry`) | — |
24+
| TUI shows blank screen or wrong row | `src/tui.ts` | `src/render/rows.ts` |
25+
| Help overlay doesn't appear / has wrong keys | `src/render.ts` (`renderHelpOverlay`) | `src/tui.ts` |
26+
| Upgrade fails or replaces wrong binary | `src/upgrade.ts` | — |
27+
| Completion script wrong content | `src/completions.ts` | — |
28+
| Completion file written to wrong path | `src/completions.ts` (`getCompletionFilePath`) | env vars (`XDG_*`, `ZDOTDIR`) |
29+
| Completion not refreshed after upgrade | `src/upgrade.ts` (`refreshCompletions`) | — |
30+
| `--version` shows wrong info | `build.ts` (SHA injection) | — |
31+
| CLI option ignored or parsed wrong | `github-code-search.ts` | `src/types.ts` (`OutputType`) |
3232

3333
---
3434

@@ -50,18 +50,16 @@ If the report is missing items 1 or 3, read the relevant module(s) to hypothesis
5050

5151
## Test-first patterns for bugs
5252

53-
### Pure function bug (aggregate, group, output, render/*)
53+
### Pure function bug (aggregate, group, output, render/\*)
5454

5555
```typescript
5656
// src/aggregate.test.ts
5757
describe("applyFiltersAndExclusions — bug #N", () => {
5858
it("excludes org-prefixed repo names correctly", () => {
5959
const result = applyFiltersAndExclusions(matches, {
60-
excludeRepositories: ["acme/my-repo"], // the previously broken form
60+
excludeRepositories: ["acme/my-repo"], // the previously broken form
6161
});
62-
expect(result).not.toContainEqual(
63-
expect.objectContaining({ repo: "acme/my-repo" }),
64-
);
62+
expect(result).not.toContainEqual(expect.objectContaining({ repo: "acme/my-repo" }));
6563
});
6664
});
6765
```
@@ -95,6 +93,7 @@ Document manual repro steps in the PR description:
9593

9694
```markdown
9795
## Steps to reproduce (before fix)
96+
9897
1. `GITHUB_TOKEN=... github-code-search query "foo" --org acme`
9998
2. Press `↓` past the last result
10099
3. Expected: cursor stays on last row / Expected: wraps to first row

‎.github/skills/documentation.md‎

Lines changed: 59 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -9,22 +9,23 @@ This skill complements `.github/instructions/documentation.instructions.md` (the
99

1010
Custom components live in `docs/.vitepress/theme/`:
1111

12-
| File / folder | Role |
13-
| ------------------------ | -------------------------------------------------------------------- |
14-
| `index.ts` | Theme entry point — imports components and global CSS |
15-
| `custom.css` | All CSS overrides — brand colours, typography, responsive, a11y |
16-
| `Layout.vue` | Root layout wrapper (adds `RichFooter`, manages slot injection) |
17-
| `TerminalDemo.vue` | Animated terminal on the hero — `aria-hidden="true"` (decorative) |
18-
| `ComparisonTable.vue` | Feature comparison table with responsive 3-column layout |
19-
| `UseCaseTabs.vue` | WAI-ARIA Tabs pattern (roving tabindex, ArrowLeft/Right/Home/End) |
20-
| `InstallSection.vue` | Install command snippets with OS tabs |
21-
| `HowItWorks.vue` | 3-step explainer with responsive card layout |
22-
| `TestimonialsSection.vue`| Community testimonials carousel |
23-
| `ProductionCta.vue` | "Used in production?" CTA banner (`<section aria-labelledby="…">`) |
24-
| `VersionBadge.vue` | Release badge — reads `version` from `package.json` at build time |
25-
| `RichFooter.vue` | Custom footer replacing VitePress default |
12+
| File / folder | Role |
13+
| ------------------------- | ------------------------------------------------------------------ |
14+
| `index.ts` | Theme entry point — imports components and global CSS |
15+
| `custom.css` | All CSS overrides — brand colours, typography, responsive, a11y |
16+
| `Layout.vue` | Root layout wrapper (adds `RichFooter`, manages slot injection) |
17+
| `TerminalDemo.vue` | Animated terminal on the hero — `aria-hidden="true"` (decorative) |
18+
| `ComparisonTable.vue` | Feature comparison table with responsive 3-column layout |
19+
| `UseCaseTabs.vue` | WAI-ARIA Tabs pattern (roving tabindex, ArrowLeft/Right/Home/End) |
20+
| `InstallSection.vue` | Install command snippets with OS tabs |
21+
| `HowItWorks.vue` | 3-step explainer with responsive card layout |
22+
| `TestimonialsSection.vue` | Community testimonials carousel |
23+
| `ProductionCta.vue` | "Used in production?" CTA banner (`<section aria-labelledby="…">`) |
24+
| `VersionBadge.vue` | Release badge — reads `version` from `package.json` at build time |
25+
| `RichFooter.vue` | Custom footer replacing VitePress default |
2626

2727
**Extending a component:**
28+
2829
1. Locate the `.vue` file above.
2930
2. Follow the existing scoped `<style>` conventions (no global selectors inside `<style scoped>`).
3031
3. Add responsive styles inside the component's `<style>` or in `custom.css` if the rule is global.
@@ -36,17 +37,17 @@ Custom components live in `docs/.vitepress/theme/`:
3637

3738
Always use VitePress CSS variables — never hard-code colours in component `<style>` blocks:
3839

39-
| Variable | Meaning |
40-
| --------------------- | ------------------------------------ |
41-
| `--vp-c-brand-1` | Violet `#9933FF` / `#cc88ff` (dark) |
42-
| `--vp-c-brand-2` | Hover darkening |
43-
| `--vp-c-brand-soft` | Soft tint for backgrounds |
44-
| `--vp-c-text-1` | Primary text (≥ WCAG AA on bg) |
45-
| `--vp-c-text-2` | Secondary text (≥ WCAG AA on bg) |
46-
| `--vp-c-text-3` | **Do not use for text** — 2.87:1 contrast, fails WCAG AA |
47-
| `--vp-c-divider` | Border / separator |
48-
| `--vp-c-bg-soft` | Card / inset background |
49-
| `--vp-font-family-mono` | Monospace (code blocks) |
40+
| Variable | Meaning |
41+
| ----------------------- | -------------------------------------------------------- |
42+
| `--vp-c-brand-1` | Violet `#9933FF` / `#cc88ff` (dark) |
43+
| `--vp-c-brand-2` | Hover darkening |
44+
| `--vp-c-brand-soft` | Soft tint for backgrounds |
45+
| `--vp-c-text-1` | Primary text (≥ WCAG AA on bg) |
46+
| `--vp-c-text-2` | Secondary text (≥ WCAG AA on bg) |
47+
| `--vp-c-text-3` | **Do not use for text** — 2.87:1 contrast, fails WCAG AA |
48+
| `--vp-c-divider` | Border / separator |
49+
| `--vp-c-bg-soft` | Card / inset background |
50+
| `--vp-font-family-mono` | Monospace (code blocks) |
5051

5152
Dark mode: VitePress applies a `.dark` class on `<html>`. Use `.dark .selector { … }` — never `@media (prefers-color-scheme: dark)`.
5253

@@ -68,17 +69,17 @@ Config: `.pa11yci.json`. F77 (Mermaid duplicate SVG IDs) is ignored — not bloc
6869

6970
### Common patterns
7071

71-
| Pattern | Correct implementation |
72-
| ------------------------------------------ | ------------------------------------------------------------------ |
73-
| Landmark regions | `<section aria-labelledby="id">` + matching `id` on heading |
74-
| Icon-only buttons / links | `aria-label="Descriptive text"` |
75-
| Decorative images / SVG | `aria-hidden="true"` and no `alt` (or `alt=""`) |
76-
| External links (open in new tab) | `aria-label="Label (opens in a new tab)"` or `.sr-only` suffix |
77-
| Check / cross icons in tables | `aria-label="Yes"` / `aria-label="No"` |
78-
| Table column headers | `<th scope="col">` + `<caption class="sr-only">` on `<table>` |
79-
| Interactive tabs | Full WAI-ARIA Tabs: `role="tablist"`, `role="tab"`, `role="tabpanel"`, roving `tabindex`, keyboard nav |
80-
| Screen-reader-only text | `.sr-only` utility class defined in `custom.css` |
81-
| Focus visibility | `:focus-visible` ring defined globally in `custom.css` |
72+
| Pattern | Correct implementation |
73+
| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
74+
| Landmark regions | `<section aria-labelledby="id">` + matching `id` on heading |
75+
| Icon-only buttons / links | `aria-label="Descriptive text"` |
76+
| Decorative images / SVG | `aria-hidden="true"` and no `alt` (or `alt=""`) |
77+
| External links (open in new tab) | `aria-label="Label (opens in a new tab)"` or `.sr-only` suffix |
78+
| Check / cross icons in tables | `aria-label="Yes"` / `aria-label="No"` |
79+
| Table column headers | `<th scope="col">` + `<caption class="sr-only">` on `<table>` |
80+
| Interactive tabs | Full WAI-ARIA Tabs: `role="tablist"`, `role="tab"`, `role="tabpanel"`, roving `tabindex`, keyboard nav |
81+
| Screen-reader-only text | `.sr-only` utility class defined in `custom.css` |
82+
| Focus visibility | `:focus-visible` ring defined globally in `custom.css` |
8283

8384
### Contrast minimums (WCAG AA)
8485

@@ -96,12 +97,12 @@ This project maintains **zero horizontal overflow** across 4 tested viewports vi
9697

9798
### Tested viewports
9899

99-
| Label | Width | Height |
100-
| --------------- | ------ | ------ |
101-
| Galaxy S21 | 360px | 800px |
102-
| iPhone SE | 375px | 667px |
103-
| iPhone 14 | 390px | 844px |
104-
| Tablet portrait | 768px | 1024px |
100+
| Label | Width | Height |
101+
| --------------- | ----- | ------ |
102+
| Galaxy S21 | 360px | 800px |
103+
| iPhone SE | 375px | 667px |
104+
| iPhone 14 | 390px | 844px |
105+
| Tablet portrait | 768px | 1024px |
105106

106107
### Tool
107108

@@ -119,22 +120,29 @@ VitePress hides its hamburger at `≥768px` and shows desktop nav links — whic
119120

120121
```css
121122
@media (max-width: 960px) {
122-
.VPNavBarMenu, .VPNavBarExtra { display: none !important; }
123-
.VPNavBarHamburger { display: flex !important; }
123+
.VPNavBarMenu,
124+
.VPNavBarExtra {
125+
display: none !important;
126+
}
127+
.VPNavBarHamburger {
128+
display: flex !important;
129+
}
124130
}
125131
@media (min-width: 768px) and (max-width: 960px) {
126-
.VPNavScreen { display: block !important; }
132+
.VPNavScreen {
133+
display: block !important;
134+
}
127135
}
128136
```
129137

130138
### Responsive patterns for components
131139

132-
| Problem | Solution |
133-
| ------------------------------------------- | ------------------------------------------------------------ |
134-
| Table columns too wide on mobile | `table-layout: fixed`, abbreviated headers via `.ct-name-short` / `.ct-name-long` toggle |
135-
| Long feature descriptions push rows wider | `display: none` on `.ct-feature-desc` at `≤640px` |
136-
| Terminal/code blocks cause page scroll | `overflow-x: auto` on the scroll container, `max-width: 100%` on the block |
137-
| Long strings in `<pre>` overflow | `pre { max-width: 100%; overflow-x: auto; }` in `custom.css` |
140+
| Problem | Solution |
141+
| ----------------------------------------- | ---------------------------------------------------------------------------------------- |
142+
| Table columns too wide on mobile | `table-layout: fixed`, abbreviated headers via `.ct-name-short` / `.ct-name-long` toggle |
143+
| Long feature descriptions push rows wider | `display: none` on `.ct-feature-desc` at `≤640px` |
144+
| Terminal/code blocks cause page scroll | `overflow-x: auto` on the scroll container, `max-width: 100%` on the block |
145+
| Long strings in `<pre>` overflow | `pre { max-width: 100%; overflow-x: auto; }` in `custom.css` |
138146

139147
Never use `overflow-x: hidden` on the page root — it silently clips content. Apply it only to specific containers where clipping is intentional.
140148

0 commit comments

Comments
 (0)