Skip to content

Commit 2ad6f1c

Browse files
fabian-hillerfabian-hiller
committed
Merge branch 'main' into i18n-greek
2 parents 62a94d7 + 3db4e9b commit 2ad6f1c

563 files changed

Lines changed: 42777 additions & 13744 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/repo-source-code-document/SKILL.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
---
2+
name: repo-source-code-document
3+
description: Write JSDoc comments and inline documentation for Valibot library source code in /library/src/. Use when documenting schemas, actions, methods, or utilities. Covers interface documentation, function overloads, purity annotations, inline comment patterns, and terminology consistency.
4+
---
5+
6+
# Valibot Source Code Documentation
7+
8+
Documentation patterns for library source code in `/library/src/`.
9+
10+
## JSDoc Patterns
11+
12+
### Interface Documentation
13+
14+
```typescript
15+
/**
16+
* String issue interface.
17+
*/
18+
export interface StringIssue extends BaseIssue<unknown> {
19+
/**
20+
* The issue kind.
21+
*/
22+
readonly kind: 'schema';
23+
/**
24+
* The issue type.
25+
*/
26+
readonly type: 'string';
27+
}
28+
```
29+
30+
**Rules:**
31+
32+
- First line: `[Name] [category] interface.` (e.g., "String issue interface.")
33+
- Property comments: `The [description].` (always start with "The", end with period)
34+
- All properties use `readonly`
35+
- No blank lines between property and its comment
36+
37+
### Function Overloads
38+
39+
Each overload gets its own complete JSDoc:
40+
41+
```typescript
42+
/**
43+
* Creates a string schema.
44+
*
45+
* @returns A string schema.
46+
*/
47+
export function string(): StringSchema<undefined>;
48+
49+
/**
50+
* Creates a string schema.
51+
*
52+
* @param message The error message.
53+
*
54+
* @returns A string schema.
55+
*/
56+
export function string<
57+
const TMessage extends ErrorMessage<StringIssue> | undefined,
58+
>(message: TMessage): StringSchema<TMessage>;
59+
```
60+
61+
**Rules:**
62+
63+
- First line: `Creates a [name] [category].` (use "a" vs "an" correctly)
64+
- Blank line after description
65+
- `@param name The [description].` (start with "The", end with period)
66+
- Blank line after params
67+
- `@returns A [name] [category].` or `@returns The [description].`
68+
69+
### Hints
70+
71+
Add hints after the main description, before `@param`:
72+
73+
```typescript
74+
/**
75+
* Creates an object schema.
76+
*
77+
* Hint: This schema removes unknown entries. To include unknown entries, use
78+
* `looseObject`. To reject unknown entries, use `strictObject`.
79+
*
80+
* @param entries The entries schema.
81+
*
82+
* @returns An object schema.
83+
*/
84+
```
85+
86+
### Links
87+
88+
Link to external resources when relevant using markdown format:
89+
90+
```typescript
91+
/**
92+
* Creates an [email](https://en.wikipedia.org/wiki/Email_address) validation action.
93+
*/
94+
```
95+
96+
### Implementation Function
97+
98+
The implementation has **NO JSDoc** but uses `// @__NO_SIDE_EFFECTS__`:
99+
100+
```typescript
101+
// @__NO_SIDE_EFFECTS__
102+
export function string(
103+
message?: ErrorMessage<StringIssue>
104+
): StringSchema<ErrorMessage<StringIssue> | undefined> {
105+
return {
106+
/* ... */
107+
};
108+
}
109+
```
110+
111+
**`// @__NO_SIDE_EFFECTS__` rules:**
112+
113+
- Add for pure functions (no external state mutation, no I/O)
114+
- Most schema/action/method factories are pure
115+
- **Do NOT add** for functions that mutate arguments (like `_addIssue`)
116+
- Used by bundlers for tree-shaking
117+
118+
### Utility Functions
119+
120+
```typescript
121+
/**
122+
* Stringifies an unknown input to a literal or type string.
123+
*
124+
* @param input The unknown input.
125+
*
126+
* @returns A literal or type string.
127+
*
128+
* @internal
129+
*/
130+
// @__NO_SIDE_EFFECTS__
131+
export function _stringify(input: unknown): string {
132+
// ...
133+
}
134+
```
135+
136+
**Rules:**
137+
138+
- Use `@internal` tag for internal utilities
139+
- Prefix internal functions with `_`
140+
- Only add `// @__NO_SIDE_EFFECTS__` if function is pure
141+
142+
## Inline Comment Patterns
143+
144+
### Section Headers
145+
146+
```typescript
147+
'~run'(dataset, config) {
148+
// Get input value from dataset
149+
const input = dataset.value;
150+
151+
// If root type is valid, check nested types
152+
if (Array.isArray(input)) {
153+
// Set typed to true and value to empty array
154+
dataset.typed = true;
155+
dataset.value = [];
156+
157+
// Parse schema of each array item
158+
for (let key = 0; key < input.length; key++) {
159+
// ...
160+
}
161+
}
162+
}
163+
```
164+
165+
**Rules:**
166+
167+
- Describe WHAT the next code block does
168+
- Present tense verbs: "Get", "Parse", "Check", "Set", "Add", "Create"
169+
- **Omit articles** ("the", "a", "an"): "Get input value" not "Get the input value"
170+
- No period at end
171+
- Blank line before comment, no blank line after
172+
173+
### Conditional Logic
174+
175+
```typescript
176+
// If root type is valid, check nested types
177+
if (input && typeof input === 'object') {
178+
// ...
179+
}
180+
181+
// Otherwise, add issue
182+
else {
183+
_addIssue(this, 'type', dataset, config);
184+
}
185+
```
186+
187+
**Rules:**
188+
189+
- Use "If [condition], [action]"
190+
- Use "Otherwise, [action]" for else branches
191+
- Omit articles
192+
193+
### Hint Comments (Exception)
194+
195+
```typescript
196+
// Hint: The issue is deliberately not constructed with the spread operator
197+
// for performance reasons
198+
const issue: BaseIssue<unknown> = {
199+
/* ... */
200+
};
201+
```
202+
203+
**Rules:**
204+
205+
- Start with "Hint:"
206+
- Explain WHY, not just what
207+
- **CAN use articles** (unlike other inline comments)
208+
- Document performance decisions, non-obvious logic
209+
210+
### TODO Comments
211+
212+
```typescript
213+
// TODO: Should we add "n" suffix to bigints?
214+
if (type === 'bigint') {
215+
/* ... */
216+
}
217+
```
218+
219+
### @ts-expect-error
220+
221+
Used for internal dataset mutations TypeScript can't track:
222+
223+
```typescript
224+
// @ts-expect-error
225+
dataset.typed = true;
226+
```
227+
228+
## File Type Patterns
229+
230+
### Schema Files (`string.ts`, `object.ts`, etc.)
231+
232+
1. Issue interface with JSDoc
233+
2. Schema interface with JSDoc
234+
3. Function overloads with full JSDoc each
235+
4. Implementation with `// @__NO_SIDE_EFFECTS__`
236+
5. Return object with `'~run'` method containing inline comments
237+
238+
### Action Files (`email.ts`, `minLength.ts`, etc.)
239+
240+
1. Issue interface (for validation actions)
241+
2. Action interface with JSDoc
242+
3. Function overloads with JSDoc
243+
4. Implementation with `// @__NO_SIDE_EFFECTS__`
244+
245+
### Method Files (`parse.ts`, `pipe.ts`, etc.)
246+
247+
More complex logic, require more inline comments.
248+
249+
### Utility Files (`_addIssue.ts`, `_stringify.ts`)
250+
251+
1. Single function with JSDoc including `@internal`
252+
2. `// @__NO_SIDE_EFFECTS__` only if pure
253+
254+
## Terminology Consistency
255+
256+
JSDoc descriptions must match the `kind` property if present:
257+
258+
| `kind` Property | JSDoc Wording |
259+
| ------------------ | -------------------------------------- |
260+
| `'schema'` | "Creates a ... schema." |
261+
| `'validation'` | "Creates a ... validation action." |
262+
| `'transformation'` | "Creates a ... transformation action." |
263+
264+
## Quick Reference
265+
266+
### JSDoc First Lines
267+
268+
| Type | Pattern |
269+
| --------- | ------------------------------ |
270+
| Interface | `[Name] [category] interface.` |
271+
| Type | `[Name] [category] type.` |
272+
| Function | `Creates a [name] [category].` |
273+
| Utility | `[Verb]s [description].` |
274+
275+
### Inline Comment Starters
276+
277+
| Pattern | Example |
278+
| ------------------------------ | ---------------------------------------------- |
279+
| `// Get [what]` | `// Get input value from dataset` |
280+
| `// If [condition], [action]` | `// If root type is valid, check nested types` |
281+
| `// Otherwise, [action]` | `// Otherwise, add issue` |
282+
| `// Create [what]` | `// Create object path item` |
283+
| `// Add [what] to [where]` | `// Add issues to dataset` |
284+
| `// Parse [what]` | `// Parse schema of each array item` |
285+
| `// Set [property] to [value]` | `// Set typed to true` |
286+
| `// Hint: [explanation]` | `// Hint: This is for performance` |
287+
| `// TODO: [task]` | `// TODO: Add bigint suffix` |
288+
289+
## Terminology
290+
291+
Use consistently:
292+
293+
- **Schema** (not "validator")
294+
- **Action** (not "validation" for the object)
295+
- **Issue** (not "error" in type names)
296+
- **Dataset** (internal data structure)
297+
- **Config/Configuration** (not "options")
298+
299+
## Checklist
300+
301+
- [ ] Interfaces: `[Name] [category] interface.`
302+
- [ ] Properties: `The [description].`
303+
- [ ] Overloads: Complete JSDoc each
304+
- [ ] Implementation: NO JSDoc
305+
- [ ] Pure functions: `// @__NO_SIDE_EFFECTS__`
306+
- [ ] Impure functions (mutate args): NO `@__NO_SIDE_EFFECTS__`
307+
- [ ] Internal utilities: `@internal` tag
308+
- [ ] Inline comments: No articles (except Hint), no periods
309+
- [ ] JSDoc comments: End with periods

0 commit comments

Comments
 (0)