@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,343 @@
|
|
|
1
|
+
# @trismegisto/spine — guia do shell
|
|
2
|
+
|
|
3
|
+
Escrito para a **API 1.0.0**. Nomes exatos de cada export: `spine-api.md` (gerado do código); receitas
|
|
4
|
+
prontas: `spine-recipes.md`. O conteúdo das telas (componentes `hm-*`, tokens, formulários) é do
|
|
5
|
+
`@trismegisto/angular`: `angular.md`. Sessão, token, `PrivateGuard`, logout e troca de crachá são do
|
|
6
|
+
`@orfeu/angular` — skill **orfeu**.
|
|
7
|
+
|
|
8
|
+
O spine é o **esqueleto pronto** de um app Angular: cabeçalho (marca, busca de telas, apps,
|
|
9
|
+
tema, perfil), menu lateral montado da árvore de rotas do servidor de autorização (Argos), área de trabalho
|
|
10
|
+
em abas (`hm-workspace`), barra da página (título, descrição, trilha, favoritar, copiar link, documentação),
|
|
11
|
+
telas de login/callback/saída/sem permissão/bloqueado, modal, painel lateral e toasts por serviço, painel
|
|
12
|
+
de configurações, tour de boas-vindas, novidades e atalhos de teclado. O app entrega **só as telas**; o resto
|
|
13
|
+
vem do spine.
|
|
14
|
+
|
|
15
|
+
Ele fica na ponta da cadeia `tokens ← icons ← primitives ← core ← angular ← spine` e é **acoplado à
|
|
16
|
+
autenticação** do `@orfeu/angular` (OIDC + PKCE contra o Argos). Não serve a app que não se autentica no
|
|
17
|
+
Argos — para esse caso, monte o shell à mão com o `@trismegisto/angular` (`angular-recipes.md` §1).
|
|
18
|
+
|
|
19
|
+
## 1. Instalação
|
|
20
|
+
|
|
21
|
+
Pacotes, peers e `styles` do `angular.json`: `../SKILL.md` §2. Dependências diretas (vêm sozinhas): `marked` e
|
|
22
|
+
`dompurify` (documentação das telas). `@orfeu/angular` precisa ser **uma cópia só** no app (ver armadilhas).
|
|
23
|
+
|
|
24
|
+
Se as telas tiverem documentação (`document.load` com `import('./README.md')`), o loader de texto em
|
|
25
|
+
`build.options`: `"loader": { ".md": "text" }` + um `src/markdown.d.ts` com
|
|
26
|
+
`declare module '*.md' { const content: string; export default content; }`.
|
|
27
|
+
|
|
28
|
+
## 2. Pontos de entrada
|
|
29
|
+
|
|
30
|
+
| Import | Para quê |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `@trismegisto/spine` | `provideUi`, `SpineConfig`/`SPINE_CONFIG`, `Route` + `routerIdOf`, `applyRuntimeEnvironment`, `SPINE_ADMIN_API`, `provideSpineNews`, i18n (`SPINE_MESSAGES`, `provideSpineMessages`, catálogos), `ThemeService`, `DensityService`, `ThemePresetService`, `SpinePreferencesService`, `SpineQuickAccessService`, logo/favicon (`SpineLogoConfig`, `resolveSpineLogo`, `applySpineFavicon`) |
|
|
33
|
+
| `@trismegisto/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, `ShellOptions`, telas públicas e de estado |
|
|
34
|
+
| `@trismegisto/spine/routing` | `ComponentRoute`, `RouteDocument`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor` + `ROUTE_ID_HEADER`/`CLIENT_ID_HEADER`, `LoggerService`, `ComponentDistributorService`, resolução de cadeia (`resolveRouteChain`, `findFirstNavigable`…) |
|
|
35
|
+
| `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), `SPINE_BRAND`, `provideSettingsSection`, `SpineSettingsService`, `SpineDocsService`, `SpineNewsService`, `OnboardingService`, `ShortcutService` e as peças do layout |
|
|
36
|
+
| `@trismegisto/spine/modal` | `ModalService`, `ModalConfig`, `ModalContent` |
|
|
37
|
+
| `@trismegisto/spine/side-panel` | `SidePanelService`, `SidePanelConfig`, `SidePanelContent` |
|
|
38
|
+
| `@trismegisto/spine/notification` | `NotificationService`, `AlertType`, `Notification` |
|
|
39
|
+
| `@trismegisto/spine/graphql` | `provideGraphql`, `injectGraphqlClient`, `unwrap`, `GraphqlEnvelopeError`, `wsReconnected$`, tipos `GraphqlEndpoint`/`GraphqlEnvelope` |
|
|
40
|
+
| `@trismegisto/spine/auto-service` | `provideAutoService({ adminApi })`, `AutoServiceService`, ids de router do template, `AUTO_SERVICE_SCREENS` |
|
|
41
|
+
| `@trismegisto/spine/audit` | `SpineAuditComponent` (`spine-audit`), `SpineAuditService`, tipos e funções puras da auditoria — **importe só de código lazy** |
|
|
42
|
+
|
|
43
|
+
## 3. Bootstrap
|
|
44
|
+
|
|
45
|
+
### 3.1 `main.ts`
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import { bootstrapApplication } from '@angular/platform-browser';
|
|
49
|
+
import { applyRuntimeEnvironment } from '@trismegisto/spine';
|
|
50
|
+
import { AppComponent } from './app/app.component';
|
|
51
|
+
import { appConfig } from './app/app.config';
|
|
52
|
+
import { environment } from './environments/environment';
|
|
53
|
+
|
|
54
|
+
applyRuntimeEnvironment(environment); // ANTES do bootstrap
|
|
55
|
+
bootstrapApplication(AppComponent, appConfig).catch((err) => console.error(err));
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`applyRuntimeEnvironment(environment)` deriva do endereço em que o app está rodando:
|
|
59
|
+
- **sempre:** `authorizationServer.redirectUrl = <origem><base href>/callback` e
|
|
60
|
+
`postLogoutRedirectUri = <origem><base href>/logoff` (o servidor exige `redirect_uri` absoluto e o app pode
|
|
61
|
+
viver sob um prefixo);
|
|
62
|
+
- **sem porta na URL** (atrás de proxy reverso): `authority = <origem>/argos` e cada endpoint GraphQL **ainda
|
|
63
|
+
sem valor** (vazio ou contendo `CHANGE_ME`) vira `<origem><base href>/graphql` (HTTP e WS). URL explícita no
|
|
64
|
+
environment sempre vence.
|
|
65
|
+
Devolve `{ origin, basePath, behindProxy, unset }` para o que for específico do app.
|
|
66
|
+
|
|
67
|
+
### 3.2 `app.config.ts`
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
|
|
71
|
+
import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
|
|
72
|
+
import { provideRouter } from '@angular/router';
|
|
73
|
+
import { provideAuth } from '@orfeu/angular/core';
|
|
74
|
+
import { provideUi } from '@trismegisto/spine';
|
|
75
|
+
import { APP_ROUTES, provideShell } from '@trismegisto/spine/shell';
|
|
76
|
+
import { provideAutoService } from '@trismegisto/spine/auto-service';
|
|
77
|
+
import { provideGraphql } from '@trismegisto/spine/graphql';
|
|
78
|
+
import { components } from './features/features.routes';
|
|
79
|
+
import { environment } from '../environments/environment';
|
|
80
|
+
import packageInfo from '../../package.json';
|
|
81
|
+
|
|
82
|
+
export const appConfig: ApplicationConfig = {
|
|
83
|
+
providers: [
|
|
84
|
+
provideZoneChangeDetection({ eventCoalescing: true }),
|
|
85
|
+
provideHttpClient(withInterceptorsFromDi()), // obrigatório: ativa o RouteIdInterceptor
|
|
86
|
+
provideUi({ clientId: environment.authorizationServer.clientId, appName: 'Meu App' }),
|
|
87
|
+
provideRouter(APP_ROUTES),
|
|
88
|
+
provideAuth(environment.authorizationServer),
|
|
89
|
+
provideAutoService({ adminApi: environment.adminApi }), // opcional: telas de auto-serviço
|
|
90
|
+
provideShell({ appComponents: components, packageInfo }),
|
|
91
|
+
provideGraphql({ endpoints: environment.graphql }), // opcional: só com backends GraphQL
|
|
92
|
+
],
|
|
93
|
+
};
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`packageInfo` precisa de `"resolveJsonModule": true` no `tsconfig` (o painel "Sobre" mostra nome/versão/dependências).
|
|
97
|
+
|
|
98
|
+
O que cada provider faz:
|
|
99
|
+
|
|
100
|
+
- **`provideUi(config?: SpineConfig)`** — registra o catálogo de ícones **inteiro** (`HERMES_ICONS`; o app
|
|
101
|
+
não precisa de `provideHermesIcons`), aplica tema/família/densidade/fonte no `<body>` (`ThemeService`),
|
|
102
|
+
fornece `SPINE_CONFIG` e usa `hermes_<clientId>` como prefixo de **todas** as chaves salvas (tema, menu
|
|
103
|
+
lateral, abas do workspace, idioma, fuso, novidades, favoritos…): apps na mesma origem não misturam
|
|
104
|
+
preferências. Aplica `favicon` no bootstrap se configurado. Opções de `SpineConfig`:
|
|
105
|
+
|
|
106
|
+
| Campo | Padrão | Efeito |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| `clientId` (obrigatório) | — | o `clientId` do app no Argos; prefixo de armazenamento e `X-Client-Id` |
|
|
109
|
+
| `appName` | `'Hermes'` | nome ao lado do logo |
|
|
110
|
+
| `logo` | `'assets/images/logo.svg'` | `string`, `{ light, dark?, alt? }` ou `false` (sem imagem). 404 = imagem some, fica o nome |
|
|
111
|
+
| `showAppName` | `true` | com `false`, o nome só aparece quando não há logo visível |
|
|
112
|
+
| `favicon` | — | atualiza/cria o `<link rel="icon">`; sem ele vale o do `index.html` |
|
|
113
|
+
| `technicalDocs` | `isDevMode()` | mostra a aba "Especificação técnica" da documentação das telas |
|
|
114
|
+
|
|
115
|
+
- **`provideRouter(APP_ROUTES)`** — `APP_ROUTES` = `PUBLIC_ROUTES` (`/login`, `/callback`, `/logoff`,
|
|
116
|
+
`/blocked`, `''` → `login`) + `{ path: '', component: LayoutComponent, canActivate/canActivateChild:
|
|
117
|
+
[PrivateGuard], children: PRIVATE_ROUTES }` + `**` → `''`. `PRIVATE_ROUTES` = `/no-permission` (lazy),
|
|
118
|
+
`''` → `home` e `**` com `ViewGuard`. Precisa de página pública fora do login? Componha as mesmas peças à
|
|
119
|
+
mão (receitas §2).
|
|
120
|
+
- **`provideAuth(environment.authorizationServer, options?)`** (do `@orfeu/angular/core`) — sessão, token,
|
|
121
|
+
`/view` (árvore de rotas) e `connectionState$`. `authorizationServer` = `{ authority, realmId, clientId,
|
|
122
|
+
redirectUrl, postLogoutRedirectUri, scope }`. Com rota pública em `/`, passe `{ eagerInit: false }` para
|
|
123
|
+
não esperar a rede de autenticação no primeiro render.
|
|
124
|
+
- **`provideShell({ appComponents, packageInfo })`** — contribui com as telas do app para `COMPONENT_ROUTES`
|
|
125
|
+
(`multi`), registra o `RouteIdInterceptor` em `HTTP_INTERCEPTORS` e fornece `APP_PACKAGE_INFO`. Lança erro
|
|
126
|
+
se um `id` do app repetir um id das telas base do shell.
|
|
127
|
+
- **`provideAutoService({ adminApi })`** — liga as 5 telas do auto-serviço (Início, Grupos, Aplicações,
|
|
128
|
+
Cliente, Auditoria) pelo `source_template_router_id` do template do Argos, todas **lazy**, e fornece
|
|
129
|
+
`SPINE_ADMIN_API` (usado também pelo painel de configurações para os tokens de aplicação). O app não declara
|
|
130
|
+
nada disso em `features.routes.ts`: basta o client estar vinculado ao template de auto-serviço no Argos.
|
|
131
|
+
Sem auto-serviço, o painel de configurações ainda pode listar tokens se o app fornecer
|
|
132
|
+
`{ provide: SPINE_ADMIN_API, useValue: environment.adminApi }`; sem isso, essa parte se esconde.
|
|
133
|
+
- **`provideGraphql({ endpoints })`** — um cliente Apollo nomeado por backend (seção 6).
|
|
134
|
+
|
|
135
|
+
### 3.3 Componente raiz
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
@Component({ selector: 'app-root', imports: [RouterOutlet], template: '<router-outlet />' })
|
|
139
|
+
export class AppComponent {}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Só isso. O tema já está no `<body>`: **não** ponha `hermesTheme`, `hm-header`, `hm-sidebar` nem
|
|
143
|
+
`hm-toast-stack` no app — o `spine-layout` já monta cabeçalho, aviso de conexão, menu, workspace,
|
|
144
|
+
`spine-notification`, `spine-modal`, `spine-side-panel`, painel de atalhos, configurações, documentação,
|
|
145
|
+
novidades e tour.
|
|
146
|
+
|
|
147
|
+
### 3.4 Sessão e aviso de conexão (`@orfeu/angular`)
|
|
148
|
+
|
|
149
|
+
- `/login` chama `authorize()`; `/callback` usa `handleCallback()` (confere state/verifier, volta para a URL
|
|
150
|
+
pedida antes do login; `login_required` da reautorização silenciosa segue para o login interativo).
|
|
151
|
+
Callback recusado **nunca desloga**: com sessão viva volta para a URL de retorno, sem sessão mostra erro com
|
|
152
|
+
"Entrar novamente".
|
|
153
|
+
- `spine-connection-banner` (entre o cabeçalho e o corpo) mostra `hm-alert` em faixa quando
|
|
154
|
+
`connectionState$` está `offline`, `reconnecting` ou `reauthorizing`, e "Entrar novamente" (chama
|
|
155
|
+
`authorize(urlAtual)`, sem logout) quando `reauthorizationRequired$` pede. Textos em `SpineMessages.session`.
|
|
156
|
+
O app não faz nada para ter isso.
|
|
157
|
+
- Acesso: token sem nenhum crachá (`badges` vazio) → `/blocked` (tela cheia, fora do layout); crachá mas
|
|
158
|
+
`/view` sem rotas → `/no-permission`. As duas telas saem sozinhas quando a situação muda (F5, renovação do
|
|
159
|
+
token, troca de crachá).
|
|
160
|
+
- Logout: menu do perfil e `Mod+Shift+L` já chamam `AuthorizationService.logout()`.
|
|
161
|
+
|
|
162
|
+
## 4. Navegação: telas identificadas pelo router do Argos
|
|
163
|
+
|
|
164
|
+
A árvore de navegação **não está no app**: vem do `/view` do Argos (`ViewService.currentView.routes`, tipo
|
|
165
|
+
`Route[]`), já recortada pelo que a pessoa pode ver. Níveis: módulo (nível 1) → grupos → página (nó `'page'`).
|
|
166
|
+
|
|
167
|
+
- **Identidade da tela = `router_id`** do nó `'page'` (`web.router` do client: a posição da tela na
|
|
168
|
+
navegação). Leia sempre com **`routerIdOf(route)`** (`router_id ?? route_id` — Argos antigo só mandava
|
|
169
|
+
`route_id`, com o mesmo valor). **Nunca** use `routed_id` (`web.routes.route_id`) para achar tela: a rota é
|
|
170
|
+
só nome/ícone/path e se repete em vários routers.
|
|
171
|
+
- O app registra cada tela por esse id em `ComponentRoute.id` (receitas §3). Ordem de casamento:
|
|
172
|
+
`id` do app → `source_template_router_id` (router do template, usado por pacotes plugáveis como o
|
|
173
|
+
auto-serviço). Customização do client vence o componente genérico do pacote.
|
|
174
|
+
- Sem entrada para o router (ou `import()` quebrado): o painel mostra "tela não publicada" com o código do
|
|
175
|
+
router. Chunk que sumiu do servidor (build novo com a aba aberta, `isChunkLoadError`): página pronta
|
|
176
|
+
`hm-state-page kind="outdated"` ("Nova versão disponível") com o botão "Recarregar" (`window.location.reload()`).
|
|
177
|
+
Não há nada a configurar; em telas próprias que fazem `import()` dinâmico, use `isChunkLoadError(err)` para
|
|
178
|
+
mostrar a mesma página (`isChunkLoadError` sai de `@trismegisto/spine/routing`).
|
|
179
|
+
- **Título e descrição** da tela aparecem na `spine-page-bar` do painel: título = `route_display_name`,
|
|
180
|
+
descrição = `Route.description` (`web.router.description`, editada no Argos), ícone = `route_icon` (ou o do
|
|
181
|
+
módulo). **A tela não repete título nem descrição** no próprio template — comece direto pelo conteúdo
|
|
182
|
+
(barra de ferramentas, filtros, grade). O `document.title` também vem do router.
|
|
183
|
+
- A barra da página também traz favoritar (`SpineQuickAccessService`, chave = endereço `route_redirect`),
|
|
184
|
+
copiar link, trilha (`hm-breadcrumb`) e o botão de documentação quando a tela tem `document`.
|
|
185
|
+
- Nó organizacional (com filhos, sem conteúdo): navegar até ele desce sozinho para o primeiro filho navegável.
|
|
186
|
+
- **Workspace em abas e painéis:** cada aba/painel resolve a própria URL (`resolveSpineRoute`) e monta a tela
|
|
187
|
+
com `ngComponentOutlet`. Consequências para a tela: ela **não recebe inputs** nem tem `ActivatedRoute`
|
|
188
|
+
próprio (o `Router` só conhece a URL do painel focado); as abas ficam vivas (`keepAlive`), então trocar de
|
|
189
|
+
aba **não destrói** a tela; links internos (`routerLink`/`href` para outro `route_redirect`) funcionam —
|
|
190
|
+
num painel não focado, o spine os intercepta e navega naquele painel.
|
|
191
|
+
- Busca do cabeçalho (`Mod+K`): procura nas telas da árvore da pessoa; nada a configurar.
|
|
192
|
+
|
|
193
|
+
## 5. Chamadas HTTP: `X-Route-Id` e `X-Client-Id`
|
|
194
|
+
|
|
195
|
+
`provideShell` registra o `RouteIdInterceptor` (interceptor **de classe**, via `HTTP_INTERCEPTORS`). Ele
|
|
196
|
+
acrescenta em **toda** requisição do `HttpClient`:
|
|
197
|
+
- `X-Route-Id` = a **rota** da página do painel focado (`LoggerService.routeId` = `routed_id` do nó `'page'`,
|
|
198
|
+
não o `router_id`). Nó sem router (grupo) não manda o cabeçalho. É marca de correlação para os logs de
|
|
199
|
+
operação/auditoria do Orfeu, nunca usada para permissão;
|
|
200
|
+
- `X-Client-Id` = `SpineConfig.clientId`.
|
|
201
|
+
Cabeçalho já presente na requisição não é sobrescrito.
|
|
202
|
+
|
|
203
|
+
**Exige `provideHttpClient(withInterceptorsFromDi())`** — sem `withInterceptorsFromDi()` o Angular ignora o
|
|
204
|
+
interceptor em silêncio e nenhum evento de auditoria sai com tela/app.
|
|
205
|
+
|
|
206
|
+
O interceptor **não** põe o token. Nas APIs REST do app, mande `x-access-token` com
|
|
207
|
+
`inject(AuthorizationService).getToken()` (receitas §4; detalhes na skill orfeu).
|
|
208
|
+
|
|
209
|
+
## 6. GraphQL (`@trismegisto/spine/graphql`)
|
|
210
|
+
|
|
211
|
+
```ts
|
|
212
|
+
// environment.ts
|
|
213
|
+
graphql: { principal: { namedClient: 'principal', http: 'CHANGE_ME', ws: 'CHANGE_ME' } }
|
|
214
|
+
// app.config.ts
|
|
215
|
+
provideGraphql({ endpoints: environment.graphql })
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Tipo de cada entrada: `GraphqlEndpoint` (`namedClient`, `http`, `ws?` — sem `ws`, sem subscription). Importe o
|
|
219
|
+
tipo daqui; não o redeclare. O comportamento é fixo de propósito (sem opções):
|
|
220
|
+
- token do Orfeu em `x-access-token` no HTTP e no `connection_init` do WebSocket (na raiz e em `headers`),
|
|
221
|
+
junto de `routeId`/`clientId` para a auditoria das subscriptions;
|
|
222
|
+
- HTTP em lote (`HttpBatchLink`), `fetchPolicy: 'no-cache'`, `errorPolicy` padrão (`none`);
|
|
223
|
+
- subscription por `graphql-ws`, só no navegador, reconexão ilimitada (backoff até 30 s); 401/4401/4403
|
|
224
|
+
recria os sockets; aba que volta de mais de 60 s em segundo plano também. `wsReconnected$` emite o
|
|
225
|
+
`namedClient` a cada **re**conexão — use para ressincronizar (receitas §6);
|
|
226
|
+
- **toast automático do envelope** `{ status, message, data }` de cada campo raiz: mutation avisa sempre que
|
|
227
|
+
falha (texto do catálogo se não vier `message`) e no sucesso quando o backend manda `message`; query só
|
|
228
|
+
na falha e nunca em 404; subscription nunca. 2xx = sucesso, 3xx = atenção, 4xx/5xx = erro. Silencie uma
|
|
229
|
+
operação com `context: { silenceEnvelope: true }` (ou `{ silenceEnvelope: true }` no `GraphqlClient`).
|
|
230
|
+
|
|
231
|
+
Nos serviços de domínio:
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
private readonly gql = injectGraphqlClient('principal'); // contexto de injeção
|
|
235
|
+
async listTeams() {
|
|
236
|
+
return unwrap((await this.gql.query(ListTeamsDocument)).teams); // TypedDocumentNode do codegen
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
- `unwrap(envelope)` devolve `data` ou **lança** `GraphqlEnvelopeError` (`status` preservado; `message` do
|
|
241
|
+
backend) quando o envelope não veio (resolver estourou) ou o status não é de sucesso (número fora de 2xx,
|
|
242
|
+
texto `error`/`failed`/`failure`/`fail`). **O status vem no payload, não no HTTP**: HTTP 200 pode trazer
|
|
243
|
+
`status: 403`. Nunca leia `data` sem `unwrap` — é o que transforma "sem permissão" em "lista vazia".
|
|
244
|
+
- Erro de transporte ou `errors[]` do GraphQL rejeita a Promise; resposta sem `data` também.
|
|
245
|
+
- Trate o erro como **estado da tela** (`resource().error()`, `catch` → `hm-alert`/`hm-state-screen`), não
|
|
246
|
+
`console.error` nem `?? []`. Decida por `err.status` (403 sem acesso, 404 vazio, 5xx tentar de novo). Mostre
|
|
247
|
+
`message` como texto, nunca por `innerHTML`.
|
|
248
|
+
- Utilitários: `isEnvelopeOk(status)`, `envelopesOf(data)`, `failedEnvelopes(data)`.
|
|
249
|
+
|
|
250
|
+
## 7. Serviços do shell para as telas
|
|
251
|
+
|
|
252
|
+
| Preciso de… | Use |
|
|
253
|
+
|---|---|
|
|
254
|
+
| Toast | `NotificationService.addNotification({ timer, hermesAlertType, message, hermesAlertClosable? })` (`@trismegisto/spine/notification`). `timer` em segundos; `hermesAlertType` = `AlertType` ou um status HTTP (vira tipo por faixa). A mensagem passa por redação de segredos. `processErrorNotification()` = erro genérico do catálogo |
|
|
255
|
+
| Modal com componente | `ModalService.open<R, D>({ title, component, data, size: 'sm'\|'md'\|'lg'\|'xl', closable, showActions })` → `Observable<R \| null>` (`null` = cancelado/substituído). O componente implementa `ModalContent` (`getResult()`, `isValid?()`), recebe `data` por `readonly data = input<D>()` e o botão Confirmar fica desabilitado enquanto `isValid()` for falso. Só um aberto por vez |
|
|
256
|
+
| Modal só texto | `ModalService.open({ title, text })` |
|
|
257
|
+
| Painel lateral | `SidePanelService.open(...)` — mesma API (`SidePanelContent` = `ModalContent`), `size` aceita também `'full'` |
|
|
258
|
+
| Estado "salvando" no Confirmar | `modalService.setState(HermesLoadingState.LOADING)` (`@trismegisto/angular`) |
|
|
259
|
+
| Diálogo de confirmação simples | `HermesDialogService.confirm(...)` do `@trismegisto/angular` (não precisa do spine) |
|
|
260
|
+
| Abrir configurações | `SpineSettingsService.open(SPINE_SETTINGS_KEYS.appearance)` ou link `?settings=aparencia` |
|
|
261
|
+
| Abrir documentação | `SpineDocsService.openIndex()` / `openForRoute(routerId)` |
|
|
262
|
+
| Reabrir tour / novidades | `OnboardingService.restart()` / `SpineNewsService.showAll()` |
|
|
263
|
+
| Fuso e idioma da pessoa | `SpinePreferencesService.effectiveTimeZone()` (sinal; IANA) e `language()` |
|
|
264
|
+
| Página atual | `LoggerService.page`, `.routerId`, `.routeId` (`@trismegisto/spine/routing`) |
|
|
265
|
+
| Tema/densidade por código | `ThemeService.setMode('light'\|'dark'\|'system')`, `setTheme`, `DensityService.setDensity('comfortable'\|'compact')`, `toggleDensity()`, `ThemePresetService.setPreset(family)` — sincronizam entre abas. Em geral **não precisa**: o painel de configurações já oferece tudo |
|
|
266
|
+
|
|
267
|
+
Atalhos globais já registrados: `G H` (início), `G 1…9` (favoritos), `Mod+K` (busca), `Mod+,`
|
|
268
|
+
(configurações), `Mod+.` (tema), `Mod+Shift+F` (tela cheia), `Mod+Shift+L` (sair), `?` (painel de atalhos).
|
|
269
|
+
Atalho de tela: diretiva `hmShortcut` ou `HermesShortcutService.register` do `@trismegisto/angular` — aparece
|
|
270
|
+
sozinho no painel `?`. Não reuse essas combinações.
|
|
271
|
+
|
|
272
|
+
## 8. Auto-serviço e auditoria
|
|
273
|
+
|
|
274
|
+
- **Auto-serviço** (`provideAutoService`): as telas casam por `source_template_router_id`
|
|
275
|
+
(`AUTO_SERVICE_*_TEMPLATE_ROUTER_ID`) e ficam em chunks próprios (`AUTO_SERVICE_SCREENS`). As classes das
|
|
276
|
+
telas **não são exportadas** de propósito. `AutoServiceService` expõe o HTTP (`{adminApi}/auto-service/...`)
|
|
277
|
+
para quem precisar.
|
|
278
|
+
- **Auditoria** (`@trismegisto/spine/audit`): `<spine-audit scope="admin" />` (todos os apps,
|
|
279
|
+
`{adminApi}/admin/audit/*`) ou `<spine-audit scope="client" [clientId]="id" />` (apps do projeto do client,
|
|
280
|
+
`{adminApi}/auto-service/:clientId/audit/*`, recorte no servidor). `adminApi` pelo input `[adminApi]` ou
|
|
281
|
+
pelo `SPINE_ADMIN_API`. Inclui período rápido, filtros (com filtros salvos), KPIs, linha do tempo,
|
|
282
|
+
rankings paginados, tabela paginada por cursor e detalhe/cadeia (trace) num `hm-drawer`; estados de
|
|
283
|
+
carregando, vazio, erro, janela > 31 dias, filtro inválido e 403. No auto-serviço ela já aparece sozinha.
|
|
284
|
+
**Este ponto de entrada exporta o componente: importe-o só de código lazy** (`loadComponent`, `import()`,
|
|
285
|
+
`@defer`) — receitas §8.
|
|
286
|
+
|
|
287
|
+
## 9. Idiomas, tema e densidade
|
|
288
|
+
|
|
289
|
+
- Textos do spine: catálogo `SpineMessages` com pt-BR, en e es **embutidos**. O idioma ativo é o do
|
|
290
|
+
`HermesI18nService` do `@trismegisto/angular`: configure com `provideHermesI18n({ locale: 'en' })` e troque com
|
|
291
|
+
`setLocale` — lib e spine mudam juntos, sem recarregar. A pessoa também troca idioma e fuso no painel de
|
|
292
|
+
configurações (`SpinePreferencesService`, salvo por app e sincronizado entre abas).
|
|
293
|
+
- Sobrescrever textos ou acrescentar idioma: `provideSpineMessages({ override: { header: { search: '…' } },
|
|
294
|
+
catalogs: { fr: MEU_CATALOGO_FR } })` (`override` vale em qualquer idioma; `catalogs` é um `SpineMessages`
|
|
295
|
+
completo por idioma — um idioma novo precisa também do catálogo da lib, `provideHermesI18n({ catalogs })`,
|
|
296
|
+
senão só os textos do spine mudam). Ler em código: `inject(SPINE_MESSAGES).secao.chave` (vivo, segue
|
|
297
|
+
`setLocale`); fora de injeção, `currentSpineMessages()`. Textos com `{param}`: `formatMessage` de
|
|
298
|
+
`@trismegisto/primitives`.
|
|
299
|
+
- Tema, família (12 paletas), densidade (confortável/compacto) e fonte vêm do Hermes, aplicados no `<body>` e
|
|
300
|
+
persistidos por app; a pessoa escolhe em Configurações › Aparência. As telas só precisam usar tokens
|
|
301
|
+
`--hm-*` e a escala de espaço (`angular.md` §2) para acompanhar tudo isso.
|
|
302
|
+
- **Famílias e fontes próprias do app** (`provideUi({ clientId, theme: { families, replace, defaultFamily,
|
|
303
|
+
fonts, replaceFonts, defaultFont } })`): `../SKILL.md` §4. Não registre `HERMES_THEME_CONFIG` à mão — o
|
|
304
|
+
`provideUi` já compõe com o prefixo do app.
|
|
305
|
+
|
|
306
|
+
## 10. Regras e armadilhas
|
|
307
|
+
|
|
308
|
+
1. **`provideHttpClient(withInterceptorsFromDi())`.** O `RouteIdInterceptor` é de classe; sem isso ele não roda
|
|
309
|
+
e a auditoria perde tela/app — sem erro nenhum.
|
|
310
|
+
2. **Telas sempre lazy.** `ComponentRoute.load` é `() => import('./x.component').then((m) => m.X)`. Nunca
|
|
311
|
+
importe a classe de uma tela estaticamente em `features.routes.ts`, `app.config.ts` ou serviço global.
|
|
312
|
+
Um `features.routes.spec.ts` confere que todo `load()` resolve e que os `id` são UUID únicos, sem
|
|
313
|
+
diferenciar maiúsculas (receitas §14).
|
|
314
|
+
3. **Auditoria e auto-serviço continuam lazy.** Não importe `@trismegisto/spine/audit` em código do bundle
|
|
315
|
+
inicial (só em rota/`import()`/`@defer`). As telas do auto-serviço nem são exportadas; não tente
|
|
316
|
+
alcançá-las por caminho interno. (O pacote confere isso no próprio build com `scripts/check-lazy.mjs`: um
|
|
317
|
+
`export` estático de tela faria o rollup trocar o `import()` por `Promise.resolve()` e colar a tela no
|
|
318
|
+
bundle inicial de todo app.)
|
|
319
|
+
4. **`COMPONENT_ROUTES` é `multi`.** Contribua pelo `provideShell` (ou com `{ provide: COMPONENT_ROUTES,
|
|
320
|
+
useValue: [...], multi: true }`). Sem `multi: true` o Angular lança erro de provider inconsistente.
|
|
321
|
+
5. **Id da tela = `router_id`** (`routerIdOf`). `routed_id`/`web.routes.route_id` não acha componente; é o que
|
|
322
|
+
vai no `X-Route-Id`. `ComponentRoute.route_id`/`component` são nomes antigos depreciados (use `id`/`load`).
|
|
323
|
+
6. **Uma cópia do `@orfeu/angular`.** App e spine precisam resolver o mesmo pacote; duas cópias (versões
|
|
324
|
+
diferentes, `file:` duplicado, SDK antigo no app) dão `NullInjectorError` em `AUTH_CONFIG` ou uma segunda
|
|
325
|
+
sessão. Confira com `npm ls @orfeu/angular`.
|
|
326
|
+
7. **Não monte o shell de novo.** Nada de `hermesTheme`, `hm-header`, `hm-sidebar`, `hm-toast-stack`, tela de
|
|
327
|
+
login/callback ou guard de rota próprios: o spine já tem. Toast é o `NotificationService`.
|
|
328
|
+
8. **A tela não repete título/descrição** — vêm do router, na barra da página. Para mudar o texto, edite o
|
|
329
|
+
router no Argos.
|
|
330
|
+
9. **Tela não depende de `ActivatedRoute`/inputs** (montada por `ngComponentOutlet` no painel) e sobrevive à
|
|
331
|
+
troca de aba (`keepAlive`): recarregue dados por ação da pessoa, `wsReconnected$` ou sinal, não por
|
|
332
|
+
`ngOnInit` a cada visita.
|
|
333
|
+
10. **Envelope GraphQL sempre por `unwrap`.** Não confie no HTTP 200.
|
|
334
|
+
11. **Detecção de mudanças:** os apps de referência usam `provideZoneChangeDetection`; parte do shell ainda usa
|
|
335
|
+
a estratégia `Eager` e `NgZone`. Funcionamento sem zone.js não é garantido.
|
|
336
|
+
12. **Documentação de tela** é markdown cru importado como texto (loader `.md: "text"`); o texto vai no chunk
|
|
337
|
+
da tela e o índice só lista telas que a pessoa enxerga.
|
|
338
|
+
13. **Chaves salvas** usam o `clientId`: trocar o `clientId` de um app "zera" tema, abas, favoritos e tour.
|
|
339
|
+
14. **Logo** é arquivo do app (`src/assets/images/logo.svg` por convenção), legível sobre o fundo escuro do
|
|
340
|
+
cabeçalho **nos dois temas**; marca em componente via `SPINE_BRAND` (sem link/botão dentro).
|
|
341
|
+
|
|
342
|
+
Se você está **desenvolvendo o próprio spine** (não um app consumidor), siga as convenções do repositório
|
|
343
|
+
dele; este guia é para quem consome o pacote.
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Verificador da skill `trismegisto`: interface com @trismegisto/* num app Angular.
|
|
3
|
+
// node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/trismegisto/scripts/checar.mjs)
|
|
4
|
+
// Confere contra os catálogos gerados do código das libs (`../references/catalogo/*.json`).
|
|
5
|
+
// Exceção: `// acropole-ignore-next-line <regra> -- motivo` (ou `<!-- ... -->` no HTML) na linha anterior.
|
|
6
|
+
import fs from 'node:fs';
|
|
7
|
+
import path from 'node:path';
|
|
8
|
+
import { fileURLToPath } from 'node:url';
|
|
9
|
+
import { estilos, executar, templates } from './nucleo.mjs';
|
|
10
|
+
|
|
11
|
+
const CATALOGO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'references', 'catalogo');
|
|
12
|
+
const ler = (nome) => JSON.parse(fs.readFileSync(path.join(CATALOGO, nome), 'utf8'));
|
|
13
|
+
const TOKENS = new Set(ler('tokens.json'));
|
|
14
|
+
const ICONES = new Set(ler('icones.json'));
|
|
15
|
+
const SELETORES = ler('seletores.json');
|
|
16
|
+
|
|
17
|
+
/** Elemento `hm-*` → { inputs de ícone, outputs }. Um seletor pode listar vários elementos (`a, b[x]`). */
|
|
18
|
+
const ELEMENTOS = new Map();
|
|
19
|
+
for (const s of SELETORES) {
|
|
20
|
+
for (const parte of s.seletor.split(',')) {
|
|
21
|
+
const tag = parte.trim().match(/^([a-z][\w-]*)/)?.[1];
|
|
22
|
+
if (!tag || !tag.startsWith('hm-')) continue;
|
|
23
|
+
const atual = ELEMENTOS.get(tag) ?? { icones: new Set(), outputs: new Set() };
|
|
24
|
+
for (const i of s.inputs) {
|
|
25
|
+
if ((/^(icon|icon(Start|End)|\w+Icon)$/.test(i.nome) && /\bstring\b/.test(i.tipo)) || (tag === 'hm-icon' && i.nome === 'shape')) atual.icones.add(i.nome);
|
|
26
|
+
}
|
|
27
|
+
for (const o of s.outputs) atual.outputs.add(o);
|
|
28
|
+
ELEMENTOS.set(tag, atual);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Distância de edição (para sugerir o nome mais próximo). */
|
|
33
|
+
function distancia(a, b) {
|
|
34
|
+
const d = Array.from({ length: a.length + 1 }, (_, i) => [i]);
|
|
35
|
+
for (let j = 1; j <= b.length; j++) d[0][j] = j;
|
|
36
|
+
for (let i = 1; i <= a.length; i++) {
|
|
37
|
+
for (let j = 1; j <= b.length; j++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
38
|
+
}
|
|
39
|
+
return d[a.length][b.length];
|
|
40
|
+
}
|
|
41
|
+
function parecido(nome, conjunto) {
|
|
42
|
+
if (nome.length < 4) return null;
|
|
43
|
+
let melhor = null;
|
|
44
|
+
let menor = Infinity;
|
|
45
|
+
for (const c of conjunto) {
|
|
46
|
+
const dist = distancia(nome, c);
|
|
47
|
+
if (dist < menor) [melhor, menor] = [c, dist];
|
|
48
|
+
}
|
|
49
|
+
return melhor && menor <= Math.max(2, Math.floor(nome.length / 3)) ? melhor : null;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Tags `<hm-*>` de um trecho de template, com atributos e a posição de cada um. */
|
|
53
|
+
function* tagsHm(trecho) {
|
|
54
|
+
const re = /<(hm-[a-z0-9-]*[a-z0-9])(?![\w-])/g;
|
|
55
|
+
let m;
|
|
56
|
+
while ((m = re.exec(trecho))) {
|
|
57
|
+
let i = re.lastIndex;
|
|
58
|
+
let aspas = '';
|
|
59
|
+
for (; i < trecho.length; i++) {
|
|
60
|
+
const ch = trecho[i];
|
|
61
|
+
if (aspas) {
|
|
62
|
+
if (ch === aspas) aspas = '';
|
|
63
|
+
} else if (ch === '"' || ch === "'") aspas = ch;
|
|
64
|
+
else if (ch === '>') break;
|
|
65
|
+
}
|
|
66
|
+
const corpo = trecho.slice(re.lastIndex, i);
|
|
67
|
+
const atributos = [];
|
|
68
|
+
for (const a of corpo.matchAll(/([^\s=/>"']+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)) {
|
|
69
|
+
atributos.push({ nome: a[1], valor: a[2] ?? a[3] ?? a[4], pos: re.lastIndex + a.index });
|
|
70
|
+
}
|
|
71
|
+
yield { tag: m[1], pos: m.index, atributos };
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const sugestao = (nome, conjunto, padrao) => {
|
|
76
|
+
const s = parecido(nome, conjunto);
|
|
77
|
+
return s ? `use \`${s}\`? ${padrao}` : padrao;
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
const regras = [
|
|
81
|
+
{
|
|
82
|
+
id: 'cor-cravada',
|
|
83
|
+
resumo: 'cor #hex/rgb()/hsl() cravada em CSS de componente/tela (use token --hm-*)',
|
|
84
|
+
aceita: (a) => ['.css', '.scss', '.less', '.ts'].includes(a.ext),
|
|
85
|
+
checar(arq) {
|
|
86
|
+
const out = [];
|
|
87
|
+
for (const seg of estilos(arq)) {
|
|
88
|
+
for (const d of seg.texto.matchAll(/(\$?[\w-]+)\s*:\s*([^;{}]*)(?=[;}])/g)) {
|
|
89
|
+
const prop = d[1];
|
|
90
|
+
if (prop.startsWith('--hm-')) continue; // definição de token (tema/família próprios)
|
|
91
|
+
let valor = d[2];
|
|
92
|
+
if (/url\(/i.test(valor)) continue;
|
|
93
|
+
// Fallback dentro de var() não é a cor usada; o que importa é o token.
|
|
94
|
+
valor = valor.replace(/var\((?:[^()]|\([^()]*\))*\)/g, (v) => ' '.repeat(v.length));
|
|
95
|
+
const cor = valor.match(/(?:^|[^\w&#-])(#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4}))(?![\w-])|\b((?:rgba?|hsla?)\(\s*[\d.])/);
|
|
96
|
+
if (!cor) continue;
|
|
97
|
+
const idx = seg.inicio + d.index + d[0].indexOf(':') + 1 + (cor.index ?? 0);
|
|
98
|
+
out.push({
|
|
99
|
+
linha: arq.linhaDe(idx),
|
|
100
|
+
mensagem: `cor cravada \`${(cor[1] ?? cor[2]).replace(/\(\s*[\d.]$/, '(…)')}\` em \`${prop}\`: não acompanha tema escuro, família nem alto contraste`,
|
|
101
|
+
correcao: 'use um token `var(--hm-*)` (texto, superfície, borda, status; séries: `--hm-data-*`) — grupos em references/angular.md §2',
|
|
102
|
+
});
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
return out;
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
id: 'token-inexistente',
|
|
110
|
+
resumo: 'var(--hm-x) sem fallback com token que não existe',
|
|
111
|
+
aceita: (a) => ['.css', '.scss', '.less', '.ts', '.html'].includes(a.ext),
|
|
112
|
+
checar(arq, ctx) {
|
|
113
|
+
const out = [];
|
|
114
|
+
for (const m of arq.limpo.matchAll(/var\(\s*(--hm-[a-z0-9-]*[a-z0-9])\s*\)/g)) {
|
|
115
|
+
if (TOKENS.has(m[1]) || ctx.tokensDoApp.has(m[1])) continue;
|
|
116
|
+
out.push({
|
|
117
|
+
linha: arq.linhaDe(m.index),
|
|
118
|
+
mensagem: `token \`${m[1]}\` não existe no @trismegisto/tokens (o valor some sem erro)`,
|
|
119
|
+
correcao: sugestao(m[1], TOKENS, 'confira o nome em references/catalogo/tokens.json'),
|
|
120
|
+
});
|
|
121
|
+
}
|
|
122
|
+
return out;
|
|
123
|
+
},
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
id: 'seletor-inexistente',
|
|
127
|
+
resumo: 'elemento <hm-*> que não existe no catálogo',
|
|
128
|
+
aceita: (a) => a.ext === '.html' || a.ext === '.ts',
|
|
129
|
+
checar(arq) {
|
|
130
|
+
const out = [];
|
|
131
|
+
for (const seg of templates(arq)) {
|
|
132
|
+
for (const t of tagsHm(seg.texto)) {
|
|
133
|
+
if (ELEMENTOS.has(t.tag)) continue;
|
|
134
|
+
out.push({
|
|
135
|
+
linha: arq.linhaDe(seg.inicio + t.pos),
|
|
136
|
+
mensagem: `\`<${t.tag}>\` não existe no Trismegisto (o build quebra)`,
|
|
137
|
+
correcao: sugestao(t.tag, ELEMENTOS.keys(), 'procure o componente certo em references/angular.md §4 e references/angular-api.md'),
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
return out;
|
|
142
|
+
},
|
|
143
|
+
},
|
|
144
|
+
{
|
|
145
|
+
id: 'icone-inexistente',
|
|
146
|
+
resumo: 'nome de ícone literal (shape/icon/...Icon) fora do catálogo',
|
|
147
|
+
aceita: (a) => a.ext === '.html' || a.ext === '.ts',
|
|
148
|
+
checar(arq) {
|
|
149
|
+
const out = [];
|
|
150
|
+
for (const seg of templates(arq)) {
|
|
151
|
+
for (const t of tagsHm(seg.texto)) {
|
|
152
|
+
const el = ELEMENTOS.get(t.tag);
|
|
153
|
+
if (!el) continue;
|
|
154
|
+
for (const a of t.atributos) {
|
|
155
|
+
let nome = a.nome;
|
|
156
|
+
let valor = a.valor;
|
|
157
|
+
const ligado = nome.match(/^\[(\w+)\]$/);
|
|
158
|
+
if (ligado) {
|
|
159
|
+
nome = ligado[1];
|
|
160
|
+
valor = valor?.match(/^\s*'([^']*)'\s*$/)?.[1]; // [icon]="'trash'"
|
|
161
|
+
}
|
|
162
|
+
if (!el.icones.has(nome) || !valor || /[{}$]/.test(valor) || ICONES.has(valor)) continue;
|
|
163
|
+
out.push({
|
|
164
|
+
linha: arq.linhaDe(seg.inicio + a.pos),
|
|
165
|
+
mensagem: `ícone \`${valor}\` não está no catálogo (vira o ícone genérico com aviso [hermes-icons])`,
|
|
166
|
+
correcao: sugestao(valor, ICONES, 'nomes em references/catalogo/icones.json (kebab-case); ícone próprio registrado pelo app: use a exceção com motivo'),
|
|
167
|
+
});
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
return out;
|
|
172
|
+
},
|
|
173
|
+
},
|
|
174
|
+
{
|
|
175
|
+
id: 'click-em-hm-button',
|
|
176
|
+
resumo: '(click) em <hm-button>/<hm-icon-button>... (o evento é (clicked))',
|
|
177
|
+
aceita: (a) => a.ext === '.html' || a.ext === '.ts',
|
|
178
|
+
checar(arq) {
|
|
179
|
+
const out = [];
|
|
180
|
+
for (const seg of templates(arq)) {
|
|
181
|
+
for (const t of tagsHm(seg.texto)) {
|
|
182
|
+
if (!ELEMENTOS.get(t.tag)?.outputs.has('clicked')) continue;
|
|
183
|
+
for (const a of t.atributos) {
|
|
184
|
+
if (a.nome !== '(click)') continue;
|
|
185
|
+
// Só conter o evento (a ação fica no `(clicked)`) é o jeito certo de não abrir a linha de baixo.
|
|
186
|
+
if (/^\s*(?:\$event\.(?:stopPropagation|preventDefault)\(\)\s*;?\s*)+$/.test(a.valor ?? '')) continue;
|
|
187
|
+
out.push({
|
|
188
|
+
linha: arq.linhaDe(seg.inicio + a.pos),
|
|
189
|
+
mensagem: `\`(click)\` em \`<${t.tag}>\`: dispara mesmo desabilitado/carregando e fura o controle da peça`,
|
|
190
|
+
correcao: 'troque por `(clicked)`',
|
|
191
|
+
});
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
return out;
|
|
196
|
+
},
|
|
197
|
+
},
|
|
198
|
+
];
|
|
199
|
+
|
|
200
|
+
/** Tokens `--hm-*` que o próprio app declara (tema/família exportados do theme builder etc.). */
|
|
201
|
+
function preparar(arquivos, ctx) {
|
|
202
|
+
ctx.tokensDoApp = new Set();
|
|
203
|
+
for (const a of arquivos) {
|
|
204
|
+
for (const re of [/(--hm-[a-z0-9-]*[a-z0-9])['"]?\s*:/g, /\[style\.(--hm-[a-z0-9-]*[a-z0-9])\]/g, /setProperty\(\s*['"`](--hm-[a-z0-9-]*[a-z0-9])/g]) {
|
|
205
|
+
for (const m of a.limpo.matchAll(re)) ctx.tokensDoApp.add(m[1]);
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
process.exitCode = executar({
|
|
211
|
+
skill: 'trismegisto',
|
|
212
|
+
descricao: 'cores cravadas, tokens/seletores/ícones inexistentes e (click) em botão do Trismegisto.',
|
|
213
|
+
regras,
|
|
214
|
+
extensoes: ['.ts', '.html', '.css', '.scss', '.less'],
|
|
215
|
+
preparar,
|
|
216
|
+
});
|