@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.
- package/README.md +180 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +75 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +152 -0
- package/skills/angular/references/armadilhas.md +95 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +260 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +230 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +222 -0
- package/skills/apollo/references/armadilhas.md +95 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +299 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +180 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +282 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +154 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +154 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +274 -0
- package/skills/express/references/testes-deploy.md +150 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +129 -0
- package/skills/fastapi/references/banco.md +185 -0
- package/skills/fastapi/references/estrutura.md +281 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +348 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +534 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +234 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- 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
|
+
}
|