Project Layout 1.2.1-SNAPSHOT API

Project Layout

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

The library centers on a common layout abstraction that represents a project root together with root-relative source, test, documentation, and module locations. It includes specialized implementations for Maven, Gradle, JavaScript workspace, Python, and generic filesystem-based projects, allowing callers to detect a layout and then process the project using one uniform API.

Package overview

org.machanism.machai.project

This package provides the entry points for layout detection and project processing. It is responsible for choosing an appropriate ProjectLayout implementation for a filesystem directory and for traversing a project or its nested modules through a reusable processor abstraction.

  • ProjectLayoutManager detects the effective layout by inspecting project metadata such as Maven, Gradle, JavaScript, or Python build files.
  • ProjectProcessor scans a project directory, delegates per-module processing when modules are present, and invokes user-defined folder processing logic for leaf projects.

org.machanism.machai.project.layout

This package defines the shared contract for describing a repository's on-disk structure and provides concrete implementations for different ecosystems. The central type, ProjectLayout, exposes the project root, conventional source and test folders, documentation locations, project identity metadata, and optional child modules.

  • MavenProjectLayout reads pom.xml metadata, reports Maven source and test roots, exposes multi-module reactor definitions, and derives project identifiers from the Maven model.
  • GradleProjectLayout uses the Gradle Tooling API to inspect Gradle projects and expose child project names together with conventional source, test, and documentation roots.
  • JScriptProjectLayout parses package.json and resolves workspace module patterns against the filesystem.
  • PythonProjectLayout detects Python projects using pyproject.toml and related metadata.
  • DefaultProjectLayout serves as a fallback when no ecosystem-specific layout can be detected.
  • PomReader provides Maven model parsing and lightweight property replacement support for reading POM data.

Core concepts

  • Project root: the filesystem directory that acts as the base for all layout calculations and metadata lookup.
  • Root-relative paths: layout accessors typically return relative directory names such as src/main/java, src/test/java, or src/site. Callers resolve these values against the project root before performing file operations.
  • Modules: some layouts represent parent projects that contain child projects. Module resolution may come from build metadata such as Maven reactor modules, Gradle child projects, or JavaScript workspaces.
  • Ignored directories: the shared layout utilities intentionally skip known build, cache, IDE, dependency, and temporary directories such as node_modules, .git, target, build, and .machai when scanning the filesystem.

Typical usage

  1. Detect a ProjectLayout for a root directory.
  2. Query the layout for sources, tests, documents, identifiers, and optional modules.
  3. Resolve returned root-relative paths against the project root before reading or writing files.
  4. Optionally process the project recursively using a ProjectProcessor implementation.

Usage examples

Detect a layout and inspect 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();
java.util.Collection<String> tests = layout.getTests();
java.util.Collection<String> documents = layout.getDocuments();

Process a repository tree

java.io.File repoDir = new java.io.File("C:\\path\\to\\repo");
org.machanism.machai.project.ProjectProcessor processor = /* custom implementation */ null;
processor.scanFolder(repoDir);

Structure and relationships

The class diagram below summarizes the main abstractions and concrete layout implementations in this module.

Project Layout class diagram

Packages
Package
Description
org.machanism.machai.project
Provides APIs for detecting a project's layout and traversing its modules or root directory for processing.
org.machanism.machai.project.layout
APIs for detecting, describing, and working with a repository's on-disk project layout.