generate_sivacor_partb.sh - Generate a template-consistent SIVACOR Part B report

Description¶

Bash wrapper around get_sivacor_info.py and replace_placeholders.py that generates generated/REPLICATION-PartB-SIVACOR.md from a submitted SIVACOR TRO (Transparent Research Object) JSON-LD file, without rerunning the author’s code.

It extracts the four SIVACOR-specific Markdown snippets (computing environment, replication steps, findings, and appendix) from the TRO, splits the report template to the Part B section, and fills in the SIVACOR placeholders to produce a Part B report consistent with the standard REPLICATION.md template.

Usage¶

tools/generate_sivacor_partb.sh [-j tro.jsonld] [-t template.md] [-o output.md] [-d output_dir] [--dry-run]

If -j is omitted, the first */tro/tro-*.jsonld file found under the current directory is used.

Options¶

• -j, --jsonld <file> - Path to the SIVACOR TRO JSON-LD file. Defaults to the first */tro/tro-*.jsonld match.

• -t, --template <file> - Report template to extract Part B from. Defaults to REPLICATION.md.

• -o, --output <file> - Path for the combined output file. Defaults to generated/REPLICATION-PartB-SIVACOR.md.

• -d, --output-dir <dir> - Directory for generated snippet and output files. Defaults to generated.

• --dry-run - Preview the combined output (or a summary of what would be written) without writing any files.

• -h, --help - Show usage and exit.

Environment Variables¶

• PYTHON - Python interpreter to use. Defaults to python3, falling back to python if python3 is not on PATH. The script exits with an error if neither is found, or if PYTHON is set to a command that isn’t found.

Outputs¶

Written under output_dir (default generated/):

• sivacor-partb-computing-environment.md - Computing Environment of the Replicator snippet

• sivacor-partb-replication-steps.md - Replication steps snippet

• sivacor-partb-findings.md - Findings snippet

• sivacor-partb-appendix.md - Full arrangement comparison, included by the normal generated appendix template

• REPLICATION-PartB-SIVACOR.md (or the path given via -o) - The combined, template-consistent Part B report

Workflow¶

1. Resolve the Python interpreter (PYTHON, python3, or python).

2. Parse command-line options.

3. If -j was not given, find the first */tro/tro-*.jsonld file (excluding .git/).

4. Fail if no JSON-LD file was found, or if the template file does not exist.

5. Run get_sivacor_info.py four times against the JSON-LD file to write the computing environment, replication steps, findings, and appendix snippets.

6. If the template contains the line You are starting *PartB*., truncate the template to start from that line (so only the Part B portion of a combined REPLICATION.md is used); otherwise use the template as-is.

7. Run replace_placeholders.py to substitute placeholders in the (possibly truncated) template with the generated snippets, writing the combined output file.

8. On --dry-run, print the combined preview to stdout (or, if the snippet files don’t yet exist, print a description of what would be generated) instead of writing the output file.

9. Clean up any temporary truncated-template file.

Requirements¶

• Python >= 3.12 (see get_sivacor_info.py)

• tools/get_sivacor_info.py and tools/replace_placeholders.py present in tools/

• A submitted repository containing a tro/ directory with a tro-*.jsonld file (or an explicit -j path)

Examples¶

# Auto-detect the TRO file and generate generated/REPLICATION-PartB-SIVACOR.md
tools/generate_sivacor_partb.sh

# Preview the combined Part B report without writing any files
tools/generate_sivacor_partb.sh --dry-run

# Use an explicit TRO file and output path
tools/generate_sivacor_partb.sh -j 246665/tro/tro-6a23045802a927359ccb67f4.jsonld -o generated/REPLICATION-PartB-SIVACOR.md

# Write generated snippets to a custom directory
tools/generate_sivacor_partb.sh -d generated/sivacor

SIVACOR Workflow Note¶

For repositories generated by SIVACOR, do not rerun the author code as part of the AEA workflow. The submitted repository should include a tro/ directory containing the TRO JSON-LD file. Use this script, or automations/18_summarize_sivacor.sh, to generate a template-consistent generated/REPLICATION-PartB-SIVACOR.md, then apply it with --replace-report. In split-report cases this updates REPLICATION-PartB.md; in single-file revision reports it replaces the Part B section inside REPLICATION.md. Human review still compares output files against the manuscript, evaluates substantive code behavior, checks requirements completeness against the README, and assigns the final classification.

Error Handling¶

• Exits with an error if neither python3 nor python is found, or if PYTHON is set to a missing command.

• Exits with an error on an unrecognized option.

• Exits with an error if no TRO JSON-LD file can be found (and none was given via -j).

• Exits with an error if the template file does not exist.

See Also¶

• get_sivacor_info.py - Extracts SIVACOR computing environment, timing, and Part B snippets from TRO JSONLD files

• SIVACOR TRO (Transparent Research Object) specification

• Replication report templates (REPLICATION.md, REPLICATION-PartB.md)