feat: create mermaid workflow diagrams

Author: Evgeny Torbin

CONTRIBUTING.md

@@ -1,16 +1,25 @@
 # Contributing to IDF Component Manager
+
 We welcome all contributions to the Component Manager project!
 
 You can contribute by fixing bugs, adding features, adding documentation, or reporting an [issue](https://github.com/espressif/idf-component-manager/issues). We accept contributions via [GitHub Pull Requests](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
 
 Before reporting an issue, make sure you've searched for a similar one that was already created. If you are reporting a new issue, please follow the Issue Template.
 
 ## Writing integration tests
+
 For information about tests, refer to the following documents:
+
 - [integration_tests/README.md](integration_tests/README.md)
 - [integration_tests/version_solver_components/README.md](integration_tests/version_solver_components/README.md)
 - [integration_tests/managed_components_sources/README.md](integration_tests/managed_components_sources/README.md)
 
 ## Contributing to the documentation
 
 See [docs/README.md](docs/README.md).
+
+## Workflow diagrams
+
+- [Downloading dependencies](contributing_docs/diagrams/download_dependencies.md)
+- [Component download using WebServiceSource](contributing_docs/diagrams/web_service_download.md)
+- [Validate hash file equals hash of directory](contributing_docs/diagrams/validate_hashfile_eq_hashdir.md)

contributing_docs/diagrams/download_dependencies.md

@@ -0,0 +1,100 @@
+```mermaid
+flowchart TD
+    classDef exception fill:#ff6054,stroke:#b80c00,stroke-width:2px,color:#000;
+
+    download_deps([Download dependencies])
+    solve_deps[Solve dependencies]
+    detect_unused[Detect unused dependencies]
+
+    download_deps --> solve_deps
+    solve_deps --> detect_unused
+    detect_unused --> S1
+
+    subgraph S1[Process dependency]
+        direction LR
+
+        subgraph S2[PRE DOWNLOAD CHECK]
+            direction TB
+
+            S2_is_source_downloadable{Is component source downloadable?}
+            S2_is_component_exist{"Is component exist in managed_components directory?"}
+            S2_is_overwrite_set{"Is OVERWRITE_MANAGED_COMPONENTS set?"}
+            S2_check_local[Check local changes]
+            S2_download_dep[Download dependency]
+
+            S2_is_source_downloadable -- No --> S2_download_dep
+            S2_is_source_downloadable -- Yes --> S2_is_component_exist
+            S2_is_component_exist -- No --> S2_download_dep
+            S2_is_component_exist -- Yes --> S2_is_overwrite_set
+            S2_is_overwrite_set -- No --> S2_check_local
+            S2_is_overwrite_set -- Yes --> S2_download_dep
+        end
+
+        subgraph S3[CHECK LOCAL CHANGES]
+            direction TB
+
+            S3_is_strict_set{"Is STRICT_CHECKSUM set?"}
+            S3_validate_hashfile_eq_hashdir[Validate hashfile_eq_hashdir]
+            S3_check_up_to_date[Check up to date]
+            S3_is_valid{Is valid?}
+            S3_component_modified[Component Modified]:::exception
+
+            S3_is_strict_set -- No --> S3_check_up_to_date
+            S3_is_strict_set -- Yes --> S3_validate_hashfile_eq_hashdir
+            S3_validate_hashfile_eq_hashdir --> S3_is_valid
+            S3_is_valid -- No --> S3_component_modified
+            S3_is_valid -- Yes --> S3_check_up_to_date
+        end
+
+        subgraph S4[CHECK UP TO DATE]
+            direction TB
+
+            S4_is_component_has_hash{Is downloadable component has hash?}
+            S4_is_strict_set{"Is STRICT_CHECKSUM set?"}
+            S4_download_checksums[Download component checksums]
+            S4_is_checksums_exist{Is checksums exist?}
+            S4_validate_checksums[Validate checksums]
+            S4_validate_hash_eq_hashfile[Validate hash_eq_hashfile]
+            S4_validate_hash_eq_hashdir[Validate hash_eq_hashdir]
+            S4_is_valid{Is valid?}
+            S4_fetching_error[Fetching error]:::exception
+            S4_download_dep[Download dependency]
+            S4_add_to_dep_list[Add to downloaded dependencies list]
+
+            S4_is_component_has_hash -- No --> S4_fetching_error
+            S4_is_component_has_hash -- Yes --> S4_is_strict_set
+            S4_is_strict_set -- No --> S4_validate_hash_eq_hashfile
+            S4_is_strict_set -- Yes --> S4_download_checksums
+            S4_download_checksums --> S4_is_checksums_exist
+            S4_is_checksums_exist -- No --> S4_validate_hash_eq_hashdir
+            S4_is_checksums_exist -- Yes --> S4_validate_checksums
+            S4_validate_hash_eq_hashfile --> S4_is_valid
+            S4_validate_checksums --> S4_is_valid
+            S4_validate_hash_eq_hashdir --> S4_is_valid
+            S4_is_valid -- No --> S4_download_dep
+            S4_is_valid -- Yes --> S4_add_to_dep_list
+        end
+
+        subgraph S5[DOWNLOAD DEPENDENCY]
+            direction TB
+
+            S5_download_dep[Download dependency from source]
+            S5_is_source_downloadable{Is component source downloadable?}
+            S5_validate_hashfile_eq_hashdir[Validate hashfile_eq_hashdir]
+            S5_is_valid{Is valid?}
+            S5_fetching_error[Fetching error]:::exception
+            S5_add_to_dep_list[Add to downloaded dependencies list]
+
+            S5_download_dep --> S5_is_source_downloadable
+            S5_is_source_downloadable -- No --> S5_add_to_dep_list
+            S5_is_source_downloadable -- Yes --> S5_validate_hashfile_eq_hashdir
+            S5_validate_hashfile_eq_hashdir --> S5_is_valid
+            S5_is_valid -- No --> S5_fetching_error
+            S5_is_valid -- Yes --> S5_add_to_dep_list
+        end
+
+        S2 ~~~ S3
+        S3 ~~~ S4
+        S4 ~~~ S5
+    end
+```

contributing_docs/diagrams/validate_hashfile_eq_hashdir.md

@@ -0,0 +1,17 @@
+```mermaid
+flowchart TD
+    classDef exception fill:#ff6054,stroke:#b80c00,stroke-width:2px,color:#000;
+
+    validate_hashfile_eq_hashdir([Validate hashfile_eq_hashdir])
+    is_checksums_exist{"Is CHECKSUMS.json exists?"}
+    validate_checksums[Validate checksums]
+    is_component_hash_exist{"Is .component_hash exist?"}
+    validate_hash_eq_hashdir[Validate hash_eq_hashdir]
+    hash_not_found[Hash Not Found]:::exception
+
+    validate_hashfile_eq_hashdir --> is_checksums_exist
+    is_checksums_exist -- No --> is_component_hash_exist
+    is_checksums_exist -- Yes --> validate_checksums
+    is_component_hash_exist -- No --> hash_not_found
+    is_component_hash_exist -- Yes --> validate_hash_eq_hashdir
+```

contributing_docs/diagrams/web_service_download.md

@@ -0,0 +1,39 @@
+```mermaid
+flowchart TD
+    classDef exception fill:#ff6054,stroke:#b80c00,stroke-width:2px,color:#000;
+
+    web_service_source_download([WebServiceSource download])
+    is_component_has_hash{Is downloadable component has hash?}
+    is_component_has_version{Is downloadable component has version?}
+    is_component_exist_in_cache{Is component exist in cache?}
+    validate_hash_eq_hashdir[Validate hash_eq_hashdir]
+    is_valid{Is valid?}
+    download_component["
+    Download component
+    Copy to cache and managed_components
+    "]
+    download_checksums["
+    Download CHECKSUMS.json
+    Copy to cache and managed_components
+    "]
+    copy_from_cache["
+    Copy component
+    from cache to managed_components
+    "]
+    return_download_path[Return download path]
+    fetching_error[Fetching error]:::exception
+
+    web_service_source_download --> is_component_has_hash
+    is_component_has_hash -- No --> fetching_error
+    is_component_has_hash -- Yes --> is_component_has_version
+    is_component_has_version -- No --> fetching_error
+    is_component_has_version -- Yes --> is_component_exist_in_cache
+    is_component_exist_in_cache -- No --> download_component
+    is_component_exist_in_cache -- Yes --> validate_hash_eq_hashdir
+    validate_hash_eq_hashdir --> is_valid
+    is_valid -- No --> download_component
+    is_valid -- Yes --> copy_from_cache
+    copy_from_cache --> return_download_path
+    download_component --> download_checksums
+    download_checksums --> return_download_path
+```

idf_component_manager/dependencies.py

@@ -413,6 +413,8 @@ def download_project_dependencies(
     """
     Solves dependencies and download components (only talk about resolve-required scenario)
 
+    For a detailed workflow, see `contributing_docs/diagrams/download_dependencies.md`.
+
     By default, we run as local-first mode, the process is:
     - read existing lock file first, get the solved_components
     - use the solved_components with the version solver, to see if solution is still valid

idf_component_tools/hash_tools/validate.py

@@ -68,6 +68,8 @@ def validate_hashfile_eq_hashdir(root: t.Union[str, Path]) -> None:
     1. Validate hash of each file in the component directory, if CHECKSUMS_FILENAME is present
     2. Validate hashsum of the component directory, if HASH_FILENAME is present
 
+    For a detailed workflow, see `contributing_docs/diagrams/validate_hashfile_eq_hashdir.md`.
+
     :param root: Path to the component
     :raises ComponentNotFoundError: Component path does not exist
     :raises HashNotFoundError: Hash file does not exist

idf_component_tools/sources/web_service.py

@@ -275,6 +275,15 @@ def normalized_name(self, name):
         return name
 
     def download(self, component: 'SolvedComponent', download_path: str) -> str:
+        """Download component from the web service.
+
+        For a detailed workflow, see `contributing_docs/diagrams/web_service_download.md`.
+
+        :param component: Component to download
+        :param download_path: Destination path for the downloaded component
+        :raises FetchingError: If there is an error during the download process.
+        :return: Path to the downloaded component.
+        """
         from idf_component_tools.registry.service_details import get_storage_client
 
         # Check for required components