@acropole/skills 0.0.0-stage → 1.1.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 +181 -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 +80 -0
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -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 +155 -0
- package/skills/angular/references/armadilhas.md +99 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +279 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +257 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +226 -0
- package/skills/apollo/references/armadilhas.md +99 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +310 -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 +181 -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 +286 -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 +156 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +157 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +286 -0
- package/skills/express/references/testes-deploy.md +154 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +132 -0
- package/skills/fastapi/references/banco.md +197 -0
- package/skills/fastapi/references/estrutura.md +325 -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 +354 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +541 -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 +240 -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,240 @@
|
|
|
1
|
+
# orfeu (Python) — guia de uso (FastAPI, Flask, Django, Strawberry)
|
|
2
|
+
|
|
3
|
+
> Escrito para a **API 1.0.0** (versão instalada: `python -c "import importlib.metadata as m;
|
|
4
|
+
> print(m.version('orfeu'))"`). Conceitos comuns às três implementações estão no `SKILL.md` da skill; o que muda
|
|
5
|
+
> em relação ao Node e ao Angular está em [diferencas.md](diferencas.md). Estrutura do serviço FastAPI em si
|
|
6
|
+
> (camadas, banco, configuração): skill `fastapi`. Flask, Django e Strawberry ainda não têm skill de
|
|
7
|
+
> padrões — aqui só a integração com o Orfeu.
|
|
8
|
+
|
|
9
|
+
O orfeu é o cliente Python do autorizador **Argos**. Num serviço, ele:
|
|
10
|
+
|
|
11
|
+
1. autentica o próprio backend no Argos (`app_id` + `secret`), baixa o JWKS e **sincroniza o catálogo de
|
|
12
|
+
operações** declaradas com `@operation`;
|
|
13
|
+
2. em cada chamada a uma rota marcada, valida a credencial de quem chama (JWT, token pessoal ou token de
|
|
14
|
+
API), decide a permissão e responde 401/403 sem rodar o handler quando nega;
|
|
15
|
+
3. grava **um evento de auditoria** por chamada guardada (enviado em lote, em segundo plano) e **uma linha
|
|
16
|
+
de log** estruturada (`logging` padrão);
|
|
17
|
+
4. mantém a correlação W3C `traceparent` e oferece `orfeu_headers(...)` para repassar contexto a outro serviço.
|
|
18
|
+
|
|
19
|
+
Sem OpenTelemetry e sem dependência de observabilidade: só `httpx` e `PyJWT[crypto]`.
|
|
20
|
+
|
|
21
|
+
Leia sob demanda:
|
|
22
|
+
- [python-api.md](python-api.md) — **todos** os exports públicos (`orfeu`, `orfeu.adapters.*` e submódulos úteis), com
|
|
23
|
+
assinatura, comportamento, erros e status.
|
|
24
|
+
- [python-recipes.md](python-recipes.md) — receitas prontas: app FastAPI protegido, operação com permissão, rota
|
|
25
|
+
pública/opcional, anotar alvo na auditoria, chamada entre serviços propagando trace (como o usuário e como
|
|
26
|
+
o próprio serviço), WebSocket, log JSON, testes com mocks, cliente avulso (script/worker), Strawberry,
|
|
27
|
+
Flask/Django — e a lista de armadilhas.
|
|
28
|
+
|
|
29
|
+
## 1. Instalação
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pip install "orfeu[fastapi]" # FastAPI/Starlette (fastapi>=0.111, starlette>=0.37)
|
|
33
|
+
pip install "orfeu[flask]" # ou [django], [strawberry]; sem extra = só o cliente (OrfeuClient)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- **Python ≥ 3.11** (`requires-python = ">=3.11"`; usa `enum.StrEnum`). Testado em 3.11–3.14.
|
|
37
|
+
- Dependências fixas: `httpx>=0.27`, `PyJWT[crypto]>=2.8`. O adapter FastAPI foi testado com FastAPI
|
|
38
|
+
0.111.0, 0.116.1, 0.137.0 e 0.142.2.
|
|
39
|
+
- Fixe a versão maior no app: `orfeu[fastapi]>=1.0,<2`.
|
|
40
|
+
|
|
41
|
+
## 2. Configuração
|
|
42
|
+
|
|
43
|
+
A lib **não lê variáveis de ambiente**. Tudo entra pelo construtor (`Orfeu(...)` dos adapters ou
|
|
44
|
+
`OrfeuClient(...)`), exceto no Django, que lê `settings`.
|
|
45
|
+
|
|
46
|
+
| Parâmetro | Obrigatório | O que é |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| `authorizer_url` | sim | URL base da API do Argos (a barra final é removida). |
|
|
49
|
+
| `realm_id` | sim | Realm do backend (nome ou UUID). Tokens de outro realm são recusados. |
|
|
50
|
+
| `app_id` | sim | UUID do backend cadastrado no Argos (é o `agent_id` dos logs). |
|
|
51
|
+
| `secret` | sim | Segredo do backend, em texto puro. Nunca no código: venha de variável de ambiente/cofre. |
|
|
52
|
+
| `tls_verify` | não, só por nome (`*`) | `True` (padrão). `False` desliga a verificação TLS **só** nas chamadas ao Argos (certificado autoassinado em desenvolvimento). Não é global. |
|
|
53
|
+
| `audit` | não, só por nome | `True` (padrão), `False` (desliga a auditoria) ou `AuditOptions(...)` (ajusta lote/buffer). |
|
|
54
|
+
| `permissions_refresh` | não, só por nome (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) | `True` (padrão: revalida o catálogo com os grupos liberados a cada 60 s ±20%, com `If-None-Match`; mantém o anterior se o Argos cair), `False` ou `PermissionsRefreshOptions(enabled, interval_s, jitter)`. Django: `ORFEU_PERMISSIONS_REFRESH`. |
|
|
55
|
+
|
|
56
|
+
Django: settings `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (obrigatórios —
|
|
57
|
+
sem eles o middleware levanta `RuntimeError`), `ORFEU_TLS_VERIFY` e `ORFEU_AUDIT` (opcionais).
|
|
58
|
+
|
|
59
|
+
Nos outros frameworks o app escolhe os nomes das variáveis. Convenção sugerida (a mesma do Django):
|
|
60
|
+
`ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET`, `ORFEU_TLS_VERIFY`.
|
|
61
|
+
|
|
62
|
+
## 3. App FastAPI — o mínimo
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
import os
|
|
66
|
+
from fastapi import FastAPI, Request
|
|
67
|
+
from orfeu import Level, Method
|
|
68
|
+
from orfeu.adapters.fastapi import Orfeu, install_envelope, operation
|
|
69
|
+
|
|
70
|
+
app = FastAPI() # com ou sem lifespan= próprio
|
|
71
|
+
install_envelope(app) # todo erro vira {status, message, data: null}
|
|
72
|
+
orfeu = Orfeu(
|
|
73
|
+
app,
|
|
74
|
+
authorizer_url=os.environ["ORFEU_AUTHORIZER_URL"],
|
|
75
|
+
realm_id=os.environ["ORFEU_REALM_ID"],
|
|
76
|
+
app_id=os.environ["ORFEU_APP_ID"],
|
|
77
|
+
secret=os.environ["ORFEU_SECRET"],
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
@app.get("/items")
|
|
81
|
+
@operation(id="items.list", level=Level.PRIVATE, method=Method.READ)
|
|
82
|
+
async def list_items(request: Request):
|
|
83
|
+
user = request.state.user # TokenClaims
|
|
84
|
+
return {"status": 200, "message": "", "data": {"sub": user.sub}}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- `Orfeu(app, ...)` instala um middleware ASGI e **embrulha o lifespan** do app: no startup roda
|
|
88
|
+
token do app → JWKS → sync das operações → busca das operações com grupos (e, com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1, agenda a recarga
|
|
89
|
+
periódica delas); no shutdown para a recarga e faz o flush da auditoria (`client.close()`). Funciona com `lifespan=` e com `on_startup`. Não chame nada no seu lifespan.
|
|
90
|
+
- O startup **falha** (e o app não sobe) se o Argos recusar as credenciais (`OrfeuAuthError`), o sync falhar
|
|
91
|
+
(`OrfeuSyncError`), o JWKS não vier (`OrfeuError`) ou **nenhuma** `@operation` estiver registrada
|
|
92
|
+
(`OrfeuConfigError`). Não há retentativa: o Argos precisa estar acessível no boot.
|
|
93
|
+
- `await orfeu.startup_async()` / `orfeu.startup()` são públicos e idempotentes (testes, scripts). O
|
|
94
|
+
`OrfeuClient` fica em `orfeu.client`.
|
|
95
|
+
- Rotas **sem** `@operation` passam direto, sem autenticação, log ou auditoria.
|
|
96
|
+
|
|
97
|
+
## 4. Operações: `@operation`, `Level`, `Method`
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
@router.post("/forms")
|
|
101
|
+
@operation(id="forms.create", level=Level.PROTECTED, method=Method.WRITE)
|
|
102
|
+
async def create_form(...): ...
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
- `id`: identificador único da operação, 1..200 caracteres (convenção: `recurso.acao`). A chave real no
|
|
106
|
+
Argos é `(id, method)`: o mesmo `id` com outro `method` é outra operação.
|
|
107
|
+
- `level` (`Level`, `StrEnum` — as strings `"private"` etc. também valem). Significado de cada nível:
|
|
108
|
+
`SKILL.md` §3.
|
|
109
|
+
|
|
110
|
+
- `method` (`Method`): `READ`, `WRITE`, `DELETE`, `STREAM`. Sem `method=`, é inferido pelo **nome da
|
|
111
|
+
função**: `get_`/`list_`/`fetch_`/`read_` → `read`; `delete_`/`remove_`/`destroy_` → `delete`; contém
|
|
112
|
+
`stream`/`subscribe`/`watch`/`listen` → `stream`; o resto → `write`. **Prefira passar `method=`**:
|
|
113
|
+
renomear a função muda a operação.
|
|
114
|
+
- Valor inválido levanta `OrfeuConfigError` **na importação** do módulo.
|
|
115
|
+
- O decorator **não embrulha** a função: só grava `__orfeu_id__`/`__orfeu_method__`/`__orfeu_level__` nela
|
|
116
|
+
e registra num **registro global** do processo. Coloque `@operation` logo abaixo do decorator de rota —
|
|
117
|
+
o objeto que o FastAPI registra precisa carregar esses atributos (ver armadilhas).
|
|
118
|
+
- Quem pode chamar uma operação `protected` (grupos) é configurado **no Argos**, não no código.
|
|
119
|
+
|
|
120
|
+
## 5. Credenciais e regra de decisão
|
|
121
|
+
|
|
122
|
+
Headers (`x-access-token` → `x-app-token` → `x-api-token`, vale a primeira presente; `Authorization` é
|
|
123
|
+
ignorado) e a regra 401/403 estão no `SKILL.md` §4 — idêntica em FastAPI HTTP/WebSocket, Flask, Django e
|
|
124
|
+
Strawberry. Específico do Python: o JWT precisa ser RS256 com `kid` no header; introspecção com cache de 60 s
|
|
125
|
+
(token inativo: 10 s); tokens de outro realm são sempre recusados (não há `acceptAnyRealm`).
|
|
126
|
+
|
|
127
|
+
O que o handler FastAPI recebe (`request.state` / `websocket.state`):
|
|
128
|
+
|
|
129
|
+
| Caso | `request.state.user` | `request.state.api_token` |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| usuário (`x-access-token`/`x-app-token`) válido | `TokenClaims` | ausente |
|
|
132
|
+
| `x-api-token` válido | `None` | `ApiTokenClaims(token_id, app_id)` |
|
|
133
|
+
| anônimo (`public`/`optional` sem credencial válida) | **ausente** (`AttributeError`) | ausente |
|
|
134
|
+
|
|
135
|
+
Por isso, em `public`/`optional` leia com `getattr(request.state, "user", None)`.
|
|
136
|
+
|
|
137
|
+
`TokenClaims` é um **objeto** (dataclass), não um `dict`: `user.sub`, `user.realm_id`, `user.groups`, `user.exp` e
|
|
138
|
+
`user.raw` (o JWT decodificado inteiro). Nome/e-mail do usuário estão em `raw`:
|
|
139
|
+
`user.raw.get("preferred_username") or user.raw.get("email") or user.sub`. `user.get(...)` lança
|
|
140
|
+
`AttributeError: 'TokenClaims' object has no attribute 'get'` (500 na rota).
|
|
141
|
+
|
|
142
|
+
## 6. Respostas, erros e status
|
|
143
|
+
|
|
144
|
+
| Situação | Resposta |
|
|
145
|
+
|---|---|
|
|
146
|
+
| sem credencial / credencial inválida | `401` `{"status": 401, "message": "Invalid or missing credentials.", "data": null, "error": "unauthorized", "detail": "..."}` — corpo **genérico**; o motivo real vai só para log/auditoria |
|
|
147
|
+
| sem permissão | `403` `{..., "message": "Insufficient permissions.", "error": "forbidden"}` |
|
|
148
|
+
| rota que a guarda não conseguiu resolver | `500` `error: "route_unresolved"`, handler **não** roda (falha fechada; logger `orfeu.guard`) |
|
|
149
|
+
| WebSocket negado/irresolvível | fecha com **1008** antes do `accept` |
|
|
150
|
+
|
|
151
|
+
Envelope de sucesso/erro do próprio app (`install_envelope(app)`): levante `NotFound("Formulário não
|
|
152
|
+
encontrado.")`, `Conflict(...)`, `BadRequest(...)` etc. na regra de negócio — vira `fail(status, message)`.
|
|
153
|
+
`HTTPException` → `detail` como mensagem; 422 de validação → mensagens unidas por `; `; qualquer outra
|
|
154
|
+
exceção → `500 "Erro inesperado no serviço."` (detalhe só no log `orfeu.envelope`). Sucesso: `ok(data,
|
|
155
|
+
message, status)`; `response_model=Envelope[T]` documenta no OpenAPI.
|
|
156
|
+
|
|
157
|
+
O status final da resposta (inclusive 4xx/5xx gerados pelo envelope) é o que vai para a auditoria como
|
|
158
|
+
`outcome`/`status`, com a `message` do corpo.
|
|
159
|
+
|
|
160
|
+
## 7. Auditoria
|
|
161
|
+
|
|
162
|
+
Toda chamada guardada vira um evento (quem, o quê, onde, resultado, duração, trace), enviado em lote por
|
|
163
|
+
uma thread daemon (`orfeu-audit`: a cada 1 s ou 200 eventos; buffer de 10 mil; backoff até 60 s em erro;
|
|
164
|
+
404 do Argos pausa por 10 min). A requisição nunca espera.
|
|
165
|
+
|
|
166
|
+
No handler, acrescente o **alvo** quando ele for conhecido:
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
from orfeu import annotate_operation
|
|
170
|
+
|
|
171
|
+
annotate_operation(target_type="form", target_id=form_id, details={"campos": ["titulo"]})
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- Só funciona **dentro** de uma chamada guardada; fora dela devolve `False` e não faz nada.
|
|
175
|
+
- `target_id` vira `str`; `details` é mesclado a cada chamada. Limites: `target_type` 100 caracteres,
|
|
176
|
+
`target_id` 200, `details` 4 KB (acima disso vira `{"truncated": true, "original_bytes": n}`).
|
|
177
|
+
- Nunca ponha segredo, token ou dado pessoal sensível em `details`.
|
|
178
|
+
- Flush: automático no shutdown do FastAPI e no `atexit`; `orfeu.client.flush_audit()` força.
|
|
179
|
+
`audit=False` desliga; `AuditOptions(flush_interval=..., batch_size=..., max_buffer=...)` ajusta.
|
|
180
|
+
|
|
181
|
+
## 8. Trace e chamadas entre serviços
|
|
182
|
+
|
|
183
|
+
Cada chamada guardada tem um `OrfeuTrace`: com `traceparent` W3C válido na entrada, o trace continua
|
|
184
|
+
(`entry=False`, mesmo `trace_id`); sem ele (ou inválido), começa um novo (`entry=True`).
|
|
185
|
+
|
|
186
|
+
Para chamar outro serviço **em nome da requisição atual**, use `orfeu_headers(request)`:
|
|
187
|
+
|
|
188
|
+
```python
|
|
189
|
+
import httpx
|
|
190
|
+
from orfeu.adapters.fastapi import orfeu_headers
|
|
191
|
+
|
|
192
|
+
async with httpx.AsyncClient() as http:
|
|
193
|
+
r = await http.get(f"{OUTRO_SERVICO}/forms/{form_id}", headers=orfeu_headers(request))
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Ele devolve `traceparent` (o evento do outro serviço vira um passo interno da mesma ação),
|
|
197
|
+
`x-route-id`/`x-client-id` recebidos e a credencial **de usuário** (`x-access-token` ou `x-app-token`).
|
|
198
|
+
O `x-api-token` de quem chamou **nunca** é repassado. `credential=False` omite a credencial (para chamar
|
|
199
|
+
como o próprio serviço, com o `x-api-token` dele). Fora de uma chamada guardada devolve `{}`.
|
|
200
|
+
|
|
201
|
+
## 9. Logs
|
|
202
|
+
|
|
203
|
+
Uma linha por chamada guardada no logger `orfeu.operation` (`INFO "operação executada"` / `ERROR` com a
|
|
204
|
+
mensagem), com os campos como atributos do `LogRecord` (`operation`, `operation_id`, `operation_method`,
|
|
205
|
+
`operation_level`, `agent_id`, `actor_type`, `permission_result`, `duration_ms`, `user`, `token_id`,
|
|
206
|
+
`route_id`, `client_id`, `trace_id`, `span_id`). Outros loggers: `orfeu.audit` (falha de entrega),
|
|
207
|
+
`orfeu.envelope` (exceção convertida em 500), `orfeu.guard` (rota irresolvível). O orfeu não configura
|
|
208
|
+
handlers: ligue `JsonLogFormatter` se quiser uma linha JSON por registro ([python-recipes.md](python-recipes.md) §8).
|
|
209
|
+
|
|
210
|
+
## 10. Testes
|
|
211
|
+
|
|
212
|
+
Não há módulo de mocks oficial. O padrão (o mesmo da suíte do pacote) é construir o app real e trocar só os
|
|
213
|
+
métodos públicos do `OrfeuClient` que vão à rede:
|
|
214
|
+
|
|
215
|
+
```python
|
|
216
|
+
from unittest.mock import AsyncMock, MagicMock
|
|
217
|
+
orfeu = Orfeu(app, "http://authorizer.test/api", "realm", "app-id", "secret", audit=False)
|
|
218
|
+
orfeu.client.startup = AsyncMock() # sem rede no lifespan
|
|
219
|
+
orfeu.client.validate_token = AsyncMock(return_value=claims)
|
|
220
|
+
orfeu.client.check_permission = MagicMock(return_value=True)
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Detalhes (registro global, `clear_registry()`, capturar eventos de auditoria, logs): [python-recipes.md](python-recipes.md) §9.
|
|
224
|
+
|
|
225
|
+
## 11. Regras que não podem ser quebradas
|
|
226
|
+
|
|
227
|
+
1. **Toda rota que não é pública leva `@operation`.** Rota sem ele não tem autenticação nenhuma.
|
|
228
|
+
2. **`@operation` logo abaixo do decorator de rota**, sobre a função que o framework registra. Um wrapper
|
|
229
|
+
intermediário sem `functools.wraps` apaga os atributos e a rota fica **aberta, sem aviso**.
|
|
230
|
+
3. **Passe `method=` explícito.** A inferência pelo nome muda se a função for renomeada.
|
|
231
|
+
4. **Nunca leia `Authorization`/`Bearer`** nem valide token na mão: use `request.state.user`/`api_token`.
|
|
232
|
+
5. **Em `public`/`optional`, `getattr(request.state, "user", None)`** — o atributo não existe no anônimo.
|
|
233
|
+
6. **Erros de negócio com as classes do envelope** (`NotFound`, `Conflict`...), não `JSONResponse` montado à mão.
|
|
234
|
+
7. **Chamada a outro serviço dentro de um handler usa `orfeu_headers(request)`** (ou `credential=False` +
|
|
235
|
+
o `x-api-token` do serviço); nunca repasse o `x-api-token` recebido.
|
|
236
|
+
8. **`annotate_operation` antes de retornar**, no fluxo do handler (não numa task que roda depois da resposta).
|
|
237
|
+
9. **Segredo fora do código** e nunca em log, `details` ou mensagem de erro.
|
|
238
|
+
|
|
239
|
+
Mais armadilhas (registro global, operações importadas tarde, grupos alterados no Argos, `from __future__
|
|
240
|
+
import annotations` com `Request`): [python-recipes.md](python-recipes.md) §13.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Verificador da skill `orfeu`: autenticação/autorização feitas à mão em vez do SDK.
|
|
3
|
+
// node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/orfeu/scripts/checar.mjs)
|
|
4
|
+
// Ignora testes (*.spec.*, *.test.*, test_*.py, *_test.py, pastas test/tests).
|
|
5
|
+
// Exceção: `// acropole-ignore-next-line <regra> -- motivo` (`# ...` no Python) na linha anterior.
|
|
6
|
+
import { executar } from './nucleo.mjs';
|
|
7
|
+
|
|
8
|
+
const JS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
|
|
9
|
+
const ehTeste = (a) => /\.(spec|test)\.[cm]?[jt]sx?$/.test(a.nome) || /^test_.*\.py$|_test\.py$|^conftest\.py$/.test(a.nome) || /(^|\/)(tests?|__tests__|e2e)\//.test(a.relRaiz);
|
|
10
|
+
const ehApp = (a) => !ehTeste(a);
|
|
11
|
+
const ehJs = (a) => JS.includes(a.ext) && ehApp(a);
|
|
12
|
+
const ehPy = (a) => a.ext === '.py' && ehApp(a);
|
|
13
|
+
|
|
14
|
+
function procurar(arq, re, fazer) {
|
|
15
|
+
return [...arq.limpo.matchAll(re)].map((m) => ({ linha: arq.linhaDe(m.index), ...fazer(m) }));
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** Índice do `)` que fecha o `(` em `inicio`, ignorando strings. */
|
|
19
|
+
function fechaParen(t, inicio) {
|
|
20
|
+
let prof = 0;
|
|
21
|
+
let aspas = '';
|
|
22
|
+
for (let i = inicio; i < t.length; i++) {
|
|
23
|
+
const ch = t[i];
|
|
24
|
+
if (aspas) {
|
|
25
|
+
if (ch === '\\') i++;
|
|
26
|
+
else if (ch === aspas) aspas = '';
|
|
27
|
+
} else if (ch === '"' || ch === "'" || ch === '`') aspas = ch;
|
|
28
|
+
else if (ch === '(') prof++;
|
|
29
|
+
else if (ch === ')' && --prof === 0) return i;
|
|
30
|
+
}
|
|
31
|
+
return t.length;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// Só leitura: atribuição (`headers['Authorization'] = ...`, chamada de saída para terceiro) não conta.
|
|
35
|
+
const AUTH_JS = /\bheaders\s*(?:\.\s*authorization\b|\[\s*['"`]authorization['"`]\s*\])(?!\s*=[^=])|\.\s*(?:get|header)\(\s*['"`]authorization['"`]\s*\)|\b(?:split|replace|startsWith|substring|slice)\(\s*['"`]bearer\b/gi;
|
|
36
|
+
const AUTH_PY = /\bheaders\s*(?:\.get\(\s*['"]authorization['"]|\[\s*['"]authorization['"]\s*\](?!\s*=[^=]))|\bHeader\([^)]*alias\s*=\s*['"]authorization['"]|\bauthorization\s*:\s*[\w\[\]| .]*=\s*Header\(|\b(?:HTTPBearer|OAuth2PasswordBearer)\(|\.(?:split|replace|startswith)\(\s*['"]bearer\b/gi;
|
|
37
|
+
|
|
38
|
+
const regras = [
|
|
39
|
+
{
|
|
40
|
+
id: 'authorization-manual',
|
|
41
|
+
resumo: 'token lido de Authorization/Bearer à mão',
|
|
42
|
+
aceita: (a) => ehJs(a) || ehPy(a),
|
|
43
|
+
checar: (arq) =>
|
|
44
|
+
procurar(arq, arq.ext === '.py' ? AUTH_PY : AUTH_JS, () => ({
|
|
45
|
+
mensagem: 'credencial lida à mão de `Authorization`/`Bearer` — a API do app recebe `x-access-token`, `x-app-token` ou `x-api-token`; `Bearer` só existe entre o SDK e o Argos',
|
|
46
|
+
correcao:
|
|
47
|
+
arq.ext === '.py'
|
|
48
|
+
? 'proteja a rota com `@operation(...)` e leia `request.state.user` (referências: python.md)'
|
|
49
|
+
: 'proteja com `guard(...)`/`operation(...)` do `@orfeu/node` e use o usuário do contexto (referências: node.md)',
|
|
50
|
+
})),
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
id: 'jwt-manual',
|
|
54
|
+
resumo: 'validação de JWT à mão (jwt.verify / jwt.decode do PyJWT)',
|
|
55
|
+
aceita: (a) => ehJs(a) || ehPy(a),
|
|
56
|
+
checar: (arq) =>
|
|
57
|
+
procurar(arq, arq.ext === '.py' ? /\bjwt\.decode\s*\(/g : /\bjwt\.verify\s*\(|\bjwtVerify\s*\(/g, (m) => ({
|
|
58
|
+
mensagem: `\`${m[0].replace(/\s*\($/, '')}\` valida token à mão; o SDK já valida JWT/JWKS e introspecção`,
|
|
59
|
+
correcao: 'use o guard do Orfeu (`@operation`, `guard`, `operation`) e o usuário que ele entrega',
|
|
60
|
+
})),
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
id: 'token-em-storage',
|
|
64
|
+
resumo: 'token ou outra credencial guardada em localStorage/sessionStorage',
|
|
65
|
+
aceita: ehJs,
|
|
66
|
+
checar: (arq) =>
|
|
67
|
+
procurar(arq, /\b(localStorage|sessionStorage)\s*(?:\.\s*setItem\(([^)]*)\)|\[\s*(['"`][^'"`]*['"`])\s*\]\s*=(?!=)|\.\s*(\w+)\s*=(?!=))/g, (m) => m)
|
|
68
|
+
.filter((a) => /token|jwt|bearer|credential|access|refresh|senha|password|passwd|secret|api[-_]?key/i.test(a[2] ?? a[3] ?? a[4] ?? ''))
|
|
69
|
+
.map((a) => ({
|
|
70
|
+
linha: a.linha,
|
|
71
|
+
mensagem: `credencial gravada em \`${a[1]}\`: qualquer script da página lê (XSS) e ela vaza entre abas/usuários`,
|
|
72
|
+
correcao: 'não guarde: o `@orfeu/angular` mantém o token só em memória e renova pelo cookie do Argos; outra credencial que precise durar fica em memória, num service `providedIn: root`',
|
|
73
|
+
})),
|
|
74
|
+
},
|
|
75
|
+
{
|
|
76
|
+
id: 'rota-sem-operation',
|
|
77
|
+
resumo: '(Python) rota FastAPI sem @operation num arquivo que já usa @operation',
|
|
78
|
+
aceita: ehPy,
|
|
79
|
+
checar(arq) {
|
|
80
|
+
const t = arq.limpo;
|
|
81
|
+
if (!/from\s+orfeu[\w.]*\s+import\s*\(?[^)]*?\boperation\b/.test(t)) return [];
|
|
82
|
+
const out = [];
|
|
83
|
+
const defs = [...t.matchAll(/^[ \t]*(?:async[ \t]+)?def[ \t]+\w+/gm)].map((m) => m.index);
|
|
84
|
+
for (const m of t.matchAll(/^[ \t]*@\w+\.(?:get|post|put|patch|delete|api_route|websocket)\(/gm)) {
|
|
85
|
+
const def = defs.find((d) => d > m.index);
|
|
86
|
+
if (def === undefined) continue;
|
|
87
|
+
const anterior = defs.filter((d) => d < m.index).pop() ?? 0;
|
|
88
|
+
if (/@operation\s*\(/.test(t.slice(anterior, def))) continue;
|
|
89
|
+
out.push({
|
|
90
|
+
linha: arq.linhaDe(m.index + m[0].search(/@/)),
|
|
91
|
+
mensagem: 'rota sem `@operation`: passa sem autenticação, sem usuário e sem auditoria',
|
|
92
|
+
correcao: 'acrescente `@operation(id="dominio:acao", level=Level.X, method=Method.Y)` logo abaixo do decorator de rota (pública de propósito: `level=Level.PUBLIC`)',
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
return out;
|
|
96
|
+
},
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
id: 'rota-sem-guard',
|
|
100
|
+
resumo: '(Node) rota Express sem guard() num arquivo que já usa guard do @orfeu/node',
|
|
101
|
+
aceita: ehJs,
|
|
102
|
+
checar(arq) {
|
|
103
|
+
const t = arq.limpo;
|
|
104
|
+
if (!/['"]@orfeu\/node(?:\/[\w-]+)?['"]/.test(t) || !/\bguard\s*\(/.test(t)) return [];
|
|
105
|
+
const out = [];
|
|
106
|
+
for (const m of t.matchAll(/\b(\w*[Rr]outer|app)\s*\.\s*(get|post|put|patch|delete)\s*\(\s*['"`]/g)) {
|
|
107
|
+
const abre = m.index + m[0].lastIndexOf('(');
|
|
108
|
+
const chamada = t.slice(abre, fechaParen(t, abre) + 1);
|
|
109
|
+
if (!chamada.includes(',') || /\bguard\s*\(/.test(chamada)) continue;
|
|
110
|
+
out.push({
|
|
111
|
+
linha: arq.linhaDe(m.index),
|
|
112
|
+
mensagem: `\`${m[1]}.${m[2]}(...)\` sem \`guard(...)\`: a rota não é protegida nem auditada`,
|
|
113
|
+
correcao: "ponha `guard('area:recurso:acao', Level.X)` na própria linha da rota (pública de propósito: `Level.PUBLIC`)",
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
return out;
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
];
|
|
120
|
+
|
|
121
|
+
process.exitCode = executar({
|
|
122
|
+
skill: 'orfeu',
|
|
123
|
+
descricao: 'Authorization/Bearer e JWT à mão, token em storage, rota FastAPI sem @operation e rota Express sem guard.',
|
|
124
|
+
regras,
|
|
125
|
+
extensoes: [...JS, '.py'],
|
|
126
|
+
});
|
|
@@ -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
|
+
}
|