Agent Skills › open-circle/formisch › repo-source-code-review

repo-source-code-review

GitHub

用于审查 Formisch 库和框架的 PR 及源码，涵盖代码规范、类型安全、文档完整性及测试覆盖度验证，确保合并前符合项目标准。

.agents/skills/repo-source-code-review/SKILL.md open-circle/formisch

触发场景

审查修改库源码的 Pull Request 合并前验证实现模式与代码质量

安装

npx skills add open-circle/formisch --skill repo-source-code-review -g -y

更多选项

非标准路径

npx skills add https://github.com/open-circle/formisch/tree/main/.agents/skills/repo-source-code-review -g -y

不安装直接使用

npx skills use open-circle/formisch@repo-source-code-review

指定 Agent (Claude Code)

npx skills add open-circle/formisch --skill repo-source-code-review -a claude-code -g -y

安装 repo 全部 skill

npx skills add open-circle/formisch --all -g -y

预览 repo 内 skill

npx skills add open-circle/formisch --list

SKILL.md

Frontmatter

{
    "name": "repo-source-code-review",
    "metadata": {
        "author": "formisch",
        "version": "1.0"
    },
    "description": "Review PRs and source code changes in Formisch packages\/ and frameworks\/. Use when reviewing pull requests, validating implementation patterns, or checking code quality before merging."
}

Reviewing Source Code Changes

Guide for reviewing PRs and source code changes in packages/ and frameworks/.

When to Use This Guide

Reviewing pull requests modifying library source
Validating implementation patterns before merging
Checking code quality, types, documentation, and tests

Review Process

Understand the change — Read PR description, identify affected files
Check patterns — Verify code follows existing conventions
Verify types — Ensure type safety and proper inference
Review docs — Confirm JSDoc is complete and accurate
Check tests — Validate runtime and type test coverage

What to Review

Code Quality

Check	Requirement
Naming	Matches existing patterns (`FormStore`, `useField`, `createForm`)
Purity annotation	`// @__NO_SIDE_EFFECTS__` before pure factory functions
Import extensions	All imports use `.ts` extension
Interface vs type	Use `interface` for object shapes, `type` for unions/aliases
Folder structure	Methods: `name.ts`, `index.ts`. Primitives/components in their folder

Good — purity annotation:

// @__NO_SIDE_EFFECTS__
export function useField<TSchema, TFieldPath>(
  form: FormStore<TSchema>,
  config: UseFieldConfig<TSchema, TFieldPath>
): FieldStore<TSchema, TFieldPath> {
  return {
    /* ... */
  };
}

Bad — missing annotation:

export function useField<TSchema, TFieldPath>(
  form: FormStore<TSchema>,
  config: UseFieldConfig<TSchema, TFieldPath>
): FieldStore<TSchema, TFieldPath> {
  return {
    /* ... */
  };
}

Type Safety

Check	Requirement
Generic inference	Types infer correctly without explicit annotations
Constraints	Generic parameters have appropriate `extends` clauses
Return types	Explicit return types on exported functions
Type tests	`.test-d.ts` file covers type inference scenarios

Good — constrained generic:

export function useField<
  TSchema extends FormSchema,
  TFieldPath extends RequiredPath<TSchema>,
>(
  form: FormStore<TSchema>,
  config: UseFieldConfig<TSchema, TFieldPath>
): FieldStore<TSchema, TFieldPath>;

Documentation

Check	Requirement
JSDoc present	All exported functions have JSDoc
First line	Action verb matching function purpose (see below)
`@param` tags	Every parameter documented
`@returns` tag	Return value documented
Overloads	Every overload has its own complete JSDoc block

First line patterns by category:

Category	Pattern
Primitives	`Creates a ...`
Methods	`Focuses ...`, `Resets ...`, `Validates ...`
Components	`Renders a ...`
Utilities	`Returns ...`, `Gets ...`, `Sets ...`

Tests

Check	Requirement
Runtime tests	`.test.ts` covers success cases, failure cases, edge cases
Type tests	`.test-d.ts` validates type inference with `expectTypeOf`
Error handling	Tests verify correct error messages and validation

Common Issues

Issue	What to Look For
Missing purity annotation	Factory function without `// @__NO_SIDE_EFFECTS__`
Incomplete JSDoc	Missing `@param` or `@returns`, wrong description format
No type tests	New API without `.test-d.ts` file
Wrong import extension	Imports without `.ts` suffix
Inconsistent naming	Primitives not using `create`/`use` prefix, wrong Store suffix
Side effects in pure code	Mutations, I/O, or global state in primitive/method creation