projectatlas/

atlas_map.rs

//! Purpose: Render and lint `ProjectAtlas` structure maps from Rust.

use blake3::Hasher;
use projectatlas_core::{
    CanonicalProjectRoot, Node, NodeKind,
    language::{BROAD_SOURCE_EXTENSIONS, canonical_language_id},
    validated_repo_file_key,
};
use projectatlas_db::AtlasStore;
use projectatlas_fs::{ScanOptions, explicit_language_override, scan_repo};
use projectatlas_symbols::document_format_for_path;
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet};
use std::fs::{self, OpenOptions};
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};
use thiserror::Error;
use toml_edit::{Array, DocumentMut, Item, Table, value};

/// Legacy folder-purpose filename accepted only as migration input.
const DEFAULT_LEGACY_PURPOSE_FILENAME: &str = ".purpose";
/// Default legacy map import path and adjacent JSON export location.
const DEFAULT_MAP_PATH: &str = ".projectatlas/projectatlas.toon";
/// Maximum bytes in a complete map response.
pub(crate) const MAX_MAP_RESPONSE_BYTES: usize = 4 * 1024 * 1024;
/// Default non-source summary input path.
const DEFAULT_NONSOURCE_PATH: &str = ".projectatlas/projectatlas-nonsource-files.toon";
/// Durable `.projectatlas` inputs indexed by `SQLite` but ignored by legacy map/lint.
const DURABLE_PROJECTATLAS_INPUT_PATHS: &[&str] = &[
    ".projectatlas/config.toml",
    ".projectatlas/projectatlas-nonsource-files.toon",
    ".projectatlas/projectatlas-purpose-review.json",
];
/// Default maximum number of lines scanned for purpose headers.
const DEFAULT_MAX_SCAN_LINES: usize = 80;
/// Default maximum UTF-8 file size persisted into `SQLite` text search.
pub(crate) const DEFAULT_TEXT_INDEX_MAX_BYTES: u64 = 2_000_000;
/// Default maximum purpose summary length.
const DEFAULT_SUMMARY_MAX_LENGTH: usize = 140;
/// Ordered overview keys written into the TOON map.
const OVERVIEW_KEYS: &[&str] = &[
    "tracked_source_files",
    "tracked_nonsource_files",
    "tracked_files_total",
    "tracked_folders",
    "source_extensions",
    "exclude_dir_names",
    "exclude_path_prefixes",
];
/// Source extensions scanned for Purpose metadata by default.
const DEFAULT_SOURCE_EXTENSIONS: &[&str] = BROAD_SOURCE_EXTENSIONS;
/// Document extensions admitted by the bounded document parser in addition to
/// the frozen v0.3.26 broad-source compatibility set.
const DOCUMENT_SOURCE_EXTENSIONS: &[&str] = &[".pdf", ".docx"];
/// Directory names excluded from scans even when config is hand-edited.
const REQUIRED_EXCLUDE_DIR_NAMES: &[&str] = &[".git", ".projectatlas"];
/// Directory names excluded from scans by default.
const DEFAULT_EXCLUDE_DIR_NAMES: &[&str] = &[
    ".cache",
    ".egg-info",
    ".git",
    ".idea",
    ".mypy_cache",
    ".projectatlas",
    ".pytest_cache",
    ".tmp",
    ".venv",
    "__pycache__",
    "artifacts",
    "build",
    "coverage",
    "dist",
    "node_modules",
    "sandbox",
    "target",
    "temp",
    "test-results",
    "tmp",
];
/// Asset extensions recognized for untracked-file reporting.
const DEFAULT_ASSET_EXTENSIONS: &[&str] = &[
    ".bmp", ".gif", ".ico", ".jpeg", ".jpg", ".pdf", ".png", ".svg", ".ttf", ".webp", ".woff",
    ".woff2",
];
/// Line comment prefixes supported by default.
const DEFAULT_LINE_COMMENT_PREFIXES: &[&str] = &["//", "#", "--", ";"];

/// Atlas map operation errors.
#[derive(Debug, Error)]
pub(crate) enum AtlasMapError {
    /// A complete map cannot fit in the supported response budget.
    #[error("map response exceeds byte limit: observed {observed}, limit {limit}")]
    ResponseLimitExceeded {
        /// Encoded response size.
        observed: usize,
        /// Maximum supported response size.
        limit: usize,
    },
    /// Filesystem operation failed.
    #[error("io error for {path:?}: {source}")]
    Io {
        /// Path involved in the failed operation.
        path: PathBuf,
        /// Source IO error.
        source: std::io::Error,
    },
    /// TOML parsing failed.
    #[error("toml parse error for {path:?}: {source}")]
    Toml {
        /// TOML path that failed to parse.
        path: PathBuf,
        /// Source TOML parse error.
        source: Box<toml::de::Error>,
    },
    /// Filesystem scanner failed.
    #[error("{0}")]
    Scan(#[from] projectatlas_fs::FsError),
    /// Durable index read failed.
    #[error("database error for {path:?}: {message}")]
    Database {
        /// Database path that failed.
        path: PathBuf,
        /// Source database error text.
        message: String,
    },
    /// Config or manual metadata referenced an unsafe repository path.
    #[error("invalid repository-relative path {path:?}: {message}")]
    InvalidRepositoryPath {
        /// Invalid path text.
        path: String,
        /// Validation failure.
        message: String,
    },
    /// A configured language selector or target is invalid.
    #[error("invalid language override {selector:?} = {language:?}: {message}")]
    InvalidLanguageOverride {
        /// Exact filename or extension selector.
        selector: String,
        /// Requested canonical ID or alias.
        language: String,
        /// Validation failure.
        message: String,
    },
    /// Editable TOML config was malformed for the requested operation.
    #[error("toml edit error for {path:?}: {message}")]
    TomlEdit {
        /// Config path that failed to edit.
        path: PathBuf,
        /// TOML edit failure.
        message: String,
    },
}

/// Result alias for atlas map operations.
type AtlasMapResult<T> = Result<T, AtlasMapError>;

/// Raw deserialized config file.
#[derive(Debug, Default, Deserialize)]
struct RawConfig {
    /// Project table.
    project: Option<RawProject>,
    /// Scan table.
    scan: Option<RawScan>,
    /// Purpose table.
    purpose: Option<RawPurpose>,
    /// Summary rules table.
    summary_rules: Option<RawSummaryRules>,
    /// Untracked policy table.
    untracked: Option<RawUntracked>,
}

/// Raw project table.
#[derive(Debug, Default, Deserialize)]
struct RawProject {
    /// Repository root.
    root: Option<String>,
    /// Legacy map import path and adjacent JSON sidecar location.
    map_path: Option<String>,
    /// Non-source file summary path.
    nonsource_files_path: Option<String>,
    /// Legacy manual file summary path.
    manual_files_path: Option<String>,
    /// Purpose filename.
    purpose_filename: Option<String>,
}

/// Raw scan table.
#[derive(Debug, Default, Deserialize)]
struct RawScan {
    /// Source extensions.
    source_extensions: Option<Vec<String>>,
    /// Excluded directory names.
    exclude_dir_names: Option<Vec<String>>,
    /// Excluded directory suffixes.
    exclude_dir_suffixes: Option<Vec<String>>,
    /// Excluded path prefixes.
    exclude_path_prefixes: Option<Vec<String>>,
    /// Non-source path prefixes.
    non_source_path_prefixes: Option<Vec<String>>,
    /// Maximum header scan lines.
    max_scan_lines: Option<usize>,
    /// Maximum UTF-8 file size persisted into `SQLite` text search.
    text_index_max_bytes: Option<u64>,
    /// Explicit exact-filename or extension language selections.
    language_overrides: Option<BTreeMap<String, String>>,
}

/// Raw purpose table.
#[derive(Debug, Default, Deserialize)]
struct RawPurpose {
    /// Default purpose header style.
    default_style: Option<String>,
    /// Line-comment prefixes.
    line_comment_prefixes: Option<Vec<String>>,
    /// Per-extension purpose styles.
    styles_by_extension: Option<BTreeMap<String, String>>,
}

/// Raw summary-rules table.
#[derive(Debug, Default, Deserialize)]
struct RawSummaryRules {
    /// Whether purpose summaries must be ASCII.
    ascii_only: Option<bool>,
    /// Whether purpose summaries may contain commas.
    no_commas: Option<bool>,
    /// Maximum purpose summary length.
    max_length: Option<usize>,
}

/// Raw untracked table.
#[derive(Debug, Default, Deserialize)]
struct RawUntracked {
    /// Allowed untracked filenames.
    allowed_filenames: Option<Vec<String>>,
    /// Allowed untracked directory prefixes.
    allowlist_dir_prefixes: Option<Vec<String>>,
    /// Allowed untracked files.
    allowlist_files: Option<Vec<String>>,
    /// Allowed asset prefixes.
    asset_allowed_prefixes: Option<Vec<String>>,
    /// Asset extensions.
    asset_extensions: Option<Vec<String>>,
}

/// Normalized atlas map configuration.
#[derive(Clone, Debug)]
pub(crate) struct AtlasMapConfig {
    /// Repository root.
    pub(crate) root: PathBuf,
    /// Lossless UTF-8 generated TOON map path, when one is available.
    pub(crate) map_path: PathBuf,
    /// Non-source file summary path.
    pub(crate) nonsource_files_path: PathBuf,
    /// Purpose filename.
    purpose_filename: String,
    /// Source extensions that require purpose headers.
    source_extensions: BTreeSet<String>,
    /// Excluded directory names.
    exclude_dir_names: BTreeSet<String>,
    /// Excluded directory suffixes.
    exclude_dir_suffixes: BTreeSet<String>,
    /// Excluded repository-relative prefixes.
    exclude_path_prefixes: BTreeSet<String>,
    /// Prefixes treated as non-source even when extensions match.
    non_source_path_prefixes: BTreeSet<String>,
    /// Validated exact-filename or extension language overrides.
    language_overrides: BTreeMap<String, String>,
    /// Allowed untracked filenames.
    allowed_untracked_filenames: BTreeSet<String>,
    /// Allowed untracked directory prefixes.
    untracked_allowlist_dir_prefixes: BTreeSet<String>,
    /// Allowed untracked files.
    untracked_allowlist_files: BTreeSet<String>,
    /// Allowed asset root prefixes.
    asset_allowed_prefixes: BTreeSet<String>,
    /// Asset extensions.
    asset_extensions: BTreeSet<String>,
    /// Durable `SQLite` index path.
    db_path: PathBuf,
    /// Maximum lines to scan for purpose headers.
    max_scan_lines: usize,
    /// Maximum UTF-8 file size persisted into `SQLite` text search.
    text_index_max_bytes: u64,
    /// Maximum purpose summary length.
    summary_max_length: usize,
    /// Whether summaries must be ASCII.
    summary_ascii_only: bool,
    /// Whether summaries may contain commas.
    summary_no_commas: bool,
    /// Per-extension purpose styles.
    purpose_styles: BTreeMap<String, String>,
    /// Default purpose style.
    purpose_default_style: String,
    /// Supported line-comment prefixes.
    line_comment_prefixes: Vec<String>,
}

impl AtlasMapConfig {
    /// Bind database-backed map and lint work to the selected runtime database.
    pub(crate) fn with_database_path(mut self, database_path: &Path) -> Self {
        self.db_path = database_path.to_path_buf();
        self
    }

    /// Return scanner options derived from the normalized project config.
    pub(crate) fn scan_options(&self) -> ScanOptions {
        ScanOptions {
            exclude_dir_names: self.exclude_dir_names.iter().cloned().collect(),
            exclude_dir_suffixes: self.exclude_dir_suffixes.iter().cloned().collect(),
            exclude_path_prefixes: self.exclude_path_prefixes.iter().cloned().collect(),
            language_overrides: self.language_overrides.clone(),
            admit_optional_languages: false,
        }
    }

    /// Return the configured maximum UTF-8 file size for `SQLite` text search.
    pub(crate) fn text_index_max_bytes(&self) -> u64 {
        self.text_index_max_bytes
    }

    /// Return the configured legacy folder-purpose filename.
    pub(crate) fn purpose_filename(&self) -> &str {
        &self.purpose_filename
    }
}

/// Serializable view of the effective `ProjectAtlas` configuration.
#[derive(Debug, Serialize)]
pub(crate) struct EffectiveConfigReport {
    /// Lossless UTF-8 repository root, when one is available.
    pub(crate) root: Option<String>,
    /// Lossless UTF-8 generated TOON map path, when one is available.
    pub(crate) map_path: Option<String>,
    /// Lossless UTF-8 non-source purpose registry path, when one is available.
    pub(crate) nonsource_files_path: Option<String>,
    /// Lossless UTF-8 durable `SQLite` index path, when one is available.
    pub(crate) db_path: Option<String>,
    /// Purpose metadata filename.
    pub(crate) purpose_filename: String,
    /// Source extensions treated as indexable project content.
    pub(crate) source_extensions: Vec<String>,
    /// Directory names excluded from normal scans.
    pub(crate) exclude_dir_names: Vec<String>,
    /// Repository-relative path prefixes excluded from normal scans.
    pub(crate) exclude_path_prefixes: Vec<String>,
    /// Configured non-source path prefixes.
    pub(crate) non_source_path_prefixes: Vec<String>,
    /// Validated exact-filename or extension language overrides.
    pub(crate) language_overrides: BTreeMap<String, String>,
    /// Default purpose style.
    pub(crate) purpose_default_style: String,
    /// Per-extension purpose style overrides.
    pub(crate) purpose_styles: BTreeMap<String, String>,
    /// Supported line comment prefixes for purpose headers.
    pub(crate) line_comment_prefixes: Vec<String>,
    /// Maximum file size persisted into `SQLite` text search.
    pub(crate) text_index_max_bytes: u64,
    /// Maximum purpose line length.
    pub(crate) summary_max_length: usize,
    /// Whether purpose summaries must be ASCII.
    pub(crate) summary_ascii_only: bool,
    /// Whether purpose summaries may not contain commas.
    pub(crate) summary_no_commas: bool,
}

/// Build the effective configuration report used by agents and docs.
pub(crate) fn effective_config_report(config: &AtlasMapConfig) -> EffectiveConfigReport {
    EffectiveConfigReport {
        root: CanonicalProjectRoot::from_path(&config.root)
            .ok()
            .and_then(|root| root.display_string().ok()),
        map_path: effective_config_path_display(&config.map_path),
        nonsource_files_path: effective_config_path_display(&config.nonsource_files_path),
        db_path: effective_config_path_display(&config.db_path),
        purpose_filename: config.purpose_filename.clone(),
        source_extensions: config.source_extensions.iter().cloned().collect(),
        exclude_dir_names: config.exclude_dir_names.iter().cloned().collect(),
        exclude_path_prefixes: config.exclude_path_prefixes.iter().cloned().collect(),
        non_source_path_prefixes: config.non_source_path_prefixes.iter().cloned().collect(),
        language_overrides: config.language_overrides.clone(),
        purpose_default_style: config.purpose_default_style.clone(),
        purpose_styles: config.purpose_styles.clone(),
        line_comment_prefixes: config.line_comment_prefixes.clone(),
        text_index_max_bytes: config.text_index_max_bytes,
        summary_max_length: config.summary_max_length,
        summary_ascii_only: config.summary_ascii_only,
        summary_no_commas: config.summary_no_commas,
    }
}

/// Render a native path without replacing non-UTF-8 units.
#[cfg(windows)]
fn effective_config_path_display(path: &Path) -> Option<String> {
    projectatlas_core::lossless_native_path_display(path)
        .ok()
        .map(|value| value.replace('/', "\\"))
}

/// Render a native path without replacing non-UTF-8 units.
#[cfg(not(windows))]
fn effective_config_path_display(path: &Path) -> Option<String> {
    path.to_str().map(ToOwned::to_owned)
}

/// `ProjectAtlas` map record.
#[derive(Clone, Debug, Eq, PartialEq)]
struct MapRecord {
    /// Repository-relative path.
    path: String,
    /// One-line purpose summary.
    summary: String,
    /// Source of the summary.
    source: String,
}

/// Snapshot rendered as a current `ProjectAtlas` map.
#[derive(Debug)]
struct AtlasSnapshot {
    /// Folder records.
    folder_records: Vec<MapRecord>,
    /// File records.
    file_records: Vec<MapRecord>,
    /// Folder tree lines.
    folder_tree: Vec<String>,
    /// Duplicate folder summaries.
    folder_duplicates: Vec<String>,
    /// Duplicate file summaries.
    file_duplicates: Vec<String>,
    /// File record hash.
    file_hash: String,
    /// Folder record hash.
    folder_hash: String,
    /// Generated timestamp.
    generated_at: String,
    /// Overview counters.
    overview: BTreeMap<String, usize>,
}

/// Result of collecting repository paths.
#[derive(Debug)]
struct RepoPaths {
    /// Folder paths.
    folders: Vec<String>,
    /// Source file paths.
    source_files: Vec<String>,
    /// Non-source file paths.
    untracked_files: Vec<String>,
    /// Excluded paths that exist.
    excluded_paths: Vec<String>,
}

/// Parsed non-source entry set and validation state.
#[derive(Debug)]
struct NonsourceEntries {
    /// Valid or placeholder records.
    records: Vec<MapRecord>,
    /// Entries pointing to missing paths.
    missing: Vec<String>,
    /// Entries with invalid summaries.
    invalid: BTreeMap<String, Vec<String>>,
    /// File-level parsing errors.
    errors: Vec<String>,
}

/// Lint options supplied by the CLI.
#[derive(Clone, Copy, Debug)]
pub(crate) struct LintOptions {
    /// Deprecated compatibility flag accepted by the CLI.
    pub(crate) strict_folders: bool,
    /// Whether to print untracked-file report.
    pub(crate) report_untracked: bool,
    /// Whether untracked files fail lint.
    pub(crate) strict_untracked: bool,
}

/// Typed map-owned portion of one lint result.
#[derive(Debug, Eq, PartialEq, Serialize)]
pub(crate) struct MapLintReport {
    /// Whether every map-owned check passed.
    pub(crate) ok: bool,
    /// Compatibility notices that do not fail lint.
    pub(crate) notes: Vec<String>,
    /// Validation state for the non-source purpose registry.
    pub(crate) non_source: NonSourceLintReport,
    /// Untracked-file inventory when requested.
    pub(crate) untracked: Option<UntrackedLintReport>,
}

/// Typed non-source purpose-registry lint facts.
#[derive(Debug, Eq, PartialEq, Serialize)]
pub(crate) struct NonSourceLintReport {
    /// File-level parse or validation errors.
    pub(crate) errors: Vec<String>,
    /// Registry entries whose paths do not exist.
    pub(crate) missing: Vec<String>,
    /// Registry entries with invalid summaries, keyed by path.
    pub(crate) invalid: BTreeMap<String, Vec<String>>,
}

/// Typed untracked-file lint inventory.
#[derive(Debug, Eq, PartialEq, Serialize)]
pub(crate) struct UntrackedLintReport {
    /// Total untracked non-source files found.
    pub(crate) total: usize,
    /// Files admitted by configured purpose or allow-list policy.
    pub(crate) allowed: usize,
    /// Files not admitted by configured purpose or allow-list policy.
    pub(crate) disallowed: Vec<String>,
    /// Disallowed file counts grouped by normalized extension.
    pub(crate) disallowed_extension_counts: BTreeMap<String, usize>,
    /// Allowed file counts grouped by normalized extension.
    pub(crate) allowed_extension_counts: BTreeMap<String, usize>,
    /// Configured asset roots that currently exist.
    pub(crate) asset_roots_present: usize,
    /// Asset files found outside configured asset roots.
    pub(crate) assets_outside_roots: Vec<String>,
    /// Existing paths excluded from source scanning.
    pub(crate) excluded_paths_present: usize,
    /// Whether disallowed untracked files fail lint.
    pub(crate) strict: bool,
}

impl MapLintReport {
    /// Return the CLI-compatible exit code for map-owned findings.
    pub(crate) const fn exit_code(&self) -> i32 {
        if self.ok { 0 } else { 1 }
    }

    /// Render the compatibility text from the same typed facts.
    pub(crate) fn render_text(&self) -> String {
        let mut report = self.notes.clone();
        if let Some(untracked) = &self.untracked {
            untracked.append_text(&mut report);
        }
        self.non_source.append_errors(&mut report);
        if self
            .untracked
            .as_ref()
            .is_some_and(|untracked| untracked.strict && !untracked.disallowed.is_empty())
        {
            report.push("Untracked files detected.".to_string());
        }
        join_report(&report)
    }
}

impl NonSourceLintReport {
    /// Return whether the non-source registry contains blocking findings.
    fn is_empty(&self) -> bool {
        self.errors.is_empty() && self.missing.is_empty() && self.invalid.is_empty()
    }

    /// Append compatibility text for blocking non-source findings.
    fn append_errors(&self, report: &mut Vec<String>) {
        if !self.errors.is_empty() {
            report.push("Non-source file list errors:".to_string());
            report.push(format_list(&self.errors));
        }
        if !self.missing.is_empty() {
            report.push("Missing non-source file entries:".to_string());
            report.push(format_list(&self.missing));
        }
        if !self.invalid.is_empty() {
            report.push("Invalid non-source file summaries:".to_string());
            report.extend(
                self.invalid
                    .iter()
                    .map(|(path, issues)| format!(" - {path}: {}", issues.join(", "))),
            );
        }
    }
}

impl UntrackedLintReport {
    /// Append compatibility text for the typed untracked-file inventory.
    fn append_text(&self, report: &mut Vec<String>) {
        report.push(format!(
            "Untracked files (non-source extensions): {} (allowed {}, disallowed {})",
            self.total,
            self.allowed,
            self.disallowed.len()
        ));
        if self.disallowed.is_empty() {
            report.push("Disallowed untracked files: 0".to_string());
        } else {
            report.push("Disallowed untracked files:".to_string());
            report.push(format_list(&self.disallowed));
            report.push("Disallowed extension counts:".to_string());
            report.push(format_extension_counts(&self.disallowed_extension_counts));
        }
        report.push("Allowed untracked extension counts:".to_string());
        report.push(if self.allowed_extension_counts.is_empty() {
            " (none)".to_string()
        } else {
            format_extension_counts(&self.allowed_extension_counts)
        });
        report.push(format!("Asset roots present: {}", self.asset_roots_present));
        if !self.assets_outside_roots.is_empty() {
            report.push("Asset files outside allowed roots:".to_string());
            report.push(format_list(&self.assets_outside_roots));
        }
        report.push(format!(
            "Excluded paths present: {}",
            self.excluded_paths_present
        ));
    }
}

/// Purpose record imported from legacy `ProjectAtlas` metadata.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) struct ImportedPurposeRecord {
    /// Repository-relative path.
    pub(crate) path: String,
    /// Imported purpose summary.
    pub(crate) summary: String,
}

/// Manual `ProjectAtlas` ignore entry kind.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum IgnoreEntryKind {
    /// Exclude every directory with this name anywhere under the project root.
    DirName,
    /// Exclude one repository-relative path subtree.
    PathPrefix,
}

impl IgnoreEntryKind {
    /// Stable config key for this ignore kind.
    fn config_key(self) -> &'static str {
        match self {
            Self::DirName => "exclude_dir_names",
            Self::PathPrefix => "exclude_path_prefixes",
        }
    }

    /// Agent-facing ignore kind name.
    fn as_str(self) -> &'static str {
        match self {
            Self::DirName => "dir-name",
            Self::PathPrefix => "path-prefix",
        }
    }
}

/// Current `ProjectAtlas` ignore configuration report.
#[derive(Debug, Serialize)]
pub(crate) struct IgnoreListReport {
    /// Lossless UTF-8 config path used for the manual `ProjectAtlas` ignore layer.
    pub(crate) config_path: Option<String>,
    /// Lossless UTF-8 `.gitignore` path that the scanner will honor when it exists.
    pub(crate) gitignore_path: Option<String>,
    /// Whether a `.gitignore` file currently exists at the project root.
    pub(crate) gitignore_present: bool,
    /// Scanner behavior for `.gitignore`.
    pub(crate) gitignore_mode: String,
    /// Order of the manual `ProjectAtlas` ignore layer.
    pub(crate) manual_layer_order: String,
    /// Effective directory-name excludes after defaults and config are applied.
    pub(crate) exclude_dir_names: Vec<String>,
    /// Effective repository-relative path-prefix excludes.
    pub(crate) exclude_path_prefixes: Vec<String>,
}

/// Result of creating a project-root `.gitignore` when it is missing.
#[derive(Debug, Serialize)]
pub(crate) struct GitignoreInitReport {
    /// Lossless UTF-8 `.gitignore` path that was checked, when one is available.
    pub(crate) gitignore_path: Option<String>,
    /// Whether the file already existed before the command.
    pub(crate) existed: bool,
    /// Whether the command created the file.
    pub(crate) created: bool,
    /// Whether `.gitignore` rules are inherited dynamically by the scanner.
    pub(crate) gitignore_inherited: bool,
}

/// Result of adding or removing a manual `ProjectAtlas` ignore entry.
#[derive(Debug, Serialize)]
pub(crate) struct IgnoreMutationReport {
    /// Lossless UTF-8 config path that was edited, when one is available.
    pub(crate) config_path: Option<String>,
    /// Lossless UTF-8 `.gitignore` path that the scanner will honor when it exists.
    pub(crate) gitignore_path: Option<String>,
    /// Whether a `.gitignore` file currently exists at the project root.
    pub(crate) gitignore_present: bool,
    /// Mutation action.
    pub(crate) action: String,
    /// Ignore kind that was targeted, or `any` for a broad remove.
    pub(crate) kind: String,
    /// Normalized ignore value.
    pub(crate) value: String,
    /// Whether the config file changed.
    pub(crate) changed: bool,
    /// Scanner behavior for `.gitignore`.
    pub(crate) gitignore_mode: String,
    /// Order of the manual `ProjectAtlas` ignore layer.
    pub(crate) manual_layer_order: String,
    /// Effective directory-name excludes after the mutation.
    pub(crate) exclude_dir_names: Vec<String>,
    /// Effective repository-relative path-prefix excludes after the mutation.
    pub(crate) exclude_path_prefixes: Vec<String>,
}

/// Load atlas map configuration from disk.
pub(crate) fn load_atlas_config(config_path: Option<&Path>) -> AtlasMapResult<AtlasMapConfig> {
    let cwd = std::env::current_dir().map_err(|source| AtlasMapError::Io {
        path: PathBuf::from("."),
        source,
    })?;
    let config_file = match config_path {
        Some(path) => Some(path.to_path_buf()),
        None => find_config_path(&cwd),
    };
    if let Some(path) = &config_file {
        let text = fs::read_to_string(path).map_err(|source| AtlasMapError::Io {
            path: path.clone(),
            source,
        })?;
        return load_atlas_config_from_text(path, &text);
    }
    normalize_config(RawConfig::default(), None, &cwd, &cwd)
}

/// Parse an already-bounded configuration input using normal path semantics.
pub(crate) fn load_atlas_config_from_text(
    path: &Path,
    text: &str,
) -> AtlasMapResult<AtlasMapConfig> {
    let cwd = std::env::current_dir().map_err(|source| AtlasMapError::Io {
        path: PathBuf::from("."),
        source,
    })?;
    let parsed = toml::from_str::<RawConfig>(text).map_err(|source| AtlasMapError::Toml {
        path: path.to_path_buf(),
        source: Box::new(source),
    })?;
    let base_dir = path.parent().map_or_else(|| cwd.clone(), Path::to_path_buf);
    normalize_config(parsed, Some(path), &base_dir, &cwd)
}

/// Load atlas map configuration for an explicit project root.
pub(crate) fn load_atlas_config_for_root(root: &Path) -> AtlasMapResult<AtlasMapConfig> {
    if let Some(config_path) = find_config_path(root) {
        return load_atlas_config(Some(&config_path));
    }
    normalize_config(RawConfig::default(), None, root, root)
}

/// Write default `ProjectAtlas` config files, honoring an explicitly selected config path.
pub(crate) fn init_project_with_config(
    root: &Path,
    selected_config: Option<&Path>,
) -> AtlasMapResult<String> {
    let canonical_root = fs::canonicalize(root).map_err(|source| AtlasMapError::Io {
        path: root.to_path_buf(),
        source,
    })?;
    let root = canonical_root.as_path();
    let project_dir = root.join(".projectatlas");
    let nested_config_path = project_dir.join("config.toml");
    let flat_config_path = root.join("projectatlas.toml");
    let config_path = selected_config.map_or_else(
        || {
            if nested_config_path.exists() {
                nested_config_path.clone()
            } else if flat_config_path.exists() {
                flat_config_path
            } else {
                nested_config_path.clone()
            }
        },
        Path::to_path_buf,
    );
    let mut state =
        crate::project_state::ProjectStateGuard::preflight(root, None, Some(&config_path))
            .map_err(|source| AtlasMapError::Io {
                path: project_dir.clone(),
                source,
            })?;
    let default_config = if config_path.exists() {
        None
    } else {
        Some(default_config_text_for(root, &config_path)?)
    };
    let mut config_document = if default_config.is_some() {
        crate::project_state::ProjectStateGuard::preflight_document(root, &config_path).map_err(
            |source| AtlasMapError::Io {
                path: config_path.clone(),
                source,
            },
        )?
    } else {
        None
    };
    state
        .ensure_directory()
        .map_err(|source| AtlasMapError::Io {
            path: project_dir.clone(),
            source,
        })?;
    if let Some(default_config) = default_config {
        if let Some(parent) = config_path
            .parent()
            .filter(|path| !path.as_os_str().is_empty())
        {
            fs::create_dir_all(parent).map_err(|source| AtlasMapError::Io {
                path: parent.to_path_buf(),
                source,
            })?;
        }
        state.verify().map_err(|source| AtlasMapError::Io {
            path: project_dir.clone(),
            source,
        })?;
        // The document role owns both fixed-name admission and creation mode.
        let written = if let Some(document) = &mut config_document {
            document
                .create_document(default_config.as_bytes())
                .map(|_| ())
        } else {
            // This destination was explicitly selected by the operator.
            fs::write(&config_path, default_config)
        };
        written.map_err(|source| AtlasMapError::Io {
            path: config_path.clone(),
            source,
        })?;
    }
    let nonsource_path = project_dir.join("projectatlas-nonsource-files.toon");
    if !nonsource_path.exists() {
        state.verify().map_err(|source| AtlasMapError::Io {
            path: project_dir.clone(),
            source,
        })?;
        state
            .write_new(&nonsource_path, b"nonsource_files[]:\n  # path,summary\n")
            .map_err(|source| AtlasMapError::Io {
                path: nonsource_path.clone(),
                source,
            })?;
    }
    Ok(String::new())
}

/// List effective `ProjectAtlas` ignore policy.
pub(crate) fn list_ignore_entries(
    config_path: Option<&Path>,
    project_root: &Path,
) -> AtlasMapResult<IgnoreListReport> {
    let path = resolve_config_edit_path(config_path, project_root)?;
    let config = if path.exists() {
        load_atlas_config(Some(&path))?
    } else {
        load_atlas_config_for_root(project_root)?
    };
    Ok(ignore_list_report(&path, &config))
}

/// Create a project-root `.gitignore` when it is missing.
pub(crate) fn init_gitignore(
    config_path: Option<&Path>,
    project_root: &Path,
) -> AtlasMapResult<GitignoreInitReport> {
    let path = resolve_config_edit_path(config_path, project_root)?;
    let config = if path.exists() {
        load_atlas_config(Some(&path))?
    } else {
        load_atlas_config_for_root(project_root)?
    };
    let gitignore_path = config.root.join(".gitignore");
    let existed = match fs::symlink_metadata(&gitignore_path) {
        Ok(_) => true,
        Err(source) if source.kind() == io::ErrorKind::NotFound => false,
        Err(source) => {
            return Err(AtlasMapError::Io {
                path: gitignore_path,
                source,
            });
        }
    };
    let created = if existed {
        false
    } else {
        let mut guard = crate::project_state::ProjectStateGuard::preflight_document(
            &config.root,
            &gitignore_path,
        )
        .map_err(|source| AtlasMapError::Io {
            path: gitignore_path.clone(),
            source,
        })?
        .ok_or_else(|| AtlasMapError::Io {
            path: gitignore_path.clone(),
            source: io::Error::new(
                io::ErrorKind::InvalidInput,
                "gitignore has no admitted project owner",
            ),
        })?;
        guard
            .create_document(default_gitignore_text().as_bytes())
            .map_err(|source| AtlasMapError::Io {
                path: gitignore_path.clone(),
                source,
            })?
    };
    Ok(GitignoreInitReport {
        gitignore_path: effective_config_path_display(&gitignore_path),
        existed: existed || !created,
        created,
        gitignore_inherited: true,
    })
}

/// Add one manual `ProjectAtlas` ignore entry to config.
pub(crate) fn add_ignore_entry(
    config_path: Option<&Path>,
    project_root: &Path,
    kind: IgnoreEntryKind,
    value: &str,
) -> AtlasMapResult<IgnoreMutationReport> {
    let normalized = normalize_ignore_value(kind, value)?;
    let path = resolve_config_edit_path(config_path, project_root)?;
    let mut document = load_config_document_for_edit(&path)?;
    let mut values = string_array_values(&path, &document, kind)?;
    let changed = values.insert(normalized.clone());
    if changed {
        write_string_array(&mut document, kind, &values)?;
        write_config_document(&path, &document, project_root)?;
    }
    let config = load_atlas_config(Some(&path))?;
    Ok(ignore_mutation_report(
        &path,
        "add",
        kind.as_str(),
        &normalized,
        changed,
        &config,
    ))
}

/// Remove one manual `ProjectAtlas` ignore entry from config.
pub(crate) fn remove_ignore_entry(
    config_path: Option<&Path>,
    project_root: &Path,
    kind: Option<IgnoreEntryKind>,
    value: &str,
) -> AtlasMapResult<IgnoreMutationReport> {
    let path = resolve_config_edit_path(config_path, project_root)?;
    let mut document = load_config_document_for_edit(&path)?;
    let mut changed = false;
    let normalized = if let Some(kind) = kind {
        let normalized = normalize_ignore_value(kind, value)?;
        let mut values = string_array_values(&path, &document, kind)?;
        if values.remove(&normalized) {
            changed = true;
            write_string_array(&mut document, kind, &values)?;
        }
        normalized
    } else {
        let normalized_prefix = normalize_ignore_value(IgnoreEntryKind::PathPrefix, value)?;
        let normalized_dir = normalize_ignore_value(IgnoreEntryKind::DirName, value).ok();
        let mut prefix_values = string_array_values(&path, &document, IgnoreEntryKind::PathPrefix)?;
        if prefix_values.remove(&normalized_prefix) {
            changed = true;
            write_string_array(&mut document, IgnoreEntryKind::PathPrefix, &prefix_values)?;
        }
        if let Some(normalized_dir) = normalized_dir.as_deref() {
            let mut dir_values = string_array_values(&path, &document, IgnoreEntryKind::DirName)?;
            if dir_values.remove(normalized_dir) {
                changed = true;
                write_string_array(&mut document, IgnoreEntryKind::DirName, &dir_values)?;
            }
        }
        normalized_prefix
    };
    if changed {
        write_config_document(&path, &document, project_root)?;
    }
    let config = load_atlas_config(Some(&path))?;
    Ok(ignore_mutation_report(
        &path,
        "remove",
        kind.map_or("any", IgnoreEntryKind::as_str),
        &normalized,
        changed,
        &config,
    ))
}

/// Complete current map response and optional sidecar state.
pub(crate) struct MapResponse {
    /// Complete selected-format map content.
    pub(crate) content: String,
}

/// Render a current map without writing a legacy TOON snapshot.
pub(crate) fn render_map(
    config: &AtlasMapConfig,
    json_response: bool,
    write_json: bool,
) -> AtlasMapResult<MapResponse> {
    render_map_with_limit(config, json_response, write_json, MAX_MAP_RESPONSE_BYTES)
}

/// Render under an explicit budget so refusal and no-write order are testable.
fn render_map_with_limit(
    config: &AtlasMapConfig,
    json_response: bool,
    write_json: bool,
    response_limit: usize,
) -> AtlasMapResult<MapResponse> {
    let snapshot = build_snapshot(config)?;
    let content = if json_response {
        render_json_map(&snapshot)?
    } else {
        render_toon(&snapshot, config)
    };
    enforce_map_response_limit(&content, response_limit)?;
    if write_json {
        if json_response {
            write_json_map(&content, config)?;
        } else {
            write_json_map(&render_json_map(&snapshot)?, config)?;
        }
    }
    Ok(MapResponse { content })
}

/// Refuse a partial response before any optional file mutation.
pub(crate) fn enforce_map_response_limit(content: &str, limit: usize) -> AtlasMapResult<()> {
    if content.len() > limit {
        return Err(AtlasMapError::ResponseLimitExceeded {
            observed: content.len(),
            limit,
        });
    }
    Ok(())
}

/// Extract approved legacy purpose records from an existing controlled scan.
///
/// The caller owns text-input cancellation and byte accounting through
/// `read_text`; this function never starts a second repository scan.
pub(crate) fn imported_purpose_records_from_nodes<E, F>(
    config: &AtlasMapConfig,
    nodes: &[Node],
    read_text: &mut F,
) -> Result<Vec<ImportedPurposeRecord>, E>
where
    E: From<AtlasMapError>,
    F: FnMut(&Path) -> Result<String, E>,
{
    let paths = repo_paths_from_nodes(config, nodes);
    imported_purpose_records_from_paths(config, &paths, read_text)
}

/// Extract approved purpose rows from one already-selected path inventory.
fn imported_purpose_records_from_paths<E, F>(
    config: &AtlasMapConfig,
    paths: &RepoPaths,
    read_text: &mut F,
) -> Result<Vec<ImportedPurposeRecord>, E>
where
    E: From<AtlasMapError>,
    F: FnMut(&Path) -> Result<String, E>,
{
    let mut imported = BTreeMap::new();
    append_existing_map_purpose_records_with_reader(config, &mut imported, read_text)?;
    let db_purposes = BTreeMap::new();
    let (file_records, _, _) =
        build_file_records_with_reader(&paths.source_files, config, &db_purposes, read_text)?;
    let nonsource = read_nonsource_file_entries_with_reader(config, read_text)?;
    let merged_file_records = merge_records(&file_records, &nonsource.records);
    let (folder_records, _, _) =
        build_folder_records_with_reader(&paths.folders, config, &db_purposes, read_text)?;
    append_imported_records(&mut imported, &folder_records);
    append_imported_records(&mut imported, &merged_file_records);
    Ok(imported
        .into_iter()
        .map(|(path, summary)| ImportedPurposeRecord { path, summary })
        .collect())
}

/// Append valid imported records from map records.
fn append_imported_records(imported: &mut BTreeMap<String, String>, records: &[MapRecord]) {
    for record in records {
        if record.summary == "MISSING" || record.summary == "INVALID" {
            continue;
        }
        imported.insert(record.path.clone(), record.summary.clone());
    }
}

/// Append approved records from an existing committed atlas map.
#[cfg(test)]
fn append_existing_map_purpose_records(
    config: &AtlasMapConfig,
    imported: &mut BTreeMap<String, String>,
) -> AtlasMapResult<()> {
    let mut read_text = read_text_file;
    append_existing_map_purpose_records_with_reader(config, imported, &mut read_text)
}

/// Append approved map rows using the caller-owned text reader.
fn append_existing_map_purpose_records_with_reader<E, F>(
    config: &AtlasMapConfig,
    imported: &mut BTreeMap<String, String>,
    read_text: &mut F,
) -> Result<(), E>
where
    E: From<AtlasMapError>,
    F: FnMut(&Path) -> Result<String, E>,
{
    if !config.map_path.exists() {
        return Ok(());
    }
    let content = read_text(&config.map_path)?;
    let mut in_record_rows = false;
    for line in content.lines().map(str::trim) {
        if line.starts_with("folders[") || line.starts_with("files[") {
            in_record_rows = true;
            continue;
        }
        if line.ends_with(':') {
            in_record_rows = false;
            continue;
        }
        if !in_record_rows || line.is_empty() || line.starts_with('#') {
            continue;
        }
        let cells = split_record_cells(line);
        if cells.len() < 2 {
            continue;
        }
        let summary = cells[1].trim();
        if summary.is_empty() || summary == "MISSING" || summary == "INVALID" {
            continue;
        }
        let path = normalize_repo_string(&cells[0]).map_err(E::from)?;
        imported.insert(path, summary.to_string());
    }
    Ok(())
}

/// Read one complete UTF-8 atlas-map input through the compatibility path.
fn read_text_file(path: &Path) -> AtlasMapResult<String> {
    fs::read_to_string(path).map_err(|source| AtlasMapError::Io {
        path: path.to_path_buf(),
        source,
    })
}

/// Load approved purpose records from the durable `SQLite` index.
fn load_db_purpose_records(config: &AtlasMapConfig) -> AtlasMapResult<BTreeMap<String, String>> {
    if !config.db_path.exists() {
        return Ok(BTreeMap::new());
    }
    let admission = crate::project_state::ProjectStateGuard::preflight_database_path(
        &config.db_path,
        &config.root,
    )
    .map_err(|source| AtlasMapError::Io {
        path: config.db_path.clone(),
        source,
    })?;
    let database = crate::runtime::admitted_database_path(&config.db_path, admission.as_ref());
    let store =
        AtlasStore::open_read_only_for_project(database, &config.root).map_err(|source| {
            AtlasMapError::Database {
                path: config.db_path.clone(),
                message: source.to_string(),
            }
        })?;
    let nodes = store
        .load_nodes()
        .map_err(|source| AtlasMapError::Database {
            path: config.db_path.clone(),
            message: source.to_string(),
        })?;
    Ok(nodes
        .into_iter()
        .filter(|node| node.purpose.status == projectatlas_core::PurposeStatus::Approved)
        .filter_map(|node| {
            node.purpose
                .purpose
                .map(|purpose| (node.node.path, purpose))
        })
        .collect())
}

/// Lint map-owned repository inputs and return typed facts.
pub(crate) fn lint_map(
    config: &AtlasMapConfig,
    options: LintOptions,
) -> AtlasMapResult<MapLintReport> {
    let paths = collect_repo_paths(config)?;
    let nonsource = read_nonsource_file_entries(config)?;
    let notes = if options.strict_folders {
        vec![
            "Note: --strict-folders is deprecated; database folder purpose linting uses --purpose-level."
                .to_string(),
        ]
    } else {
        Vec::new()
    };
    let non_source = NonSourceLintReport {
        errors: nonsource.errors,
        missing: nonsource.missing,
        invalid: nonsource.invalid,
    };
    let untracked = options
        .report_untracked
        .then(|| build_untracked_report(config, &paths, options))
        .transpose()?;
    let ok = non_source.is_empty()
        && !untracked
            .as_ref()
            .is_some_and(|report| report.strict && !report.disallowed.is_empty());
    Ok(MapLintReport {
        ok,
        notes,
        non_source,
        untracked,
    })
}

/// Find a default config path under the current root.
fn find_config_path(root: &Path) -> Option<PathBuf> {
    let project_config = root.join(".projectatlas").join("config.toml");
    if project_config.exists() {
        return Some(project_config);
    }
    let flat_config = root.join("projectatlas.toml");
    if flat_config.exists() {
        return Some(flat_config);
    }
    None
}

/// Resolve the config file path that ignore commands should edit.
fn resolve_config_edit_path(
    config_path: Option<&Path>,
    project_root: &Path,
) -> AtlasMapResult<PathBuf> {
    let cwd = std::env::current_dir().map_err(|source| AtlasMapError::Io {
        path: PathBuf::from("."),
        source,
    })?;
    if let Some(path) = config_path {
        return Ok(if path.is_absolute() {
            path.to_path_buf()
        } else {
            cwd.join(path)
        });
    }
    Ok(find_config_path(project_root)
        .unwrap_or_else(|| project_root.join(".projectatlas").join("config.toml")))
}

/// Load an editable TOML document, creating default config text when absent.
fn load_config_document_for_edit(path: &Path) -> AtlasMapResult<DocumentMut> {
    let text = if path.exists() {
        fs::read_to_string(path).map_err(|source| AtlasMapError::Io {
            path: path.to_path_buf(),
            source,
        })?
    } else {
        default_config_text()
    };
    text.parse::<DocumentMut>()
        .map_err(|source| AtlasMapError::TomlEdit {
            path: path.to_path_buf(),
            message: source.to_string(),
        })
}

/// Persist an editable TOML document to disk.
fn write_config_document(
    path: &Path,
    document: &DocumentMut,
    project_root: &Path,
) -> AtlasMapResult<()> {
    if let Some(mut guard) =
        crate::project_state::ProjectStateGuard::preflight_document(project_root, path).map_err(
            |source| AtlasMapError::Io {
                path: path.to_path_buf(),
                source,
            },
        )?
    {
        return guard
            .write_document(document.to_string().as_bytes())
            .map_err(|source| AtlasMapError::Io {
                path: path.to_path_buf(),
                source,
            });
    }
    if let Some(parent) = path.parent()
        && !parent.as_os_str().is_empty()
    {
        fs::create_dir_all(parent).map_err(|source| AtlasMapError::Io {
            path: parent.to_path_buf(),
            source,
        })?;
    }
    fs::write(path, document.to_string()).map_err(|source| AtlasMapError::Io {
        path: path.to_path_buf(),
        source,
    })
}

/// Read a string array from the `[scan]` table, returning an empty set when absent.
fn string_array_values(
    path: &Path,
    document: &DocumentMut,
    kind: IgnoreEntryKind,
) -> AtlasMapResult<BTreeSet<String>> {
    let key = kind.config_key();
    let Some(scan) = document.get("scan") else {
        return Ok(BTreeSet::new());
    };
    let Some(table) = scan.as_table() else {
        return Err(AtlasMapError::TomlEdit {
            path: path.to_path_buf(),
            message: "[scan] must be a TOML table".to_string(),
        });
    };
    let Some(item) = table.get(key) else {
        return Ok(BTreeSet::new());
    };
    let Some(array) = item.as_array() else {
        return Err(AtlasMapError::TomlEdit {
            path: path.to_path_buf(),
            message: format!("[scan].{key} must be an array of strings"),
        });
    };
    let mut values = BTreeSet::new();
    for value in array {
        let Some(text) = value.as_str() else {
            return Err(AtlasMapError::TomlEdit {
                path: path.to_path_buf(),
                message: format!("[scan].{key} must contain only strings"),
            });
        };
        let trimmed = text.trim();
        if !trimmed.is_empty() {
            values.insert(normalize_ignore_value(kind, trimmed)?);
        }
    }
    Ok(values)
}

/// Replace one `[scan]` string array while preserving unrelated config content.
fn write_string_array(
    document: &mut DocumentMut,
    kind: IgnoreEntryKind,
    values: &BTreeSet<String>,
) -> AtlasMapResult<()> {
    let key = kind.config_key();
    if document.get("scan").is_none() {
        document["scan"] = Item::Table(Table::new());
    }
    let Some(scan) = document["scan"].as_table_mut() else {
        return Err(AtlasMapError::TomlEdit {
            path: PathBuf::from("<config>"),
            message: "[scan] must be a TOML table".to_string(),
        });
    };
    if scan.get(key).is_none() {
        scan[key] = value(Array::new());
    }
    let Some(array) = scan[key].as_array_mut() else {
        return Err(AtlasMapError::TomlEdit {
            path: PathBuf::from("<config>"),
            message: format!("[scan].{key} must be an array of strings"),
        });
    };
    let mut retained = BTreeSet::new();
    let mut index = 0;
    while index < array.len() {
        let Some(text) = array.get(index).and_then(toml_edit::Value::as_str) else {
            return Err(AtlasMapError::TomlEdit {
                path: PathBuf::from("<config>"),
                message: format!("[scan].{key} must contain only strings"),
            });
        };
        let trimmed = text.trim();
        if trimmed.is_empty() {
            index += 1;
            continue;
        }
        let normalized = normalize_ignore_value(kind, trimmed)?;
        if values.contains(&normalized) {
            retained.insert(normalized);
            index += 1;
        } else {
            array.remove(index);
        }
    }
    for missing in values.difference(&retained) {
        array.push(missing.as_str());
    }
    Ok(())
}

/// Normalize raw config into runtime config.
fn normalize_config(
    raw: RawConfig,
    config_path: Option<&Path>,
    base_dir: &Path,
    cwd: &Path,
) -> AtlasMapResult<AtlasMapConfig> {
    let project = raw.project.unwrap_or_default();
    let private_config = if project
        .root
        .as_deref()
        .is_none_or(|root| root.trim() == ".")
    {
        config_path_is_projectatlas(config_path)?
    } else {
        false
    };
    let root = match project.root {
        Some(root) if root.trim() == "." && private_config => {
            project_root_for_projectatlas_config(config_path, cwd)
        }
        Some(root) => absolutize(base_dir, &root),
        None if private_config => project_root_for_projectatlas_config(config_path, cwd),
        None => cwd.to_path_buf(),
    };
    let root = root.canonicalize().map_err(|source| AtlasMapError::Io {
        path: root.clone(),
        source,
    })?;
    let scan = raw.scan.unwrap_or_default();
    let purpose = raw.purpose.unwrap_or_default();
    let summary = raw.summary_rules.unwrap_or_default();
    let untracked = raw.untracked.unwrap_or_default();
    Ok(AtlasMapConfig {
        map_path: absolutize(
            &root,
            project.map_path.as_deref().unwrap_or(DEFAULT_MAP_PATH),
        ),
        nonsource_files_path: absolutize(
            &root,
            project
                .nonsource_files_path
                .as_deref()
                .or(project.manual_files_path.as_deref())
                .unwrap_or(DEFAULT_NONSOURCE_PATH),
        ),
        purpose_filename: project
            .purpose_filename
            .unwrap_or_else(|| DEFAULT_LEGACY_PURPOSE_FILENAME.to_string()),
        source_extensions: normalize_set(
            scan.source_extensions
                .filter(|extensions| {
                    !extensions
                        .iter()
                        .map(String::as_str)
                        .eq(DEFAULT_SOURCE_EXTENSIONS.iter().copied())
                })
                .unwrap_or_else(default_source_extensions),
        ),
        exclude_dir_names: exclude_dir_name_set(scan.exclude_dir_names),
        exclude_dir_suffixes: string_set(scan.exclude_dir_suffixes, &[".egg-info"]),
        exclude_path_prefixes: normalize_prefix_set(scan.exclude_path_prefixes)?,
        non_source_path_prefixes: normalize_prefix_set(scan.non_source_path_prefixes)?,
        language_overrides: normalize_language_overrides(scan.language_overrides)?,
        allowed_untracked_filenames: string_set(untracked.allowed_filenames, &[]),
        untracked_allowlist_dir_prefixes: normalize_prefix_set(untracked.allowlist_dir_prefixes)?,
        untracked_allowlist_files: normalize_prefix_set(untracked.allowlist_files)?,
        asset_allowed_prefixes: normalize_prefix_set(untracked.asset_allowed_prefixes)?,
        asset_extensions: normalize_set(untracked.asset_extensions.unwrap_or_else(|| {
            DEFAULT_ASSET_EXTENSIONS
                .iter()
                .map(ToString::to_string)
                .collect()
        })),
        db_path: root.join(".projectatlas").join("projectatlas.db"),
        max_scan_lines: scan.max_scan_lines.unwrap_or(DEFAULT_MAX_SCAN_LINES),
        text_index_max_bytes: scan
            .text_index_max_bytes
            .filter(|value| *value > 0)
            .unwrap_or(DEFAULT_TEXT_INDEX_MAX_BYTES),
        summary_max_length: summary.max_length.unwrap_or(DEFAULT_SUMMARY_MAX_LENGTH),
        summary_ascii_only: summary.ascii_only.unwrap_or(true),
        summary_no_commas: summary.no_commas.unwrap_or(true),
        purpose_styles: normalize_style_map(purpose.styles_by_extension),
        purpose_default_style: purpose
            .default_style
            .unwrap_or_else(|| "javadoc".to_string()),
        line_comment_prefixes: purpose.line_comment_prefixes.unwrap_or_else(|| {
            DEFAULT_LINE_COMMENT_PREFIXES
                .iter()
                .map(ToString::to_string)
                .collect()
        }),
        root,
    })
}

/// Return whether the config path is inside `.projectatlas`.
fn config_path_is_projectatlas(config_path: Option<&Path>) -> AtlasMapResult<bool> {
    let Some(parent) = config_path.and_then(Path::parent) else {
        return Ok(false);
    };
    crate::project_state::state_directory_spelling(parent).map_err(|source| AtlasMapError::Io {
        path: parent.to_path_buf(),
        source,
    })
}

/// Return the project root implied by `.projectatlas/config.toml`.
fn project_root_for_projectatlas_config(config_path: Option<&Path>, cwd: &Path) -> PathBuf {
    let Some(root) = config_path
        .and_then(Path::parent)
        .and_then(Path::parent)
        .filter(|path| !path.as_os_str().is_empty() && *path != Path::new("."))
    else {
        return cwd.to_path_buf();
    };
    root.to_path_buf()
}

/// Convert a possibly relative path to an absolute path.
fn absolutize(base: &Path, value: &str) -> PathBuf {
    let path = PathBuf::from(value);
    if path.is_absolute() {
        path
    } else {
        base.join(path)
    }
}

/// Normalize extension strings into a lower-case set.
fn normalize_set(values: Vec<String>) -> BTreeSet<String> {
    values
        .into_iter()
        .map(|value| value.trim().to_ascii_lowercase())
        .filter(|value| !value.is_empty())
        .collect()
}

/// Validate explicit exact-filename and extension language selections.
fn normalize_language_overrides(
    values: Option<BTreeMap<String, String>>,
) -> AtlasMapResult<BTreeMap<String, String>> {
    let mut normalized = BTreeMap::new();
    for (raw_selector, raw_language) in values.unwrap_or_default() {
        let selector = raw_selector.trim();
        let valid_selector = !selector.is_empty() && !selector.contains(['/', '\\']);
        if !valid_selector {
            return Err(AtlasMapError::InvalidLanguageOverride {
                selector: raw_selector,
                language: raw_language,
                message: "selector must be one exact filename or a dot-prefixed extension"
                    .to_string(),
            });
        }
        let Some(language) = canonical_language_id(&raw_language) else {
            return Err(AtlasMapError::InvalidLanguageOverride {
                selector: raw_selector,
                language: raw_language,
                message: "target is not an accepted canonical language ID or alias".to_string(),
            });
        };
        let selector = if selector.starts_with('.') {
            selector.to_ascii_lowercase()
        } else {
            selector.to_string()
        };
        if let Some(previous) = normalized.insert(selector.clone(), language.to_string()) {
            return Err(AtlasMapError::InvalidLanguageOverride {
                selector,
                language: language.to_string(),
                message: format!("selector collides after normalization with target {previous:?}"),
            });
        }
    }
    Ok(normalized)
}

/// Normalize one manual ignore entry.
fn normalize_ignore_value(kind: IgnoreEntryKind, value: &str) -> AtlasMapResult<String> {
    match kind {
        IgnoreEntryKind::DirName => normalize_ignore_dir_name(value),
        IgnoreEntryKind::PathPrefix => {
            let normalized = normalize_repo_string(value)?;
            if normalized == "." {
                return Err(AtlasMapError::InvalidRepositoryPath {
                    path: value.to_string(),
                    message: "project root cannot be ignored by ProjectAtlas".to_string(),
                });
            }
            Ok(normalized)
        }
    }
}

/// Normalize one directory-name ignore entry.
fn normalize_ignore_dir_name(value: &str) -> AtlasMapResult<String> {
    let trimmed = value.trim().trim_matches('/').trim_matches('\\');
    if trimmed.is_empty() || trimmed == "." || trimmed == ".." {
        return Err(AtlasMapError::InvalidRepositoryPath {
            path: value.to_string(),
            message: "directory name ignore must name one directory".to_string(),
        });
    }
    if trimmed.contains('/') || trimmed.contains('\\') {
        return Err(AtlasMapError::InvalidRepositoryPath {
            path: value.to_string(),
            message:
                "directory-name ignores cannot contain path separators; use path-prefix instead"
                    .to_string(),
        });
    }
    Ok(trimmed.to_string())
}

/// Convert optional strings into a set with defaults.
fn string_set(values: Option<Vec<String>>, defaults: &[&str]) -> BTreeSet<String> {
    values
        .unwrap_or_else(|| defaults.iter().map(ToString::to_string).collect())
        .into_iter()
        .filter(|value| !value.trim().is_empty())
        .collect()
}

/// Normalize excluded directory names and preserve required internal excludes.
fn exclude_dir_name_set(values: Option<Vec<String>>) -> BTreeSet<String> {
    let mut names = string_set(values, DEFAULT_EXCLUDE_DIR_NAMES);
    names.extend(REQUIRED_EXCLUDE_DIR_NAMES.iter().map(ToString::to_string));
    names
}

/// Build a report for current ignore settings.
fn ignore_list_report(path: &Path, config: &AtlasMapConfig) -> IgnoreListReport {
    let gitignore_path = config.root.join(".gitignore");
    IgnoreListReport {
        config_path: effective_config_path_display(path),
        gitignore_path: effective_config_path_display(&gitignore_path),
        gitignore_present: gitignore_path.exists(),
        gitignore_mode: "inherited-when-present".to_string(),
        manual_layer_order: "after-gitignore".to_string(),
        exclude_dir_names: config.exclude_dir_names.iter().cloned().collect(),
        exclude_path_prefixes: config.exclude_path_prefixes.iter().cloned().collect(),
    }
}

/// Build a report for an ignore mutation.
fn ignore_mutation_report(
    path: &Path,
    action: &str,
    kind: &str,
    value: &str,
    changed: bool,
    config: &AtlasMapConfig,
) -> IgnoreMutationReport {
    let gitignore_path = config.root.join(".gitignore");
    IgnoreMutationReport {
        config_path: effective_config_path_display(path),
        gitignore_path: effective_config_path_display(&gitignore_path),
        gitignore_present: gitignore_path.exists(),
        action: action.to_string(),
        kind: kind.to_string(),
        value: value.to_string(),
        changed,
        gitignore_mode: "inherited-when-present".to_string(),
        manual_layer_order: "after-gitignore".to_string(),
        exclude_dir_names: config.exclude_dir_names.iter().cloned().collect(),
        exclude_path_prefixes: config.exclude_path_prefixes.iter().cloned().collect(),
    }
}

/// Normalize path-prefix strings into slash-separated values.
fn normalize_prefix_set(values: Option<Vec<String>>) -> AtlasMapResult<BTreeSet<String>> {
    let mut prefixes = BTreeSet::new();
    for value in values.unwrap_or_default() {
        let normalized = normalize_repo_string(&value)?;
        if !normalized.is_empty() {
            prefixes.insert(normalized);
        }
    }
    Ok(prefixes)
}

/// Normalize per-extension purpose styles.
fn normalize_style_map(values: Option<BTreeMap<String, String>>) -> BTreeMap<String, String> {
    let mut map = BTreeMap::new();
    map.insert(".py".to_string(), "python-docstring".to_string());
    map.insert(".vue".to_string(), "vue-block".to_string());
    map.insert(".rs".to_string(), "line-comment".to_string());
    map.insert(".go".to_string(), "line-comment".to_string());
    map.insert(".sh".to_string(), "line-comment".to_string());
    map.insert(".bash".to_string(), "line-comment".to_string());
    map.insert(".zsh".to_string(), "line-comment".to_string());
    map.insert(".ps1".to_string(), "line-comment".to_string());
    map.insert(".psm1".to_string(), "line-comment".to_string());
    map.insert(".psd1".to_string(), "line-comment".to_string());
    map.insert(".sql".to_string(), "line-comment".to_string());
    if let Some(values) = values {
        for (extension, style) in values {
            map.insert(extension.to_ascii_lowercase(), style);
        }
    }
    map
}

/// Collect repository folders, source files, and non-source files.
fn collect_repo_paths(config: &AtlasMapConfig) -> AtlasMapResult<RepoPaths> {
    let options = config.scan_options();
    let nodes = scan_repo(&config.root, &options)?;
    Ok(repo_paths_from_nodes(config, &nodes))
}

/// Classify one existing scan into legacy map input paths.
fn repo_paths_from_nodes(config: &AtlasMapConfig, nodes: &[Node]) -> RepoPaths {
    let mut folders = Vec::new();
    let mut source_files = Vec::new();
    let mut untracked_files = Vec::new();
    let mut excluded_paths = BTreeSet::new();
    for node in nodes {
        if has_excluded_suffix_component(&node.path, &config.exclude_dir_suffixes) {
            excluded_paths.insert(node.path.clone());
            continue;
        }
        match node.kind {
            NodeKind::Folder => {
                if is_legacy_map_metadata_folder(&node.path) {
                    continue;
                }
                folders.push(node.path.clone());
            }
            NodeKind::File => {
                if is_durable_projectatlas_input(&node.path, config) {
                    continue;
                }
                if is_source_node(
                    &node.path,
                    node.extension.as_deref(),
                    node.language.as_deref(),
                    config,
                ) {
                    source_files.push(node.path.clone());
                } else {
                    untracked_files.push(node.path.clone());
                }
            }
        }
    }
    folders.sort();
    source_files.sort();
    untracked_files.sort();
    RepoPaths {
        folders,
        source_files,
        untracked_files,
        excluded_paths: excluded_paths.into_iter().collect(),
    }
}

/// Return whether any path component has an excluded suffix.
fn has_excluded_suffix_component(path: &str, suffixes: &BTreeSet<String>) -> bool {
    path.split('/').any(|part| {
        suffixes
            .iter()
            .any(|suffix| !suffix.is_empty() && part.ends_with(suffix))
    })
}

/// Return whether a folder is `ProjectAtlas` metadata ignored by legacy map/lint.
fn is_legacy_map_metadata_folder(path: &str) -> bool {
    path == ".projectatlas"
}

/// Return whether a file is a durable `ProjectAtlas` input outside legacy map/lint.
fn is_durable_projectatlas_input(path: &str, config: &AtlasMapConfig) -> bool {
    DURABLE_PROJECTATLAS_INPUT_PATHS.contains(&path)
        || configured_nonsource_registry_path(config).as_deref() == Some(path)
}

/// Return the configured non-source registry as a repository-relative path.
fn configured_nonsource_registry_path(config: &AtlasMapConfig) -> Option<String> {
    let relative = config
        .nonsource_files_path
        .strip_prefix(&config.root)
        .ok()?;
    validated_repo_file_key(relative).ok()
}

/// Return whether a scanned file should be treated as source.
fn is_source_node(
    path: &str,
    extension: Option<&str>,
    language: Option<&str>,
    config: &AtlasMapConfig,
) -> bool {
    if is_under_any_prefix(path, &config.non_source_path_prefixes) {
        return false;
    }
    extension.is_some_and(|extension| config.source_extensions.contains(extension))
        || is_path_special_source_family(language)
}

/// Return whether the scanner detected a source-like file family without relying on extension policy.
fn is_path_special_source_family(language: Option<&str>) -> bool {
    matches!(
        language,
        Some("cargo-manifest" | "cargo-lock" | "rust-build-script" | "dockerfile" | "makefile")
    )
}

/// Build the full atlas snapshot.
fn build_snapshot(config: &AtlasMapConfig) -> AtlasMapResult<AtlasSnapshot> {
    let paths = collect_repo_paths(config)?;
    let db_purposes = load_db_purpose_records(config)?;
    let (file_records, _, _) = build_file_records(&paths.source_files, config, &db_purposes)?;
    let nonsource = read_nonsource_file_entries(config)?;
    let merged_file_records = merge_records(&file_records, &nonsource.records);
    let (folder_records, _, _) = build_folder_records(&paths.folders, config, &db_purposes)?;
    let folder_summary_map = folder_records
        .iter()
        .map(|record| (record.path.clone(), record.summary.clone()))
        .collect::<BTreeMap<_, _>>();
    let folder_tree = build_folder_tree(&paths.folders, &folder_summary_map);
    let folder_duplicates = build_summary_duplicates(&folder_records);
    let file_duplicates = build_summary_duplicates(&merged_file_records);
    let file_hash = compute_file_hash(&merged_file_records);
    let folder_hash = compute_folder_hash(&paths.folders);
    let overview = compute_overview(
        &paths,
        config,
        nonsource
            .records
            .iter()
            .filter(|record| record.source == "nonsource")
            .count(),
    );
    Ok(AtlasSnapshot {
        folder_records,
        file_records: merged_file_records,
        folder_tree,
        folder_duplicates,
        file_duplicates,
        generated_at: generated_at(),
        file_hash,
        folder_hash,
        overview,
    })
}

/// Return a simple UTC-ish generated timestamp.
fn generated_at() -> String {
    let seconds = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_or(0, |duration| duration.as_secs());
    format!("unix:{seconds}")
}

/// Build file records and validation lists.
fn build_file_records(
    files: &[String],
    config: &AtlasMapConfig,
    db_purposes: &BTreeMap<String, String>,
) -> AtlasMapResult<(Vec<MapRecord>, Vec<String>, BTreeMap<String, Vec<String>>)> {
    let mut read_text = read_text_file;
    build_file_records_with_reader(files, config, db_purposes, &mut read_text)
}

/// Build file purpose rows through a caller-owned bounded text reader.
fn build_file_records_with_reader<E, F>(
    files: &[String],
    config: &AtlasMapConfig,
    db_purposes: &BTreeMap<String, String>,
    read_text: &mut F,
) -> Result<(Vec<MapRecord>, Vec<String>, BTreeMap<String, Vec<String>>), E>
where
    E: From<AtlasMapError>,
    F: FnMut(&Path) -> Result<String, E>,
{
    let mut records = Vec::new();
    let mut missing = Vec::new();
    let mut invalid = BTreeMap::new();
    for rel_path in files {
        if let Some(summary) = db_purposes.get(rel_path) {
            records.push(MapRecord {
                path: rel_path.clone(),
                summary: summary.clone(),
                source: "database".to_string(),
            });
            continue;
        }
        let path = repo_join(&config.root, rel_path);
        let (summary, header_issues) =
            extract_purpose_header_with_reader(&path, rel_path, config, read_text)?;
        if let Some(summary) = summary {
            let issues = validate_summary(&summary, config);
            if issues.is_empty() {
                records.push(MapRecord {
                    path: rel_path.clone(),
                    summary,
                    source: "header".to_string(),
                });
            } else {
                invalid.insert(rel_path.clone(), issues);
                records.push(missing_record(rel_path));
            }
        } else if header_issues
            .iter()
            .any(|issue| issue.starts_with("missing "))
        {
            missing.push(rel_path.clone());
            records.push(missing_record(rel_path));
        } else {
            invalid.insert(rel_path.clone(), header_issues);
            records.push(invalid_record(rel_path));
        }
    }
    Ok((records, missing, invalid))
}

/// Build folder records and validation lists.
fn build_folder_records(
    folders: &[String],
    config: &AtlasMapConfig,
    db_purposes: &BTreeMap<String, String>,
) -> AtlasMapResult<(Vec<MapRecord>, Vec<String>, BTreeMap<String, Vec<String>>)> {
    let mut read_text = read_text_file;
    build_folder_records_with_reader(folders, config, db_purposes, &mut read_text)
}

/// Build folder purpose rows through a caller-owned bounded text reader.
fn build_folder_records_with_reader<E, F>(
    folders: &[String],
    config: &AtlasMapConfig,
    db_purposes: &BTreeMap<String, String>,
    read_text: &mut F,
) -> Result<(Vec<MapRecord>, Vec<String>, BTreeMap<String, Vec<String>>), E>
where
    E: From<AtlasMapError>,
    F: FnMut(&Path) -> Result<String, E>,
{
    let mut records = Vec::new();
    let mut missing = Vec::new();
    let mut invalid = BTreeMap::new();
    for folder in folders {
        if let Some(summary) = db_purposes.get(folder) {
            records.push(MapRecord {
                path: folder.clone(),
                summary: summary.clone(),
                source: "database".to_string(),
            });
            continue;
        }
        let (summary, issues) = read_folder_purpose_with_reader(folder, config, read_text)?;
        if let Some(summary) = summary {
            if issues.is_empty() {
                records.push(MapRecord {
                    path: folder.clone(),
                    summary,
                    source: "purpose".to_string(),
                });
            } else {
                invalid.insert(folder.clone(), issues);
                records.push(invalid_record(folder));
            }
        } else if issues.iter().any(|issue| issue == "missing .purpose file") {
            missing.push(folder.clone());
            records.push(missing_record(folder));
        } else {
            invalid.insert(folder.clone(), issues);
            records.push(invalid_record(folder));
        }
    }
    Ok((records, missing, invalid))
}

/// Create a missing placeholder record.
fn missing_record(path: &str) -> MapRecord {
    MapRecord {
        path: path.to_string(),
        summary: "MISSING".to_string(),
        source: "missing".to_string(),
    }
}

/// Create an invalid placeholder record.
fn invalid_record(path: &str) -> MapRecord {
    MapRecord {
        path: path.to_string(),
        summary: "INVALID".to_string(),
        source: "invalid".to_string(),
    }
}

/// Extract a purpose header through a caller-owned bounded text reader.
fn extract_purpose_header_with_reader<E, F>(
    path: &Path,
    rel_path: &str,
    config: &AtlasMapConfig,
    read_text: &mut F,
) -> Result<(Option<String>, Vec<String>), E>
where
    F: FnMut(&Path) -> Result<String, E>,
{
    let extension = normalized_extension(rel_path);
    let language =
        explicit_language_override(rel_path, Some(&extension), &config.language_overrides);
    if document_format_for_path(rel_path, language).is_some() {
        return Ok((
            None,
            vec!["missing database purpose for document".to_owned()],
        ));
    }
    let content = read_text(path)?;
    let lines = content.lines().map(ToString::to_string).collect::<Vec<_>>();
    let style = resolve_purpose_style(rel_path, config);
    let result = match style.as_str() {
        "python-docstring" => extract_python_docstring_purpose(&lines, config.max_scan_lines),
        "vue-block" => extract_vue_purpose(&lines, config.max_scan_lines),
        "javadoc" => extract_javadoc_purpose(&lines, config.max_scan_lines),
        "block-comment" => extract_block_comment_purpose(&lines, config.max_scan_lines),
        "line-comment" => extract_line_comment_purpose(
            &lines,
            config.max_scan_lines,
            &config.line_comment_prefixes,
        ),
        _ => (None, vec![format!("unsupported Purpose style: {style}")]),
    };
    Ok(result)
}

/// Resolve configured purpose style for a relative path.
fn resolve_purpose_style(path: &str, config: &AtlasMapConfig) -> String {
    let extension = normalized_extension(path);
    config
        .purpose_styles
        .get(&extension)
        .cloned()
        .unwrap_or_else(|| config.purpose_default_style.clone())
}

/// Extract a purpose from a Javadoc-style block.
fn extract_javadoc_purpose(
    lines: &[String],
    max_scan_lines: usize,
) -> (Option<String>, Vec<String>) {
    let Some(start) = first_content_line(lines) else {
        return (
            None,
            vec!["missing Javadoc-style Purpose header".to_string()],
        );
    };
    if !lines[start].trim_start().starts_with("/**") {
        return (
            None,
            vec!["missing Javadoc-style Purpose header".to_string()],
        );
    }
    let block = collect_until(lines, start, max_scan_lines, "*/");
    match block {
        Some(block) => purpose_from_lines(&block, None).map_or_else(
            || {
                (
                    None,
                    vec!["missing Purpose line in Javadoc-style header".to_string()],
                )
            },
            |summary| (Some(summary), Vec::new()),
        ),
        None => (None, vec!["unterminated Javadoc-style header".to_string()]),
    }
}

/// Extract a purpose from a generic block comment.
fn extract_block_comment_purpose(
    lines: &[String],
    max_scan_lines: usize,
) -> (Option<String>, Vec<String>) {
    let Some(start) = first_content_line(lines) else {
        return (
            None,
            vec!["missing block comment Purpose header".to_string()],
        );
    };
    if !lines[start].trim_start().starts_with("/*") {
        return (
            None,
            vec!["missing block comment Purpose header".to_string()],
        );
    }
    let block = collect_until(lines, start, max_scan_lines, "*/");
    match block {
        Some(block) => purpose_from_lines(&block, None).map_or_else(
            || {
                (
                    None,
                    vec!["missing Purpose line in block comment header".to_string()],
                )
            },
            |summary| (Some(summary), Vec::new()),
        ),
        None => (None, vec!["unterminated block comment header".to_string()]),
    }
}

/// Extract a purpose from a Python module docstring.
fn extract_python_docstring_purpose(
    lines: &[String],
    max_scan_lines: usize,
) -> (Option<String>, Vec<String>) {
    let Some(start) = first_python_doc_line(lines) else {
        return (
            None,
            vec!["missing module docstring Purpose header".to_string()],
        );
    };
    let trimmed = lines[start].trim_start();
    let delimiter = if trimmed.starts_with("\"\"\"") {
        "\"\"\""
    } else if trimmed.starts_with("'''") {
        "'''"
    } else {
        return (
            None,
            vec!["missing module docstring Purpose header".to_string()],
        );
    };
    let block = collect_python_docstring(lines, start, max_scan_lines, delimiter);
    match block {
        Some(block) => purpose_from_lines(&block, None).map_or_else(
            || {
                (
                    None,
                    vec!["missing Purpose line in module docstring".to_string()],
                )
            },
            |summary| (Some(summary), Vec::new()),
        ),
        None => (None, vec!["unterminated module docstring".to_string()]),
    }
}

/// Extract a purpose from a Vue script or style block.
fn extract_vue_purpose(lines: &[String], max_scan_lines: usize) -> (Option<String>, Vec<String>) {
    for tag in ["script", "style"] {
        let Some(start) = lines
            .iter()
            .position(|line| line.trim_start().starts_with(&format!("<{tag}")))
        else {
            continue;
        };
        let Some(end) = lines
            .iter()
            .enumerate()
            .skip(start + 1)
            .find_map(|(index, line)| {
                line.trim_start()
                    .starts_with(&format!("</{tag}>"))
                    .then_some(index)
            })
        else {
            return (None, vec![format!("unterminated <{tag}> block")]);
        };
        return extract_javadoc_purpose(&lines[start + 1..end], max_scan_lines);
    }
    (
        None,
        vec!["missing Javadoc-style Purpose header in <script> or <style> block".to_string()],
    )
}

/// Extract a purpose from a line-comment header.
fn extract_line_comment_purpose(
    lines: &[String],
    max_scan_lines: usize,
    prefixes: &[String],
) -> (Option<String>, Vec<String>) {
    let mut comment_lines = Vec::new();
    for line in skip_yaml_frontmatter(lines).iter().take(max_scan_lines) {
        let trimmed = line.trim();
        if trimmed.is_empty() {
            if comment_lines.is_empty() {
                continue;
            }
            break;
        }
        if trimmed.starts_with("#!") && comment_lines.is_empty() {
            continue;
        }
        if prefixes.iter().any(|prefix| trimmed.starts_with(prefix)) {
            comment_lines.push(trimmed.to_string());
            continue;
        }
        break;
    }
    if comment_lines.is_empty() {
        return (
            None,
            vec!["missing line-comment Purpose header".to_string()],
        );
    }
    purpose_from_lines(&comment_lines, Some(prefixes)).map_or_else(
        || {
            (
                None,
                vec!["missing Purpose line in line-comment header".to_string()],
            )
        },
        |summary| (Some(summary), Vec::new()),
    )
}

/// Return lines after a leading YAML frontmatter block when one is present.
fn skip_yaml_frontmatter(lines: &[String]) -> &[String] {
    if lines.first().is_none_or(|line| line.trim() != "---") {
        return lines;
    }
    lines
        .iter()
        .enumerate()
        .skip(1)
        .find_map(|(index, line)| (line.trim() == "---").then_some(&lines[index + 1..]))
        .unwrap_or(lines)
}

/// Return the first content line after shebangs and blanks.
fn first_content_line(lines: &[String]) -> Option<usize> {
    lines.iter().enumerate().find_map(|(index, line)| {
        let trimmed = line.trim();
        (!trimmed.is_empty() && !trimmed.starts_with("#!") && !is_php_open_tag_line(trimmed))
            .then_some(index)
    })
}

/// Return the first Python docstring candidate line.
fn first_python_doc_line(lines: &[String]) -> Option<usize> {
    lines.iter().enumerate().find_map(|(index, line)| {
        let trimmed = line.trim();
        if trimmed.is_empty()
            || trimmed.starts_with("#!")
            || trimmed.starts_with('#')
            || trimmed.contains("coding:")
            || trimmed.contains("coding=")
        {
            None
        } else {
            Some(index)
        }
    })
}

/// Return whether a line is only a PHP open tag or declaration before comments.
fn is_php_open_tag_line(trimmed: &str) -> bool {
    trimmed
        .strip_prefix("<?php")
        .map(str::trim)
        .is_some_and(|rest| rest.is_empty() || rest.starts_with("declare("))
}

/// Collect lines until a marker appears.
fn collect_until(
    lines: &[String],
    start: usize,
    max_scan_lines: usize,
    marker: &str,
) -> Option<Vec<String>> {
    let mut block = Vec::new();
    for line in lines.iter().skip(start).take(max_scan_lines) {
        block.push(line.clone());
        if line.contains(marker) {
            return Some(block);
        }
    }
    None
}

/// Collect a Python docstring body.
fn collect_python_docstring(
    lines: &[String],
    start: usize,
    max_scan_lines: usize,
    delimiter: &str,
) -> Option<Vec<String>> {
    let first = lines[start].trim_start();
    let after_open = first.strip_prefix(delimiter)?;
    if let Some((before_close, _)) = after_open.split_once(delimiter) {
        return Some(vec![before_close.to_string()]);
    }
    let mut block = vec![after_open.to_string()];
    for line in lines.iter().skip(start + 1).take(max_scan_lines) {
        if let Some((before_close, _)) = line.split_once(delimiter) {
            block.push(before_close.to_string());
            return Some(block);
        }
        block.push(line.clone());
    }
    None
}

/// Extract a normalized purpose from comment lines.
fn purpose_from_lines(lines: &[String], prefixes: Option<&[String]>) -> Option<String> {
    lines.iter().find_map(|line| {
        let mut cleaned = line.trim().to_string();
        if let Some(prefixes) = prefixes {
            cleaned = strip_line_comment_prefix(&cleaned, prefixes);
        }
        cleaned = cleaned
            .trim_start_matches("/**")
            .trim_start_matches("/*")
            .trim_start_matches('*')
            .trim_end_matches("*/")
            .trim()
            .to_string();
        cleaned
            .split_once("Purpose:")
            .map(|(_, summary)| normalize_summary(summary))
    })
}

/// Strip a line-comment prefix.
fn strip_line_comment_prefix(line: &str, prefixes: &[String]) -> String {
    for prefix in prefixes {
        if let Some(remainder) = line.strip_prefix(prefix) {
            return remainder.trim_start_matches('!').trim_start().to_string();
        }
    }
    line.to_string()
}

/// Normalize a summary to a single-line value.
fn normalize_summary(summary: &str) -> String {
    summary.split_whitespace().collect::<Vec<_>>().join(" ")
}

/// Validate a purpose summary.
fn validate_summary(summary: &str, config: &AtlasMapConfig) -> Vec<String> {
    let mut problems = Vec::new();
    if summary.is_empty() {
        problems.push("summary is empty".to_string());
    }
    if config.summary_no_commas && summary.contains(',') {
        problems.push("summary contains a comma".to_string());
    }
    if config.summary_ascii_only && !summary.is_ascii() {
        problems.push("summary contains non-ASCII characters".to_string());
    }
    if summary.len() > config.summary_max_length {
        problems.push("summary exceeds length limit".to_string());
    }
    problems
}

/// Read folder purpose metadata through a caller-owned bounded text reader.
fn read_folder_purpose_with_reader<E, F>(
    folder: &str,
    config: &AtlasMapConfig,
    read_text: &mut F,
) -> Result<(Option<String>, Vec<String>), E>
where
    F: FnMut(&Path) -> Result<String, E>,
{
    let purpose_path = repo_join(&config.root, folder).join(&config.purpose_filename);
    if !purpose_path.exists() {
        return Ok((None, vec!["missing .purpose file".to_string()]));
    }
    let content = read_text(&purpose_path)?;
    for line in content.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with("//") {
            continue;
        }
        let summary = trimmed.split_once("Purpose:").map_or_else(
            || normalize_summary(trimmed),
            |(_, value)| normalize_summary(value),
        );
        let issues = validate_summary(&summary, config);
        return Ok((Some(summary), issues));
    }
    Ok((None, vec!["missing Purpose summary".to_string()]))
}

/// Read non-source file entries.
fn read_nonsource_file_entries(config: &AtlasMapConfig) -> AtlasMapResult<NonsourceEntries> {
    let mut read_text = read_text_file;
    read_nonsource_file_entries_with_reader(config, &mut read_text)
}

/// Read non-source purpose rows through a caller-owned bounded text reader.
fn read_nonsource_file_entries_with_reader<E, F>(
    config: &AtlasMapConfig,
    read_text: &mut F,
) -> Result<NonsourceEntries, E>
where
    E: From<AtlasMapError>,
    F: FnMut(&Path) -> Result<String, E>,
{
    if !config.nonsource_files_path.exists() {
        return Ok(NonsourceEntries {
            records: Vec::new(),
            missing: Vec::new(),
            invalid: BTreeMap::new(),
            errors: vec![format!(
                "non-source file list missing: {}",
                config.nonsource_files_path.display()
            )],
        });
    }
    let content = read_text(&config.nonsource_files_path)?;
    let mut in_nonsource = false;
    let mut records = Vec::new();
    let mut missing = Vec::new();
    let mut invalid = BTreeMap::new();
    for raw in content.lines() {
        let line = raw.trim();
        if line.is_empty() || line.starts_with('#') || line.starts_with("//") {
            continue;
        }
        if line.starts_with("nonsource_files[") || line.starts_with("manual_files[") {
            in_nonsource = true;
            continue;
        }
        if line.starts_with("folders[") || line.starts_with("files[") {
            in_nonsource = false;
            continue;
        }
        if !in_nonsource || line.starts_with('-') || line.ends_with(':') {
            continue;
        }
        let cells = split_record_cells(line);
        if cells.len() < 2 {
            continue;
        }
        let rel_path = match normalize_repo_string(&cells[0]) {
            Ok(path) => path,
            Err(error) => {
                invalid.insert(cells[0].clone(), vec![error.to_string()]);
                continue;
            }
        };
        let summary = normalize_summary(&cells[1]);
        if !repo_join(&config.root, &rel_path).exists() {
            missing.push(rel_path.clone());
            records.push(missing_record(&rel_path));
            continue;
        }
        let issues = validate_summary(&summary, config);
        if issues.is_empty() {
            records.push(MapRecord {
                path: rel_path,
                summary,
                source: "nonsource".to_string(),
            });
        } else {
            invalid.insert(rel_path.clone(), issues);
            records.push(invalid_record(&rel_path));
        }
    }
    Ok(NonsourceEntries {
        records,
        missing,
        invalid,
        errors: Vec::new(),
    })
}

/// Merge source and non-source records.
fn merge_records(source: &[MapRecord], nonsource: &[MapRecord]) -> Vec<MapRecord> {
    let mut merged = source
        .iter()
        .map(|record| (record.path.clone(), record.clone()))
        .collect::<BTreeMap<_, _>>();
    for record in nonsource {
        merged
            .entry(record.path.clone())
            .or_insert_with(|| record.clone());
    }
    merged.into_values().collect()
}

/// Build duplicate summary entries.
fn build_summary_duplicates(records: &[MapRecord]) -> Vec<String> {
    let mut grouped: BTreeMap<&str, Vec<&str>> = BTreeMap::new();
    for record in records {
        if record.summary == "MISSING" || record.summary == "INVALID" {
            continue;
        }
        grouped
            .entry(&record.summary)
            .or_default()
            .push(&record.path);
    }
    grouped
        .into_iter()
        .filter_map(|(summary, mut paths)| {
            if paths.len() < 2 {
                None
            } else {
                paths.sort_unstable();
                Some(format!("{summary} :: {}", paths.join(" | ")))
            }
        })
        .collect()
}

/// Build folder tree lines.
fn build_folder_tree(folders: &[String], summaries: &BTreeMap<String, String>) -> Vec<String> {
    folders
        .iter()
        .map(|folder| {
            let summary = summaries
                .get(folder)
                .map_or("MISSING", std::string::String::as_str);
            if folder == "." {
                format!(". - {summary}")
            } else {
                let depth = folder.matches('/').count();
                let name = folder.rsplit('/').next().unwrap_or(folder);
                format!("{}{name}/ - {summary}", "  ".repeat(depth))
            }
        })
        .collect()
}

/// Compute overview counters.
fn compute_overview(
    paths: &RepoPaths,
    config: &AtlasMapConfig,
    nonsource_count: usize,
) -> BTreeMap<String, usize> {
    let mut overview = BTreeMap::new();
    overview.insert("tracked_source_files".to_string(), paths.source_files.len());
    overview.insert("tracked_nonsource_files".to_string(), nonsource_count);
    overview.insert(
        "tracked_files_total".to_string(),
        paths.source_files.len() + nonsource_count,
    );
    overview.insert("tracked_folders".to_string(), paths.folders.len());
    overview.insert(
        "source_extensions".to_string(),
        config.source_extensions.len(),
    );
    overview.insert(
        "exclude_dir_names".to_string(),
        config.exclude_dir_names.len(),
    );
    overview.insert(
        "exclude_path_prefixes".to_string(),
        config.exclude_path_prefixes.len(),
    );
    overview
}

/// Compute file record hash.
fn compute_file_hash(records: &[MapRecord]) -> String {
    let payload = records
        .iter()
        .map(|record| format!("{}|{}", record.path, record.summary))
        .collect::<Vec<_>>()
        .join("\n");
    hash_text(&payload)
}

/// Compute folder path hash.
fn compute_folder_hash(folders: &[String]) -> String {
    hash_text(&folders.join("\n"))
}

/// Hash a text payload with BLAKE3.
fn hash_text(payload: &str) -> String {
    let mut hasher = Hasher::new();
    hasher.update(payload.as_bytes());
    hasher.finalize().to_hex().to_string()
}

/// Render a TOON snapshot.
fn render_toon(snapshot: &AtlasSnapshot, config: &AtlasMapConfig) -> String {
    let mut lines = Vec::new();
    lines.push("version: 1".to_string());
    lines.push(format!("generated_at: {}", snapshot.generated_at));
    lines.push(format!("file_hash: \"{}\"", snapshot.file_hash));
    lines.push(format!("folder_hash: \"{}\"", snapshot.folder_hash));
    lines.push("root: .".to_string());
    lines.push(format_overview(&snapshot.overview));
    lines.push("source_extensions[]:".to_string());
    lines.extend(
        config
            .source_extensions
            .iter()
            .map(|extension| format!("  - {extension}")),
    );
    lines.push("exclude_dir_names[]:".to_string());
    lines.extend(
        config
            .exclude_dir_names
            .iter()
            .map(|name| format!("  - {name}")),
    );
    lines.push("exclude_path_prefixes[]:".to_string());
    lines.extend(
        config
            .exclude_path_prefixes
            .iter()
            .map(|prefix| format!("  - {prefix}")),
    );
    append_record_rows(&mut lines, "folders", &snapshot.folder_records);
    append_record_rows(&mut lines, "files", &snapshot.file_records);
    append_list(
        &mut lines,
        "folder_summary_duplicates",
        &snapshot.folder_duplicates,
    );
    append_list(
        &mut lines,
        "file_summary_duplicates",
        &snapshot.file_duplicates,
    );
    append_list(&mut lines, "folder_tree", &snapshot.folder_tree);
    lines.join("\n") + "\n"
}

/// Append TOON record rows.
fn append_record_rows(lines: &mut Vec<String>, label: &str, records: &[MapRecord]) {
    lines.push(format!(
        "{label}[{}]{{path,summary,source}}:",
        records.len()
    ));
    lines.extend(records.iter().map(|record| {
        format!(
            "  {},{},{}",
            toon_cell(&record.path),
            toon_cell(&record.summary),
            toon_cell(&record.source)
        )
    }));
}

/// Append TOON list rows.
fn append_list(lines: &mut Vec<String>, label: &str, entries: &[String]) {
    lines.push(format!("{label}[]:"));
    lines.extend(
        entries
            .iter()
            .map(|entry| format!("  - {}", toon_cell(entry))),
    );
}

/// Render a TOON scalar cell with JSON-compatible escaping when needed.
fn toon_cell(value: &str) -> String {
    if needs_quoted_cell(value) {
        quote_toon_string(value)
    } else {
        value.to_string()
    }
}

/// Return whether a tabular TOON cell needs quotes.
fn needs_quoted_cell(value: &str) -> bool {
    value.is_empty()
        || value.chars().any(|character| {
            matches!(
                character,
                ',' | '"' | '\\' | '\n' | '\r' | '\t' | '[' | ']' | '{' | '}'
            ) || character.is_control()
        })
        || value.trim() != value
}

/// Quote a string with JSON-compatible escapes for TOON scalar cells.
fn quote_toon_string(value: &str) -> String {
    let mut quoted = String::with_capacity(value.len() + 2);
    quoted.push('"');
    for character in value.chars() {
        match character {
            '"' => quoted.push_str("\\\""),
            '\\' => quoted.push_str("\\\\"),
            '\n' => quoted.push_str("\\n"),
            '\r' => quoted.push_str("\\r"),
            '\t' => quoted.push_str("\\t"),
            character if character.is_control() => {
                push_unicode_escape_digits(&mut quoted, character as u32);
            }
            character => quoted.push(character),
        }
    }
    quoted.push('"');
    quoted
}

/// Split a compact TOON record row into cells.
fn split_record_cells(line: &str) -> Vec<String> {
    let mut cells = Vec::new();
    let mut current = String::new();
    let mut chars = line.chars().peekable();
    let mut in_quotes = false;
    while let Some(character) = chars.next() {
        match character {
            '"' if in_quotes => in_quotes = false,
            '"' if current.trim().is_empty() => in_quotes = true,
            '\\' if in_quotes => push_escaped_char(&mut current, &mut chars),
            ',' if !in_quotes => {
                cells.push(current.trim().to_string());
                current.clear();
            }
            character => current.push(character),
        }
    }
    cells.push(current.trim().to_string());
    cells
}

/// Push one escaped character from a quoted TOON cell.
fn push_escaped_char(current: &mut String, chars: &mut std::iter::Peekable<std::str::Chars<'_>>) {
    match chars.next() {
        Some('"') => current.push('"'),
        Some('\\') | None => current.push('\\'),
        Some('n') => current.push('\n'),
        Some('r') => current.push('\r'),
        Some('t') => current.push('\t'),
        Some('u') => push_unicode_escape(current, chars),
        Some(other) => current.push(other),
    }
}

/// Push a four-digit Unicode escape into a quoted string.
fn push_unicode_escape_digits(output: &mut String, value: u32) {
    const HEX: &[u8; 16] = b"0123456789abcdef";
    output.push_str("\\u");
    for shift in [12, 8, 4, 0] {
        let index = ((value >> shift) & 0x0f) as usize;
        output.push(char::from(HEX[index]));
    }
}

/// Push a four-digit Unicode escape when present.
fn push_unicode_escape(current: &mut String, chars: &mut std::iter::Peekable<std::str::Chars<'_>>) {
    let mut digits = String::with_capacity(4);
    for _ in 0..4 {
        if let Some(digit) = chars.next() {
            digits.push(digit);
        }
    }
    if let Ok(value) = u32::from_str_radix(&digits, 16)
        && let Some(character) = char::from_u32(value)
    {
        current.push(character);
        return;
    }
    current.push_str("\\u");
    current.push_str(&digits);
}

/// Format overview counters.
fn format_overview(overview: &BTreeMap<String, usize>) -> String {
    let parts = OVERVIEW_KEYS
        .iter()
        .filter_map(|key| overview.get(*key).map(|value| format!("{key}={value}")))
        .collect::<Vec<_>>();
    format!("overview: {}", parts.join(" "))
}

/// Render the JSON map payload.
fn render_json_map(snapshot: &AtlasSnapshot) -> AtlasMapResult<String> {
    let payload = serde_json::json!({
        "version": 1,
        "generated_at": snapshot.generated_at,
        "file_hash": snapshot.file_hash,
        "folder_hash": snapshot.folder_hash,
        "root": ".",
        "overview": snapshot.overview,
        "folders": snapshot.folder_records.iter().map(record_json).collect::<Vec<_>>(),
        "files": snapshot.file_records.iter().map(record_json).collect::<Vec<_>>(),
        "folder_summary_duplicates": snapshot.folder_duplicates,
        "file_summary_duplicates": snapshot.file_duplicates,
        "folder_tree": snapshot.folder_tree,
    });
    Ok(serde_json::to_string_pretty(&payload)? + "\n")
}

/// Write an explicitly requested JSON map next to the legacy import location.
pub(crate) fn write_json_map(content: &str, config: &AtlasMapConfig) -> AtlasMapResult<()> {
    let json_path = match config
        .map_path
        .extension()
        .and_then(|extension| extension.to_str())
    {
        Some(extension) if extension.eq_ignore_ascii_case("json") => {
            config.map_path.with_extension(format!("{extension}.json"))
        }
        _ => config.map_path.with_extension("json"),
    };
    let document_guard =
        crate::project_state::ProjectStateGuard::preflight_document(&config.root, &json_path)
            .map_err(|source| AtlasMapError::Io {
                path: json_path.clone(),
                source,
            })?;
    if document_guard.is_none()
        && let Some(parent) = json_path.parent()
    {
        fs::create_dir_all(parent).map_err(|source| AtlasMapError::Io {
            path: parent.to_path_buf(),
            source,
        })?;
    }
    let legacy = match same_file::Handle::from_path(&config.map_path) {
        Ok(handle) => Some(handle),
        Err(source) if source.kind() == io::ErrorKind::NotFound => {
            match fs::symlink_metadata(&config.map_path) {
                Err(source) if source.kind() == io::ErrorKind::NotFound => None,
                Ok(metadata) if metadata.file_type().is_symlink() => {
                    return Err(AtlasMapError::Io {
                        path: config.map_path.clone(),
                        source: io::Error::new(
                            io::ErrorKind::InvalidInput,
                            "legacy map is a dangling symlink",
                        ),
                    });
                }
                Ok(_) => {
                    return Err(AtlasMapError::Io {
                        path: config.map_path.clone(),
                        source,
                    });
                }
                Err(source) => {
                    return Err(AtlasMapError::Io {
                        path: config.map_path.clone(),
                        source,
                    });
                }
            }
        }
        Err(source) => {
            return Err(AtlasMapError::Io {
                path: config.map_path.clone(),
                source,
            });
        }
    };
    if let Some(mut guard) = document_guard {
        if let Some(legacy) = &legacy {
            let aliases_legacy = match same_file::Handle::from_path(&json_path) {
                Ok(identity) => &identity == legacy,
                Err(source) if source.kind() == io::ErrorKind::NotFound => false,
                Err(source) => {
                    return Err(AtlasMapError::Io {
                        path: json_path,
                        source,
                    });
                }
            };
            if aliases_legacy {
                return Err(AtlasMapError::Io {
                    path: json_path,
                    source: io::Error::new(
                        io::ErrorKind::InvalidInput,
                        "JSON sidecar aliases the legacy map",
                    ),
                });
            }
        }
        return guard
            .write_document(content.as_bytes())
            .map_err(|source| AtlasMapError::Io {
                path: json_path,
                source,
            });
    }
    let mut output = match OpenOptions::new().write(true).open(&json_path) {
        Ok(file) => file,
        Err(source) if source.kind() == io::ErrorKind::NotFound => OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&json_path)
            .map_err(|source| AtlasMapError::Io {
                path: json_path.clone(),
                source,
            })?,
        Err(source) => {
            return Err(AtlasMapError::Io {
                path: json_path,
                source,
            });
        }
    };
    let identity =
        same_file::Handle::from_file(output.try_clone().map_err(|source| AtlasMapError::Io {
            path: json_path.clone(),
            source,
        })?)
        .map_err(|source| AtlasMapError::Io {
            path: json_path.clone(),
            source,
        })?;
    if legacy.as_ref() == Some(&identity) {
        return Err(AtlasMapError::Io {
            path: json_path,
            source: io::Error::new(
                io::ErrorKind::InvalidInput,
                "JSON sidecar aliases the legacy map",
            ),
        });
    }
    output.set_len(0).map_err(|source| AtlasMapError::Io {
        path: json_path.clone(),
        source,
    })?;
    output
        .write_all(content.as_bytes())
        .map_err(|source| AtlasMapError::Io {
            path: json_path,
            source,
        })
}

/// Convert a map record to JSON.
fn record_json(record: &MapRecord) -> serde_json::Value {
    serde_json::json!({
        "path": record.path,
        "summary": record.summary,
        "source": record.source,
    })
}

/// Build the typed untracked-file inventory.
fn build_untracked_report(
    config: &AtlasMapConfig,
    paths: &RepoPaths,
    options: LintOptions,
) -> AtlasMapResult<UntrackedLintReport> {
    let nonsource = read_nonsource_file_entries(config)?;
    let nonsource_paths = nonsource
        .records
        .iter()
        .map(|record| record.path.as_str())
        .collect::<BTreeSet<_>>();
    let db_purposes = load_db_purpose_records(config)?;
    let mut allowed = Vec::new();
    let mut disallowed = Vec::new();
    let mut asset_outside_roots = Vec::new();
    for path in &paths.untracked_files {
        if nonsource_paths.contains(path.as_str())
            || db_purposes.contains_key(path)
            || is_allowed_untracked(path, config)
        {
            allowed.push(path.clone());
        } else if is_asset_file(path, config)
            && !is_under_any_prefix(path, &config.asset_allowed_prefixes)
        {
            asset_outside_roots.push(path.clone());
            disallowed.push(path.clone());
        } else {
            disallowed.push(path.clone());
        }
    }
    Ok(UntrackedLintReport {
        total: paths.untracked_files.len(),
        allowed: allowed.len(),
        disallowed_extension_counts: summarize_extensions(&disallowed),
        allowed_extension_counts: summarize_extensions(&allowed),
        asset_roots_present: existing_asset_roots(config).len(),
        assets_outside_roots: asset_outside_roots,
        excluded_paths_present: paths.excluded_paths.len(),
        strict: options.strict_untracked,
        disallowed,
    })
}

/// Return whether an untracked path is allowed.
fn is_allowed_untracked(path: &str, config: &AtlasMapConfig) -> bool {
    let name = path.rsplit('/').next().unwrap_or(path);
    config.allowed_untracked_filenames.contains(name)
        || config.untracked_allowlist_files.contains(path)
        || is_under_any_prefix(path, &config.untracked_allowlist_dir_prefixes)
}

/// Return whether a file is an asset by extension.
fn is_asset_file(path: &str, config: &AtlasMapConfig) -> bool {
    config
        .asset_extensions
        .contains(&normalized_extension(path))
}

/// List existing asset roots.
fn existing_asset_roots(config: &AtlasMapConfig) -> Vec<String> {
    config
        .asset_allowed_prefixes
        .iter()
        .filter(|prefix| repo_join(&config.root, prefix).exists())
        .cloned()
        .collect()
}

/// Summarize extensions for reporting.
fn summarize_extensions(paths: &[String]) -> BTreeMap<String, usize> {
    let mut counts: BTreeMap<String, usize> = BTreeMap::new();
    for path in paths {
        let extension = normalized_extension(path);
        let key = if extension.is_empty() {
            "<no_ext>".to_string()
        } else {
            extension
        };
        *counts.entry(key).or_default() += 1;
    }
    counts
}

/// Format deterministic extension counts as compatibility list items.
fn format_extension_counts(counts: &BTreeMap<String, usize>) -> String {
    format_list(
        &counts
            .iter()
            .map(|(extension, count)| format!("{extension}={count}"))
            .collect::<Vec<_>>(),
    )
}

/// Format report list items.
fn format_list(items: &[String]) -> String {
    items
        .iter()
        .map(|item| format!(" - {item}"))
        .collect::<Vec<_>>()
        .join("\n")
}

/// Join report sections with newlines.
fn join_report(report: &[String]) -> String {
    if report.is_empty() {
        String::new()
    } else {
        report.join("\n") + "\n"
    }
}

/// Return whether a path is below any configured prefix.
fn is_under_any_prefix(path: &str, prefixes: &BTreeSet<String>) -> bool {
    prefixes
        .iter()
        .any(|prefix| path == prefix || path.starts_with(&format!("{prefix}/")))
}

/// Join a repository-relative slash path onto a root.
fn repo_join(root: &Path, rel_path: &str) -> PathBuf {
    if rel_path == "." {
        return root.to_path_buf();
    }
    rel_path
        .split('/')
        .fold(root.to_path_buf(), |path, part| path.join(part))
}

/// Normalize a path-like string to repository slash format.
fn normalize_repo_string(path: &str) -> AtlasMapResult<String> {
    let value = path.trim();
    if value.is_empty() || value == "." {
        return Ok(".".to_string());
    }
    validated_repo_file_key(Path::new(value)).map_err(|source| {
        AtlasMapError::InvalidRepositoryPath {
            path: path.to_string(),
            message: source.to_string(),
        }
    })
}

/// Return a normalized extension from a repository path.
fn normalized_extension(path: &str) -> String {
    if path.ends_with(".d.ts") {
        return ".d.ts".to_string();
    }
    let file_name = path.rsplit('/').next().unwrap_or(path);
    match file_name.rsplit_once('.') {
        Some((prefix, suffix)) if !prefix.is_empty() => format!(".{}", suffix.to_ascii_lowercase()),
        _ => String::new(),
    }
}

/// Build default config text.
fn default_config_text() -> String {
    default_config_text_with_root(".")
}

/// Build default config text for a config file created by init.
fn default_config_text_for(root: &Path, config_path: &Path) -> AtlasMapResult<String> {
    Ok(default_config_text_with_root(&default_config_root_value(
        root,
        config_path,
    )?))
}

/// Return the `[project].root` value that keeps an explicit init config bound to `root`.
fn default_config_root_value(root: &Path, config_path: &Path) -> AtlasMapResult<String> {
    let canonical_root = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
    if config_path_is_projectatlas(Some(config_path))? {
        let implied = project_root_for_projectatlas_config(Some(config_path), &canonical_root);
        if implied
            .canonicalize()
            .is_ok_and(|implied| implied == canonical_root)
        {
            return Ok(".".to_string());
        }
    }
    let Some(parent) = config_path.parent() else {
        return Ok(".".to_string());
    };
    let root = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
    let parent = resolve_config_parent(parent);
    if parent == root {
        return Ok(".".to_string());
    }
    if let Ok(relative_parent) = parent.strip_prefix(&root) {
        let depth = relative_parent
            .components()
            .filter(|component| matches!(component, std::path::Component::Normal(_)))
            .count();
        if depth == 0 {
            Ok(".".to_string())
        } else {
            Ok(std::iter::repeat_n("..", depth)
                .collect::<Vec<_>>()
                .join("/"))
        }
    } else {
        projectatlas_core::lossless_native_path_display(&root).map_err(|_error| {
            AtlasMapError::InvalidRepositoryPath {
                path: "<native project root>".to_string(),
                message: "cannot serialize a non-UTF-8 root into an external TOML config"
                    .to_string(),
            }
        })
    }
}

/// Resolve a config parent through existing symlinks while preserving missing native components.
fn resolve_config_parent(parent: &Path) -> PathBuf {
    let mut missing_components = Vec::new();
    let mut candidate = parent;
    loop {
        match candidate.canonicalize() {
            Ok(mut resolved) => {
                for component in missing_components.iter().rev() {
                    resolved.push(component);
                }
                return resolved;
            }
            Err(source) if source.kind() == io::ErrorKind::NotFound => {
                let Some(component) = candidate.file_name() else {
                    return parent.to_path_buf();
                };
                missing_components.push(component.to_os_string());
                let Some(next) = candidate.parent() else {
                    return parent.to_path_buf();
                };
                candidate = next;
            }
            Err(_) => return parent.to_path_buf(),
        }
    }
}

/// Build default config text with the supplied project root value.
fn default_config_text_with_root(root_value: &str) -> String {
    let default_source_extensions = default_source_extensions();
    let source_extension_refs = default_source_extensions
        .iter()
        .map(String::as_str)
        .collect::<Vec<_>>();
    let source_extensions = toml_array(&source_extension_refs);
    [
        "[project]",
        &format!(
            "root = \"{}\"",
            root_value.replace('\\', "\\\\").replace('"', "\\\"")
        ),
        "map_path = \".projectatlas/projectatlas.toon\"",
        "nonsource_files_path = \".projectatlas/projectatlas-nonsource-files.toon\"",
        "",
        "[scan]",
        &format!("source_extensions = {source_extensions}"),
        "exclude_dir_names = [\".git\", \".projectatlas\", \".venv\", \"__pycache__\", \"node_modules\", \"dist\", \"build\", \"target\"]",
        "exclude_dir_suffixes = [\".egg-info\"]",
        "exclude_path_prefixes = []",
        "non_source_path_prefixes = []",
        "max_scan_lines = 80",
        &format!("text_index_max_bytes = {DEFAULT_TEXT_INDEX_MAX_BYTES}"),
        "",
        "[scan.language_overrides]",
        "",
        "[purpose]",
        "default_style = \"line-comment\"",
        "line_comment_prefixes = [\"//\", \"#\", \"--\", \";\"]",
        "",
        "[purpose.styles_by_extension]",
        "\".rs\" = \"line-comment\"",
        "",
        "[summary_rules]",
        "ascii_only = true",
        "no_commas = true",
        "max_length = 140",
        "",
        "[untracked]",
        "allowed_filenames = []",
        "allowlist_dir_prefixes = [\".githooks\"]",
        "allowlist_files = []",
        "asset_allowed_prefixes = []",
        "asset_extensions = [\".png\", \".jpg\", \".jpeg\", \".svg\", \".gif\", \".webp\", \".ico\", \".pdf\"]",
        "",
    ]
    .join("\n")
}

/// Return the normal source-extension defaults plus supported document files.
fn default_source_extensions() -> Vec<String> {
    DEFAULT_SOURCE_EXTENSIONS
        .iter()
        .chain(DOCUMENT_SOURCE_EXTENSIONS)
        .map(ToString::to_string)
        .collect()
}

/// Default `.gitignore` text created only by the explicit setup helper.
fn default_gitignore_text() -> String {
    [
        "# ProjectAtlas local runtime state",
        ".projectatlas/*.db",
        ".projectatlas/*.db-*",
        ".projectatlas/*.lock",
        ".projectatlas/graph-stage-*/",
        ".projectatlas/optional-parser-pack.json",
        ".projectatlas/projectatlas.toon",
        ".projectatlas/projectatlas-purpose-review.json",
        ".projectatlas/projectatlas.mcp.json",
        ".projectatlas/projectatlas.claude.mcp.json",
        ".projectatlas/projectatlas.opencode.json",
        "",
    ]
    .join("\n")
}

/// Render string values as a TOML array.
fn toml_array(values: &[&str]) -> String {
    let items = values
        .iter()
        .map(|value| format!("\"{value}\""))
        .collect::<Vec<_>>()
        .join(", ");
    format!("[{items}]")
}

impl From<serde_json::Error> for AtlasMapError {
    fn from(source: serde_json::Error) -> Self {
        Self::Io {
            path: PathBuf::from("<json>"),
            source: std::io::Error::other(source),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{
        AtlasMapConfig, AtlasMapError, DEFAULT_TEXT_INDEX_MAX_BYTES, IgnoreEntryKind, MapRecord,
        add_ignore_entry, append_existing_map_purpose_records, append_record_rows, build_snapshot,
        collect_repo_paths, default_config_root_value, enforce_map_response_limit,
        exclude_dir_name_set, extract_block_comment_purpose, extract_line_comment_purpose,
        load_atlas_config_from_text, normalize_repo_string, project_root_for_projectatlas_config,
        remove_ignore_entry, render_map_with_limit, split_record_cells, toon_cell, write_json_map,
    };
    use std::collections::{BTreeMap, BTreeSet};
    use std::error::Error;
    use std::fs;
    use std::io;
    #[cfg(unix)]
    #[test]
    fn initialization_defaults_preserve_ordinary_creation_and_existing_modes()
    -> Result<(), Box<dyn Error>> {
        use std::os::unix::fs::PermissionsExt;
        for relative in [
            None,
            Some(".projectatlas/config.toml"),
            Some("projectatlas.toml"),
        ] {
            let temp = tempfile::tempdir()?;
            let root = temp.path().canonicalize()?;
            let selected = relative.map(|relative| root.join(relative));
            let control = root.join("ordinary-control");
            fs::write(&control, b"ordinary creation control")?;
            let mode = fs::metadata(&control)?.permissions().mode() & 0o777;
            super::init_project_with_config(&root, selected.as_deref())?;
            let config = selected.unwrap_or_else(|| root.join(".projectatlas/config.toml"));
            let nonsource = root.join(".projectatlas/projectatlas-nonsource-files.toon");
            for path in [&config, &nonsource] {
                if fs::metadata(path)?.permissions().mode() & 0o777 != mode {
                    return Err(io::Error::other(format!(
                        "initialization changed ordinary creation mode for {}",
                        path.display()
                    ))
                    .into());
                }
                fs::set_permissions(path, fs::Permissions::from_mode(0o640))?;
            }
            let contents = [fs::read(&config)?, fs::read(&nonsource)?];
            super::init_project_with_config(&root, Some(&config))?;
            for (path, bytes) in [&config, &nonsource].into_iter().zip(contents) {
                if fs::metadata(path)?.permissions().mode() & 0o777 != 0o640
                    || fs::read(path)? != bytes
                {
                    return Err(
                        io::Error::other("reinitialization changed existing defaults").into(),
                    );
                }
            }
        }
        Ok(())
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn initialization_preserves_custom_config_aliases_independently_of_parent()
    -> Result<(), Box<dyn Error>> {
        let mut failures = Vec::new();
        for relative in [
            "custom.toml",
            ".projectatlas/custom.toml",
            ".projectatlas/operator/config.toml",
            "operator/config.toml",
        ] {
            for alias in [false, true] {
                let temp = tempfile::tempdir()?;
                let root = temp.path().join("checkout");
                let selected = root.join(relative);
                let parent = selected
                    .parent()
                    .ok_or_else(|| io::Error::other("custom config has no parent"))?;
                fs::create_dir_all(parent)?;
                let outside = temp.path().join("selected-target.toml");
                let target = if alias {
                    symlink_file(&outside, &selected)?;
                    &outside
                } else {
                    &selected
                };
                let control = target.with_file_name("ordinary-control");
                fs::write(&control, b"ordinary creation control")?;
                if let Err(error) = super::init_project_with_config(&root, Some(&selected)) {
                    failures.push(format!("{relative}, alias={alias}: {error}"));
                    continue;
                }
                let original = fs::read(target)?;
                if original.is_empty()
                    || fs::symlink_metadata(&selected)?.file_type().is_symlink() != alias
                {
                    return Err(io::Error::other(
                        "custom config did not retain its selected entry",
                    )
                    .into());
                }
                #[cfg(unix)]
                {
                    use std::os::unix::fs::PermissionsExt;
                    if fs::metadata(target)?.permissions().mode() & 0o777
                        != fs::metadata(&control)?.permissions().mode() & 0o777
                    {
                        return Err(io::Error::other(
                            "custom config lost ordinary creation permissions",
                        )
                        .into());
                    }
                }
                let permissions = fs::metadata(target)?.permissions();
                super::init_project_with_config(&root, Some(&selected))?;
                if fs::read(target)? != original
                    || fs::metadata(target)?.permissions() != permissions
                {
                    return Err(io::Error::other(
                        "reinitialization changed an existing custom config",
                    )
                    .into());
                }
            }
        }
        if failures.is_empty() {
            Ok(())
        } else {
            Err(io::Error::other(format!(
                "custom config routing depended on its parent: {failures:?}"
            ))
            .into())
        }
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn initialization_admits_explicit_managed_legacy_config_before_outputs()
    -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let root = temp.path().join("checkout");
        fs::create_dir(&root)?;
        let outside = temp.path().join("outside");
        let selected = root.join("projectatlas.toml");
        symlink_file(&outside, &selected)?;
        let result = super::init_project_with_config(&root, Some(&selected));
        if result.is_ok() || outside.exists() || root.join(".projectatlas").exists() {
            return Err(io::Error::other(
                "legacy config creation followed its alias or created other outputs before admission",
            ).into());
        }
        Ok(())
    }

    #[test]
    fn default_map_parent_reduction_never_becomes_an_external_write() -> Result<(), Box<dyn Error>>
    {
        for existing_parent in [false, true] {
            let temp = tempfile::tempdir()?;
            let root = temp.path().join("checkout");
            let state = root.join(".projectatlas");
            fs::create_dir_all(&state)?;
            let missing = state.join("intermediate");
            if existing_parent {
                fs::create_dir(&missing)?;
            }
            let outside = temp.path().join("outside");
            fs::write(&outside, b"outside map bytes")?;
            let sidecar = state.join("projectatlas.json");
            fs::hard_link(&outside, &sidecar)?;
            let mut config = test_config(missing.join("../projectatlas.toon"));
            config.root = root.canonicalize()?;
            let result = write_json_map("{}", &config);
            if result.is_ok() != existing_parent
                || fs::read(&outside)? != b"outside map bytes"
                || missing.exists() != existing_parent
                || (existing_parent && fs::read(&sidecar)? != b"{}")
            {
                return Err(io::Error::other(format!(
                    "default map parent admission failed, existing={existing_parent}: {result:?}",
                ))
                .into());
            }
        }
        Ok(())
    }

    #[cfg(unix)]
    #[test]
    fn automatic_document_mutations_preserve_alias_owners() -> Result<(), Box<dyn Error>> {
        for operation in ["config", "gitignore", "map"] {
            let temp = tempfile::tempdir()?;
            let root = temp.path().join("checkout");
            fs::create_dir(&root)?;
            let root = root.canonicalize()?;
            fs::create_dir(root.join(".projectatlas"))?;
            let outside = temp.path().join("outside");
            let leaf = match operation {
                "config" => root.join(".projectatlas/config.toml"),
                "gitignore" => root.join(".gitignore"),
                _ => root.join(".projectatlas/projectatlas.json"),
            };
            std::os::unix::fs::symlink(&outside, &leaf)?;
            match operation {
                "config" => {
                    if add_ignore_entry(None, &root, IgnoreEntryKind::PathPrefix, "generated")
                        .is_ok()
                    {
                        return Err(
                            io::Error::other("automatic config followed a dangling alias").into(),
                        );
                    }
                }
                "gitignore" => {
                    let report = super::init_gitignore(None, &root)?;
                    if report.created || !report.existed {
                        return Err(io::Error::other(
                            "existing gitignore alias was treated as absent",
                        )
                        .into());
                    }
                }
                _ => {
                    let mut config = test_config(root.join(".projectatlas/projectatlas.toon"));
                    config.root = root.clone();
                    if write_json_map("{}", &config).is_ok() {
                        return Err(
                            io::Error::other("automatic JSON sidecar followed an alias").into()
                        );
                    }
                }
            }
            if outside.exists() || !fs::symlink_metadata(&leaf)?.file_type().is_symlink() {
                return Err(io::Error::other(
                    "refusal changed an outside target or existing alias",
                )
                .into());
            }
        }
        Ok(())
    }

    #[test]
    fn automatic_document_replacement_preserves_hardlinked_targets() -> Result<(), Box<dyn Error>> {
        for operation in ["config", "map"] {
            let temp = tempfile::tempdir()?;
            let root = temp.path().join("checkout");
            fs::create_dir(&root)?;
            let root = root.canonicalize()?;
            fs::create_dir(root.join(".projectatlas"))?;
            let outside = temp.path().join("outside");
            let original = if operation == "config" {
                super::default_config_text()
            } else {
                "outside data".to_string()
            };
            fs::write(&outside, original.as_bytes())?;
            let leaf = root.join(if operation == "config" {
                ".projectatlas/config.toml"
            } else {
                ".projectatlas/projectatlas.json"
            });
            fs::hard_link(&outside, &leaf)?;
            if operation == "config" {
                add_ignore_entry(None, &root, IgnoreEntryKind::PathPrefix, "generated")?;
            } else {
                let mut config = test_config(root.join(".projectatlas/projectatlas.toon"));
                config.root = root;
                write_json_map("{}", &config)?;
            }
            if fs::read(&outside)? != original.as_bytes() || fs::read(&leaf)? == original.as_bytes()
            {
                return Err(io::Error::other(
                    "document mutation changed its outside hardlink owner",
                )
                .into());
            }
        }
        Ok(())
    }

    #[cfg(unix)]
    #[test]
    fn initialization_refuses_indirect_state_before_creating_outputs() -> Result<(), Box<dyn Error>>
    {
        let temp = tempfile::tempdir()?;
        let root = temp.path().join("checkout");
        let outside = temp.path().join("outside");
        fs::create_dir(&root)?;
        fs::create_dir(&outside)?;
        std::os::unix::fs::symlink(&outside, root.join(".projectatlas"))?;
        let result = super::init_project_with_config(&root, None);
        if result.is_ok() || fs::read_dir(&outside)?.next().is_some() {
            return Err(
                io::Error::other("indirect automatic state was admitted or written").into(),
            );
        }
        Ok(())
    }

    #[cfg(unix)]
    use std::os::unix::fs::symlink as symlink_file;
    #[cfg(windows)]
    use std::os::windows::fs::symlink_file;
    use std::path::Path;

    fn test_config(map_path: std::path::PathBuf) -> AtlasMapConfig {
        let root = map_path.parent().map_or_else(
            || std::path::PathBuf::from("."),
            std::path::Path::to_path_buf,
        );
        AtlasMapConfig {
            root: root.clone(),
            map_path,
            nonsource_files_path: root.join("projectatlas-nonsource-files.toon"),
            purpose_filename: ".purpose".to_string(),
            source_extensions: BTreeSet::new(),
            exclude_dir_names: BTreeSet::new(),
            exclude_dir_suffixes: BTreeSet::new(),
            exclude_path_prefixes: BTreeSet::new(),
            non_source_path_prefixes: BTreeSet::new(),
            language_overrides: BTreeMap::new(),
            allowed_untracked_filenames: BTreeSet::new(),
            untracked_allowlist_dir_prefixes: BTreeSet::new(),
            untracked_allowlist_files: BTreeSet::new(),
            asset_allowed_prefixes: BTreeSet::new(),
            asset_extensions: BTreeSet::new(),
            db_path: root.join("projectatlas.db"),
            max_scan_lines: 80,
            text_index_max_bytes: DEFAULT_TEXT_INDEX_MAX_BYTES,
            summary_max_length: 140,
            summary_ascii_only: true,
            summary_no_commas: true,
            purpose_styles: BTreeMap::new(),
            purpose_default_style: "line-comment".to_string(),
            line_comment_prefixes: vec!["//".to_string()],
        }
    }

    #[test]
    fn json_sidecar_never_aliases_custom_legacy_json_path() -> Result<(), Box<dyn Error>> {
        for (name, sidecar) in [
            ("legacy.json", "legacy.json.json"),
            ("legacy.JSON", "legacy.JSON.json"),
            ("legacy.toon", "legacy.json"),
        ] {
            let temp = tempfile::tempdir()?;
            let legacy = temp.path().join(name);
            fs::write(&legacy, "legacy purpose input")?;
            write_json_map("{\"files\":[]}", &test_config(legacy.clone()))?;
            if fs::read_to_string(&legacy)? != "legacy purpose input"
                || fs::read_to_string(temp.path().join(sidecar))? != "{\"files\":[]}"
            {
                return Err(io::Error::other(format!(
                    "JSON sidecar overwrote the legacy map for {name}"
                ))
                .into());
            }
        }
        Ok(())
    }

    #[test]
    fn json_sidecar_refuses_hard_link_without_changing_legacy_import() -> Result<(), Box<dyn Error>>
    {
        let temp = tempfile::tempdir()?;
        let legacy = temp.path().join("legacy.toon");
        let sidecar = temp.path().join("legacy.json");
        fs::write(&legacy, "legacy purpose input")?;
        fs::hard_link(&legacy, &sidecar)?;
        if !matches!(
            write_json_map("{\"files\":[]}", &test_config(legacy.clone())),
            Err(AtlasMapError::Io { source, .. }) if source.kind() == io::ErrorKind::InvalidInput
        ) {
            return Err(io::Error::other("JSON sidecar did not refuse a legacy hard link").into());
        }
        if fs::read_to_string(&legacy)? != "legacy purpose input"
            || fs::read_to_string(&sidecar)? != "legacy purpose input"
        {
            return Err(io::Error::other("JSON sidecar changed the hard-linked legacy map").into());
        }
        Ok(())
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn json_sidecar_refuses_symlink_without_changing_legacy_import() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let legacy = temp.path().join("legacy.toon");
        let sidecar = temp.path().join("legacy.json");
        fs::write(&legacy, "legacy purpose input")?;
        let linked = symlink_file(&legacy, &sidecar);
        #[cfg(windows)]
        if matches!(&linked, Err(source) if source.raw_os_error() == Some(1314)) {
            return Ok(());
        }
        linked?;
        if !matches!(
            write_json_map("{\"files\":[]}", &test_config(legacy.clone())),
            Err(AtlasMapError::Io { source, .. }) if source.kind() == io::ErrorKind::InvalidInput
        ) {
            return Err(io::Error::other("JSON sidecar did not refuse a legacy symlink").into());
        }
        if fs::read_to_string(&legacy)? != "legacy purpose input"
            || !fs::symlink_metadata(&sidecar)?.file_type().is_symlink()
        {
            return Err(io::Error::other("JSON sidecar changed the symlinked legacy map").into());
        }
        Ok(())
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn json_sidecar_refuses_dangling_legacy_symlink_before_creation() -> Result<(), Box<dyn Error>>
    {
        let temp = tempfile::tempdir()?;
        let legacy = temp.path().join("legacy.toon");
        let sidecar = temp.path().join("legacy.json");
        let linked = symlink_file(&sidecar, &legacy);
        #[cfg(windows)]
        if matches!(&linked, Err(source) if source.raw_os_error() == Some(1314)) {
            return Ok(());
        }
        linked?;
        if !matches!(
            write_json_map("{\"files\":[]}", &test_config(legacy.clone())),
            Err(AtlasMapError::Io { source, .. }) if source.kind() == io::ErrorKind::InvalidInput
        ) {
            return Err(
                io::Error::other("JSON sidecar did not refuse a dangling legacy symlink").into(),
            );
        }
        if fs::symlink_metadata(&sidecar).is_ok() || fs::read_link(&legacy)? != sidecar {
            return Err(io::Error::other("JSON sidecar mutated a dangling legacy symlink").into());
        }
        Ok(())
    }

    #[test]
    fn json_sidecar_update_preserves_existing_file_identity() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let sidecar = temp.path().join("legacy.json");
        fs::write(&sidecar, "old")?;
        let identity = same_file::Handle::from_path(&sidecar)?;
        write_json_map("new", &test_config(temp.path().join("legacy.toon")))?;
        if same_file::Handle::from_path(&sidecar)? != identity
            || fs::read_to_string(&sidecar)? != "new"
        {
            return Err(io::Error::other("JSON sidecar replacement changed file identity").into());
        }
        Ok(())
    }

    #[test]
    fn map_response_limit_refuses_complete_oversize_content() -> Result<(), Box<dyn Error>> {
        enforce_map_response_limit("abcd", 4)?;
        if !matches!(
            enforce_map_response_limit("abcde", 4),
            Err(AtlasMapError::ResponseLimitExceeded {
                observed: 5,
                limit: 4
            })
        ) {
            return Err(io::Error::other("map response limit did not report exact bytes").into());
        }
        let temp = tempfile::tempdir()?;
        let map_path = temp.path().join("projectatlas.toon");
        let config = test_config(map_path.clone());
        fs::write(
            temp.path().join("source.rs"),
            "// Purpose: Map budget fixture.\n",
        )?;
        if !matches!(
            render_map_with_limit(&config, false, true, 1),
            Err(AtlasMapError::ResponseLimitExceeded { limit: 1, .. })
        ) || map_path.exists()
            || map_path.with_extension("json").exists()
        {
            return Err(io::Error::other(
                "oversized map response wrote a file or lost its typed refusal",
            )
            .into());
        }
        Ok(())
    }

    #[test]
    fn document_map_records_preserve_purposes_without_reading_binary_headers()
    -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let config = test_config(temp.path().join("projectatlas.toon"));
        for path in ["guide.pdf", "guide.DOCX", "approved.docx"] {
            fs::write(temp.path().join(path), b"\xff\xfe binary document")?;
        }
        fs::write(
            temp.path().join("lib.rs"),
            "// Purpose: Explain source ownership.\n",
        )?;
        let files = ["guide.pdf", "guide.DOCX", "approved.docx", "lib.rs"].map(str::to_owned);
        let purposes = BTreeMap::from([(
            "approved.docx".to_owned(),
            "Explain document ownership.".to_owned(),
        )]);
        let (records, missing, invalid) = super::build_file_records(&files, &config, &purposes)?;
        let actual = records
            .iter()
            .map(|record| {
                (
                    record.path.as_str(),
                    record.summary.as_str(),
                    record.source.as_str(),
                )
            })
            .collect::<Vec<_>>();
        if missing != ["guide.pdf", "guide.DOCX"]
            || !invalid.is_empty()
            || actual
                != [
                    ("guide.pdf", "MISSING", "missing"),
                    ("guide.DOCX", "MISSING", "missing"),
                    ("approved.docx", "Explain document ownership.", "database"),
                    ("lib.rs", "Explain source ownership.", "header"),
                ]
        {
            return Err(io::Error::other("map changed binary or text purpose ownership").into());
        }
        fs::write(temp.path().join("invalid.rs"), b"\xff")?;
        if super::build_file_records(&["invalid.rs".to_owned()], &config, &purposes).is_ok() {
            return Err(io::Error::other("map accepted invalid UTF-8 source headers").into());
        }
        Ok(())
    }

    #[test]
    fn document_map_headers_follow_scanner_language_overrides() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        for (path, overrides, text_header) in [
            ("guide.pdf", vec![(".pdf", "rust")], true),
            ("guide.DOCX", vec![(".docx", "rust")], true),
            ("guide.rs", vec![(".rs", "pdf")], false),
            ("guide.rs", vec![("guide.rs", "docx")], false),
            (
                "guide.pdf",
                vec![(".pdf", "pdf"), ("guide.pdf", "rust")],
                true,
            ),
            (
                "guide.text.pdf",
                vec![(".pdf", "pdf"), (".text.pdf", "rust")],
                true,
            ),
        ] {
            let mut config = test_config(temp.path().join("projectatlas.toon"));
            config.language_overrides = overrides
                .into_iter()
                .map(|(selector, language)| (selector.to_owned(), language.to_owned()))
                .collect();
            fs::write(
                temp.path().join(path),
                if text_header {
                    b"// Purpose: Explain configured source ownership.\n".as_slice()
                } else {
                    b"\xff\xfe binary document"
                },
            )?;
            let (records, missing, invalid) =
                super::build_file_records(&[path.to_owned()], &config, &BTreeMap::new())?;
            let expected = if text_header {
                "Explain configured source ownership."
            } else {
                "MISSING"
            };
            if records.len() != 1
                || records[0].summary != expected
                || missing.is_empty() != text_header
                || !invalid.is_empty()
            {
                return Err(io::Error::other(format!(
                    "map ignored language override for {path}: {records:?}"
                ))
                .into());
            }
        }
        Ok(())
    }

    #[test]
    fn exclude_dir_names_preserve_required_internal_excludes() {
        let names = exclude_dir_name_set(Some(vec!["target".to_string()]));

        assert!(names.contains("target"));
        assert!(names.contains(".git"));
        assert!(names.contains(".projectatlas"));
    }

    #[test]
    fn inverse_ignore_edits_restore_original_config_bytes() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let atlas = temp.path().join(".projectatlas");
        fs::create_dir(&atlas)?;
        let config_path = atlas.join("config.toml");
        let original = r#"[project]
root = "."

[scan]
# Preserve this formatting and comment.
exclude_dir_names = [
    "",
    "   ",
    ".git",
    ".projectatlas",
    "target",
]
exclude_path_prefixes = ["", "  "]
"#;
        fs::write(&config_path, original)?;

        for (kind, value, remove_kind) in [
            (
                IgnoreEntryKind::DirName,
                "temporary-cache",
                Some(IgnoreEntryKind::DirName),
            ),
            (
                IgnoreEntryKind::PathPrefix,
                "generated/cache",
                Some(IgnoreEntryKind::PathPrefix),
            ),
            (IgnoreEntryKind::DirName, "temporary-untyped", None),
            (IgnoreEntryKind::PathPrefix, "generated/untyped", None),
        ] {
            let added = add_ignore_entry(Some(&config_path), temp.path(), kind, value)?;
            if !added.changed {
                return Err(io::Error::other("ignore add did not change the config").into());
            }
            let removed = remove_ignore_entry(Some(&config_path), temp.path(), remove_kind, value)?;
            if !removed.changed || fs::read_to_string(&config_path)? != original {
                return Err(io::Error::other(
                    "inverse ignore edits did not restore the original config bytes",
                )
                .into());
            }
        }
        for result in [
            add_ignore_entry(
                Some(&config_path),
                temp.path(),
                IgnoreEntryKind::DirName,
                " ",
            )
            .map(|_| ()),
            remove_ignore_entry(
                Some(&config_path),
                temp.path(),
                Some(IgnoreEntryKind::PathPrefix),
                "",
            )
            .map(|_| ()),
            remove_ignore_entry(Some(&config_path), temp.path(), None, " ").map(|_| ()),
        ] {
            if result.is_ok() || fs::read_to_string(&config_path)? != original {
                return Err(
                    io::Error::other("invalid blank ignore mutation changed the config").into(),
                );
            }
        }
        Ok(())
    }

    #[test]
    fn config_normalizes_validated_language_overrides() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let path = temp.path().join(".projectatlas").join("config.toml");
        let config = load_atlas_config_from_text(
            &path,
            r#"
[project]
root = "."

[scan.language_overrides]
".D.TS" = "ts"
"Cargo.toml" = "py"
"#,
        )?;
        if config.language_overrides.get(".d.ts").map(String::as_str) != Some("typescript") {
            return Err(io::Error::other("compound extension override was not normalized").into());
        }
        if config
            .language_overrides
            .get("Cargo.toml")
            .map(String::as_str)
            != Some("python")
        {
            return Err(io::Error::other("exact filename override was not normalized").into());
        }
        if config.scan_options().language_overrides != config.language_overrides {
            return Err(io::Error::other("scanner did not receive language overrides").into());
        }
        Ok(())
    }

    #[test]
    fn config_extends_only_the_exact_generated_source_extension_list() -> Result<(), Box<dyn Error>>
    {
        let temp = tempfile::tempdir()?;
        let path = temp.path().join(".projectatlas").join("config.toml");
        let legacy = super::DEFAULT_SOURCE_EXTENSIONS.to_vec();
        let mut reordered = legacy.clone();
        reordered.reverse();
        for (extensions, documents) in [
            (legacy, true),
            (vec![".rs"], false),
            (reordered, false),
            (Vec::new(), false),
        ] {
            let text = format!(
                "[project]\nroot = \".\"\n[scan]\nsource_extensions = {}\n",
                serde_json::to_string(&extensions)?
            );
            let config = load_atlas_config_from_text(&path, &text)?;
            if config.source_extensions.contains(".pdf") != documents
                || config.source_extensions.contains(".docx") != documents
                || (!documents
                    && config.source_extensions
                        != extensions
                            .iter()
                            .map(|value| value.to_ascii_lowercase())
                            .collect())
            {
                return Err(io::Error::other(format!(
                    "legacy defaults or custom extension policy changed incorrectly: documents={documents}, input={extensions:?}, actual={:?}", config.source_extensions,
                ))
                .into());
            }
        }
        Ok(())
    }

    #[test]
    fn config_root_uses_one_canonical_database_identity() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let nested = temp.path().join("nested");
        fs::create_dir(&nested)?;
        let config_path = nested.join("..").join(".projectatlas").join("config.toml");

        let config = load_atlas_config_from_text(&config_path, "[project]\nroot = \".\"\n")?;
        let expected_root = temp.path().canonicalize()?;

        let expected_database = expected_root.join(".projectatlas").join("projectatlas.db");
        if config.root != expected_root || config.db_path != expected_database {
            return Err(io::Error::other(format!(
                "config did not share one canonical database identity: {config:?}"
            ))
            .into());
        }
        Ok(())
    }

    #[cfg(unix)]
    #[test]
    fn effective_config_report_does_not_replace_native_root_bytes() -> Result<(), Box<dyn Error>> {
        use std::ffi::OsString;
        use std::os::unix::ffi::OsStringExt;

        let temp = tempfile::tempdir()?;
        let raw_root = temp.path().join(OsString::from_vec(b"repo-\x80".to_vec()));
        fs::create_dir(&raw_root)?;
        let config = super::load_atlas_config_for_root(&raw_root)?;
        let report = super::effective_config_report(&config);
        let value = serde_json::to_value(report)?;
        if value.get("root") != Some(&serde_json::Value::Null)
            || value.get("map_path") != Some(&serde_json::Value::Null)
            || value.get("db_path") != Some(&serde_json::Value::Null)
            || value.to_string().contains("repo-�")
        {
            return Err(io::Error::other(
                "effective config report exposed a lossy native root projection",
            )
            .into());
        }
        Ok(())
    }

    #[test]
    fn config_rejects_unknown_language_override_target() {
        let result = load_atlas_config_from_text(
            Path::new(".projectatlas/config.toml"),
            r#"
[scan.language_overrides]
".rs" = "not-a-language"
"#,
        );
        assert!(matches!(
            result,
            Err(AtlasMapError::InvalidLanguageOverride { .. })
        ));
    }

    #[test]
    fn toon_record_rows_escape_commas_quotes_and_newlines() {
        let mut lines = Vec::new();
        append_record_rows(
            &mut lines,
            "files",
            &[MapRecord {
                path: "docs/a,b.md".to_string(),
                summary: "Explain \"quoted\"\nsummary".to_string(),
                source: "source".to_string(),
            }],
        );

        assert_eq!(lines[0], "files[1]{path,summary,source}:");
        assert_eq!(
            lines[1],
            "  \"docs/a,b.md\",\"Explain \\\"quoted\\\"\\nsummary\",source"
        );
    }

    #[test]
    fn toon_record_parser_accepts_quoted_and_legacy_cells() {
        assert_eq!(
            split_record_cells("\"docs/a,b.md\",\"Summary, with comma\",source"),
            vec![
                "docs/a,b.md".to_string(),
                "Summary, with comma".to_string(),
                "source".to_string()
            ]
        );
        assert_eq!(
            split_record_cells("logo.png,Demo asset"),
            vec!["logo.png".to_string(), "Demo asset".to_string()]
        );
    }

    #[test]
    fn simple_toon_cells_remain_unquoted() {
        assert_eq!(toon_cell("src/main.rs"), "src/main.rs");
        assert_eq!(toon_cell("Plain summary"), "Plain summary");
    }

    #[test]
    fn line_comment_purpose_skips_yaml_frontmatter() -> Result<(), Box<dyn std::error::Error>> {
        let lines = [
            "---",
            "name: projectatlas",
            "description: Skill frontmatter must stay first.",
            "---",
            "",
            "# Purpose: Guide agents through ProjectAtlas workflows.",
            "",
            "# ProjectAtlas",
        ]
        .iter()
        .map(ToString::to_string)
        .collect::<Vec<_>>();
        let prefixes = vec!["#".to_string(), "//".to_string()];

        let (purpose, issues) = extract_line_comment_purpose(&lines, 80, &prefixes);

        if !issues.is_empty() {
            return Err(
                std::io::Error::other(format!("unexpected purpose issues: {issues:?}")).into(),
            );
        }
        if purpose.as_deref() != Some("Guide agents through ProjectAtlas workflows.") {
            return Err(std::io::Error::other(format!(
                "frontmatter purpose mismatch: {purpose:?}"
            ))
            .into());
        }
        Ok(())
    }

    #[test]
    fn block_comment_purpose_skips_php_open_tag() -> Result<(), Box<dyn std::error::Error>> {
        let lines = ["<?php", "/*", "Purpose: Render legacy PHP page.", "*/"]
            .iter()
            .map(ToString::to_string)
            .collect::<Vec<_>>();

        let (purpose, issues) = extract_block_comment_purpose(&lines, 80);

        if !issues.is_empty() {
            return Err(
                std::io::Error::other(format!("unexpected purpose issues: {issues:?}")).into(),
            );
        }
        if purpose.as_deref() != Some("Render legacy PHP page.") {
            return Err(
                std::io::Error::other(format!("PHP block purpose mismatch: {purpose:?}")).into(),
            );
        }
        Ok(())
    }

    #[test]
    fn custom_nonsource_registry_is_not_classified_as_source()
    -> Result<(), Box<dyn std::error::Error>> {
        let temp = tempfile::tempdir()?;
        let root = temp.path();
        std::fs::create_dir(root.join("src"))?;
        std::fs::write(
            root.join("src").join("live.toon"),
            "Purpose: Live TOON source.\n",
        )?;
        std::fs::write(
            root.join("src").join("projectatlas-nonsource-files.toon"),
            "nonsource_files[]:\n",
        )?;
        let mut config = test_config(root.join("projectatlas.toon"));
        config.nonsource_files_path = root.join("src").join("projectatlas-nonsource-files.toon");
        config.source_extensions.insert(".toon".to_string());

        let paths = collect_repo_paths(&config)?;

        if paths
            .source_files
            .iter()
            .any(|path| path == "src/projectatlas-nonsource-files.toon")
        {
            return Err(std::io::Error::other("custom non-source registry was source").into());
        }
        if !paths
            .source_files
            .iter()
            .any(|path| path == "src/live.toon")
        {
            return Err(std::io::Error::other("sibling TOON source was skipped").into());
        }
        Ok(())
    }

    #[test]
    fn repo_metadata_paths_reject_parent_traversal_and_absolute_paths()
    -> Result<(), Box<dyn std::error::Error>> {
        if normalize_repo_string("../outside.txt").is_ok() {
            return Err(std::io::Error::other("parent traversal was accepted").into());
        }
        if normalize_repo_string("C:/outside.txt").is_ok() {
            return Err(std::io::Error::other("absolute Windows path was accepted").into());
        }
        let normalized = normalize_repo_string("docs\\guide.md")?;
        if normalized != "docs/guide.md" {
            return Err(
                std::io::Error::other(format!("normalized path mismatch: {normalized}")).into(),
            );
        }
        Ok(())
    }

    #[test]
    fn bare_projectatlas_config_path_resolves_root_to_cwd() {
        let cwd = std::path::Path::new("repo");
        assert_eq!(
            project_root_for_projectatlas_config(
                Some(std::path::Path::new(".projectatlas/config.toml")),
                cwd,
            ),
            cwd
        );
        assert_eq!(
            project_root_for_projectatlas_config(
                Some(std::path::Path::new("./.projectatlas/config.toml")),
                cwd,
            ),
            cwd
        );
    }

    #[test]
    fn default_init_config_root_points_from_subdir_back_to_repo()
    -> Result<(), Box<dyn std::error::Error>> {
        let temp = tempfile::tempdir()?;
        let root = temp.path();
        let config_dir = root.join("config").join("atlas");
        std::fs::create_dir_all(&config_dir)?;

        let cases = [
            (root.join(".projectatlas").join("config.toml"), "."),
            (root.join("projectatlas.toml"), "."),
            (root.join("config").join("projectatlas.toml"), ".."),
            (config_dir.join("projectatlas.toml"), "../.."),
        ];
        for (config_path, expected_root) in cases {
            let actual_root = default_config_root_value(root, &config_path)?;
            if actual_root != expected_root {
                return Err(std::io::Error::other(format!(
                    "default config root mismatch for {config_path:?}: expected {expected_root}, got {actual_root}"
                ))
                .into());
            }
        }
        // A conventional basename in another project does not select its root.
        let external = tempfile::tempdir()?;
        let external_config = external.path().join(".projectatlas/config.toml");
        std::fs::create_dir_all(
            external_config
                .parent()
                .ok_or_else(|| std::io::Error::other("external config fixture has no parent"))?,
        )?;
        let text = super::default_config_text_for(root, &external_config)?;
        if load_atlas_config_from_text(&external_config, &text)?.root != root.canonicalize()? {
            return Err(
                io::Error::other("external private config changed the selected root").into(),
            );
        }
        Ok(())
    }

    #[test]
    fn relative_config_roots_follow_native_private_directory_names() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let root = temp.path();
        fs::create_dir(root.join(".projectatlas"))?;
        #[cfg(not(windows))]
        let names = [".PROJECTATLAS", ".projectatlas\u{200d}"];
        #[cfg(windows)]
        let names = [
            ".PROJECTATLAS",
            ".projectatlas\u{200d}",
            ".projectatlas.",
            ".projectatlas ",
        ];
        for name in names {
            let directory = root.join(name);
            let aliases = directory.try_exists()?;
            if !aliases {
                fs::create_dir(&directory)?;
            }
            let config = directory.join("config.toml");
            let actual = load_atlas_config_from_text(&config, "[project]\nroot = \".\"\n")?;
            if actual.root != if aliases { root } else { &directory }.canonicalize()? {
                return Err(io::Error::other(format!(
                    "relative config root ignored native directory spelling: {name}"
                ))
                .into());
            }
            if aliases {
                let absent = load_atlas_config_from_text(&config, "[project]\n")?;
                if absent.root != root.canonicalize()?
                    || default_config_root_value(root, &config)? != "."
                {
                    return Err(io::Error::other(
                        "private config root inference disagreed with creation",
                    )
                    .into());
                }
            }
        }
        #[cfg(windows)]
        for name in [".projectatlas.", ".projectatlas "] {
            // canonicalize supplies a verbatim prefix, making these actual
            // distinct directory entries rather than ordinary Win32 aliases.
            let literal = root.canonicalize()?.join(name);
            fs::create_dir(&literal)?;
            let config = literal.join("config.toml");
            let actual = load_atlas_config_from_text(&config, "[project]\nroot = \".\"\n")?;
            if actual.root != literal.canonicalize()? {
                return Err(io::Error::other(
                    "literal private-looking directory changed config root semantics",
                )
                .into());
            }
            let text = super::default_config_text_for(root, &config)?;
            if load_atlas_config_from_text(&config, &text)?.root != root.canonicalize()? {
                return Err(io::Error::other(
                    "literal custom config initialization lost the requested root",
                )
                .into());
            }
        }
        Ok(())
    }

    #[cfg(windows)]
    #[test]
    fn external_config_preserves_absolute_volume_guid_root() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let root = Path::new(r"\\?\Volume{12345678-1234-1234-1234-123456789abc}\repo");
        let config_path = temp.path().join("external").join("projectatlas.toml");

        let text = super::default_config_text_for(root, &config_path)?;
        let expected = root
            .to_str()
            .ok_or_else(|| io::Error::other("synthetic volume-GUID root was not UTF-8"))?;
        let parsed = toml::from_str::<toml::Value>(&text)?;
        let decoded = parsed
            .get("project")
            .and_then(toml::Value::as_table)
            .and_then(|project| project.get("root"))
            .and_then(toml::Value::as_str)
            .ok_or_else(|| io::Error::other("generated volume-GUID root was not a TOML string"))?;
        if !Path::new(decoded).is_absolute() || decoded != expected {
            return Err(io::Error::other(format!(
                "generated volume-GUID root lost its absolute native spelling: {decoded:?}"
            ))
            .into());
        }
        let escaped = expected.replace('\\', "\\\\");
        if !text.contains(&format!("root = \"{escaped}\"")) {
            return Err(io::Error::other("generated volume-GUID root was not TOML-escaped").into());
        }
        Ok(())
    }

    #[cfg(windows)]
    #[test]
    fn reports_preserve_absolute_volume_guid_paths() -> Result<(), Box<dyn Error>> {
        let root = Path::new(r"\\?\Volume{12345678-1234-1234-1234-123456789abc}\repo");
        let config_path = root.join(".projectatlas").join("config.toml");
        let map_path = root.join(".projectatlas").join("projectatlas.toon");
        let nonsource_path = root
            .join(".projectatlas")
            .join("projectatlas-nonsource-files.toon");
        let database_path = root.join(".projectatlas").join("projectatlas.db");
        let mut config = test_config(map_path.clone());
        config.root = root.to_path_buf();
        config.nonsource_files_path = nonsource_path;
        config.db_path = database_path;
        let expected = |path: &Path| path.to_str().map(ToOwned::to_owned);

        let effective = super::effective_config_report(&config);
        if effective.map_path != expected(&map_path)
            || effective.nonsource_files_path != expected(&config.nonsource_files_path)
            || effective.db_path != expected(&config.db_path)
        {
            return Err(io::Error::other(format!(
                "effective config report changed the volume-GUID spelling: {effective:?}"
            ))
            .into());
        }

        let ignore = super::ignore_list_report(&config_path, &config);
        if ignore.config_path != expected(&config_path)
            || ignore.gitignore_path != expected(&root.join(".gitignore"))
        {
            return Err(io::Error::other(format!(
                "ignore list report changed the volume-GUID spelling: {ignore:?}"
            ))
            .into());
        }
        let mutation =
            super::ignore_mutation_report(&config_path, "add", "dir-name", "target", true, &config);
        if mutation.config_path != expected(&config_path)
            || mutation.gitignore_path != expected(&root.join(".gitignore"))
        {
            return Err(io::Error::other(format!(
                "ignore mutation report changed the volume-GUID spelling: {mutation:?}"
            ))
            .into());
        }

        if super::effective_config_path_display(Path::new(r"\\?\C:\repo\file"))
            != Some(r"C:\repo\file".to_string())
            || super::effective_config_path_display(Path::new(r"\\?\UNC\server\share\repo\file"))
                != Some(r"\\server\share\repo\file".to_string())
        {
            return Err(io::Error::other(
                "ordinary extended drive or UNC display was not normalized",
            )
            .into());
        }
        Ok(())
    }

    #[cfg(windows)]
    #[test]
    fn external_config_preserves_verbatim_drive_root() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let root = Path::new(r"\\?\C:\repo\folder.");
        let config_path = temp.path().join("external").join("projectatlas.toml");
        let text = super::default_config_text_for(root, &config_path)?;
        let expected = root
            .to_str()
            .ok_or_else(|| io::Error::other("synthetic verbatim root was not UTF-8"))?;
        let parsed = toml::from_str::<toml::Value>(&text)?;
        let decoded = parsed
            .get("project")
            .and_then(toml::Value::as_table)
            .and_then(|project| project.get("root"))
            .and_then(toml::Value::as_str)
            .ok_or_else(|| io::Error::other("generated verbatim root was not a TOML string"))?;
        if !Path::new(decoded).is_absolute() || decoded != expected {
            return Err(io::Error::other(format!(
                "generated verbatim root changed its absolute spelling: {decoded:?}"
            ))
            .into());
        }
        let escaped = expected.replace('\\', "\\\\");
        if !text.contains(&format!("root = \"{escaped}\"")) {
            return Err(io::Error::other("generated verbatim root was not TOML-escaped").into());
        }
        Ok(())
    }

    #[cfg(unix)]
    #[test]
    fn external_config_through_symlink_preserves_canonical_project_root()
    -> Result<(), Box<dyn Error>> {
        use std::os::unix::fs::symlink;

        let temp = tempfile::tempdir()?;
        let root = temp.path().join("repo");
        let outside = temp.path().join("outside");
        fs::create_dir(&root)?;
        fs::create_dir(&outside)?;
        symlink(&outside, root.join("link"))?;

        let config_path = root.join("link").join("nested").join("projectatlas.toml");
        super::init_project_with_config(&root, Some(&config_path))?;

        let config = super::load_atlas_config(Some(&config_path))?;
        let expected_root = root.canonicalize()?;
        if config.root != expected_root {
            return Err(io::Error::other(format!(
                "symlinked external config selected {:?}, expected {expected_root:?}",
                config.root
            ))
            .into());
        }
        Ok(())
    }

    #[cfg(unix)]
    #[test]
    fn external_config_preserves_unix_backslash_root() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let root = temp.path().join("repo\\name");
        let config_path = temp.path().join("external").join("projectatlas.toml");
        fs::create_dir(&root)?;

        super::init_project_with_config(&root, Some(&config_path))?;

        let config_text = fs::read_to_string(&config_path)?;
        if !config_text.contains("repo\\\\name") {
            return Err(io::Error::other(
                "external config did not TOML-escape its literal Unix backslash",
            )
            .into());
        }
        let config = super::load_atlas_config(Some(&config_path))?;
        let expected_root = root.canonicalize()?;
        if config.root != expected_root {
            return Err(io::Error::other(format!(
                "external config selected {:?}, expected {expected_root:?}",
                config.root
            ))
            .into());
        }
        Ok(())
    }

    #[cfg(unix)]
    #[test]
    fn external_config_rejects_non_utf8_root_before_writes() -> Result<(), Box<dyn Error>> {
        use std::ffi::OsString;
        use std::os::unix::ffi::OsStringExt;

        let temp = tempfile::tempdir()?;
        let raw_root = temp.path().join(OsString::from_vec(b"repo-\x80".to_vec()));
        let config_parent = temp.path().join("external-config").join("nested");
        let config_path = config_parent.join("projectatlas.toml");
        fs::create_dir(&raw_root)?;

        let result = super::init_project_with_config(&raw_root, Some(&config_path));

        if !matches!(result, Err(AtlasMapError::InvalidRepositoryPath { .. })) {
            return Err(io::Error::other(format!(
                "external config initialization returned an unexpected result: {result:?}"
            ))
            .into());
        }
        if raw_root.join(".projectatlas").exists() || config_parent.exists() || config_path.exists()
        {
            return Err(io::Error::other(
                "external config refusal left project or config filesystem state",
            )
            .into());
        }
        Ok(())
    }

    #[test]
    fn generated_at_is_render_time_not_legacy_snapshot_time() -> Result<(), Box<dyn Error>> {
        let temp = tempfile::tempdir()?;
        let map_path = temp.path().join("projectatlas.toon");
        let config = test_config(map_path.clone());
        let first = build_snapshot(&config)?;
        fs::write(
            &map_path,
            format!(
                "version: 1\ngenerated_at: unix:123\nfile_hash: \"{}\"\nfolder_hash: \"{}\"\n",
                first.file_hash, first.folder_hash
            ),
        )?;
        let second = build_snapshot(&config)?;
        if second.generated_at == "unix:123"
            || !second.generated_at.starts_with("unix:")
            || first.file_hash != second.file_hash
            || first.folder_hash != second.folder_hash
        {
            return Err(
                io::Error::other("map render reused a legacy timestamp or changed hashes").into(),
            );
        }
        Ok(())
    }

    #[test]
    fn existing_map_rows_seed_imported_purposes() -> Result<(), Box<dyn std::error::Error>> {
        let temp = tempfile::tempdir()?;
        let map_path = temp.path().join("projectatlas.toon");
        std::fs::write(
            &map_path,
            [
                "version: 1",
                "folders[1]{path,summary,source}:",
                "  .,Repository root,database",
                "files[2]{path,summary,source}:",
                "  Cargo.toml,Rust workspace manifest,database",
                "  \"docs/a,b.md\",\"Quoted, summary\",database",
                "folder_summary_duplicates[]:",
            ]
            .join("\n"),
        )?;
        let config = test_config(map_path);
        let mut imported = BTreeMap::new();

        append_existing_map_purpose_records(&config, &mut imported)?;

        if imported.get(".").map(String::as_str) != Some("Repository root") {
            return Err(std::io::Error::other("root purpose was not imported").into());
        }
        if imported.get("Cargo.toml").map(String::as_str) != Some("Rust workspace manifest") {
            return Err(std::io::Error::other("Cargo purpose was not imported").into());
        }
        if imported.get("docs/a,b.md").map(String::as_str) != Some("Quoted, summary") {
            return Err(std::io::Error::other("quoted file purpose was not imported").into());
        }
        Ok(())
    }
}