Add documentation.

Cargo.lock

@@ -54,9 +54,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.100"
+version = "1.0.101"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"
+checksum = "5f0e0fee31ef5ed1ba1316088939cea399010ed7731dba877ed44aeb407a75ea"
 
 [[package]]
 name = "async-trait"
@@ -66,14 +66,14 @@ checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.114",
+ "syn 2.0.116",
 ]
 
 [[package]]
 name = "bitflags"
-version = "2.10.0"
+version = "2.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"
+checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
 
 [[package]]
 name = "block-buffer"
@@ -86,9 +86,9 @@ dependencies = [
 
 [[package]]
 name = "bytes"
-version = "1.11.0"
+version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b35204fbdc0b3f4446b89fc1ac2cf84a8a68971995d0bf2e925ec7cd960f9cb3"
+checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "bytesize"
@@ -104,9 +104,9 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "clap"
-version = "4.5.56"
+version = "4.5.58"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a75ca66430e33a14957acc24c5077b503e7d374151b2b4b3a10c83b4ceb4be0e"
+checksum = "63be97961acde393029492ce0be7a1af7e323e6bae9511ebfac33751be5e6806"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -114,9 +114,9 @@ dependencies = [
 
 [[package]]
 name = "clap_builder"
-version = "4.5.56"
+version = "4.5.58"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "793207c7fa6300a0608d1080b858e5fdbe713cdc1c8db9fb17777d8a13e63df0"
+checksum = "7f13174bda5dfd69d7e947827e5af4b0f2f94a4a3ee92912fba07a66150f21e2"
 dependencies = [
  "anstream",
  "anstyle",
@@ -133,14 +133,14 @@ dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn 2.0.114",
+ "syn 2.0.116",
 ]
 
 [[package]]
 name = "clap_lex"
-version = "0.7.7"
+version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c3e64b0cc0439b12df2fa678eae89a1c56a529fd067a9115f7827f1fffd22b32"
+checksum = "3a822ea5bc7590f9d40f1ba12c0dc3c2760f3482c6984db1573ad11031420831"
 
 [[package]]
 name = "cli"
@@ -166,7 +166,7 @@ dependencies = [
 
 [[package]]
 name = "core"
-version = "0.1.1"
+version = "0.1.4"
 dependencies = [
  "anyhow",
  "derive_more",
@@ -218,7 +218,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "rustc_version",
- "syn 2.0.114",
+ "syn 2.0.116",
  "unicode-xid",
 ]
 
@@ -316,7 +316,7 @@ checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 
 [[package]]
 name = "java"
-version = "0.2.1"
+version = "0.2.2"
 dependencies = [
  "bytesize",
  "derive_more",
@@ -339,15 +339,15 @@ checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
 [[package]]
 name = "libc"
-version = "0.2.180"
+version = "0.2.182"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bcc35a38544a891a5f7c865aca548a982ccb3b8650a5b06d0fd33a10283c56fc"
+checksum = "6800badb6cb2082ffd7b6a67e6125bb39f18782f793520caee8cb8846be06112"
 
 [[package]]
 name = "memchr"
-version = "2.7.6"
+version = "2.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f52b00d39961fc5b2736ea853c9cc86238e165017a493d1d5c8eac6bdc4cc273"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "once_cell_polyfill"
@@ -455,7 +455,7 @@ checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.114",
+ "syn 2.0.116",
 ]
 
 [[package]]
@@ -515,7 +515,7 @@ dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn 2.0.114",
+ "syn 2.0.116",
 ]
 
 [[package]]
@@ -541,9 +541,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "2.0.114"
+version = "2.0.116"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4d107df263a3013ef9b1879b0df87d706ff80f65a86ea879bd9c31f9b307c2a"
+checksum = "3df424c70518695237746f84cede799c9c58fcb37450d7b23716568cc8bc69cb"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -607,9 +607,9 @@ checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.22"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
+checksum = "537dd038a89878be9b64dd4bd1b260315c1bb94f4d784956b81e27a088d9a09e"
 
 [[package]]
 name = "unicode-segmentation"

README.md

@@ -29,10 +29,12 @@ WSL *may* affect the behaviour of raven. Quirks to be worked out.
 ```bash
 raven new demo
 cd demo
-raven run main.Main
+raven run main
 ```
 
 ## Raven commands
+
+```bash
 Usage: raven <COMMAND>
 
 Commands:
@@ -47,6 +49,7 @@ Commands:
 Options:
   -h, --help     Print help
   -V, --version  Print version
+```
 
 ## Future plans
 

crates/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "core"
-version = "0.1.1"
+version = "0.1.4"
 edition.workspace = true
 license.workspace = true
 

crates/core/src/class.rs

@@ -1,35 +1,74 @@
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 
+use java::{JAVA_EXT_CLASS, JAVA_EXT_SOURCE};
 use serde::{Deserialize, Serialize};
 
-/// Data struct
+use crate::{Error, Result};
+
+/// [`Class`] represents a source file. It is a handler.
 #[derive(Debug, Clone, Deserialize, Serialize, Hash, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Class {
+    /// Path relative to PACKAGE/java, without file extension.
     pub path: PathBuf,
     pub checksum: String,
 }
 
 impl Class {
-    pub fn is_updated(&self) -> crate::Result<bool> {
-        // If the path is local and that file has not been updated.
-        Ok(self.checksum == sha256::try_digest(self.path.clone())?)
+    /// Creates a new [`Class`].
+    ///
+    /// # Error
+    ///
+    /// * [`Error::MismatchedPackage`] if the provided `file_path` is absolute, and cannot be
+    /// subtracted to just its relative path within its parent package.
+    /// * [`Error::Io`] if the source file cannot be loaded and digested.
+    pub fn new<P: AsRef<Path>>(package_src_root: P, file_path: P) -> Result<Self> {
+        let mut file_path = file_path.as_ref().to_path_buf();
+        if file_path.is_absolute() {
+            file_path = pathsub::sub_paths(file_path.as_path(), package_src_root.as_ref())
+                .ok_or(Error::MismatchedPackage)?;
+        }
+
+        Ok(Self {
+            path: dbg!(file_path.with_extension("")),
+            checksum: sha256::try_digest(package_src_root.as_ref().join(file_path))?,
+        })
     }
 
-    pub fn update(&mut self) -> crate::Result<()> {
-        self.checksum = sha256::try_digest(self.path.clone())?;
+    /// Returns a boolean representing if the class is up to date.
+    ///
+    /// # Criteria
+    ///
+    /// * The class path is local.
+    /// * The class has been compiled to `target/`
+    /// * The class' source file has not been updated.
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::Io`]
+    pub fn is_updated<P: AsRef<Path>>(&self, class_path: P) -> Result<bool> {
+        // If the path is local and that file has not been updated.
+        Ok(class_path
+            .as_ref()
+            .join(self.path.as_path())
+            .with_extension(JAVA_EXT_CLASS)
+            .exists()
+            && self.checksum == sha256::try_digest(self.path.clone())?)
+    }
+
+    /// Updates the class' checksum.
+    ///
+    /// Only call this if you know that the class has been compiled successfully.
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::Io`] if the source file cannot be loaded and digested.
+    pub fn update<P: AsRef<Path>>(&mut self, package_src_root: P) -> Result<()> {
+        self.checksum = sha256::try_digest(dbg!(
+            package_src_root
+                .as_ref()
+                .join(self.path.as_path())
+                .with_extension(JAVA_EXT_SOURCE),
+        ))?;
         Ok(())
     }
 }
-
-// TODO: Make it clearer that this is for general files,
-// not nests.
-impl TryFrom<PathBuf> for Class {
-    type Error = crate::Error;
-
-    fn try_from(value: PathBuf) -> Result<Self, Self::Error> {
-        Ok(Self {
-            path: value.clone(),
-            checksum: sha256::try_digest(value)?,
-        })
-    }
-}

crates/core/src/dependency.rs

@@ -1,6 +1,7 @@
 use semver::Version;
 use serde::{Deserialize, Serialize};
 
+use crate::Result;
 use crate::package::PackageHandler;
 
 /// Data struct
@@ -26,7 +27,7 @@ impl Dependency {
         return self.name.clone();
     }
 
-    pub fn is_updated(&self) -> crate::Result<bool> {
+    pub fn is_updated(&self) -> Result<bool> {
         // If the path is local and that file has not been updated.
         Ok(self.source.as_ref().is_some_and(|path| is_url(path))
             && self.checksum == sha256::try_digest(self.source.as_ref().unwrap())?)

crates/core/src/error.rs

@@ -4,6 +4,10 @@ pub type Result<T> = std::result::Result<T, Error>;
 
 #[derive(Debug, From, Display)]
 pub enum Error {
+    /// Attempted to replace a value in a hash collection,
+    /// but there was no prime present when one was expected.
+    AbsentPrimeHashingError,
+
     #[from]
     Io(std::io::Error),
 
@@ -12,11 +16,15 @@ pub enum Error {
 
     MissingFileName,
 
+    MismatchedPackage,
+
     #[from]
     TomlDeserialize(toml::de::Error),
 
     #[from]
     TomlSerialize(toml::ser::Error),
 
+    UndefinedEntryPoint,
+
     UnknownPackage,
 }

crates/core/src/nest.rs

@@ -29,16 +29,16 @@ impl Nest {
         }
     }
 
-    pub fn write<P: AsRef<Path>>(&self, path: P) -> crate::Result<()> {
-        let mut path = path.as_ref().to_path_buf();
-        if path.is_dir() {
-            path = path.join(F_NEST_TOML);
+    pub fn write<P: AsRef<Path>>(&self, project_root: P) -> crate::Result<()> {
+        let mut project_root = project_root.as_ref().to_path_buf();
+        if project_root.is_dir() {
+            project_root = project_root.join(F_NEST_TOML);
         }
 
         Ok(OpenOptions::new()
             .write(true)
             .create(true)
-            .open(path)?
+            .open(project_root)?
             .write_all(toml::to_string_pretty(&self)?.as_bytes())?)
     }
 

crates/core/src/package.rs

@@ -1,30 +1,35 @@
 use std::hash::Hash;
 use std::path::{Path, PathBuf};
 
-use fs::expand_files;
 use serde::{Deserialize, Serialize};
 
 use crate::class::Class;
 use crate::prey::{F_PREY_LOCK, F_PREY_TOML, Prey, PreyLock};
 
+pub const DIR_JAVA: &str = "java/";
+
 /// Hashing is only based off the Prey.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PackageHandler {
     prey: Prey,
-    prey_lock: Option<PreyLock>,
+    prey_lock: PreyLock,
+    /// Path relative to WORKSPACE/src
     package_root: PathBuf,
     target_dir: PathBuf,
 }
 
 impl PackageHandler {
-    const DIR_JAVA: &str = "java/";
-
     pub fn new<P: AsRef<Path>>(src_dir: P, package_root: P, target_dir: P) -> crate::Result<Self> {
         let package_root = src_dir.as_ref().join(package_root.as_ref());
+        let prey_lock = if let Ok(prey_lock) = PreyLock::try_from(package_root.join(F_PREY_LOCK)) {
+            prey_lock
+        } else {
+            PreyLock::new(package_root.clone(), package_root.join(DIR_JAVA))?
+        };
 
         Ok(Self {
             prey: Prey::try_from(package_root.join(F_PREY_TOML))?,
-            prey_lock: PreyLock::try_from(package_root.join(F_PREY_LOCK)).ok(),
+            prey_lock,
             package_root,
             target_dir: target_dir.as_ref().to_path_buf(),
         })
@@ -42,32 +47,26 @@ impl PackageHandler {
         self.prey.version()
     }
 
-    pub fn get_update_targets(&mut self) -> crate::Result<Vec<&Class>> {
-        if self.prey_lock.is_none() {
-            // Try to pass a reference to the class so that there's mutability of the object
-            // available at the workspace level instead of parsing all the way down the
-            // tree. How I do this, idk. My brain is friend from a few days of JS.
+    pub fn prey_lock(&mut self) -> &mut PreyLock {
+        &mut self.prey_lock
+    }
 
-            self.prey_lock = Some(PreyLock::from(expand_files(
-                self.package_root.join(Self::DIR_JAVA),
-            )?));
-            return Ok(self.prey_lock.as_ref().unwrap().classes.iter().collect());
-        }
-
-        Ok(self
-            .prey_lock
-            .as_ref()
-            .unwrap()
-            .classes
+    pub fn get_outdated<P: AsRef<Path>>(&self, class_path: P) -> Vec<Class> {
+        self.prey_lock
+            .clone()
+            .classes()
             .iter()
-            .filter_map(|tracked| {
-                if tracked.is_updated().is_ok_and(|v| v == true) {
-                    Some(tracked)
-                } else {
-                    None
-                }
+            .filter(|class| {
+                class
+                    .is_updated(class_path.as_ref())
+                    .is_ok_and(|b| b == false)
             })
-            .collect())
+            .cloned()
+            .collect()
+    }
+
+    pub fn write_lock(&self) -> crate::Result<()> {
+        self.prey_lock.write(self.package_root.as_path())
     }
 }
 

crates/core/src/prey.rs

@@ -1,7 +1,9 @@
+use std::collections::HashSet;
 use std::fs::{File, OpenOptions};
-use std::io::Read;
+use std::io::{Read, Write};
 use std::path::{Path, PathBuf};
 
+use fs::expand_files;
 use serde::{Deserialize, Serialize};
 
 use crate::class::Class;
@@ -68,14 +70,54 @@ impl TryFrom<File> for Prey {
 /// Data struct
 #[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq, Eq)]
 pub struct PreyLock {
-    pub classes: Vec<Class>,
+    classes: HashSet<Class>,
 }
 
 impl PreyLock {
+    pub fn new<P: AsRef<Path>>(package_root: P, package_src_root: P) -> crate::Result<Self> {
+        Ok(Self::from_paths(
+            expand_files(package_root)?,
+            package_src_root,
+        ))
+    }
+
+    pub fn from_paths<P: AsRef<Path>>(paths: Vec<PathBuf>, package_src_root: P) -> Self {
+        let mut lock = Self::default();
+        lock.classes = paths
+            .iter()
+            .filter_map(|f| {
+                let dep = Class::new(package_src_root.as_ref().to_path_buf(), f.to_owned());
+                if dep.is_ok() {
+                    Some(dep.unwrap())
+                } else {
+                    None
+                }
+            })
+            .collect();
+        lock
+    }
+
+    pub fn write<P: AsRef<Path>>(&self, package_root: P) -> crate::Result<()> {
+        let mut package_root = package_root.as_ref().to_path_buf();
+        if package_root.is_dir() {
+            package_root = package_root.join(F_PREY_LOCK);
+        }
+
+        Ok(OpenOptions::new()
+            .write(true)
+            .create(true)
+            .open(package_root)?
+            .write_all(toml::to_string_pretty(&self)?.as_bytes())?)
+    }
+
     pub fn with_class(&mut self, class: Class) -> &mut Self {
-        self.classes.push(class);
+        self.classes.insert(class);
         self
     }
+
+    pub fn classes(&mut self) -> &mut HashSet<Class> {
+        &mut self.classes
+    }
 }
 
 /// Load the PreyLock from Prey.lock file.
@@ -97,21 +139,3 @@ impl TryFrom<File> for PreyLock {
         Ok(toml::from_str(buf.as_str())?)
     }
 }
-
-impl From<Vec<PathBuf>> for PreyLock {
-    fn from(value: Vec<PathBuf>) -> Self {
-        let mut lock = Self::default();
-        lock.classes = value
-            .iter()
-            .filter_map(|f| {
-                let dep = Class::try_from(f.to_owned());
-                if dep.is_ok() {
-                    Some(dep.unwrap())
-                } else {
-                    None
-                }
-            })
-            .collect();
-        lock
-    }
-}

crates/core/src/workspace.rs

@@ -9,11 +9,15 @@ use java::{JAVA_EXT_CLASS, JAVA_EXT_SOURCE};
 use serde::{Deserialize, Serialize};
 use subprocess::Exec;
 
-use crate::Error;
 use crate::nest::{F_NEST_LOCK, F_NEST_TOML, Nest, NestLock};
 use crate::package::PackageHandler;
-use crate::prey::{F_PREY_TOML, Prey};
+use crate::prey::{F_PREY_LOCK, F_PREY_TOML, Prey};
+use crate::{Error, package};
 
+/// Represents a raven workspace.
+///
+/// [`WorkspaceHandler`] manages project compilation, cache writing,
+/// and tracking of all packages that make up the workspace.
 #[derive(Debug)]
 pub struct WorkspaceHandler {
     nest: Nest,
@@ -26,6 +30,13 @@ impl WorkspaceHandler {
     const DIR_SRC: &str = "src/";
     const DIR_TARGET: &str = "target/";
 
+    /// Creates a new [`WorkspaceHandler`] instance at the provided path.
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::Io`] if the `project_root` cannot be canonicalized.
+    /// * [`Error::MissingFileName`] if a name for the workspace cannot be derived
+    /// from the `project_root`
     pub fn new<P: AsRef<Path>>(project_root: P) -> crate::Result<Self> {
         let project_root = project_root.as_ref().canonicalize()?;
 
@@ -42,6 +53,14 @@ impl WorkspaceHandler {
         })
     }
 
+    /// Loads an existing workspace from the provided path.
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::Io`] for any number of IO-related errors.
+    /// Unwrap the [`std::io::Error`] for further information.
+    /// * [`Error::MissingFileName`] if a name for the workspace cannot be derived
+    /// from the `project_root`
     pub fn load<P: AsRef<Path>>(project_root: P) -> crate::Result<Self> {
         let project_root = project_root.as_ref().canonicalize()?;
 
@@ -57,16 +76,39 @@ impl WorkspaceHandler {
         Ok(workspace_manager)
     }
 
-    pub fn write(&self) -> crate::Result<()> {
-        self.write_nest()?;
-
+    /// Writes all lock files (Nest.toml, src/**/Prey.toml) to the disk.
+    pub fn write_locks(&self) -> crate::Result<()> {
         if let Option::Some(lock) = self.nest_lock.clone() {
             lock.write(self.project_root.join(F_NEST_LOCK))?;
         }
 
+        for handler in self.packages.values() {
+            handler.write_lock()?;
+        }
+
         Ok(())
     }
 
+    /// Initializes a new workspace.
+    ///
+    /// # Behaviour
+    ///
+    /// Init will avoid overwriting or adding an example project if raven is being integrated into
+    /// an existing workspace codebase.
+    ///
+    /// Init will always write:
+    ///
+    /// * Nest.toml
+    /// * .java-version
+    /// * Attempt to append to .gitignore
+    ///
+    /// If this is an empty workspace, init will include:
+    ///
+    /// * Calling `git init`
+    /// * Writing an example project.
+    /// * Automatic package discovery.
+    ///
+    /// # Errors
     pub fn init(&mut self) -> crate::Result<&mut Self> {
         // ORDER MATTERS.
         let is_empty = read_dir(self.project_root.as_path()).is_ok_and(|tree| tree.count() == 0);
@@ -112,30 +154,69 @@ impl WorkspaceHandler {
         Ok(self)
     }
 
-    // This is the naive build
+    /// This is a naive build; it attempts to build every source file individually.
+    ///
+    /// It calls [`PackageHandler::get_outdated()`] on all known packages to determine
+    /// compile targets.
+    ///
+    /// It will then attempt to write all locks to update the caches and avoid attempting to
+    /// needlessly recompile targets.
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::AbsentPrimeError`]
+    /// * [`Error::Io`]
     pub fn build(&mut self) -> crate::Result<&mut Self> {
-        let mut targets = vec![];
-
-        for handler in self.packages.values_mut() {
-            targets.append(&mut handler.get_update_targets()?);
-        }
-
         let compiler = java::compiler::CompilerBuilder::new()
             .class_path(Self::DIR_TARGET)
             .destination(Self::DIR_TARGET)
             .build();
 
-        for target in targets.iter() {
-            // Possibly come up with a source file handler for this?
-            if let Ok(_) = compiler.clone().compile(target.path.as_path()) {
-                // TODO: Prevent unnecessary recompile
-                //target.update()?;
+        // No unintentional deep copying anywhere, right?
+        // Probably not. We'll see.
+        for handler in self.packages.values_mut() {
+            let package_src_root = self
+                .project_root
+                .join(Self::DIR_SRC)
+                .join(handler.name())
+                .join(package::DIR_JAVA);
+            let targets = handler.get_outdated(self.project_root.join(Self::DIR_TARGET));
+
+            for mut target in targets {
+                dbg!(&target);
+                if let Ok(true) = compiler
+                    .clone()
+                    .compile(package_src_root.join(target.path.as_path()))
+                {
+                    target.update(package_src_root.as_path())?;
+                    handler
+                        .prey_lock()
+                        .classes()
+                        .replace(target)
+                        .ok_or(Error::AbsentPrimeHashingError)?;
+                }
             }
         }
 
+        self.write_locks()?;
+
         Ok(self)
     }
 
+    /// Attempts to call the JVM to run, in order of precedence:
+    ///
+    /// 1. Provided entry point which includes a specific source file.
+    /// 2. Provided entry point to a package, using that package's default entry point
+    /// defined in it's `Prey.toml`
+    /// 3. The workspace's default package defined in `Nest.toml`, and that package's default
+    /// entry point as defined in it's `Prey.toml`.
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::UnknownPackage`] if the package cannot be found.
+    /// * [`Error::UndefinedEntryPoint`] if no fallback entry point can be found.
+    /// * [`Error::Io`]
+    /// * [`Error::Java`]
     pub fn run<P: AsRef<Path>>(
         &mut self,
         entry_point: Option<P>,
@@ -158,6 +239,10 @@ impl WorkspaceHandler {
                 .entry_point();
         }
 
+        if entry_point.file_name().is_none() {
+            return Err(Error::UndefinedEntryPoint);
+        }
+
         java::runtime::JVMBuilder::new(Self::DIR_TARGET)
             .assertions(assertions)
             .monitor(true)
@@ -167,13 +252,47 @@ impl WorkspaceHandler {
         Ok(self)
     }
 
+    /// Cleans the workspace of it's caches:
+    ///
+    /// * `target/`
+    /// * Nest.lock
+    /// * Prey.lock
     pub fn clean(&mut self) -> crate::Result<&mut Self> {
-        std::fs::remove_file(self.project_root.join(F_NEST_LOCK))?;
-        std::fs::remove_dir_all(Self::DIR_TARGET)?;
+        // Clear Nest.lock
+        if let Err(err) = std::fs::remove_file(self.project_root.join(F_NEST_LOCK)) {
+            if err.kind() != std::io::ErrorKind::NotFound {
+                return Err(Error::from(err));
+            }
+        }
+
+        // Clear src/**/Prey.lock
+        for handler in self.packages.values() {
+            if let Err(err) = std::fs::remove_file(
+                self.project_root
+                    .join(Self::DIR_SRC)
+                    .join(handler.name())
+                    .join(F_PREY_LOCK),
+            ) {
+                if err.kind() != std::io::ErrorKind::NotFound {
+                    return Err(Error::from(err));
+                }
+            }
+        }
+
+        // Clear target/
+        let _ = std::fs::remove_dir_all(Self::DIR_TARGET);
+
         Ok(self)
     }
 
-    /// Add any newly created packages.
+    /// Scan for newly created packages, wrapping them in [`PackageHandler`]s
+    /// and adding them to the [`WorkspaceHandler`]'s package map.
+    ///
+    /// Packages are identified by their `Prey.toml` manifests.
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::Io`]
     fn discover_packages(&mut self) -> crate::Result<()> {
         // Scan the src/ directory for entries,
         // filter out the files,
@@ -238,22 +357,31 @@ impl WorkspaceHandler {
         Ok(())
     }
 
+    /// Writes the [`WorkspaceHandler`]'s `Nest.toml` to disk.
     fn write_nest(&self) -> crate::Result<()> {
         Ok(self.nest.write(self.project_root.clone())?)
     }
 
+    /// Writes a `.java-version` file for `jenv` to the disk with an automatically parsed
+    /// java version from [`java::get_javac_version()`].
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::Io`]
+    /// * [`Error::Java`]
     fn write_java_version(&self) -> crate::Result<()> {
         if let Result::Ok(mut f) = OpenOptions::new()
             .write(true)
             .create_new(true)
             .open(java::F_JAVA_VERSION)
         {
-            f.write_all(format!("{}\n", java::get_javac_ver()?.major.to_string()).as_bytes())?;
+            f.write_all(format!("{}\n", java::get_javac_version()?.major.to_string()).as_bytes())?;
         }
 
         Ok(())
     }
 
+    /// Writes an example project tree to disk.
     fn write_dir_tree(&self) -> std::io::Result<()> {
         for dir in [
             format!("{}main/java", Self::DIR_SRC),
@@ -266,6 +394,7 @@ impl WorkspaceHandler {
         Ok(())
     }
 
+    /// Writes an example project to disk.
     fn write_example_project(&self) -> crate::Result<()> {
         let main: PathBuf = PathBuf::from(Self::DIR_SRC).join("main/");
         let test: PathBuf = PathBuf::from(Self::DIR_SRC).join("test/");

crates/java/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "java"
-version = "0.2.1"
+version = "0.2.2"
 edition.workspace = true
 license.workspace = true
 

crates/java/src/compiler.rs

@@ -1,9 +1,11 @@
+use std::fmt::Display;
 use std::path::{Path, PathBuf};
 
 use subprocess::Exec;
 use subprocess::Redirection;
 
 use crate::JAVA_BIN_COMPILER;
+use crate::JAVA_EXT_SOURCE;
 use crate::Result;
 
 #[derive(Debug, Default, Clone)]
@@ -48,26 +50,6 @@ pub struct Compiler {
 }
 
 impl Compiler {
-    /*
-    pub fn compile<P: AsRef<Path>>(self, path: P) -> Result<(Option<String>, Option<String>)> {
-        let mut cmd: Vec<String> = vec![JAVA_BIN_COMPILER.to_string()];
-
-        cmd.extend(
-            self.flags
-                .clone()
-                .into_iter()
-                .flat_map(|f| Into::<Vec<String>>::into(f)),
-        );
-        cmd.extend(
-            fs::expand_files(path)?
-                .into_iter()
-                .filter_map(|f| Some(f.to_str()?.to_string())),
-        );
-
-        Ok(io::run_process(cmd.as_slice())?)
-    }
-    */
-
     pub fn compile<P: AsRef<Path>>(self, path: P) -> Result<bool> {
         Ok(Exec::cmd(JAVA_BIN_COMPILER)
             .args(
@@ -76,7 +58,7 @@ impl Compiler {
                     .into_iter()
                     .flat_map(|f| Into::<Vec<String>>::into(f)),
             )
-            .arg(path.as_ref())
+            .arg(path.as_ref().with_extension(JAVA_EXT_SOURCE))
             .stdout(Redirection::Pipe)
             .detached()
             .start()?
@@ -89,6 +71,7 @@ impl Compiler {
 pub enum CompilerFlag {
     Classpath { path: PathBuf },
     Destination { path: PathBuf },
+    Version,
 }
 
 impl Into<Vec<String>> for CompilerFlag {
@@ -96,6 +79,18 @@ impl Into<Vec<String>> for CompilerFlag {
         match self {
             Self::Classpath { path } => vec!["-classpath".to_string(), path.display().to_string()],
             Self::Destination { path } => vec!["-d".to_string(), path.display().to_string()],
+            Self::Version => vec!["--version".to_string()],
+        }
+    }
+}
+
+// TODO: Clean this up a bit?
+impl Display for CompilerFlag {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Classpath { path } => write!(f, "-classpath {}", path.display()),
+            Self::Destination { path } => write!(f, "-d {}", path.display()),
+            Self::Version => write!(f, "--version"),
         }
     }
 }

crates/java/src/lib.rs

@@ -8,6 +8,8 @@ pub use error::{Error, Result};
 use runtime::VMFlag;
 use subprocess::Exec;
 
+use crate::compiler::CompilerFlag;
+
 pub const JAVA_BIN_VM: &str = "java";
 pub const JAVA_BIN_COMPILER: &str = "javac";
 
@@ -16,24 +18,22 @@ pub const JAVA_EXT_CLASS: &str = "class";
 
 pub const F_JAVA_VERSION: &str = ".java-version";
 
-/// Uses the java binary to parse its stdout for version information.
-///
-/// This is non-caching.
-pub fn get_javac_ver() -> Result<semver::Version> {
-    // TODO: Consider making this pull the version info from javac instead?
-
-    /*
-     * $ java --version
-     *      openjdk 21.0.9 2025-10-21
-     *      OpenJDK Runtime Environment (build 21.0.9+10)
-     *      OpenJDK 64-Bit Server VM (build 21.0.9+10, mixed mode, sharing)
-     */
+/// Uses the javac binary to get information about the install compiler.
+pub fn get_javac_version() -> Result<semver::Version> {
+    // Try to pull from javac first.
+    if let Ok(version) = semver::Version::from_str(
+        Exec::cmd(JAVA_BIN_COMPILER)
+            .arg(CompilerFlag::Version.to_string())
+            .capture()?
+            .stdout_str()
+            .replace("javac", "")
+            .trim(),
+    ) {
+        return Ok(version);
+    }
 
     Ok(semver::Version::from_str(
         get_java_version_info()?
-            .lines()
-            .nth(0)
-            .ok_or(Error::EmptyStdout)?
             .split_ascii_whitespace()
             .nth(1)
             .ok_or(Error::NthOutOfBounds)?,
@@ -42,8 +42,14 @@ pub fn get_javac_ver() -> Result<semver::Version> {
 
 /// Calls the java binary, returning the complete stdout version information.
 fn get_java_version_info() -> Result<String> {
+    /*
+     * $ java --version
+     *      openjdk 21.0.9 2025-10-21
+     *      OpenJDK Runtime Environment (build 21.0.9+10)
+     *      OpenJDK 64-Bit Server VM (build 21.0.9+10, mixed mode, sharing)
+     */
     Ok(Exec::cmd(JAVA_BIN_VM)
-        .arg(VMFlag::Version.to_string().as_str())
+        .arg(VMFlag::Version.to_string())
         .capture()?
         .stdout_str())
 }

crates/raven/src/main.rs

@@ -5,6 +5,11 @@ use cli::{CLI_ARGS, Command};
 
 fn main() -> anyhow::Result<()> {
     // type_ is yet unused.
+
+    // `raven new` requires special behaviour.
+    // This will call the "new" part of the command,
+    // changing the cwd, before calling WorkspaceHandler.init()
+    // on the actual workspace directory.
     if let Command::New { project_name, .. } = &CLI_ARGS.command {
         new(project_name.to_owned())?;
     }
@@ -35,7 +40,10 @@ fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
+/// Creates a new project directory and enters it.
 fn new(project_name: String) -> anyhow::Result<()> {
+    // Because this messes around with the CWD, this should live external to any
+    // instance of a `WorkspaceHandler`.
     let cwd = std::env::current_dir()?.join(project_name);
 
     std::fs::create_dir(&cwd)?;