{ "$schema": "https://raw.githubusercontent.com/machanism-org/machai/refs/heads/main/bindex-core/src/main/resources/schema/bindex-schema-v2.json", "id": "org.machanism.machai:project-layout:1.2.0-SNAPSHOT", "name": "org.machanism.machai:project-layout", "version": "1.2.0-SNAPSHOT", "location": { "repositoryType": "Maven", "repositoryUrl": "https://machai.machanism.org/project-layout", "coordinates": { "group": "org.machanism.machai", "artifactId": "project-layout", "version": "1.2.0-SNAPSHOT", "extension": "jar" } }, "description": "Project Layout is a Java utility library for describing, detecting, and working with conventional project directory layouts in a consistent way. It is intended for build tooling, plugins, automation utilities, repository scanners, documentation processors, and code generation workflows that need to locate well-known project directories reliably across different project types. The library centers on a common org.machanism.machai.project.layout.ProjectLayout abstraction representing a project root together with root-relative source, test, documentation, and module locations. It provides specialized implementations for Maven, Gradle, JavaScript and TypeScript workspaces, Python projects, and generic filesystem-based projects. The org.machanism.machai.project.ProjectLayoutManager entry point detects an effective layout by inspecting project metadata such as Maven, Gradle, JavaScript, or Python build files. The org.machanism.machai.project.ProjectProcessor abstraction recursively scans project roots and nested modules, delegating concrete leaf project handling to subclasses. The org.machanism.machai.project.layout package exposes a uniform API for source, test, documentation, module, identity, and root-relative path information, while MavenProjectLayout, GradleProjectLayout, JScriptProjectLayout, PythonProjectLayout, DefaultProjectLayout, and PomReader encapsulate ecosystem-specific layout and metadata rules.", "authors": [ { "name": "Machanism.org", "website": "https://machai.machanism.org/project-layout" } ], "license": "Apache License, Version 2.0", "classification": { "type": "library", "domains": [ "Build Tooling", "Project Layout Detection", "Repository Scanning", "Developer Tooling", "Automation Utilities", "Documentation Processing", "Multi-module Project Processing" ], "languages": [ { "name": "Java", "version": "8+" } ], "layers": [ "Utils", "Infrastructure" ], "usageContext": [ "Detecting a project layout from a filesystem root directory", "Querying root-relative source, test, documentation, and module directories", "Processing project roots and nested modules through a reusable processor abstraction", "Building plugins and automation tools that must work across Maven, Gradle, JavaScript workspace, Python, and generic projects", "Resolving layout metadata before reading, writing, scanning, indexing, or generating files", "Parsing Maven pom.xml metadata through a helper utility" ], "targetEnvironment": [ "Java" ], "integrations": [ "Maven", "Gradle", "Node.js", "Python" ] }, "constructors": [ { "package": "org.machanism.machai.project.layout", "signature": "public org.machanism.machai.project.layout.MavenProjectLayout()", "description": "Creates a Maven-specific ProjectLayout implementation. The layout reads Maven-oriented information from conventional directory structure and pom.xml metadata, reports Maven source and test roots, exposes multi-module reactor definitions, and derives project identifiers from the Maven model.", "examples": [ { "snippet": "java.io.File projectDir = new java.io.File(\"C:\\\\workspace\\\\sample-maven-project\");\norg.machanism.machai.project.layout.MavenProjectLayout layout = new org.machanism.machai.project.layout.MavenProjectLayout().projectDir(projectDir);\njava.util.Collection sources = layout.getSources();\njava.util.Collection tests = layout.getTests();\njava.util.Collection documents = layout.getDocuments();\njava.util.List modules = layout.getModules();", "description": "How to use it: create the Maven layout, configure it with a project root directory, and query Maven source, test, documentation, and module paths as root-relative strings." } ] }, { "package": "org.machanism.machai.project.layout", "signature": "public org.machanism.machai.project.layout.GradleProjectLayout()", "description": "Creates a Gradle-specific ProjectLayout implementation. It uses Gradle project conventions and Gradle tooling information to inspect Gradle projects and expose child project names together with conventional source, test, and documentation roots.", "examples": [ { "snippet": "java.io.File projectDir = new java.io.File(\"C:\\\\workspace\\\\gradle-build\");\norg.machanism.machai.project.layout.GradleProjectLayout layout = new org.machanism.machai.project.layout.GradleProjectLayout().projectDir(projectDir);\njava.util.List modules = layout.getModules();\njava.util.Collection sources = layout.getSources();\njava.util.Collection documents = layout.getDocuments();", "description": "How to use it: instantiate the Gradle layout for a Gradle project root and read modules and conventional directory locations through the common ProjectLayout API." } ] }, { "package": "org.machanism.machai.project.layout", "signature": "public org.machanism.machai.project.layout.JScriptProjectLayout()", "description": "Creates a JavaScript and TypeScript project layout utility. It parses package.json and resolves JavaScript workspace module patterns against the filesystem while preserving the same common layout API used by other project types.", "examples": [ { "snippet": "java.io.File projectDir = new java.io.File(\"C:\\\\workspace\\\\js-monorepo\");\norg.machanism.machai.project.layout.JScriptProjectLayout layout = new org.machanism.machai.project.layout.JScriptProjectLayout().projectDir(projectDir);\njava.util.List modules = layout.getModules();\njava.lang.String projectId = layout.getProjectId();", "description": "How to use it: bind the JavaScript layout to a package.json-based repository and read workspace modules and project identity information." } ] }, { "package": "org.machanism.machai.project.layout", "signature": "public org.machanism.machai.project.layout.PythonProjectLayout()", "description": "Creates a Python project layout implementation. It identifies Python project structure from pyproject.toml conventions and related metadata while exposing source, test, documentation, and module access through the shared ProjectLayout contract.", "examples": [ { "snippet": "java.io.File projectDir = new java.io.File(\"C:\\\\workspace\\\\python-project\");\norg.machanism.machai.project.layout.PythonProjectLayout layout = new org.machanism.machai.project.layout.PythonProjectLayout().projectDir(projectDir);\njava.util.Collection tests = layout.getTests();\njava.util.Collection documents = layout.getDocuments();", "description": "How to use it: instantiate the Python layout for a Python project root and consume it through the same methods used for other ecosystems." } ] }, { "package": "org.machanism.machai.project.layout", "signature": "public org.machanism.machai.project.layout.DefaultProjectLayout()", "description": "Creates a minimal fallback ProjectLayout implementation used when no ecosystem-specific model applies. It provides generic filesystem-based behavior for repositories that cannot be classified as Maven, Gradle, JavaScript, or Python projects.", "examples": [ { "snippet": "java.io.File repoDir = new java.io.File(\"C:\\\\workspace\\\\generic-repo\");\norg.machanism.machai.project.layout.DefaultProjectLayout layout = new org.machanism.machai.project.layout.DefaultProjectLayout().projectDir(repoDir);\njava.util.List modules = layout.getModules();", "description": "How to use it: configure the fallback layout with a directory when a repository does not expose known build metadata, then inspect generic module information." } ] }, { "package": "org.machanism.machai.project.layout", "signature": "public org.machanism.machai.project.layout.PomReader()", "description": "Creates a utility for reading and processing Maven pom.xml files into Maven model objects. PomReader provides Maven model parsing and lightweight property replacement support for POM data.", "examples": [ { "snippet": "java.io.File pomFile = new java.io.File(\"C:\\\\workspace\\\\sample-maven-project\\\\pom.xml\");\norg.machanism.machai.project.layout.PomReader reader = new org.machanism.machai.project.layout.PomReader();\norg.apache.maven.model.Model model = reader.getProjectModel(pomFile);\njava.util.Map properties = reader.getPomProperties();", "description": "How to use it: create a PomReader, parse a pom.xml file into an org.apache.maven.model.Model, and inspect Maven properties captured during processing." } ] } ], "features": [ { "package": "org.machanism.machai.project", "name": "detectProjectLayout", "signature": "public static org.machanism.machai.project.layout.ProjectLayout detectProjectLayout(java.io.File projectDir) throws java.io.FileNotFoundException", "description": "Detects the effective ProjectLayout for a filesystem directory by inspecting project metadata such as Maven, Gradle, JavaScript, or Python build files. It returns a specialized layout implementation when possible and a generic fallback otherwise, allowing callers to use one uniform API for heterogeneous project structures.", "examples": [ { "snippet": "java.io.File projectDir = new java.io.File(\"C:\\\\path\\\\to\\\\project\");\norg.machanism.machai.project.layout.ProjectLayout layout = org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(projectDir);\njava.util.Collection sources = layout.getSources();\njava.util.Collection tests = layout.getTests();\njava.util.Collection documents = layout.getDocuments();", "description": "How to use it: point the library at a project root, let ProjectLayoutManager choose the right implementation, and then read standardized source, test, and documentation directory lists." } ] }, { "package": "org.machanism.machai.project", "name": "scanFolder", "signature": "public void scanFolder(java.io.File projectDir) throws java.io.IOException", "description": "Scans a project directory, delegates per-module processing when modules are present, and invokes user-defined folder processing logic for leaf projects. This supports reusable recursive repository traversal while letting subclasses define the actual processing behavior.", "examples": [ { "snippet": "java.io.File repoDir = new java.io.File(\"C:\\\\path\\\\to\\\\repo\");\norg.machanism.machai.project.ProjectProcessor processor = new org.machanism.machai.project.ProjectProcessor() {\n @java.lang.Override\n public void processFolder(org.machanism.machai.project.layout.ProjectLayout processorLayout) {\n java.util.Collection sourceRoots = processorLayout.getSources();\n java.util.Collection docRoots = processorLayout.getDocuments();\n System.out.println(sourceRoots);\n System.out.println(docRoots);\n }\n};\nprocessor.scanFolder(repoDir);", "description": "How to use it: implement ProjectProcessor.processFolder with custom work such as indexing or reporting, then call scanFolder on the repository root to process leaf projects and nested modules." } ] }, { "package": "org.machanism.machai.project.layout", "name": "getModules", "signature": "public java.util.List getModules()", "description": "Returns child project modules discovered from build metadata or common multi-module conventions. Module discovery can come from Maven reactor modules, Gradle child projects, JavaScript workspaces, or generic filesystem-based fallback behavior.", "examples": [ { "snippet": "org.machanism.machai.project.layout.ProjectLayout layout = org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(new java.io.File(\"C:\\\\path\\\\to\\\\repository\"));\njava.util.List modules = layout.getModules();\nfor (java.lang.String module : modules) {\n System.out.println(module);\n}", "description": "How to use it: ask the detected layout for modules to decide whether to recurse into child projects or process the current project as a leaf." } ] }, { "package": "org.machanism.machai.project.layout", "name": "getSources", "signature": "public abstract java.util.Collection getSources()", "description": "Returns root-relative production source directories for the active project layout. Callers resolve these relative paths against the project root before reading or writing files.", "examples": [ { "snippet": "org.machanism.machai.project.layout.ProjectLayout layout = org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(new java.io.File(\"C:\\\\path\\\\to\\\\project\"));\nfor (java.lang.String sourceRoot : layout.getSources()) {\n java.io.File absoluteDir = new java.io.File(layout.getProjectDir(), sourceRoot);\n System.out.println(absoluteDir.getAbsolutePath());\n}", "description": "How to use it: retrieve standardized source folders and resolve them against the project root for scanners, compilers, generators, or indexing workflows." } ] }, { "package": "org.machanism.machai.project.layout", "name": "getTests", "signature": "public abstract java.util.Collection getTests()", "description": "Returns root-relative test directories for the active project layout, helping tools distinguish validation assets from production inputs.", "examples": [ { "snippet": "org.machanism.machai.project.layout.ProjectLayout layout = org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(new java.io.File(\"C:\\\\path\\\\to\\\\project\"));\njava.util.Collection testRoots = layout.getTests();\nSystem.out.println(testRoots);", "description": "How to use it: query test roots for QA pipelines, code analysis, test reporting, or any workflow that needs to separate test files from application files." } ] }, { "package": "org.machanism.machai.project.layout", "name": "getDocuments", "signature": "public abstract java.util.Collection getDocuments()", "description": "Returns root-relative documentation directories for the active project layout, such as conventional documentation or site folders used by build and documentation tooling.", "examples": [ { "snippet": "org.machanism.machai.project.layout.ProjectLayout layout = org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(new java.io.File(\"C:\\\\path\\\\to\\\\project\"));\nfor (java.lang.String documentRoot : layout.getDocuments()) {\n java.io.File docsDir = new java.io.File(layout.getProjectDir(), documentRoot);\n System.out.println(docsDir.getAbsolutePath());\n}", "description": "How to use it: locate documentation folders in a build-tool-neutral way before generating sites, aggregating docs, or preparing documentation processing jobs." } ] }, { "package": "org.machanism.machai.project.layout", "name": "getProjectModel", "signature": "public org.apache.maven.model.Model getProjectModel(java.io.File pomFile)", "description": "Reads and processes a Maven pom.xml file into a Maven org.apache.maven.model.Model, applying lightweight property replacement support for Maven metadata extraction.", "examples": [ { "snippet": "java.io.File pomFile = new java.io.File(\"C:\\\\path\\\\to\\\\project\\\\pom.xml\");\norg.machanism.machai.project.layout.PomReader reader = new org.machanism.machai.project.layout.PomReader();\norg.apache.maven.model.Model model = reader.getProjectModel(pomFile);\nSystem.out.println(model.getArtifactId());", "description": "How to use it: parse pom.xml into a structured Maven model and inspect artifact metadata, modules, parent information, or build configuration." } ] }, { "package": "org.machanism.machai.project.layout", "name": "getPomProperties", "signature": "public java.util.Map getPomProperties()", "description": "Returns Maven properties collected while reading POM data, enabling custom tooling to inspect property values used during model processing.", "examples": [ { "snippet": "org.machanism.machai.project.layout.PomReader reader = new org.machanism.machai.project.layout.PomReader();\nreader.getProjectModel(new java.io.File(\"C:\\\\path\\\\to\\\\project\\\\pom.xml\"));\njava.util.Map properties = reader.getPomProperties();\nfor (java.util.Map.Entry entry : properties.entrySet()) {\n System.out.println(entry.getKey() + \"=\" + entry.getValue());\n}", "description": "How to use it: parse a POM first, then inspect collected Maven properties for diagnostics, reporting, or secondary configuration logic." } ] } ], "customizations": [ { "name": "org.machanism.machai.project.ProjectProcessor.processFolder", "package": "org.machanism.machai.project", "description": "Primary extension point for custom project-processing workflows. Developers implement processFolder(org.machanism.machai.project.layout.ProjectLayout) to define the logic that should run for each detected leaf project after module traversal has been handled.", "type": "abstract method", "examples": [ { "snippet": "org.machanism.machai.project.ProjectProcessor processor = new org.machanism.machai.project.ProjectProcessor() {\n @java.lang.Override\n public void processFolder(org.machanism.machai.project.layout.ProjectLayout processorLayout) {\n java.lang.String id = processorLayout.getProjectId();\n java.util.Collection sources = processorLayout.getSources();\n System.out.println(id + \" -> \" + sources);\n }\n};\nprocessor.scanFolder(new java.io.File(\"C:\\\\path\\\\to\\\\repo\"));", "description": "How to use it: implement the abstract method to customize project handling, then run scanFolder to execute your logic across detected leaf projects." } ] }, { "name": "org.machanism.machai.project.layout.ProjectLayout", "package": "org.machanism.machai.project.layout", "description": "Abstract base type for creating new ecosystem-specific layout resolvers. Developers can extend this class to support additional build systems or organizational conventions while preserving the same API for sources, tests, documents, modules, and project identifiers.", "type": "abstract class", "examples": [ { "snippet": "public class com.example.tooling.CustomProjectLayout extends org.machanism.machai.project.layout.ProjectLayout {\n @java.lang.Override\n public java.util.Collection getSources() {\n return java.util.Arrays.asList(\"app/src\");\n }\n\n @java.lang.Override\n public java.util.Collection getDocuments() {\n return java.util.Arrays.asList(\"docs\");\n }\n\n @java.lang.Override\n public java.util.Collection getTests() {\n return java.util.Arrays.asList(\"app/test\");\n }\n}", "description": "How to use it: extend ProjectLayout to model a custom project convention and expose root-relative folders through the standard API." } ] } ], "studs": [ { "name": "org.machanism.machai.project.layout.ProjectLayout", "package": "org.machanism.machai.project.layout", "type": "abstract class", "description": "Base abstraction for describing a project's conventional on-disk layout. It represents a project directory together with root-relative source, test, documentation, module, and identity information, and is implemented by MavenProjectLayout, GradleProjectLayout, JScriptProjectLayout, PythonProjectLayout, and DefaultProjectLayout.", "methods": [ "public abstract java.util.Collection getSources()", "public abstract java.util.Collection getDocuments()", "public abstract java.util.Collection getTests()", "public java.util.List getModules()", "public org.machanism.machai.project.layout.ProjectLayout projectDir(java.io.File projectDir)" ], "examples": [ { "snippet": "org.machanism.machai.project.layout.ProjectLayout layout = org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(new java.io.File(\"C:\\\\repo\"));\njava.util.Collection sources = layout.getSources();\njava.util.Collection tests = layout.getTests();", "description": "How to use it: consume ProjectLayout polymorphically so the same tooling works regardless of whether the project is Maven, Gradle, JavaScript, Python, or generic." } ], "implement": "org.machanism.machai.project.layout.MavenProjectLayout" }, { "name": "org.machanism.machai.project.ProjectProcessor", "package": "org.machanism.machai.project", "type": "abstract class", "description": "Abstract base class for processing project structures and modules. It provides reusable recursive scanning and delegates concrete folder handling to subclasses via processFolder(ProjectLayout).", "methods": [ "public void scanFolder(java.io.File projectDir) throws java.io.IOException", "protected void processModule(java.io.File projectDir, java.lang.String module) throws java.io.IOException", "public abstract void processFolder(org.machanism.machai.project.layout.ProjectLayout processor)", "public org.machanism.machai.project.layout.ProjectLayout getProjectLayout(java.io.File projectDir) throws java.io.FileNotFoundException" ], "examples": [ { "snippet": "org.machanism.machai.project.ProjectProcessor processor = new org.machanism.machai.project.ProjectProcessor() {\n @java.lang.Override\n public void processFolder(org.machanism.machai.project.layout.ProjectLayout processorLayout) {\n System.out.println(processorLayout.getProjectName());\n }\n};\nprocessor.scanFolder(new java.io.File(\"C:\\\\repo\"));", "description": "How to use it: implement the abstract processor to build a reusable repository traversal tool that handles each detected leaf project." } ], "implement": null } ], "examples": [ { "title": "Install as a Maven dependency and detect a project layout", "scenario": "Use Project Layout as a Java library inside a build tool, plugin, repository scanner, or documentation processor.", "steps": [ "Add the Maven dependency org.machanism.machai:project-layout:1.2.0-SNAPSHOT to your application or plugin.", "Create a java.io.File pointing to the project or repository root you want to inspect.", "Call org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(java.io.File).", "Read sources, tests, documents, identifiers, and optional modules from the returned org.machanism.machai.project.layout.ProjectLayout.", "Resolve returned root-relative paths against the project root before performing filesystem operations." ], "snippet": "\n org.machanism.machai\n project-layout\n 1.2.0-SNAPSHOT\n\n\njava.io.File projectDir = new java.io.File(\"C:\\\\workspace\\\\target-project\");\norg.machanism.machai.project.layout.ProjectLayout layout = org.machanism.machai.project.ProjectLayoutManager.detectProjectLayout(projectDir);\nSystem.out.println(layout.getProjectLayoutType());\nSystem.out.println(layout.getSources());\nSystem.out.println(layout.getTests());\nSystem.out.println(layout.getDocuments());", "description": "This practical how-to-use-it scenario shows installation, minimal configuration through the project root File, and runtime invocation for automatic layout detection." }, { "title": "Process a multi-module repository with a custom ProjectProcessor", "scenario": "Build a reusable repository traversal pipeline that works across supported project ecosystems.", "steps": [ "Install the project-layout dependency in your Java application.", "Create a subclass or anonymous implementation of org.machanism.machai.project.ProjectProcessor.", "Implement processFolder(org.machanism.machai.project.layout.ProjectLayout) with custom processing logic.", "Invoke scanFolder(java.io.File) on the repository root.", "Let the processor recurse through detected modules and execute your logic for each leaf project." ], "snippet": "org.machanism.machai.project.ProjectProcessor processor = new org.machanism.machai.project.ProjectProcessor() {\n @java.lang.Override\n public void processFolder(org.machanism.machai.project.layout.ProjectLayout processorLayout) {\n System.out.println(\"Project: \" + processorLayout.getProjectId());\n System.out.println(\"Sources: \" + processorLayout.getSources());\n System.out.println(\"Docs: \" + processorLayout.getDocuments());\n }\n};\nprocessor.scanFolder(new java.io.File(\"C:\\\\workspace\\\\repo-root\"));", "description": "This example demonstrates configuring the extension point and running it in a real-world module traversal scenario." }, { "title": "Read Maven metadata with PomReader", "scenario": "Use Maven-specific helper utilities when you need parsed pom.xml information in addition to general layout detection.", "steps": [ "Add the project-layout dependency to your Java application.", "Create an instance of org.machanism.machai.project.layout.PomReader.", "Pass a java.io.File pointing to pom.xml into getProjectModel(java.io.File).", "Inspect the returned org.apache.maven.model.Model for artifact and build metadata.", "Optionally inspect collected POM properties through getPomProperties()." ], "snippet": "org.machanism.machai.project.layout.PomReader reader = new org.machanism.machai.project.layout.PomReader();\norg.apache.maven.model.Model model = reader.getProjectModel(new java.io.File(\"C:\\\\workspace\\\\target-project\\\\pom.xml\"));\nSystem.out.println(model.getGroupId());\nSystem.out.println(model.getArtifactId());\nSystem.out.println(reader.getPomProperties());", "description": "This how-to-use-it scenario shows installing the library, configuring a PomReader instance, and invoking it to extract Maven model data." } ], "dependencies": [ "commons-io:commons-io:2.11.0", "org.tomlj:tomlj:1.1.1", "com.fasterxml.jackson.core:jackson-databind", "org.apache.commons:commons-lang3", "ch.qos.logback:logback-classic:1.3.16", "org.gradle:gradle-tooling-api:7.3-20210825160000+0000", "org.apache.maven:maven-model", "org.apache.maven:maven-model-builder" ] }