Documentation

Author: coatless

R/file-mapping.R

@@ -1,35 +1,59 @@
 #' Create a file mapping for multi-repository deployment
 #'
+#' This function builds a mapping between local files and their target paths in repositories,
+#' supporting both individual file mapping and bulk directory processing.
+#'
 #' @param ... Named arguments where names are local file paths and values are repository paths
 #' @param dir Character string specifying a directory to search for files. Default is NULL.
 #' @param pattern Character string with a regular expression pattern to match files in dir. Default is NULL.
 #' @param target_prefix Character string to prefix to all target paths. Default is "".
 #' @param preserve_structure Logical indicating whether to preserve directory structure in target. Default is FALSE.
+#' @param quiet Logical; if TRUE, suppresses information messages. Default is FALSE.
+#'
+#' @return 
+#' Returns an object of class `"file_mapping"` (which is just a marked up `"list"`) containing:
+#' 
+#' - A named list where each entry maps a local file path (name) to a target repository path (value)
+#' - Each key is the full path to a local file
+#' - Each value is the corresponding path where the file should be placed in repositories
 #'
-#' @return A named list where names are local file paths and values are repository paths
+#' @seealso [`print.file_mapping()`] to display the mapping in a formatted way.
+#' 
+#' @details
+#' The `dir` argument requires a valid directory path currently on the local filesystem.
+#' This directory is scanned for files matching the `pattern` regular expression,
+#' and each file is mapped to a target path in repositories. If the directory is
+#' not found, an error is thrown.
+#' 
+#' 
 #' @export
 #'
 #' @examples
-#' \dontrun{
-#' # Individual files
+#' # Map individual files with explicit source-to-target paths
 #' mapping <- file_mapping(
 #'   "local/path/ci.yml" = ".github/workflows/ci.yml",
 #'   "local/path/lint.R" = ".lintr"
 #' )
 #'
-#' # All yaml files from a directory to .github/workflows
-#' mapping <- file_mapping(
-#'   dir = "local/workflows",
-#'   pattern = "\\.ya?ml$",
-#'   target_prefix = ".github/workflows/"
+#' # Automatically map all R files from a directory to backup/R2/
+#' workflow_mapping <- file_mapping(
+#'   dir = system.file(package = "multideploy"),
+#'   pattern = "\\.R$",
+#'   target_prefix = "backup/R2/"
 #' )
 #'
-#' # Preserve directory structure
-#' mapping <- file_mapping(
-#'   dir = "templates",
+#' # Preserve directory structure when mapping files
+#' template_mapping <- file_mapping(
+#'   dir = system.file(package = "multideploy"),
 #'   preserve_structure = TRUE
 #' )
-#' }
+#'
+#' # Combine explicit mappings with directory-based mappings
+#' combined_mapping <- file_mapping(
+#'   "specific/file.R" = "R/functions.R",
+#'   dir = system.file(package = "multideploy"),
+#'   target_prefix = ".github/"
+#' )
 file_mapping <- function(..., dir = NULL, pattern = NULL, 
                          target_prefix = "", preserve_structure = FALSE, quiet = FALSE) {
   mapping <- list(...)
@@ -79,12 +103,36 @@ file_mapping <- function(..., dir = NULL, pattern = NULL,
 
 #' Print method for file_mapping objects
 #'
-#' @param x A file_mapping object to print
+#' This method provides a formatted display of file mappings, showing the relationship between
+#' local files and their target repository paths with visual indicators for file existence.
+#'
+#' @param x An object of class `"file_mapping"` as returned by `file_mapping()`
 #' @param max_files Maximum number of files to display. Default is 20.
-#' @param ... Additional arguments passed to print methods (not used)
+#' @param ... Additional arguments passed to other print methods (not used)
+#'
+#' @return 
+#' Invisibly returns the original `file_mapping` object unchanged, allowing for
+#' chained operations. 
+#' 
+#' Displays a formatted representation of the mapping to the console, including:
+#' 
+#' - Total count of mapped files
+#' - Visual indicators showing which local files exist (checkmark) or are missing (x)
+#' - Source-to-target mapping for each file (limited by `max_files`)
 #'
-#' @return Invisibly returns the file_mapping object
 #' @export
+#'
+#' @examples
+#' # Create and display a mapping
+#' mapping <- file_mapping(
+#'   "R/functions.R" = "R/utils.R",
+#'   dir = system.file(package = "multideploy")
+#' )
+#' # The mapping is automatically printed when not assigned
+#'
+#' # Control how many files are displayed
+#' mapping <- file_mapping(dir = system.file(package = "multideploy"))
+#' print(mapping, max_files = 5)  # Show only first 5 mappings
 print.file_mapping <- function(x, max_files = 20, ...) {
   n_files <- length(x)
 

R/file.R

@@ -1,17 +1,39 @@
 #' Retrieve the content of a file from a GitHub repository
 #'
-#' @param repo Character string specifying the full name of the repository (owner/repo)
-#' @param path Character string specifying the path to the file
-#' @param ref Character string specifying the branch name or commit SHA. Default is NULL.
+#' This function fetches a file from a GitHub repository and returns its content and SHA.
+#' If the file cannot be retrieved, it returns NULL and optionally displays a warning message.
+#'
+#' @param repo Character string specifying the full name of the repository (format: "owner/repo")
+#' @param path Character string specifying the path to the file within the repository
+#' @param ref Character string specifying the branch name, tag, or commit SHA. Default is NULL (uses default branch).
+#'
+#' @return 
+#' When successful, returns a `list` with two elements:
+#' 
+#' \describe{
+#'   \item{content}{Character string containing the decoded file content}
+#'   \item{sha}{Character string with the file's blob SHA for use in update operations}
+#' }
+#' 
+#' When the file cannot be retrieved (e.g., does not exist or no access), returns `NULL`.
 #'
-#' @return List with the content and SHA of the file if it exists, NULL otherwise
 #' @export
 #'
-#' @examples
-#' \dontrun{
-#' file_info <- file_content("username/repo", "path/to/file.R")
+#' @examplesIf interactive()
+#' # Get content from default branch
+#' file_info <- file_content("username/repository", "path/to/file.R")
+#' if (!is.null(file_info)) {
+#'   # Access the content and SHA
+#'   content <- file_info$content
+#'   sha <- file_info$sha
 #' }
-file_content <- function(repo, path, ref = NULL, quiet = FALSE) {
+#'
+#' # Get content from specific branch
+#' file_info <- file_content("username/repository", "path/to/file.R", ref = "develop")
+#'
+#' # Suppress warnings
+#' file_info <- file_content("username/repository", "path/to/file.R")
+file_content <- function(repo, path, ref = NULL) {
   tryCatch({
     query <- list(path = path)
     if (!is.null(ref)) {
@@ -33,28 +55,62 @@ file_content <- function(repo, path, ref = NULL, quiet = FALSE) {
       return(NULL)
     }
   }, error = function(e) {
-    if (!quiet) {
-      cli::cli_alert_warning("Could not fetch file {.file {path}} from {.val {repo}}: {e$message}")
-    }
+    cli::cli_alert_warning("Could not fetch file {.file {path}} from {.val {repo}}: {e$message}")
     return(NULL)
   })
 }
 
 #' Create or update a file in a GitHub repository
 #'
-#' @param repo Character string specifying the full name of the repository (owner/repo)
-#' @param path Character string specifying the path to the file
+#' This function creates a new file or updates an existing file in a GitHub repository.
+#' For updating existing files, the SHA of the current file must be provided.
+#'
+#' @param repo Character string specifying the full name of the repository (format: "owner/repo")
+#' @param path Character string specifying the path to the file within the repository
 #' @param content Character string with the new content of the file
 #' @param message Character string with the commit message
 #' @param branch Character string specifying the branch name. Default is NULL (uses default branch).
-#' @param sha Character string with the blob SHA of the file being replaced (required for updates). Default is NULL.
+#' @param sha Character string with the blob SHA of the file being replaced. Required for updating
+#'   existing files; omit for creating new files. Default is NULL.
+#' @param quiet Logical; if TRUE, suppresses progress and status messages. Default is FALSE.
+#'
+#' @return 
+#' When successful, returns a `list` containing the GitHub API response with details about the commit,
+#' including:
+#' 
+#' \describe{
+#'   \item{content}{Information about the updated file}
+#'   \item{commit}{Details about the created commit}
+#' }
+#' 
+#' When the operation fails (e.g., permission issues, invalid SHA), returns `NULL`.
 #'
-#' @return A list with the API response or NULL if operation failed
 #' @export
 #'
-#' @examples
-#' \dontrun{
-#' result <- file_update("username/repo", "path/to/file.R", "new content", "Update file")
+#' @examplesIf interactive()
+#' # Create a new file
+#' result <- file_update(
+#'   repo = "username/repository", 
+#'   path = "path/to/new_file.R", 
+#'   content = "# New R script\n\nprint('Hello world')", 
+#'   message = "Add new script file"
+#' )
+#' # Check if operation was successful
+#' if (!is.null(result)) {
+#'   # Access commit information
+#'   commit_sha <- result$commit$sha
+#' }
+#'
+#' # Update an existing file (requires SHA)
+#' file_info <- file_content("username/repository", "path/to/existing_file.R")
+#' if (!is.null(file_info)) {
+#'   result <- file_update(
+#'     repo = "username/repository", 
+#'     path = "path/to/existing_file.R", 
+#'     content = "# Updated content\n\nprint('Hello updated world')", 
+#'     message = "Update file content",
+#'     sha = file_info$sha
+#'   )
 #' }
 file_update <- function(repo, path, content, message, branch = NULL, sha = NULL, quiet = FALSE) {
   tryCatch({
@@ -84,7 +140,6 @@ file_update <- function(repo, path, content, message, branch = NULL, sha = NULL,
       ),
       query
     ))
-    
     if (!quiet) {
       if (operation == "create") {
         cli::cli_alert_success("Created file {.file {path}} in {.val {repo}}")
@@ -97,31 +152,55 @@ file_update <- function(repo, path, content, message, branch = NULL, sha = NULL,
 
   }, error = function(e) {
     operation_name <- ifelse(is.null(sha), "creating", "updating")
-    if (!quiet) {
-      cli::cli_alert_danger("Error {operation_name} file {.file {path}} in {.val {repo}}: {e$message}")
-    }
+    cli::cli_alert_danger("Error {operation_name} file {.file {path}} in {.val {repo}}: {e$message}")
     return(NULL)
   })
 }
 
 #' Deploy a file to multiple GitHub repositories
 #'
+#' This function deploys a local file to multiple GitHub repositories. It can create new files
+#' or update existing ones, and provides detailed status reporting for each operation.
+#'
 #' @param source_file Character string specifying the local file path to deploy
 #' @param target_path Character string specifying the path in the repositories where the file should be placed
-#' @param repos Data frame of repositories as returned by repos()
-#' @param commit_message Character string with the commit message. Default uses a standard message.
+#' @param repos Data frame of repositories as returned by `repos()` function, with at least a `full_name` column
+#' @param commit_message Character string with the commit message. Default automatically generates a message.
 #' @param branch Character string specifying the branch name. Default is NULL (uses default branch).
 #' @param create_if_missing Logical indicating whether to create the file if it doesn't exist. Default is TRUE.
-#' @param dry_run Logical indicating whether to only simulate the changes without actually making them. Default is FALSE.
+#' @param dry_run Logical indicating whether to only simulate the changes without making actual commits. Default is FALSE.
+#' @param quiet Logical; if TRUE, suppresses progress and status messages. Default is FALSE.
+#'
+#' @return 
+#' Returns a `data.frame` with class `"file_deploy_result"` containing the following columns:
+#' 
+#' \describe{
+#'   \item{repository}{Character, the full repository name (owner/repo)}
+#'   \item{status}{Character, indicating the operation result with one of these values:
+#'     "created", "updated", "unchanged", "skipped", "error", "would_create", "would_update"}
+#'   \item{message}{Character, a description of the action taken or error encountered}
+#' }
+#' 
+#' @seealso [`print.file_deploy_result()`] for a formatted summary of deployment results.
 #'
-#' @return A data frame with the results of each deployment
 #' @export
 #'
-#' @examples
-#' \dontrun{
-#' repositories <- repos("myorg")
-#' results <- file_deploy("local/path/to/file.R", ".github/workflows/ci.yml", repositories)
-#' }
+#' @examplesIf interactive()
+#' # Get list of repositories
+#' repositories <- repos("my-organization")
+#'
+#' # Deploy a workflow file to all repositories
+#' results <- file_deploy(
+#'   source_file = "local/path/to/workflow.yml",
+#'   target_path = ".github/workflows/ci.yml",
+#'   repos = repositories
+#' )
+#' 
+#' # Filter to see only successfully updated repositories
+#' updated <- results[results$status == "updated", ]
+#' 
+#' # Check for any errors
+#' errors <- results[results$status == "error", ]
 file_deploy <- function(source_file, target_path, repos, 
                         commit_message = NULL, branch = NULL, 
                         create_if_missing = TRUE, dry_run = FALSE, quiet = FALSE) {
@@ -134,7 +213,7 @@ file_deploy <- function(source_file, target_path, repos,
   file_content <- readChar(source_file, file.info(source_file)$size)
 
   if (is.null(commit_message)) {
-    commit_message <- sprintf("Update %s via multi.gh automated deployment", target_path)
+    commit_message <- sprintf("Update %s via multideploy automated deployment", target_path)
   }
 
   # Initialize results data frame
@@ -215,19 +294,30 @@ file_deploy <- function(source_file, target_path, repos,
   return(results)
 }
 
-#' Print method for file_deploy_result objects
+#' Print method for `"file_deploy_result"` objects
+#'
+#' This method provides a formatted summary of file deployment results,
+#' showing counts by status and details for any errors encountered.
 #'
-#' @param x The file_deploy_result object to print
-#' @param ... Additional arguments to pass to print methods
+#' @param x An object of class `"file_deploy_result"` as returned by `file_deploy()`
+#' @param ... Additional arguments passed to other print methods (not used)
+#'
+#' @return 
+#' Invisibly returns the original input data frame unchanged.
+#' 
+#' Displays a formatted summary of deployment results to the console.
 #'
-#' @return Invisibly returns the input data frame
 #' @export
 #'
-#' @examples
-#' \dontrun{
-#' results <- file_deploy("local/file.R", "remote/file.R", repos)
+#' @examplesIf interactive()
+#' # Get list of repositories
+#' repositories <- repos("my-organization")
+#' 
+#' # Deploy files
+#' results <- file_deploy("local/file.R", "remote/file.R", repositories)
+#' 
+#' # Explicitly print the summary
 #' print(results)
-#' }
 print.file_deploy_result <- function(x, ...) {
   # Summary
   status_counts <- table(x$status)