Package org.machanism.machai.gw.processor
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:
-
ClassDescriptionAbstract 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 configuredProcessProviderprovider 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.