Spec Brainstorming

brainstorm/add.md

@@ -0,0 +1,45 @@
+# `dvs add`
+
+Goal: Add files to an initialized dvs repository.
+
+- [ ] Currently the `message` is attached to all files checked in simultaneously.
+  dvs has a log and audit log to
+  illuminate "why" a change occurred in the data.
+
+<!-- TODO: how do we enhance the why illumination? -->
+
+## CLI
+
+- Assume that current directory is a dvs repository, both in cli and R-package.
+- The option to return `--json` must be present.
+
+## R
+
+Signature:
+
+```r
+dvs_add <- function(
+  files = character(), 
+  glob = character(),
+  ignore.case = NULL %||% !is.empty(glob),
+  overwrite = FALSE,
+  fail = FALSE
+)
+```
+
+## Compression
+
+If the added file exceeds a certain threshold, the
+R package should provide suggest compressing the recently added file.
+
+- [ ] `getOption(dvs.large_file_size = integer()`)
+  - Hard limit 100 MB [PMx-project-template](https://github.com/A2-ai/template-PMx-project-starter/blob/main/.lefthook/pre-commit/file-size)
+  - Soft limit 50 MB (warning emitted) [PMx-project-template](https://github.com/A2-ai/template-PMx-project-starter/blob/main/.lefthook/pre-commit/file-size)
+
+Advice compression when
+
+- a single size exceeds size thresholds
+- a directory of files exceeds size thresholds
+
+There are cases where individual files are not large, but the collection of files
+starts to amount to a large amount, presumably too large to track.

brainstorm/alias_git.md

@@ -0,0 +1,5 @@
+# Alias dvs with get terminology
+
+- [ ] (future?) Should dvs-cli and dvs-rpkg have a --git-mode, where we
+expose a git compatible interface to dvs, in order to
+plug-in dvs as a git replacement?

brainstorm/audit.md

@@ -0,0 +1,38 @@
+# `dvs audit`
+
+Goal: Provide a repository wide log of dvs tracked files.
+
+## CLI
+
+The option to return `--json` must be present.
+
+```sh
+$ dvs audit
+[Date] [User] [+{files} -{files}] [Message]
+```
+
+```sh
+$ dvs audit --since <date|duration>
+```
+
+## R
+
+Signature:
+
+```r
+dvs_audit <- function(
+  since = NULL, # date | duration (unit)
+  by_user = character())
+
+```
+
+
+
+```r
+dvs_audit()
+
+```
+
+```r
+dvs_audit(since = NULL)
+```

brainstorm/configuration.md

@@ -0,0 +1,5 @@
+# `dvs.toml`
+
+
+Configuration should track which patterns are tracked [DVS Tracking](./tracking.md).
+

brainstorm/delete.md

@@ -0,0 +1,29 @@
+# `dvs delete`
+
+Goal: Remove tracked files.
+
+## CLI
+
+```shell
+$ dvs delete
+
+```
+
+## R package
+
+```r
+dvs_delete <- function(
+  files = character(), 
+  glob = character(),
+  ignore.case = NULL %||% !is.empty(glob),
+  fail = FALSE
+)
+```
+
+Aliases: `dvs_delete`, `dvs_remove`, `dvs_rm`.
+
+- `files`: list of files that are to be deleted.
+
+### Non-existing files
+
+Emit a warning, but still remove the files that do exist and are tracked.

brainstorm/dvs_last.md

@@ -0,0 +1,10 @@
+# `dvs_last`
+
+Goal: provide users with the ability to retrieve the result of
+the last executed dvs command within the r package.
+
+Example: Suppose after `dvs_add(by_folder = "data/derived/*")` was executed
+an error occurred, and an overview is displayed as a data-frame. The user
+got a R native result, a data-frame, but if the user wants to act on the
+provided information, we might want to provide a `dvs_last` that contains
+miscellaneous.

brainstorm/enum_status.md

@@ -0,0 +1,39 @@
+# Configuration: Status
+
+- current | absent | unsynced
+- tracked file that is un-added
+
+
+
+# TODO (editing needed)
+
+    relative_path: relative path to the file with respect to where the operation was called
+
+    status: (doesn’t include error status)
+
+        current: the file is present in the project directory and matches the version in the storage directory
+
+        absent: the file isn't present in the project directory
+
+        unsynced: the file is present in the project directory, but doesn't match the version on in the storage directory
+
+    file_size_bytes: current size of the file in bytes
+
+    time_stamp: the ISO 8601 Zulu time of the most recent file version in the storage directory 
+
+    saved_by: the user who uploaded the most recent file version in the storage directory
+
+    message: the message inputted to the dvs_add command that added the most recent file version in the storage directory
+
+    blake3_checksum: hash of the file via the blake3 algorithm
+
+    absolute_path: canonicalized path of the file
+  input:
+
+    If inputted explicitly via file glob or path: the file name
+
+    if inputted implicitly via dvs_status() (without input): NA
+
+error: if the outcome was error, the error type, else NA
+
+error message: if the outcome was error, the error message (if there was one), else NA

brainstorm/follow.md

@@ -0,0 +1,19 @@
+# `dvs track` / `dvs_track`
+
+Goal: Purpose is to specify which files we ought to follow in dvs. 
+
+User journey: 
+
+- [ ] All the .csv files underneath a specific directory.
+- [ ] All the .csv files that are less than 25 MB
+
+- File type
+- Size filters
+
+- [ ] MOSSA: We may want to not track too large files, even if they are .csv
+- [ ] pre-hook 100mb limit see template-PMx-project-starter
+
+Cloned repositories do not have hooks!
+
+- [ ] MOSSA: Filtering **/* but only the tracked files by dvs!
+- [ ] 

brainstorm/get.md

@@ -0,0 +1,20 @@
+# `dvs get`
+
+## CLI
+
+The option to return `--json` must be present.
+
+## R
+
+Signature:
+
+```r
+dvs_get <- function(
+  files = character(),
+  glob = character(),
+  ignore.case = NULL %||% !is.empty(glob),
+  fail = FALSE # follows fs::dir_ls
+)
+```
+
+