-- trilha.lua

-- A FONTE ÚNICA DE VERDADE da organização do repositório: as pastas de
-- conteúdo na ORDEM PEDAGÓGICA (a mesma do guia de estudos), o tema de
-- cada pasta e as lições de cada pasta na ordem de estudo, com uma
-- descrição curta por arquivo.
--
-- Quem consome esta tabela:
--   * gerar.lua      — a tabela de pastas da página inicial do site e a
--                      ordem/descrição dos índices por pasta;
--   * verificar_trilha.lua — o guarda anti-deriva: confere que trilha,
--                      disco e a tabela "Organização do repositório" do
--                      README.md continuam sincronizados.
--
-- Ao criar uma pasta ou uma lição nova, registre-a AQUI e na tabela do
-- README (mesma ordem, mesmo tema) — verificar_trilha.lua falha se as
-- três fontes divergirem.
--
-- Formato: lista ordenada de pastas; cada pasta é
--   { nome = "pasta", tema = "uma linha", arquivos = { {"caminho", "descrição"}, ... } }
-- com caminhos relativos à pasta (subpastas incluídas, ex.: "mvc/modelo.lua").

return {
  {
    nome = "basico",
    tema = "Primeiros passos, tipos, cadeias de texto, operadores e formatação",
    arquivos = {
      { "ola_mundo.lua", "O primeiro programa: um print" },
      { "lua_introducao_rapida.lua", "Tour executável de quase toda a linguagem" },
      { "fundamentos.md", "Visão geral e dicas para começar" },
      { "tipos.md", "Guia dos tipos de dados básicos" },
      { "tipos.lua", "Os tipos básicos verificados com assert" },
      { "limites_numericos.lua", "Bordas dos inteiros de 64 bits e floats" },
      { "escopo.lua", "Escopo de bloco e sombreamento de locais" },
      { "operadores.lua", "Operadores aritméticos, relacionais, lógicos e bit a bit" },
      { "cadeias_de_texto.md", "Guia de manipulação de strings" },
      { "cadeias_de_texto.lua", "Strings na prática, com as armadilhas de UTF-8" },
      { "utf8_na_pratica.lua", "Validação, iteração e limites da biblioteca utf8" },
      { "padroes_de_texto.lua", "Recursos avançados da biblioteca de padrões" },
      { "formatacao_de_saida.lua", "Técnicas de formatação de saída" },
      { "fizzbuzz.lua", "O clássico FizzBuzz com lógica testável" },
    },
  },
  {
    nome = "controle_de_fluxo",
    tema = "Condicionais, laços, break, switch e goto",
    arquivos = {
      { "controle_de_fluxo.md", "Guia das estruturas condicionais e de repetição" },
      { "valores_verdadeiros.lua", "Só nil e false contam como falsos" },
      { "lacos.lua", "while, repeat, for numérico e break" },
      { "switch.lua", "Um switch construído com tabelas" },
      { "goto.lua", "O idioma goto continue nos laços" },
    },
  },
  {
    nome = "funcoes",
    tema = "Funções, clausuras, varargs, múltiplos retornos e memoização",
    arquivos = {
      { "funcoes.md", "Guia de conceitos de funções" },
      { "funcoes.lua", "Definição, chamada e parâmetros de funções" },
      { "argumentos.lua", "Argumentos fixos, com padrão e variáveis" },
      { "retornos.lua", "Valores de retorno, simples e múltiplos" },
      { "multiplos_retornos.lua", "Regras de ajuste de múltiplos retornos" },
      { "select.lua", "select para navegar argumentos variáveis" },
      { "funcoes_anonimas.md", "Funções anônimas e chamada imediata" },
      { "clausuras.lua", "Clausuras: funções que guardam estado" },
      { "memoizacao.lua", "Cache de resultados com clausuras" },
    },
  },
  {
    nome = "tabelas",
    tema = "Tabelas, vetores, pilhas, listas, iteradores, buracos/#, cópias e serialização",
    arquivos = {
      { "README.md", "Visão geral e ordem de estudo das tabelas" },
      { "tabelas.lua", "Aspectos essenciais das tabelas de Lua" },
      { "vetores.lua", "Operações básicas de array e matrizes" },
      { "biblioteca_de_tabelas.lua", "Tour da biblioteca padrão table" },
      { "lista.lua", "A lista como tipo abstrato de dados" },
      { "pilha.lua", "Uma pilha construída sobre tabelas" },
      { "crud.lua", "CRUD em memória com tabelas" },
      { "selecionar_onde.lua", "Filtrar os elementos por um critério" },
      { "escolher_ferramenta.lua", "Escolher a operação certa para cada tarefa" },
      { "next.lua", "Enumeração par a par com next" },
      { "iteradores.lua", "Iteradores próprios para o for genérico" },
      { "table_move.lua", "Copiar faixas de elementos com table.move" },
      { "referencias_e_copias.lua", "Atribuição cria apelido; cópia rasa vs profunda" },
      { "buracos_e_comprimento.lua", "A pegadinha do # com buracos" },
      { "serializacao.lua", "Serializar tabelas como código Lua" },
    },
  },
  {
    nome = "metatabelas",
    tema = "Metatabelas, metamétodos, proxies e tabelas somente leitura",
    arquivos = {
      { "README.md", "Índice de todos os metamétodos cobertos" },
      { "metatabela.lua", "setmetatable e o primeiro metamétodo" },
      { "tostring.lua", "__tostring: apresentação legível de tabelas" },
      { "chamada.lua", "__call: tabela usada como função" },
      { "comparacao.lua", "__eq, __lt e __le nas comparações" },
      { "tamanho_e_concatenacao.lua", "__len e __concat personalizados" },
      { "indice_como_funcao.lua", "__index como função e proxies completos" },
      { "tabela_proxy.lua", "__newindex interceptando atribuições" },
      { "somente_leitura.lua", "Invólucro somente leitura via proxy" },
      { "finalizadores.lua", "__close e __gc no Lua 5.4" },
    },
  },
  {
    nome = "poo",
    tema = "Classes, herança, polimorfismo, mixins e interfaces",
    arquivos = {
      { "poo.md", "Guia de orientação a objetos em Lua" },
      { "classe.lua", "Classe e instâncias com __index" },
      { "retangulo.lua", "Uma classe completa, com métodos" },
      { "heranca.lua", "Herança simples entre tabelas" },
      { "prototipo.lua", "Herança por protótipos encadeados" },
      { "sobrescrita.lua", "Sobrescrita de métodos herdados" },
      { "polimorfismo.lua", "Classes diferentes respondem à mesma chamada" },
      { "mixins.lua", "Composição de comportamento com __index-função" },
      { "interface/README.md", "Projeto-exemplo de interfaces: visão geral" },
      { "interface/ipagamento.lua", "O contrato IPagamento" },
      { "interface/cartao_de_credito.lua", "Implementação do contrato: cartão" },
      { "interface/pix.lua", "Implementação do contrato: Pix" },
      { "interface/carrinho_de_compras.lua", "O cliente que usa a interface" },
      { "interface/principal.lua", "Integra o carrinho e os pagamentos" },
    },
  },
  {
    nome = "modulos",
    tema = "require, dofile, loadfile, ambientes (_ENV) e empacotamento com LuaRocks",
    arquivos = {
      { "require.md", "Guia do require e do caminho de busca" },
      { "modulo.lua", "Um módulo: arquivo que devolve uma tabela" },
      { "usando_require.lua", "require com cache em package.loaded" },
      { "carregadores.lua", "dofile, loadfile e load lado a lado" },
      { "arquivo.lua", "Arquivo auxiliar de carregadores.lua" },
      { "arquivo.txt", "Texto de apoio de carregadores.lua" },
      { "ambientes.lua", "_ENV, globais e um sandbox" },
      { "rede_http.lua", "HTTP via curl, com guarda de dependência" },
      { "empacotamento.md", "Guia do LuaRocks e do rockspec" },
      { "rockspec.lua", "Anatomia ilustrada de um rockspec" },
    },
  },
  {
    nome = "erros",
    tema = "error, assert, pcall, xpcall e try/except",
    arquivos = {
      { "README.md", "Visão geral do tratamento de erros" },
      { "erro.lua", "error: lançar erros, com nível" },
      { "assercao.lua", "assert transforma condição falsa em erro" },
      { "pcall.lua", "pcall: executar em modo protegido" },
      { "xpcall.lua", "xpcall, com tratador e traceback" },
      { "objetos_de_erro.lua", "Erros como tabelas estruturadas" },
      { "erro_estruturado.lua", "Classe de erro com __tostring" },
      { "try_except.lua", "try/except construído sobre pcall" },
    },
  },
  {
    nome = "io",
    tema = "Leitura e escrita de arquivos, em texto e binário",
    arquivos = {
      { "README.md", "Visão geral da biblioteca io" },
      { "arquivo_manipulacao_basica.lua", "Ler e escrever no estilo implícito" },
      { "arquivo_manipulacao_objeto.lua", "Manipulador de arquivos orientado a objetos" },
      { "arquivo_acrescentar.lua", "Acrescentar conteúdo com o modo a" },
      { "arquivo_crud.lua", "CRUD de um arquivo de texto" },
      { "arquivo_com_close.lua", "Fechamento garantido com <close>" },
      { "arquivo_binario.lua", "Binário com string.pack e string.unpack" },
    },
  },
  {
    nome = "sistema",
    tema = "Data e hora, relógio, esperas, aleatórios e linha de comando",
    arquivos = {
      { "README.md", "Visão geral da biblioteca os" },
      { "data_e_hora.lua", "os.time, os.date e timestamps" },
      { "relogio.lua", "Relógio de parede com os.time e os.difftime" },
      { "cronometro.lua", "Um cronômetro de tempo de parede" },
      { "cpu_vs_parede.lua", "os.clock vs os.time na prática" },
      { "espera.lua", "Espera ocupada, medida com os.clock" },
      { "dormir.lua", "Espera ociosa, delegada ao sistema" },
      { "tempo_limite.lua", "Um setTimeout para corrotinas" },
      { "fonte_de_tempo.lua", "Interface de fonte de tempo injetável" },
      { "aleatorios.lua", "math.random e math.randomseed" },
      { "linha_de_comando.lua", "arg, os.exit, ambiente e canais padrão" },
    },
  },
  {
    nome = "gc",
    tema = "Coleta de lixo e tabelas fracas",
    arquivos = {
      { "README.md", "Visão geral da coleta de lixo" },
      { "coleta_de_lixo.lua", "Coleta por alcançabilidade" },
      { "modos_do_coletor.lua", "Modos incremental e geracional" },
      { "chaves_fracas.lua", "Tabelas com chaves fracas" },
      { "memoizacao_fraca.lua", "Um cache que não impede a coleta" },
    },
  },
  {
    nome = "desempenho",
    tema = "Medição de desempenho: cronometrar antes de otimizar",
    arquivos = {
      { "README.md", "Por que medir antes de otimizar" },
      { "medicao.lua", "Benchmarks de idiomas clássicos com os.clock" },
    },
  },
  {
    nome = "depuracao",
    tema = "Biblioteca debug: introspecção da pilha e ganchos de execução",
    arquivos = {
      { "README.md", "Visão geral da biblioteca debug" },
      { "introspeccao.lua", "Inspecionar pilha, locais e upvalues" },
      { "gancho.lua", "debug.sethook: freio e mini-cobertura" },
    },
  },
  {
    nome = "testes",
    tema = "Framework de teste unitário e exemplos de testes",
    arquivos = {
      { "README.md", "Visão geral do mini-framework de testes" },
      { "teste_unitario_basico.lua", "Mini-framework de teste unitário" },
      { "suite_de_testes.lua", "Uma suíte que usa o framework" },
      { "intervalo.lua", "Módulo intervalo, semelhante ao range" },
      { "teste_intervalo.lua", "Testes do módulo intervalo" },
      { "espera.lua", "Espera ocupada usada pela suíte" },
    },
  },
  {
    nome = "padroes",
    tema = "Padrões de projeto, da fábrica ao MVC e à máquina de estados",
    arquivos = {
      { "README.md", "Visão geral dos padrões adaptados a Lua" },
      { "fabrica.lua", "Fábrica: a função criadora decide o tipo" },
      { "fabrica_abstrata.lua", "Famílias de componentes compatíveis" },
      { "construtor.lua", "Builder: montagem passo a passo" },
      { "prototipo.lua", "Prototype: criar objetos clonando" },
      { "singleton.lua", "Uma única instância, com acesso global" },
      { "adaptador.lua", "Converter uma interface em outra" },
      { "decorador.lua", "Acrescentar comportamento sem modificar" },
      { "composto.lua", "Árvores com folhas e compostos" },
      { "comando.lua", "Requisições como objetos, com undo" },
      { "memento.lua", "Capturar e restaurar o estado" },
      { "observador.lua", "Um sujeito notifica os observadores" },
      { "metodo_modelo.lua", "Esqueleto fixo, passos variáveis" },
      { "maquina_de_estados.lua", "Um semáforo como máquina de estados" },
      { "maquina_de_estados_estendida.lua", "Máquina de estados com contexto" },
      { "estrategia/pagamento.lua", "A estratégia abstrata de pagamento" },
      { "estrategia/cartao_de_credito.lua", "Estratégia concreta: cartão de crédito" },
      { "estrategia/paypal.lua", "Estratégia concreta: PayPal" },
      { "estrategia/carrinho_de_compras.lua", "O cliente que troca de estratégia" },
      { "estrategia/principal.lua", "Demonstração do padrão estratégia" },
      { "fachada/luzes.lua", "Subsistema: luzes do cinema" },
      { "fachada/projetor.lua", "Subsistema: projetor" },
      { "fachada/amplificador.lua", "Subsistema: amplificador" },
      { "fachada/leitor_dvd.lua", "Subsistema: leitor de DVD" },
      { "fachada/home_theater.lua", "A fachada que orquestra os subsistemas" },
      { "fachada/principal.lua", "Demonstração do padrão fachada" },
      { "mvc/comum.lua", "Classe base compartilhada do MVC" },
      { "mvc/modelo.lua", "Modelo: a lógica dos dados" },
      { "mvc/visao.lua", "Visão: a camada de apresentação" },
      { "mvc/controlador.lua", "Controlador liga modelo e visão" },
      { "mvc/principal.lua", "Integra os componentes do MVC" },
    },
  },
  {
    nome = "solid",
    tema = "Princípios SOLID, um arquivo por princípio",
    arquivos = {
      { "README.md", "Visão geral dos cinco princípios" },
      { "srp.lua", "Princípio da responsabilidade única (SRP)" },
      { "ocp.lua", "Aberto para extensão, fechado para modificação (OCP)" },
      { "lsp.lua", "Princípio da substituição de Liskov (LSP)" },
      { "isp.lua", "Princípio da segregação de interface (ISP)" },
      { "dip.lua", "Princípio da inversão de dependência (DIP)" },
    },
  },
  {
    nome = "corrotinas",
    tema = "Guias e exemplos de corrotinas",
    arquivos = {
      { "corrotinas.md", "Guia completo de corrotinas" },
      { "ciclo_de_vida_das_corrotinas.lua", "create, resume, yield e status" },
      { "argumentos_de_corrotinas.lua", "Troca de valores com resume e yield" },
      { "corrotina_com_wrap.lua", "coroutine.wrap em vez de resume" },
      { "gerador_com_wrap.lua", "Geradores para o for genérico" },
      { "agendador.lua", "Agendador cooperativo round-robin" },
      { "jogo_com_corrotinas.lua", "Mini-jogo de perseguição com corrotinas" },
    },
  },
  {
    nome = "banco_de_dados",
    tema = "Integração com SQLite via CLI",
    arquivos = {
      { "README.md", "Visão geral do acesso ao SQLite" },
      { "roteiro.sql", "Roteiro SQL idempotente do exemplo" },
      { "sqlite3.lua", "SQLite via os.execute e io.popen" },
    },
  },
  {
    nome = "capi",
    tema = "API C: embutir Lua em C e módulos C carregáveis via require",
    arquivos = {
      { "README.md", "Guia da API C e da compilação" },
      { "Makefile", "Compila o host e o módulo C" },
      { "embutir.c", "Embutir Lua num programa C" },
      { "modulo_c.c", "Estender Lua com um módulo C" },
      { "testar_modulo.lua", "Testa o módulo C compilado" },
    },
  },
  {
    nome = "projetos",
    tema = "Projetos completos (pluralizador, json, equipe) e soluções dos exercícios",
    arquivos = {
      { "README.md", "Visão geral dos projetos e exercícios" },
      { "exercicios/par_ou_impar.lua", "Exercício 1: par ou ímpar" },
      { "exercicios/maior_da_lista.lua", "Exercício 2: maior da lista" },
      { "exercicios/contar_palavras.lua", "Exercício 3: contador de palavras" },
      { "exercicios/inverter_tabela.lua", "Exercício 4: inverter tabela" },
      { "pluralizador/README.md", "Pluralizador: visão geral do projeto" },
      { "pluralizador/principal.lua", "O módulo principal do pluralizador" },
      { "pluralizador/regulares.lua", "Regras regulares de pluralização" },
      { "pluralizador/excecoes.lua", "Exceções às regras regulares" },
      { "pluralizador/irregulares.lua", "Plurais irregulares do inglês" },
      { "pluralizador/validacao.lua", "Casos de validação do pluralizador" },
      { "pluralizador/teste.lua", "Testes do pluralizador" },
      { "pluralizador/pluralizador-1.0-1.rockspec", "Rockspec real, instalado pela CI" },
      { "json/README.md", "JSON: visão geral e limitações" },
      { "json/json.lua", "A interface pública do módulo JSON" },
      { "json/json_codificar.lua", "Codificação de tabelas para JSON" },
      { "json/json_decodificar.lua", "Decodificação de JSON para tabelas" },
      { "json/principal.lua", "Roundtrip de codificação e decodificação" },
      { "equipe/README.md", "Equipe: agentes com ferramentas" },
      { "equipe/classe.lua", "A classe base do projeto equipe" },
      { "equipe/agente.lua", "Agentes com papel e objetivo" },
      { "equipe/ferramenta.lua", "Ferramentas estendem os agentes" },
      { "equipe/ferramentas_basicas.lua", "Ferramentas de uso comum, prontas" },
      { "equipe/registrador.lua", "O registrador de ações da equipe" },
      { "equipe/principal.lua", "Monta e executa a equipe" },
    },
  },
  {
    nome = "documentacao",
    tema = "Guia de estudos, roteiro, paradigmas, convenções, guias de instalação, "
      .. "LuaJIT/versões e enunciados de projetos",
    arquivos = {
      { "comece_aqui.md", "Roteiro guiado dos 3 primeiros dias" },
      { "guia_de_estudos.md", "A trilha completa, seção por seção" },
      { "roteiro_de_estudos.yml", "Mapa de tópicos legível por máquina" },
      { "instalacao_linux_macos.md", "Instalação no Linux e no macOS" },
      { "instalacao_lua_win10.md", "Instalação no Windows 10/11" },
      { "luajit_e_versoes.md", "LuaJIT e as diferenças entre versões" },
      { "paradigmas_de_programacao.md", "Paradigmas de programação, com exemplos" },
      { "convencoes_de_nomenclatura.md", "Convenções de nomenclatura do repositório" },
      { "projetos_lua.md", "Como propor enunciados de projetos" },
    },
  },
  {
    nome = "site",
    tema = "Gerador do site estático em arquitetura hexagonal — estudo de caso de portas e adaptadores",
    arquivos = {
      { "README.md", "O estudo de caso da arquitetura hexagonal" },
      { "gerar.lua", "A raiz de composição do gerador" },
      { "trilha.lua", "Fonte única da organização das pastas" },
      { "nucleo.lua", "O núcleo puro: toda a decisão" },
      { "markdown.lua", "Conversor de Markdown para HTML" },
      { "realce.lua", "Realce de sintaxe Lua" },
      { "adaptador_arquivos.lua", "Porta de disco POSIX (find, io)" },
      { "adaptador_memoria.lua", "Porta de memória para os testes" },
      { "testar_markdown.lua", "Testes do conversor e do realce" },
      { "testar_nucleo.lua", "Testa o núcleo com o adaptador de memória" },
      { "verificar_trilha.lua", "Guarda anti-deriva: trilha, disco e README" },
      { "verificar_saida.lua", "Valida o HTML e os links do site gerado" },
    },
  },
}