Project Layout

Project Layout is a small utility library for describing and working with conventional project directory layouts (sources, resources, tests, documentation, and other project files) in a consistent way. It is intended for build tooling and plugins that need to locate well-known folders reliably across different projects.

The library supports all relevant project-file categories, including source code, documentation, project-site content, configuration, resources, tests, and files discovered while a repository is inspected. A ProjectLayout represents one project root and exposes locations relative to that root, together with project identity and child-module information. Resolve a returned path against getProjectDir() before using it with the filesystem.

Package structure

`org.machanism.machai.project`

This package coordinates layout detection and recursive processing. The ProjectLayoutManager checks descriptors in a defined order: Maven (pom.xml), Gradle (build.gradle), JavaScript or TypeScript (package.json), and Python (pyproject.toml). An existing directory without a recognized descriptor uses DefaultProjectLayout; a missing directory causes FileNotFoundException.

ProjectProcessor separates detection from application logic. Its scanFolder(File) method processes each declared module recursively and invokes processFolder(ProjectLayout) for a leaf project. Subclasses can therefore inspect source, test, documentation, resource, and other paths without duplicating descriptor detection or module traversal.

`org.machanism.machai.project.layout`

This package contains the common layout abstraction and ecosystem-specific implementations. ProjectLayout provides project-root configuration, project identifiers and names, parent identity, layout type, child modules, root-relative path conversion, recursive directory discovery, exclusion rules, and a temporary-directory name. Implementations expose source, test, and documentation locations as collections of relative paths. The related package-level documentation describes the same responsibilities and contracts in detail.

MavenProjectLayout reads Maven coordinates, parent identity, packaging, modules, build source and resource directories, test directories, and the conventional src/site documentation directory through PomReader. Maven source defaults are applied when the build does not specify them.
GradleProjectLayout uses the Gradle Tooling API to load child projects and supplies the conventional src/main, src/test, and src/site locations. Custom Gradle source sets are not currently parsed.
JScriptProjectLayout reads package.json and expands array-form workspaces glob patterns into unique module directories that contain their own package descriptor. Source, test, and documentation discovery currently returns empty collections.
PythonProjectLayout recognizes a public project whose valid pyproject.toml supplies a project name and does not mark it private. Its source, test, documentation, and module discovery are currently empty by design.
DefaultProjectLayout is the filesystem fallback. It treats non-excluded immediate subdirectories as module candidates and returns empty collections for ecosystem-specific source, test, and documentation roots.

Typical usage

Pass an existing root directory to ProjectLayoutManager.detectProjectLayout(projectDir).
Query the result with getSources(), getTests(), getDocuments(), and getModules().
Resolve every returned relative path against getProjectDir() before reading or writing project files.
For recursive work, subclass ProjectProcessor, implement processFolder(ProjectLayout), and call scanFolder(projectDir).

Examples

Detect a layout and inspect locations

File projectDir = new File("path/to/project");
ProjectLayout layout = ProjectLayoutManager.detectProjectLayout(projectDir);
Collection<String> sources = layout.getSources();
Collection<String> tests = layout.getTests();
Collection<String> documents = layout.getDocuments();

Process a repository tree

A concrete processor implements processFolder(ProjectLayout) and scans a root with processor.scanFolder(new File("path/to/repository"));. A parent layout causes each declared module to be scanned recursively; a leaf layout is passed directly to the callback.

Structure and relationships

The class diagram below illustrates the relationship between the detection and processing entry points, the common layout abstraction, and its Maven, Gradle, JavaScript, Python, and default implementations.