49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
Use this repository as a conversion-focused toolchain with a small, testable core.
|
||
|
||
- `src/` contains the runnable implementation modules.
|
||
- `tests/` contains unit and integration tests for each converter path.
|
||
- `assets/` stores input/output fixtures used by tests and manual verification.
|
||
- `scripts/` contains one-off developer scripts (data migration, bootstrapping, local checks).
|
||
- `docs/` holds reference notes and usage examples.
|
||
- `tooling.toml` / `pyproject.toml` / `package.json` (if present) are the source of truth for local tooling.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `npm run lint` (or `pnpm lint` / `yarn lint`): format/lint project files before changes.
|
||
- `npm test` (or `python -m pytest`): run automated tests.
|
||
- `npm run build` (or `python -m build`): compile/transpile and package outputs if configured.
|
||
- `npm run dev` / local script: start the converter in development mode for manual smoke testing.
|
||
|
||
Run commands from repository root after installing dependencies.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Use 2-space indentation for JS/TS, 4-space for Python, and keep line length reasonable (100–120 chars).
|
||
- Use `kebab-case` for file names (`skill-schema-updater.py`, `convert-task.ts`), `snake_case` for Python variables/functions, and `camelCase` for JS/TS variables.
|
||
- Prefer clear action-oriented function names (`convert_markdown_to_skill`, `normalize_skill_entry`).
|
||
- Apply formatter/linter hooks before committing: `prettier`, `eslint`, `ruff`, or equivalent tool configured by the project.
|
||
|
||
## Testing Guidelines
|
||
- Primary frameworks: project defaults (`pytest`/`vitest`/`jest` as configured).
|
||
- Tests should validate: normal conversion, edge cases, and failure handling.
|
||
- Naming convention:
|
||
- Python: `tests/test_<feature>.py`
|
||
- JS/TS: `*.test.ts` or `*.spec.ts`
|
||
- Aim for meaningful coverage of converter logic and I/O parsing paths; add regression fixtures when fixing a bug.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Follow the existing project history if present; otherwise use Conventional Commits:
|
||
`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`.
|
||
- Keep commits scoped and one logical change per commit.
|
||
- PRs should include:
|
||
- Brief summary and testing evidence (`npm test` / `pytest`)
|
||
- Linked issue or rationale
|
||
- Before/after examples for behavior changes
|
||
- Screenshots only when output format/UI output changes.
|
||
|
||
## Security & Configuration Tips
|
||
- Never commit credentials, API keys, or raw user artifacts.
|
||
- Store secrets in local environment variables only.
|
||
- Add new config defaults conservatively and document any environment variable in `docs/`.
|