From ac522b6fd675230da905c0b54b241904e6c76705 Mon Sep 17 00:00:00 2001 From: RavenMarQ <143663502+RavenMarQ@users.noreply.github.com> Date: Sun, 8 Dec 2024 03:02:52 -1000 Subject: [PATCH] i #308 Add Scitools Understand Parser Adds Scitools Understand Dependencies parser for files and classes. --------- Signed-off-by: Carlos Paradis Co-authored-by: Nicholas Beydler Co-authored-by: Carlos Paradis --- DESCRIPTION | 3 +- NAMESPACE | 4 + NEWS.md | 1 + R/src.R | 202 ++++++++++++++++++ _pkgdown.yml | 4 + conf/helix.yml | 15 +- conf/kaiaulu.yml | 15 -- man/build_understand_project.Rd | 46 ++++ man/export_understand_dependencies.Rd | 52 +++++ ...e_bugzilla_perceval_rest_issue_comments.Rd | 5 +- ...lla_perceval_traditional_issue_comments.Rd | 5 +- man/parse_bugzilla_rest_comments.Rd | 5 +- man/parse_bugzilla_rest_issues.Rd | 5 +- man/parse_bugzilla_rest_issues_comments.Rd | 5 +- man/parse_commit_message_id.Rd | 5 +- man/parse_dependencies.Rd | 5 +- man/parse_dv8_clusters.Rd | 5 +- man/parse_gitlog.Rd | 5 +- man/parse_jira.Rd | 5 +- man/parse_jira_latest_date.Rd | 5 +- man/parse_jira_rss_xml.Rd | 5 +- man/parse_mbox.Rd | 5 +- man/parse_nvdfeed.Rd | 5 +- man/parse_understand_dependencies.Rd | 34 +++ man/transform_commit_message_id_to_network.Rd | 3 +- man/transform_cve_cwe_file_to_network.Rd | 3 +- man/transform_dependencies_to_network.Rd | 3 +- man/transform_dependencies_to_sdsmj.Rd | 3 +- man/transform_gitlog_to_bipartite_network.Rd | 3 +- ...form_gitlog_to_entity_bipartite_network.Rd | 3 +- ...sform_gitlog_to_entity_temporal_network.Rd | 3 +- man/transform_gitlog_to_hdsmj.Rd | 3 +- man/transform_gitlog_to_temporal_network.Rd | 3 +- man/transform_reply_to_bipartite_network.Rd | 3 +- man/transform_temporal_gitlog_to_adsmj.Rd | 3 +- ...form_understand_dependencies_to_network.Rd | 31 +++ tools.yml | 2 + vignettes/understand_showcase.Rmd | 137 ++++++++++++ 38 files changed, 607 insertions(+), 42 deletions(-) create mode 100644 man/build_understand_project.Rd create mode 100644 man/export_understand_dependencies.Rd create mode 100644 man/parse_understand_dependencies.Rd create mode 100644 man/transform_understand_dependencies_to_network.Rd create mode 100644 vignettes/understand_showcase.Rmd diff --git a/DESCRIPTION b/DESCRIPTION index 7c257f6b..6c7a1bec 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,7 +2,7 @@ Package: kaiaulu Type: Package Title: Kaiaulu Version: 0.0.0.9700 -Description: Kaiaulu is an R package and common interface that helps with understanding evolving software development communities, and the artifacts (gitlog, mailing list, files, etc.) which developers collaborate and communicate about. See Paradis et al., (2012) . +Description: Kaiaulu is an R package and common interface that helps with understanding evolving software development communities, and the artifacts (gitlog, mailing list, files, etc.) which developers collaborate and communicate about. See Paradis et al., (2012) . Authors@R: c( person('Carlos', 'Paradis', role = c('aut', 'cre'), email = 'cvas@hawaii.edu', @@ -21,6 +21,7 @@ Authors@R: c( person('Anthony', 'Lau', role = c('ctb')), person('Sean', 'Sunoo', role = c('ctb')), person('Ian Jaymes', 'Iwata', role= c('ctb')), + person('Raven', 'Quiddaoen', role= c('ctb')), person('Nicholas', 'Beydler', role = c('ctb')), person('Mark', 'Burgess', role = c('ctb')) ) diff --git a/NAMESPACE b/NAMESPACE index e4b818ed..7321af5b 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -3,6 +3,7 @@ export(annotate_src_text) export(assign_exact_identity) export(bipartite_graph_projection) +export(build_understand_project) export(commit_message_id_coverage) export(community_oslom) export(convert_pipermail_to_mbox) @@ -42,6 +43,7 @@ export(example_notebook_alternating_function_in_files) export(example_notebook_function_in_code_blocks) export(example_renamed_file) export(example_test_example_src_repo) +export(export_understand_dependencies) export(filter_by_commit_interval) export(filter_by_commit_size) export(filter_by_file_extension) @@ -189,6 +191,7 @@ export(parse_r_dependencies) export(parse_r_function_definition) export(parse_r_function_dependencies) export(parse_rfile_ast) +export(parse_understand_dependencies) export(query_src_text) export(query_src_text_class_names) export(query_src_text_namespace) @@ -214,6 +217,7 @@ export(transform_gitlog_to_temporal_network) export(transform_r_dependencies_to_network) export(transform_reply_to_bipartite_network) export(transform_temporal_gitlog_to_adsmj) +export(transform_understand_dependencies_to_network) export(weight_scheme_count_deleted_nodes) export(weight_scheme_cum_temporal) export(weight_scheme_pairwise_cum_temporal) diff --git a/NEWS.md b/NEWS.md index 22437260..c9c66cfd 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,6 +3,7 @@ __kaiaulu 0.0.0.9700 (in development)__ ### NEW FEATURES + * `build`, `export` `parse` and `transform` functions for Scitools Understand have been added. [#308](https://github.com/sailuh/kaiaulu/issues/308) * The GitHUB API has been expanded to use refresh, along with other functions. `github_api_project_issue_search` has been added that makes the search/issues endpoint API calls. `github_api_project_issue_or_pr_comments_by_date` and `github_api_project_issue_by_date` have been added to download issue data and comments by date ranges. `github_parse_search_issues_refresh` has been added that parses the issue data downloaded from the search endpoint in the refresh_issues folder. `github_api_project_issue_refresh` and `github_api_project_issue_or_pr_comment_refresh` were added to download issue data or comments respectively that have not already been downloaded. `format_created_at_from_file` was added to retrieve the greatest date from a JSON file. See the Reference Docs on GitHub section for more details. [#282](https://github.com/sailuh/kaiaulu/issues/282) * `config.R` now contains a set of getter functions used to centralize the gathering of configuration data and these getter functions are used to refactor configuration file information gathering. For example, loading configuration file information with variable assignment is as follows `git_repo_path <- config_file[["version_control"]][["log"]]` but refactoring with a config.R getter function becomes `git_repo_path <- get_git_repo_path(config_file)`. [#230](https://github.com/sailuh/kaiaulu/issues/230) * `refresh_jira_issues()` had been added. It is a wrapper function for the previous downloader and downloads only issues greater than the greatest key already downloaded. [#275](https://github.com/sailuh/kaiaulu/issues/275) diff --git a/R/src.R b/R/src.R index da5b9d9a..ea3b3465 100644 --- a/R/src.R +++ b/R/src.R @@ -4,8 +4,174 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at https://mozilla.org/MPL/2.0/. +############## Understand Project Builder ############## + +#' Build Understand DB +#' +#' Uses Scitools Understand to create a source code project Und Database. +#' +#' @param scitools_path path to the scitools binary `und` +#' @param project_path path to the project source code folder to create the Understand DB. +#' @param language the primary language of the project (language must be supported by Understand) +#' @param output_dir path to output directory (formatted output_path/) +#' +#' @return The created Scitools Understand DB path +#' @references See pg. 352 in https://documentation.scitools.com/pdf/understand.pdf Sept. 2024 Edition +#' @export +#' @family parsers +build_understand_project <- function(scitools_path, project_path, language, output_dir){ + + scitools_path <- path.expand(scitools_path) + + # Create variables for command line + command <- scitools_path + project_path <- shQuote(project_path) # Quoting the project path + db_dir <- file.path(output_dir, "Understand.und") + args <- c("create", "-db", db_dir, "-languages", language) + + # Build the Understand project by parsing through using Understand's und command + build_output <- system2(command, args) + args <- c("-db", db_dir, "add", project_path) + db_output <- system2(command, args) + analyze_output <- args <- c("analyze", db_dir) + output <- system2(command, args) + + return(db_dir) + +} + +#' Extract Understand Dependencies +#' +#' Extract the XML dependency file for either class or file granularity from +#' an understand DB. +#' +#' @param scitools_path path to the scitools binary `und` +#' @param db_path path to the scitools DB (see \code{\link{build_understand_project}}) +#' @param parse_type Type of dependencies to generate into xml (either "file" or "class") +#' @param output_filepath path to the output XML filepath of dependencies +#' +#' @return The output directory where the db will be created, i.e. output_dir parameter. +#' @references See pg. 352 in https://documentation.scitools.com/pdf/understand.pdf Sept. 2024 Edition +#' @export +#' @family parsers +export_understand_dependencies <- function(scitools_path, db_filepath, parse_type = c("file", "class"), output_filepath){ + + scitools_path <- path.expand(scitools_path) + + # Before running, check if parse_type is correct + parse_type <- match.arg(parse_type) + + # Create the variables used in command lines + #db_dir <- file.path(understand_dir, "Understand.und") + + #file_name <- paste0(parse_type, "Dependencies.xml") + #xml_dir <- file.path(db_dir, file_name) + + # Generate the XML file + # Derived from pg. 352 in https://documentation.scitools.com/pdf/understand.pdf Sept. 2024 Edition + args <- c("export", "-dependencies", parse_type, "cytoscape", output_filepath, db_filepath) + output <- system2(scitools_path, args) + + return(output_filepath) + + # Generated XML file is assumed to be in this approximate format (regardless of parse_type) using Understand Build 1202 + # + # ... [Irrelevant graph attributes and rdf grandchildren] + # + # + # + # + # + # + # + # + # ... [Other nodes sharing the format] + # + # + # + # + # + # + # + # ... [Other edges sharing the format] + + +} + ############## Parsers ############## +#' Parse Scitools Understand Dependencies XML +#' +#' Parses either a file or class scitools understand dependency XML to table. +#' +#' @param dependencies_path path to the exported Understand dependencies file (see \code{\link{export_understand_dependencies}}). +#' @export +#' @family parsers +parse_understand_dependencies <- function(dependencies_path) { + + # Parse the XML file + xml_data <- xmlParse(dependencies_path) # Creates pointer to file + xml_nodes <- xmlRoot(xml_data) # Finds the head: graph + xml_nodes <- xmlChildren(xml_nodes) + # xml_nodes now contains the nodes and edges (which were children of graph) and also graph's atts + + # From child nodes- filter for those with name "node" + # Create a list by iterating through all the children in xml_nodes + node_elements <- lapply(xml_nodes, function(child) { + if (xmlName(child) == "node") { # We're searching for nodes, not att or edges + id <- xmlGetAttr(child, "id") # Extract the id from the node line + att_nodes <- xmlChildren(child) # To access the atts of the node + node_label <- xmlGetAttr(att_nodes[[3]], "value") # Relevant att is the 3rd line + long_name <- xmlGetAttr(att_nodes[[4]], "value") # Relevant att is the 4th line + return(data.table(node_label = node_label, id = id, long_name = long_name)) # Returns the table containing the filtered node data + } else { + return(NULL) # Return NULL for the entry to be filtered out later + } + }) + + # Remove NULLs and combine the results from the node_elements list + node_list <- rbindlist(node_elements[!sapply(node_elements, is.null)], use.names = TRUE, fill = TRUE) + + # From child nodes- filter for those with name "edge" + # Create a list by iterating through all the children in xml_nodes + edge_elements <- lapply(xml_nodes, function(child) { + if (xmlName(child) == "edge") { # We're searching for edges, not att or nodes + # Extract the id_from and id_to from the edge line + id_from <- xmlGetAttr(child, "source") + id_to <- xmlGetAttr(child, "target") + att_nodes <- xmlChildren(child) # To access the atts of the edge + dependency_kind <- xmlGetAttr(att_nodes[[5]], "value") # Relevant att is the 5th line + # Error handling for empty and NULL dependency_kind (this is necessary as errors do occur even in the formatted style) + # Code correctly handles all the edges, however produces error if error handling is not included... so... + if (!is.null(dependency_kind) && dependency_kind != "") { + dependency_kind <- unlist(stri_split(dependency_kind, regex = ",\\s*")) # Separates the string into a vector + return(data.table(id_from = id_from, id_to = id_to, dependency_kind = dependency_kind)) # Returns the table containing the filtered node data + } else { + return(NULL) # Return NULL for the entry to be filtered out later + } + } else { + return(NULL) # Return NULL for the entry to be filtered out later + } + }) + + # Remove NULLs and combine the results from the edge_elements list + edge_list <- rbindlist(edge_elements[!sapply(edge_elements, is.null)], use.names = TRUE, fill = TRUE) + + # Merge edges with nodes to get label_from + edge_list <- merge(edge_list, node_list[, .(id, node_label)], by.x = "id_from", by.y = "id", all.x = TRUE) + setnames(edge_list, "node_label", "label_from") + + # Merge again to get label_to + edge_list <- merge(edge_list, node_list[, .(id, node_label)], by.x = "id_to", by.y = "id", all.x = TRUE) + setnames(edge_list, "node_label", "label_to") + + # Reorder columns to have label_from and label_to on the left + edge_list <- edge_list[, .(label_from, label_to, id_from, id_to, dependency_kind)] + + # Create a list of the network to return + graph <- list(node_list = node_list, edge_list = edge_list) + return(graph) +} #' Parse dependencies from Depends #' @@ -215,6 +381,42 @@ parse_r_dependencies <- function(folder_path){ ############## Network Transform ############## +#' Transform Understand Dependencies +#' +#' @description This function subsets a parsed table from parse_understand_dependencies +#' +#' @param parsed Parsed table from \code{\link{parse_understand_dependencies}} +#' @param weight_types The weight types as defined in Depends. Accepts single string and vector input +#' @export +#' @family edgelists +transform_understand_dependencies_to_network <- function(parsed, weight_types) { + + nodes <- parsed[["node_list"]] + edges <- parsed[["edge_list"]] + + # Create an ID column, as the file name in a label may occur + # again in other parts of the code. + + nodes$node_label <- stringi::stri_c(nodes$node_label,"|",nodes$id) + + edges$label_from <- stringi::stri_c(edges$label_from,"|",edges$id_from) + edges$label_to <- stringi::stri_c(edges$label_to,"|",edges$id_to) + + # Filter out by weights if vector provided + if (length(weight_types) > 0) { + edges <- edges[dependency_kind %in% weight_types] + } + + # If filter removed all edges: + if (nrow(edges) == 0) { + stop("Error: No edges found under weight_types.") + } + + # Create a list to return + graph <- list(node_list = nodes, edge_list = edges) + return(graph) +} + #' Transform parsed dependencies into a network #' #' @param depends_parsed A parsed mbox by \code{\link{parse_dependencies}}. diff --git a/_pkgdown.yml b/_pkgdown.yml index 5df12100..aede9d0c 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -25,8 +25,12 @@ reference: Notebooks for examples. - contents: - parse_dependencies + - build_understand_project + - export_understand_dependencies + - parse_understand_dependencies - parse_r_dependencies - transform_dependencies_to_network + - transform_understand_dependencies_to_network - transform_r_dependencies_to_network - subtitle: __Gang of Four Patterns__ desc: > diff --git a/conf/helix.yml b/conf/helix.yml index 9acd7804..aedf0a58 100644 --- a/conf/helix.yml +++ b/conf/helix.yml @@ -219,7 +219,20 @@ tool: # project_path: ../../rawdata/kaiaulu/git_repo/understand/ # # Where the output for the understands analysis is stored # output_path: ../../analysis/kaiaulu/understand/ - + understand: + # Accepts one language at a time: ada, assembly, c/c++, c#, fortran, java, jovial, delphi/pascal, python, vhdl, basic, javascript + code_language: java + # Specify which types of Dependencies to keep + keep_dependencies_type: + - Import + - Call + - Create + - Use + - Type GenericArgument + # Where the files to analyze should be stored + project_path: ../../rawdata/helix/git_repo/helix/ + # Where the output for the understands analysis is stored + output_path: ../../analysis/helix/understand/ # Analysis Configuration # analysis: # You can specify the intervals in 2 ways: window, or enumeration diff --git a/conf/kaiaulu.yml b/conf/kaiaulu.yml index 14cc2ed9..800e4b44 100644 --- a/conf/kaiaulu.yml +++ b/conf/kaiaulu.yml @@ -208,21 +208,6 @@ tool: # 3. Use sudo ./gradlew build # 4. After building, locate the engine class files and specify as the class_folder_path: # in this case they are in: /path/to/junit5/analysis/junit-platform-engine/build/classes/java/main/org/junit/platform/engine/ - understand: - # Accepts one language at a time: ada, assembly, c/c++, c#, fortran, java, jovial, delphi/pascal, python, vhdl, basic, javascript - code_language: java - # Specify which types of Dependencies to keep - keep_dependencies_type: - - Import - - Call - - Create - - Use - - Type GenericArgument - # Where the files to analyze should be stored - project_path: ../../rawdata/kaiaulu/git_repo/understand/ - # Where the output for the understands analysis is stored - output_path: ../../analysis/kaiaulu/understand/ - # Analysis Configuration # analysis: diff --git a/man/build_understand_project.Rd b/man/build_understand_project.Rd new file mode 100644 index 00000000..adb43563 --- /dev/null +++ b/man/build_understand_project.Rd @@ -0,0 +1,46 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/src.R +\name{build_understand_project} +\alias{build_understand_project} +\title{Build Understand DB} +\usage{ +build_understand_project(scitools_path, project_path, language, output_dir) +} +\arguments{ +\item{scitools_path}{path to the scitools binary `und`} + +\item{project_path}{path to the project source code folder to create the Understand DB.} + +\item{language}{the primary language of the project (language must be supported by Understand)} + +\item{output_dir}{path to output directory (formatted output_path/)} +} +\value{ +The created Scitools Understand DB path +} +\description{ +Uses Scitools Understand to create a source code project Und Database. +} +\references{ +See pg. 352 in https://documentation.scitools.com/pdf/understand.pdf Sept. 2024 Edition +} +\seealso{ +Other parsers: +\code{\link{export_understand_dependencies}()}, +\code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, +\code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, +\code{\link{parse_bugzilla_rest_comments}()}, +\code{\link{parse_bugzilla_rest_issues_comments}()}, +\code{\link{parse_bugzilla_rest_issues}()}, +\code{\link{parse_commit_message_id}()}, +\code{\link{parse_dependencies}()}, +\code{\link{parse_dv8_clusters}()}, +\code{\link{parse_gitlog}()}, +\code{\link{parse_jira_latest_date}()}, +\code{\link{parse_jira_rss_xml}()}, +\code{\link{parse_jira}()}, +\code{\link{parse_mbox}()}, +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} +} +\concept{parsers} diff --git a/man/export_understand_dependencies.Rd b/man/export_understand_dependencies.Rd new file mode 100644 index 00000000..a14503df --- /dev/null +++ b/man/export_understand_dependencies.Rd @@ -0,0 +1,52 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/src.R +\name{export_understand_dependencies} +\alias{export_understand_dependencies} +\title{Extract Understand Dependencies} +\usage{ +export_understand_dependencies( + scitools_path, + db_filepath, + parse_type = c("file", "class"), + output_filepath +) +} +\arguments{ +\item{scitools_path}{path to the scitools binary `und`} + +\item{parse_type}{Type of dependencies to generate into xml (either "file" or "class")} + +\item{output_filepath}{path to the output XML filepath of dependencies} + +\item{db_path}{path to the scitools DB (see \code{\link{build_understand_project}})} +} +\value{ +The output directory where the db will be created, i.e. output_dir parameter. +} +\description{ +Extract the XML dependency file for either class or file granularity from +an understand DB. +} +\references{ +See pg. 352 in https://documentation.scitools.com/pdf/understand.pdf Sept. 2024 Edition +} +\seealso{ +Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, +\code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, +\code{\link{parse_bugzilla_rest_comments}()}, +\code{\link{parse_bugzilla_rest_issues_comments}()}, +\code{\link{parse_bugzilla_rest_issues}()}, +\code{\link{parse_commit_message_id}()}, +\code{\link{parse_dependencies}()}, +\code{\link{parse_dv8_clusters}()}, +\code{\link{parse_gitlog}()}, +\code{\link{parse_jira_latest_date}()}, +\code{\link{parse_jira_rss_xml}()}, +\code{\link{parse_jira}()}, +\code{\link{parse_mbox}()}, +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} +} +\concept{parsers} diff --git a/man/parse_bugzilla_perceval_rest_issue_comments.Rd b/man/parse_bugzilla_perceval_rest_issue_comments.Rd index d8788d60..2616e16b 100644 --- a/man/parse_bugzilla_perceval_rest_issue_comments.Rd +++ b/man/parse_bugzilla_perceval_rest_issue_comments.Rd @@ -24,6 +24,8 @@ Parse Bugzilla data obtained from Perceval REST API Bugzilla backend \code{\link{download_bugzilla_perceval_rest_issue_comments}} a donwoloader function download bugzilla data with perceval Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, \code{\link{parse_bugzilla_rest_issues_comments}()}, @@ -36,6 +38,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_bugzilla_perceval_traditional_issue_comments.Rd b/man/parse_bugzilla_perceval_traditional_issue_comments.Rd index 06f9397d..8d22b68c 100644 --- a/man/parse_bugzilla_perceval_traditional_issue_comments.Rd +++ b/man/parse_bugzilla_perceval_traditional_issue_comments.Rd @@ -24,6 +24,8 @@ Parse Bugzilla data obtained from Perceval traditional Bugzilla backend \code{\link{download_bugzilla_perceval_traditional_issue_comments}} a downloader function to download bugzilla data with perceval Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, \code{\link{parse_bugzilla_rest_issues_comments}()}, @@ -36,6 +38,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_bugzilla_rest_comments.Rd b/man/parse_bugzilla_rest_comments.Rd index 8121d873..4c23b9c8 100644 --- a/man/parse_bugzilla_rest_comments.Rd +++ b/man/parse_bugzilla_rest_comments.Rd @@ -17,6 +17,8 @@ Parse Bugzilla comments data obtained from json files from Bugzilla crawler \cod } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_issues_comments}()}, @@ -29,6 +31,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_bugzilla_rest_issues.Rd b/man/parse_bugzilla_rest_issues.Rd index 69d55e6b..6d1a7086 100644 --- a/man/parse_bugzilla_rest_issues.Rd +++ b/man/parse_bugzilla_rest_issues.Rd @@ -19,6 +19,8 @@ Parse Bugzilla issues data obtained from json files from Bugzilla crawler \code{\link{download_bugzilla_rest_issues_comments}} a downloader function to parse Bugzilla issues and comments data Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -31,6 +33,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_bugzilla_rest_issues_comments.Rd b/man/parse_bugzilla_rest_issues_comments.Rd index 68939e2c..cda90b6c 100644 --- a/man/parse_bugzilla_rest_issues_comments.Rd +++ b/man/parse_bugzilla_rest_issues_comments.Rd @@ -21,6 +21,8 @@ Parse Bugzilla issues and comments data table \code{\link{download_bugzilla_rest_issues_comments}} a downloader function to parse Bugzilla issues and comments data Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -33,6 +35,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_commit_message_id.Rd b/man/parse_commit_message_id.Rd index 1fe5fd3f..caef84ed 100644 --- a/man/parse_commit_message_id.Rd +++ b/man/parse_commit_message_id.Rd @@ -16,6 +16,8 @@ Adds a column commit_message_id containing the parsed commit message } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -28,6 +30,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_dependencies.Rd b/man/parse_dependencies.Rd index 9cd9d487..062bbf5b 100644 --- a/man/parse_dependencies.Rd +++ b/man/parse_dependencies.Rd @@ -25,6 +25,8 @@ Parse dependencies from Depends } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -37,6 +39,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_dv8_clusters.Rd b/man/parse_dv8_clusters.Rd index 474205be..524e4d40 100644 --- a/man/parse_dv8_clusters.Rd +++ b/man/parse_dv8_clusters.Rd @@ -14,6 +14,8 @@ Parses a cluster *-clsx.json into a data table. } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -26,7 +28,8 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} Other dv8: \code{\link{dependencies_to_sdsmj}()}, diff --git a/man/parse_gitlog.Rd b/man/parse_gitlog.Rd index 5552e83c..5a0c8cad 100644 --- a/man/parse_gitlog.Rd +++ b/man/parse_gitlog.Rd @@ -20,6 +20,8 @@ Parses the `.git` file in a github repository using the Perceval library. } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -32,6 +34,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_jira.Rd b/man/parse_jira.Rd index 26b2da1f..b0363181 100644 --- a/man/parse_jira.Rd +++ b/man/parse_jira.Rd @@ -30,6 +30,8 @@ If a field is not present in an issue, then its value will be NA. } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -42,6 +44,7 @@ Other parsers: \code{\link{parse_jira_latest_date}()}, \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_jira_latest_date.Rd b/man/parse_jira_latest_date.Rd index f5b8b18f..e92216bd 100644 --- a/man/parse_jira_latest_date.Rd +++ b/man/parse_jira_latest_date.Rd @@ -22,6 +22,8 @@ For example: "SAILUH_1231234_2312413.json". This nomenclature is defined by \cod } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -34,6 +36,7 @@ Other parsers: \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_jira_rss_xml.Rd b/man/parse_jira_rss_xml.Rd index 38bb6948..1043f976 100644 --- a/man/parse_jira_rss_xml.Rd +++ b/man/parse_jira_rss_xml.Rd @@ -25,6 +25,8 @@ in IEEE Transactions on Software Engineering, vol. 48, no. 8, pp. 3159-3184, } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -37,6 +39,7 @@ Other parsers: \code{\link{parse_jira_latest_date}()}, \code{\link{parse_jira}()}, \code{\link{parse_mbox}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_mbox.Rd b/man/parse_mbox.Rd index f048bd48..8b8ad909 100644 --- a/man/parse_mbox.Rd +++ b/man/parse_mbox.Rd @@ -20,6 +20,8 @@ consistently renamed for clarity. } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -32,6 +34,7 @@ Other parsers: \code{\link{parse_jira_latest_date}()}, \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, -\code{\link{parse_nvdfeed}()} +\code{\link{parse_nvdfeed}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_nvdfeed.Rd b/man/parse_nvdfeed.Rd index e861f2a3..7b49c51c 100644 --- a/man/parse_nvdfeed.Rd +++ b/man/parse_nvdfeed.Rd @@ -15,6 +15,8 @@ Parse NVD Feed CVEs, descriptions and CWE ids } \seealso{ Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, \code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, \code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, \code{\link{parse_bugzilla_rest_comments}()}, @@ -27,6 +29,7 @@ Other parsers: \code{\link{parse_jira_latest_date}()}, \code{\link{parse_jira_rss_xml}()}, \code{\link{parse_jira}()}, -\code{\link{parse_mbox}()} +\code{\link{parse_mbox}()}, +\code{\link{parse_understand_dependencies}()} } \concept{parsers} diff --git a/man/parse_understand_dependencies.Rd b/man/parse_understand_dependencies.Rd new file mode 100644 index 00000000..4411d5dd --- /dev/null +++ b/man/parse_understand_dependencies.Rd @@ -0,0 +1,34 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/src.R +\name{parse_understand_dependencies} +\alias{parse_understand_dependencies} +\title{Parse Scitools Understand Dependencies XML} +\usage{ +parse_understand_dependencies(dependencies_path) +} +\arguments{ +\item{dependencies_path}{path to the exported Understand dependencies file (see \code{\link{export_understand_dependencies}}).} +} +\description{ +Parses either a file or class scitools understand dependency XML to table. +} +\seealso{ +Other parsers: +\code{\link{build_understand_project}()}, +\code{\link{export_understand_dependencies}()}, +\code{\link{parse_bugzilla_perceval_rest_issue_comments}()}, +\code{\link{parse_bugzilla_perceval_traditional_issue_comments}()}, +\code{\link{parse_bugzilla_rest_comments}()}, +\code{\link{parse_bugzilla_rest_issues_comments}()}, +\code{\link{parse_bugzilla_rest_issues}()}, +\code{\link{parse_commit_message_id}()}, +\code{\link{parse_dependencies}()}, +\code{\link{parse_dv8_clusters}()}, +\code{\link{parse_gitlog}()}, +\code{\link{parse_jira_latest_date}()}, +\code{\link{parse_jira_rss_xml}()}, +\code{\link{parse_jira}()}, +\code{\link{parse_mbox}()}, +\code{\link{parse_nvdfeed}()} +} +\concept{parsers} diff --git a/man/transform_commit_message_id_to_network.Rd b/man/transform_commit_message_id_to_network.Rd index 04af4987..e66752bd 100644 --- a/man/transform_commit_message_id_to_network.Rd +++ b/man/transform_commit_message_id_to_network.Rd @@ -25,6 +25,7 @@ Other edgelists: \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} } \concept{edgelists} diff --git a/man/transform_cve_cwe_file_to_network.Rd b/man/transform_cve_cwe_file_to_network.Rd index cea7aac3..9cbc0b46 100644 --- a/man/transform_cve_cwe_file_to_network.Rd +++ b/man/transform_cve_cwe_file_to_network.Rd @@ -25,6 +25,7 @@ Other edgelists: \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} } \concept{edgelists} diff --git a/man/transform_dependencies_to_network.Rd b/man/transform_dependencies_to_network.Rd index 7d051f76..79f10ca4 100644 --- a/man/transform_dependencies_to_network.Rd +++ b/man/transform_dependencies_to_network.Rd @@ -25,6 +25,7 @@ Other edgelists: \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} } \concept{edgelists} diff --git a/man/transform_dependencies_to_sdsmj.Rd b/man/transform_dependencies_to_sdsmj.Rd index a9eeb0fb..6d477988 100644 --- a/man/transform_dependencies_to_sdsmj.Rd +++ b/man/transform_dependencies_to_sdsmj.Rd @@ -39,7 +39,8 @@ Other edgelists: \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} Other dv8: \code{\link{dependencies_to_sdsmj}()}, diff --git a/man/transform_gitlog_to_bipartite_network.Rd b/man/transform_gitlog_to_bipartite_network.Rd index 052de1be..1bc147b7 100644 --- a/man/transform_gitlog_to_bipartite_network.Rd +++ b/man/transform_gitlog_to_bipartite_network.Rd @@ -28,6 +28,7 @@ Other edgelists: \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} } \concept{edgelists} diff --git a/man/transform_gitlog_to_entity_bipartite_network.Rd b/man/transform_gitlog_to_entity_bipartite_network.Rd index f95ea70b..9079a048 100644 --- a/man/transform_gitlog_to_entity_bipartite_network.Rd +++ b/man/transform_gitlog_to_entity_bipartite_network.Rd @@ -28,6 +28,7 @@ Other edgelists: \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} } \concept{edgelists} diff --git a/man/transform_gitlog_to_entity_temporal_network.Rd b/man/transform_gitlog_to_entity_temporal_network.Rd index 9e02d4d5..5267c903 100644 --- a/man/transform_gitlog_to_entity_temporal_network.Rd +++ b/man/transform_gitlog_to_entity_temporal_network.Rd @@ -45,6 +45,7 @@ Other edgelists: \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} } \concept{edgelists} diff --git a/man/transform_gitlog_to_hdsmj.Rd b/man/transform_gitlog_to_hdsmj.Rd index 4c766638..4072dbde 100644 --- a/man/transform_gitlog_to_hdsmj.Rd +++ b/man/transform_gitlog_to_hdsmj.Rd @@ -37,7 +37,8 @@ Other edgelists: \code{\link{transform_gitlog_to_entity_temporal_network}()}, \code{\link{transform_gitlog_to_temporal_network}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} Other dv8: \code{\link{dependencies_to_sdsmj}()}, diff --git a/man/transform_gitlog_to_temporal_network.Rd b/man/transform_gitlog_to_temporal_network.Rd index 67219e27..109c7e38 100644 --- a/man/transform_gitlog_to_temporal_network.Rd +++ b/man/transform_gitlog_to_temporal_network.Rd @@ -47,6 +47,7 @@ Other edgelists: \code{\link{transform_gitlog_to_entity_temporal_network}()}, \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_reply_to_bipartite_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} } \concept{edgelists} diff --git a/man/transform_reply_to_bipartite_network.Rd b/man/transform_reply_to_bipartite_network.Rd index 84168bdf..a6011f65 100644 --- a/man/transform_reply_to_bipartite_network.Rd +++ b/man/transform_reply_to_bipartite_network.Rd @@ -23,6 +23,7 @@ Other edgelists: \code{\link{transform_gitlog_to_entity_temporal_network}()}, \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, -\code{\link{transform_temporal_gitlog_to_adsmj}()} +\code{\link{transform_temporal_gitlog_to_adsmj}()}, +\code{\link{transform_understand_dependencies_to_network}()} } \concept{edgelists} diff --git a/man/transform_temporal_gitlog_to_adsmj.Rd b/man/transform_temporal_gitlog_to_adsmj.Rd index 3f968ac4..27bd6aad 100644 --- a/man/transform_temporal_gitlog_to_adsmj.Rd +++ b/man/transform_temporal_gitlog_to_adsmj.Rd @@ -35,7 +35,8 @@ Other edgelists: \code{\link{transform_gitlog_to_entity_temporal_network}()}, \code{\link{transform_gitlog_to_hdsmj}()}, \code{\link{transform_gitlog_to_temporal_network}()}, -\code{\link{transform_reply_to_bipartite_network}()} +\code{\link{transform_reply_to_bipartite_network}()}, +\code{\link{transform_understand_dependencies_to_network}()} Other dv8: \code{\link{dependencies_to_sdsmj}()}, diff --git a/man/transform_understand_dependencies_to_network.Rd b/man/transform_understand_dependencies_to_network.Rd new file mode 100644 index 00000000..b09eb9a3 --- /dev/null +++ b/man/transform_understand_dependencies_to_network.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/src.R +\name{transform_understand_dependencies_to_network} +\alias{transform_understand_dependencies_to_network} +\title{Transform Understand Dependencies} +\usage{ +transform_understand_dependencies_to_network(parsed, weight_types) +} +\arguments{ +\item{parsed}{Parsed table from \code{\link{parse_understand_dependencies}}} + +\item{weight_types}{The weight types as defined in Depends. Accepts single string and vector input} +} +\description{ +This function subsets a parsed table from parse_understand_dependencies +} +\seealso{ +Other edgelists: +\code{\link{transform_commit_message_id_to_network}()}, +\code{\link{transform_cve_cwe_file_to_network}()}, +\code{\link{transform_dependencies_to_network}()}, +\code{\link{transform_dependencies_to_sdsmj}()}, +\code{\link{transform_gitlog_to_bipartite_network}()}, +\code{\link{transform_gitlog_to_entity_bipartite_network}()}, +\code{\link{transform_gitlog_to_entity_temporal_network}()}, +\code{\link{transform_gitlog_to_hdsmj}()}, +\code{\link{transform_gitlog_to_temporal_network}()}, +\code{\link{transform_reply_to_bipartite_network}()}, +\code{\link{transform_temporal_gitlog_to_adsmj}()} +} +\concept{edgelists} diff --git a/tools.yml b/tools.yml index 27951fe6..df8bc87d 100644 --- a/tools.yml +++ b/tools.yml @@ -17,3 +17,5 @@ oslom_undir: ~/OSLOM2/oslom_undir srcml: /usr/local/bin/srcml # pattern4: https://users.encs.concordia.ca/~nikolaos/pattern_detection.html pattern4: ~/Desktop/kaiaulu/tools/pattern4.jar +# Scitools Understand: https://scitools.com/ +scitools: /Applications/Understand.app/Contents/MacOS/und diff --git a/vignettes/understand_showcase.Rmd b/vignettes/understand_showcase.Rmd new file mode 100644 index 00000000..f8f05314 --- /dev/null +++ b/vignettes/understand_showcase.Rmd @@ -0,0 +1,137 @@ +--- +title: "Understand Showcase" +output: + html_document: + toc: true + number_sections: true +vignette: > + %\VignetteEngine{knitr::rmarkdown} + %\VignetteIndexEntry{Understand Showcase} + %\VignetteEncoding{UTF-8} +--- + + +# Introduction + +Within a project, we might want to see the in-between file or in-between class dependencies. This notebook showcases how to obtain either dependencies using [Scitool's Understand](https://scitools.com)). Note you will need a license from Scitools to use this Notebook. + + +```{r warning = FALSE, message = FALSE} +rm(list = ls()) +require(kaiaulu) +require(visNetwork) +require(XML) +require(stringi) +require(igraph) +require(data.table) +require(gt) +``` + +# Project Configuration File + +For this notebook, we will use Apache Helix as an example. Refer to Helix project configuration file under the conf/ folder, in particular the `understand` section. For supported languages, see [scitools documentation](https://support.scitools.com/support/solutions/articles/70000582794-supported-languages). + +```{r} +tool <- parse_config("../tools.yml") +scitools_path <- get_tool_project("scitools", tool) + +conf <- parse_config("../conf/helix.yml") +keep_dependencies_type <- get_understand_keep_dependencies_type(conf) +project_path <- get_understand_project_path(conf) + +# Scitools +understand_folder <- get_understand_output_path(conf) +code_language <- get_understand_code_language(conf) + +db_path <- stringi::stri_c(understand_folder,"Understand.und") + +file_dependencies_path <- stringi::stri_c(understand_folder,"file_dependencies.xml") +class_dependencies_path <- stringi::stri_c(understand_folder,"class_dependencies.xml") +``` + + +# Build Understand DB + +To export dependencies, scitools require a `und` database to be created: + +```{r eval = FALSE} +db_path <- build_understand_project(scitools_path = scitools_path, project_path = project_path, language = code_language, output_dir = understand_folder) +``` + +# Export Dependencies + +Subsequently, we can make our dependencies export out of the database. We can either export XML files or class dependencies. + +## File Dependencies + +```{r eval = FALSE} +file_dependencies_path <- export_understand_dependencies(scitools_path = scitools_path, db_filepath = db_path, parse_type = "file", output_filepath = file_dependencies_path) +``` + +The XML files can then be parsed into tables for manipulation in Kaiaulu: + +```{r} +file_dependencies <- parse_understand_dependencies(dependencies_path = file_dependencies_path) + +head(file_dependencies[["node_list"]]) %>% + gt(auto_align = FALSE) +``` + +```{r} +head(file_dependencies[["edge_list"]]) %>% + gt(auto_align = FALSE) +``` + + +## Class Dependencies + +The process to export and parse class dependencies is identical, save for specifying the `parse_type` to "class": + +```{r eval = FALSE} +class_dependencies_path <- export_understand_dependencies(scitools_path = scitools_path, db_filepath = db_path, parse_type = "class", output_filepath = class_dependencies_path) +``` + + +```{r} +class_dependencies <- parse_understand_dependencies(dependencies_path = class_dependencies_path) + +head(class_dependencies[["node_list"]]) %>% + gt(auto_align = FALSE) +``` + +```{r} +head(class_dependencies[["edge_list"]]) %>% + gt(auto_align = FALSE) +``` + + +# Network Visualization + +We can display the parsed dependencies as a network. You can use the dependency_kind parameter to subset the dependencies used. Refer to [Kaiaulu wiki](https://github.com/sailuh/kaiaulu/wiki/Scitools) for the types of dependencies Scitools support. + +## File Network + +```{r} +file_graph <- transform_understand_dependencies_to_network(parsed = file_dependencies, weight_types = c(keep_dependencies_type[2], keep_dependencies_type[5])) + + +project_function_network <- igraph::graph_from_data_frame(d=file_graph[["edge_list"]], + directed = TRUE, + vertices = file_graph[["node_list"]]) +visIgraph(project_function_network,randomSeed = 1) +``` + + +## Class Network + +The same applies to outputting our class_dependencies, but we can visualize what our class dependency data is using the same parameters sans the parsed data table. + +```{r} +class_graph <- transform_understand_dependencies_to_network(parsed = class_dependencies, weight_types = c(keep_dependencies_type[2], keep_dependencies_type[5])) + +project_function_network <- igraph::graph_from_data_frame(d=class_graph[["edge_list"]], + directed = TRUE, + vertices = class_graph[["node_list"]]) +visIgraph(project_function_network,randomSeed = 1) +``` +