Package org.machanism.machai.gw.processor


package org.machanism.machai.gw.processor
Provides Ghostwriter's project traversal, prompt processing, inline-guidance, and act-execution pipeline.

The package is organized in layers. AbstractFileProcessor supplies the filesystem layer: it obtains module information from ProjectLayout, traverses project files, applies exact-path and glob: or regex: filters, honors exclusions, and can process modules with a bounded worker pool. Subclasses implement the work performed for files, modules, and parent directories while sharing project-relative path handling and a layered mutable configuration.

Provider-backed file processing

AIFileProcessor builds on that traversal layer and delegates prompts to a selected ProcessProvider. It registers discovered and explicitly added function tools, records project layout values for context tools, and supplies processing context containing the processed relative path and operating-system name. It accepts YAML front matter at the beginning of prompts. The gw.model property selects a provider or model for that request; enabledTools accepts a scalar, YAML list, or mapping; and other front-matter properties are added to the layered configuration for substitution. The errorHandling property is passed to the provider when present.

A line beginning with AIFileProcessor.FILE_INCLUDED_MARKER can include UTF-8 content from an HTTP or HTTPS URL or from a project-relative file:// reference. Included content is parsed recursively, and public configuration groups named by AIFileProcessor.PUBLIC_PROP_GROUP_NAME are available to templates, including ${public.projectName}. Interactive processing recognizes . to terminate, > to accept the current response, and >> to continue without another input prompt.

Inline guidance workflow

GuidanceProcessor specializes the provider-backed processor for source files containing GuidanceProcessor.GUIDANCE_TAG_NAME. It discovers Reviewer implementations with ServiceLoader, selects reviewers by normalized file extension, and lets each reviewer extract guidance while preserving the marker at its source location. The bundled guidance rules are sent with extracted guidance. A configured default prompt can process matching files without an inline marker. Results contain a project-relative file path and provider message, while GuidanceProcessor.getProcessedFiles() counts attempts that produced a normalized report response.

Act and episode workflow

ActProcessor loads TOML act definitions from the built-in /acts/ classpath resources, configured local directories, HTTP or HTTPS locations, or explicit TOML/content files. Acts may inherit through basedOn; ${super.value} splices inherited values into child properties. default.* entries provide fallbacks and public.prompt exposes the command prompt to act templates. A leading > expands an ad-hoc command into the task act. An act suffix, such as review#1,3!, selects episodes 1 and 3 and disables continuation in normal order. Act outputs and merged properties are available through ActProcessor.getResults() and ActProcessor.getActProperties(). Episode front matter may request enabledTools: auto to select tools for that episode through a provider-assisted request; an auto mapping may provide query text to guide that selection, rather than directly disabling tools. Selected tools are cached for the act episode.

Episodes owns the ordered prompts of an act. It supports regular execution, explicitly selected 1-based episode IDs, repeat callbacks, numeric jumps, and heading-name jumps. It validates selected IDs, records callback results through its owning act processor, and exposes episode names and current episode metadata through Episodes.getActInformation(int). An unknown heading destination raises EpisodeNotFoundException.

Command-line entry point and shared types

Ghostwriter parses command-line options and configuration properties, applies precedence, and selects guidance mode by default or act mode through --act. It configures project, model, instruction, exclusion, thread, and scan-path settings, supports multi-line console input, and translates processing failures into exit codes. GWConstants centralizes the configuration keys and formatting values. ProjectContextKey names the operating-system, project identity, layout, source, test, documentation, and module values stored for project-context tools.

Typical usage

GuidanceProcessor guidance = new GuidanceProcessor(projectDir, "openai:model", configurator);
guidance.setInstructions("Follow the project's coding standards.");
guidance.scanDocuments(projectDir, "glob:**/*.java");

ActProcessor acts = new ActProcessor(projectDir, "openai:model", configurator);
acts.setAct("review#1,3! Check correctness and error handling");
acts.process(projectLayout);
See Also:
  • Class
    Description
    Abstract base implementation for processors that traverse project directories and perform work on their files and folders.
    Signals that an act definition could not be found in the configured act locations or on the classpath.
    Processes named action definitions (“acts”) and executes their prompts against a project, a project directory, or matching files by delegating the actual AI interaction to AIFileProcessor.
    File processor that drives a configured ProcessProvider provider with project-aware context, prompt metadata, optional external prompt inclusions, public configuration substitution, and function-tool registration.
    Signals that an episode requested by name could not be resolved.
    Maintains an ordered collection of act episode prompts and provides execution helpers that support several playback strategies.
    Command-line entry point for the Ghostwriter application.
    Mutable holder for startup settings resolved before processor creation.
    Processes project files that contain inline guidance comments and dispatches the extracted instructions to the configured AI provider.
    Defines property names and shared formatting values used by Ghostwriter configuration and runtime processing.
    Represents the context metadata keys used for evaluating and storing project layouts.