alef 0.66.0

use crate::core::backend::GeneratedFile;
use crate::core::config::e2e::{E2eConfig, SnippetConfig};
use crate::core::config::{Language, ResolvedCrateConfig};
use crate::core::ir::{EnumDef, TypeDef};
use crate::e2e::codegen::{E2eCodegen, all_generators};
use crate::e2e::fixture::{Fixture, FixtureDocs, SideEffectClass};
use anyhow::{Context, Result, bail};
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet};
use std::path::{Component, Path, PathBuf};

pub mod coverage;
pub(crate) mod ledger_paths;
pub mod migration;
mod mock_harness_guard;
mod mock_url_defaults;
pub mod ownership;
mod recipe_policy;

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SnippetInclusion {
    Include,
    Exclude { missing_requirements: Vec<String> },
}

#[derive(Debug, Clone)]
pub struct GeneratedSnippet {
    pub file: GeneratedFile,
    pub fixture_id: String,
    pub fixture_source: String,
    pub language: String,
    pub requirements: Vec<String>,
    pub side_effects: SideEffectClass,
}

pub const COVERAGE_MANIFEST: &str = ".alef-snippet-coverage.json";
pub const COVERAGE_MANIFEST_VERSION: u32 = 2;

/// True when `path`'s file name is alef's own snippet-coverage ledger.
///
/// The ledger is strict JSON, so it can never carry an `alef:hash:` provenance marker, and
/// `write_scaffold_files_report`'s write-time ownership guard falls back to the committed
/// `.alef-ownership.toml` record for exactly that reason. That record is populated by the
/// guard itself the first time it *creates* a path, but a ledger written before this
/// mechanism existed — or one whose only prior writes happened to leave content
/// byte-identical to disk, which records nothing by design (byte-equality is never proof of
/// authorship) — reaches this guard already `exists()` and unrecorded, and is refused
/// forever: refusing means the write never happens, so the record that would unblock the
/// *next* write is never established either.
///
/// This is deliberately not folded into a general "unmarkable extension" filename
/// allowlist the way `orphans.rs`'s `UNMARKABLE_ALEF_MANIFESTS` covers
/// `composer.json`/`package.json` for orphan reclaim: those names a human plausibly authors
/// independently of alef, so trusting the name alone there would risk silently overwriting
/// hand-written content. This ledger's dotfile name has no meaning or use to anything but
/// alef's own coverage bookkeeping — nothing else ever reads or writes it — so a name match
/// here is sufficient proof of exclusive alef authorship without weakening the guard's
/// protection for any other path. Consulted from
/// `cli::pipeline::generate::scaffold::write_scaffold_files_report`'s ownership check; once
/// it lets the write through once, the guard's own write-time registration records the path
/// durably and this predicate is never needed again for that tree. ~keep
pub fn is_snippet_coverage_manifest_path(path: &Path) -> bool {
    path.file_name().and_then(|name| name.to_str()) == Some(COVERAGE_MANIFEST)
}

/// Requirement namespace for a Cargo crate a generated Rust snippet body names directly. ~keep
/// The Rust snippet validator resolves these into `[dependencies]` of the check project.
pub const CRATE_REQUIREMENT_PREFIX: &str = "crate:";

const SERDE_JSON_REQUIREMENT: &str = "crate:serde_json";

/// `rust/snippet_body.rs.jinja` emits `#[tokio::main]` for an async fixture, so the snippet ~keep
/// carries a tokio dependency the fixture's own config never declares. Without this requirement
/// the check project has no `tokio` in `[dependencies]` and every async Rust snippet fails to
/// resolve the attribute macro (E0433) before any of its actual content is checked.
const TOKIO_REQUIREMENT: &str = "crate:tokio";

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub struct SnippetCoverageKey {
    pub fixture_id: String,
    pub language: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GeneratedSnippetMetadata {
    pub key: SnippetCoverageKey,
    pub path: PathBuf,
    pub language: String,
    pub target: String,
    pub session: String,
    pub requires: Vec<String>,
    pub side_effect: SideEffectClass,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MissingSnippet {
    pub key: SnippetCoverageKey,
    pub reason: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DocumentedSnippetException {
    pub key: SnippetCoverageKey,
    pub reason: String,
    pub reference: String,
}

#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct SnippetCoverageLedger {
    #[serde(default)]
    pub format_version: u32,
    #[serde(default)]
    pub generated_paths: Vec<PathBuf>,
    #[serde(default)]
    pub generated_metadata: Vec<GeneratedSnippetMetadata>,
    pub expected: Vec<SnippetCoverageKey>,
    pub generated: Vec<SnippetCoverageKey>,
    pub missing: Vec<MissingSnippet>,
    pub documented_exceptions: Vec<DocumentedSnippetException>,
}

/// A snippet body the mock-harness guard refused, kept out of the coverage ledger. ~keep
///
/// This deliberately does not live on [`SnippetCoverageLedger`]: the ledger is the
/// serialized manifest, and a guard rejection is never a durable state a run may come to
/// rest in — it aborts generation. Carrying it on the in-memory report instead keeps the
/// on-disk manifest format unchanged while still giving the caller per-language,
/// per-marker attribution.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnippetGuardRejection {
    pub key: SnippetCoverageKey,
    pub marker: String,
}

/// The guard's typed failure, so a caller can tell "this body leaked harness scaffolding" ~keep
/// apart from every other reason a recipe can fail to render. Without the type the two are
/// indistinguishable strings, and a `coverage_exceptions` entry authored for an unrelated
/// capability gap silently absorbs a leak.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MockHarnessLeak {
    pub marker: String,
    pub fixture_id: String,
    pub language: String,
}

impl std::fmt::Display for MockHarnessLeak {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            formatter,
            "`{}` snippet for fixture `{}` leaks e2e mock-server scaffolding (`{}`); \
             a documentation snippet must construct its client the way a reader would",
            self.language, self.fixture_id, self.marker
        )
    }
}

impl std::error::Error for MockHarnessLeak {}

#[derive(Debug, Clone, Default)]
pub struct SnippetGenerationReport {
    pub snippets: Vec<GeneratedSnippet>,
    pub coverage: SnippetCoverageLedger,
    /// Always empty on a successful run: a non-empty value aborts generation. ~keep
    pub guard_rejections: Vec<SnippetGuardRejection>,
}

struct SnippetRenderContext<'a> {
    e2e: &'a E2eConfig,
    crate_config: &'a ResolvedCrateConfig,
    type_defs: &'a [TypeDef],
    enums: &'a [EnumDef],
    functions: &'a [crate::core::ir::FunctionDef],
    errors: &'a [crate::core::ir::ErrorDef],
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum DocumentationLanguage {
    Binding(Language),
    Shell,
}

impl DocumentationLanguage {
    fn code_fence(self) -> &'static str {
        match self {
            Self::Binding(language) => crate::docs::naming::lang_code_fence(language),
            Self::Shell => "bash",
        }
    }

    fn canonical_name(self) -> &'static str {
        self.code_fence()
    }

    fn display_name(self) -> &'static str {
        match self {
            Self::Binding(language) => crate::docs::naming::lang_display_name(language),
            Self::Shell => "Shell",
        }
    }
}

#[expect(clippy::too_many_arguments, reason = "preserves the public snippet generation API")]
pub fn generate_snippets(
    fixtures: &[Fixture],
    languages: &[String],
    e2e: &E2eConfig,
    snippets: &SnippetConfig,
    crate_config: &ResolvedCrateConfig,
    type_defs: &[TypeDef],
    enums: &[EnumDef],
    functions: &[crate::core::ir::FunctionDef],
) -> Result<Vec<GeneratedFile>> {
    Ok(generate_snippet_report(
        fixtures,
        languages,
        e2e,
        snippets,
        crate_config,
        type_defs,
        enums,
        functions,
        &[],
    )?
    .snippets
    .into_iter()
    .map(|snippet| snippet.file)
    .collect())
}

/// ~keep `errors` is `ApiSurface::errors`. Only a caller that holds it can let a snippet name the
/// exception class a specific error variant maps to (see `codegen::snippet_error_branch`); the
/// coverage-only paths, which never publish a rendered body, pass an empty slice and get the
/// generic catch-all, which is exactly what they rendered before.
#[expect(clippy::too_many_arguments, reason = "preserves the public snippet generation API")]
pub fn generate_snippet_report(
    fixtures: &[Fixture],
    languages: &[String],
    e2e: &E2eConfig,
    snippets: &SnippetConfig,
    crate_config: &ResolvedCrateConfig,
    type_defs: &[TypeDef],
    enums: &[EnumDef],
    functions: &[crate::core::ir::FunctionDef],
    errors: &[crate::core::ir::ErrorDef],
) -> Result<SnippetGenerationReport> {
    crate::with_extensions(|extensions| {
        let context = SnippetRenderContext {
            e2e,
            crate_config,
            type_defs,
            enums,
            functions,
            errors,
        };
        generate_snippet_report_with_extensions(fixtures, languages, snippets, &context, extensions)
    })
}

fn generate_snippet_report_with_extensions(
    fixtures: &[Fixture],
    languages: &[String],
    snippets: &SnippetConfig,
    context: &SnippetRenderContext<'_>,
    extensions: &[Box<dyn crate::Extension>],
) -> Result<SnippetGenerationReport> {
    validate_relative_path(Path::new(&snippets.output), "snippet output")?;
    // Pin the *previous* run's ownership record before this run computes, let alone writes,
    // anything. `e2e::run` hands the freshly computed ledger to the same write batch as the
    // snippets, and `.alef-snippet-coverage.json` sorts ahead of every sibling snippet directory
    // in that batch's `BTreeMap`, so reading it any later would read this run's intentions and
    // silently degrade `ownership::is_ledger_owned_snippet_path` to bare path identity. ~keep
    ownership::snapshot_pre_run_ledger(Path::new(&snippets.output));
    let generators = snippet_generators(languages)?;
    let mut generated = BTreeMap::<PathBuf, GeneratedSnippet>::new();
    let mut guard_rejections = Vec::<SnippetGuardRejection>::new();
    let mut coverage = SnippetCoverageLedger {
        format_version: COVERAGE_MANIFEST_VERSION,
        ..SnippetCoverageLedger::default()
    };
    for fixture in fixtures {
        validate_requirements(fixture)?;
        validate_coverage_exceptions(fixture)?;
        validate_docs_paths(fixture, languages)?;
        for (language, generator) in &generators {
            // A function this language's `exclude_functions` (or the crate-wide
            // `[crates.exclude].functions` that `language_excludes` folds in) drops can
            // never be emitted here, so the cell must not enter `expected` at all --
            // pushing it and then failing to generate it is exactly the ledger/emitter
            // disagreement this check exists to prevent. See
            // `function_excluded_for_language`'s doc comment for why this reuses the
            // docs generator's exclusion accessor instead of re-deriving the rule. ~keep
            // A call declaring `skip_languages` for this language is already excluded from
            // the executable e2e suite by `crate::e2e::codegen::fixture_inclusion` --
            // consulting the same `call_skip_reason` seam here, rather than re-deriving the
            // check, is what keeps the snippet generator from attempting (and failing) a
            // render for a call the target language cannot represent at all. This is
            // deliberately narrower than a fixture-level `skip` directive, which opts a
            // fixture out of the executable harness only and must NOT suppress a
            // documentation snippet -- see `call_skip_reason`'s doc comment and
            // `documentation_rendering_is_independent_of_test_harness_skips`. ~keep
            if crate::e2e::codegen::call_skip_reason(fixture, language, context.e2e).is_some()
                || function_excluded_for_language(fixture, language, generator.language_name(), context)
                || visitor_excluded_for_language(fixture, generator.language_name(), context)
            {
                continue;
            }
            let key = SnippetCoverageKey {
                fixture_id: fixture.id.clone(),
                language: language.to_string(),
            };
            coverage.expected.push(key.clone());
            let Some(docs) = fixture.docs.as_ref() else {
                coverage.missing.push(MissingSnippet {
                    key,
                    reason: "fixture has no documentation metadata".to_string(),
                });
                continue;
            };
            let capabilities = capabilities(language, snippets, context.crate_config);
            let capability_decision = snippet_inclusion(fixture, &capabilities);
            let exclusion_reason = match &capability_decision {
                SnippetInclusion::Exclude { missing_requirements } => {
                    Some(format!("missing requirements: {}", missing_requirements.join(", ")))
                }
                SnippetInclusion::Include => None,
            };
            if let Some(reason) = exclusion_reason {
                if let Some(exception) = coverage_exception(docs, language) {
                    coverage.documented_exceptions.push(DocumentedSnippetException {
                        key,
                        reason: exception.reason.clone(),
                        reference: exception.documentation.clone(),
                    });
                } else {
                    coverage.missing.push(MissingSnippet { key, reason });
                }
                continue;
            }
            let lang = parse_language(generator.language_name()).ok_or_else(|| {
                anyhow::anyhow!(
                    "e2e code generator `{}` has no documentation language mapping",
                    generator.language_name()
                )
            })?;
            let path = snippet_path(&snippets.output, docs, &fixture.id, language, lang)?;
            let body = match render_snippet_body(extensions, generator.as_ref(), fixture, language, context) {
                Ok(body) => body,
                Err(error) => {
                    // A guard rejection is a generator defect, not a documented limitation, so ~keep
                    // it is recorded separately and is deliberately *not* eligible for the
                    // coverage-exception branch below. Routing it there is what turned a
                    // rejected snippet into a silent deletion.
                    if let Some(leak) = error.downcast_ref::<MockHarnessLeak>() {
                        guard_rejections.push(SnippetGuardRejection {
                            key: key.clone(),
                            marker: leak.marker.clone(),
                        });
                        coverage.missing.push(MissingSnippet {
                            key,
                            reason: format!("{error:#}"),
                        });
                        continue;
                    }
                    if let Some(exception) = coverage_exception(docs, language) {
                        coverage.documented_exceptions.push(DocumentedSnippetException {
                            key,
                            reason: exception.reason.clone(),
                            reference: exception.documentation.clone(),
                        });
                    } else {
                        coverage.missing.push(MissingSnippet {
                            key,
                            reason: format!("{error:#}"),
                        });
                    }
                    continue;
                }
            };
            let content = render_snippet_markdown(&body, fixture, docs, language, lang);
            let requirements = snippet_requirements(fixture, language, &body);
            let file = GeneratedFile {
                path: path.clone(),
                content,
                generated_header: false,
            };
            let snippet = GeneratedSnippet {
                file,
                fixture_id: fixture.id.clone(),
                fixture_source: fixture.source.clone(),
                language: language.to_string(),
                requirements: requirements.clone(),
                side_effects: docs.side_effects,
            };
            if generated.insert(path.clone(), snippet).is_some() {
                bail!("snippet output collision at {}", path.display());
            }
            let relative_path = path
                .strip_prefix(&snippets.output)
                .context("generated snippet path escaped the configured output root")?
                .to_path_buf();
            coverage.generated_paths.push(relative_path.clone());
            coverage.generated_metadata.push(GeneratedSnippetMetadata {
                key: key.clone(),
                path: relative_path,
                language: lang.canonical_name().to_string(),
                target: language.to_string(),
                session: language.to_string(),
                requires: requirements,
                side_effect: docs.side_effects,
            });
            coverage.generated.push(key);
        }
    }
    // Abort before the caller reports coverage, prunes orphans, or writes anything: a run ~keep
    // that deleted the stale files and *then* failed would still have destroyed published
    // documentation.
    guard_rejections.sort_by(|left, right| left.key.cmp(&right.key));
    ensure_no_guard_rejections(&guard_rejections)?;
    coverage = coverage::normalize(coverage);
    coverage::validate(&coverage)?;
    Ok(SnippetGenerationReport {
        snippets: generated.into_values().collect(),
        coverage,
        guard_rejections,
    })
}

/// Find a fixture's coverage exception for `language`.
///
/// Both the exception's declared key and `language` resolve through
/// [`crate::e2e::fixture::canonical_language`], so an exception declared under one accepted
/// spelling of a backend (e.g. `docs.coverage_exceptions = { c = ... }`) still applies when
/// that backend is configured under an alias spelling (e.g. running as `ffi`). Without this,
/// `"c"` and `"ffi"` silently stopped matching each other and the exception never fired. ~keep
fn coverage_exception<'a>(
    docs: &'a FixtureDocs,
    language: &str,
) -> Option<&'a crate::e2e::fixture::SnippetCoverageException> {
    let canonical = crate::e2e::fixture::canonical_language(language);
    docs.coverage_exceptions
        .iter()
        .find(|(key, _)| crate::e2e::fixture::canonical_language(key) == canonical)
        .map(|(_, exception)| exception)
}

/// The canonical e2e language name every registered code generator declares, used to
/// validate `docs.coverage_exceptions` keys against real backends rather than arbitrary
/// strings.
///
/// Delegates to [`crate::e2e::known_e2e_target_names`] -- the same enumeration
/// `validate_skip_languages` (`src/e2e/fixture.rs`) checks `skip.languages` ids against --
/// rather than re-deriving the generator list here. Two independently computed "is this a
/// real backend" enumerations is the same defect shape as two alias lists: nothing forces
/// them to agree, and only one needs to fall behind for a validator to start passing
/// nonsense through. ~keep
fn known_language_names() -> BTreeSet<String> {
    crate::e2e::known_e2e_target_names().into_iter().collect()
}

/// Render `known` as a human-readable list, expanding any alias groups (e.g. `"c"` also
/// accepts `"c_ffi"` and `"ffi"`) so a validation error can name every accepted spelling.
fn describe_known_languages(known: &BTreeSet<String>) -> String {
    known
        .iter()
        .map(|canonical| {
            let aliases = crate::e2e::fixture::language_alias_groups()
                .iter()
                .find(|(name, _)| *name == canonical.as_str())
                .map(|(_, aliases)| *aliases)
                .unwrap_or_default();
            if aliases.is_empty() {
                canonical.clone()
            } else {
                format!("{canonical} (also accepted: {})", aliases.join(", "))
            }
        })
        .collect::<Vec<_>>()
        .join(", ")
}

fn validate_coverage_exceptions(fixture: &Fixture) -> Result<()> {
    let Some(docs) = &fixture.docs else {
        return Ok(());
    };
    let known = known_language_names();
    for (language, exception) in &docs.coverage_exceptions {
        if language.trim().is_empty() || exception.reason.trim().is_empty() {
            bail!(
                "fixture `{}` has invalid coverage exception for language `{language}`: language and reason must be non-empty",
                fixture.id
            );
        }
        if !known.contains(crate::e2e::fixture::canonical_language(language)) {
            bail!(
                "fixture `{}` has a coverage exception for unknown language `{language}`; accepted language spellings: {}",
                fixture.id,
                describe_known_languages(&known)
            );
        }
        validate_documentation_reference(&exception.documentation).map_err(|error| {
            anyhow::anyhow!(
                "fixture `{}` has invalid coverage exception documentation for language `{language}`: {error}",
                fixture.id
            )
        })?;
    }
    Ok(())
}

fn validate_documentation_reference(reference: &str) -> Result<()> {
    if reference.trim() != reference || reference.is_empty() {
        bail!("reference must be non-empty and have no surrounding whitespace");
    }
    if reference.starts_with("https://") || reference.starts_with("http://") {
        if reference.chars().any(char::is_whitespace) {
            bail!("URL reference must not contain whitespace");
        }
        return Ok(());
    }
    validate_relative_path(Path::new(reference), "documentation reference")
}

fn render_snippet_body(
    extensions: &[Box<dyn crate::Extension>],
    generator: &dyn E2eCodegen,
    fixture: &Fixture,
    language: &str,
    context: &SnippetRenderContext<'_>,
) -> Result<String> {
    let docs_fixture = fixture.docs_call_fixture();
    for extension in extensions {
        if let Some(body) = extension
            .render_e2e_snippet(
                &docs_fixture,
                context.e2e,
                context.crate_config,
                language,
                context.type_defs,
                context.enums,
            )
            .map_err(|error| anyhow::anyhow!("extension `{}` could not render snippet: {error:#}", extension.name()))?
        {
            if body.trim().is_empty() {
                bail!("extension `{}` returned an empty snippet body", extension.name());
            }
            mock_harness_guard::reject_mock_harness_scaffolding(&body, &docs_fixture, language)?;
            return Ok(body);
        }
    }
    let call = context.e2e.resolve_call_for_fixture(
        docs_fixture.call.as_deref(),
        &docs_fixture.id,
        &docs_fixture.resolved_category(),
        &docs_fixture.tags,
        &docs_fixture.input,
    );
    let docs_fixture = mock_url_defaults::with_default_mock_url_literals(docs_fixture, call);
    let fixture = &docs_fixture;
    if let Some(kind) = recipe_policy::extension_owned_recipe_kind(fixture, fixture.resolved_args(call)) {
        bail!("{kind} fixture requires an extension-owned documentation recipe");
    }
    let effective_function = call
        .effective_function(language)
        .or_else(|| {
            // The naive identity fallback below derives a symbol name from the raw
            // `fixture.call` config text (`register_fn`/`unregister_fn`/`clear_fn`), which
            // can diverge from what the FFI backend actually generates (see
            // `trait_bridge_function_identity`'s doc comment). A fixture author who set
            // `skip.languages` for this language has already declared that the harness
            // (and by extension this naive fallback) cannot speak for it here; only trust
            // the fallback when the fixture is not skipped for this language. Fixtures with
            // a real, extension-owned recipe never reach this branch — the extension loop
            // above already returned their body, and `recipe_policy::extension_owned_recipe_kind`
            // already bailed for fixtures that require one but lack it.
            let skipped_for_language = fixture.skip.as_ref().is_some_and(|skip| skip.should_skip(language));
            (!skipped_for_language && crate::e2e::fixture::canonical_language(language) == "c")
                .then(|| crate::e2e::codegen::recipe::trait_bridge_function_identity(context.crate_config, fixture))
                .flatten()
        })
        .unwrap_or_default();
    if effective_function.trim().is_empty() {
        bail!(
            "built-in `{language}` snippet recipe has no function identity; configure a call function or provide an extension-owned documentation recipe"
        );
    }
    let body = generator
        .render_snippet_body_with_functions(
            fixture,
            context.e2e,
            context.crate_config,
            context.type_defs,
            context.enums,
            context.functions,
            context.errors,
        )
        .map_err(|error| anyhow::anyhow!("built-in `{language}` snippet recipe is incompatible: {error:#}"))?;
    if body.trim().is_empty() {
        bail!("built-in `{language}` snippet recipe returned an empty body");
    }
    mock_harness_guard::reject_mock_harness_scaffolding(&body, fixture, language)?;
    Ok(body)
}

/// Turn every guard rejection this run produced into one aborting, attributed error. ~keep
///
/// A rejection must never come to rest as a coverage gap: `missing` cells can be retired by
/// writing a `docs.coverage_exceptions` entry, and an exception authored for an unrelated
/// capability gap would then also retire a leak — deleting the snippet from the docs tree
/// with no signal at all. Failing here, before the caller prunes orphans or writes any
/// file, is what makes the denylist's failure mode loud instead of a silent deletion.
fn ensure_no_guard_rejections(rejections: &[SnippetGuardRejection]) -> Result<()> {
    if rejections.is_empty() {
        return Ok(());
    }
    let mut by_language: BTreeMap<&str, BTreeMap<&str, Vec<&str>>> = BTreeMap::new();
    for rejection in rejections {
        by_language
            .entry(rejection.key.language.as_str())
            .or_default()
            .entry(rejection.marker.as_str())
            .or_default()
            .push(rejection.key.fixture_id.as_str());
    }
    let mut detail = String::new();
    for (language, markers) in &by_language {
        let language_total: usize = markers.values().map(Vec::len).sum();
        detail.push_str(&format!("\n  {language} ({language_total}):"));
        for (marker, fixtures) in markers {
            detail.push_str(&format!(
                "\n    `{marker}` ({}): {}",
                fixtures.len(),
                fixtures.join(", ")
            ));
        }
    }
    bail!(
        "{} documentation snippet(s) were rejected by the mock-harness guard; each would otherwise \
         disappear from the docs tree with no report. Fix the generator so the snippet constructs \
         its client the way a reader would — a `docs.coverage_exceptions` entry cannot retire a \
         guard rejection.{detail}",
        rejections.len()
    )
}

fn snippet_generators(languages: &[String]) -> Result<Vec<(&str, Box<dyn E2eCodegen>)>> {
    let mut available = BTreeMap::new();
    for generator in all_generators() {
        let name = generator.language_name();
        if available.insert(name, generator).is_some() {
            bail!("duplicate e2e code generator registered for snippet language `{name}`");
        }
    }
    let mut requested = BTreeSet::new();
    languages
        .iter()
        .map(|language| {
            let generator_name = generator_name(language);
            if !requested.insert(generator_name) {
                bail!("duplicate snippet language resolves to e2e code generator `{generator_name}`");
            }
            available
                .remove(generator_name)
                .map(|generator| (language.as_str(), generator))
                .ok_or_else(|| anyhow::anyhow!("no e2e code generator registered for snippet language `{language}`"))
        })
        .collect()
}

/// Resolve a configured e2e language to the generator name registered in [`all_generators`].
///
/// Delegates entirely to [`crate::e2e::fixture::canonical_language`] -- the single alias
/// table for backends with more than one accepted spelling -- rather than carrying its own
/// copy of the `"c"`/`"c_ffi"`/`"ffi"` and `"rust"`/`"core"`/`"rust_core"` groups.
fn generator_name(language: &str) -> &str {
    crate::e2e::fixture::canonical_language(language)
}

/// The CLI invocation that produces fixture snippets, embedded verbatim in every
/// snippet's provenance header by [`render_snippet_markdown`].
const SNIPPET_REGENERATE_COMMAND: &str = "alef e2e generate";

/// Render one fixture snippet as a self-marking Markdown document.
///
/// The provenance header comes from [`crate::docs::with_html_header`] — the same emitter
/// `readme::template` and `docs::render` use — rather than a second marker producer, so the
/// bytes the ownership guard reads back are byte-identical across every `.md` alef writes.
///
/// Why it is needed here at all: `write::marker_comment_style`'s doc excludes `.md` on the
/// stated grounds that "`readme::template` and `docs::render` both route content through
/// `docs::render::with_html_header`". That is true of READMEs and docs pages and false of
/// fixture snippets, which are assembled here and never touch `docs::render`. The result was
/// a `.md` that no side stamps: `generated_header` is `false`, `marker_header_syntax` is
/// `None` for `.md`, and the snippet output root sits outside any path
/// `cache::record_scaffold_owned_path` had recorded — so once a snippet existed on disk the
/// write guard could prove nothing and refused it forever (15,677 refusals in one consumer
/// repo, 9,139 in another). ~keep
///
/// Placement is load-bearing and has no slack. `with_html_header` puts the marker after the
/// YAML front matter (it must: Astro/Starlight imports these files as content and requires the
/// opening `---` to be the first bytes) with one blank line between, so with
/// `snippets/file.md.jinja`'s front matter the marker lands on line 10 at worst — the last line
/// `hash::content_has_alef_marker`'s 10-line scan window reads. **Adding a front-matter line
/// beyond that budget pushes the marker out of the window and silently restores the deadlock**;
/// the marker would still be in the file and nothing would read it. The front matter is 8 lines
/// when `level:` is present and 7 when it is omitted, so the omitted case has one line of slack
/// and the present case has none. `snippet_marker_lands_inside_the_read_side_scan_window`
/// and its control fail if that budget is spent. ~keep
fn render_snippet_markdown(
    body: &str,
    fixture: &Fixture,
    docs: &FixtureDocs,
    target: &str,
    language: DocumentationLanguage,
) -> String {
    let snippet_id = format!("fixture_{target}_{}", fixture.id);
    let requirements = snippet_requirements(fixture, target, body);
    let requires = serde_json::to_string(&requirements).unwrap_or_else(|_| "[]".to_string());
    let rendered = crate::e2e::template_env::render(
        "snippets/file.md.jinja",
        minijinja::context! {
            description => docs.description.as_deref().unwrap_or(&fixture.description),
            fence => language.code_fence(),
            id => snippet_id,
            language => language.canonical_name(),
            level => level_stamp(docs.side_effects),
            requires => requires,
            side_effect => side_effect_name(docs.side_effects),
            target => target,
            title => language.display_name(),
            // Generators end their body with a newline; the template adds its own before the
            // closing fence, so passing the body through verbatim put a blank line inside every
            // one of the thousands of generated code fences. ~keep
            body => body.trim_end(),
        },
    );
    crate::docs::with_html_header(rendered, SNIPPET_REGENERATE_COMMAND)
}

fn snippet_requirements(fixture: &Fixture, target: &str, body: &str) -> Vec<String> {
    let mut requirements = fixture.requirements.clone();
    if target == "rust" && fixture.visitor.is_some() && !requirements.iter().any(|value| value == "feature:visitor") {
        requirements.push("feature:visitor".to_string());
    }
    if generator_name(target) == "rust"
        && body.contains("serde_json::")
        && !requirements.iter().any(|value| value == SERDE_JSON_REQUIREMENT)
    {
        requirements.push(SERDE_JSON_REQUIREMENT.to_string());
    }
    if generator_name(target) == "rust"
        && body.contains("#[tokio::main]")
        && !requirements.iter().any(|value| value == TOKIO_REQUIREMENT)
    {
        requirements.push(TOKIO_REQUIREMENT.to_string());
    }
    requirements
}

/// The front-matter `level` a generated snippet declares. `effective_validation_level`
/// (`src/snippets/runner.rs`) folds this with the requested level by `min`, so any concrete
/// value here can only ever lower validation, never raise it.
///
/// `94d09809d` ("fix(e2e): typecheck fixture snippets") made this stamp unconditional, replacing
/// a `syntax` ceiling with `typecheck` specifically because fixtures with side effects the e2e
/// harness cannot safely execute unattended (network calls, process/install/server side effects)
/// were being validated no deeper than syntax. That protection is still needed for exactly those
/// fixtures. It was never needed for `Safe` ones, and stamping them anyway silently capped every
/// generated snippet at `typecheck` regardless of what the workspace and the snippet's own
/// capabilities could actually support. A `Safe` snippet OMITS the `level:` key entirely — an
/// absent key deserialises to `SnippetMetadata::level == None` exactly as an explicit `null` did
/// — so it has nothing to fold against `requested` and validates at whatever level the workspace
/// and validator achieve on their own.
///
/// The key is omitted rather than rendered `level: null` because these files are Astro content
/// entries, and Astro's collection schema types `level` as an optional STRING: an absent key
/// validates, an explicit YAML null does not (`Expected type "string", received "object"`). One
/// such entry fails the whole `astro build`, which took out 810 generated snippets in a consumer
/// docs site. Alef's own parser treats the two spellings identically, so nothing here is lost. ~keep
fn level_stamp(side_effects: SideEffectClass) -> Option<&'static str> {
    if side_effects == SideEffectClass::Safe {
        None
    } else {
        Some("typecheck")
    }
}

fn side_effect_name(side_effect: SideEffectClass) -> &'static str {
    match side_effect {
        SideEffectClass::Safe => "safe",
        SideEffectClass::Network => "network",
        SideEffectClass::Process => "process",
        SideEffectClass::Install => "install",
        SideEffectClass::Server => "server",
    }
}

fn validate_requirements(fixture: &Fixture) -> Result<()> {
    for requirement in &fixture.requirements {
        let valid = requirement.split_once(':').is_some_and(|(kind, value)| {
            matches!(kind, "feature" | "model" | "service" | "credential") && !value.is_empty() && !value.contains(':')
        });
        if !valid {
            bail!("fixture `{}` has invalid requirement token `{requirement}`", fixture.id);
        }
    }
    Ok(())
}

pub fn snippet_inclusion(fixture: &Fixture, capabilities: &BTreeSet<String>) -> SnippetInclusion {
    let missing_requirements: Vec<_> = fixture
        .requirements
        .iter()
        .filter(|requirement| !capabilities.contains(*requirement))
        .cloned()
        .collect();
    if missing_requirements.is_empty() {
        SnippetInclusion::Include
    } else {
        SnippetInclusion::Exclude { missing_requirements }
    }
}

fn capabilities(language: &str, snippets: &SnippetConfig, crate_config: &ResolvedCrateConfig) -> BTreeSet<String> {
    let mut values = snippets.capabilities.for_language(language);
    values.extend(crate_config.features.iter().map(|feature| format!("feature:{feature}")));
    values
}

/// Whether the function a fixture's call resolves to for `language` is excluded for that
/// language, and therefore can never be rendered into a snippet.
///
/// Reuses [`crate::docs::language_pages::excludes::language_excludes`] -- the accessor the
/// docs generator already consults for the same question -- rather than re-deriving the
/// per-language `exclude_functions` union here. A second copy of that rule is exactly how a
/// ledger and its emitter drift apart: one path evolves (a language gains an override, a new
/// per-language config field is added) and the other silently keeps checking the old shape.
/// [`CallConfig::core_lookup_name`] gives the Rust-spelled identity `exclude_functions`
/// entries are keyed by, matching every built-in snippet recipe's own resolution (see
/// `e2e/codegen/go/snippet.rs`, `kotlin/snippet.rs`, `php/snippet.rs`, `ruby/snippet.rs`, and
/// the WASM-specific `rust_identity_for_wasm_symbol`, which resolves the same identity for the
/// one target that also accepts the JS spelling of an override). ~keep
fn function_excluded_for_language(
    fixture: &Fixture,
    language: &str,
    generator_language_name: &str,
    context: &SnippetRenderContext<'_>,
) -> bool {
    let Some(DocumentationLanguage::Binding(lang)) = parse_language(generator_language_name) else {
        return false;
    };
    let docs_fixture = fixture.docs_call_fixture();
    let call = context.e2e.resolve_call_for_fixture(
        docs_fixture.call.as_deref(),
        &docs_fixture.id,
        &docs_fixture.resolved_category(),
        &docs_fixture.tags,
        &docs_fixture.input,
    );
    let Some(function_name) = call.core_lookup_name(language) else {
        return false;
    };
    let (excluded_functions, _) = crate::docs::language_pages::excludes::language_excludes(context.crate_config, lang);
    excluded_functions.contains(function_name.as_ref())
}

/// Whether `fixture` exercises the fixture engine's generic visitor/trait-bridge entry point
/// ([`Fixture::visitor`]) and this language excludes it via the
/// [`crate::e2e::fixture::VISITOR_EXCLUDE_FUNCTION_NAME`] convention.
///
/// `exclude_functions` normally names a real Rust function, so
/// [`function_excluded_for_language`] cannot catch this case: a visitor fixture's *call*
/// resolves to some ordinary function (e.g. `convert`), while the visitor itself attaches
/// through a trait-bridge parameter or options-struct field that never has its own IR function
/// name. `e2e::codegen::kotlin_android::project` already applies this exact rule when deciding
/// whether to emit a fixture's Kotlin-Android e2e test or fall back to
/// `ExcludedBindingsTest.kt`; without the matching check here, snippet generation rendered real
/// code against a visitor API the binding never exposed for that language. ~keep
fn visitor_excluded_for_language(
    fixture: &Fixture,
    generator_language_name: &str,
    context: &SnippetRenderContext<'_>,
) -> bool {
    if fixture.visitor.is_none() {
        return false;
    }
    let Some(DocumentationLanguage::Binding(lang)) = parse_language(generator_language_name) else {
        return false;
    };
    let (excluded_functions, _) = crate::docs::language_pages::excludes::language_excludes(context.crate_config, lang);
    excluded_functions.contains(crate::e2e::fixture::VISITOR_EXCLUDE_FUNCTION_NAME)
}

fn snippet_path(
    output: &str,
    docs: &FixtureDocs,
    fixture_id: &str,
    target_language: &str,
    language: DocumentationLanguage,
) -> Result<PathBuf> {
    if let Some(relative) = docs.paths.get(target_language) {
        let relative = Path::new(relative);
        validate_relative_path(relative, "fixture docs target path")?;
        if relative.extension().and_then(|value| value.to_str()) != Some("md") {
            bail!("fixture docs target path must end in .md: {}", relative.display());
        }
        return Ok(Path::new(output)
            .join(snippet_output_slug(target_language, language))
            .join(relative));
    }
    validate_component(&docs.topic, "snippet topic")?;
    let stem = docs.stem.as_deref().unwrap_or(fixture_id);
    validate_component(stem, "snippet stem")?;
    Ok(Path::new(output)
        .join(snippet_output_slug(target_language, language))
        .join(&docs.topic)
        .join(format!("{stem}.md")))
}

fn snippet_output_slug(target_language: &str, language: DocumentationLanguage) -> &'static str {
    match target_language {
        "node" => "typescript",
        "wasm" => "wasm",
        "kotlin_android" => "kotlin-android",
        "brew" => "brew",
        "homebrew" => "homebrew",
        _ => language.canonical_name(),
    }
}

fn validate_component(value: &str, label: &str) -> Result<()> {
    if value.is_empty() || Path::new(value).components().count() != 1 || matches!(value, "." | "..") {
        bail!("unsafe {label} `{value}`");
    }
    Ok(())
}

fn validate_relative_path(path: &Path, label: &str) -> Result<()> {
    if path.as_os_str().is_empty()
        || path.is_absolute()
        || path.components().any(|part| !matches!(part, Component::Normal(_)))
    {
        bail!("{label} must be a safe relative path: {}", path.display());
    }
    Ok(())
}

fn validate_docs_paths(fixture: &Fixture, languages: &[String]) -> Result<()> {
    let Some(docs) = &fixture.docs else {
        return Ok(());
    };
    for target in docs.paths.keys() {
        if !languages.iter().any(|language| language == target) {
            bail!(
                "fixture `{}` docs path targets unconfigured language `{target}`",
                fixture.id
            );
        }
    }
    Ok(())
}

/// Aliases resolve through [`crate::e2e::fixture::canonical_language`] before matching here,
/// so `"c_ffi"`/`"ffi"` and `"core"`/`"rust_core"` are not spelled out a second time in this
/// match arm list.
fn parse_language(value: &str) -> Option<DocumentationLanguage> {
    let language = match crate::e2e::fixture::canonical_language(value) {
        "python" => Language::Python,
        "node" => Language::Node,
        "wasm" => Language::Wasm,
        "ruby" => Language::Ruby,
        "php" | "php_ext" => Language::Php,
        "elixir" => Language::Elixir,
        "go" => Language::Go,
        "java" => Language::Java,
        "csharp" => Language::Csharp,
        "r" => Language::R,
        "rust" => Language::Rust,
        "kotlin" => Language::Kotlin,
        "kotlin_android" => Language::KotlinAndroid,
        "swift" => Language::Swift,
        "dart" => Language::Dart,
        "gleam" => Language::Gleam,
        "zig" => Language::Zig,
        "c" => Language::C,
        "brew" | "homebrew" => return Some(DocumentationLanguage::Shell),
        _ => return None,
    };
    Some(DocumentationLanguage::Binding(language))
}

#[cfg(test)]
mod tests;