39711d117c
- Stack and pin policy (Node 24, npm 11, 30-day dep aging) - Fork-specific convention: English commits (vs upstream-aligned) - Coverage ratchet at 8% (only goes up) - CI structure: Lint → Test → Security, build moved to release.yml - Pointers to docs/ARCHITECTURE, DEVELOPMENT, CONTRIBUTING - Sensitive areas flagged: fake-license shortcut in pro/account.ts, large untested files (main.ts, settings.ts, pro/sync.ts)
85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guia para Claude Code (claude.ai/code) trabalhar neste fork.
|
|
|
|
## Sobre o projeto
|
|
|
|
Fork de [`remotely-save/remotely-save`](https://github.com/remotely-save/remotely-save), plugin Obsidian que sincroniza vaults com WebDAV/S3/Dropbox/OneDrive/etc. Upstream com main branch parada desde 2024-11. Este fork retoma manutenção.
|
|
|
|
Detalhes técnicos completos em:
|
|
- `docs/ARCHITECTURE.md` — abstração `FakeFs`, fluxo de sync, state em IndexedDB
|
|
- `docs/DEVELOPMENT.md` — setup mise, comandos npm
|
|
- `docs/CONTRIBUTING.md` — workflow, convenções, política de cobertura
|
|
|
|
## Stack
|
|
|
|
- TypeScript 5.5 + Node 24.15.0 (pin via `mise.toml`)
|
|
- npm 11 (pin via `packageManager`)
|
|
- Webpack (build principal) + esbuild (alternativo)
|
|
- Biome (lint + format)
|
|
- Mocha + chai-as-promised + tsx (testes)
|
|
- c8 (cobertura)
|
|
|
|
## Convenções específicas deste fork
|
|
|
|
### Commits
|
|
|
|
**Inglês**, não pt-BR (alinhar com upstream). Imperativo, primeira letra maiúscula, ~72 caracteres na primeira linha. Corpo opcional com bullets `-`. Citar PR upstream quando aplicável (`based on upstream PR #1094`).
|
|
|
|
### Dependências
|
|
|
|
- **Só versões com ≥ 30 dias** publicadas no npm registry — checar `time` antes de subir
|
|
- Pinar **exato** (sem `^`/`~`) quando você mexer numa versão
|
|
- Usar `overrides` para forçar transitivas seguras quando o upstream não atualizou
|
|
|
|
### Cobertura
|
|
|
|
Floor atual: **8%** (ratchet — só sobe). Configurado em `package.json:scripts.test:coverage` com `c8 --check-coverage --lines=N`. Ao subir cobertura, atualizar `N` no script.
|
|
|
|
### Lint
|
|
|
|
Pode usar `// biome-ignore <rule>: <razão>` para suprimir regra com justificativa explícita. Sem suprimir silenciosamente.
|
|
|
|
### Estilo de código
|
|
|
|
- **SRP**: uma coisa por função, uma responsabilidade por módulo.
|
|
- **Nomes**: específicos e únicos. Evitar `data`, `handler`, `Manager`. Preferir nomes que retornem menos de 5 hits num grep do codebase.
|
|
- **Tipos**: explícitos. Sem `any`, sem `Dict`, sem funções sem tipo.
|
|
- **Funções**: ≤ 50 linhas. Dividir se passar.
|
|
- **Controle de fluxo**: early returns, no máximo 2 níveis de aninhamento.
|
|
- **Exceções**: incluir o valor ofensor e o formato esperado na mensagem.
|
|
|
|
## CI (`.github/workflows/ci.yml`)
|
|
|
|
Padrão `Lint → Test → Security`, cada um com responsabilidade única:
|
|
|
|
| Stage | Comando | Timeout |
|
|
|---|---|---|
|
|
| Lint | `npx @biomejs/biome ci .` | 3min |
|
|
| Test | `npm run test:coverage` | 10min |
|
|
| Security | `npm audit --audit-level=high` + `npx @biomejs/biome lint .` | 5min |
|
|
|
|
Build de produção fica em `release.yml` (não no CI de PR). Local: `npm run build`.
|
|
|
|
## Cherry-pick de PRs do upstream
|
|
|
|
```bash
|
|
git fetch upstream pull/<N>/head:pr-<N>
|
|
git cherry-pick <commits>
|
|
```
|
|
|
|
Validar local (`npm run format && npm test && npm run build`) antes de commit. Mencionar o PR no commit message.
|
|
|
|
## Cuidados ao mexer
|
|
|
|
- `pro/src/account.ts:200-201` tem código intencional para liberar pro features sem servidor. Não remover.
|
|
- `src/main.ts` (~2k LOC) e `src/settings.ts` (~3k LOC) são funções gigantes — refactors em passos pequenos.
|
|
- `pro/src/sync.ts:doActualSync` é o coração. **Sem testes** atualmente. Qualquer mudança aqui precisa teste novo.
|
|
- Backends `fs*.ts` seguem `FakeFs`. Não criar novo sem implementar a interface completa.
|
|
|
|
## Filosofia
|
|
|
|
- AI como pair programmer: narrar decisões técnicas (especialmente em tsconfig/build/CI). Perguntar em vez de assumir. Explicar trade-off.
|
|
- Mudança incremental: commits pequenos e bisect-friendly.
|
|
- Cada feature ou bugfix inclui teste.
|