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 used to record processor initialization and provider output.

    • 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:

    • DEFAULT_TOOLS

      private static final String[] DEFAULT_TOOLS
      Fully qualified names of the built-in function-tool implementations enabled when a provider has not been configured with any tools.

    • promptBundle

      final ResourceBundle promptBundle
      Resource bundle that supplies the default system instructions and guidance rules used when no explicit instructions are configured.

    • reviewerMap

      private final Map<String,Reviewer> reviewerMap
      Reviewers indexed by normalized, dot-free lower-case file extension.

    • report

      private final List<Map<String,Object>> report
      Provider results accumulated during this processor instance's lifetime. Each entry contains the relative file path and the provider message.

    • processedFilesCounter

      private final AtomicInteger processedFilesCounter
      Number of files for which processing has been attempted successfully.

  • 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 each supported normalized extension to the first reviewer that declares it.

    • 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, ProjectLayout projectLayout)
      Applies path matching while preserving default-guidance behavior when no path matcher is configured. In that case, all files are eligible when no default prompt exists; otherwise only the project directory is eligible.
      Overrides:
      match in class AbstractFileProcessor
      Parameters:
      file - candidate file/directory
      projectLayout - current project layout
      Returns:
      true when the candidate should be processed

    • processModule

      protected void processModule(File projectDir, String module) throws IOException
      Processes a module directory after determining whether it is relevant to the configured scan path.

      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 module directories. A matching project directory is additionally processed with the default prompt when one is configured.
      Overrides:
      processParentFiles in class AbstractFileProcessor
      Parameters:
      projectLayout - project layout whose parent files are scanned
      Throws:
      IOException - if listing or processing a child cannot be completed

    • processDefaultGuidance

      private void processDefaultGuidance(ProjectLayout projectLayout, File projectDir)
      Processes the project directory with the configured default prompt when the directory matches the active scan criteria.
      Parameters:
      projectLayout - project layout used for matching and processing
      projectDir - project directory to process

    • processFile

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

    • defaultReport

      private String defaultReport(ProjectLayout projectLayout, File file, String perform)
      Normalizes an empty provider response and increments the processed-file counter.
      Parameters:
      projectLayout - project layout associated with the file; retained for processing-context compatibility
      file - file being counted; retained for processing-context compatibility
      perform - provider response
      Returns:
      the provider response, or "OK" when it is blank

    • process

      public String process(ProjectLayout projectLayout, File file, String guidance)
      Composes the final prompt, dispatches it to the configured provider, and adds the resulting message to this processor's report.
      Overrides:
      process in class AIFileProcessor
      Parameters:
      projectLayout - project layout
      file - file currently being processed
      guidance - extracted guidance and/or default guidance
      Returns:
      provider output, or null when the provider produces no result

    • getInstructions

      public String getInstructions()
      Returns the current base instructions used for processing. If no explicit instructions are configured, this method returns the bundled guidance system instructions.
      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 after normalizing the extension to the key format used by the reviewer registry.
      Parameters:
      extension - file extension (with or without a dot)
      Returns:
      reviewer, or null if none is registered for that extension

    • applyTools

      protected void applyTools(String instructions, String[] prompts, ProcessProvider provider, String[] tools)
      Configures provider tools, expanding the "auto" shortcut to the built-in command, file, and web function-tool classes before delegating to the base processor.
      Overrides:
      applyTools in class AIFileProcessor
      Parameters:
      instructions - provider system instructions
      prompts - prompts to provide to the provider
      provider - configured GenAI provider
      tools - requested tool class names

    • scanDocuments

      public void scanDocuments(File projectDir, String path) throws IOException
      Scans the requested project location and logs the number of files processed after the scan completes.
      Overrides:
      scanDocuments in class AIFileProcessor
      Parameters:
      projectDir - project directory to scan
      path - optional file or directory path relative to the project directory
      Throws:
      IOException - if the scan cannot be completed

    • getReport

      public List<Map<String,Object>> getReport()
      Returns the mutable list of processing results collected so far.
      Returns:
      result entries containing "file" and "message" values

    • getProcessedFiles

      public int getProcessedFiles()
      Returns the total number of files processed.
      Returns:
      the current count of processed files