Skip to contents

Observe a filesystem and construct a reproducible snapshot

Source: R/scan_storage.R
scan_storage.Rd

Recursively scans a root folder and returns a data.frame where each row represents one filesystem observation recorded at a specific time.

Usage

scan_storage(
  root,
  storage_id = "local-storage",
  person_id = "local-user",
  scan_time = Sys.time(),
  compute_signature = TRUE,
  max_signature_size = 200 * 1024 * 1024
)

Arguments

root

Character. Path to the root folder to observe.

storage_id

Character. Identifier of the storage context.

person_id

Character. Identifier of the observer or operator.

scan_time

POSIXct. Timestamp of the observation. Defaults to Sys.time() if not provided.

compute_signature

Logical. Whether to compute lightweight content signatures.

max_signature_size

Numeric. Maximum file size (bytes) for signature computation.

Value

A data.frame where each row represents one filesystem observation.

Details

The function implements a read-only filesystem observation model:

  • it records accessible filesystem state;

  • it does not interpret file contents;

  • it does not assume canonical, complete, or authoritative state.

Each observation records:

  • a relative filesystem locator (rel_path);

  • a storage context (storage_id);

  • an observation timestamp (scan_time).

Additional metadata may include:

  • filesystem properties (size, timestamps, permissions);

  • optional content signatures (quick_sig);

  • repository and version-control context (repo_root, repo_rel_path, git_tracked).

The package deliberately records filesystem observations first and postpones documentary interpretation, Record Set construction, and RiC-aligned semantic assertions to later analytical stages.

This creates a reproducible observational snapshot suitable for:

  • forensic analysis of development environments;

  • reconstruction of activity patterns;

  • audit and compliance workflows;

  • alignment with version-controlled repositories.

The returned dataset at minimum contains:

  • rel_path: relative filesystem locator within the observed root;

  • storage_path_id: deterministic storage-scoped identifier derived from storage_id::rel_path;

  • filename: basename of the observed file;

  • mtime: last modification timestamp;

  • extension: file extension.

Additional variables may be present depending on scan configuration.

The function is:

  • read-only and non-destructive;

  • deterministic for a given filesystem state;

  • robust to inaccessible files, which are silently skipped.

The result represents observed filesystem state rather than complete historical provenance.

See also

snapshot_storage()

Examples

root <- system.file(
  "testdata/minimal_R_folder",
  package = "fscontext"
)

snapshot <- scan_storage(root)
#> Starting scan_storage() on: C:/Users/DanielAntal/AppData/Local/R/win-library/4.5/fscontext/testdata/minimal_R_folder
#> Scanning 15 files.
#> Signatures computed. Detecting repositories and Git status...
#> Files scanned: 15
#> Files in Git repos: 0
#> Files tracked by Git: 0
#> Skipped approximately 0 inaccessible files
#> scan_storage completed in 0.34 seconds

subset(
  snapshot,
  rel_path %in% c(
    "DESCRIPTION",
    "NAMESPACE",
    "R/hello_world.R",
    "vignettes/demo.Rmd"
  )
)[, c("rel_path", "extension")]
#>              rel_path extension
#> 3         DESCRIPTION      <NA>
#> 7           NAMESPACE      <NA>
#> 9     R/hello_world.R         r
#> 15 vignettes/demo.Rmd       rmd