Project Layout 1.1.0 API

Project Layout

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

What this module provides

This module models a source repository as a project root plus a set of conventional, root-relative directories such as production sources, test sources, resources, and documentation roots. It also supports optional module discovery for multi-project repositories.

A typical workflow is: detect an appropriate layout for a root directory, query that layout for conventional locations, then resolve those locations against the root to perform filesystem operations.

Packages

org.machanism.machai.project

Facilities for discovering, describing, and processing a source-code project rooted at a filesystem directory. This package provides orchestration APIs for detecting a project’s on-disk convention and for scanning a project tree (optionally including nested modules) using a user-supplied processor.

org.machanism.machai.project.layout

APIs for detecting, describing, and working with a repository's on-disk project layout. The central abstraction is ProjectLayout, which models a project root directory plus conventional, root-relative locations for sources, tests, resources, and documentation.

The package provides layout implementations for common ecosystems:

Key concepts

  • Project root: the filesystem directory that contains the project’s build metadata and top-level folders.
  • Root-relative paths: layout accessors return conventional paths (for example src/main/java, src/test/java, src/main/resources, src/test/resources, or documentation roots) expressed relative to the project root. Resolve these against the configured project root before performing filesystem I/O.
  • Modules: some layouts can enumerate nested projects (for example Maven reactor modules, Gradle multi-project builds, or JavaScript workspaces). Module discovery is layout-specific and may be driven by build metadata or filesystem scanning.

Typical workflow

  1. Detect a ProjectLayout for a project root.
  2. Query the layout for conventional directories (returned as root-relative paths).
  3. Resolve those paths against the project root before performing filesystem I/O.
  4. Optionally scan a repository and process each discovered project/module using a ProjectProcessor.

Examples

Detect a layout and resolve conventional folders

java.io.File projectDir = new java.io.File("C:\\path\\to\\project");

org.machanism.machai.project.layout.ProjectLayout layout =
    org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(projectDir);

java.util.Collection<String> sources = layout.getSources();
for (String rel : sources) {
  java.nio.file.Path dir = projectDir.toPath().resolve(rel);
  // ... work with dir
}

Scan a repository tree with a processor

java.io.File repoDir = new java.io.File("C:\\path\\to\\repo");

org.machanism.machai.project.ProjectProcessor processor = /* your implementation */ null;
processor.scanFolder(repoDir);

// The processor hook is invoked for the root and for each discovered module.

Class diagram

The diagram below summarizes the primary abstractions and their relationships.

Project Layout - class diagram

Packages
Package
Description
org.machanism.machai.project
Facilities for discovering, describing, and processing a source-code project rooted at a filesystem directory.
org.machanism.machai.project.layout
APIs for detecting, describing, and working with a repository's on-disk project layout.