@clhaas/palette-kit 0.3.0 → 0.4.0

package/planning/phase-7-review.md

@@ -1,411 +0,0 @@
-# Revisão Fase 7 — Codegen de Types
-
-**Data**: 18 de janeiro de 2026  
-**Revisor**: GitHub Copilot (usando review-guide-v0.3.md)  
-**Status**: ✅ **APROVADO COM SUGESTÕES MENORES**
-
----
-
-## 📋 Resumo Executivo
-
-A implementação da Fase 7 (Codegen de types) está **funcionalmente completa e bem estruturada**. O código:
-
-- ✅ Gera `tokens.ts` e `tokens.d.ts` navegáveis
-- ✅ Possui testes com snapshots
-- ✅ É determinístico
-- ✅ Suporta palavras reservadas do JS
-- ✅ Gera JSDoc por token
-
-**Sugestões menores**:
-
-1. Adicionar JSDoc na função pública `generateTokenArtifacts`
-2. Validar tree-shaking em testes
-3. Documentar comportamento de segmentos vazios
-
----
-
-## ✅ CRITÉRIOS GERAIS (Todos aprovados)
-
-### 1. Contratos e tipos ✅
-
-- ✅ **Nenhum `any` ou `unknown` injustificado**
-- ✅ **Tipos exportados**: `GeneratedTokens` bem definido
-- ✅ **Sem circular imports**: `tokens.ts` importa apenas de `types`
-- ✅ **Hierarquia respeitada**: `types` → `cli/codegen`
-- ⚠️ **JSDoc em tipos públicos**: `GeneratedTokens` tem JSDoc mínimo na função, falta no type
-
-**Recomendação**:
-
-```typescript
-/**
- * Result of token artifact generation.
- * Contains TypeScript source code for tokens.ts and tokens.d.ts,
- * plus a sorted list of all token names.
- */
-export type GeneratedTokens = {
-  /** Sorted array of all token names from the registry. */
-  tokenNames: string[];
-  /** TypeScript source code for tokens.ts (runtime export). */
-  tokensTs: string;
-  /** TypeScript declaration file source for tokens.d.ts. */
-  tokensDts: string;
-};
-```
-
----
-
-### 2. Qualidade de código ✅
-
-- ✅ **Build**: Código bem estruturado, sem warnings aparentes
-- ✅ **Testes**: `tokens.test.ts` com 2 testes + snapshots
-- ✅ **Sem TODO/FIXME**: Nenhum encontrado
-- ✅ **Comentários**: Funções helper bem nomeadas (auto-documentadas)
-- ✅ **Style**: Formatação consistente
-
-**Pontos positivos**:
-
-- `RESERVED_WORDS` como constante
-- Escape de JSDoc com `escapeJsDoc()`
-- Determinismo testado explicitamente
-
----
-
-### 3. DX (Developer Experience) ✅
-
-- ⚠️ **JSDoc na função pública**: Presente mas sem exemplo
-- ✅ **Erros claros**: Validação de identifier
-- ✅ **Sem magia**: Tree building é explícito
-- ✅ **Autocomplete**: Estrutura nested garante navegação
-
-**Sugestão de melhoria no JSDoc**:
-
-```typescript
-/**
- * Generate `dist/palette/tokens.ts` and `dist/palette/tokens.d.ts` sources.
- *
- * Output is deterministic and derived from the token registry.
- * The generated files provide:
- * - Navigable token object with JSDoc hints
- * - Type-safe TokenName union
- * - Full TypeScript declarations
- *
- * @param registry - Token registry from preset (minimal-ui, modern-ui, etc.)
- * @returns Object with tokenNames array and source code strings
- *
- * @example
- * ```typescript
- * import { modernUiTokens } from './presets/tokens';
- * const { tokensTs, tokensDts } = generateTokenArtifacts(modernUiTokens);
- * await writeFile('dist/tokens.ts', tokensTs);
- * await writeFile('dist/tokens.d.ts', tokensDts);
- * ```
- */
-```
-
----
-
-### 4. Princípios da v0.3 ✅
-
-- ✅ **Runtime-first**: Core não depende dos types gerados
-- ✅ **Serializer não altera intenção**: Codegen é puro
-- ✅ **Resolver independente**: Não afeta resolução de cores
-- ✅ **Sem decisões visuais ocultas**: Apenas gera types
-- ✅ **Determinismo**: Testado com `shuffled` registry
-
----
-
-## ✅ CRITÉRIOS ESPECÍFICOS DA FASE 7
-
-### Outputs ✅
-
-- ✅ **`tokens.ts` com objeto navegável**: Estrutura nested perfeita
-- ✅ **`tokens.d.ts` com types**: Declarations consistentes
-- ✅ **Unions**: `TokenName` e `ColorRole` gerados
-
-**Evidência (snapshot)**:
-
-```typescript
-export const tokens = {
-  bg: {
-    app: "bg.app",
-  },
-  text: {
-    primary: "text.primary",
-  },
-} as const;
-
-export type TokenName = (typeof tokenNames)[number];
-export type ColorRole = TokenName;
-```
-
----
-
-### Autocomplete ✅
-
-- ✅ **Navegação por objeto funciona**: `tokens.bg.app` → autocomplete
-- ✅ **Unions inferem corretamente**: `TokenName` via `typeof`
-- ✅ **JSDoc por token presente**: Cada token tem `@token`, `@category`, `@states`
-- ✅ **Compatível com IDEs**: Estrutura padrão TS
-
-**Exemplo de JSDoc gerado**:
-
-```typescript
-/**
- * Primary text on standard surfaces.
- * @token text.primary
- * @category text
- * @states hover
- */
-primary: "text.primary"
-```
-
----
-
-### Performance ✅ (com ressalva para validação)
-
-- ✅ **Zero custo em runtime**: Strings literais com `as const`
-- ⚠️ **Tree-shaking**: Não validado em testes (sugestão abaixo)
-- ✅ **Bundle size**: Estrutura flat evita nesting excessivo
-
-**Sugestão de teste tree-shaking**:
-
-```typescript
-it("supports tree-shaking of unused tokens", () => {
-  const { tokensTs } = generateTokenArtifacts(registry);
-  // Verificar que cada token é exportado independentemente
-  expect(tokensTs).toContain('app: "bg.app"');
-  expect(tokensTs).toContain('primary: "text.primary"');
-  // TODO: adicionar teste real de bundle com esbuild/rollup
-});
-```
-
----
-
-### Integração ✅
-
-- ✅ **Gerado por `palette-kit build`**: Integração em `src/cli.ts` correta
-- ✅ **Core continua aceitando `string`**: Não quebra API existente
-- ✅ **Types são optional enhancement**: Usuário pode ignorar
-
-**Evidência da integração**:
-
-```typescript
-// src/cli.ts linha 67-71
-const writeTokensCodegen = async (outDir: string, registry: typeof minimalUiTokens) => {
-  const generated = generateTokenArtifacts(registry);
-  await writeFile(join(outDir, "tokens.ts"), generated.tokensTs, "utf8");
-  await writeFile(join(outDir, "tokens.d.ts"), generated.tokensDts, "utf8");
-  return generated.tokenNames;
-};
-```
-
----
-
-### Testes ✅
-
-- ✅ **Codegen de preset simples**: Registry com 3 tokens testado
-- ✅ **Validação de types gerados**: Snapshots garantem output
-- ✅ **Determinismo**: Teste com ordem shuffled
-
-**Testes presentes**:
-
-1. `generates navigable tokens.ts and tokens.d.ts` → valida estrutura
-2. `is deterministic regardless of registry object order` → valida determinismo
-
-**Sugestão de teste adicional**:
-
-```typescript
-it("handles tokens with reserved JS keywords", () => {
-  const registry: TokenRegistry = {
-    tokens: {
-      "control.default": {
-        name: "control.default",
-        description: "Default control.",
-        category: "control",
-        query: { role: "control.default" },
-      },
-    },
-  };
-  
-  const { tokensTs } = generateTokenArtifacts(registry);
-  // 'default' é palavra reservada, deve ser quoted
-  expect(tokensTs).toContain('"default": "control.default"');
-});
-```
-
----
-
-## ⚠️ SUGESTÕES DE MELHORIA (Não bloqueantes)
-
-### 1. JSDoc completo no type `GeneratedTokens`
-
-**Localização**: `src/cli/codegen/tokens.ts` linha 154
-
-**Código atual**:
-
-```typescript
-export type GeneratedTokens = {
-  tokenNames: string[];
-  tokensTs: string;
-  tokensDts: string;
-};
-```
-
-**Sugestão**:
-
-```typescript
-/**
- * Result of token artifact generation.
- * 
- * Contains TypeScript source code for tokens.ts and tokens.d.ts,
- * plus a sorted list of all token names.
- */
-export type GeneratedTokens = {
-  /** Sorted array of all token names from the registry. */
-  tokenNames: string[];
-  /** TypeScript source code for tokens.ts (runtime export). */
-  tokensTs: string;
-  /** TypeScript declaration file source for tokens.d.ts. */
-  tokensDts: string;
-};
-```
-
----
-
-### 2. Documentar comportamento de segmentos vazios
-
-**Localização**: `src/cli/codegen/tokens.ts` linha 85
-
-**Código atual**:
-
-```typescript
-const segments = tokenName.split(".").filter(Boolean);
-if (segments.length === 0) continue;
-```
-
-**Sugestão**: Adicionar comentário explicativo
-
-```typescript
-// Skip empty token names (e.g., "", ".", "..")
-const segments = tokenName.split(".").filter(Boolean);
-if (segments.length === 0) continue;
-```
-
----
-
-### 3. Teste para palavras reservadas do JS
-
-**Motivação**: O código trata palavras reservadas com `RESERVED_WORDS`, mas não há teste específico.
-
-**Sugestão**:
-
-```typescript
-it("quotes reserved JavaScript keywords", () => {
-  const registry: TokenRegistry = {
-    tokens: {
-      "control.default": {
-        name: "control.default",
-        description: "Default control.",
-        category: "control",
-        query: { role: "control.default" },
-      },
-      "state.return": {
-        name: "state.return",
-        description: "Return state.",
-        category: "state",
-        query: { role: "state.return" },
-      },
-    },
-  };
-  
-  const { tokensTs, tokensDts } = generateTokenArtifacts(registry);
-  
-  // 'default' e 'return' são palavras reservadas
-  expect(tokensTs).toContain('"default": "control.default"');
-  expect(tokensTs).toContain('"return": "state.return"');
-  expect(tokensDts).toContain('"default": "control.default"');
-  expect(tokensDts).toContain('"return": "state.return"');
-});
-```
-
----
-
-### 4. Validação de tree-shaking
-
-**Motivação**: Checklist menciona "Tree-shaking funcional" mas não há teste.
-
-**Sugestão**: Adicionar teste que valida que tokens não usados podem ser eliminados.
-
-```typescript
-it("generates tree-shakeable structure", () => {
-  const { tokensTs } = generateTokenArtifacts(registry);
-  
-  // Cada token deve ser uma propriedade independente
-  // Não deve haver dependencies entre tokens
-  expect(tokensTs).toContain('app: "bg.app"');
-  expect(tokensTs).toContain('primary: "text.primary"');
-  
-  // Estrutura deve permitir destructuring
-  expect(tokensTs).toContain('export const tokens =');
-  expect(tokensTs).toContain('as const');
-});
-```
-
----
-
-## 🎯 CHECKLIST FINAL
-
-### Critérios Gerais
-
-- ✅ Contratos e tipos (com sugestão de JSDoc)
-- ✅ Qualidade de código
-- ✅ DX (com sugestão de exemplo)
-- ✅ Princípios v0.3
-
-### Critérios Fase 7
-
-- ✅ Outputs (`tokens.ts`, `tokens.d.ts`, unions)
-- ✅ Autocomplete (navegação, unions, JSDoc, IDE-compatible)
-- ✅ Performance (zero runtime, tree-shaking não testado)
-- ✅ Integração (`palette-kit build`, core independente)
-- ✅ Testes (preset simples, determinismo)
-
-### O que NÃO deve acontecer ✅
-
-- ✅ Runtime NÃO acoplado a types gerados
-- ✅ Types NÃO são obrigatórios
-- ✅ Codegen NÃO quebra tree-shaking
-
----
-
-## 📊 VEREDICTO FINAL
-
-**Status**: ✅ **APROVADO PARA MERGE**
-
-**Implementação sólida** que:
-
-- Atende todos os critérios obrigatórios da Fase 7
-- Possui testes com snapshots
-- É determinística e bem estruturada
-- Integra corretamente com CLI
-
-**Sugestões para PR futuro** (não bloqueantes):
-
-1. Adicionar JSDoc completo em `GeneratedTokens`
-2. Teste específico para palavras reservadas JS
-3. Validação de tree-shaking com bundler real
-4. Comentário sobre segmentos vazios
-
-**Parabéns pela implementação limpa e bem testada!** 🎉
-
----
-
-## 📚 Referências
-
-- Guia de revisão: `.github/skills/review-guide/references/review-guide-v0.3.md`
-- Fase 7 checklist: Linhas 388-438 do guia
-- Arquivos revisados:
-
-  - `src/cli/codegen/tokens.ts` (191 linhas)
-  - `src/cli/codegen/tokens.test.ts` (61 linhas)
-  - `src/cli.ts` (integração)