lib/NBI/Manifest.pm

filter: Statementstmt 97.5% 81 / 83 Branchbran 66.6% 12 / 18 Conditioncond 65.9% 29 / 44 MC/DCmcdc 45.0% 9 / 20 Subroutinesub 100% 11 / 11 Podpod 100% 5 / 5 totaltotal 81.2% 147 / 181 CC 33 SCAR 28.2
CC
33
Cov
84%
new
28.9
load
4.1
write
4.0
CRAP 16.8
« lib/NBI/Launcher/Kraken2.pm ↑ Summary blib/lib/NBI/EcoScheduler.pm »
1 package NBI::Manifest;
2 #ABSTRACT: Provenance record for a single nbilaunch job run
3 #
4 # NBI::Manifest - Reads and writes JSON provenance records for nbilaunch.
5 #
6 # DESCRIPTION:
7 # Serialises every input, parameter, output, and Slurm resource used by a
8 # single launcher invocation to a JSON file that lives alongside the results.
9 # Written in two phases:
10 # 1. At submission (by nbilaunch): status "submitted", no job ID yet.
11 # 2. At job end (by injected shell): status "success" or "failure",
12 # exit code, completion time, and checksums are patched in.
13 #
14 # The on-disk format uses JSON::PP with canonical key ordering so that
15 # diffs between runs are clean.
16 #
17 # RELATIONSHIPS:
18 # - Created by NBI::Launcher->build() and written by bin/nbilaunch.
19 # - The injected shell function _nbi_manifest_update patches the file
20 # in-place using a perl one-liner (no jq dependency).
21 # - Complex launchers can chain jobs via NBI::Manifest->load() to read
22 # a previous run's output paths.
23 #
24  
25 2 ▶use 5.012;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
28 2 ▶use Carp qw(confess);
Subroutine BEGIN: called CC=1 SCAR=0.0
29 2 ▶use JSON::PP;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 2 ▶use POSIX qw(strftime);
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 2 $NBI::Manifest::VERSION = $NBI::Slurm::VERSION;
33  
34 # Fields serialised to JSON (in this order, for readability).
35 # The internal _path field is excluded.
36 2 my @JSON_FIELDS = qw(
37 tool tool_version launcher_version nbi_slurm_version
38 submitted_at completed_at
39 slurm_job_id slurm_queue slurm_cpus slurm_mem_gb
40 host user status exit_code sample
41 inputs params outputs
42 outdir scratch checksums script
43 );
44  
45 5 ▶sub new {
Subroutine new: called CC=23 SCAR=33.6
Pod documented
46 5 my ($class, %args) = @_;
47  
48 5 my $self = bless {}, $class;
49  
50 # Required fields
51 5 for my $f (qw(tool sample outdir)) {
52 confess "ERROR NBI::Manifest: missing required field '$f'\n"
53 14 ▶ unless defined $args{$f};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args{$f} 2 12 14
54 }
55  
56 # Populate all known fields with defaults where sensible
57 3 $self->{tool} = $args{tool};
58 3 ▶ $self->{tool_version} = $args{tool_version} // 'unknown';
Condition100%2/2
$args{"tool_version"} // "unknown"
l!l
21
MC/DC100%1/1
$args{"tool_version"} // "unknown"
$args{"tool_version"}
Truth table100%2/2
A
A= $args{"tool_version"}
Aresult
11
00
59 3 ▶ $self->{launcher_version} = $args{launcher_version} // '0.1.0';
Condition50%1/2
$args{"launcher_version"} // "0.1.0"
l!l
03
MC/DC0%0/1
$args{"launcher_version"} // "0.1.0"
$args{"launcher_version"}
Truth table50%1/2
A
A= $args{"launcher_version"}
Aresult
11
00
60 3 ▶ $self->{nbi_slurm_version} = $args{nbi_slurm_version} // ($NBI::Slurm::VERSION // 'unknown');
Condition50%2/4
$args{"nbi_slurm_version"} // ($NBI::Slurm::VERSION // "unknown")
l!l
03
$NBI::Slurm::VERSION // "unknown"
l!l
03
MC/DC0%0/1
$args{"nbi_slurm_version"} // ($NBI::Slurm::VERSION // "unknown")
$args{"nbi_slurm_version"}
Truth table50%1/2
A
A= $args{"nbi_slurm_version"}
Aresult
11
00
61 $self->{submitted_at} = $args{submitted_at}
62 3 ▶ // strftime("%Y-%m-%dT%H:%M:%SZ", gmtime());
Condition33%1/3
$args{"submitted_at"} // strftime("%Y-%m-%dT%H:%M:%SZ", gmtime())
l!l&&r!l&&!r
030
MC/DC0%0/2
$args{"submitted_at"} // strftime("%Y-%m-%dT%H:%M:%SZ", gmtime())
$args{"submitted_at"} strftime("%Y-%m-%dT%H:%M:%SZ", gmtime())
Truth table33%1/3
A // B
A= $args{"submitted_at"}B= strftime("%Y-%m-%dT%H:%M:%SZ", gmtime())
ABresult
1X1
011
000
63 3 $self->{completed_at} = $args{completed_at}; # undef until job ends
64 3 $self->{slurm_job_id} = $args{slurm_job_id}; # undef until submitted
65 3 ▶ $self->{slurm_queue} = $args{slurm_queue} // 'unknown';
Condition100%2/2
$args{"slurm_queue"} // "unknown"
l!l
21
MC/DC100%1/1
$args{"slurm_queue"} // "unknown"
$args{"slurm_queue"}
Truth table100%2/2
A
A= $args{"slurm_queue"}
Aresult
11
00
66 3 ▶ $self->{slurm_cpus} = $args{slurm_cpus} // 1;
Condition100%2/2
$args{"slurm_cpus"} // 1
l!l
21
MC/DC100%1/1
$args{"slurm_cpus"} // 1
$args{"slurm_cpus"}
Truth table100%2/2
A
A= $args{"slurm_cpus"}
Aresult
11
00
67 3 ▶ $self->{slurm_mem_gb} = $args{slurm_mem_gb} // 0;
Condition100%2/2
$args{"slurm_mem_gb"} // 0
l!l
21
MC/DC100%1/1
$args{"slurm_mem_gb"} // 0
$args{"slurm_mem_gb"}
Truth table100%2/2
A
A= $args{"slurm_mem_gb"}
Aresult
11
00
68 $self->{host} = $args{host}
69 // $ENV{HOSTNAME}
70 0 ▶ // do { chomp(my $h = `hostname 2>/dev/null`); $h } // 'unknown';
Condition37%3/8
(($args{"host"} // $ENV{"HOSTNAME"}) // do { chomp(my $h = `hostname 2>/dev/null`); $h }) // "unknown"
l!l
30
($args{"host"} // $ENV{"HOSTNAME"}) // do { chomp(my $h = `hostname 2>/dev/null`); $h }
l!l&&r!l&&!r
300
$args{"host"} // $ENV{"HOSTNAME"}
l!l&&r!l&&!r
030
MC/DC0%0/3
(($args{"host"} // $ENV{"HOSTNAME"}) // do { chomp(my $h = `hostname 2>/dev/null`); $h }) // "unknown"
$args{"host"} $ENV{"HOSTNAME"} do { chomp(my $h = `hostname 2>/dev/null`); $h }
Truth table25%1/4
A // B // C
A= $args{"host"}B= $ENV{"HOSTNAME"}C= do { chomp(my $h = `hostname 2>/dev/null`); $h }
ABCresult
1XX1
01X1
0011
0000
71 3 ▶ $self->{user} = $args{user} // $ENV{USER} // 'unknown';
Condition40%2/5
($args{"user"} // $ENV{"USER"}) // "unknown"
l!l
03
$args{"user"} // $ENV{"USER"}
l!l&&r!l&&!r
003
MC/DC0%0/2
($args{"user"} // $ENV{"USER"}) // "unknown"
$args{"user"} $ENV{"USER"}
Truth table33%1/3
A // B
A= $args{"user"}B= $ENV{"USER"}
ABresult
1X1
011
000
72 3 ▶ $self->{status} = $args{status} // 'submitted';
Condition100%2/2
$args{"status"} // "submitted"
l!l
12
MC/DC100%1/1
$args{"status"} // "submitted"
$args{"status"}
Truth table100%2/2
A
A= $args{"status"}
Aresult
11
00
73 3 $self->{exit_code} = $args{exit_code}; # undef until job ends
74 3 $self->{sample} = $args{sample};
75 3 ▶ $self->{inputs} = $args{inputs} // {};
Condition100%2/2
$args{"inputs"} // {}
l!l
21
MC/DC100%1/1
$args{"inputs"} // {}
$args{"inputs"}
Truth table100%2/2
A
A= $args{"inputs"}
Aresult
11
00
76 3 ▶ $self->{params} = $args{params} // {};
Condition100%2/2
$args{"params"} // {}
l!l
21
MC/DC100%1/1
$args{"params"} // {}
$args{"params"}
Truth table100%2/2
A
A= $args{"params"}
Aresult
11
00
77 3 ▶ $self->{outputs} = $args{outputs} // {};
Condition100%2/2
$args{"outputs"} // {}
l!l
21
MC/DC100%1/1
$args{"outputs"} // {}
$args{"outputs"}
Truth table100%2/2
A
A= $args{"outputs"}
Aresult
11
00
78 3 $self->{outdir} = $args{outdir};
79 3 ▶ $self->{scratch} = $args{scratch} // '';
Condition50%1/2
$args{"scratch"} // ""
l!l
03
MC/DC0%0/1
$args{"scratch"} // ""
$args{"scratch"}
Truth table50%1/2
A
A= $args{"scratch"}
Aresult
11
00
80 3 ▶ $self->{checksums} = $args{checksums} // {};
Condition50%1/2
$args{"checksums"} // {}
l!l
03
MC/DC0%0/1
$args{"checksums"} // {}
$args{"checksums"}
Truth table50%1/2
A
A= $args{"checksums"}
Aresult
11
00
81 3 ▶ $self->{script} = $args{script} // '';
Condition100%2/2
$args{"script"} // ""
l!l
12
MC/DC100%1/1
$args{"script"} // ""
$args{"script"}
Truth table100%2/2
A
A= $args{"script"}
Aresult
11
00
82  
83 # Internal: path where this manifest lives on disk (not serialised)
84 3 $self->{_path} = $args{_path};
85  
86 3 return $self;
87 }
88  
89 # ── write($path) ──────────────────────────────────────────────────────────────
90 # Serialise to JSON and write to $path. Records _path for future update() calls.
91 3 ▶sub write {
Subroutine write: called CC=4 SCAR=14.0
Pod documented
92 3 my ($self, $path) = @_;
93 3 ▶ confess "ERROR NBI::Manifest::write: path required\n" unless defined $path;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $path 0 3 3
94  
95 # Build the hash to serialise (JSON_FIELDS order, excluding _path)
96 3 my %data;
97 3 for my $f (@JSON_FIELDS) {
98 66 $data{$f} = $self->{$f};
99 }
100  
101 3 my $json = JSON::PP->new->utf8->pretty->canonical->encode(\%data);
102  
103 3 ▶ open(my $fh, '>', $path)
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, ">", $path or confess("ERROR NBI::Manifest::write: cannot open '${path}': $!\n") 3 0 3
104 or confess "ERROR NBI::Manifest::write: cannot open '$path': $!\n";
105 3 print $fh $json;
106 3 close $fh;
107  
108 3 $self->{_path} = $path;
109 3 return $self;
110 }
111  
112 # ── load($path) ───────────────────────────────────────────────────────────────
113 # Parse an existing manifest JSON file and return a blessed object.
114 3 ▶sub load {
Subroutine load: called CC=4 SCAR=14.0
Pod documented
115 3 my ($class, $path) = @_;
116 3 ▶ confess "ERROR NBI::Manifest::load: path required\n" unless defined $path;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $path 0 3 3
117 3 ▶ confess "ERROR NBI::Manifest::load: '$path' not found\n" unless -f $path;
Branch: 1 branch
BranchTrueFalseTotal
unless -f $path 0 3 3
118  
119 3 ▶ open(my $fh, '<', $path)
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "<", $path or confess("ERROR NBI::Manifest::load: cannot open '${path}': $!\n") 3 0 3
120 or confess "ERROR NBI::Manifest::load: cannot open '$path': $!\n";
121 3 my $raw = do { local $/; <$fh> };
122 3 close $fh;
123  
124 3 my $data = JSON::PP->new->utf8->decode($raw);
125 3 my $self = bless $data, $class;
126 3 $self->{_path} = $path;
127 3 return $self;
128 }
129  
130 # ── output($name) ─────────────────────────────────────────────────────────────
131 # Returns the absolute path of a named output file.
132 # Useful for chaining launchers: read a previous manifest to get output paths.
133 2 ▶sub output {
Subroutine output: called CC=3 SCAR=11.0
Pod documented
134 2 my ($self, $name) = @_;
135 2 ▶ confess "ERROR NBI::Manifest::output: name required\n" unless defined $name;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $name 0 2 2
136 2 ▶ my $filename = $self->{outputs}{$name}
Branch: 1 branch
BranchTrueFalseTotal
my $filename = $self->{"outputs"}{$name} or confess("ERROR NBI::Manifest::output: no output named '${name}'\n") 1 1 2
137 or confess "ERROR NBI::Manifest::output: no output named '$name'\n";
138 1 return "$self->{outdir}/$filename";
139 }
140  
141 # ── update(%changes) ──────────────────────────────────────────────────────────
142 # Merge %changes into the object and rewrite to the stored _path.
143 # Used by nbilaunch after submission to record the Slurm job ID.
144 3 ▶sub update {
Subroutine update: called CC=3 SCAR=11.0
Pod documented
145 3 my ($self, %changes) = @_;
146 confess "ERROR NBI::Manifest::update: no path known - call write() first\n"
147 3 ▶ unless defined $self->{_path};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_path"} 1 2 3
148  
149 2 for my $k (keys %changes) {
150 5 $self->{$k} = $changes{$k};
151 }
152 2 $self->write($self->{_path});
153 2 return $self;
154 }
155  
156 2 1;
157  
158 __END__
« lib/NBI/Launcher/Kraken2.pm ↑ Summary blib/lib/NBI/EcoScheduler.pm »