sdd-layer 0.25.0

// Permite dead_code: alguns tipos e métodos do módulo ainda não têm call sites
// fora dos testes. Os warnings residuais são esperados até T-06/T-07.
#![allow(dead_code)]

/// Módulo de domínio para geração de artefatos SDD.
///
/// Introduz o contrato `trait ArtifactGenerator` e os tipos associados,
/// substituindo as três funções paralelas de renderização do monolito `src/main.rs`
/// de forma incremental (T-02 é aditivo; T-04 migra os call sites).
///
/// Rastreabilidade: Tech Spec §Contratos, ADR-002, Tasks T-02.
use std::path::Path;

use anyhow::Result;

use crate::domain::providers::ProviderSelection;
use crate::tui::runner::TokenUsageSample;

// ---------------------------------------------------------------------------
// Tipos públicos
// ---------------------------------------------------------------------------

/// Formato de saída solicitado. Deriva de StageArgs.format (--format html|md).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum ArtifactFormat {
    #[default]
    Markdown,
    Html,
}

/// Amostra de timing de geração.
///
/// Redefinido aqui como tipo público de domínio. O tipo homônimo privado em
/// `src/main.rs` será substituído por este quando T-04 migrar os call sites.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct GenerationTimingSample {
    pub started_at: Option<String>,
    pub execution_started_at: Option<String>,
    pub finished_at: Option<String>,
    pub duration_ms: Option<u128>,
    pub reasoning_duration_ms: Option<u128>,
    pub execution_duration_ms: Option<u128>,
    pub provider_reported: bool,
}

/// Telemetria REAL reportada pelo provider (env SDD_USAGE_* / SDD_GENERATION_*).
///
/// Nunca é populada por estimativa local — essa é a garantia de RN-01.
/// `usage` e `timing` são `Option` porque podem chegar separadamente.
#[derive(Clone, Debug)]
pub struct Telemetry {
    pub provider: String,
    pub model: String,
    pub effort: String,
    pub offline: bool,
    pub usage: Option<TokenUsageSample>,
    pub timing: Option<GenerationTimingSample>,
}

/// Tudo que o gerador precisa para produzir um artefato.
///
/// Substitui os dois passes atuais: `real_telemetry` já vem pronta (`Some`)
/// ou ausente (`None`), nunca estimada (RF-03/RN-01).
pub struct GenerationContext<'a> {
    pub stage: &'a str,
    pub name: &'a str,
    pub input: &'a str,
    pub root: &'a Path,
    pub provider: &'a ProviderSelection,
    pub format: ArtifactFormat,
    pub real_telemetry: Option<Telemetry>,
    pub no_telemetry: bool,
}

impl GenerationContext<'_> {
    /// Regra única de emissão do bloco de telemetria (RF-03/04/05, RN-01).
    ///
    /// Retorna `true` somente quando há telemetria real disponível
    /// E o flag `--no-telemetry` não foi passado.
    pub fn should_emit_telemetry(&self) -> bool {
        self.real_telemetry.is_some() && !self.no_telemetry
    }
}

// ---------------------------------------------------------------------------
// Trait público
// ---------------------------------------------------------------------------

/// Contrato de geração compartilhado por CLI e TUI (RF-12, RF-13).
///
/// Ordem canônica de seções (RN-07, RF-01):
/// Título → Resumo → [conteúdo do stage] → Diagramas → Rastreabilidade → Histórico de revisão
pub trait ArtifactGenerator {
    /// Markdown canônico. Sempre disponível.
    fn generate_markdown(&self, ctx: &GenerationContext<'_>) -> Result<String>;

    /// HTML single-file (RF-07/09/10/11).
    /// Só compilado com a feature flag `html-gen`.
    #[cfg(feature = "html-gen")]
    fn generate_html(&self, ctx: &GenerationContext<'_>) -> Result<String>;
}

// ---------------------------------------------------------------------------
// Implementações concretas
// ---------------------------------------------------------------------------

/// Scaffolding determinístico local — nunca emite telemetria (RF-03).
///
/// Usado quando `GenerationContext.real_telemetry` é `None`.
pub struct DeterministicGenerator;

/// Geração com provider real — anexa bloco de telemetria no rodapé (RF-04).
///
/// Usado quando `GenerationContext.real_telemetry` é `Some(_)`.
pub struct ProviderGenerator;

impl ArtifactGenerator for DeterministicGenerator {
    /// Scaffolding determinístico: sem telemetria de provider, seções na nova
    /// ordem canônica (Rastreabilidade por último). Delega para
    /// `render_stage_artifact_with_ctx` em `src/main.rs` — acoplamento a ser
    /// extraído em tarefa futura (T-13+). `ctx.should_emit_telemetry()` é false
    /// aqui (real_telemetry = None), logo nenhum campo de provider é emitido.
    fn generate_markdown(&self, ctx: &GenerationContext<'_>) -> Result<String> {
        crate::render_stage_artifact_with_ctx(ctx)
    }

    #[cfg(feature = "html-gen")]
    fn generate_html(&self, ctx: &GenerationContext<'_>) -> Result<String> {
        let markdown = self.generate_markdown(ctx)?;
        crate::domain::html::StageHtmlGenerator::new(&markdown, ctx.stage, ctx.name).render()
    }
}

impl ArtifactGenerator for ProviderGenerator {
    /// Geração com provider real: bloco de telemetria (Provider/Modelo/Effort/
    /// Offline/tokens/timing) emitido no rodapé da seção Rastreabilidade.
    /// Delega para `render_stage_artifact_with_ctx`, que lê SDD_USAGE_* e
    /// SDD_GENERATION_* do env e chama `render_stage_artifact_body` com
    /// `emit_provider_fields = true`.
    fn generate_markdown(&self, ctx: &GenerationContext<'_>) -> Result<String> {
        crate::render_stage_artifact_with_ctx(ctx)
    }

    #[cfg(feature = "html-gen")]
    fn generate_html(&self, ctx: &GenerationContext<'_>) -> Result<String> {
        let markdown = self.generate_markdown(ctx)?;
        crate::domain::html::StageHtmlGenerator::new(&markdown, ctx.stage, ctx.name).render()
    }
}

// ---------------------------------------------------------------------------
// Dispatch estático (sem dyn, sem alocação)
// ---------------------------------------------------------------------------

/// Enum de dispatch estático selecionado por presença de telemetria real.
///
/// Evita `Box<dyn ArtifactGenerator>` e mantém a saída byte-idêntica CLI/TUI.
pub enum StageGenerator {
    Deterministic(DeterministicGenerator),
    Provider(ProviderGenerator),
}

impl StageGenerator {
    /// Seleciona o gerador correto com base no contexto.
    ///
    /// - `real_telemetry = None` → `DeterministicGenerator` (scaffolding local)
    /// - `real_telemetry = Some(_)` → `ProviderGenerator` (provider real)
    pub fn select(ctx: &GenerationContext<'_>) -> Self {
        match ctx.real_telemetry {
            Some(_) => StageGenerator::Provider(ProviderGenerator),
            None => StageGenerator::Deterministic(DeterministicGenerator),
        }
    }
}

impl ArtifactGenerator for StageGenerator {
    fn generate_markdown(&self, ctx: &GenerationContext<'_>) -> Result<String> {
        match self {
            StageGenerator::Deterministic(g) => g.generate_markdown(ctx),
            StageGenerator::Provider(g) => g.generate_markdown(ctx),
        }
    }

    #[cfg(feature = "html-gen")]
    fn generate_html(&self, ctx: &GenerationContext<'_>) -> Result<String> {
        match self {
            StageGenerator::Deterministic(g) => g.generate_html(ctx),
            StageGenerator::Provider(g) => g.generate_html(ctx),
        }
    }
}

// ---------------------------------------------------------------------------
// Testes unitários (TDD — red-green antes da implementação)
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::{Path, PathBuf};

    fn dummy_provider() -> ProviderSelection {
        use std::collections::BTreeMap;
        ProviderSelection {
            id: "anthropic".to_string(),
            kind: "claude".to_string(),
            model: "claude-sonnet-4-5".to_string(),
            effort: "normal".to_string(),
            offline: false,
            enabled: true,
            auth_env: None,
            auth_present: None,
            auth_methods: vec![],
            models: vec![],
            efforts: vec![],
            stage_models: BTreeMap::new(),
            stage_efforts: BTreeMap::new(),
            capabilities: vec![],
            token_budget: None,
            usage_limits: vec![],
            explicit: false,
        }
    }

    fn ctx_with_telemetry<'a>(
        provider: &'a ProviderSelection,
        root: &'a Path,
        telemetry: Option<Telemetry>,
        no_telemetry: bool,
    ) -> GenerationContext<'a> {
        GenerationContext {
            stage: "idea",
            name: "Test Orchestration",
            input: "input de teste",
            root,
            provider,
            format: ArtifactFormat::Markdown,
            real_telemetry: telemetry,
            no_telemetry,
        }
    }

    fn dummy_telemetry() -> Telemetry {
        Telemetry {
            provider: "anthropic".to_string(),
            model: "claude-sonnet-4-5".to_string(),
            effort: "normal".to_string(),
            offline: false,
            usage: None,
            timing: None,
        }
    }

    // -----------------------------------------------------------------------
    // Matriz should_emit_telemetry (RF-03/04/05, RN-01)
    //
    // | real_telemetry | no_telemetry | should_emit |
    // |----------------|--------------|-------------|
    // | None           | false        | false       |  (scaffolding local, sem telemetria)
    // | None           | true         | false       |  (scaffolding local + flag)
    // | Some(_)        | false        | true        |  (provider real, emite)
    // | Some(_)        | true         | false       |  (provider real + --no-telemetry)
    // -----------------------------------------------------------------------

    #[test]
    fn should_emit_telemetry_none_no_flag() {
        let provider = dummy_provider();
        let root = PathBuf::from("/tmp");
        let ctx = ctx_with_telemetry(&provider, &root, None, false);
        assert!(
            !ctx.should_emit_telemetry(),
            "sem telemetria real e sem flag: não deve emitir"
        );
    }

    #[test]
    fn should_emit_telemetry_none_with_flag() {
        let provider = dummy_provider();
        let root = PathBuf::from("/tmp");
        let ctx = ctx_with_telemetry(&provider, &root, None, true);
        assert!(
            !ctx.should_emit_telemetry(),
            "sem telemetria real + no_telemetry=true: não deve emitir"
        );
    }

    #[test]
    fn should_emit_telemetry_some_no_flag() {
        let provider = dummy_provider();
        let root = PathBuf::from("/tmp");
        let ctx = ctx_with_telemetry(&provider, &root, Some(dummy_telemetry()), false);
        assert!(
            ctx.should_emit_telemetry(),
            "telemetria real disponível e sem flag: deve emitir"
        );
    }

    #[test]
    fn should_emit_telemetry_some_with_flag() {
        let provider = dummy_provider();
        let root = PathBuf::from("/tmp");
        let ctx = ctx_with_telemetry(&provider, &root, Some(dummy_telemetry()), true);
        assert!(
            !ctx.should_emit_telemetry(),
            "telemetria real disponível + no_telemetry=true: não deve emitir"
        );
    }

    // -----------------------------------------------------------------------
    // StageGenerator::select — dispatch correto por presença de telemetria
    // -----------------------------------------------------------------------

    #[test]
    fn stage_generator_select_deterministic_when_no_telemetry() {
        let provider = dummy_provider();
        let root = PathBuf::from("/tmp");
        let ctx = ctx_with_telemetry(&provider, &root, None, false);
        let gen = StageGenerator::select(&ctx);
        assert!(
            matches!(gen, StageGenerator::Deterministic(_)),
            "sem telemetria real: deve selecionar DeterministicGenerator"
        );
    }

    #[test]
    fn stage_generator_select_provider_when_telemetry_present() {
        let provider = dummy_provider();
        let root = PathBuf::from("/tmp");
        let ctx = ctx_with_telemetry(&provider, &root, Some(dummy_telemetry()), false);
        let gen = StageGenerator::select(&ctx);
        assert!(
            matches!(gen, StageGenerator::Provider(_)),
            "com telemetria real: deve selecionar ProviderGenerator"
        );
    }

    // -----------------------------------------------------------------------
    // ArtifactFormat default
    // -----------------------------------------------------------------------

    #[test]
    fn artifact_format_default_is_markdown() {
        assert_eq!(ArtifactFormat::default(), ArtifactFormat::Markdown);
    }

    // -----------------------------------------------------------------------
    // GenerationContext fields
    // -----------------------------------------------------------------------

    #[test]
    fn generation_context_fields_accessible() {
        let provider = dummy_provider();
        let root = PathBuf::from("/tmp");
        let ctx = GenerationContext {
            stage: "prd",
            name: "Minha Feature",
            input: "descrição da feature",
            root: root.as_path(),
            provider: &provider,
            format: ArtifactFormat::Html,
            real_telemetry: None,
            no_telemetry: false,
        };
        assert_eq!(ctx.stage, "prd");
        assert_eq!(ctx.format, ArtifactFormat::Html);
        assert!(!ctx.should_emit_telemetry());
    }

    // -----------------------------------------------------------------------
    // T-08 — Teste de paridade CLI=TUI (RNF-05)
    //
    // Garante que para a mesma `GenerationContext` determinística (sem
    // telemetria real, sem env vars de provider), chamar
    // `StageGenerator::select(&ctx).generate_markdown(&ctx)` duas vezes
    // produz saída byte-idêntica.
    //
    // Contexto arquitetural: o caminho determinístico da TUI delega ao
    // subprocesso `sdd <stage>` que, internamente, chama a MESMA pipeline
    // `GenerationContext → StageGenerator::select → generate_markdown`.
    // Este teste verifica que essa pipeline é determinística (mesma entrada =
    // mesma saída), o que é a condição necessária e suficiente para que
    // CLI e TUI produzam artefatos byte-idênticos para o mesmo `GenerationContext`.
    //
    // Smoke manual em TTY real (renderização interativa, animações, layout)
    // permanece pendente para T-15 (fechamento).
    // -----------------------------------------------------------------------

    #[test]
    fn parity_cli_tui_deterministic_generate_markdown_byte_identical() {
        let provider = dummy_provider();
        let root = PathBuf::from("/tmp");
        let ctx = GenerationContext {
            stage: "idea",
            name: "parity-test-orchestration",
            input: "entrada de paridade determinística",
            root: root.as_path(),
            provider: &provider,
            format: ArtifactFormat::Markdown,
            real_telemetry: None,
            no_telemetry: false,
        };

        // Caminho CLI: gera via StageGenerator (mesma pipeline que run_stage usa).
        let cli_output = StageGenerator::select(&ctx)
            .generate_markdown(&ctx)
            .expect("CLI path deve gerar Markdown sem erro");

        // Caminho TUI (equivalente): para geração determinística, a TUI delega
        // ao subprocesso `sdd <stage>` que executa a mesma pipeline internamente.
        // Aqui chamamos a função diretamente (sem subprocess) para verificar
        // a invariante de determinismo puro da pipeline de geração.
        let tui_equivalent_output = StageGenerator::select(&ctx)
            .generate_markdown(&ctx)
            .expect("TUI equivalent path deve gerar Markdown sem erro");

        assert_eq!(
            cli_output, tui_equivalent_output,
            "T-08 paridade CLI=TUI: saída deve ser byte-idêntica para o mesmo GenerationContext"
        );

        // Verifica conteúdo mínimo esperado no artefato gerado.
        assert!(
            cli_output.contains("# "),
            "artefato deve ter título de nível 1"
        );
        assert!(
            cli_output.contains("parity-test-orchestration"),
            "artefato deve referenciar o nome da orquestração"
        );
        assert!(
            cli_output.contains("## Rastreabilidade"),
            "artefato deve conter seção de rastreabilidade"
        );
    }
}