📝 mark internal use binaries

src/bin/audit.rs

@@ -1,3 +1,7 @@
+//! The audit binary: Interactively audit side effects in a crate.
+//!
+//! See README for current usage information.
+
 use cargo_scan::audit_file::*;
 use cargo_scan::auditing::audit::start_audit;
 use cargo_scan::auditing::info::Config;

src/bin/audit_stats.rs

@@ -1,3 +1,10 @@
+/*
+    This binary is intended for internal use.
+
+    The main supported binaries are `--bin scan` and `--bin audit`.
+    See README.md for usage instructions.
+*/
+
 use anyhow::{anyhow, Result};
 use cargo_lock::{Lockfile, Package};
 use clap::Parser;
@@ -388,6 +395,8 @@ fn dump_sinks(all_stats: &Vec<AuditingStats>) -> Result<()> {
     Ok(())
 }
 fn main() -> Result<()> {
+    eprintln!("Warning: `--bin audit_stats` is intended for internal use. The primary supported binaries are `--bin scan` and `--bin audit`.");
+
     cargo_scan::util::init_logging();
     let args = Args::parse();
     let mut all_stats = Vec::new();

src/bin/chain.rs

@@ -1,3 +1,10 @@
+/*
+    This binary is intended for internal use.
+
+    The main supported binaries are `--bin scan` and `--bin audit`.
+    See README.md for usage instructions.
+*/
+
 use cargo_scan::auditing::chain::{Command, CommandRunner, OuterArgs};
 use clap::Parser;
 
@@ -11,6 +18,8 @@ struct Args {
 }
 
 fn main() {
+    eprintln!("Warning: `--bin chain` is not recommended. The primary supported binaries are `--bin scan` and `--bin audit`.");
+
     cargo_scan::util::init_logging();
     let args = Args::parse();
 

src/bin/check_resolution.rs

@@ -1,3 +1,10 @@
+/*
+    This binary is intended for internal use.
+
+    The main supported binaries are `--bin scan` and `--bin audit`.
+    See README.md for usage instructions.
+*/
+
 #![allow(unused_variables)]
 
 use std::path::PathBuf;
@@ -26,6 +33,8 @@ struct Args {
 }
 
 pub fn main() -> Result<()> {
+    eprintln!("Warning: `--bin check_resolution` is intended for internal use. The primary supported binaries are `--bin scan` and `--bin audit`.");
+
     cargo_scan::util::init_logging();
     let args = Args::parse();
 

src/bin/default_audit.rs

@@ -1,3 +1,10 @@
+/*
+    This binary is intended for internal use.
+
+    The main supported binaries are `--bin scan` and `--bin audit`.
+    See README.md for usage instructions.
+*/
+
 use std::{collections::HashSet, path::PathBuf};
 
 use cargo_scan::{audit_file::AuditFile, effect::EffectType};
@@ -66,6 +73,8 @@ fn runner(args: Args) -> Result<()> {
 }
 
 fn main() {
+    eprintln!("Warning: `--bin default_audit` is intended for internal use. The primary supported binaries are `--bin scan` and `--bin audit`.");
+
     cargo_scan::util::init_logging();
     let args = Args::parse();
 

src/bin/scan.rs

@@ -1,8 +1,9 @@
-//! Run a scan for a single crate.
+//! The scan binary: Scan a crate and print side effects to stdout in CSV format.
 //!
 //! Prints out potentially dangerous effects to stdout (one per line),
-//! in CSV format,
-//! followed by various metadata.
+//! as well as metadata.
+//!
+//! See README for current usage information.
 
 use cargo_scan::effect::EffectInstance;
 use cargo_scan::scan_stats::{self, CrateStats};

src/bin/scan_all.rs

@@ -1,4 +1,9 @@
-//! Run a scan for a list of crates in parallel.
+//! The scan_all binary: Scan a set of crates in parallel.
+//!
+//! This binary is used in our test suites and experiments (see the Makefile);
+//! however, it is not recommended to call it directly.
+//!
+//! See README for current usage information.
 
 use cargo_scan::effect::EffectInstance;
 use cargo_scan::scan_stats::{self, CrateStats};

src/bin/stat.rs

@@ -1,3 +1,10 @@
+/*
+    This binary is intended for internal use.
+
+    The main supported binaries are `--bin scan` and `--bin audit`.
+    See README.md for usage instructions.
+*/
+
 use std::fs::create_dir_all;
 use std::{fs::remove_dir_all, path::PathBuf};
 
@@ -69,6 +76,8 @@ impl std::fmt::Display for PathType {
 // TODO: Figure out who is responsible for clearing the audit path so we don't
 //       re-use audited policies.
 fn main() -> Result<()> {
+    eprintln!("Warning: `--bin stat` is intended for internal use. The primary supported binaries are `--bin scan` and `--bin audit`.");
+
     cargo_scan::util::init_logging();
     let args = Args::parse();