@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,75 @@
|
|
|
1
|
+
# Modelo de README de tela
|
|
2
|
+
|
|
3
|
+
O `README.md` é o manual de quem **usa** a tela. Abre num modal do spine, ao lado da tela, então é
|
|
4
|
+
lido em pé: curto, em passos, com os rótulos iguais aos da interface.
|
|
5
|
+
|
|
6
|
+
## Esqueleto
|
|
7
|
+
|
|
8
|
+
```md
|
|
9
|
+
# <Nome da tela, igual ao menu>
|
|
10
|
+
|
|
11
|
+
<Uma ou duas frases: o que a tela mostra ou cadastra e para que serve.>
|
|
12
|
+
|
|
13
|
+
## Como usar
|
|
14
|
+
|
|
15
|
+
1. <Primeiro passo, com o rótulo em negrito: escolha o **projeto** no seletor.>
|
|
16
|
+
2. Clique em **<Rótulo do botão>** para <efeito>.
|
|
17
|
+
3. Na aba **<Nome da aba>**, <o que se faz ali>.
|
|
18
|
+
|
|
19
|
+
## Status
|
|
20
|
+
|
|
21
|
+
| Status | Significado |
|
|
22
|
+
| --- | --- |
|
|
23
|
+
| <Rótulo exibido> | <O que quer dizer para quem opera.> |
|
|
24
|
+
|
|
25
|
+
> <Dica final: o erro mais comum, o efeito irreversível ou onde fica o cadastro relacionado.>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`## Status` é opcional: só entra quando a tela mostra estados, cores, ícones ou etiquetas que a pessoa
|
|
29
|
+
precisa interpretar. Pode virar `## Legenda` ou `## Colunas` conforme o caso. Outras seções curtas
|
|
30
|
+
(`## Filtros`, `## Permissões`) são bem-vindas quando a tela tem muito disso; mantenha `## Como usar`
|
|
31
|
+
como a primeira seção depois da descrição.
|
|
32
|
+
|
|
33
|
+
## Regras de escrita
|
|
34
|
+
|
|
35
|
+
- **Português, segunda pessoa implícita, verbo no imperativo**: "Escolha", "Clique em", "Use a busca".
|
|
36
|
+
- **Rótulo em negrito, exatamente como na tela**, incluindo maiúsculas: se o botão diz "Novo Registry",
|
|
37
|
+
o README diz **Novo Registry**. É isso que o verificador confere (`rotulo-inexistente`) nas frases
|
|
38
|
+
"clique em **X**", "botão **X**" e "aba **X**".
|
|
39
|
+
- **Efeito, não implementação**: "publica a versão atual nos workers", não "chama a mutation deploy".
|
|
40
|
+
Nome de serviço, query e tabela vão para a especificação.
|
|
41
|
+
- **Um passo, uma ação.** Ações alternativas viram sub-itens do mesmo passo.
|
|
42
|
+
- **Sem captura de tela e sem link relativo**: o renderizador não resolve caminhos do repositório.
|
|
43
|
+
Link absoluto (`https://...`) funciona.
|
|
44
|
+
- **Caminho de menu** em negrito com `>`: **Infraestrutura > Origens**. Não use "clique em" com ele.
|
|
45
|
+
- **Permissão como efeito**: "Na visão de **Operador**, o Rollback não aparece." Quem decide é o servidor;
|
|
46
|
+
isso vai para a especificação.
|
|
47
|
+
- Tamanho de referência: 10 a 30 linhas. Passou de 50, provavelmente metade é especificação.
|
|
48
|
+
|
|
49
|
+
## O que o renderizador do spine aceita
|
|
50
|
+
|
|
51
|
+
Markdown GFM (`marked`) sanitizado (`DOMPurify`):
|
|
52
|
+
|
|
53
|
+
| Funciona | Não funciona ou não vale a pena |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| `#` a `####`, parágrafos, listas numeradas e com marcador, sub-listas | HTML cru com script/estilo (filtrado) |
|
|
56
|
+
| tabelas GFM, `> citação`, `` `código` ``, blocos de código | imagens com caminho relativo, link para outro `.md` |
|
|
57
|
+
| negrito, itálico, link `https://` | diagramas (mermaid etc.), notas de rodapé |
|
|
58
|
+
|
|
59
|
+
Quebra de linha simples **não** vira `<br>` (`breaks: false`): parágrafo novo pede linha em branco.
|
|
60
|
+
|
|
61
|
+
## Exemplo curto
|
|
62
|
+
|
|
63
|
+
```md
|
|
64
|
+
# Registries
|
|
65
|
+
|
|
66
|
+
Cadastro dos **registries** de onde saem as imagens e os pacotes usados nos builds.
|
|
67
|
+
|
|
68
|
+
## Como usar
|
|
69
|
+
|
|
70
|
+
1. Clique em **Novo Registry** e informe endereço e credenciais.
|
|
71
|
+
2. Escolha um registry no seletor para consultar o conteúdo, separado em **Imagens**, **npm** e **PyPI**.
|
|
72
|
+
3. **Editar** e **Excluir** ficam nas ações de cada linha.
|
|
73
|
+
|
|
74
|
+
> Excluir um registry que ainda é usado por alguma aplicação faz os próximos builds dela falharem.
|
|
75
|
+
```
|
|
@@ -0,0 +1,454 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Verificador da skill `documentacao`: documentação das telas Angular ligadas ao @trismegisto/spine.
|
|
3
|
+
// node checar.mjs [pasta-do-app | features.routes.ts ...] [--json]
|
|
4
|
+
// node checar.mjs [pasta-do-app] --registrar-revisao <pasta-da-feature | todas>
|
|
5
|
+
// (instalado: ~/.claude/skills/documentacao/scripts/checar.mjs)
|
|
6
|
+
// Parte do `features.routes.ts`: cada rota com `load` de tela, o `document` dela, os .md importados, o
|
|
7
|
+
// `angular.json` (loader `.md`), a declaração `*.md` e o registro de revisão `.documentacao.json`
|
|
8
|
+
// (`{ "<pasta da feature>": "<sha256 dos .ts/.html/.scss>" }`, ao lado do features.routes.ts).
|
|
9
|
+
// Exceção: `// acropole-ignore-next-line <regra> -- motivo` (ou `<!-- ... -->` no .md) na linha anterior.
|
|
10
|
+
import crypto from 'node:crypto';
|
|
11
|
+
import fs from 'node:fs';
|
|
12
|
+
import path from 'node:path';
|
|
13
|
+
import { executar, lerArquivo, listarArquivos } from './nucleo.mjs';
|
|
14
|
+
|
|
15
|
+
const ROTAS = 'features.routes.ts';
|
|
16
|
+
const REGISTRO = '.documentacao.json';
|
|
17
|
+
const IGNORADAS = new Set(['node_modules', 'dist', '.angular', '.git', 'coverage', '.nx', '.turbo']);
|
|
18
|
+
|
|
19
|
+
// ------------------------------------------------------------------------------------------ utilidades
|
|
20
|
+
|
|
21
|
+
const posix = (p) => p.split(path.sep).join('/');
|
|
22
|
+
const existe = (p) => {
|
|
23
|
+
try {
|
|
24
|
+
return fs.statSync(p);
|
|
25
|
+
} catch {
|
|
26
|
+
return null;
|
|
27
|
+
}
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
/** Copia o texto com o conteúdo das strings trocado por espaço (mesmo tamanho): chaves em string não contam. */
|
|
31
|
+
function semStrings(texto) {
|
|
32
|
+
const c = texto.split('');
|
|
33
|
+
for (let i = 0; i < texto.length; i++) {
|
|
34
|
+
const q = texto[i];
|
|
35
|
+
if (q !== '"' && q !== "'" && q !== '`') continue;
|
|
36
|
+
let j = i + 1;
|
|
37
|
+
while (j < texto.length && texto[j] !== q) {
|
|
38
|
+
if (texto[j] === '\\') c[j++] = ' ';
|
|
39
|
+
if (texto[j] !== '\n') c[j] = ' ';
|
|
40
|
+
j++;
|
|
41
|
+
}
|
|
42
|
+
i = j;
|
|
43
|
+
}
|
|
44
|
+
return c.join('');
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Para cada posição, o índice da `{` aberta mais interna (-1 fora de objeto); e o pai de cada `{`. */
|
|
48
|
+
function chaves(estrutura) {
|
|
49
|
+
const abre = new Int32Array(estrutura.length).fill(-1);
|
|
50
|
+
const pai = new Map();
|
|
51
|
+
const pilha = [];
|
|
52
|
+
for (let i = 0; i < estrutura.length; i++) {
|
|
53
|
+
const ch = estrutura[i];
|
|
54
|
+
if (ch === '{') {
|
|
55
|
+
pai.set(i, pilha.length ? pilha[pilha.length - 1] : -1);
|
|
56
|
+
pilha.push(i);
|
|
57
|
+
}
|
|
58
|
+
abre[i] = pilha.length ? pilha[pilha.length - 1] : -1;
|
|
59
|
+
if (ch === '}') pilha.pop();
|
|
60
|
+
}
|
|
61
|
+
return { abre, pai };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Pasta do app: a primeira acima com `angular.json` (senão `tsconfig.json`/`package.json`). */
|
|
65
|
+
function raizDoApp(dir) {
|
|
66
|
+
for (const marca of ['angular.json', 'tsconfig.json', 'package.json']) {
|
|
67
|
+
for (let d = dir; ; d = path.dirname(d)) {
|
|
68
|
+
if (existe(path.join(d, marca))) return { raiz: d, angularJson: marca === 'angular.json' ? path.join(d, marca) : null };
|
|
69
|
+
if (path.dirname(d) === d) break;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
return { raiz: dir, angularJson: null };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Caminho de um `import('...')`: relativo ao arquivo, ou a partir da raiz do app (`src/...`, baseUrl). */
|
|
76
|
+
function resolverImport(spec, dirRotas, raiz) {
|
|
77
|
+
if (spec.startsWith('./') || spec.startsWith('../')) return path.resolve(dirRotas, spec);
|
|
78
|
+
const primeiro = spec.split('/')[0];
|
|
79
|
+
if (primeiro && existe(path.join(raiz, primeiro))) return path.resolve(raiz, spec);
|
|
80
|
+
if (primeiro && existe(path.join(raiz, 'src', primeiro))) return path.resolve(raiz, 'src', spec);
|
|
81
|
+
return null; // alias de tsconfig ou pacote: não dá para conferir sem resolver o tsconfig
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Arquivos de uma pasta, recursivo, sem as pastas ignoradas nem as `excluir` (outras features). */
|
|
85
|
+
function arquivosDe(dir, filtro, excluir = new Set()) {
|
|
86
|
+
const out = [];
|
|
87
|
+
(function andar(d) {
|
|
88
|
+
let itens;
|
|
89
|
+
try {
|
|
90
|
+
itens = fs.readdirSync(d, { withFileTypes: true });
|
|
91
|
+
} catch {
|
|
92
|
+
return;
|
|
93
|
+
}
|
|
94
|
+
for (const e of itens) {
|
|
95
|
+
const p = path.join(d, e.name);
|
|
96
|
+
if (e.isDirectory()) {
|
|
97
|
+
if (!IGNORADAS.has(e.name) && !excluir.has(p)) andar(p);
|
|
98
|
+
} else if (filtro(p)) out.push(p);
|
|
99
|
+
}
|
|
100
|
+
})(dir);
|
|
101
|
+
return out.sort();
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
const entraNoHash = (p) => /\.(ts|html|scss)$/.test(p) && !p.endsWith('.spec.ts');
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* sha256 dos .ts/.html/.scss da feature (sem .spec.ts e sem .md), com CRLF→LF e sem BOM. `extras` são as pastas
|
|
108
|
+
* onde moram os documentos quando não é a da tela (tela-invólucro que reaproveita outra lista): o que muda lá
|
|
109
|
+
* também desatualiza a doc.
|
|
110
|
+
*/
|
|
111
|
+
function hashDaFeature(dir, outrasFeatures = new Set(), extras = []) {
|
|
112
|
+
const h = crypto.createHash('sha256');
|
|
113
|
+
const arquivos = [dir, ...extras]
|
|
114
|
+
.flatMap((d) => arquivosDe(d, entraNoHash, outrasFeatures))
|
|
115
|
+
.filter((p, i, todos) => todos.indexOf(p) === i)
|
|
116
|
+
.map((p) => ({ p, rel: posix(path.relative(dir, p)) }))
|
|
117
|
+
.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
|
|
118
|
+
for (const { p, rel } of arquivos) {
|
|
119
|
+
const texto = fs.readFileSync(p, 'utf8').replace(/^/, '').replace(/\r\n?/g, '\n');
|
|
120
|
+
h.update(`${rel}\0${texto}\0`);
|
|
121
|
+
}
|
|
122
|
+
return h.digest('hex');
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
// --------------------------------------------------------------------------------- leitura das rotas
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Lê um features.routes.ts. Devolve `{ raiz, angularJson, dirRotas, rotas }`; cada rota:
|
|
129
|
+
* `{ inicio, linhaLoad, tela, pastaTela, doc: null | { linha, variavel, load, tecnico } }`, onde `load`/`tecnico`
|
|
130
|
+
* são `{ spec, caminho, linha }` (caminho null quando não dá para resolver).
|
|
131
|
+
*/
|
|
132
|
+
function lerRotas(arq) {
|
|
133
|
+
const dirRotas = path.dirname(arq.caminho);
|
|
134
|
+
const { raiz, angularJson } = raizDoApp(dirRotas);
|
|
135
|
+
const estrutura = semStrings(arq.limpo);
|
|
136
|
+
const { abre, pai } = chaves(estrutura);
|
|
137
|
+
const importDe = (idx) => {
|
|
138
|
+
const re = /\b(?:load|loadTechnical|component)\s*:\s*(?:async\s*)?\(\s*\)\s*=>\s*(?:\{\s*return\s+)?\(?\s*(?:await\s+)?import\(\s*(['"`])([^'"`]+)\1/y;
|
|
139
|
+
re.lastIndex = idx;
|
|
140
|
+
const m = re.exec(arq.limpo);
|
|
141
|
+
if (!m) return null;
|
|
142
|
+
return { spec: m[2], caminho: resolverImport(m[2], dirRotas, raiz), linha: arq.linhaDe(idx) };
|
|
143
|
+
};
|
|
144
|
+
// Objeto que é o valor de `document:` (o texto antes da `{` termina em `document:`).
|
|
145
|
+
const ehDocumento = (obj) => obj >= 0 && /\bdocument\s*:\s*$/.test(estrutura.slice(Math.max(0, obj - 40), obj));
|
|
146
|
+
|
|
147
|
+
const rotas = new Map();
|
|
148
|
+
for (const m of estrutura.matchAll(/\b(load|component)\s*:/g)) {
|
|
149
|
+
const obj = abre[m.index];
|
|
150
|
+
if (obj < 0 || ehDocumento(obj) || rotas.has(obj)) continue;
|
|
151
|
+
const imp = importDe(m.index);
|
|
152
|
+
rotas.set(obj, {
|
|
153
|
+
inicio: obj,
|
|
154
|
+
linhaLoad: arq.linhaDe(m.index),
|
|
155
|
+
tela: imp,
|
|
156
|
+
pastaTela: imp?.caminho ? path.dirname(imp.caminho) : null,
|
|
157
|
+
doc: null,
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
for (const m of estrutura.matchAll(/\bdocument\s*:/g)) {
|
|
161
|
+
const rota = rotas.get(abre[m.index]);
|
|
162
|
+
if (!rota) continue;
|
|
163
|
+
const resto = estrutura.slice(m.index + m[0].length);
|
|
164
|
+
const aberto = resto.match(/^\s*\{/);
|
|
165
|
+
rota.doc = { linha: arq.linhaDe(m.index), variavel: !aberto, load: null, tecnico: null, objeto: aberto ? m.index + m[0].length + aberto[0].length - 1 : -1 };
|
|
166
|
+
}
|
|
167
|
+
for (const m of estrutura.matchAll(/\b(load|loadTechnical)\s*:/g)) {
|
|
168
|
+
const obj = abre[m.index];
|
|
169
|
+
if (!ehDocumento(obj)) continue;
|
|
170
|
+
const rota = rotas.get(pai.get(obj));
|
|
171
|
+
if (!rota?.doc) continue;
|
|
172
|
+
const imp = importDe(m.index) ?? { spec: null, caminho: null, linha: arq.linhaDe(m.index) };
|
|
173
|
+
rota.doc[m[1] === 'load' ? 'load' : 'tecnico'] = imp;
|
|
174
|
+
}
|
|
175
|
+
return { raiz, angularJson, dirRotas, rotas: [...rotas.values()].sort((a, b) => a.inicio - b.inicio) };
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** Features documentadas (pasta da tela → chave relativa à pasta do features.routes.ts). */
|
|
179
|
+
function featuresDocumentadas(info) {
|
|
180
|
+
const todas = new Set(info.rotas.map((r) => r.pastaTela).filter(Boolean));
|
|
181
|
+
const out = new Map();
|
|
182
|
+
for (const r of info.rotas) {
|
|
183
|
+
if (!r.doc || !r.pastaTela) continue;
|
|
184
|
+
if (!out.has(r.pastaTela)) {
|
|
185
|
+
const outras = new Set([...todas].filter((p) => p !== r.pastaTela));
|
|
186
|
+
out.set(r.pastaTela, { chave: posix(path.relative(info.dirRotas, r.pastaTela)) || '.', rota: r, outras, extras: [] });
|
|
187
|
+
}
|
|
188
|
+
// Documento fora da pasta da tela (ex.: invólucro que reaproveita a lista de outra pasta): essa pasta entra no
|
|
189
|
+
// hash. Pasta que contém a da tela (ou a raiz das rotas) não entra, senão o hash cobriria o app inteiro.
|
|
190
|
+
const f = out.get(r.pastaTela);
|
|
191
|
+
for (const imp of [r.doc.load, r.doc.tecnico]) {
|
|
192
|
+
const pastaDoc = imp?.caminho && path.dirname(imp.caminho);
|
|
193
|
+
if (!pastaDoc || pastaDoc === r.pastaTela || f.extras.includes(pastaDoc)) continue;
|
|
194
|
+
if ((r.pastaTela + path.sep).startsWith(pastaDoc + path.sep) || pastaDoc === info.dirRotas) continue;
|
|
195
|
+
f.extras.push(pastaDoc);
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
return out;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
function lerRegistro(arquivo) {
|
|
202
|
+
if (!existe(arquivo)) return { dados: null, erro: null };
|
|
203
|
+
try {
|
|
204
|
+
const dados = JSON.parse(fs.readFileSync(arquivo, 'utf8'));
|
|
205
|
+
if (!dados || typeof dados !== 'object' || Array.isArray(dados)) return { dados: null, erro: 'não é um objeto { pasta: hash }' };
|
|
206
|
+
return { dados, erro: null };
|
|
207
|
+
} catch (e) {
|
|
208
|
+
return { dados: null, erro: `JSON inválido (${e.message})` };
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
// ------------------------------------------------------------------------------------------- análise
|
|
213
|
+
|
|
214
|
+
/** Rótulo que o README apresenta como ação: "clique em **X**", "botão **X**", "aba **X**". */
|
|
215
|
+
const ACAO = /(?:\b(?:clique|clicar|clica|toque|tocar)\s+(?:em|no|na|nos|nas)\s+(?:(?:o|a)\s+)?(?:(?:botão|aba|menu|opção|ícone|link)\s+)?|\bbot(?:ão|ões)\s+|\babas?\s+)\*\*([^*\n]+)\*\*/gi;
|
|
216
|
+
const normalizar = (s) =>
|
|
217
|
+
s.toLowerCase().replace(/ | /g, ' ').replace(/&/g, '&').replace(/\s+/g, ' ').trim();
|
|
218
|
+
|
|
219
|
+
function analisarAngularJson(caminho, pastaRotas, add) {
|
|
220
|
+
let texto;
|
|
221
|
+
let json;
|
|
222
|
+
try {
|
|
223
|
+
texto = fs.readFileSync(caminho, 'utf8');
|
|
224
|
+
json = JSON.parse(texto);
|
|
225
|
+
} catch (e) {
|
|
226
|
+
add(caminho, { regra: 'md-sem-loader', linha: 1, mensagem: `não foi possível ler o angular.json (${e.message})`, correcao: 'corrija o JSON; o loader `.md` fica em architect.build/test.options.loader' });
|
|
227
|
+
return;
|
|
228
|
+
}
|
|
229
|
+
const projetos = Object.entries(json.projects ?? {});
|
|
230
|
+
const raizJson = path.dirname(caminho);
|
|
231
|
+
// Projeto dono das rotas: o de `root`/`sourceRoot` que contém a pasta; com um projeto só, ele.
|
|
232
|
+
const dono =
|
|
233
|
+
projetos.find(([, p]) => p.sourceRoot && pastaRotas.startsWith(path.resolve(raizJson, p.sourceRoot) + path.sep)) ??
|
|
234
|
+
projetos.find(([, p]) => p.root && pastaRotas.startsWith(path.resolve(raizJson, p.root) + path.sep)) ??
|
|
235
|
+
(projetos.length === 1 ? projetos[0] : null);
|
|
236
|
+
if (!dono) return;
|
|
237
|
+
const [nome, projeto] = dono;
|
|
238
|
+
const linhaDe = (chave) => {
|
|
239
|
+
const ini = Math.max(0, texto.indexOf(`"${nome}"`));
|
|
240
|
+
const idx = texto.indexOf(`"${chave}"`, ini);
|
|
241
|
+
return idx < 0 ? 1 : texto.slice(0, idx).split('\n').length;
|
|
242
|
+
};
|
|
243
|
+
const arquitetura = projeto.architect ?? projeto.targets ?? {};
|
|
244
|
+
for (const alvo of ['build', 'test']) {
|
|
245
|
+
const t = arquitetura[alvo];
|
|
246
|
+
if (!t) continue;
|
|
247
|
+
// Builder unit-test herda as opções do build (buildTarget): o loader vem de lá.
|
|
248
|
+
if (alvo === 'test' && (t.options?.buildTarget || /:unit-test$/.test(t.builder ?? ''))) continue;
|
|
249
|
+
if (t.options?.loader?.['.md'] === 'text') continue;
|
|
250
|
+
add(caminho, {
|
|
251
|
+
regra: 'md-sem-loader',
|
|
252
|
+
linha: linhaDe(alvo),
|
|
253
|
+
mensagem: `o target \`${alvo}\` do projeto \`${nome}\` não tem o loader \`.md: "text"\`: o \`import()\` do README ${alvo === 'build' ? 'quebra o build' : 'quebra o teste de rotas'}`,
|
|
254
|
+
correcao: `acrescente \`"loader": { ".md": "text" }\` em architect.${alvo}.options`,
|
|
255
|
+
});
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
function temDeclaracaoMd(raiz) {
|
|
260
|
+
return arquivosDe(raiz, (p) => p.endsWith('.d.ts')).some((p) => /declare\s+module\s+['"]\*\.md['"]/.test(fs.readFileSync(p, 'utf8')));
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/** Analisa um features.routes.ts e devolve os achados por arquivo: Map<caminho, achado[]>. */
|
|
264
|
+
function analisar(arq, add) {
|
|
265
|
+
const info = lerRotas(arq);
|
|
266
|
+
const aqui = (linha, regra, mensagem, correcao) => add(arq.caminho, { regra, linha, mensagem, correcao });
|
|
267
|
+
|
|
268
|
+
for (const r of info.rotas) {
|
|
269
|
+
const pastaRel = r.pastaTela ? posix(path.relative(info.dirRotas, r.pastaTela)) : null;
|
|
270
|
+
if (!r.doc) {
|
|
271
|
+
const temReadme = r.pastaTela && existe(path.join(r.pastaTela, 'README.md'));
|
|
272
|
+
const nome = r.tela ? ` \`${pastaRel}/${path.basename(r.tela.spec)}\`` : '';
|
|
273
|
+
aqui(r.linhaLoad, 'rota-sem-documento', `tela${nome} registrada sem \`document\`: o botão de documentação não aparece`,
|
|
274
|
+
temReadme
|
|
275
|
+
? `já existe ${pastaRel}/README.md: ligue com \`document: { load: () => import('.../README.md').then(m => m.default) }\``
|
|
276
|
+
: 'escreva o README.md da tela (references/modelo-readme.md) e ligue em `document.load`');
|
|
277
|
+
continue;
|
|
278
|
+
}
|
|
279
|
+
if (r.doc.variavel) continue; // documento montado fora do literal: não dá para seguir
|
|
280
|
+
for (const imp of [r.doc.load, r.doc.tecnico]) {
|
|
281
|
+
if (!imp?.spec || !imp.caminho) continue;
|
|
282
|
+
if (!existe(imp.caminho)) {
|
|
283
|
+
aqui(imp.linha, 'documento-inexistente', `\`${imp.spec}\` não existe: o chunk da tela não compila`, 'crie o arquivo ou corrija o caminho do `import()`');
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
const especificacao = r.pastaTela && path.join(r.pastaTela, 'ESPECIFICACAO.md');
|
|
287
|
+
if (especificacao && existe(especificacao) && !r.doc.tecnico) {
|
|
288
|
+
aqui(r.doc.linha, 'especificacao-desligada', `\`${pastaRel}/ESPECIFICACAO.md\` existe, mas a rota não tem \`loadTechnical\`: a aba técnica não mostra nada`,
|
|
289
|
+
"acrescente `loadTechnical: () => import('.../ESPECIFICACAO.md').then(m => m.default)` no `document`");
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
// READMEs ligados: formato e rótulos.
|
|
294
|
+
const readmes = new Map();
|
|
295
|
+
for (const r of info.rotas) {
|
|
296
|
+
const c = r.doc?.load?.caminho;
|
|
297
|
+
if (c && /\.md$/i.test(c) && existe(c)) readmes.set(c, r);
|
|
298
|
+
}
|
|
299
|
+
for (const caminho of readmes.keys()) {
|
|
300
|
+
const texto = fs.readFileSync(caminho, 'utf8').replace(/^/, '').replace(/\r\n?/g, '\n');
|
|
301
|
+
const visivel = texto.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
|
|
302
|
+
const noReadme = (linha, mensagem, correcao) => add(caminho, { regra: 'readme-fora-do-padrao', linha, mensagem, correcao });
|
|
303
|
+
if (!visivel.trim()) {
|
|
304
|
+
noReadme(1, 'README vazio: o modal de documentação abre em branco', 'escreva o manual da tela (references/modelo-readme.md)');
|
|
305
|
+
continue;
|
|
306
|
+
}
|
|
307
|
+
if (!/^# \S/m.test(visivel)) noReadme(1, 'README sem título `# `', 'comece com `# <nome da tela>` (o mesmo que aparece no menu)');
|
|
308
|
+
if (!/^## Como usar\s*$/m.test(visivel)) noReadme(1, 'README sem a seção `## Como usar`', 'acrescente `## Como usar` com os passos da tela (references/modelo-readme.md)');
|
|
309
|
+
|
|
310
|
+
// Rótulos de ação que não estão em nenhum template/código da pasta da tela.
|
|
311
|
+
const pasta = path.dirname(caminho);
|
|
312
|
+
const fontes = arquivosDe(pasta, (p) => /\.(html|ts)$/.test(p) && !p.endsWith('.spec.ts')).map((p) => fs.readFileSync(p, 'utf8'));
|
|
313
|
+
// Sem template, ou com i18n por chave (o texto não está no código): não dá para conferir.
|
|
314
|
+
if (!fontes.length || fontes.some((f) => /\|\s*(?:translate|transloco)\b|\$localize`|\bi18n\b/.test(f))) continue;
|
|
315
|
+
const corpus = normalizar(fontes.join('\n'));
|
|
316
|
+
for (const m of visivel.matchAll(ACAO)) {
|
|
317
|
+
const rotulo = m[1].trim().replace(/[.:,;]+$/, '');
|
|
318
|
+
if (rotulo.length < 2 || rotulo.length > 60 || /[>›{}$`]/.test(rotulo)) continue; // caminho de menu, placeholder
|
|
319
|
+
if (corpus.includes(normalizar(rotulo))) continue;
|
|
320
|
+
const idx = m.index + m[0].indexOf('**');
|
|
321
|
+
add(caminho, {
|
|
322
|
+
regra: 'rotulo-inexistente',
|
|
323
|
+
linha: texto.slice(0, idx).split('\n').length,
|
|
324
|
+
mensagem: `o README manda usar **${rotulo}**, mas esse texto não aparece em nenhum template da pasta da tela`,
|
|
325
|
+
correcao: 'confira o rótulo atual na tela e corrija o README (ou o template, se o README estiver certo)',
|
|
326
|
+
});
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
// Loader `.md` e declaração `*.md`, só se o app importa .md.
|
|
331
|
+
const usaMd = info.rotas.some((r) => [r.doc?.load, r.doc?.tecnico].some((i) => i?.spec && /\.md$/i.test(i.spec)));
|
|
332
|
+
if (usaMd) {
|
|
333
|
+
const primeiraDoc = info.rotas.find((r) => r.doc)?.doc.linha ?? 1;
|
|
334
|
+
if (info.angularJson) analisarAngularJson(info.angularJson, info.dirRotas, add);
|
|
335
|
+
else aqui(primeiraDoc, 'md-sem-loader', 'o app importa .md, mas não há angular.json acima das rotas para conferir o loader', 'confira se o builder tem o loader `.md: "text"` no build e no test');
|
|
336
|
+
if (!temDeclaracaoMd(info.raiz)) {
|
|
337
|
+
aqui(primeiraDoc, 'md-sem-loader', 'falta a declaração `declare module \'*.md\'`: o TypeScript não aceita o `import()` do README', "crie `src/markdown.d.ts` com `declare module '*.md' { const content: string; export default content; }`");
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
// Revisão registrada: cada feature documentada no .documentacao.json com o hash atual.
|
|
342
|
+
const registro = path.join(info.dirRotas, REGISTRO);
|
|
343
|
+
const { dados, erro } = lerRegistro(registro);
|
|
344
|
+
if (erro) {
|
|
345
|
+
add(registro, { regra: 'documentacao-desatualizada', linha: 1, mensagem: `${REGISTRO}: ${erro}`, correcao: 'corrija ou apague o arquivo e registre a revisão de novo depois de revisar as docs (--registrar-revisao todas)' });
|
|
346
|
+
return;
|
|
347
|
+
}
|
|
348
|
+
for (const [pasta, f] of featuresDocumentadas(info)) {
|
|
349
|
+
const atual = hashDaFeature(pasta, f.outras, f.extras);
|
|
350
|
+
const salvo = dados?.[f.chave];
|
|
351
|
+
if (salvo === atual) continue;
|
|
352
|
+
aqui(f.rota.doc.linha, 'documentacao-desatualizada',
|
|
353
|
+
salvo ? `a tela \`${f.chave}\` mudou depois da última revisão da documentação` : `a tela \`${f.chave}\` não tem revisão registrada em ${REGISTRO}`,
|
|
354
|
+
`revise o README${existe(path.join(pasta, 'ESPECIFICACAO.md')) ? '/ESPECIFICACAO' : ''} contra a tela (references/checklist-coerencia.md) e registre a revisão: node checar.mjs <app> --registrar-revisao ${f.chave}`);
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
// --------------------------------------------------------------------------------------------- regras
|
|
359
|
+
|
|
360
|
+
const REGRAS = [
|
|
361
|
+
['rota-sem-documento', 'rota com `load` de tela e sem `document`'],
|
|
362
|
+
['documento-inexistente', '`import()` de .md (load/loadTechnical) que aponta para arquivo que não existe'],
|
|
363
|
+
['especificacao-desligada', 'ESPECIFICACAO.md na pasta da tela e rota sem `loadTechnical`'],
|
|
364
|
+
['readme-fora-do-padrao', 'README vazio, sem título `# ` ou sem `## Como usar`'],
|
|
365
|
+
['rotulo-inexistente', 'README manda clicar em **X** / botão **X** / aba **X** que não está nos templates da tela'],
|
|
366
|
+
['md-sem-loader', 'app usa `document` sem loader `.md` no build/test do angular.json ou sem `declare module \'*.md\'`'],
|
|
367
|
+
['documentacao-desatualizada', `tela documentada fora do ${REGISTRO} ou com hash diferente (código mudou desde a revisão)`],
|
|
368
|
+
];
|
|
369
|
+
|
|
370
|
+
const regras = REGRAS.map(([id, resumo]) => ({
|
|
371
|
+
id,
|
|
372
|
+
resumo,
|
|
373
|
+
checar: (arq, ctx) => (ctx.achados.get(arq.caminho) ?? []).filter((a) => a.regra === id),
|
|
374
|
+
}));
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* Lê os features.routes.ts e calcula todos os achados. Os arquivos citados nos achados (README, angular.json,
|
|
378
|
+
* .documentacao.json) entram na lista de arquivos do núcleo, para a exceção da linha anterior valer neles.
|
|
379
|
+
*/
|
|
380
|
+
function preparar(arquivos, ctx) {
|
|
381
|
+
ctx.achados = new Map();
|
|
382
|
+
const add = (caminho, achado) => {
|
|
383
|
+
if (!ctx.achados.has(caminho)) ctx.achados.set(caminho, []);
|
|
384
|
+
ctx.achados.get(caminho).push(achado);
|
|
385
|
+
};
|
|
386
|
+
for (const arq of [...arquivos]) analisar(arq, add);
|
|
387
|
+
const lidos = new Set(arquivos.map((a) => a.caminho));
|
|
388
|
+
for (const caminho of ctx.achados.keys()) {
|
|
389
|
+
if (lidos.has(caminho)) continue;
|
|
390
|
+
arquivos.push(lerArquivo(caminho, posix(path.relative(process.cwd(), caminho)) || path.basename(caminho)));
|
|
391
|
+
lidos.add(caminho);
|
|
392
|
+
}
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
// ------------------------------------------------------------------------------- registro de revisão
|
|
396
|
+
|
|
397
|
+
/** Regrava o hash da(s) feature(s) no .documentacao.json. Só escreve esse arquivo. */
|
|
398
|
+
function registrarRevisao(caminhos, alvo, cwd = process.cwd()) {
|
|
399
|
+
const rotas = listarArquivos(caminhos, cwd, (p) => path.basename(p) === ROTAS);
|
|
400
|
+
if (!rotas.length) throw new Error(`nenhum ${ROTAS} encontrado em ${caminhos.join(', ') || cwd}`);
|
|
401
|
+
const feitos = [];
|
|
402
|
+
const disponiveis = [];
|
|
403
|
+
for (const { caminho } of rotas) {
|
|
404
|
+
const info = lerRotas(lerArquivo(caminho, caminho));
|
|
405
|
+
const features = featuresDocumentadas(info);
|
|
406
|
+
disponiveis.push(...[...features.values()].map((f) => f.chave));
|
|
407
|
+
const alvoAbs = alvo === 'todas' ? null : path.resolve(cwd, alvo);
|
|
408
|
+
const escolhidas = [...features].filter(([pasta, f]) => alvo === 'todas' || f.chave === posix(alvo) || pasta === alvoAbs);
|
|
409
|
+
if (!escolhidas.length) continue;
|
|
410
|
+
const registro = path.join(info.dirRotas, REGISTRO);
|
|
411
|
+
const { dados, erro } = lerRegistro(registro);
|
|
412
|
+
if (erro && alvo !== 'todas') throw new Error(`${registro}: ${erro} (use --registrar-revisao todas para regravar)`);
|
|
413
|
+
// `todas` regrava do zero (some quem não é mais tela documentada); uma feature só mantém o resto.
|
|
414
|
+
const novo = alvo === 'todas' ? {} : { ...(dados ?? {}) };
|
|
415
|
+
for (const [pasta, f] of escolhidas) {
|
|
416
|
+
novo[f.chave] = hashDaFeature(pasta, f.outras, f.extras);
|
|
417
|
+
feitos.push(posix(path.relative(cwd, path.join(info.dirRotas, f.chave))));
|
|
418
|
+
}
|
|
419
|
+
const ordenado = Object.fromEntries(Object.keys(novo).sort().map((k) => [k, novo[k]]));
|
|
420
|
+
fs.writeFileSync(registro, `${JSON.stringify(ordenado, null, 2)}\n`);
|
|
421
|
+
}
|
|
422
|
+
if (!feitos.length) throw new Error(`feature \`${alvo}\` não encontrada entre as telas documentadas: ${disponiveis.join(', ') || '(nenhuma)'}`);
|
|
423
|
+
return feitos;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
// ------------------------------------------------------------------------------------------- entrada
|
|
427
|
+
|
|
428
|
+
const argv = process.argv.slice(2);
|
|
429
|
+
const iRegistro = argv.indexOf('--registrar-revisao');
|
|
430
|
+
if (iRegistro >= 0 && !argv.includes('--help') && !argv.includes('-h')) {
|
|
431
|
+
const alvo = argv[iRegistro + 1];
|
|
432
|
+
if (!alvo || alvo.startsWith('--')) {
|
|
433
|
+
console.error('checar (documentacao): --registrar-revisao precisa de <pasta-da-feature> ou `todas`');
|
|
434
|
+
process.exitCode = 2;
|
|
435
|
+
} else {
|
|
436
|
+
const caminhos = argv.filter((a, i) => i !== iRegistro && i !== iRegistro + 1 && a !== '--json');
|
|
437
|
+
try {
|
|
438
|
+
for (const f of registrarRevisao(caminhos, alvo)) console.log(`revisão registrada: ${f}`);
|
|
439
|
+
} catch (e) {
|
|
440
|
+
console.error(`checar (documentacao): ${e.message}`);
|
|
441
|
+
process.exitCode = 2;
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
} else {
|
|
445
|
+
process.exitCode = executar({
|
|
446
|
+
skill: 'documentacao',
|
|
447
|
+
descricao: `documentação das telas (README/ESPECIFICACAO ligados nas rotas, loader .md, rótulos e revisão registrada).
|
|
448
|
+
Recebe a pasta do app ou o ${ROTAS}. Depois de revisar a doc de uma tela que mudou, registre a revisão:
|
|
449
|
+
node checar.mjs <app> --registrar-revisao <pasta-da-feature | todas> (só regrava ${REGISTRO})`,
|
|
450
|
+
regras,
|
|
451
|
+
extensoes: [ROTAS],
|
|
452
|
+
preparar,
|
|
453
|
+
});
|
|
454
|
+
}
|