Skip to content

Commit b23ce7c

Browse files
scopewuscopewu
committed
chore(AI): opencode init.
1 parent 84dc848 commit b23ce7c

File tree

1 file changed

+192
-0
lines changed

1 file changed

+192
-0
lines changed

‎AGENTS.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Agent Guidelines for qrcode.vue
2+
3+
This document provides guidelines for AI agents working on the qrcode.vue repository.
4+
It includes build/test commands, code style conventions, and project-specific patterns.
5+
6+
## Build and Development Commands
7+
8+
The project uses npm scripts defined in `package.json`:
9+
10+
| Command | Purpose |
11+
|---------|---------|
12+
| `npm run dev` | Start development server with hot reload (uses rsbuild) |
13+
| `npm run build` | Build production bundles using Rollup (generates CommonJS, ES module, UMD) |
14+
| `npm test` | Run all tests using rstest |
15+
| `npm run test -- --testNamePattern="pattern"` | Run tests matching pattern (rstest filter) |
16+
| `rstest test/index.test.ts` | Run a specific test file |
17+
18+
### Running a Single Test
19+
20+
To run a specific test or test file, use the rstest CLI directly:
21+
22+
```bash
23+
# Run a specific test file
24+
npx rstest test/index.test.ts
25+
26+
# Run tests matching a pattern (grep)
27+
npx rstest --testNamePattern="renders SVG"
28+
29+
# Run with coverage (if configured)
30+
npx rstest --coverage
31+
```
32+
33+
### Type Checking
34+
35+
The project uses TypeScript with strict mode enabled. Type checking is performed during the Rollup build for ES modules only (configured in `rollup.config.js`). To manually check types:
36+
37+
```bash
38+
npx tsc --noEmit
39+
```
40+
41+
## Code Style Guidelines
42+
43+
### Indentation and Formatting
44+
45+
- **Indentation**: 2 spaces (no tabs) – enforced by `.editorconfig`
46+
- **Line endings**: LF (Unix)
47+
- **Trailing whitespace**: Trimmed
48+
- **Final newline**: Yes (except for *.md files)
49+
50+
### TypeScript Conventions
51+
52+
- **Strict mode**: Always enabled (`strict: true` in tsconfig)
53+
- **Type annotations**: Prefer explicit types for function parameters and return types
54+
- **Interfaces vs Types**: Use `type` for simple aliases, `interface` for object shapes that may be extended (observe existing patterns)
55+
- **Import style**: Use ES6 imports; group Vue imports first, then local imports
56+
57+
Example from `src/index.ts`:
58+
```ts
59+
import { defineComponent, Fragment, h, onMounted, onUpdated, PropType, ref } from 'vue'
60+
import QR from './qrcodegen'
61+
```
62+
63+
### Naming Conventions
64+
65+
- **Component names**: PascalCase (e.g., `QrcodeVue`, `QrcodeSvg`, `QrcodeCanvas`)
66+
- **Variable/function names**: camelCase
67+
- **Constants**: UPPER_SNAKE_CASE for true constants, otherwise camelCase
68+
- **Type parameters**: Single uppercase letters (e.g., `T`, `U`)
69+
- **Private fields**: No special prefix; TypeScript's `private` modifier or naming convention `_private` is not used
70+
71+
### Vue Component Patterns
72+
73+
- Use Composition API with `defineComponent`
74+
- Props defined as objects with type annotations using `PropType`
75+
- Reactive state managed with `ref` and `computed`
76+
- Lifecycle hooks: `onMounted`, `onUpdated`, etc.
77+
- Render function using `h()` (hyperscript) – no template DSL
78+
- Component `name` property set to PascalCase string
79+
80+
Example prop definition:
81+
```ts
82+
const QRCodeProps = {
83+
value: {
84+
type: String,
85+
required: true,
86+
default: '',
87+
},
88+
size: {
89+
type: Number,
90+
default: 100,
91+
},
92+
// ...
93+
}
94+
```
95+
96+
### Error Handling
97+
98+
- Use `throw new RangeError` for invalid arguments (see `qrcodegen.ts`)
99+
- Validate props with validator functions
100+
- Graceful fallbacks for unsupported browser features (e.g., `Path2D` detection)
101+
102+
### Imports Order
103+
104+
1. Vue framework imports
105+
2. Third‑party libraries
106+
3. Local modules (relative paths)
107+
108+
### Semicolons
109+
110+
The codebase uses semicolons inconsistently. Follow the existing file's style:
111+
- `qrcodegen.ts` uses semicolons consistently (legacy TypeScript/JavaScript)
112+
- `index.ts` uses semicolons mostly for statements but not after function declarations
113+
114+
When in doubt, match the surrounding code.
115+
116+
## Testing
117+
118+
- Tests are written with `@rstest/core` and `@vue/test-utils`
119+
- Test files are in `test/` directory with `.test.ts` extension
120+
- Use `describe`/`it` pattern
121+
- Mount components with `mount()` from `@vue/test-utils`
122+
- Assertions use `expect()` from `@rstest/core`
123+
124+
Example test:
125+
```ts
126+
import { describe, expect, it } from '@rstest/core'
127+
import { mount } from '@vue/test-utils'
128+
import QrcodeVue from '../src'
129+
130+
describe('QrcodeVue', () => {
131+
it('renders correctly with default props', () => {
132+
const wrapper = mount(QrcodeVue, {
133+
props: { value: 'test' },
134+
})
135+
expect(wrapper.html()).toContain('<canvas')
136+
})
137+
})
138+
```
139+
140+
## Build Configuration
141+
142+
- **Rollup**: Bundles library for CommonJS, ES module, and UMD (see `rollup.config.js`)
143+
- **Rsbuild**: Used for development and example building (see `rsbuild.config.js`)
144+
- **TypeScript**: Configuration in `tsconfig.json` (minimal, strict)
145+
- **No separate linting tool** (rely on TypeScript strict checks and editorconfig)
146+
147+
## Project Structure
148+
149+
```
150+
src/
151+
index.ts # Main Vue component (exports QrcodeVue, QrcodeSvg, QrcodeCanvas)
152+
qrcodegen.ts # QR code generator library (external, minimally modified)
153+
test/
154+
index.test.ts # Component tests
155+
example/ # Demo application
156+
webpack-entry.ts # Entry point for dev server
157+
webpack.html # HTML template
158+
styles.scss # Demo styles
159+
typings/ # TypeScript declarations
160+
dist/ # Built artifacts (ignored in git)
161+
```
162+
163+
## Quality Assurance
164+
165+
- After making changes, run `npm run build` to ensure the library builds successfully.
166+
- Run `npm test` to ensure all tests pass.
167+
- Consider running `npx tsc --noEmit` to verify TypeScript strictness.
168+
- There are no Cursor (`/.cursor/`) or Copilot (`/.github/copilot-instructions.md`) rules in this repository.
169+
170+
## Notes for Agents
171+
172+
- This is a Vue 3 component library; ensure compatibility with Vue 3's API
173+
- The QR code generator (`qrcodegen.ts`) is a third‑party library (Project Nayuki) – avoid modifications unless absolutely necessary
174+
- The component supports both canvas and SVG rendering, with gradient and image overlay features
175+
- When adding new props, maintain the existing prop definition pattern and include appropriate validators
176+
- Ensure any changes work for both Vue 2 and Vue 3 (the library claims support for both, but check peerDependencies)
177+
178+
## Commit Guidelines
179+
180+
- Use conventional commit messages (feat, fix, chore, docs, test, etc.)
181+
- Reference GitHub issues when applicable
182+
- Keep commits focused; one logical change per commit
183+
184+
## Resources
185+
186+
- [Vue 3 Composition API](https://vuejs.org/guide/extras/composition-api-faq)
187+
- [Rollup documentation](https://rollupjs.org/)
188+
- [rstest documentation](https://github.com/rsuite/rstest)
189+
- [QR Code Generator Library](https://www.nayuki.io/page/qr-code-generator-library)
190+
191+
---
192+
*This file was generated for agentic coding assistants. Update it as the project evolves.*

0 commit comments

Comments
 (0)