auditkit 0.1.0

package/src/html_check.rs

@@ -0,0 +1,240 @@
+use anyhow::Result;
+use regex::Regex;
+
+use crate::ui::score_status;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HtmlCheck {
+    pub url: String,
+    pub score: i32,
+    pub status: u16,
+    pub bytes: usize,
+    pub title: String,
+    pub meta_description_present: bool,
+    pub h1_count: usize,
+    pub image_total: usize,
+    pub image_missing_alt: usize,
+    pub feedback: Vec<String>,
+}
+
+fn normalise_url(value: &str) -> String {
+    if value.starts_with("http://") || value.starts_with("https://") {
+        value.to_string()
+    } else {
+        format!("https://{value}")
+    }
+}
+
+fn strip_tags(value: &str) -> String {
+    Regex::new(r"<[^>]*>")
+        .expect("valid regex")
+        .replace_all(value, " ")
+        .split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+fn first_capture(html: &str, pattern: &str) -> String {
+    Regex::new(pattern)
+        .expect("valid regex")
+        .captures(html)
+        .and_then(|captures| captures.get(1))
+        .map(|match_value| strip_tags(match_value.as_str().trim()))
+        .unwrap_or_default()
+}
+
+fn contains_cta(html: &str) -> bool {
+    let text = strip_tags(html).to_lowercase();
+    [
+        "book",
+        "buy",
+        "call",
+        "contact",
+        "demo",
+        "enquire",
+        "get started",
+        "quote",
+        "schedule",
+        "start",
+    ]
+    .iter()
+    .any(|word| text.contains(word))
+}
+
+fn tag_has_attribute(html: &str, tag_pattern: &str, required_parts: &[&str]) -> bool {
+    let tag_regex = Regex::new(tag_pattern).expect("valid regex");
+    let found = tag_regex.find_iter(html).any(|tag| {
+        let lower = tag.as_str().to_lowercase();
+        required_parts.iter().all(|part| lower.contains(part))
+    });
+    found
+}
+
+pub fn analyze_html(url: &str, html: &str, status: u16, bytes: usize) -> HtmlCheck {
+    let title = first_capture(html, r"(?is)<title\b[^>]*>(.*?)</title>");
+    let meta_description_present = tag_has_attribute(
+        html,
+        r#"(?is)<meta\b[^>]*>"#,
+        &["name=\"description\"", "content="],
+    ) || tag_has_attribute(
+        html,
+        r#"(?is)<meta\b[^>]*>"#,
+        &["name='description'", "content="],
+    );
+    let h1_count = Regex::new(r"(?is)<h1\b[^>]*>.*?</h1>")
+        .expect("valid regex")
+        .find_iter(html)
+        .count();
+    let images = Regex::new(r#"(?is)<img\b[^>]*>"#).expect("valid regex");
+    let image_total = images.find_iter(html).count();
+    let image_missing_alt = images
+        .find_iter(html)
+        .filter(|image| {
+            !Regex::new(r#"\balt\s*=\s*["'][^"']+["']"#)
+                .expect("valid regex")
+                .is_match(image.as_str())
+        })
+        .count();
+    let has_viewport = tag_has_attribute(html, r#"(?is)<meta\b[^>]*>"#, &["name=\"viewport\""])
+        || tag_has_attribute(html, r#"(?is)<meta\b[^>]*>"#, &["name='viewport'"]);
+    let has_canonical = tag_has_attribute(html, r#"(?is)<link\b[^>]*>"#, &["rel=\"canonical\""])
+        || tag_has_attribute(html, r#"(?is)<link\b[^>]*>"#, &["rel='canonical'"]);
+    let has_cta = contains_cta(html);
+
+    let mut score = 100;
+    let mut feedback = Vec::new();
+
+    if title.is_empty() {
+        score -= 15;
+        feedback.push(
+            "Missing title tag. Add a clear page title for search results and browser tabs."
+                .to_string(),
+        );
+    } else if title.len() < 10 || title.len() > 65 {
+        score -= 8;
+        feedback.push(format!(
+            "Title length is {}. Aim for roughly 10-65 characters.",
+            title.len()
+        ));
+    } else {
+        feedback.push(format!("Title found: \"{title}\"."));
+    }
+
+    if !meta_description_present {
+        score -= 12;
+        feedback.push(
+            "Missing meta description. Add a concise summary for search snippets.".to_string(),
+        );
+    } else {
+        feedback.push("Meta description found.".to_string());
+    }
+
+    if h1_count == 0 {
+        score -= 12;
+        feedback.push("Missing H1. Add one clear primary heading.".to_string());
+    } else if h1_count > 1 {
+        score -= 8;
+        feedback.push(format!(
+            "Multiple H1 tags found ({h1_count}). Keep one primary page heading."
+        ));
+    } else {
+        feedback.push("Single H1 found.".to_string());
+    }
+
+    if image_missing_alt > 0 {
+        score -= (image_missing_alt as i32 * 8).min(15);
+        feedback.push(format!("{image_missing_alt} image(s) missing alt text."));
+    }
+
+    if !has_viewport {
+        score -= 10;
+        feedback.push("Missing viewport meta tag. Mobile layout may render poorly.".to_string());
+    }
+
+    if !has_canonical {
+        score -= 4;
+        feedback
+            .push("No canonical link found. Add one if duplicate URLs are possible.".to_string());
+    }
+
+    if !has_cta {
+        score -= 10;
+        feedback.push("No obvious CTA language found. Make the next action clear.".to_string());
+    } else {
+        feedback.push("Primary CTA found.".to_string());
+    }
+
+    if bytes > 200_000 {
+        score -= 7;
+        feedback.push(
+            "HTML response is large. Check unnecessary markup, scripts, or inline payloads."
+                .to_string(),
+        );
+    }
+
+    HtmlCheck {
+        url: url.to_string(),
+        score: score.max(0),
+        status,
+        bytes,
+        title,
+        meta_description_present,
+        h1_count,
+        image_total,
+        image_missing_alt,
+        feedback,
+    }
+}
+
+pub fn check_url(input_url: &str) -> Result<HtmlCheck> {
+    let url = normalise_url(input_url);
+    let response = reqwest::blocking::Client::new()
+        .get(&url)
+        .header("user-agent", "AuditKit/0.1")
+        .header("accept", "text/html,application/xhtml+xml")
+        .send()?;
+    let final_url = response.url().to_string();
+    let status = response.status().as_u16();
+    let html = response.text()?;
+    Ok(analyze_html(&final_url, &html, status, html.len()))
+}
+
+pub fn format_cli(result: &HtmlCheck) -> String {
+    let mut output = format!(
+        "\n== Audit Kit Check ==\nURL: {}\nScore: {}/100 ({})\n\n== Signals ==\nStatus: {}\nResponse: {} bytes\nTitle: {}\nMeta description: {}\nH1 count: {}\nImages missing alt: {}/{}\n\n== Feedback ==\n",
+        result.url,
+        result.score,
+        score_status(result.score),
+        result.status,
+        result.bytes,
+        if result.title.is_empty() { "missing" } else { &result.title },
+        if result.meta_description_present { "present" } else { "missing" },
+        result.h1_count,
+        result.image_missing_alt,
+        result.image_total
+    );
+
+    for item in &result.feedback {
+        output.push_str(&format!("- {item}\n"));
+    }
+
+    output
+}
+
+pub fn format_markdown(result: &HtmlCheck) -> String {
+    format!("# Automated Check\n\n{}\n", format_cli(result))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn analyze_html_finds_useful_feedback() {
+        let html = r#"<title>Acme Dental</title><meta name="description" content="Dental care"><h1>Care</h1><a>Book now</a><img src="/x.jpg">"#;
+        let result = analyze_html("https://example.com", html, 200, html.len());
+        assert_eq!(result.score, 78);
+        assert_eq!(result.image_missing_alt, 1);
+        assert!(result.feedback.join("\n").contains("Primary CTA found"));
+    }
+}

package/src/lib.rs

@@ -0,0 +1,21 @@
+//! Audit Kit library modules.
+//!
+//! The binary in `main.rs` wires these modules together. Each module owns one
+//! small part of the workflow, so a Rust beginner can read one file at a time.
+
+/// Shared audit input helpers such as slug creation and comma-list parsing.
+pub mod audit;
+/// Lightweight HTML checks: title, meta description, H1, images, CTA signals.
+pub mod html_check;
+/// Bridge from Rust to the Node Lighthouse helper.
+pub mod lighthouse;
+/// Final report and client email generation.
+pub mod report;
+/// Security header checks.
+pub mod security;
+/// Markdown templates used when creating a new audit workspace.
+pub mod templates;
+/// Terminal output helpers.
+pub mod ui;
+/// File paths, audit folder lookup, and read/write helpers.
+pub mod workspace;

package/src/lighthouse.rs

@@ -0,0 +1,71 @@
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use anyhow::{Context, Result};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LighthousePaths {
+    pub markdown_path: PathBuf,
+    pub json_path: PathBuf,
+}
+
+pub fn run_lighthouse(
+    root: &Path,
+    url: &str,
+    output_folder: Option<&Path>,
+) -> Result<LighthousePaths> {
+    let script = root.join("scripts/lighthouse.mjs");
+    let mut command = Command::new("node");
+    command.arg(script).arg(url);
+
+    if let Some(folder) = output_folder {
+        command.arg("--out").arg(folder);
+    }
+
+    let output = command.output().context("Running Node Lighthouse helper")?;
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        anyhow::bail!("{}", stderr.trim());
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let markdown_path = find_output_path(&stdout, "LIGHTHOUSE_MD:")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| output_folder.unwrap_or(root).join("lighthouse.md"));
+    let json_path = find_output_path(&stdout, "LIGHTHOUSE_JSON:")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| output_folder.unwrap_or(root).join("lighthouse.json"));
+
+    for line in stdout.lines() {
+        if !line.contains("LIGHTHOUSE_MD:") && !line.contains("LIGHTHOUSE_JSON:") {
+            println!("{line}");
+        }
+    }
+    Ok(LighthousePaths {
+        markdown_path,
+        json_path,
+    })
+}
+
+fn find_output_path(stdout: &str, prefix: &str) -> Option<String> {
+    stdout
+        .lines()
+        .find_map(|line| line.strip_prefix(prefix))
+        .map(str::trim)
+        .map(ToOwned::to_owned)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_helper_output_paths() {
+        let stdout =
+            "ok\nLIGHTHOUSE_MD: /tmp/lighthouse.md\nLIGHTHOUSE_JSON: /tmp/lighthouse.json\n";
+        assert_eq!(
+            find_output_path(stdout, "LIGHTHOUSE_MD:"),
+            Some("/tmp/lighthouse.md".to_string())
+        );
+    }
+}

package/src/main.rs

@@ -0,0 +1,261 @@
+use std::io::{self, Write};
+
+use anyhow::{Context, Result};
+use auditkit::audit::{slugify, split_comma_list, AuditInput};
+use auditkit::html_check;
+use auditkit::lighthouse;
+use auditkit::report;
+use auditkit::security;
+use auditkit::ui;
+use auditkit::workspace::Workspace;
+use chrono::Local;
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(
+    name = "auditkit",
+    version,
+    about = "Audit Kit: small agency website audit workflow"
+)]
+struct Cli {
+    #[command(subcommand)]
+    command: Option<Command>,
+}
+
+#[derive(Subcommand)]
+enum Command {
+    New,
+    List,
+    Check {
+        target: String,
+        #[arg(long)]
+        save: Option<String>,
+    },
+    Security {
+        target: Option<String>,
+        #[arg(long)]
+        save: Option<String>,
+    },
+    Lighthouse {
+        target: Option<String>,
+        #[arg(long)]
+        save: Option<String>,
+    },
+    Inspect {
+        target: Option<String>,
+    },
+    Report {
+        target: Option<String>,
+    },
+}
+
+fn main() {
+    if let Err(error) = run() {
+        ui::error(error);
+        std::process::exit(1);
+    }
+}
+
+fn run() -> Result<()> {
+    let cli = Cli::parse();
+    let workspace = Workspace::discover()?;
+
+    match cli.command {
+        Some(Command::New) => new_audit(&workspace),
+        Some(Command::List) => list_audits(&workspace),
+        Some(Command::Check { target, save }) => check(&workspace, &target, save.as_deref()),
+        Some(Command::Security { target, save }) => {
+            security_check(&workspace, target.as_deref(), save.as_deref())
+        }
+        Some(Command::Lighthouse { target, save }) => {
+            lighthouse_check(&workspace, target.as_deref(), save.as_deref())
+        }
+        Some(Command::Inspect { target }) => inspect(&workspace, target.as_deref()),
+        Some(Command::Report { target }) => generate_report(&workspace, target.as_deref()),
+        None => {
+            ui::help();
+            Ok(())
+        }
+    }
+}
+
+fn new_audit(workspace: &Workspace) -> Result<()> {
+    ui::section("New Audit");
+    let client_name = prompt("Client name            ")?;
+    let url = prompt("Website URL            ")?;
+    let business_type = prompt("Business type          ")?;
+    let goal = prompt("Primary goal           ")?;
+    let target_customer = prompt("Target customer        ")?;
+    let conversion_action = prompt("Main conversion action ")?;
+    let pages = prompt("Pages, comma-separated ")?;
+    let known_concerns = prompt("Known concerns         ")?;
+    let competitors = prompt("Competitors            ")?;
+
+    let audit = AuditInput {
+        slug: slugify(&client_name),
+        client_name,
+        url,
+        business_type,
+        goal,
+        target_customer,
+        conversion_action,
+        pages: split_comma_list(&pages),
+        known_concerns: split_comma_list(&known_concerns),
+        competitors: split_comma_list(&competitors),
+        created_at: Local::now().format("%Y-%m-%d").to_string(),
+    };
+
+    let folder = workspace.create_audit(&audit)?;
+    ui::section("Audit Created");
+    ui::saved(folder.display());
+    ui::bullet("Next: ak inspect latest");
+    ui::bullet("Then fill findings.md, scorecard.md, and pages/*.md");
+    Ok(())
+}
+
+fn list_audits(workspace: &Workspace) -> Result<()> {
+    ui::section("Audits");
+    let folders = workspace.list_audits()?;
+    if folders.is_empty() {
+        println!("No audits yet.");
+    } else {
+        for folder in folders {
+            ui::bullet(&folder);
+        }
+    }
+    Ok(())
+}
+
+fn check(workspace: &Workspace, target: &str, save: Option<&str>) -> Result<()> {
+    if looks_like_url(target) {
+        let result = ui::with_task("Fetching website and reading HTML", || {
+            html_check::check_url(target)
+        })?;
+        println!("{}", html_check::format_cli(&result));
+        if let Some(folder) = save {
+            let folder = workspace.resolve_target(Some(folder))?;
+            let path = workspace.write_audit_file(
+                &folder,
+                "automated-check.md",
+                &html_check::format_markdown(&result),
+            )?;
+            ui::saved(path.display());
+        }
+        return Ok(());
+    }
+
+    let folder = workspace.resolve_target(Some(target))?;
+    let website = audit_website(workspace, &folder)?;
+    let result = ui::with_task("Fetching website and reading HTML", || {
+        html_check::check_url(&website)
+    })?;
+    println!("{}", html_check::format_cli(&result));
+    let path = workspace.write_audit_file(
+        &folder,
+        "automated-check.md",
+        &html_check::format_markdown(&result),
+    )?;
+    ui::saved(path.display());
+    Ok(())
+}
+
+fn security_check(workspace: &Workspace, target: Option<&str>, save: Option<&str>) -> Result<()> {
+    let target = target.unwrap_or("latest");
+
+    if looks_like_url(target) {
+        let result = ui::with_task("Checking security headers", || security::check_url(target))?;
+        println!("{}", security::format_cli(&result));
+        if let Some(folder) = save {
+            let folder = workspace.resolve_target(Some(folder))?;
+            let path = workspace.write_audit_file(
+                &folder,
+                "security.md",
+                &security::format_markdown(&result),
+            )?;
+            ui::saved(path.display());
+        }
+        return Ok(());
+    }
+
+    let folder = workspace.resolve_target(Some(target))?;
+    let website = audit_website(workspace, &folder)?;
+    let result = ui::with_task("Checking security headers", || {
+        security::check_url(&website)
+    })?;
+    println!("{}", security::format_cli(&result));
+    let path =
+        workspace.write_audit_file(&folder, "security.md", &security::format_markdown(&result))?;
+    ui::saved(path.display());
+    Ok(())
+}
+
+fn lighthouse_check(workspace: &Workspace, target: Option<&str>, save: Option<&str>) -> Result<()> {
+    let target = target.unwrap_or("latest");
+
+    if looks_like_url(target) {
+        let output_folder = match save {
+            Some(folder) => Some(workspace.audit_folder(&workspace.resolve_target(Some(folder))?)),
+            None => None,
+        };
+        let paths = ui::with_task("Running Lighthouse in Helium", || {
+            lighthouse::run_lighthouse(&workspace.root, target, output_folder.as_deref())
+        })?;
+        ui::saved(paths.markdown_path.display());
+        ui::saved(paths.json_path.display());
+        return Ok(());
+    }
+
+    let folder = workspace.resolve_target(Some(target))?;
+    let website = audit_website(workspace, &folder)?;
+    let audit_folder = workspace.audit_folder(&folder);
+    let paths = ui::with_task("Running Lighthouse in Helium", || {
+        lighthouse::run_lighthouse(&workspace.root, &website, Some(&audit_folder))
+    })?;
+    ui::saved(paths.markdown_path.display());
+    ui::saved(paths.json_path.display());
+    Ok(())
+}
+
+fn inspect(workspace: &Workspace, target: Option<&str>) -> Result<()> {
+    let folder = workspace.resolve_target(target)?;
+    ui::section("Inspect");
+    ui::bullet(&format!("Running checks for {folder}"));
+    check(workspace, &folder, None)?;
+    security_check(workspace, Some(&folder), None)?;
+    lighthouse_check(workspace, Some(&folder), None)?;
+    Ok(())
+}
+
+fn generate_report(workspace: &Workspace, target: Option<&str>) -> Result<()> {
+    let folder = workspace.resolve_target(target)?;
+    let (report_path, email_path) =
+        ui::with_task("Building final report and client email", || {
+            report::generate_report(workspace, &folder)
+        })?;
+    ui::section("Report Generated");
+    ui::saved(report_path.display());
+    ui::saved(email_path.display());
+    Ok(())
+}
+
+fn audit_website(workspace: &Workspace, folder: &str) -> Result<String> {
+    let files = workspace.read_audit_files(folder)?;
+    let brief = files.get("brief.md").context("Missing brief.md")?;
+    let parsed = report::parse_brief(brief);
+    if parsed.website.is_empty() {
+        anyhow::bail!("No website found in {folder}/brief.md");
+    }
+    Ok(parsed.website)
+}
+
+fn looks_like_url(value: &str) -> bool {
+    value.starts_with("http://") || value.starts_with("https://") || value.contains('.')
+}
+
+fn prompt(label: &str) -> Result<String> {
+    print!("{label}");
+    io::stdout().flush()?;
+    let mut value = String::new();
+    io::stdin().read_line(&mut value)?;
+    Ok(value.trim().to_string())
+}