@acropole/skills 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +180 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,140 @@
1
+ # Rotas, validação, envelope e erros
2
+
3
+ Semântica completa de `@operation`, `Level`, `Method`, claims e auditoria: **orfeu**. Aqui só o
4
+ uso dentro do padrão do serviço.
5
+
6
+ ## Convenção de rotas
7
+
8
+ - Um `APIRouter(prefix="/<recurso>", tags=["<Recurso>"])` por domínio; o prefixo global
9
+ (`/<projeto>/server`) vem do `include_router(..., prefix=settings.api_prefix)` no `main.py`.
10
+ - Recursos no plural, kebab ou palavra única: `/tags`, `/catalog/products`, `/teams/{team_id}/members`.
11
+ - Coleção sem barra final: `@router.get("")`, não `"/"`.
12
+ - Verbos: `GET` lista/detalhe, `POST` cria (201), `PATCH` edição parcial, `DELETE` remove. `PUT` só se
13
+ a semântica for substituição completa.
14
+ - Ids de path tipados (`tag_id: UUID`) — o FastAPI devolve 422 sozinho para valor inválido.
15
+ - Query params com nome reservado do Python: use `Query(alias="from")` em vez de expor `from_` na URL.
16
+
17
+ ## `@operation`
18
+
19
+ ```python
20
+ @router.patch("/{tag_id}", response_model=Envelope[TagOut]) # 1º: decorator da rota
21
+ @operation(id="tags:update", level=Level.PROTECTED) # 2º: logo abaixo
22
+ def update_tag(tag_id: UUID, body: TagUpdate, db: Session = Depends(get_db)):
23
+ return ok(TagService(db).update(tag_id, body.name), "Tag atualizada.")
24
+ ```
25
+
26
+ - Ordem: o decorator da rota por **cima**, `@operation` por **baixo** (é aplicado primeiro, sobre a
27
+ função crua).
28
+ - `id` = `"<domínio>:<ação>"` ou `"<domínio>:<sub>:<ação>"` (`catalog:teams:members:assign`). É a chave
29
+ da permissão no Argos: não renomeie à toa.
30
+ - Sem `method=`, o nome da função define o método (`list_*`/`get_*` leitura, `delete_*` remoção, resto
31
+ escrita...). Os serviços existentes dependem dessa inferência; em código novo passe
32
+ `method=Method.READ/WRITE/DELETE` explícito (regra da orfeu) e, mesmo assim, dê nomes que
33
+ reflitam a ação.
34
+ - `@operation` precisa ficar sobre a função que o FastAPI registra: wrapper intermediário sem
35
+ `functools.wraps` apaga os atributos e a rota fica **aberta sem aviso**.
36
+ - Leituras de catálogo para qualquer autenticado: `Level.PRIVATE`; ações administrativas:
37
+ `Level.PROTECTED`; leitura que muda de comportamento com/sem usuário: `Level.OPTIONAL`
38
+ (`request.state.user` pode ser `None`). Confirme na orfeu.
39
+ - Rotas sem `@operation` são públicas. Só `/health` (e afins) deve ficar assim.
40
+
41
+ ## Schemas Pydantic
42
+
43
+ ```python
44
+ class TagCreate(BaseModel):
45
+ name: str
46
+
47
+ class TagOut(BaseModel):
48
+ model_config = ConfigDict(from_attributes=True) # aceita o objeto ORM direto
49
+ tag_id: UUID
50
+ name: str
51
+ created_at: datetime
52
+ ```
53
+
54
+ - Entrada: `*Create`/`*Update` (ou `*In`/`*Patch`). Em `*Patch`/`*Update` parcial, todos os campos
55
+ `Optional[...] = None` e o service só aplica o que veio.
56
+ - Saída: `*Out` com `from_attributes=True`, ou um `@classmethod from_model(cls, model)` quando o
57
+ formato difere da tabela (ex.: `id=str(model.product_id)`).
58
+ - Normalização/validação de campo com `field_validator` (ex.: `strip()` e recusa de vazio). Um
59
+ `ValueError` vira 422 no envelope com a mensagem dele.
60
+ - **camelCase na borda** (divergência entre serviços: um responde `snake_case`, outro `camelCase`).
61
+ Recomendado: base comum em `app/shared/schemas.py` e alinhar com o gateway (apollo):
62
+
63
+ ```python
64
+ from pydantic import BaseModel, ConfigDict
65
+ from pydantic.alias_generators import to_camel
66
+
67
+ class CamelModel(BaseModel):
68
+ model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
69
+ ```
70
+
71
+ Com `response_model=Envelope[XOut]`, o FastAPI serializa por alias (camelCase) por padrão.
72
+ Decida um formato por serviço e não misture.
73
+
74
+ ## Envelope de resposta
75
+
76
+ Toda resposta (sucesso e erro) é `{"status": int, "message": str, "data": ...}`:
77
+
78
+ | Situação | Como | Corpo |
79
+ |---|---|---|
80
+ | Leitura | `return ok(dado)` | `{"status":200,"message":"","data":...}` |
81
+ | Escrita | `return ok(dado, "Tag atualizada.")` | mensagem pronta para toast |
82
+ | Criação | `status_code=201` no decorator **e** `ok(dado, "Tag criada.", 201)` | `status` 201 nos dois |
83
+ | Remoção | `return ok(id_removido, "Tag removida.")` + `response_model=Envelope[UUID]` | devolve o id |
84
+ | Erro de negócio | `raise NotFound("Tag não encontrada.")` | `{"status":404,"message":"...","data":null}` |
85
+
86
+ - `ok()` devolve um `dict`; ele **não** muda o status HTTP. Por isso o `status_code=201` no decorator.
87
+ - `response_model=Envelope[T]` documenta o contrato no OpenAPI e filtra campos extras.
88
+ - Mensagens em português, frase curta, com ponto final, no gênero certo do substantivo. Leitura pode
89
+ ficar com mensagem vazia.
90
+ - Não use `204 No Content`: o envelope sempre tem corpo.
91
+
92
+ ## Erros
93
+
94
+ Do pacote `orfeu` (o service importa, não conhece HTTP):
95
+
96
+ | Classe | Status | Uso típico |
97
+ |---|---|---|
98
+ | `BadRequest` | 400 | parâmetro coerente no formato mas inválido para a regra |
99
+ | `Unauthorized` | 401 | falta credencial exigida pela regra (fora do `@operation`) |
100
+ | `Forbidden` | 403 | usuário autenticado sem acesso ao recurso específico (ex.: time de outro) |
101
+ | `NotFound` | 404 | recurso inexistente |
102
+ | `Conflict` | 409 | unicidade, estado incompatível |
103
+ | `Unprocessable` | 422 | regra de negócio recusou o conteúdo |
104
+ | `Unavailable` | 503 | dependência externa fora do ar (outro serviço, storage) |
105
+ | `EnvelopeError(msg, status)` | qualquer | status não coberto acima |
106
+
107
+ `install_envelope(app)` converte:
108
+
109
+ - `EnvelopeError` → status e mensagem dele;
110
+ - `HTTPException` → `status_code` e `detail` como mensagem (prefira os erros do orfeu);
111
+ - `RequestValidationError` → 422 com as mensagens do Pydantic unidas por `; `;
112
+ - qualquer outra exceção → 500 `"Erro inesperado no serviço."` (stack no log, nunca para o usuário).
113
+
114
+ Padrão de unicidade:
115
+
116
+ ```python
117
+ def create(self, name: str) -> Tag:
118
+ try:
119
+ return self.repo.create(name=name)
120
+ except IntegrityError:
121
+ self.db.rollback() # sessão volta a ser utilizável
122
+ raise Conflict("Já existe uma tag com esse nome.")
123
+ ```
124
+
125
+ Erros de clientes HTTP próprios (`ArgosClientError` etc.) devem ser traduzidos no service para
126
+ `Unavailable`/`BadRequest`, nunca vazar como 500.
127
+
128
+ ## Autorização por dado (além do `@operation`)
129
+
130
+ Quando a permissão depende do registro (ex.: só membros do time veem os registros do time), crie
131
+ `app/domains/<domínio>/access.py` com funções puras sobre as claims + repository e levante `Forbidden`.
132
+ Ids de perfis/grupos que a regra compara devem vir de configuração ou do Argos, não espalhados em código.
133
+ Checagem de permissão programática (fora do decorator) usa o cliente do Orfeu guardado em
134
+ `app.state.orfeu_client` — API em orfeu.
135
+
136
+ ## Upload
137
+
138
+ `UploadFile`/`File`/`Form` exigem `python-multipart` no requirements. Valide tipo e tamanho no service e
139
+ envie o binário a um storage (não ao Postgres nem ao filesystem do container); a chamada bloqueante de
140
+ upload vai para `run_in_threadpool`.
@@ -0,0 +1,190 @@
1
+ # Testes, container e execução
2
+
3
+ ## pytest
4
+
5
+ `pytest.ini`:
6
+
7
+ ```ini
8
+ [pytest]
9
+ testpaths = tests
10
+ pythonpath = src
11
+ asyncio_mode = strict # só se usar pytest-asyncio
12
+ markers =
13
+ db: exige Postgres real (rode `pytest -m "not db"` sem ele)
14
+ ```
15
+
16
+ `requirements-dev.txt`: `-r requirements.txt`, `pytest>=8` (+ `pytest-asyncio` se houver teste async).
17
+
18
+ ### Três níveis
19
+
20
+ | Nível | O que exercita | Banco |
21
+ |---|---|---|
22
+ | Puro | funções de regra/validação/parsers | nenhum |
23
+ | Rota (padrão) | router → service → repository → envelope, via `TestClient` | SQLite em memória |
24
+ | Integração (`@pytest.mark.db`) | SQL específico de Postgres, constraints reais | Postgres real com rollback |
25
+
26
+ ### Rota em SQLite (`tests/conftest.py`)
27
+
28
+ ```python
29
+ @pytest.fixture
30
+ def db() -> Iterator[Session]:
31
+ engine = create_engine(
32
+ "sqlite://",
33
+ connect_args={"check_same_thread": False},
34
+ poolclass=StaticPool, # mesma conexão para o TestClient (outra thread)
35
+ execution_options={"schema_translate_map": {CATALOGO_SCHEMA: None}}, # schema Postgres → banco padrão
36
+ )
37
+
38
+ def _on_connect(conn, _):
39
+ conn.execute("PRAGMA foreign_keys=ON") # FK valendo, como no Postgres
40
+ conn.create_function("gen_random_uuid", 0, lambda: uuid4().hex) # se algum server_default usar
41
+
42
+ event.listen(engine, "connect", _on_connect)
43
+ CatalogoBase.metadata.create_all(engine) # importe antes todos os models.py usados
44
+ session = sessionmaker(bind=engine)()
45
+ try:
46
+ yield session
47
+ finally:
48
+ session.close()
49
+ engine.dispose()
50
+
51
+
52
+ @pytest.fixture
53
+ def client_for(db):
54
+ """client_for(router, user=None, admin=False) → TestClient com o router, o envelope e o banco do teste."""
55
+ def build(*routers, user=None, admin=False):
56
+ app = FastAPI()
57
+ install_envelope(app)
58
+ for r in routers:
59
+ app.include_router(r)
60
+ app.dependency_overrides[get_db] = lambda: db
61
+ app.state.orfeu_client = FakeOrfeuClient(allow=admin) # se o service checa permissão programática
62
+
63
+ @app.middleware("http")
64
+ async def _user(request, call_next): # o que o middleware do Orfeu deixaria
65
+ request.state.user = user
66
+ return await call_next(request)
67
+
68
+ return TestClient(app, raise_server_exceptions=False) # 500 vira envelope, como em produção
69
+ return build
70
+ ```
71
+
72
+ - O middleware do Orfeu **não** entra: o `@operation` só marca a função; sem `Orfeu(app)` a rota roda
73
+ direto. Permissão do Argos se testa na orfeu; aqui se testa regra + contrato.
74
+ - Usuário falso: objeto com `sub` e `raw` (claims) — o mesmo formato que o service lê.
75
+ - Teste o **envelope inteiro** nos erros:
76
+
77
+ ```python
78
+ def test_duplicate_name_is_conflict(client):
79
+ client.post("/tags", json={"name": "a"})
80
+ r = client.post("/tags", json={"name": "a"})
81
+ assert r.status_code == 409
82
+ assert r.json() == {"status": 409, "message": "Já existe uma tag com esse nome.", "data": None}
83
+ ```
84
+
85
+ - Cubra: criação (201 nos dois lugares), listagem, 404, 409, 422 (campo faltando aparece na mensagem),
86
+ remoção devolvendo o id, e o filtro de acesso por usuário quando houver `access.py`.
87
+
88
+ ### Postgres real com rollback (marcados `db`)
89
+
90
+ Os repositories fazem `commit()`; para o teste não deixar dado, junte a sessão a uma transação externa
91
+ e recrie um savepoint a cada fim de transação interna:
92
+
93
+ ```python
94
+ @pytest.fixture
95
+ def db_session(db_connection):
96
+ outer = db_connection.begin()
97
+ session = Session(bind=db_connection)
98
+ nested = db_connection.begin_nested()
99
+
100
+ @event.listens_for(session, "after_transaction_end")
101
+ def _restart_savepoint(sess, transaction):
102
+ nonlocal nested
103
+ if not nested.is_active:
104
+ nested = db_connection.begin_nested()
105
+
106
+ yield session
107
+ session.close()
108
+ outer.rollback() # desfaz tudo, inclusive os commits do código testado
109
+ ```
110
+
111
+ Use um banco de teste/descartável, nunca o de produção, mesmo com rollback.
112
+
113
+ ### Armadilhas de teste
114
+
115
+ - **Basename de teste repetido** em pastas diferentes (`tests/a/test_router.py` e `tests/b/test_router.py`)
116
+ quebra a coleta. Nomeie `test_<domínio>_router.py` (ou ponha `__init__.py` em todas as pastas).
117
+ - `create_all` só cria tabelas de models **importados**; importe os `models.py` dos domínios usados.
118
+ - Diferenças SQLite × Postgres (`ILIKE`, `JSONB`, `ON CONFLICT`, arrays, funções): teste esse SQL com
119
+ `@pytest.mark.db`.
120
+ - Teste que chama outro serviço: substitua o cliente (fixture que faz `monkeypatch` do singleton ou
121
+ `dependency_overrides`), nunca chame a rede.
122
+ - Rode só o que mudou (`pytest tests/test_<domínio>.py`) durante o desenvolvimento.
123
+
124
+ ## Dockerfile
125
+
126
+ ```dockerfile
127
+ FROM python:3.11-slim
128
+ WORKDIR /app
129
+ ENV PYTHONDONTWRITEBYTECODE=1 \
130
+ PYTHONUNBUFFERED=1 \
131
+ PIP_DISABLE_PIP_VERSION_CHECK=1
132
+
133
+ ARG PIP_INDEX_URL # índice privado opcional, vindo do build
134
+ ENV PIP_INDEX_URL=${PIP_INDEX_URL}
135
+ COPY requirements.txt .
136
+ RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
137
+ timeout -k 10 600 pip install -r requirements.txt
138
+
139
+ COPY . .
140
+ ENV PORT=8000
141
+ ENV PYTHONPATH=/app/src
142
+ EXPOSE 8000
143
+ CMD ["sh", "-c", "exec uvicorn src.main:app --host 0.0.0.0 --port $PORT"]
144
+ ```
145
+
146
+ - Imagem única, sem estágio de build: `psycopg2-binary` vem como wheel (sem compilador).
147
+ - `--mount=type=cache` mantém o cache do pip entre builds; `timeout` impede um `pip` travado de segurar
148
+ o build indefinidamente.
149
+ - `PYTHONPATH=/app/src`: o código importa `core`, `app`, `settings` como top-level.
150
+ - **`exec`** no `CMD`: o uvicorn vira PID 1 e recebe o SIGTERM; sem ele o stop espera o timeout e mata.
151
+ - Um `PORT` por serviço, declarado em settings (`port: int`), e o mesmo valor no `EXPOSE`.
152
+ - `--workers N` só se o processo não tiver coletores/tarefas de ciclo (`APP_ROLE=api`, ver integracoes.md).
153
+ - Healthcheck do orquestrador em `<api_prefix>/health`.
154
+
155
+ `.dockerignore` (sem ele, histórico do git e ambientes locais entram na imagem):
156
+
157
+ ```
158
+ .git
159
+ .venv
160
+ venv
161
+ **/__pycache__
162
+ **/*.pyc
163
+ .pytest_cache
164
+ .mypy_cache
165
+ .ruff_cache
166
+ tests
167
+ **/.env
168
+ **/.env.*
169
+ !**/.env.example
170
+ *.log
171
+ Dockerfile
172
+ .dockerignore
173
+ ```
174
+
175
+ Ignorar `**/.env.*` tira os arquivos de ambiente da imagem: a configuração chega por variáveis do
176
+ container (que vencem os arquivos, `override=False`) ou por volume. Defina isso conscientemente — se a
177
+ imagem depender de `settings/environment/.env.<APP_ENV>` copiado, o serviço sobe sem configuração.
178
+
179
+ ## Rodar local
180
+
181
+ ```bash
182
+ python -m venv .venv
183
+ .venv/bin/pip install -r requirements-dev.txt # Windows: .venv\Scripts\pip
184
+ # src/.env com APP_ENV=local e src/settings/environment/.env.local preenchido (fora do git)
185
+ cd src && uvicorn main:app --reload --port 8000 # ou: python src/main.py
186
+ ```
187
+
188
+ Docs em `http://localhost:<porta><api_prefix>/docs` (só fora de produção: em `APP_ENV=prod` os três
189
+ endpoints de documentação ficam desligados). O startup falha se o banco ou o Argos não
190
+ responderem (ping do banco e bootstrap do Orfeu) — é proposital.
@@ -0,0 +1,108 @@
1
+ #!/usr/bin/env node
2
+ // Verificador da skill `fastapi`: armadilhas de serviços FastAPI + SQLAlchemy síncrono.
3
+ // node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/fastapi/scripts/checar.mjs)
4
+ // Exceção: `# acropole-ignore-next-line <regra> -- motivo` na linha anterior.
5
+ // (Dockerfile é da skill `docker`; rota sem `@operation` é do verificador da skill `orfeu`.)
6
+ import { executar } from './nucleo.mjs';
7
+
8
+ /** Literais de string Python a partir de `i` (concatenação implícita): `[{ conteudo, inicio }]`. */
9
+ function literais(t, i) {
10
+ const out = [];
11
+ for (;;) {
12
+ const m = t.slice(i).match(/^\s*([rRbBuUfF]{0,2})("""|'''|"|')/);
13
+ if (!m) break;
14
+ const fecha = m[2];
15
+ const ini = i + m[0].length;
16
+ let j = ini;
17
+ while (j < t.length && !t.startsWith(fecha, j)) {
18
+ if (t[j] === '\\') j++;
19
+ j++;
20
+ }
21
+ out.push({ conteudo: t.slice(ini, j), inicio: ini });
22
+ i = j + fecha.length;
23
+ }
24
+ return out;
25
+ }
26
+
27
+ /** Trechos de SQL que o `text()` também lê como parâmetro: comentários e literais entre aspas simples. */
28
+ function trechosPerigosos(sql) {
29
+ const out = [];
30
+ for (const m of sql.matchAll(/--[^\n]*|\/\*[\s\S]*?\*\/|'(?:[^']|'')*'/g)) out.push({ texto: m[0], pos: m.index });
31
+ return out;
32
+ }
33
+
34
+ const ROTA = /^[ \t]*@\w+\.(?:get|post|put|patch|delete|api_route)\(/gm;
35
+
36
+ const regras = [
37
+ {
38
+ id: 'text-dois-pontos',
39
+ resumo: 'text("...") com :palavra em comentário ou literal do SQL (vira parâmetro)',
40
+ aceita: (a) => a.ext === '.py',
41
+ checar(arq) {
42
+ const out = [];
43
+ for (const m of arq.limpo.matchAll(/\btext\(/g)) {
44
+ for (const lit of literais(arq.limpo, m.index + m[0].length)) {
45
+ for (const tr of trechosPerigosos(lit.conteudo)) {
46
+ // Mesmo critério do SQLAlchemy: `:nome` sem `:` ou `\` antes e sem `:` depois (`::text` é cast).
47
+ const p = tr.texto.match(/(?<![:\w\\]):(\w+)(?!:)/);
48
+ if (!p) continue;
49
+ out.push({
50
+ linha: arq.linhaDe(lit.inicio + tr.pos + p.index),
51
+ mensagem: `\`:${p[1]}\` dentro de ${tr.texto.startsWith("'") ? 'literal' : 'comentário'} do SQL: o \`text()\` trata como parâmetro e falha sem valor`,
52
+ correcao: 'escape como `\\:` (string raw: `r"..."`) ou, em script sem parâmetros, `text(sql.replace(":", r"\\:"))`',
53
+ });
54
+ }
55
+ }
56
+ }
57
+ return out;
58
+ },
59
+ },
60
+ {
61
+ id: 'async-sessao-sincrona',
62
+ resumo: 'rota `async def` recebendo sessão SQLAlchemy síncrona (bloqueia o event loop)',
63
+ aceita: (a) => a.ext === '.py',
64
+ checar(arq) {
65
+ const t = arq.limpo;
66
+ const usaAsync = /\bAsyncSession\b/.test(t);
67
+ const out = [];
68
+ for (const m of t.matchAll(ROTA)) {
69
+ const def = t.slice(m.index).match(/^[ \t]*(async[ \t]+)?def[ \t]+(\w+)\s*\(/m);
70
+ if (!def || !def[1]) continue;
71
+ const abre = m.index + def.index + def[0].length - 1;
72
+ let prof = 0;
73
+ let fim = abre;
74
+ for (; fim < t.length; fim++) {
75
+ if (t[fim] === '(') prof++;
76
+ else if (t[fim] === ')' && --prof === 0) break;
77
+ }
78
+ const params = t.slice(abre, fim);
79
+ const sincrona = /:\s*Session\b|\[\s*Session\s*,\s*Depends/.test(params) || (!usaAsync && /Depends\(\s*get_db\s*\)/.test(params));
80
+ if (!sincrona) continue;
81
+ // Conservador: corpo com `await` é o caso permitido (async de verdade, banco no threadpool); só acusa
82
+ // `async def` que nem espera nada.
83
+ const recuo = def[0].match(/^[ \t]*/)[0].length;
84
+ const resto = t.slice(fim).split('\n');
85
+ const corpo = [];
86
+ for (let i = 1; i < resto.length; i++) {
87
+ const l = resto[i];
88
+ if (l.trim() && l.match(/^[ \t]*/)[0].length <= recuo) break;
89
+ corpo.push(l);
90
+ }
91
+ if (/\bawait\b/.test(corpo.join('\n'))) continue;
92
+ out.push({
93
+ linha: arq.linhaDe(m.index + def.index + def[0].search(/\S/)),
94
+ mensagem: `\`async def ${def[2]}\` usa sessão SQLAlchemy síncrona: cada consulta trava o event loop inteiro`,
95
+ correcao: 'troque por `def` (roda no threadpool); se precisa de `await` (httpx), mande o trabalho de banco para `run_in_threadpool`',
96
+ });
97
+ }
98
+ return out;
99
+ },
100
+ },
101
+ ];
102
+
103
+ process.exitCode = executar({
104
+ skill: 'fastapi',
105
+ descricao: 'text() com :palavra em comentário/literal e async def com sessão síncrona.',
106
+ regras,
107
+ extensoes: ['.py'],
108
+ });
@@ -0,0 +1,227 @@
1
+ // Núcleo dos verificadores das skills (`skills/<skill>/scripts/checar.mjs`). Sem dependências, só Node ≥ 18.
2
+ // FONTE ÚNICA: este arquivo é copiado para `skills/<skill>/scripts/nucleo.mjs` pelo `npm run sync`
3
+ // (cada skill é instalada sozinha, então leva a própria cópia). Edite aqui, nunca a cópia.
4
+ //
5
+ // Uso (pelo checar.mjs de cada skill): node checar.mjs [caminhos...] [--json]
6
+ // sem caminhos: a pasta atual (ignora node_modules, dist, .angular, .git, venvs e caches).
7
+ // saída: `arquivo:linha regra mensagem → correção`; código de saída 1 se achar algo.
8
+ // Exceção pontual, na linha ANTERIOR, em comentário da linguagem:
9
+ // // acropole-ignore-next-line <regra>[,<regra>] -- motivo
10
+ // Sem motivo depois de `--`, a exceção não vale.
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+
14
+ const PASTAS_IGNORADAS = new Set(['node_modules', 'dist', '.angular', '.git', '.venv', 'venv', '__pycache__', '.pytest_cache', '.mypy_cache', 'coverage', '.nx', '.turbo']);
15
+
16
+ const C_LIKE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts', '.scss', '.less']);
17
+
18
+ /** Troca cada caractere (menos quebras de linha) de `s[a..b)` por espaço. */
19
+ function apagar(chars, a, b) {
20
+ for (let i = a; i < b; i++) if (chars[i] !== '\n') chars[i] = ' ';
21
+ }
22
+
23
+ /** Texto com os comentários apagados (mesmo tamanho, mesmas linhas). Strings ficam. */
24
+ export function semComentarios(texto, ext) {
25
+ const c = texto.split('');
26
+ const n = texto.length;
27
+ if (ext === '.html' || ext === '.htm') {
28
+ for (const m of texto.matchAll(/<!--[\s\S]*?(-->|$)/g)) apagar(c, m.index, m.index + m[0].length);
29
+ return c.join('');
30
+ }
31
+ if (ext === '.py') {
32
+ for (let i = 0; i < n; i++) {
33
+ const ch = texto[i];
34
+ if (ch === '#') {
35
+ const fim = texto.indexOf('\n', i);
36
+ apagar(c, i, fim < 0 ? n : fim);
37
+ i = fim < 0 ? n : fim;
38
+ } else if (ch === '"' || ch === "'") {
39
+ const triplo = texto.startsWith(ch.repeat(3), i);
40
+ const fecha = triplo ? ch.repeat(3) : ch;
41
+ let j = i + fecha.length;
42
+ while (j < n && !texto.startsWith(fecha, j)) {
43
+ if (texto[j] === '\\') j++;
44
+ else if (!triplo && texto[j] === '\n') break;
45
+ j++;
46
+ }
47
+ i = j + fecha.length - 1;
48
+ }
49
+ }
50
+ return c.join('');
51
+ }
52
+ const barraDupla = C_LIKE.has(ext); // .css puro só tem /* */
53
+ for (let i = 0; i < n; i++) {
54
+ const ch = texto[i];
55
+ if (ch === '/' && texto[i + 1] === '*') {
56
+ const fim = texto.indexOf('*/', i + 2);
57
+ const f = fim < 0 ? n : fim + 2;
58
+ apagar(c, i, f);
59
+ i = f - 1;
60
+ } else if (barraDupla && ch === '/' && texto[i + 1] === '/' && texto[i - 1] !== ':') {
61
+ const fim = texto.indexOf('\n', i);
62
+ apagar(c, i, fim < 0 ? n : fim);
63
+ i = fim < 0 ? n : fim;
64
+ } else if (ch === '"' || ch === "'" || ch === '`') {
65
+ let j = i + 1;
66
+ while (j < n && texto[j] !== ch) {
67
+ if (texto[j] === '\\') j++;
68
+ else if (ch !== '`' && texto[j] === '\n') break;
69
+ j++;
70
+ }
71
+ i = j;
72
+ }
73
+ }
74
+ let out = c.join('');
75
+ // Comentário HTML dentro de template inline.
76
+ if (ext === '.ts') out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
77
+ return out;
78
+ }
79
+
80
+ /** Monta o objeto de arquivo que as regras recebem. */
81
+ export function lerArquivo(caminho, rel, raiz = path.dirname(caminho)) {
82
+ const texto = fs.readFileSync(caminho, 'utf8').replace(/\r\n?/g, '\n');
83
+ const ext = path.extname(caminho).toLowerCase();
84
+ const inicios = [0];
85
+ for (let i = 0; i < texto.length; i++) if (texto[i] === '\n') inicios.push(i + 1);
86
+ const linhaDe = (idx) => {
87
+ let lo = 0;
88
+ let hi = inicios.length - 1;
89
+ while (lo < hi) {
90
+ const mid = (lo + hi + 1) >> 1;
91
+ if (inicios[mid] <= idx) lo = mid;
92
+ else hi = mid - 1;
93
+ }
94
+ return lo + 1;
95
+ };
96
+ // relRaiz: relativo ao caminho pedido na linha de comando (para regras que olham pastas, ex.: tests/).
97
+ const relRaiz = path.relative(raiz, caminho).split(path.sep).join('/') || path.basename(caminho);
98
+ return { caminho, rel, relRaiz, ext, nome: path.basename(caminho), texto, limpo: semComentarios(texto, ext), linhaDe };
99
+ }
100
+
101
+ /** Trechos de template HTML: o arquivo `.html` inteiro ou `template: \`...\`` de um `.ts`. `{ texto, inicio }`. */
102
+ export function templates(arq) {
103
+ if (arq.ext === '.html') return [{ texto: arq.limpo, inicio: 0 }];
104
+ if (arq.ext !== '.ts') return [];
105
+ const out = [];
106
+ for (const m of arq.limpo.matchAll(/\btemplate\s*:\s*`/g)) {
107
+ const ini = m.index + m[0].length;
108
+ const fim = arq.limpo.indexOf('`', ini);
109
+ if (fim > ini) out.push({ texto: arq.limpo.slice(ini, fim), inicio: ini });
110
+ }
111
+ return out;
112
+ }
113
+
114
+ /** Trechos de CSS: `.css`/`.scss` inteiros ou `styles: \`...\`` / `styles: [\`...\`]` de um `.ts`. */
115
+ export function estilos(arq) {
116
+ if (arq.ext === '.css' || arq.ext === '.scss' || arq.ext === '.less') return [{ texto: arq.limpo, inicio: 0 }];
117
+ if (arq.ext !== '.ts') return [];
118
+ const out = [];
119
+ for (const m of arq.limpo.matchAll(/\bstyles\s*:\s*\[?/g)) {
120
+ let i = m.index + m[0].length;
121
+ for (;;) {
122
+ while (/[\s,]/.test(arq.limpo[i] ?? '')) i++;
123
+ const q = arq.limpo[i];
124
+ if (q !== '`' && q !== "'" && q !== '"') break;
125
+ const fim = arq.limpo.indexOf(q, i + 1);
126
+ if (fim < 0) break;
127
+ // O conteúdo da string é CSS: apaga os /* */ dele.
128
+ out.push({ texto: semComentarios(arq.limpo.slice(i + 1, fim), '.css'), inicio: i + 1 });
129
+ i = fim + 1;
130
+ if (arq.limpo[m.index + m[0].length - 1] !== '[') break;
131
+ }
132
+ }
133
+ return out;
134
+ }
135
+
136
+ /** Lista os arquivos a verificar: `[{ caminho, raiz }]` (raiz = o caminho pedido que o contém). */
137
+ export function listarArquivos(caminhos, cwd, aceita) {
138
+ const out = new Map();
139
+ let raiz = '';
140
+ const visitar = (p, explicito) => {
141
+ let st;
142
+ try {
143
+ st = fs.statSync(p);
144
+ } catch {
145
+ throw new Error(`caminho não encontrado: ${p}`);
146
+ }
147
+ if (st.isDirectory()) {
148
+ if (!explicito && PASTAS_IGNORADAS.has(path.basename(p))) return;
149
+ if (explicito) raiz = p;
150
+ for (const e of fs.readdirSync(p).sort()) visitar(path.join(p, e), false);
151
+ } else if ((explicito || aceita(p)) && !out.has(p)) out.set(p, explicito ? path.dirname(p) : raiz);
152
+ };
153
+ for (const c of caminhos.length ? caminhos : ['.']) visitar(path.resolve(cwd, c), true);
154
+ return [...out].filter(([p]) => aceita(p)).map(([caminho, r]) => ({ caminho, raiz: r }));
155
+ }
156
+
157
+ const IGNORE = /acropole-ignore-next-line\s+([\w,-]+)(?:\s+--(.*?))?\s*(?:\*\/|-->)?\s*$/;
158
+
159
+ /** Exceção declarada na linha anterior: `{ regras: Set, motivo }` ou null. */
160
+ function excecao(arq, linha) {
161
+ const anterior = arq.texto.split('\n')[linha - 2];
162
+ const m = anterior && anterior.match(IGNORE);
163
+ if (!m) return null;
164
+ return { regras: new Set(m[1].split(',').filter(Boolean)), motivo: (m[2] ?? '').trim() };
165
+ }
166
+
167
+ /**
168
+ * Roda as regras. `regras`: `[{ id, aceita(arq) => bool, checar(arq, ctx) => [{ linha, mensagem, correcao }] }]`.
169
+ * `preparar(arquivos, ctx)` opcional roda antes, com todos os arquivos lidos (ex.: coletar declarações).
170
+ */
171
+ export function verificar({ regras, caminhos = [], cwd = process.cwd(), extensoes, preparar }) {
172
+ const aceita = (p) => extensoes.includes(path.extname(p).toLowerCase()) || extensoes.includes(path.basename(p));
173
+ const arquivos = listarArquivos(caminhos, cwd, aceita).map(({ caminho, raiz }) =>
174
+ lerArquivo(caminho, path.relative(cwd, caminho).split(path.sep).join('/') || path.basename(caminho), raiz),
175
+ );
176
+ const ctx = {};
177
+ if (preparar) preparar(arquivos, ctx);
178
+ const achados = [];
179
+ for (const arq of arquivos) {
180
+ for (const regra of regras) {
181
+ if (regra.aceita && !regra.aceita(arq)) continue;
182
+ for (const a of regra.checar(arq, ctx) ?? []) {
183
+ const exc = excecao(arq, a.linha);
184
+ let correcao = a.correcao;
185
+ if (exc && exc.regras.has(regra.id)) {
186
+ if (exc.motivo) continue;
187
+ correcao += ' (a exceção acropole-ignore-next-line precisa de motivo depois de "--")';
188
+ }
189
+ achados.push({ arquivo: arq.rel, linha: a.linha, regra: regra.id, mensagem: a.mensagem, correcao });
190
+ }
191
+ }
192
+ }
193
+ achados.sort((a, b) => (a.arquivo < b.arquivo ? -1 : a.arquivo > b.arquivo ? 1 : a.linha - b.linha || (a.regra < b.regra ? -1 : 1)));
194
+ // Mesmo achado duas vezes na mesma linha (ex.: duas cores) vira um só por regra+mensagem.
195
+ const unicos = [...new Map(achados.map((a) => [`${a.arquivo}:${a.linha}:${a.regra}:${a.mensagem}`, a])).values()];
196
+ return { arquivos: arquivos.length, achados: unicos };
197
+ }
198
+
199
+ /** Ponto de entrada dos checar.mjs: lê argv, imprime e define o código de saída. */
200
+ export function executar({ skill, descricao, regras, extensoes, preparar, argv = process.argv.slice(2) }) {
201
+ if (argv.includes('--help') || argv.includes('-h')) {
202
+ console.log(`Verificador da skill ${skill}: ${descricao}
203
+
204
+ Uso: node checar.mjs [caminhos...] [--json]
205
+ sem caminhos, verifica a pasta atual (ignora node_modules, dist, .angular...).
206
+ Exceção (linha anterior, em comentário): acropole-ignore-next-line <regra> -- motivo
207
+
208
+ Regras:
209
+ ${regras.map((r) => ` ${r.id.padEnd(28)} ${r.resumo}`).join('\n')}`);
210
+ return 0;
211
+ }
212
+ const json = argv.includes('--json');
213
+ const caminhos = argv.filter((a) => a !== '--json');
214
+ let r;
215
+ try {
216
+ r = verificar({ regras, caminhos, extensoes, preparar });
217
+ } catch (e) {
218
+ console.error(`checar (${skill}): ${e.message}`);
219
+ return 2;
220
+ }
221
+ if (json) console.log(JSON.stringify({ skill, arquivos: r.arquivos, achados: r.achados }, null, 2));
222
+ else {
223
+ for (const a of r.achados) console.log(`${a.arquivo}:${a.linha} ${a.regra} ${a.mensagem} → ${a.correcao}`);
224
+ console.log(r.achados.length ? `\n${r.achados.length} problema(s) em ${r.arquivos} arquivo(s) verificado(s).` : `Nada encontrado (${r.arquivos} arquivo(s) verificado(s)).`);
225
+ }
226
+ return r.achados.length ? 1 : 0;
227
+ }