libify

Author: bitfield

.github/workflows/audit.yml

@@ -0,0 +1,14 @@
+name: Security audit
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  push:
+    paths:
+      - '**/Cargo.toml'
+      - '**/Cargo.lock'
+jobs:
+  security_audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: EmbarkStudios/cargo-deny-action@v1

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+on: [pull_request, workflow_dispatch]
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: "clippy, rustfmt"
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --all -- --check
+      - run: cargo clippy --all-targets --all-features -- -D clippy::pedantic -D warnings
+
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test --all-features

.github/workflows/nightly.yml

@@ -0,0 +1,13 @@
+name: Nightly
+on: [pull_request, workflow_dispatch]
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test --all-features

Cargo.toml

@@ -1,7 +1,23 @@
 [package]
 name = "up2code"
 version = "0.1.0"
+authors = ["John Arundel <[email protected]>"]
 edition = "2021"
+description = """
+up2code is a tool to check code listings in Markdown files against a GitHub repository.
+"""
+keywords = ["web", "cli", "utility", "text"]
+categories = ["command-line-utilities"]
+license = "MIT OR Apache-2.0"
+readme = "README.md"
+documentation = "https://docs.rs/up2code"
+homepage = "https://github.com/bitfield/up2code"
+repository = "https://github.com/bitfield/up2code"
+exclude = ["/.github/"]
+
+[badges]
+github = { repository = "bitfield/up2code", workflow = "CI" }
+maintenance = { status = "actively-developed" }
 
 [dependencies]
 anyhow = "1.0.89"

README.md

@@ -0,0 +1,49 @@
+[![Crate](https://img.shields.io/crates/v/up2code.svg)](https://crates.io/crates/up2code)
+[![Docs](https://docs.rs/up2code/badge.svg)](https://docs.rs/up2code)
+![CI](https://github.com/bitfield/up2code/actions/workflows/ci.yml/badge.svg)
+![Audit](https://github.com/bitfield/up2code/actions/workflows/audit.yml/badge.svg)
+![Maintenance](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
+
+# up2code
+
+`up2code` is a tool for checking code listings in Markdown files, to make sure they're up to date with, and in sync with, canonical versions stored in a GitHub repo.
+
+### Installation
+
+```sh
+cargo install up2code
+```
+
+### Usage
+
+Run:
+
+```sh
+up2code book/*.md
+```
+
+`up2code` reads all the Markdown files you specify, looking for what it considers a “listing”: a fenced code block immediately followed by a web link. For example:
+
+    ```rust
+    fn main() {
+        println!("Hello, world!")
+    }
+    ```
+    [Listing `hello/1`](https://github.com/bitfield/example/blob/src/main.rs))
+
+It will try to fetch the raw code page from the specified URL (appending "?raw=true"), reporting any errors. If the fetch succeeds, it will check that the Markdown listing is an exact substring of the GitHub listing, reporting any mismatch as a unified diff:
+
+```
+tests/data/test.md: Listing `counter_2`
+@@ -6,8 +13,8 @@
+
+     #[test]
+     fn count_lines_fn_counts_lines_in_input() {
+-        let input = io::Cursor::new("line 1\nline2\n");
++        let input = io::Cursor::new("line 1\nline 2\n");
+         let lines = count_lines(input);
+-        assert_eq!(2, lines);
++        assert_eq!(lines, 2);
+     }
+ }
+```

src/lib.rs

@@ -0,0 +1,79 @@
+use regex::Regex;
+use similar::TextDiff;
+
+use std::{fs, io, path::Path, sync::LazyLock};
+
+static LISTINGS: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new(
+        r"(?m)^```.*?\n(?<code>[^`]+?\n)?```\n\(\[(?<title>[\s\S]+?)\]\((?<link>.*?)\)",
+    )
+    .unwrap()
+});
+
+static HTTP: LazyLock<reqwest::blocking::Client> =
+    LazyLock::new(|| reqwest::blocking::Client::builder().build().unwrap());
+
+/// Returns all the listings in the file at `path`.
+///
+/// # Errors
+///
+/// Any errors returned by [`fs::read_to_string`].
+pub fn listings(path: impl AsRef<Path>) -> io::Result<Vec<Listing>> {
+    let mut listings = Vec::new();
+    let text = fs::read_to_string(path)?;
+    for m in LISTINGS.captures_iter(&text) {
+        let Some(code) = m.name("code") else { continue };
+        let Some(title) = m.name("title") else {
+            continue;
+        };
+        let Some(link) = m.name("link") else { continue };
+        let url = String::from(link.as_str());
+        listings.push(Listing {
+            title: String::from(title.as_str()),
+            code: String::from(code.as_str()),
+            url: String::from(url.as_str()),
+        });
+    }
+    Ok(listings)
+}
+
+pub struct Listing {
+    pub title: String,
+    pub code: String,
+    pub url: String,
+}
+
+impl Listing {
+    /// Fetches the canonical listing from its URL and stores the text.
+    ///
+    /// # Errors
+    ///
+    /// Any errors returned by the `reqwest` client.
+    pub fn check(self) -> reqwest::Result<CheckedListing> {
+        let resp = HTTP.get(self.url.clone() + "?raw=true").send()?;
+        resp.error_for_status_ref()?;
+        Ok(CheckedListing {
+            title: self.title,
+            code: self.code,
+            text: resp.text()?
+        })
+    }
+}
+
+pub struct CheckedListing {
+    pub title: String,
+    pub code: String,
+    pub text: String,
+}
+
+impl CheckedListing {
+    #[must_use]
+    pub fn diff(&self) -> Option<String> {
+        if self.text.contains(&self.code) {
+            None
+        } else {
+            let diff = TextDiff::from_lines(&self.code, &self.text);
+            Some(format!("{}", diff.unified_diff()))
+        }
+    }
+}

src/main.rs

@@ -1,49 +1,21 @@
-use regex::Regex;
-use similar::TextDiff;
+use std::env;
 
-use std::{env, fs, sync::LazyLock};
-
-static LISTINGS: LazyLock<Regex> = LazyLock::new(|| {
-    Regex::new(
-        r"(?m)^```rust\n(?<code>[^`]+?\n)?```\n\(\[Listing `(?<listing>[\s\S]+?)`\]\((?<link>.*?)\)",
-    )
-    .unwrap()
-});
+use up2code::listings;
 
 fn main() -> anyhow::Result<()> {
     let paths: Vec<String> = env::args().skip(1).collect();
     if paths.is_empty() {
         eprintln!("Usage: up2code [PATH, ...]");
         return Ok(());
     }
-    let http = reqwest::blocking::Client::builder().build()?;
-    for path in &paths {
-        let text = fs::read_to_string(path)?;
-        for m in LISTINGS.captures_iter(&text) {
-            let Some(code) = m.name("code") else { continue };
-            let Some(listing) = m.name("listing") else {
-                continue;
-            };
-            let Some(link) = m.name("link") else { continue };
-            let raw_url = String::from(link.as_str());
-            match http.get(raw_url + "?raw=true").send() {
-                Err(e) => {
-                    println!("{path}: {e}");
-                }
-                Ok(resp) => {
-                    if let Err(e) = resp.error_for_status_ref() {
-                        println!("{path}: {e}");
-                        continue
-                    } 
-                    let text = resp.text()?;
-                    if !text.contains(code.as_str()) {
-                        println!("{path}: Listing {}", listing.as_str());
-                        let diff = TextDiff::from_lines(code.as_str(), &text);
-                        print!("{}", diff.unified_diff());
-                    }
-                }
+    for path in paths {
+        for listing in listings(&path)? {
+            let listing = listing.check()?;
+            if let Some(diff) = listing.diff() {
+                println!("{path}: {}", listing.title);
+                println!("{diff}");
             }
         }
     }
     Ok(())
-}
+}