reisidalt-f/reins-nlce

Purpose and delivery modes

Reins is a Java/Maven natural-language compilation engine: Markdown specifications are the source language, and an LLM produces target code through constrained tools. It is delivered as a Maven plugin, CLI, and embeddable Java library. Entry surfaces are src/main/java/br/com/dizeno/reins/run/mojo/CompileMojo.java, src/main/java/br/com/dizeno/reins/run/cli/ReinsCli.java, and src/main/java/br/com/dizeno/reins/run/library/ReinsLibrary.java; ReinsRunner.java composes runtime execution.

Configuration and invocation boundary

Configuration is loaded and validated into a shared model before any filesystem or LLM work. src/main/java/br/com/dizeno/reins/run/config/ReinsConfigLoader.java, src/main/java/br/com/dizeno/reins/run/config/ConfigValidator.java, and src/main/java/br/com/dizeno/reins/run/config/ReinsConfig.java govern provider selection, scanning, targets, tooling permissions, tracking, and reasoning settings. Maven exposes compile, clean, and reasoning-note operations via CompileMojo.java, CleanMojo.java, and AddReasoningNoteMojo.java.

Source discovery and dependency ordering

Markdown inputs are discovered from configured roots, then parsed into a reference graph whose ordering drives compilation and contextual attachments. Key boundaries are src/main/java/br/com/dizeno/reins/source/scanner/CoderMdScanner.java, src/main/java/br/com/dizeno/reins/source/graph/MarkdownDependencyGraphBuilder.java, and src/main/java/br/com/dizeno/reins/source/graph/ProcessingOrderResolver.java. Reference resolution supports relative paths and test-to-main fallback, while path/domain types preserve source scope.

Compilation orchestration and incrementality

src/main/java/br/com/dizeno/reins/compilation/CompilationService.java coordinates a project run: construct source work, prefilter unchanged items, process in dependency order, invoke project-level reasoning where configured, and report results. Per-source work passes through the phase chain in src/main/java/br/com/dizeno/reins/compilation/pipeline/PhaseChain.java, including source read, tracking load, request construction, reasoning, outcome branching, and result printing. Output is written through src/main/java/br/com/dizeno/reins/compilation/OutputWriter.java.

Incremental state is a filesystem-backed manifest/fingerprint subsystem: src/main/java/br/com/dizeno/reins/compilation/tracking/CompilationTrackingStore.java, SourceFingerprintService.java, and RecompilationDecider.java. It determines whether source and mapped outputs can be skipped, and cleanup removes tracked artifacts rather than broadly deleting target paths.

Reasoning runtime and scripts

The reasoning service runs a multi-turn, stateful pipeline: initialize context, render reference/context messages, dispatch inference, parse directives, execute permitted tools, and complete or extend turns. The core is src/main/java/br/com/dizeno/reins/reasoning/DefaultReasoningService.java, planned/executed through ReasoningPipelineExecutor.java and phase implementations under src/main/java/br/com/dizeno/reins/reasoning/phase/.

FreeMarker scripts make prompt composition and phase behavior customizable, with classpath defaults in src/main/resources/reasoning/reasoning-pipeline.ftl, system-context.ftl, and context-build.ftl; runtime resolution is centered on src/main/java/br/com/dizeno/reins/reasoning/scripting/ScriptRegistry.java.

LLM provider boundary

Provider-neutral inference flows through src/main/java/br/com/dizeno/reins/reasoning/inference/InferenceService.java and inference/llm/service/DefaultLlmService.java. Adapter/registry abstractions isolate external services: Gemini at inference/llm/adapters/GeminiProviderAdapter.java and Ollama at OllamaProviderAdapter.java, with HTTP clients and retry policies beneath each provider. A stub adapter supports non-provider execution paths.

Tooling and security boundary

LLM output cannot directly mutate the project. Directives are parsed and routed through src/main/java/br/com/dizeno/reins/reasoning/ReasoningToolOperationHandler.java into tooling/ToolingService.java and operation handlers. File reads/writes/patches/deletes and script execution are constrained by base-path mappings and policy in tooling/file/BasePathResolver.java, FilePolicy.java, and global src/main/java/br/com/dizeno/reins/security/PathValidator.java. This is the critical containment boundary between untrusted model responses and the local filesystem.