Skip to content

Commit 9f888ac

Browse files
chilinglingchilingling
authored
feat: add basic instruction for coding agents (opentiny#1793)
1 parent e35908b commit 9f888ac

4 files changed

Lines changed: 258 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# TinyEngine — Repository Instructions for Coding Agents
2+
3+
## Purpose and Scope
4+
5+
This file is the canonical source of truth for repo-wide agent instructions.
6+
7+
- Applies to the whole repository unless a closer `AGENTS.md` overrides it for a subtree.
8+
- `CLAUDE.md` is a compatibility entrypoint that imports this file. Do not maintain a second independent copy of the same rules.
9+
- Keep this file limited to repo-wide guidance. Package-specific implementation details belong in package-level instruction files.
10+
11+
## Repository Snapshot
12+
13+
- Monorepo: pnpm workspaces + lerna (independent versioning)
14+
- Primary stack: Vue 3, Vite, JavaScript/TypeScript
15+
- Package manager: `pnpm` only for interactive work in this repo
16+
- Designer app: `designer-demo/`
17+
- Local mock backend: `mockServer/`
18+
19+
## Working Model
20+
21+
- Inspect the affected package, its `package.json`, and the nearest instruction file before editing.
22+
- Keep changes scoped. Do not normalize unrelated files or rename fixtures just for consistency.
23+
- Prefer targeted package-level validation over whole-repo commands when possible.
24+
- Treat `pnpm lint` and `pnpm format` as mutating commands, not read-only verification.
25+
- Do not invoke `npm` or `yarn` directly for normal repo work. Existing package scripts may still shell out internally; leave that alone unless the task is specifically about package scripts.
26+
27+
## Common Commands
28+
29+
### Read-mostly commands
30+
31+
```sh
32+
pnpm install
33+
pnpm dev
34+
pnpm build:plugin
35+
pnpm build:alpha
36+
pnpm --filter @opentiny/tiny-engine-dsl-vue test:unit
37+
```
38+
39+
### Mutating commands
40+
41+
```sh
42+
pnpm lint # ESLint with --fix
43+
pnpm format # Prettier --write
44+
```
45+
46+
Canonical script definitions live in:
47+
48+
- `package.json`
49+
- `packages/*/package.json`
50+
- `.github/workflows/push-check.yml`
51+
- `.github/workflows/Release.yml`
52+
53+
## Verification Matrix
54+
55+
Run the smallest sufficient verification for the change surface, then expand if the change is broad or risky.
56+
57+
1. Docs-only changes:
58+
No code verification required unless the docs change commands or workflow descriptions that should be checked against source files.
59+
2. `packages/vue-generator/**`:
60+
Run the affected testcase or `pnpm --filter @opentiny/tiny-engine-dsl-vue test:unit`.
61+
If generator behavior changes, run the full `test:unit` suite before handoff and inspect any changed `expected/*.vue` files.
62+
3. Published library packages under `packages/**`:
63+
Run the package-local `test` script if one exists.
64+
Run `pnpm build:plugin` when build output or published package behavior may be affected.
65+
4. `designer-demo/**` or shared packages consumed by the demo:
66+
Run `pnpm build:alpha`.
67+
5. Cross-package build or release-facing changes:
68+
Run `pnpm build:plugin` and `pnpm build:alpha`.
69+
6. Config, workspace, CI, or release script changes:
70+
Verify the directly affected command(s) after approval.
71+
72+
## Approval Boundaries
73+
74+
### Always OK
75+
76+
- Read any source file
77+
- Run targeted tests and builds
78+
- Edit implementation files inside existing packages
79+
- Add or update tests that match the scope of the change
80+
- Update docs that reflect current repo behavior
81+
82+
### Ask First
83+
84+
- Changing workspace, lerna, pnpm, ESLint, Prettier, or TypeScript configuration
85+
- Modifying CI workflows, release scripts, or publish flows
86+
- Upgrading major dependencies or changing pinned overrides
87+
- Reordering or adding/removing default vue-generator attribute hooks
88+
- Large-scale edits to generated mappings or vendored patches
89+
90+
When asking first, include:
91+
92+
- what you want to change
93+
- why the current rules or implementation are insufficient
94+
- what verification you would run after approval
95+
96+
### Never
97+
98+
- Use `npm` or `yarn` directly for routine repo commands
99+
- Skip hooks with `--no-verify`
100+
- Hardcode versions for workspace packages
101+
- Edit `patches/` without understanding the upstream issue and the patch purpose
102+
- Rewrite generated expectations or snapshots without validating the new output first
103+
104+
## Task-Specific Expectations
105+
106+
- Bug fix:
107+
Add or update a regression test when behavior changes.
108+
- Refactor:
109+
Preserve behavior and prove it with targeted verification.
110+
- Snapshot or generated output change:
111+
Explain why the output changed and list the affected fixture directories.
112+
- Commit or PR work:
113+
Only do it if asked. Use Conventional Commits and target `develop` unless the user specifies otherwise.
114+
115+
## Gotchas
116+
117+
- `pnpm install` is enforced by `preinstall`; npm and yarn are rejected for direct repo usage.
118+
- `pnpm lint` writes fixes. Use it deliberately.
119+
- CI relies on `build:plugin` and `build:alpha`, not only lint or unit tests.
120+
- Test directories such as `test/`, `expected/`, and `output/` are not always linted; do not treat lint success as fixture validation.

‎CLAUDE.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# TinyEngine — Claude Code Entry
2+
3+
This file is intentionally thin. The canonical repo-wide instructions live in `AGENTS.md`.
4+
5+
@./AGENTS.md
6+
7+
When working inside a subtree that has its own `CLAUDE.md`, follow the closer file as an extension of these repo-wide rules.

‎packages/vue-generator/AGENTS.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# TinyEngine vue-generator — Package Instructions
2+
3+
## Scope
4+
5+
This file applies to `packages/vue-generator/**`.
6+
7+
- These rules extend the repo-wide rules in the root `AGENTS.md`.
8+
- Keep package-specific generator details here instead of growing the root file.
9+
10+
## Package Goal
11+
12+
`@opentiny/tiny-engine-dsl-vue` converts TinyEngine DSL schema JSON plus components map JSON into Vue single-file components.
13+
14+
This package is responsible for code generation output. Runtime behavior, designer-side execution, and app-level integration fixes should stay in their owning packages unless the generated SFC output is wrong.
15+
16+
## Key Paths
17+
18+
- `src/generator/vue/sfc/genSetupSFC.js`
19+
- `src/generator/vue/sfc/generateAttribute.js`
20+
- `src/generator/vue/sfc/generateTemplate.js`
21+
- `src/generator/vue/sfc/generateScript.js`
22+
- `src/generator/vue/sfc/generateStyle.js`
23+
- `src/utils/formatCode.js`
24+
- `test/testcases/sfc/`
25+
- `test/testcases/element-plus-case/`
26+
- `test/testcases/generator/`
27+
28+
## Architecture Rules
29+
30+
### Core pipeline
31+
32+
1. Input: schema JSON plus components map JSON
33+
2. `CodeGenerator` hook pipeline: `transformStart` -> `transform` -> `transformEnd`
34+
3. `genSetupSFC` orchestrates template, attribute, script, and style generation
35+
4. Output: a complete `.vue` SFC
36+
37+
### Default attribute hook order
38+
39+
The default hook chain registered in `genSetupSFC.js` executes in this order:
40+
41+
1. `handleSlotParams`
42+
2. `handleJsxModelValueUpdate`
43+
3. `handleConditionAttrHook`
44+
4. `handleLoopAttrHook`
45+
5. `handleSlotBindAttrHook`
46+
6. `handleAttrKeyHook`
47+
7. `handlePrimitiveAttributeHook`
48+
8. `handleExpressionAttrHook`
49+
9. `handleJSFunctionAttrHook`
50+
10. `handleI18nAttrHook`
51+
11. `handleTinyIconPropsHook`
52+
12. `handleObjBindAttrHook`
53+
13. `handleEventAttrHook`
54+
55+
`handleBindUtilsHooks` still exists in `generateAttribute.js`, but it is not part of the default hook chain.
56+
57+
Do not reorder or change the default hook chain without approval.
58+
59+
### Global hooks
60+
61+
`genSetupSFC.js` exposes shared `globalHooks` helpers:
62+
63+
- `addState(key, value)`
64+
- `addImport(fromPath, config)`
65+
- `addMethods(key, value)`
66+
- `addStatement(statement)`
67+
- `setScriptConfig(config)`
68+
69+
These helpers mutate shared script-generation state. When debugging generated `<script>` output, imports, methods, or script config, inspect `genSetupSFC.js` and the downstream script generation path before adding new hooks.
70+
71+
### Quote-handling rules
72+
73+
- Primitive string attributes containing `"` may be emitted as `&quot;` or as a `v-bind` string literal, depending on whether the content also contains `'`.
74+
- JSX slot mode is a separate path; do not assume primitive attribute escaping rules apply there unchanged.
75+
- Quote behavior is sensitive to Prettier reformatting. Validate final formatted output, not only intermediate strings.
76+
- When debugging quote output, inspect `generateAttribute.js` first and verify the formatted `.vue` result rather than raw intermediate strings.
77+
78+
## Fixture and Snapshot Workflow
79+
80+
- SFC cases live under `test/testcases/sfc/<caseName>/`.
81+
- Follow the nearest existing fixture style. Valid schema names include `schema.json`, `page.schema.json`, `block.schema.json`, and `blocks.schema.json`.
82+
- Components maps may be `components-map.json` or `componentsMap.json`.
83+
- Expected outputs live in `expected/*.vue` and are compared with `toMatchFileSnapshot()` after `formatCode(res, 'vue')`.
84+
- Test entry files typically follow `test/testcases/sfc/<caseName>/<caseName>.test.js`.
85+
86+
When generator output intentionally changes:
87+
88+
1. Update or add the smallest focused testcase that exposes the behavior.
89+
2. Keep new fixtures minimal and isolate a single behavior whenever possible.
90+
3. Regenerate or inspect the formatted output for that testcase.
91+
4. Update only the affected `expected/*.vue` files.
92+
5. Rerun the targeted testcase and then the full `test:unit` suite.
93+
94+
Do not bulk-rename fixture files just to normalize naming.
95+
96+
## Verification
97+
98+
Use the narrowest command that proves the change, then broaden as needed.
99+
100+
- Single testcase:
101+
`pnpm --filter @opentiny/tiny-engine-dsl-vue test:unit -- --run test/testcases/sfc/<case>/<case>.test.js`
102+
- Full unit suite:
103+
`pnpm --filter @opentiny/tiny-engine-dsl-vue test:unit`
104+
- Full coverage harness:
105+
`pnpm --filter @opentiny/tiny-engine-dsl-vue test`
106+
- Build plus integration-style check:
107+
`pnpm --filter @opentiny/tiny-engine-dsl-vue test:latest`
108+
109+
Run the full `test:unit` suite before handoff if a change touches shared attribute generation, hook registration, script/style/template generation, or output formatting.
110+
111+
Use `test` or `test:latest` when the change affects broad generator behavior, package build output, or integration between generation and package build steps.
112+
113+
## Ask First
114+
115+
- Changing the default hook chain in `genSetupSFC.js`
116+
- Editing `src/constant/index.js`
117+
- Changing package build tooling or package scripts
118+
- Changing shared quote-generation behavior across multiple attribute paths
119+
- Changing quote-generation behavior before adding a focused testcase that proves the intended output
120+
121+
## Never
122+
123+
- Update `expected/*.vue` without validating the formatted generator output first
124+
- Bypass `formatCode(res, 'vue')` when comparing expected SFC output
125+
- Assume one fixture naming convention is canonical across the whole package
126+
- Treat a snapshot diff by itself as proof that generated behavior is correct

‎packages/vue-generator/CLAUDE.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# TinyEngine vue-generator — Claude Code Entry
2+
3+
This file is intentionally thin. The canonical package-specific instructions live in `AGENTS.md`.
4+
5+
@./AGENTS.md

0 commit comments

Comments
 (0)