@acropole/skills 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +180 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,219 @@
1
+ # Telas (features): registro no shell e anatomia
2
+
3
+ O shell (`@trismegisto/spine/shell`) monta login, callback, layout, menu e guard de rota privada a
4
+ partir da árvore de navegação que o Argos devolve para o usuário. O app só diz **qual componente
5
+ abre para cada roteador** do client. Como o shell resolve URL, menu e permissão: `trismegisto`.
6
+ Guards e sessão: `orfeu`.
7
+
8
+ ## `src/app/features/features.routes.ts`
9
+
10
+ ```ts
11
+ import { ComponentRoute } from '@trismegisto/spine/routing';
12
+
13
+ // id = router_id (linha do roteador do client no Argos), NUNCA o route_id da página.
14
+ // A URL de cada tela vem do Argos, não do nome da pasta.
15
+ export const components: ComponentRoute[] = [
16
+ {
17
+ // Vendas > Pedidos
18
+ id: '00000000-0000-0000-0000-000000000001',
19
+ load: () => import('src/app/features/pedidos/pedidos.component').then(m => m.PedidosComponent),
20
+ document: {
21
+ load: () => import('src/app/features/pedidos/README.md').then(m => m.default),
22
+ loadTechnical: () => import('src/app/features/pedidos/ESPECIFICACAO.md').then(m => m.default),
23
+ },
24
+ },
25
+ ];
26
+ ```
27
+
28
+ Campos de `ComponentRoute`:
29
+
30
+ | Campo | Uso |
31
+ | --- | --- |
32
+ | `id` | `router_id` da tela |
33
+ | `load` | `() => Promise<Type>` — sempre `import()` dinâmico (um chunk por tela) |
34
+ | `document` | Opcional. `load` = manual de uso (`README.md`, quem opera); `loadTechnical` = especificação (`ESPECIFICACAO.md`, só aparece com `SpineConfig.technicalDocs`). `title`/`group` opcionais para o índice |
35
+ | `source_template_router_id` | Para pacotes plugáveis que casam com qualquer client clonado de um template (é o que o `provideAutoService` usa; app comum não precisa) |
36
+ | `route_id`, `component` | **Deprecated** — formato antigo de `id`/`load`, ainda aceito. Não usar em código novo |
37
+
38
+ Documentação por tela exige `"loader": { ".md": "text" }` no `angular.json` e o `markdown.d.ts`.
39
+
40
+ Comente cada entrada com o caminho no menu (`Navegação > Menu > Página`) — o UUID sozinho não diz
41
+ nada a quem lê.
42
+
43
+ ### Fluxo para uma tela nova
44
+
45
+ 1. No painel administrativo do Argos, crie a rota e o roteador do client (aba de roteadores do client).
46
+ 2. Copie o `router_id` gerado.
47
+ 3. Crie a tela em `src/app/features/<tela>/` e registre em `components`.
48
+ 4. Nenhuma mudança em `app.config.ts`: `provideShell({ appComponents })` mescla com as telas da lib.
49
+
50
+ Telas do **auto-serviço** (rotas, grupos, acessos do próprio client) vêm de `provideAutoService` e
51
+ se auto-registram; não declare `router_id` para elas.
52
+
53
+ ## Rotas próprias fora do Argos (página pública)
54
+
55
+ Quando o app precisa de uma rota estática (ex.: vitrine pública em `/`), componha as rotas à mão em
56
+ `src/core/app.routes.ts` com as mesmas peças do shell, em vez de usar `APP_ROUTES` pronto:
57
+
58
+ ```ts
59
+ import { Routes } from '@angular/router';
60
+ import { PrivateGuard } from '@orfeu/angular/core';
61
+ import { LayoutComponent } from '@trismegisto/spine/layout';
62
+ import { PRIVATE_ROUTES, PUBLIC_ROUTES } from '@trismegisto/spine/shell';
63
+
64
+ export const APP_ROUTES: Routes = [
65
+ { path: '', pathMatch: 'full',
66
+ loadComponent: () => import('src/app/features/vitrine/vitrine.component').then(m => m.VitrineComponent) },
67
+ ...PUBLIC_ROUTES, // login, callback, logoff...
68
+ { path: '', component: LayoutComponent,
69
+ canActivate: [PrivateGuard], canActivateChild: [PrivateGuard], children: PRIVATE_ROUTES },
70
+ { path: '**', redirectTo: '' },
71
+ ];
72
+ ```
73
+
74
+ A rota pública vem primeiro (com `pathMatch: 'full'`) e é `loadComponent` lazy. Nesse caso,
75
+ `provideAuth(..., { eagerInit: false })` evita travar o primeiro render de visitante anônimo
76
+ (detalhes em `orfeu`).
77
+
78
+ ## Anatomia de um componente de tela
79
+
80
+ ```ts
81
+ import { ChangeDetectionStrategy, Component, computed, inject, signal } from '@angular/core';
82
+ import { ButtonComponent, DataGridColumn, DataGridComponent } from '@trismegisto/angular';
83
+ import { PedidosService } from 'src/app/services/pedidos/pedidos.service';
84
+ import type { Pedido } from 'src/app/services/pedidos/pedidos.models';
85
+
86
+ @Component({
87
+ selector: 'app-pedidos',
88
+ imports: [ButtonComponent, DataGridComponent],
89
+ templateUrl: './pedidos.component.html',
90
+ styleUrl: './pedidos.component.scss',
91
+ changeDetection: ChangeDetectionStrategy.OnPush,
92
+ })
93
+ export class PedidosComponent {
94
+ private readonly pedidos = inject(PedidosService);
95
+
96
+ readonly itens = signal<Pedido[]>([]);
97
+ readonly carregando = signal(false);
98
+ readonly erro = signal<string | null>(null);
99
+ readonly total = computed(() => this.itens().length);
100
+
101
+ readonly colunas: readonly DataGridColumn<Pedido>[] = [
102
+ { key: 'numero', title: 'Número', value: (p) => p.numero },
103
+ { key: 'cliente', title: 'Cliente', value: (p) => p.cliente },
104
+ ];
105
+ readonly rowId = (p: Pedido): string => p.id;
106
+
107
+ constructor() {
108
+ void this.carregar();
109
+ }
110
+
111
+ async carregar(): Promise<void> {
112
+ this.carregando.set(true);
113
+ this.erro.set(null);
114
+ try {
115
+ this.itens.set(await this.pedidos.listar());
116
+ } catch (e) {
117
+ this.erro.set(e instanceof Error ? e.message : 'Falha ao carregar');
118
+ } finally {
119
+ this.carregando.set(false);
120
+ }
121
+ }
122
+ }
123
+ ```
124
+
125
+ Os componentes `hm-*` usados no template (data grid, botão, modal...) e suas APIs estão na
126
+ `trismegisto`.
127
+
128
+ ### Regras de componente
129
+
130
+ - Standalone; **não** escreva `standalone: true` (padrão desde a v20).
131
+ - `changeDetection: ChangeDetectionStrategy.OnPush` em todo componente de tela/feature.
132
+ - `inject()` em vez de injeção por construtor.
133
+ - `input()`, `input.required()`, `output()`, `model()` (two-way) em vez de `@Input`/`@Output`.
134
+ - `viewChild()`, `viewChildren()`, `contentChild()`, `contentChildren()` em vez dos decorators.
135
+ - Host bindings no objeto `host` do decorator, nunca `@HostBinding`/`@HostListener`.
136
+ - Template e estilos externos com caminho relativo; template inline só para componente pequeno.
137
+ - `NgOptimizedImage` para imagens estáticas (não serve para base64 inline).
138
+ - Componente pequeno e de responsabilidade única: modal, painel de detalhe e card complexo viram
139
+ componentes próprios na pasta da tela.
140
+
141
+ ### Estado com signals
142
+
143
+ - `signal()` para estado local; `computed()` para derivado (nunca `effect()` + signal para calcular valor).
144
+ - `effect()` só para efeito colateral (sincronizar com API não-signal, DOM imperativo, log).
145
+ - `linkedSignal()` para estado editável derivado de outro que deve resetar quando a fonte muda
146
+ (ex.: item selecionado que reseta quando a lista recarrega).
147
+ - `set`/`update`, nunca `mutate`.
148
+ - Observable que alimenta template: `toSignal()` ou `async` pipe. Assinatura manual dentro do
149
+ componente: `takeUntilDestroyed()` (em vez de `Subject` + `ngOnDestroy`).
150
+
151
+ ### Templates
152
+
153
+ - `@if`, `@for`, `@switch`, `@let` (não `*ngIf`/`*ngFor`).
154
+ - `@for (p of itens(); track p.id)` — track por id estável, não pelo objeto nem `$index`. `track p` só serve
155
+ para lista de valores primitivos (strings, números); com objeto, cada recarga traz objetos novos e o
156
+ Angular recria todas as linhas (perde foco, expansão e seleção). O verificador acusa `track-objeto-inteiro`.
157
+ - `[class.ativo]="cond"` / `[style.width.%]="pct"` em vez de `ngClass`/`ngStyle`.
158
+ - Nada de lógica pesada no template; nada de getter/método que devolve array novo alimentando `@for`
159
+ (use `computed()`).
160
+ - Não assuma globais (`new Date()`) no template; exponha pelo componente.
161
+ - `@defer (on viewport)` para regiões pesadas abaixo da dobra (gráficos, abas secundárias, modais
162
+ raros) dentro de uma tela lazy — reduz o chunk daquela tela.
163
+
164
+ ## Formulários
165
+
166
+ Reactive Forms, sempre tipados:
167
+
168
+ ```ts
169
+ import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
170
+
171
+ readonly form = new FormGroup({
172
+ cliente: new FormControl('', { nonNullable: true, validators: [Validators.required] }),
173
+ quantidade: new FormControl(1, { nonNullable: true, validators: [Validators.min(1)] }),
174
+ });
175
+ ```
176
+
177
+ - Ligação por `[formControl]`/`formControlName`. Os campos `hm-*` (input, select, textarea, checkbox)
178
+ funcionam com Reactive Forms; detalhes de cada um (e qual não associa `<label for>`) na
179
+ `trismegisto`.
180
+ - Validação de texto obrigatório que aceite só espaços em branco: validador próprio com `trim()`.
181
+ - Modal com formulário: o componente de conteúdo recebe `data = input.required<XModalData>()`,
182
+ expõe `isValid()` e `getResult()` (contrato `ModalContent<T>` do `@trismegisto/spine/modal`); a tela
183
+ abre com `ModalService.open<Result, Data>({ title, component, data })` e trata o resultado.
184
+ - `[(ngModel)]` só em formulário legado de rascunho mutável; não use em código novo.
185
+ - **Desabilitar campo de formulário reativo é pelo controle**: `control.disable()`/`enable()` (num `effect()`
186
+ quando depende de signal), nunca `[disabled]` no mesmo elemento que `[formControl]`/`formControlName` — o
187
+ Angular avisa no console e o controle continua habilitado no modelo (entra no `value` e na validação).
188
+ Regra `disabled-com-form-control` do verificador.
189
+ - **Data de formulário é data local.** `toISOString()` converte para UTC: `d.toISOString().slice(0, 10)` (ou
190
+ `.split('T')[0]`) dá o dia seguinte depois das 21h em UTC-3 e desloca a data escolhida no calendário.
191
+ Monte `AAAA-MM-DD` com `getFullYear()`/`getMonth()`/`getDate()` (ou `formatDate(d, 'yyyy-MM-dd', locale)`);
192
+ `toISOString()` só para instante (timestamp) ou data que já é UTC de propósito (`Date.UTC`). Regra
193
+ `data-utc-em-formulario`.
194
+
195
+ ## Ações destrutivas e dados sensíveis
196
+
197
+ - **Excluir, revogar, desligar, sobrescrever** pedem confirmação antes de chamar o serviço
198
+ (`HermesDialogService.confirm({ heading, message, danger: true })` → `Promise<boolean>`; ver
199
+ `trismegisto`). O botão leva `intent="danger"`. Nada de exclusão num clique só, nem em ação de linha.
200
+ - **Credencial nunca em `localStorage`/`sessionStorage`** (token, senha, segredo, chave de API): qualquer
201
+ script da página lê. O token do usuário fica com o `@orfeu/angular`, em memória; outro valor sensível que
202
+ precise durar entre telas fica em memória, num service `providedIn: 'root'` com signal. O verificador da
203
+ skill `orfeu` acusa (`token-em-storage`).
204
+
205
+ ## Acessibilidade
206
+
207
+ - Meta: passar no axe e em WCAG AA (foco, contraste, ARIA).
208
+ - Ação clicável é `<button type="button">` (ou `hm-button`/`hm-icon-button`), nunca ícone com
209
+ `(click)`: ícone não recebe foco nem teclado. Botão só com ícone leva `aria-label`.
210
+ - Modal do DS já faz foco preso, retorno de foco e Esc; não reimplemente.
211
+ - Rode `npm run lint:a11y` nos templates alterados (ver `testes-build.md`).
212
+
213
+ ## i18n
214
+
215
+ - Os apps são **monolíngues em pt-BR**: textos direto no template, `<html lang="pt-BR">`. Não há
216
+ `$localize`/`i18n=`/Transloco nos apps hoje.
217
+ - Datas, números e moeda: `registerLocaleData(localePt)` no `main.ts` e pipes com `'pt-BR'`.
218
+ - Mensagens do próprio shell (login, erros do GraphQL) vêm do catálogo de mensagens do spine
219
+ (`trismegisto`); não duplique esses textos no app.
@@ -0,0 +1,230 @@
1
+ # Testes, lint, build e Docker
2
+
3
+ ## Testes unitários
4
+
5
+ Os apps usam **Karma + Jasmine** pelo builder `@angular/build:karma` (`ng test` / `npm test`), com
6
+ `zone.js` e `zone.js/testing` nos polyfills do alvo `test` e `tsconfig.spec.json` incluindo
7
+ `src/**/*.spec.ts` com `types: ["jasmine"]`. Vitest ainda não é usado nos apps; não migre o runner
8
+ junto com uma feature.
9
+
10
+ Spec fica ao lado do arquivo (`pedidos.component.spec.ts`). Teste o que a tela promete (dado
11
+ renderizado, estado de erro, ação disparando a operação certa), não detalhe de implementação.
12
+
13
+ ### Teste das rotas (`features.routes.spec.ts`)
14
+
15
+ Um spec por app confere o mapa de telas — é o que pega `import()` quebrado e `id` repetido, que o build
16
+ não pega (tela lazy só carrega em runtime):
17
+
18
+ ```ts
19
+ import { reflectComponentType } from '@angular/core';
20
+ import { components } from 'src/app/features/features.routes';
21
+
22
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
23
+
24
+ describe('features.routes', () => {
25
+ it('ids são UUID e únicos (sem diferenciar maiúsculas)', () => {
26
+ const ids = components.map((c) => String(c.id).toLowerCase());
27
+ expect(new Set(ids).size).toBe(ids.length);
28
+ for (const id of ids) expect(id).toMatch(UUID);
29
+ });
30
+
31
+ it('todo load() resolve para um componente standalone', async () => {
32
+ for (const rota of components) {
33
+ const tipo = await rota.load!();
34
+ expect(reflectComponentType(tipo as any)?.isStandalone).withContext(String(rota.id)).toBeTrue();
35
+ }
36
+ });
37
+ });
38
+ ```
39
+
40
+ - Formato de cada entrada: `load: () => import('...').then((m) => m.X)` (um chunk por tela); nada de
41
+ importar a classe estaticamente.
42
+ - Com `document`, confira também que `document.load()` devolve texto não vazio.
43
+
44
+ ### Componente que usa service GraphQL: Apollo falso
45
+
46
+ O `injectGraphqlClient` chama `apollo.use(nome).query(...)` e espera um Observable. Substitua o
47
+ `Apollo` inteiro e responda pelo **nome da operação**:
48
+
49
+ ```ts
50
+ import { TestBed } from '@angular/core/testing';
51
+ import { provideNoopAnimations } from '@angular/platform-browser/animations';
52
+ import { provideRouter } from '@angular/router';
53
+ import { Apollo } from 'apollo-angular';
54
+ import { defer, of } from 'rxjs';
55
+ import { NotificationService } from '@trismegisto/spine/notification';
56
+
57
+ import { PedidosComponent } from 'src/app/features/pedidos/pedidos.component';
58
+ import { envelope, failure } from 'src/testing/graphql';
59
+
60
+ function fakeApollo(respostas: Record<string, unknown>) {
61
+ return {
62
+ use: () => ({
63
+ query: (opts: { query: any }) => defer(() => {
64
+ const nome = opts.query?.definitions?.[0]?.name?.value;
65
+ return Promise.resolve({ data: respostas[nome] ?? {} });
66
+ }),
67
+ mutate: () => defer(() => Promise.resolve({ data: {} })),
68
+ subscribe: () => of(),
69
+ }),
70
+ };
71
+ }
72
+
73
+ async function setup(respostas: Record<string, unknown>) {
74
+ TestBed.configureTestingModule({
75
+ imports: [PedidosComponent],
76
+ providers: [
77
+ provideRouter([]),
78
+ provideNoopAnimations(),
79
+ { provide: Apollo, useValue: fakeApollo(respostas) },
80
+ { provide: NotificationService, useValue: { addNotification: () => undefined } },
81
+ ],
82
+ });
83
+ const fixture = TestBed.createComponent(PedidosComponent);
84
+ fixture.detectChanges();
85
+ await fixture.whenStable();
86
+ fixture.detectChanges();
87
+ return { fixture, cmp: fixture.componentInstance, el: fixture.nativeElement as HTMLElement };
88
+ }
89
+
90
+ describe('PedidosComponent', () => {
91
+ it('lista os pedidos do envelope', async () => {
92
+ const { cmp } = await setup({ ListarPedidos: { pedidos: envelope([{ id: '1', numero: 'A-1' }]) } });
93
+ expect(cmp.itens().length).toBe(1);
94
+ });
95
+
96
+ it('403 vira estado de erro, não lista vazia', async () => {
97
+ const { cmp } = await setup({ ListarPedidos: { pedidos: failure(403, 'Sem permissão') } });
98
+ expect(cmp.erro()).toBe('Sem permissão');
99
+ });
100
+ });
101
+ ```
102
+
103
+ Helper compartilhado em `src/testing/graphql.ts`:
104
+
105
+ ```ts
106
+ import type { DocumentNode, OperationDefinitionNode } from 'graphql';
107
+
108
+ export const envelope = <T>(data: T, status = 200, message = '') => ({ status, message, data });
109
+ export const failure = (status: number, message: string) => ({ status, message, data: null });
110
+
111
+ const operation = (doc: DocumentNode): OperationDefinitionNode =>
112
+ doc.definitions.find((d): d is OperationDefinitionNode => d.kind === 'OperationDefinition')!;
113
+ export const operationName = (doc: DocumentNode): string => operation(doc).name?.value ?? '';
114
+ ```
115
+
116
+ Dicas:
117
+ - Fixture grande (payload real anonimizado) em `<tela>.fixture.ts` ao lado da spec; use
118
+ `structuredClone` ao devolvê-la para um teste não contaminar o outro.
119
+ - Signals: leia direto (`cmp.itens()`); para input de signal, `fixture.componentRef.setInput('x', v)`.
120
+ - Componente `hm-*` que não reflete propriedade como atributo do DOM: leia pelo componente
121
+ (`ng.getComponent(el)`), não pelo atributo.
122
+ - Valide só o que mudou (spec da tela alterada), não a bateria inteira a cada ajuste.
123
+
124
+ ## Lint de acessibilidade
125
+
126
+ `eslint.a11y.config.js` separado do lint principal, com o preset de acessibilidade de template do
127
+ `angular-eslint` rebaixado para `warn`:
128
+
129
+ ```js
130
+ // @ts-check
131
+ const tseslint = require('typescript-eslint');
132
+ const angular = require('angular-eslint');
133
+
134
+ const toWarn = (configs) => configs.map((c) => !c.rules ? c : {
135
+ ...c,
136
+ rules: Object.fromEntries(Object.entries(c.rules).map(([k, v]) => [k, Array.isArray(v) ? ['warn', ...v.slice(1)] : 'warn'])),
137
+ });
138
+
139
+ module.exports = tseslint.config({
140
+ files: ['**/*.html'],
141
+ extends: [...toWarn(angular.configs.templateAccessibility)],
142
+ });
143
+ ```
144
+
145
+ Script: `"lint:a11y": "eslint --config eslint.a11y.config.js \"src/**/*.html\""`. Dependências:
146
+ `eslint`, `angular-eslint`, `typescript-eslint`. `label-has-associated-control` dá falso positivo
147
+ quando a associação é feita em runtime pelo componente: confira o DOM renderizado antes de "corrigir".
148
+
149
+ ### axe no navegador
150
+
151
+ `scripts/axe-check.js` (puppeteer + `@axe-core/puppeteer`) abre o app servido localmente, espera o
152
+ login manual e roda o axe em cada rota de um JSON (`scripts/axe-routes.json`). Como as URLs vêm do
153
+ Argos em runtime, o JSON mapeia `router_id -> path` preenchido à mão; rotas sem path são puladas.
154
+ Rotas fixas do shell (`/login`, `/home`, `/callback`, `/logoff`) podem ir direto.
155
+
156
+ ## Build
157
+
158
+ | Configuração | Para quê | Environment |
159
+ | --- | --- | --- |
160
+ | `prod` (**padrão** do `ng build`) | produção: otimizado, `outputHashing: all`, budgets | `environment.prod.ts` |
161
+ | `homol` | homologação | `environment.homol.ts` |
162
+ | `dev` | ambiente de desenvolvimento em container | `environment.dev.ts` |
163
+ | `local` | `ng serve` nativo apontando para serviços locais | `environment.local.ts` |
164
+ | `development` | padrão do `ng serve`, sem troca de environment | `environment.ts` |
165
+
166
+ `ng build --configuration prod` (ou só `ng build`). Saída em `dist/<outputPath>/browser`.
167
+
168
+ ### Budgets
169
+
170
+ ```json
171
+ "budgets": [
172
+ { "type": "initial", "maximumWarning": "4MB", "maximumError": "5MB" },
173
+ { "type": "anyComponentStyle", "maximumWarning": "16kB", "maximumError": "32kB" }
174
+ ]
175
+ ```
176
+
177
+ - O inicial é alto por natureza: CSS global do DS (`tokens.css` + `core.css`) e shell/auth são
178
+ carregados antes de qualquer rota. `@defer` e lazy de tela não mexem nisso.
179
+ - Para baixar o inicial: `provideAnimationsAsync()`, `import()` lazy em libs pesadas
180
+ (`provideEchartsCore({ echarts: () => import('echarts') })`), não importar lib pesada em
181
+ `app.config.ts`/`core`.
182
+ - `anyComponentStyle` estourando = estilo de tela grande demais: extraia subcomponentes ou use os
183
+ componentes/tokens do DS em vez de CSS próprio.
184
+
185
+ ### `styles.scss`
186
+
187
+ Só o que é global e próprio do app (ponte para classes legadas, tema próprio via `@use`). Sempre com
188
+ tokens `--hm-*`, nunca cor/tamanho cravado. Estilo de tela fica no `.scss` da tela. Tokens e temas:
189
+ `trismegisto`.
190
+
191
+ ## Docker
192
+
193
+ Padrão multi-stage: um estágio para dev-server, um para o build e um final só com os arquivos
194
+ estáticos.
195
+
196
+ ```dockerfile
197
+ FROM node:22-slim AS dev
198
+ WORKDIR /app
199
+ COPY package.json package-lock.json ./
200
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
201
+ timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
202
+ COPY . .
203
+ EXPOSE 4200
204
+ CMD ["./node_modules/.bin/ng", "serve", "--configuration", "dev", "--host", "0.0.0.0", "--no-hmr", "--port", "4200"]
205
+
206
+ FROM node:22-slim AS build
207
+ WORKDIR /app
208
+ COPY package.json package-lock.json ./
209
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
210
+ timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
211
+ COPY . .
212
+ # ARG depois do install: declarado antes, cada ambiente invalidaria o cache do npm ci.
213
+ ARG CONFIGURATION=prod
214
+ RUN --mount=type=cache,target=/app/.angular/cache,sharing=locked \
215
+ timeout -k 10 300 ./node_modules/.bin/ng build --configuration $CONFIGURATION
216
+
217
+ # Imagem só para extrair o site (docker create + docker cp): o build estático em /dist.
218
+ FROM scratch AS site
219
+ COPY --from=build /app/dist/meu-app/browser /dist
220
+ CMD ["unused"]
221
+ ```
222
+
223
+ - `timeout -k` em passo que baixa/compila: build travado não fica rodando para sempre.
224
+ - **Não copie `.npmrc`** nem passe credencial por `ARG`/`ENV`: fica gravado na imagem. Os pacotes
225
+ `@trismegisto/*` e `@orfeu/*` vêm do npm público.
226
+ - `.dockerignore` com `node_modules`, `dist`, `.angular`.
227
+ - Para servir com nginx (ou outro servidor estático): copie `/dist` para o `root`, sirva sob o mesmo
228
+ prefixo do `baseHref` e faça fallback de SPA para o `index.html`
229
+ (`try_files $uri $uri/ /<prefixo>/index.html;`). Arquivos com hash podem ter cache longo;
230
+ `index.html` sem cache.
@@ -0,0 +1,182 @@
1
+ #!/usr/bin/env node
2
+ // Verificador da skill `angular`: padrões de app Angular (22+, standalone, signals).
3
+ // node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/angular/scripts/checar.mjs)
4
+ // Exceção: `// acropole-ignore-next-line <regra> -- motivo` (ou `<!-- ... -->` no HTML) na linha anterior.
5
+ import { executar, templates } from './nucleo.mjs';
6
+
7
+ const ehTs = (a) => a.ext === '.ts';
8
+ const ehCodigo = (a) => ehTs(a) && !/\.spec\.ts$/.test(a.nome);
9
+
10
+ /** Achados de um regex no texto sem comentários. */
11
+ function procurar(arq, texto, inicio, re, fazer) {
12
+ const out = [];
13
+ for (const m of texto.matchAll(re)) out.push({ linha: arq.linhaDe(inicio + m.index), ...fazer(m) });
14
+ return out;
15
+ }
16
+
17
+ /** Índice do `)`/`}` que fecha o `(`/`{` em `inicio` (conta só o mesmo tipo; strings de template são raras aqui). */
18
+ function fecha(texto, inicio) {
19
+ const abre = texto[inicio];
20
+ const fechaCh = abre === '(' ? ')' : '}';
21
+ let prof = 0;
22
+ for (let i = inicio; i < texto.length; i++) {
23
+ if (texto[i] === abre) prof++;
24
+ else if (texto[i] === fechaCh && --prof === 0) return i;
25
+ }
26
+ return texto.length;
27
+ }
28
+
29
+ /** Tags HTML de um trecho de template: `{ tag, pos, atributos: [{ nome, valor, pos }] }`. */
30
+ function* tags(trecho) {
31
+ const re = /<([a-zA-Z][\w-]*)(?![\w-])/g;
32
+ let m;
33
+ while ((m = re.exec(trecho))) {
34
+ let i = re.lastIndex;
35
+ let aspas = '';
36
+ for (; i < trecho.length; i++) {
37
+ const ch = trecho[i];
38
+ if (aspas) {
39
+ if (ch === aspas) aspas = '';
40
+ } else if (ch === '"' || ch === "'") aspas = ch;
41
+ else if (ch === '>') break;
42
+ }
43
+ const corpo = trecho.slice(re.lastIndex, i);
44
+ const atributos = [];
45
+ for (const a of corpo.matchAll(/([^\s=/>"']+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)) {
46
+ atributos.push({ nome: a[1], valor: a[2] ?? a[3] ?? a[4], pos: re.lastIndex + a.index });
47
+ }
48
+ yield { tag: m[1], pos: m.index, atributos };
49
+ }
50
+ }
51
+
52
+ // `toISOString()` cortado para virar data `AAAA-MM-DD`.
53
+ const ISO_CORTADO = /toISOString\(\)\s*\.\s*(?:(?:slice|substring|substr)\(\s*0\s*,\s*10\s*\)|split\(\s*(['"`])T\1\s*\)\s*\[\s*0\s*\])/g;
54
+
55
+ const regras = [
56
+ {
57
+ id: 'decorator-input-output',
58
+ resumo: '@Input()/@Output()/new EventEmitter em vez de input()/output()/model()',
59
+ aceita: ehCodigo,
60
+ checar: (arq) =>
61
+ procurar(arq, arq.limpo, 0, /@(Input|Output)\s*\(|\bnew\s+EventEmitter\b/g, (m) => ({
62
+ mensagem: m[1] ? `\`@${m[1]}()\` é a API antiga de decorators` : '`EventEmitter` é a API antiga de outputs',
63
+ correcao: m[1] === 'Input' ? 'use `readonly x = input<T>()` (ou `input.required<T>()`, `model<T>()` para two-way)' : 'use `readonly x = output<T>()`',
64
+ })),
65
+ },
66
+ {
67
+ id: 'diretiva-estrutural',
68
+ resumo: '*ngIf/*ngFor/*ngSwitchCase no template (use @if/@for/@switch)',
69
+ aceita: (a) => a.ext === '.html' || ehTs(a),
70
+ checar(arq) {
71
+ const out = [];
72
+ const novo = { ngIf: '@if (cond) { … } @else { … }', ngFor: '@for (item of itens; track item.id) { … }', ngSwitchCase: '@switch (x) { @case (v) { … } }', ngSwitchDefault: '@switch … @default { … }' };
73
+ for (const seg of templates(arq)) {
74
+ out.push(
75
+ ...procurar(arq, seg.texto, seg.inicio, /\*(ngIf|ngFor|ngSwitchCase|ngSwitchDefault)\b/g, (m) => ({
76
+ mensagem: `\`*${m[1]}\` é a sintaxe antiga de controle de fluxo`,
77
+ correcao: `use \`${novo[m[1]]}\` (migração automática: \`ng generate @angular/core:control-flow\`)`,
78
+ })),
79
+ );
80
+ }
81
+ return out;
82
+ },
83
+ },
84
+ {
85
+ id: 'http-sem-interceptors',
86
+ resumo: 'provideHttpClient( sem withInterceptorsFromDi() no mesmo arquivo',
87
+ aceita: ehCodigo,
88
+ checar(arq) {
89
+ if (/\bwithInterceptorsFromDi\s*\(/.test(arq.limpo)) return [];
90
+ return procurar(arq, arq.limpo, 0, /\bprovideHttpClient\s*\(/g, () => ({
91
+ mensagem: '`provideHttpClient` sem `withInterceptorsFromDi()`: o interceptor do spine não roda e o `x-route-id` da auditoria se perde',
92
+ correcao: 'use `provideHttpClient(withInterceptorsFromDi())` (outros `with*` podem vir junto)',
93
+ }));
94
+ },
95
+ },
96
+ {
97
+ id: 'standalone-redundante',
98
+ resumo: 'standalone: true (já é o padrão)',
99
+ aceita: ehTs,
100
+ checar: (arq) =>
101
+ procurar(arq, arq.limpo, 0, /\bstandalone\s*:\s*true\b/g, () => ({
102
+ mensagem: '`standalone: true` é redundante: componentes, diretivas e pipes já são standalone por padrão',
103
+ correcao: 'apague a linha',
104
+ })),
105
+ },
106
+ {
107
+ id: 'track-objeto-inteiro',
108
+ resumo: '@for com `track item` (o objeto) quando o item tem id (`item.id`, `item.xId`...)',
109
+ aceita: (a) => a.ext === '.html' || ehTs(a),
110
+ checar(arq) {
111
+ const out = [];
112
+ for (const seg of templates(arq)) {
113
+ const t = seg.texto;
114
+ for (const m of t.matchAll(/@for\s*\(/g)) {
115
+ const abre = m.index + m[0].length - 1;
116
+ const fim = fecha(t, abre);
117
+ const cab = t.slice(abre + 1, fim).match(/^\s*([A-Za-z_$][\w$]*)\s+of\s[\s\S]*?;\s*track\s+([^;]+?)\s*(?:;|$)/);
118
+ if (!cab || cab[2] !== cab[1]) continue;
119
+ // Só acusa quando o próprio bloco lê um identificador do item: aí ele é objeto e tem chave estável.
120
+ const corpoIni = t.indexOf('{', fim);
121
+ if (corpoIni < 0) continue;
122
+ const corpo = t.slice(corpoIni, fecha(t, corpoIni));
123
+ const v = cab[1].replace(/\$/g, '\\$');
124
+ const id = corpo.match(new RegExp(`(?<![\\w$.])${v}\\s*\\??\\.\\s*(id|uuid|key|[a-z]\\w*Id|[a-z]\\w*_id)\\b`));
125
+ if (!id) continue;
126
+ out.push({
127
+ linha: arq.linhaDe(seg.inicio + m.index),
128
+ mensagem: `\`track ${cab[1]}\` rastreia o objeto: a cada recarga a lista vem com objetos novos e tudo é recriado (perde foco, expansão, seleção)`,
129
+ correcao: `use \`track ${cab[1]}.${id[1]}\``,
130
+ });
131
+ }
132
+ }
133
+ return out;
134
+ },
135
+ },
136
+ {
137
+ id: 'data-utc-em-formulario',
138
+ resumo: 'toISOString().slice(0, 10) / .split(\'T\')[0] como data local (hoje, formulário)',
139
+ aceita: ehCodigo,
140
+ checar(arq) {
141
+ const linhas = arq.limpo.split('\n');
142
+ return procurar(arq, arq.limpo, 0, ISO_CORTADO, () => ({})).filter((a) => {
143
+ const l = linhas[a.linha - 1];
144
+ if (/Date\.UTC\(|getTimezoneOffset|getUTC\w+\(/.test(l)) return false; // UTC de propósito
145
+ return /new Date\(\s*\)|\bform\w*\b|[cC]ontrol\b|\.getRawValue\(|\.value\b|\b(?:hoje|today|now|agora)\b/.test(l);
146
+ }).map((a) => ({
147
+ linha: a.linha,
148
+ mensagem: '`toISOString()` é UTC: cortado para `AAAA-MM-DD`, dá o dia seguinte à noite no Brasil (depois das 21h em UTC-3) e o dia errado para a data escolhida no formulário',
149
+ correcao: 'monte a data local: `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, \'0\')}-${String(d.getDate()).padStart(2, \'0\')}` (ou `formatDate(d, \'yyyy-MM-dd\', locale)`)',
150
+ }));
151
+ },
152
+ },
153
+ {
154
+ id: 'disabled-com-form-control',
155
+ resumo: '[disabled] no mesmo elemento que [formControl]/formControlName',
156
+ aceita: (a) => a.ext === '.html' || ehTs(a),
157
+ checar(arq) {
158
+ const out = [];
159
+ for (const seg of templates(arq)) {
160
+ for (const t of tags(seg.texto)) {
161
+ const nomes = t.atributos.map((a) => a.nome);
162
+ if (!nomes.some((n) => /^\[?formControl(Name)?\]?$/.test(n))) continue;
163
+ const dis = t.atributos.find((a) => a.nome === '[disabled]');
164
+ if (!dis) continue;
165
+ out.push({
166
+ linha: arq.linhaDe(seg.inicio + dis.pos),
167
+ mensagem: `\`[disabled]\` junto de formulário reativo em \`<${t.tag}>\`: o Angular avisa no console e o controle continua habilitado no modelo (entra no \`form.value\` e na validação) mesmo com o campo cinza`,
168
+ correcao: 'tire o `[disabled]` e use `control.disable()` / `control.enable()` (num `effect()` se depende de signal)',
169
+ });
170
+ }
171
+ }
172
+ return out;
173
+ },
174
+ },
175
+ ];
176
+
177
+ process.exitCode = executar({
178
+ skill: 'angular',
179
+ descricao: 'APIs antigas (@Input/@Output, *ngIf/*ngFor), standalone redundante, HttpClient sem interceptors de DI, track pelo objeto, data de formulário em UTC e [disabled] com formulário reativo.',
180
+ regras,
181
+ extensoes: ['.ts', '.html'],
182
+ });