### Install Archive Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_cli/optional_parser_lifecycle.rs.html Handles the installation of a verified archive, including directory setup, platform-specific cleanup checks, and atomic tree sealing. ```rust fn install_archive( &self, archive: &Path, platform: PackPlatform, ) -> Result<(PackSlotIdentity, bool), OptionalParserPackLifecycleError> { #[cfg(test)] self.fail_admission_if_injected(archive)?; self.ensure_storage_roots()?; let versions_root = self.versions_root()?; let mut verified = Self::verify_archive(archive, platform, Some(&versions_root))?; let slot = verified.slot_identity(); let operation = (|| { let version_root = versions_root.join(&slot.projectatlas_version); ensure_direct_directory(&versions_root, &version_root)?; #[cfg(all(target_os = "windows", target_arch = "x86_64"))] if windows_slot_cleanup_in_progress(&version_root, &slot.artifact)? { return Err(invalid_data( "the selected parser-pack artifact still has a cleanup tombstone", )); } let destination = self.slot_path(&slot)?; if self.slot_path_is_real(&slot)? { self.open_verified_installed_slot(&slot)?; return Ok((slot.clone(), false)); } if fs::symlink_metadata(&destination).is_ok() { return Err(invalid_data( "immutable slot path is occupied by a non-directory entry", )); } #[cfg(all(target_os = "linux", target_arch = "x86_64"))] let _publication_staging = { let staging = stage_parser_pack_for_atomic_publication( &mut verified.pack_root, &version_root, )?; verified .temporary_profile .pack_root .clone_from(&verified.pack_root); staging }; if let Err(operation) = seal_immutable_tree(&verified.pack_root) { return finish_with_cleanup( Err(operation), make_tree_writable(&verified.pack_root), ); } match fs::rename(&verified.pack_root, &destination) { Ok(()) => { verified.transfer_profile_to_installed_slot(); Ok((slot.clone(), true)) } Err(source) if source.kind() == io::ErrorKind::AlreadyExists => { make_tree_writable(&verified.pack_root)?; self.open_verified_installed_slot(&slot)?; Ok((slot.clone(), false)) } Err(source) => finish_with_cleanup( Err(io_error( "publish immutable parser-pack slot", destination, source, )), make_tree_writable(&verified.pack_root), ), } })(); let cleanup = verified.cleanup_profile(); finish_with_cleanup(operation, cleanup) } ``` -------------------------------- ### Trim start matches example Source: https://styler-ai.github.io/ProjectAtlas/projectatlas/mcp/struct.McpToolTextResult.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates trimming characters from the start of a string slice. ```rust let x: &[_] = &['1', '2']; assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12"); ``` -------------------------------- ### install Source: https://styler-ai.github.io/ProjectAtlas/projectatlas_cli/optional_parser_lifecycle/struct.OptionalParserPackLifecycle.html?search=u32+-%3E+bool Installs a local archive into an immutable versioned slot. ```APIDOC ## pub fn install(&self, archive: &Path) -> Result ### Description Install one local completed archive into an immutable versioned slot. Installation never enables the slot for this or another project. ``` -------------------------------- ### Initialize CSS Summary Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/structural.rs.html Starts the parsing process for CSS-like stylesheets. ```rust fn css_summary(content: &str) -> Option { let mut input = CssParserInput::new(content); let mut parser = CssParser::new(&mut input); ``` -------------------------------- ### Trim Start Example Source: https://styler-ai.github.io/ProjectAtlas/projectatlas/mcp/struct.McpToolTextResult.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates trimming leading whitespace from a string containing Hebrew characters. ```rust let s = " עברית "; assert!(Some('ע') == s.trim_start().chars().next()); ``` -------------------------------- ### Starting a SourceObservationEntry Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/runtime/source_observation.rs.html Initializes the native watcher and sets up the event pipeline for a source binding. ```rust impl SourceObservationEntry { /// Start a bounded native watcher for one source binding. fn start(binding: SourceBinding) -> Result { let (sender, receiver) = sync_channel(SOURCE_OBSERVATION_QUEUE_CAPACITY); #[cfg(test)] let test_sender = sender.clone(); let ingress_sequence = Arc::new(AtomicU64::new(0)); let continuity_lost = Arc::new(AtomicBool::new(false)); let mut watcher = notify::recommended_watcher(watcher_callback( sender, Arc::clone(&ingress_sequence), Arc::clone(&continuity_lost), )) .map_err(|source| observer_error(&binding.root, &source))?; watcher .watch(&binding.root, RecursiveMode::Recursive) .map_err(|source| observer_error(&binding.root, &source))?; if let Some(config) = binding.config.as_deref() && !config.starts_with(&binding.root) && let Some(parent) = config.parent() { watcher ``` -------------------------------- ### Method Chaining Example Source: https://styler-ai.github.io/ProjectAtlas/projectatlas/mcp/struct.McpToolTextResult.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates chaining trim_prefix and trim_suffix methods. ```rust assert_eq!("".trim_prefix('<').trim_suffix('>'), "https://example.com/"); ``` -------------------------------- ### update Source: https://styler-ai.github.io/ProjectAtlas/projectatlas_cli/optional_parser_lifecycle/struct.OptionalParserPackLifecycle.html?search=u32+-%3E+bool Installs and atomically selects a replacement pack. ```APIDOC ## pub fn update(&self, archive: &Path) -> Result ### Description Install and atomically select a replacement, retaining the previous exact slot. ``` -------------------------------- ### Verify and Install Source Epoch Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/runtime/source_observation.rs.html?search= Performs verification of the source state by comparing publication contracts and policies, then installs a new epoch if the state is consistent. ```rust 597 && !entry.continuity_lost.load(Ordering::Acquire) 598 { 599 let store = open_atlas_store_read_only_for_project( 600 &entry.binding.database, 601 &entry.binding.root, 602 )?; 603 let publication = store.index_publication()?.filter(|publication| { 604 publication.state == IndexPublicationState::Complete 605 && publication.contract_fingerprint.as_deref() 606 == Some(contract_fingerprint.as_str()) 607 }); 608 let captured = store.captured_project_binding()?; 609 work.sqlite_read_statements = work.sqlite_read_statements.saturating_add(1); 610 if publication 611 .is_some_and(|publication| publication.generation == epoch.stamp.generation) 612 && captured.project_instance_id == epoch.stamp.project_instance_id 613 { 614 return Ok((store, epoch)); 615 } 616 entry.invalidate(); 617 drop(store.finish_index_read_snapshot()); 618 } 619 620 for _attempt in 0..VERIFIED_READ_ATTEMPTS { 621 entry.clear_before_exact_verification()?; 622 let before_plan = ScanRuntimePlan::for_path_controlled( 623 entry.binding.config.as_deref(), 624 &entry.binding.root, 625 None, 626 control, 627 ) 628 .map_err(|source| publication_input_error(&entry.binding.root, source))?; 629 let before_contract = before_plan.publication_contract_fingerprint(); 630 let before_policy = source_policy_witness(&before_plan, control)?; 631 let exact = open_exact_fresh_atlas_store_for_project_controlled( 632 &entry.binding.database, 633 &entry.binding.root, 634 entry.binding.config.as_deref(), 635 control, 636 )?; 637 work.add_exact(exact.work); 638 let after_plan = ScanRuntimePlan::for_path_controlled( 639 entry.binding.config.as_deref(), 640 &entry.binding.root, 641 None, 642 control, 643 ) 644 .map_err(|source| publication_input_error(&entry.binding.root, source))?; 645 let after_contract = after_plan.publication_contract_fingerprint(); 646 let after_policy = source_policy_witness(&after_plan, control)?; 647 let changed = entry.changed_since_exact_verification(&after_plan.scan_options)?; 648 if changed || before_contract != after_contract || before_policy != after_policy { 649 drop(exact.store.finish_index_read_snapshot()); 650 continue; 651 } 652 let publication = exact 653 .store 654 .index_publication()? 655 .ok_or_else(|| source_changed_during_derivation(&entry.binding.root, "."))?; 656 let captured = exact.store.captured_project_binding()?; 657 work.sqlite_read_statements = work.sqlite_read_statements.saturating_add(1); 658 let ingress_sequence = entry.ingress_sequence.load(Ordering::Acquire); 659 let epoch = entry.install_epoch( 660 self.process_nonce, 661 &captured, 662 publication.generation, 663 ingress_sequence, 664 after_contract, 665 after_policy, 666 )?; 667 return Ok((exact.store, epoch)); 668 } 669 Err(source_changed_during_derivation(&entry.binding.root, ".")) 670 } ``` -------------------------------- ### enable Source: https://styler-ai.github.io/ProjectAtlas/projectatlas_cli/optional_parser_lifecycle/struct.OptionalParserPackLifecycle.html?search=u32+-%3E+bool Enables an already installed slot for the current project. ```APIDOC ## pub fn enable(&self, artifact: &str) -> Result ### Description Enable an explicitly named already installed slot for the current project. ``` -------------------------------- ### Trim Start Matches Usage Source: https://styler-ai.github.io/ProjectAtlas/projectatlas/mcp/struct.McpToolTextResult.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Shows how to remove specific prefixes matching a pattern. ```rust assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11"); assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123"); ``` -------------------------------- ### Setup Graph Staging and Links Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/runtime/graph_projection.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates creating foreign project stages, repository graph staging databases, and filesystem links for staging directories and databases. ```rust fs::create_dir(&foreign_root)?; let foreign_store = AtlasStore::open_for_project(&foreign_root.join("projectatlas.db"), &foreign_root)?; let foreign_project = foreign_store .project_instance_id()? .ok_or("foreign project identity is missing")?; let foreign_project_stage = atlas_dir.join(format!("{GRAPH_STAGE_DIRECTORY_PREFIX}foreign-project")); fs::create_dir(&foreign_project_stage)?; drop(AtlasStore::create_repository_graph_staging( &foreign_project_stage.join(GRAPH_STAGE_DATABASE_FILE_NAME), &root, foreign_project, )?); let foreign_root_stage = atlas_dir.join(format!("{GRAPH_STAGE_DIRECTORY_PREFIX}foreign-root")); fs::create_dir(&foreign_root_stage)?; drop(AtlasStore::create_repository_graph_staging( &foreign_root_stage.join(GRAPH_STAGE_DATABASE_FILE_NAME), &foreign_root, project, )?); let linked_stage_target = temp.path().join("linked-stage-target"); fs::create_dir(&linked_stage_target)?; fs::write(linked_stage_target.join("sentinel"), "preserve")?; drop(AtlasStore::create_repository_graph_staging( &linked_stage_target.join(GRAPH_STAGE_DATABASE_FILE_NAME), &root, project, )?); let linked_stage = atlas_dir.join(format!("{GRAPH_STAGE_DIRECTORY_PREFIX}linked")); create_directory_link(&linked_stage_target, &linked_stage)?; let linked_database_target = temp.path().join("linked-stage-database.db"); drop(AtlasStore::create_repository_graph_staging( &linked_database_target, &root, project, )?); let linked_database_stage = atlas_dir.join(format!("{GRAPH_STAGE_DIRECTORY_PREFIX}linked-database")); fs::create_dir(&linked_database_stage)?; let linked_database = linked_database_stage.join(GRAPH_STAGE_DATABASE_FILE_NAME); let linked_database_created = match create_file_link(&linked_database_target, &linked_database) { Ok(()) => true, #[cfg(windows)] Err(source) if source.raw_os_error() == Some(1314) => false, Err(source) => return Err(source.into()), }; ``` -------------------------------- ### Initialize Partial Project Structure Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/main.rs.html?search= Sets up a directory structure with a partial .projectatlas configuration for testing. ```rust let partial_repo = temp.path().join("repo-partial-atlas"); fs::create_dir_all(partial_repo.join(".projectatlas"))?; fs::create_dir_all(partial_repo.join("src"))?; fs::write( partial_repo.join("src").join("lib.rs"), "pub fn partial_project_marker() {}\n", )?; let mut partial_index_file_args = Map::new(); partial_index_file_args.insert( "file".to_string(), ``` -------------------------------- ### Get Declaration Body Start Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_symbols/lib.rs.html?search=u32+-%3E+bool Determines the byte offset where the body of a declaration begins. ```rust fn declaration_body_start(node: Node<'_>) -> Option { if declaration_has_direct_callable_initializer(node) && let Some(initializer) = first_declaration_initializer(node) && let Some(body) = initializer.child_by_field_name("body") { return Some(body.start_byte()); } if declaration_kind(node.kind()) == Some(SymbolKind::Value) && let Some(initializer) = first_declaration_initializer(node) { return Some(initializer.start_byte()); } if let Some(body) = node.child_by_field_name("body") { return Some(body.start_byte()); } let mut cursor = node.walk(); node.named_children(&mut cursor) .find(|child| { ``` -------------------------------- ### Initialize Project for Testing Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/runtime/source_observation.rs.html Sets up a temporary project directory with a database and source file for testing scan pipelines. ```rust fs::create_dir_all(root.join(".projectatlas"))?; let source = root.join("source.rs"); fs::write(&source, "fn original() {}\n")?; let database = root.join(".projectatlas").join("projectatlas.db"); let mut store = super::super::open_atlas_store_for_project(&database, root)?; let plan = ScanRuntimePlan::for_path(None, root, None)?; super::super::run_scan_pipeline( &mut store, &plan, &super::super::SymbolBuildOptions::new( super::super::MAX_SYMBOL_FILE_BYTES, Some(1), None, ), )?; drop(store); Ok((database, source)) } ``` -------------------------------- ### Initialize AtlasStore for Project Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/runtime/graph_projection.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Sets up a temporary directory and initializes an AtlasStore instance for a project. ```rust #[test] fn closed_resolution_states_survive_sqlite_publication_and_reopen() -> Result<(), Box> { let temp = tempfile::tempdir()?; let root = temp.path().join("closed-resolution-states"); fs::create_dir_all(&root)?; let database = root.join("projectatlas.db"); let mut store = AtlasStore::open_for_project(&database, &root)?; let project = store .project_instance_id()? .ok_or("bound project identity is missing")?; ``` -------------------------------- ### Build Session Brief Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/mcp.rs.html?search= Constructs a read-only agent startup brief, handling cases where the project index is missing. ```rust fn build_session_brief( &self, params: AtlasSessionBriefParams, context: Option>, ) -> Result { let selected_project_path = params.project_path.clone(); let state = self.state_for_project_path(selected_project_path.clone())?; let query = Self::query_or_empty(params.query); let purpose_task = params .purpose_task .unwrap_or_else(|| MCP_PURPOSE_TASK_SESSION_STARTUP.to_string()); let folder_limit = Self::brief_limit(params.folder_limit); let file_limit = Self::brief_limit(params.file_limit); let blocker_limit = Self::brief_limit(params.blocker_limit); let purpose_limit = Self::brief_limit(params.purpose_limit); let project = Self::selected_project_capability(&state); if !state.db_path.exists() { let init_project_path = Some(normalize_native_path_display(&state.root)); return Ok(McpSessionBrief { project, policy: self.brief_policy(), overview: None, folders: Vec::new(), files: Vec::new(), blockers: McpBriefBlockers { total: 0, returned: 0, truncated: false, items: Vec::new(), }, purpose_handoff: None, recommendations: Self::missing_index_recommendations(init_project_path), limits: McpBriefLimits { folder_limit, file_limit, blocker_limit, purpose_limit, folders_truncated: false, files_truncated: false, purposes_truncated: false, } }); } ``` -------------------------------- ### Setup Partial Atlas Repository Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/main.rs.html Initializes a repository directory structure with a .projectatlas folder and a source file for testing partial indexing. ```rust let partial_repo = temp.path().join("repo-partial-atlas"); fs::create_dir_all(partial_repo.join(".projectatlas"))?; fs::create_dir_all(partial_repo.join("src"))?; fs::write( partial_repo.join("src").join("lib.rs"), "pub fn partial_project_marker() {}\n", )?; ``` -------------------------------- ### Installing Parser Pack Archives Source: https://styler-ai.github.io/ProjectAtlas/projectatlas_cli/optional_parser_lifecycle/struct.OptionalParserPackLifecycle.html Installs a local archive into an immutable versioned slot. ```rust pub fn install( &self, archive: &Path, ) -> Result ``` -------------------------------- ### Archive Verification and Installation Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_cli/optional_parser_lifecycle.rs.html?search=std%3A%3Avec Methods for verifying local archives and installing them into immutable versioned slots. ```rust /// Verify and fixture-probe one local completed archive without installing it. /// /// # Errors /// /// Returns unsupported containment before opening the archive, or an archive, /// manifest, digest, platform, path, bound, or supervisor-admission failure. pub fn verify( &self, archive: &Path, ) -> Result { let platform = self.require_supported()?; #[cfg(all(target_os = "windows", target_arch = "x86_64"))] let _lease = self.acquire_pack_lease(OptionalParserPackLeaseMode::Exclusive)?; #[cfg(test)] self.fail_admission_if_injected(archive)?; let verified = Self::verify_archive(archive, platform, None)?; let artifact = verified.slot_report(false); verified.cleanup_profile()?; Ok(self.report(OptionalParserPackOperation::Verify, false, Some(artifact))) } /// Install one local completed archive into an immutable versioned slot. /// /// Installation never enables the slot for this or another project. /// /// # Errors /// /// Returns unsupported containment before opening the archive or mutating storage, /// or a validation, admission, publication, or filesystem failure. pub fn install( &self, archive: &Path, ) -> Result { let platform = self.require_supported()?; let _lease = self.acquire_pack_lease(OptionalParserPackLeaseMode::Exclusive)?; let (slot, changed) = self.install_archive(archive, platform)?; Ok(self.report( OptionalParserPackOperation::Install, changed, Some(slot.report(true)), )) } ``` -------------------------------- ### Initialize project configuration Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/atlas_map.rs.html?search= Creates default configuration files and directory structures for a new project. ```rust /// 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 { let project_dir = root.join(".projectatlas"); fs::create_dir_all(&project_dir).map_err(|source| AtlasMapError::Io { path: project_dir.clone(), source, })?; 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, ); if !config_path.exists() { 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, })?; } fs::write(&config_path, default_config_text_for(root, &config_path)).map_err(|source| { AtlasMapError::Io { path: config_path.clone(), source, } })?; } let nonsource_path = project_dir.join("projectatlas-nonsource-files.toon"); if !nonsource_path.exists() { fs::write(&nonsource_path, "nonsource_files[]:\n # path,summary\n").map_err(|source| { AtlasMapError::Io { path: nonsource_path, source, } })?; } Ok(config_path.to_string_lossy().into_owned()) } ``` -------------------------------- ### Admit Installed Slot Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_cli/optional_parser_lifecycle.rs.html Executes the complete current-host admission probe before selecting an installed slot. ```rust fn admit_installed_slot( &self, slot: &PackSlotIdentity, ) -> Result<(), OptionalParserPackLifecycleError> { let root = self.slot_path(slot)?; #[cfg(test)] if let Some(failure) = self.admission_failure { return Err(failure(&root).into()); } let logical_bytes = read_bounded_file( &root.join(ACCEPTED_MANIFEST_FILE_NAME), u64::try_from(OPTIONAL_PARSER_PACK_MANIFEST_MAX_BYTES) .map_err(|source| invalid_data(source.to_string()))?, )?; let logical = OptionalParserPackManifest::from_json(&logical_bytes)?; let verified = self.open_verified_installed_slot(slot)?; admit_optional_parser_artifact(verified.supervisor, &logical)?; Ok(()) } ``` -------------------------------- ### Transition Project Root and Verify Identity Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_db/project_identity.rs.html?search=u32+-%3E+bool Demonstrates transitioning a project root using AtlasStore and verifying the resulting identity changes. ```rust let current_missing_identity_db = temp.path().join("current-missing-identity.db"); let current_missing_identity_root = temp.path().join("current-missing-identity-root"); let current_missing_identity_destination = temp.path().join("current-missing-identity-destination"); fs::create_dir(¤t_missing_identity_root)?; fs::create_dir(¤t_missing_identity_destination)?; AtlasStore::transition_project_root( ¤t_missing_identity_db, ¤t_missing_identity_root, ProjectRootTransition::Bind, )?; { let current = AtlasStore::open(¤t_missing_identity_db)?; current .connection .execute("DELETE FROM project_identity", [])?; current .connection .execute_batch("PRAGMA wal_checkpoint(TRUNCATE)")?; } fs::remove_dir(¤t_missing_identity_root)?; let repaired_current_move = AtlasStore::transition_project_root( ¤t_missing_identity_db, ¤t_missing_identity_destination, ProjectRootTransition::Move, )?; require( repaired_current_move.identity_changed, "current bound database move did not report its repaired identity", )?; let repaired_current = AtlasStore::open_read_only_for_project( ¤t_missing_identity_db, ¤t_missing_identity_destination, )?; require_eq( &repaired_current.project_instance_id()?, &Some(repaired_current_move.project_instance_id), "current bound database repaired identity", )?; ``` -------------------------------- ### Enabling Installed Slots Source: https://styler-ai.github.io/ProjectAtlas/projectatlas_cli/optional_parser_lifecycle/struct.OptionalParserPackLifecycle.html Activates a previously installed parser pack slot for the current project. ```rust pub fn enable( &self, artifact: &str, ) -> Result ``` -------------------------------- ### Transition Project Root Scenarios Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_db/project_identity.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates various edge cases for project root transitions, including handling of existing files, dangling links, and relative paths. ```rust fs::create_dir(®ular_root)?; AtlasStore::transition_project_root( ®ular_db, ®ular_root, ProjectRootTransition::Bind, )?; fs::remove_dir(®ular_root)?; fs::write(®ular_root, "the old root path still exists")?; let regular_bytes = fs::read(®ular_db)?; let regular_error = require_error( AtlasStore::transition_project_root(®ular_db, &root_c, ProjectRootTransition::Move), "regular file at the old root was treated as absent", )?; require( matches!(regular_error, DbError::ProjectRootStillPresent { .. }), "regular-file move returned the wrong error", )?; assert_database_unchanged(®ular_db, ®ular_bytes, "regular-file move database")?; let link_root = temp.path().join("former-root-now-link"); let missing_link_target = temp.path().join("missing-link-target"); let link_db = temp.path().join("linked-root.db"); fs::create_dir(&link_root)?; AtlasStore::transition_project_root(&link_db, &link_root, ProjectRootTransition::Bind)?; fs::remove_dir(&link_root)?; if create_dangling_directory_link(&missing_link_target, &link_root)? { let link_bytes = fs::read(&link_db)?; let link_error = require_error( AtlasStore::transition_project_root(&link_db, &root_c, ProjectRootTransition::Move), "dangling root link was treated as absent", )?; require( matches!(link_error, DbError::ProjectRootStillPresent { .. }), "dangling-link move returned the wrong error", )?; assert_database_unchanged(&link_db, &link_bytes, "dangling-link move database")?; fs::remove_file(&link_root)?; } let relative_root = temp.path().join("relative-root-source"); let relative_db = temp.path().join("relative-root.db"); fs::create_dir(&relative_root)?; AtlasStore::transition_project_root( &relative_db, &relative_root, ProjectRootTransition::Bind, )?; { let relative_store = AtlasStore::open(&relative_db)?; set_metadata( &relative_store.connection, PROJECT_ROOT_KEY, "relative/stored/root", )?; relative_store .connection .execute_batch("PRAGMA wal_checkpoint(TRUNCATE)")?; } let relative_bytes = fs::read(&relative_db)?; let relative_error = require_error( AtlasStore::transition_project_root(&relative_db, &root_c, ProjectRootTransition::Move), "non-absolute stored root was treated as a verified move", )?; require( matches!(relative_error, DbError::ProjectRootAbsenceUncertain { .. }), "non-absolute stored root returned the wrong error", )?; assert_database_unchanged(&relative_db, &relative_bytes, "relative-root move database")?; ``` -------------------------------- ### trim_end_matches Examples Source: https://styler-ai.github.io/ProjectAtlas/projectatlas/mcp/struct.McpToolTextResult.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Examples showing how to remove suffixes matching characters, numeric patterns, or closures. ```rust assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar"); assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar"); let x: &[_] = &['1', '2']; assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar"); ``` ```rust assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo"); ``` -------------------------------- ### Build Session Brief Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/mcp.rs.html Constructs an McpSessionBrief by querying the store for project overview, ranked nodes, and health status. ```rust let outcome = self.with_fresh_store_for_request(&state, context, |store, _stamp| { let overview = store.overview()?; let folder_rows = ranked_folder_nodes_with_reasons(store, &query, folder_limit.saturating_add(1))?; let file_rows = ranked_file_nodes_with_reasons( store, &query, None, None, file_limit.saturating_add(1), false, )?; let blockers = Self::brief_blockers(store, blocker_limit)?; let purpose_query = HealthQuery { start_index: 0, limit: purpose_limit, category: None, severity: None, path_prefix: None, summary_only: false, scope: HealthScope::purpose_default(), }; let purpose_queue = purpose_curation_page(store, &purpose_query, &purpose_task)?; let purposes_truncated = purpose_queue.truncated; let folders_truncated = folder_rows.len() > folder_limit; let files_truncated = file_rows.len() > file_limit; let next_navigation_call = file_rows.first().map(|row| row.next_call.clone()); Ok(McpSessionBrief { project: Self::selected_project_capability(&state), policy: self.brief_policy(), overview: Some(overview), folders: folder_rows .into_iter() .take(folder_limit) .map(Self::brief_candidate) .collect(), files: file_rows .into_iter() .take(file_limit) .map(Self::brief_candidate) .collect(), recommendations: Self::indexed_project_recommendations( &query, next_navigation_call, blockers.total, blocker_limit, selected_project_path.clone(), ), blockers, purpose_handoff: purpose_queue .actionable .then(|| purpose_curator_handoff(purpose_queue)), limits: McpBriefLimits { folder_limit, file_limit, blocker_limit, purpose_limit, folders_truncated, files_truncated, purposes_truncated, }, }) })?; Ok(outcome.value) ``` -------------------------------- ### Remove Installed Pack Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_cli/optional_parser_lifecycle.rs.html Attempts exact artifact-scoped cleanup for every installed slot before removing storage. ```rust fn remove_installed_pack( &self, pack_root: &Path, slots: Vec, ) -> Result { let mut changed = false; let mut failures = Vec::new(); for slot in slots { let result = self.remove_installed_slot(&slot); match result { Ok(slot_changed) => changed |= slot_changed, Err(error) => { if failures.len() < 16 { failures.push(format!("{}: {error}", slot.bounded_label())); } } } } if !failures.is_empty() { return Err(OptionalParserPackLifecycleError::CleanupIncomplete { message: failures.join("; "), }); } Ok(remove_tree_if_present(pack_root)? || changed) } ``` -------------------------------- ### Trim leading whitespace Source: https://styler-ai.github.io/ProjectAtlas/projectatlas/mcp/struct.McpToolTextResult.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Removes whitespace from the start of a string slice, respecting byte-level start positions. ```rust let s = "\n Hello\tworld\t\n"; assert_eq!("Hello\tworld\t\n", s.trim_start()); ``` ```rust let s = " English "; assert!(Some('E') == s.trim_start().chars().next()); ``` -------------------------------- ### Installed Slot Cleanup Management Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_cli/optional_parser_lifecycle.rs.html Structures and states for managing the lifecycle of installed slots and tombstones, specifically on Windows. ```rust /// Closed cleanup state for one lifecycle-owned slot or tombstone entry. #[cfg(all(target_os = "windows", target_arch = "x86_64"))] #[derive(Clone, Copy, Debug, Eq, PartialEq)] enum InstalledSlotCleanupState { /// Canonical deterministic installed slot awaiting an atomic removal transition. Installed, /// Unique tombstone whose artifact profile still requires idempotent cleanup. ProfilePending, /// Unique tombstone whose profile is already cleaned and only deletion remains. ProfileCleaned, } /// One direct slot or unique tombstone retained for bounded cleanup. #[derive(Clone, Debug)] struct InstalledSlotPath { /// Direct version directory name, retained even when stale. #[cfg(all(target_os = "windows", target_arch = "x86_64"))] projectatlas_version: String, /// Canonical artifact identity parsed from the slot or tombstone name. artifact: String, /// Exact lifecycle-owned direct slot or tombstone container. entry_root: PathBuf, /// Exact pack root while artifact/profile verification remains necessary. #[cfg(all(target_os = "windows", target_arch = "x86_64"))] pack_root: Option, /// Current closed cleanup transition state. #[cfg(all(target_os = "windows", target_arch = "x86_64"))] state: InstalledSlotCleanupState, } impl InstalledSlotPath { /// Return a bounded content-free label for aggregate cleanup diagnostics. fn bounded_label(&self) -> String { self.artifact.chars().take(64).collect() } } ``` -------------------------------- ### Installed Slot Transfer Test Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_cli/optional_parser_lifecycle.rs.html?search=u32+-%3E+bool Ensures that transferring a profile to an installed slot correctly disarms temporary cleanup. ```rust #[test] fn installed_slot_transfer_disarms_temporary_profile_cleanup() -> TestResult { let directory = tempfile::tempdir()?; let mut profile = TemporaryParserArtifactProfile::new( directory.path(), ParserArtifactIdentity::for_bytes(b"artifact-manifest"), ); profile.transfer_to_installed_slot(); require( !profile.cleanup_pending, "installed-slot transfer retained temporary cleanup ownership", )?; profile.cleanup()?; Ok(()) } ``` -------------------------------- ### Test Project Setup and Identity Retrieval Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/mcp.rs.html Helper functions to initialize a project directory structure and retrieve the runtime identity from an MCP server instance. ```rust fn usage_test_project( parent: &Path, name: &str, ) -> Result<(McpProjectState, AtlasStore), Box> { let root = parent.join(name); fs::create_dir_all(root.join(".projectatlas"))?; let db_path = root.join(".projectatlas").join("projectatlas.db"); let store = AtlasStore::open_for_project(&db_path, &root)?; Ok(( McpProjectState { root, db_path, config_path: None, }, store, )) } ``` ```rust fn usage_runtime_identity( server: &ProjectAtlasMcpServer, state: &McpProjectState, store: &AtlasStore, ) -> Result> { let binding = McpUsageProjectBinding::capture(state, store)?; let project_instance = server .usage_runtime .lock() .map_err(|_poisoned| io::Error::other("usage runtime lock poisoned"))? .entries .iter() .find(|entry| entry.binding == binding) .map(|entry| Arc::clone(&entry.instance)) .ok_or_else(|| io::Error::other("operating-system entropy was unavailable"))?; let identity = *project_instance .lock() .map_err(|_poisoned| io::Error::other("project usage lock poisoned"))?; Ok(identity) } ``` -------------------------------- ### PreparedParserRuntime Implementation Methods Source: https://styler-ai.github.io/ProjectAtlas/projectatlas_parser_worker/struct.PreparedParserRuntime.html?search= Methods for initializing the runtime and managing language admission. ```rust pub(crate) fn new(grammar_file: File, grammar: AcceptedGrammar) -> Self ``` ```rust pub(crate) fn admit_language( &mut self, requested: &ParserLanguageIdentity, ) -> Result<(), ParserFailureCode> ``` ```rust pub(crate) fn grammar_file(&self) -> &File ``` -------------------------------- ### Open Verified Installed Slot Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_cli/optional_parser_lifecycle.rs.html Verifies the exact installed identity, manifest bindings, and immutable permissions of a slot. ```rust fn open_verified_installed_slot( &self, slot: &PackSlotIdentity, ) -> Result { let root = self.slot_path(slot)?; if !self.slot_path_is_real(slot)? { return Err(invalid_data( "selected optional parser-pack slot is not installed", )); } verify_immutable_tree(&root)?; let selection_key = slot.selection_key()?; let supervisor = OptionalParserSupervisor::open(root)?; if supervisor.artifact_identity() != selection_key.artifact() { return Err(invalid_data( "installed slot identity differs from its artifact manifest", )); } Ok(OpenedOptionalParserPackSlot { selection_key, supervisor, }) } ``` -------------------------------- ### Task Cancellation and Start Responses Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/mcp.rs.html?search=std%3A%3Avec Structures for handling task cancellation results and initial task start responses. ```rust /// Task cancellation response. #[derive(Debug, Serialize)] struct McpTaskCancelResponse { /// Requested task id. task_id: String, /// Cancellation outcome. result: McpTaskCancelResult, /// Registry capacity. registry_capacity: usize, /// Task record when found. task: Option, } /// Immediate response for one accepted background indexing task. #[derive(Debug, Serialize)] struct McpTaskStartResponse { /// Opaque session-local task id. task_id: String, /// Accepted operation family. operation: McpTaskOperation, /// Initial task state. state: McpTaskState, /// Existing MCP tool used to poll the task. status_tool: &'static str, /// Existing MCP tool used to request cancellation. cancel_tool: &'static str, } /// Task cancellation outcome. #[derive(Debug, Eq, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] enum McpTaskCancelResult { /// Cooperative cancellation was delivered to active work. CancellationRequested, /// The task id is unknown to this MCP session. NotFound, /// The task was already finished. AlreadyFinished, /// The task exists but cannot currently be canceled. NotCancelable, } ``` -------------------------------- ### Initialize Canonical Resolution Keys Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_core/graph.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates the initialization of a CanonicalResolutionKey with domain, provider, language, package, and scope identifiers. ```rust #[test] fn canonical_resolution_keys_are_stable_qualified_and_collision_checked() -> Result<(), Box> { let provider = GraphIdentityText::new("tree-sitter")?; let language = GraphIdentityText::new("rust")?; let package = GraphIdentityText::new("auth")?; let scope = GraphIdentityText::new("crate")?; let identity = GraphIdentityText::new("répond")?; let key = CanonicalResolutionKey::new( project()?, ResolutionKeyDomain::Declaration, &provider, &language, Some(&package), Some(&scope), ``` -------------------------------- ### trim_left_matches Examples Source: https://styler-ai.github.io/ProjectAtlas/projectatlas/mcp/struct.McpToolTextResult.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Examples showing how to remove prefixes matching characters or numeric patterns. Note that this method is deprecated. ```rust assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11"); assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123"); let x: &[_] = &['1', '2']; assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12"); ``` -------------------------------- ### Transitioning Project Roots and Identity Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_db/project_identity.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates how to transition project roots using AtlasStore, including handling missing identities and detaching project instances. ```rust let current_missing_identity_db = temp.path().join("current-missing-identity.db"); let current_missing_identity_root = temp.path().join("current-missing-identity-root"); let current_missing_identity_destination = temp.path().join("current-missing-identity-destination"); fs::create_dir(¤t_missing_identity_root)?; fs::create_dir(¤t_missing_identity_destination)?; AtlasStore::transition_project_root( ¤t_missing_identity_db, ¤t_missing_identity_root, ProjectRootTransition::Bind, )?; { let current = AtlasStore::open(¤t_missing_identity_db)?; current .connection .execute("DELETE FROM project_identity", [])?; current .connection .execute_batch("PRAGMA wal_checkpoint(TRUNCATE)")?; } fs::remove_dir(¤t_missing_identity_root)?; let repaired_current_move = AtlasStore::transition_project_root( ¤t_missing_identity_db, ¤t_missing_identity_destination, ProjectRootTransition::Move, )?; require( repaired_current_move.identity_changed, "current bound database move did not report its repaired identity", )?; let repaired_current = AtlasStore::open_read_only_for_project( ¤t_missing_identity_db, ¤t_missing_identity_destination, )?; require_eq( &repaired_current.project_instance_id()?, &Some(repaired_current_move.project_instance_id), "current bound database repaired identity", )?; ``` ```rust let detached = AtlasStore::transition_project_root(©_db, &root_b, ProjectRootTransition::Detach)?; require( detached.project_instance_id != source_identity, "detach preserved copied identity", )?; require(detached.identity_changed, "detach did not change identity")?; require( detached.publication_invalidated, "detach did not invalidate publication", )?; let detached_store = AtlasStore::open_read_only_for_project(©_db, &root_b)?; require_eq( &detached_store.project_instance_id()?, &Some(detached.project_instance_id), "detached identity", )?; assert_authored_state(&detached_store)?; assert_usage_report(&detached_store, false)?; assert_runtime_scope(&detached_store, source_identity, 0, 1, 0)?; assert_graph_counts(&detached_store, [0, 0, 0, 0, 0, 0, 0])?; require( detached_store.index_publication()?.is_none(), "detach retained publication", )?; ``` -------------------------------- ### Initialize project-root .gitignore Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/atlas_map.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates a default .gitignore file in the project root if one does not already exist. ```rust pub(crate) fn init_gitignore( config_path: Option<&Path>, project_root: &Path, ) -> AtlasMapResult { 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 = gitignore_path.exists(); if !existed { fs::write(&gitignore_path, default_gitignore_text()).map_err(|source| { AtlasMapError::Io { path: gitignore_path.clone(), source, } })?; } Ok(GitignoreInitReport { gitignore_path: gitignore_path.display().to_string(), existed, created: !existed, gitignore_inherited: true, }) } ``` -------------------------------- ### Unwrap Unchecked Examples Source: https://styler-ai.github.io/ProjectAtlas/optional_parser_pack_release/type.ToolResult.html?search=std%3A%3Avec Examples of using unwrap_unchecked, which is unsafe and causes undefined behavior if called on an Err variant. ```rust let x: Result = Ok(2); assert_eq!(unsafe { x.unwrap_unchecked() }, 2); ``` ```rust let x: Result = Err("emergency failure"); unsafe { x.unwrap_unchecked() }; // Undefined behavior! ``` -------------------------------- ### Example Search Queries Source: https://styler-ai.github.io/ProjectAtlas/projectatlas/mcp/struct.McpRequestCancellationBridge.html?search= Common search patterns for finding types and trait implementations within the documentation. ```text std::vec u32 -> bool Option, (T -> U) -> Option ``` -------------------------------- ### Test storage link protection during install Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_cli/optional_parser_lifecycle.rs.html?search=std%3A%3Avec Validates that the installation process refuses to operate on storage locations that are product-owned links. ```rust #[test] fn install_refuses_product_owned_storage_link_before_archive_open() -> TestResult { let Some(platform) = host_pack_platform() else { return Ok(()); }; let root = tempfile::tempdir()?; let storage = root.path().join("storage"); let external = root.path().join("external"); fs::create_dir_all(&storage)?; fs::create_dir_all(&external)?; let marker = external.join("must-survive.txt"); fs::write(&marker, b"outside")?; create_directory_link(&external, &storage.join(OPTIONAL_PARSER_PACK_ID))?; let lifecycle = OptionalParserPackLifecycle::for_test( root.path().join("project"), storage, Some(platform), ); let missing_archive = root.path().join("missing.tar.zst"); require( lifecycle.install(&missing_archive).is_err(), "install followed a product-owned storage link", )?; require(marker.is_file(), "install mutated the link target") } ``` -------------------------------- ### Validate Tag Start Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas_symbols/semantic/embedded_source.rs.html?search= Checks if an opening tag with a specific name starts at a given position, ignoring ASCII case. ```rust fn tag_start_is(source: &[u8], start: usize, name: &[u8]) -> bool { source .get(start + 1..start + 1 + name.len()) .is_some_and(|candidate| candidate.eq_ignore_ascii_case(name)) && source .get(start + 1 + name.len()) .is_some_and(|byte| byte.is_ascii_whitespace() || matches!(*byte, b'/' | b'>')) } ``` -------------------------------- ### Initialize project configuration Source: https://styler-ai.github.io/ProjectAtlas/src/projectatlas/atlas_map.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates default configuration files and directory structures for a ProjectAtlas project. ```rust /// 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 { let project_dir = root.join(".projectatlas"); fs::create_dir_all(&project_dir).map_err(|source| AtlasMapError::Io { path: project_dir.clone(), source, })?; 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, ); if !config_path.exists() { 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, })?; } fs::write(&config_path, default_config_text_for(root, &config_path)).map_err(|source| { AtlasMapError::Io { path: config_path.clone(), source, } })?; } let nonsource_path = project_dir.join("projectatlas-nonsource-files.toon"); if !nonsource_path.exists() { fs::write(&nonsource_path, "nonsource_files[]:\n # path,summary\n").map_err(|source| { ```