Package org.machanism.machai.gw.processor
Processor architecture
AbstractFileProcessor is the traversal foundation. It obtains module
definitions through ProjectLayout,
recursively lists files, filters excluded paths, supports exact paths and
glob: or regex: matchers, and can process modules concurrently
with a bounded worker pool and configurable shutdown timeout. Subclasses
provide the per-file, module, and parent-directory hooks while sharing
project-relative path handling and a layered mutable configuration.
AIFileProcessor adds provider execution to that foundation. It selects
a provider or model, installs discovered and explicitly registered function
tools, records project layout metadata for context tools, and supplies JSON
processing information containing PROCESSED_FILE_REL_PATH,
PROCESS_MODE, and OS_NAME. It accepts YAML front matter at the
start of prompts: gw.model overrides the provider/model for that
request, while enabledTools accepts a scalar, YAML list, or mapping.
Other front-matter values are added to the layered configuration and can
participate in substitution; errorHandling is also propagated to the
provider when configured.
Prompt and instruction lines beginning with
AIFileProcessor.FILE_INCLUDED_MARKER include UTF-8 content from an
HTTP or HTTPS URL or a project-relative file:// reference. Included
content is parsed recursively. Public configuration groups
AIFileProcessor.PUBLIC_PROP_GROUP_NAME are available to templates,
including placeholders such as ${public.projectName}. Interactive
processing recognizes . to terminate, > to accept the current
response, and >> to continue without another interactive prompt.
Inline guidance workflow
GuidanceProcessor specializes AIFileProcessor for source files
containing GuidanceProcessor.GUIDANCE_TAG_NAME. It discovers a
Reviewer for each file extension via
ServiceLoader, delegates comment parsing to that reviewer,
and sends the extracted guidance together with the bundled guidance rules to
the provider. Reviewers preserve the guidance marker at its original source
location. A configured default prompt can process matching files without an
inline marker, and GuidanceProcessor.getReport() records relative file
paths and provider messages while GuidanceProcessor.getProcessedFiles()
counts attempted file processing.
Act and episode workflow
ActProcessor loads TOML act definitions from the built-in
/acts/ classpath resources, a local acts directory, an HTTP or HTTPS
location, or an explicit TOML or content file. Definitions can inherit through
basedOn; ${super.value} inserts the inherited string or prompt
value. default.* properties 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 results are available through
ActProcessor.getResults() and merged properties through
ActProcessor.getActProperties().
Episodes owns the ordered prompts of an act. It executes them in normal
order, in an explicitly selected order, or repeatedly when a callback requests
another iteration. It supports 1-based numeric jumps and heading-name jumps,
validates explicitly selected episode IDs, records episode results through its
owning ActProcessor, and exposes episode names and current-episode
metadata through Episodes.getActInformation(int). Episode front matter
may request enabledTools: auto; an optional mapping supplies
constraints to the provider-assisted tool selector. An unknown heading
destination is reported by EpisodeNotFoundException.
Command-line entry point and shared types
Ghostwriter parses command-line options and properties-file settings,
resolves precedence, and selects guidance mode by default or act mode through
--act. It also applies project, model, instruction, exclusion, thread,
and scan-path settings, supports interactive multi-line input, and maps
processing failures to exit codes. GWConstants centralizes the
corresponding configuration keys and formatting values. ProjectContextKey
names the operating-system, project identity, layout, source, test,
documentation, and module metadata registered for project-context tools.
EpisodeNotFoundException is the unchecked signal used when an episode
heading cannot be resolved.
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.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.