testing-conventions 0.0.2__tar.gz → 0.0.3__tar.gz

{testing_conventions-0.0.2 → testing_conventions-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testing-conventions
-Version: 0.0.2
+Version: 0.0.3
 Summary: Enforce testing conventions in libraries (Python, TypeScript, and Rust).
 Author-email: Kevin Scott <me@thekevinscott.com>
 License: MIT

{testing_conventions-0.0.2 → testing_conventions-0.0.3}/rust/CHANGELOG.md

@@ -12,6 +12,14 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `[python]` / `[typescript]` / `[rust]` tables) and self-validates on load:
   unknown keys and malformed TOML are rejected. The parsed config is not
   consumed yet. (#12)
+- `location` module — `missing_unit_tests()` walks a directory tree and returns
+  every Python source file (`*.py`) that has no colocated `*_test.py`, enforcing
+  the README's "Location & Naming" rule. Test files (`*_test.py`) and the package
+  marker (`__init__.py`) are exempt; the orphan list is sorted for deterministic
+  output. (#15)
+- `unit-location <PATH>` CLI subcommand — runs that check over a directory,
+  printing each source file missing its colocated `_test.py` and exiting
+  non-zero when any are missing. (#15)
 
 ### Changed
 

{testing_conventions-0.0.2 → testing_conventions-0.0.3}/rust/Cargo.lock

@@ -226,7 +226,7 @@ dependencies = [
 
 [[package]]
 name = "testing-conventions"
-version = "0.0.2"
+version = "0.0.3"
 dependencies = [
  "anyhow",
  "clap",

{testing_conventions-0.0.2 → testing_conventions-0.0.3}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "testing-conventions"
-version = "0.0.2"
+version = "0.0.3"
 edition = "2021"
 license = "MIT"
 authors = ["Kevin Scott <me@thekevinscott.com>"]

{testing_conventions-0.0.2 → testing_conventions-0.0.3}/rust/MIGRATIONS.md

@@ -21,9 +21,16 @@ reads one TOML file into it and validates the config itself (the self-guard) —
 unknown keys and malformed TOML are rejected rather than silently accepted.
 Purely additive; nothing consumes the parsed config yet.
 
+Also adds the first structural rule. The `location` module's
+`missing_unit_tests()` walks a directory and returns every Python source file
+with no colocated `*_test.py`, and the new `unit-location <PATH>` subcommand
+runs that check and exits non-zero on any orphan. Purely additive.
+
 ### Required changes
 
-None. New, additive API: `testing_conventions::config::{Config, load_config}`.
+None. New, additive API: `testing_conventions::config::{Config, load_config}`,
+`testing_conventions::location::missing_unit_tests`, and the
+`unit-location <PATH>` CLI subcommand.
 
 ### Deprecations removed
 
@@ -41,3 +48,11 @@ cd packages/rust && cargo test --test config_loader
 
 Expected: the loader's integration tests pass — the canonical config loads into
 memory, and unknown-key, malformed, and missing-file configs are rejected.
+
+```
+cd packages/rust && cargo test --test unit_location
+```
+
+Expected: the location check's integration tests pass — the clean fixture
+reports no orphans, the red fixture reports both missing twins, and the
+`unit-location` subcommand exits non-zero on the red fixture.

{testing_conventions-0.0.2 → testing_conventions-0.0.3}/rust/src/lib.rs

@@ -1,4 +1,7 @@
 pub mod config;
+pub mod location;
+
+use std::path::{Path, PathBuf};
 
 use clap::{Parser, Subcommand};
 
@@ -18,6 +21,11 @@ pub struct Cli {
 enum Command {
     /// Check the repository against its testing-conventions config.
     Check,
+    /// Check that every Python source file has a colocated `_test.py` unit test.
+    UnitLocation {
+        /// Directory to scan recursively for `*.py` sources.
+        path: PathBuf,
+    },
 }
 
 pub fn run<I, T>(args: I) -> anyhow::Result<i32>
@@ -27,9 +35,30 @@ where
 {
     let cli = Cli::try_parse_from(args)?;
     match cli.command {
-        // Rules aren't implemented yet; the scaffold just proves the wiring.
+        // The config-driven `check` umbrella isn't wired yet; the scaffold
+        // proves the wiring while individual rules land as their own subcommand.
         Some(Command::Check) | None => Ok(0),
+        Some(Command::UnitLocation { path }) => run_unit_location(&path),
+    }
+}
+
+/// Run the Python unit-test location check over `root`, reporting orphans.
+///
+/// Returns `0` when every source file has its colocated `_test.py`; otherwise
+/// prints each orphan to stderr and returns `1`.
+fn run_unit_location(root: &Path) -> anyhow::Result<i32> {
+    let orphans = location::missing_unit_tests(root)?;
+    if orphans.is_empty() {
+        return Ok(0);
+    }
+    for orphan in &orphans {
+        eprintln!("missing colocated unit test: {}", orphan.display());
     }
+    eprintln!(
+        "error: {} source file(s) missing a colocated `_test.py`",
+        orphans.len()
+    );
+    Ok(1)
 }
 
 #[cfg(test)]

testing_conventions-0.0.3/rust/src/location.rs

@@ -0,0 +1,138 @@
+//! Unit-test location/naming check for Python sources (issue #15).
+//!
+//! The convention (README "Location & Naming"; `internals/python/testing.md`):
+//! a Python source file `foo.py` is unit-tested by a colocated `foo_test.py`.
+//! [`missing_unit_tests`] walks a directory tree and returns every source file
+//! that has no such sibling — an "orphan". Files that are themselves tests
+//! (`*_test.py`) are what the check looks *for*, never subjects, and the
+//! package marker (`__init__.py`) is exempt.
+
+use std::collections::HashSet;
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+
+/// The extension that marks a Python file.
+const PY_EXTENSION: &str = "py";
+/// The stem suffix that marks a file as a unit test: `foo` → `foo_test`.
+const TEST_STEM_SUFFIX: &str = "_test";
+/// The package marker, which is never a unit-test subject.
+const PACKAGE_MARKER: &str = "__init__.py";
+
+/// Walk `root` recursively and return every Python source file that has no
+/// colocated `<stem>_test.py`, sorted for deterministic output.
+///
+/// A file whose stem ends in `_test` is itself a test and is never treated as a
+/// subject; every other `*.py` file is a subject and must have its colocated
+/// test sibling. Returns an error if the tree under `root` cannot be read.
+pub fn missing_unit_tests(root: impl AsRef<Path>) -> Result<Vec<PathBuf>> {
+    let mut python_files = Vec::new();
+    collect_python_files(root.as_ref(), &mut python_files)?;
+
+    // Every `*.py` path we found, so a subject's expected twin is a lookup
+    // rather than a second pass over the filesystem.
+    let present: HashSet<&Path> = python_files.iter().map(PathBuf::as_path).collect();
+
+    let mut orphans: Vec<PathBuf> = Vec::new();
+    for source in &python_files {
+        if is_test_file(source) || is_exempt(source) {
+            continue;
+        }
+        if !present.contains(expected_test_path(source).as_path()) {
+            orphans.push(source.clone());
+        }
+    }
+    orphans.sort();
+    Ok(orphans)
+}
+
+/// Recursively collect every `*.py` file under `dir` into `out`.
+fn collect_python_files(dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
+    let entries =
+        std::fs::read_dir(dir).with_context(|| format!("reading directory `{}`", dir.display()))?;
+    for entry in entries {
+        let path = entry
+            .with_context(|| format!("reading an entry under `{}`", dir.display()))?
+            .path();
+        if path.is_dir() {
+            collect_python_files(&path, out)?;
+        } else if is_python_source(&path) {
+            out.push(path);
+        }
+    }
+    Ok(())
+}
+
+/// `true` for a file with a `.py` extension.
+fn is_python_source(path: &Path) -> bool {
+    path.extension().and_then(|ext| ext.to_str()) == Some(PY_EXTENSION)
+}
+
+/// `true` when `path` is itself a unit test (`*_test.py`), never a subject.
+fn is_test_file(path: &Path) -> bool {
+    stem_of(path).ends_with(TEST_STEM_SUFFIX)
+}
+
+/// `true` for the package marker (`__init__.py`), which never needs a test.
+fn is_exempt(path: &Path) -> bool {
+    path.file_name().and_then(|name| name.to_str()) == Some(PACKAGE_MARKER)
+}
+
+/// The colocated test a source is expected to have: `foo.py` → `foo_test.py`.
+fn expected_test_path(source: &Path) -> PathBuf {
+    source.with_file_name(format!(
+        "{}{}.{}",
+        stem_of(source),
+        TEST_STEM_SUFFIX,
+        PY_EXTENSION
+    ))
+}
+
+/// The file stem (the name without its extension), lossily decoded.
+fn stem_of(path: &Path) -> String {
+    path.file_stem()
+        .map(|stem| stem.to_string_lossy().into_owned())
+        .unwrap_or_default()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn recognizes_python_sources_by_extension() {
+        assert!(is_python_source(Path::new("a.py")));
+        assert!(is_python_source(Path::new("pkg/widget.py")));
+        assert!(!is_python_source(Path::new("a.pyi")));
+        assert!(!is_python_source(Path::new("a.txt")));
+        assert!(!is_python_source(Path::new("README")));
+    }
+
+    #[test]
+    fn recognizes_test_files_by_stem_suffix() {
+        assert!(is_test_file(Path::new("widget_test.py")));
+        assert!(is_test_file(Path::new("pkg/helper_test.py")));
+        assert!(!is_test_file(Path::new("widget.py")));
+        assert!(!is_test_file(Path::new("pkg/helper.py")));
+    }
+
+    #[test]
+    fn exempts_the_package_marker() {
+        assert!(is_exempt(Path::new("__init__.py")));
+        assert!(is_exempt(Path::new("pkg/__init__.py")));
+        assert!(!is_exempt(Path::new("conftest.py")));
+        assert!(!is_exempt(Path::new("widget.py")));
+    }
+
+    #[test]
+    fn expected_test_path_is_the_colocated_twin() {
+        assert_eq!(
+            expected_test_path(Path::new("pkg/widget.py")),
+            PathBuf::from("pkg/widget_test.py")
+        );
+        assert_eq!(
+            expected_test_path(Path::new("widget.py")),
+            PathBuf::from("widget_test.py")
+        );
+    }
+}

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/clean/pkg/helper.py

@@ -0,0 +1 @@
+# unit_location clean fixture: nested source colocated with helper_test.py

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/clean/pkg/helper_test.py

@@ -0,0 +1 @@
+# unit_location clean fixture: nested unit test for helper.py

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/clean/widget.py

@@ -0,0 +1 @@
+# unit_location clean fixture: source colocated with widget_test.py

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/clean/widget_test.py

@@ -0,0 +1 @@
+# unit_location clean fixture: unit test for widget.py

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/exempt/__init__.py

@@ -0,0 +1 @@
+# unit_location exempt fixture: package marker — never a unit-test subject

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/exempt/pkg/__init__.py

@@ -0,0 +1 @@
+# unit_location exempt fixture: nested package marker — never a unit-test subject

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/exempt/widget.py

@@ -0,0 +1 @@
+# unit_location exempt fixture: real source colocated with widget_test.py (OK)

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/exempt/widget_test.py

@@ -0,0 +1 @@
+# unit_location exempt fixture: unit test for widget.py

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/red/lonely.py

@@ -0,0 +1 @@
+# unit_location red fixture: ORPHAN — no colocated lonely_test.py

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/red/pkg/orphan.py

@@ -0,0 +1 @@
+# unit_location red fixture: ORPHAN — no colocated orphan_test.py

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/red/pkg/paired.py

@@ -0,0 +1 @@
+# unit_location red fixture: nested source colocated with paired_test.py (OK)

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/red/pkg/paired_test.py

@@ -0,0 +1 @@
+# unit_location red fixture: nested unit test for paired.py

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/red/widget.py

@@ -0,0 +1 @@
+# unit_location red fixture: source colocated with widget_test.py (paired, OK)

testing_conventions-0.0.3/rust/tests/fixtures/unit_location/red/widget_test.py

@@ -0,0 +1 @@
+# unit_location red fixture: unit test for widget.py

testing_conventions-0.0.3/rust/tests/unit_location.rs

@@ -0,0 +1,90 @@
+//! Integration tests for the Python unit-test location/naming check (issue #15).
+//!
+//! These pin the contract from #15: a Python source file `foo.py` must have a
+//! colocated `foo_test.py`. `missing_unit_tests` walks a directory and returns
+//! every source file missing its twin; the `unit-location` subcommand turns a
+//! non-empty result into a non-zero exit.
+//!
+//! Per the #3 guardrail, the check ships a clean fixture
+//! (`unit_location/clean`, every source paired — must pass) and a red fixture
+//! (`unit_location/red`, two orphans — must fail).
+
+use std::ffi::OsString;
+use std::path::{Path, PathBuf};
+
+use testing_conventions::location::missing_unit_tests;
+use testing_conventions::run;
+
+/// Absolute path to a fixture tree under `tests/fixtures/unit_location/`.
+fn fixture(name: &str) -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures/unit_location")
+        .join(name)
+}
+
+/// Orphans reported under `root`, as `/`-joined paths relative to it.
+fn relative_orphans(root: &Path) -> Vec<String> {
+    missing_unit_tests(root)
+        .expect("walking a readable tree should succeed")
+        .iter()
+        .map(|path| {
+            path.strip_prefix(root)
+                .expect("an orphan must live under the scanned root")
+                .to_string_lossy()
+                .replace('\\', "/")
+        })
+        .collect()
+}
+
+/// Invoke the `unit-location <fixture>` subcommand, returning its exit code.
+fn run_unit_location(fixture_name: &str) -> i32 {
+    let args: Vec<OsString> = vec![
+        "testing-conventions".into(),
+        "unit-location".into(),
+        fixture(fixture_name).into_os_string(),
+    ];
+    run(args).expect("a readable tree should not error")
+}
+
+#[test]
+fn clean_tree_reports_no_orphans() {
+    assert!(
+        relative_orphans(&fixture("clean")).is_empty(),
+        "every source in the clean tree has a colocated _test.py"
+    );
+}
+
+#[test]
+fn red_tree_reports_every_missing_twin() {
+    assert_eq!(
+        relative_orphans(&fixture("red")),
+        vec!["lonely.py", "pkg/orphan.py"],
+    );
+}
+
+#[test]
+fn package_markers_are_not_orphans() {
+    assert!(
+        relative_orphans(&fixture("exempt")).is_empty(),
+        "__init__.py is a package marker, never a unit-test subject"
+    );
+}
+
+#[test]
+fn a_missing_root_is_an_error() {
+    let result = missing_unit_tests(fixture("does_not_exist"));
+    assert!(
+        result.is_err(),
+        "an unreadable root must be an error, got: {result:?}"
+    );
+}
+
+#[test]
+fn subcommand_exits_zero_on_a_clean_tree() {
+    assert_eq!(run_unit_location("clean"), 0);
+}
+
+#[test]
+fn subcommand_exits_nonzero_on_a_red_tree() {
+    assert_eq!(run_unit_location("red"), 1);
+}