Package org.machanism.machai.gw.processor

Class GuidanceProcessor

java.lang.Object
org.machanism.machai.project.ProjectProcessor
org.machanism.machai.gw.processor.AbstractFileProcessor
org.machanism.machai.gw.processor.AIFileProcessor
org.machanism.machai.gw.processor.GuidanceProcessor
public class GuidanceProcessor extends AIFileProcessor
Processes project files that contain inline guidance comments and dispatches the extracted instructions to the configured AI provider.

The processor scans project files and modules selected by the configured path matcher. For supported file types, it uses Reviewer implementations discovered through ServiceLoader to extract mandatory guidance instructions from source comments. If a default prompt is configured, matching files without explicit guidance can still be processed by applying that default prompt.

Guidance comments are identified by the special marker GUIDANCE_TAG_NAME. Reviewers are responsible for preserving marker comments in their original source locations while allowing the provider to update surrounding content. Processing results are collected in getReport() as relative file paths and provider messages.

Examples


 Configurator configurator = ...;
 GuidanceProcessor processor = new GuidanceProcessor(new File("."), "my-model", configurator);
 processor.process(projectLayout, new File("src/main/java/App.java"), "Ensure documentation is current.");
 List<Map<String, Object>> report = processor.getReport();

A supported source file may include a guidance block such as: 


 /*
  * &#64;guidance: Keep this class documented and ensure examples compile.
 *&#47;
 public class App {
 }

  • Field Details

    • logger

      private static final org.slf4j.Logger logger
      Logger for documentation input processing events.

    • GUIDANCE_TAG_NAME

      public static final String GUIDANCE_TAG_NAME
      Special comment marker used to identify guidance blocks inside supported files.

      A guidance block begins with this marker and contains mandatory processing instructions for the AI provider. For example, Java reviewers can extract comments that start with /*@guidance: and pass their contents to this processor. The marker itself must remain unchanged in processed files so future runs can discover the same guidance.

      See Also:

    • promptBundle

      final ResourceBundle promptBundle
      Resource bundle supplying prompt templates for generators.

    • reviewerMap

      private final Map<String,Reviewer> reviewerMap
      Reviewer associations keyed by file extension.

    • report

      private final List<Map<String,Object>> report

  • Constructor Details

    • GuidanceProcessor

      public GuidanceProcessor(File rootDir, String genai, Configurator configurator)
      Constructs a new GuidanceProcessor for processing files with guidance tags.

      Initializes the processor with the specified root directory, GenAI model identifier, and configuration. Logs the root directory and GenAI model (if provided), and loads reviewer information for guidance processing.

      Parameters:
      rootDir - the root directory to scan for files
      genai - the GenAI model identifier to use for processing (may be null)
      configurator - the configuration object for property resolution and runtime settings

  • Method Details

    • loadReviewers

      void loadReviewers()
      Loads file reviewers via the ServiceLoader registry, mapping supported file extensions to a reviewer.

    • normalizeExtensionKey

      static String normalizeExtensionKey(String extension)
      Normalizes a file extension (with or without a leading dot) into a lower-case lookup key.
      Parameters:
      extension - the extension to normalize (e.g., "java" or ".java")
      Returns:
      normalized key, or null if the input is blank

    • match

      protected boolean match(File file, File projectDir)
      Applies matching logic and default-guidance behavior.
      Overrides:
      match in class AbstractFileProcessor
      Parameters:
      file - candidate file/directory
      projectDir - current project directory
      Returns:
      true when the candidate should be processed

    • processModule

      protected void processModule(File projectDir, String module) throws IOException
      Processes a module directory.

      When a scan directory or pattern is configured, modules are only processed when the module itself matches or contains the scan directory.

      Overrides:
      processModule in class ProjectProcessor
      Parameters:
      projectDir - parent project directory
      module - module relative path
      Throws:
      IOException - if scanning the module fails

    • processParentFiles

      protected void processParentFiles(ProjectLayout projectLayout) throws IOException
      Processes files and folders under the parent project directory (excluding modules).
      Overrides:
      processParentFiles in class AbstractFileProcessor
      Parameters:
      projectLayout - project layout
      Throws:
      IOException - if file reading fails

    • processFile

      protected void processFile(ProjectLayout projectLayout, File file) throws IOException
      Extracts guidance for a file and, when present, performs provider processing.
      Overrides:
      processFile in class AbstractFileProcessor
      Parameters:
      projectLayout - project layout
      file - file to process
      Throws:
      IOException - if reading the file or provider execution fails

    • process

      public String process(ProjectLayout projectLayout, File file, String guidance)
      Composes the final prompt and dispatches it to the configured provider.
      Overrides:
      process in class AIFileProcessor
      Parameters:
      projectLayout - project layout
      file - file currently being processed
      guidance - extracted guidance and/or default guidance
      Returns:
      provider output

    • getInstructions

      public String getInstructions()
      Returns the current base instructions used for processing.
      Overrides:
      getInstructions in class AIFileProcessor
      Returns:
      the configured instruction text

    • parseFile

      String parseFile(File projectDir, File file) throws IOException
      Uses a Reviewer (based on file extension) to extract guidance.
      Parameters:
      projectDir - project root directory
      file - file being parsed
      Returns:
      guidance text, or null if the file type is not supported
      Throws:
      IOException - if the file cannot be read

    • getReviewerForExtension

      Reviewer getReviewerForExtension(String extension)
      Resolves a reviewer for a given file extension.
      Parameters:
      extension - file extension (with or without a dot)
      Returns:
      reviewer, or null if none is registered for that extension

    • getReport

      public List<Map<String,Object>> getReport()
      Returns:
      the report