Package org.machanism.machai.project.layout

package org.machanism.machai.project.layout
APIs for detecting and describing a repository's on-disk project layout.

A ProjectLayout represents a configured project root and exposes conventional locations as paths relative to that root. Concrete implementations adapt the common API to Maven, Gradle, JavaScript/TypeScript, Python, and unrecognized project structures. Select a layout, configure its root with ProjectLayout.projectDir(java.io.File), then query its source, test, documentation, module, and project-identity accessors. Resolve returned path strings against that configured root before using them on the filesystem.

The package provides a common contract through ProjectLayout and specialized implementations for Maven, Gradle, JavaScript/TypeScript, and Python projects. Each implementation documents its detection rules, metadata behavior, conventional locations, and limitations; use DefaultProjectLayout when no supported build descriptor is available. PomReader is the package utility for parsing and serializing Maven models.

Responsibilities

  • Expose production-source, test-source, and documentation directories as root-relative paths.
  • Discover child modules from build metadata or filesystem conventions where the ecosystem supports it.
  • Provide project identifiers, names, parent identifiers, and a layout type when the underlying metadata supplies them.
  • Offer shared path, directory-scanning, exclusion, and temporary-directory utilities through ProjectLayout.
  • Parse Maven descriptors and serialize Maven models with PomReader.

Choosing a layout

Use the descriptor-detection methods on the applicable implementation before constructing a specialized layout: MavenProjectLayout.isMavenProject(java.io.File) checks for pom.xml, GradleProjectLayout.isGradleProject(java.io.File) checks for build.gradle, JScriptProjectLayout.isPackageJsonPresent(java.io.File) checks for package.json, and isPythonProject(java.io.File) validates a public, named pyproject.toml project. When no specialized descriptor applies, DefaultProjectLayout offers a filesystem-based fallback.

Supported layouts

  • MavenProjectLayout reads pom.xml, including Maven modules, build source roots, resources, tests, project coordinates, and parent coordinates.
  • GradleProjectLayout uses the Gradle Tooling API for project and child-module names and supplies conventional src/main, src/test, and src/site roots. It does not inspect custom Gradle source sets.
  • JScriptProjectLayout reads array-form package.json workspace globs and identifies matching workspace directories containing their own package descriptor. Source, test, and documentation discovery return empty collections.
  • PythonProjectLayout recognizes public projects described by pyproject.toml; source, test, and documentation discovery currently returns empty collections.
  • DefaultProjectLayout provides a filesystem fallback that treats non-excluded immediate subdirectories as module candidates and returns empty location collections.

Typical usage


 java.io.File projectDir = new java.io.File("repo");
 ProjectLayout layout = new MavenProjectLayout().projectDir(projectDir);
 java.util.Collection<String> sources = layout.getSources();
 java.util.Collection<String> tests = layout.getTests();
 java.util.List<String> modules = layout.getModules();

Returned paths are intended to be resolved against projectDir. Layouts use null to indicate that no modules are declared, so callers must handle that result. Some accessors load and parse build descriptors when they are invoked and can report malformed or missing metadata through their documented exceptions.