This document provides guidance for AI assistants working on this codebase.
srcmorph is a prompt-driven source-tree transformer: it walks a source tree and processes each
file through a configurable LLM prompt (by default local via llama.cpp / GGUF models; per model
optionally an OpenAI-compatible API such as OpenRouter), producing
layered output — per-file, then per-package, then per-project. Today it emits structured .ai.md
Markdown summaries for AI-assisted code navigation; the same rule-routed pipeline is generic enough
to eventually emit wikis, architecture docs, diagrams, or source-to-source transformations.
This repository completed its migration to a 3-module Maven reactor. It started as a single
Maven plugin (net.ladenthin:llamacpp-ai-index-maven-plugin) and was restructured into: a
framework-free core library, a standalone CLI, and the original plugin (now a thin wrapper around
the library, renamed to net.ladenthin:srcmorph-maven-plugin). The plugin rename is done:
coordinates, package, goal prefix, and every @Parameter property changed in this step — do not
write aiIndex.* properties, the ai-index goal prefix, or the
net.ladenthin.maven.llamacpp.aiindex package in new documentation or code; use srcmorph.*,
srcmorph, and net.ladenthin.maven.srcmorph.mojo instead (see the plugin module's own section
below). The 1.4.0 reactor release was published to Maven Central from the v1.4.0 tag, and main
has since been moved on to 1.5.0-SNAPSHOT (step 6 of docs/RELEASE.md). A -SNAPSHOT on main
is the normal state between releases — main sits at a plain release version only in the short
window between the release bump and the tag, which is exactly why that step exists: main must
never again carry a version matching something already published.
A fourth module existed temporarily: a tiny relocation-stub POM
(net.ladenthin:llamacpp-ai-index-maven-plugin, pinned at 1.0.4, only a
<distributionManagement><relocation> pointing at srcmorph-maven-plugin:1.1.1) so existing
consumers of the old coordinates get transparently redirected. It was published once, verified
working end-to-end (a clean-environment Maven resolution of the old coordinates correctly followed
the relocation through to the real artifact and its full dependency graph), and then removed from
this reactor — the published 1.0.4 artifact is permanent on Maven Central regardless of what
this repo's module list contains, and it will never need another release, so there was no reason to
keep carrying it (and its versions:set exclusion footgun) in active development.
- Group ID:
net.ladenthin - Java: target bytecode 1.8 (production code), Java 21 test sources, built with JDK 25
- License: Apache 2.0
- Author: Bernard Ladenthin (Copyright 2026)
- Reactor version:
1.5.0-SNAPSHOT(single shared version acrosssrcmorph,srcmorph-cli, andsrcmorph-maven-plugin). Last released version:1.4.0.
llamacpp-ai-index-maven-plugin/ (repo root; reactor parent)
├── pom.xml net.ladenthin:srcmorph-parent:1.5.0-SNAPSHOT (packaging=pom)
│ shared build plugins + dependencyManagement + release profile
├── srcmorph/ CORE LIBRARY net.ladenthin:srcmorph (Java 8, Maven-API-free)
│ └── src/main/java/net/ladenthin/srcmorph/
│ ├── config/ the beans (incl. the shared root SrcMorphConfiguration) + the file loader
│ ├── engine/ GenerateEngine, AggregatePackagesEngine, AggregateProjectEngine,
│ │ CalibrateEngine, ListModelsEngine, SrcMorphException, GenerateResult,
│ │ CalibrationReport, ModelListReport, RunRecord, EngineSupport, ProgressBar
│ ├── indexer/ SourceFileIndexer, PackageIndexer, ProjectIndexer, IndexPlan, CalibrationRunner, ...
│ │ └── generation/ SummaryGenerator + the windows, chunks, map-reduce and time estimate
│ ├── routing/ facts/ document/ prompt/ provider/ support/
│ └── src/test/resources/SmolLM2-135M-Instruct-Q3_K_M.gguf (real-model tests live here)
├── srcmorph-cli/ CLI net.ladenthin:srcmorph-cli (thin jar; users build the runnable one)
│ └── src/main/java/net/ladenthin/srcmorph/cli/
│ ├── Main.java BitcoinAddressFinder cli/Main.java pattern
│ └── configuration/ CConfiguration + CCommand (BAF public-field style)
├── srcmorph-maven-plugin/ Maven plugin net.ladenthin:srcmorph-maven-plugin, goalPrefix srcmorph
│ └── src/main/java/net/ladenthin/maven/srcmorph/mojo/ (5 goal mojos + the abstract AbstractSrcMorphMojo base + RuleSection; renamed package/properties)
├── examples/ config_*.json/.yaml + run_*.sh/.bat + simplelogger.properties
│ └── build-your-own-jar/ pom.xml + build/run scripts: srcmorph-cli + this machine's natives -> srcmorph.jar
├── docs/ RELEASE.md + the ai-index model-benchmark writeups
└── .github/workflows/ CI adapted to the 3-module reactor
Every module inherits its <version> from the parent (net.ladenthin:srcmorph-parent), so
srcmorph/srcmorph-cli/srcmorph-maven-plugin ship in lockstep by construction. Bump their
version reactor-wide with mvn versions:set -DnewVersion=X -DgenerateBackupPoms=false from the
repo root — no exclusions needed today (the relocation-stub module that once required one was
removed after its 1.0.4 release; see "Project Overview" above).
Framework-free: no dependency on org.apache.maven.. anywhere (enforced by
CoreArchitectureTest#coreIsMavenFree, the load-bearing ArchUnit rule for this module). Depends on
net.ladenthin:llama (the llama.cpp JNI binding, used only by the provider package), SLF4J, jspecify
- checker-qual, Jackson (databind + YAML, for
SrcMorphConfigurationFileLoader), Lombok (provided). Package root:net.ladenthin.srcmorph.
config/— mutable JavaBeans (no Maven annotations) bound by Jackson from the one configuration file of the CLI and the plugin, or built in plain Java code. The run's object isSrcMorphConfiguration: one bean holding everything a run needs (baseDirectory,outputDirectory,subtrees,excludes,fileExtensions, the size band,force,regenerateOn(RegenerateOn: which changed header field rewrites a summary),planOnly,pruneOrphans(delete the summaries no planned file produces),generationProvider,profileDirectory,promptDefinitions,aiDefinitions,rules,factDefinitions,generatorVersion/aiVersion/projectName,runRecordFile: the JSON record of a file phase,engine.RunRecord,partsDirectory: each chunked file's map and reduce answers). The file around it isSrcMorphConfigurationFile(srcMorph,packageRules,projectRules, and the CLI'scommand/modelFilter), read bySrcMorphConfigurationFileLoaderthe same way for both surfaces: the extension picks JSON or YAML, a${name}in a parsed value is a property of the caller (the plugin: Maven's; the CLI: the system properties), unknown keys fail, and every relative path resolves against the file's directory (an unsetbaseDirectoryis the caller's default, an unsetoutputDirectoryissrc/site/aibelow the base; an unsetmodelDirectory/profileDirectoryis the file's directory, so a relativemodelPath,templateFileorfactsFileresolves there too). The beans depend on nothing butsupport; a Javadoc link upward is written fully qualified, not imported.routing/— which rule a file, package or project takes:ConditionEvaluator(theconditiontree, incl.contentMatchesunder asupport.ReadBudget),RuleSelector(priority, skip, exactly one fallback),FileContext(what a condition reads of a file).facts/— the fact counters:FactExtractor(the regex counts of a facts file over a source, its[ignore]regions blanked, the facts line a summary starts with),FactDefinitionLoader(afactsFileor<profileDirectory>/<key>.tsv,label<TAB>regexper line, for a rule'sfactsKey),FactGroups.engine/— one class per phase, each constructed from aSrcMorphConfigurationand owning its own AI provider lifecycle (try-with-resources; one model resident at a time):GenerateEngine(plan → validate → planOnly early-out → per-model-group indexing loop + progress bar),AggregatePackagesEngine,AggregateProjectEngine(deterministic listing + optional one-call AI overview),CalibrateEngine(per-model preflight + timing),ListModelsEngine(GET <baseUrl>/modelsper OpenAI-compatible server, rendered byModelListReportas a table and a paste-readyaiDefinitionsblock; no prompt, no model). All five throw the checkedSrcMorphExceptionon misconfiguration, never a MavenMojoExecutionException— callers (the plugin's mojos, the CLI'sMain) wrap it into whatever their own surface expects.ProgressBarisGenerateEngine's.indexer/— the walk/plan/write orchestration (SourceFileIndexer,PackageIndexer,ProjectIndexerwith its optionalProjectOverview,IndexPlan,CalibrationRunner, ...); its sub-packageindexer.generationgenerates one summary body (SummaryGenerator: single-shot, map-reduce, sampled chunks or head, deterministic, the overflow retry) with the pure classes it calls (ChunkPlan,ReduceRound,IncompleteAnswerAction,SummaryParts,MapReduceMath,TokenWindow,OverflowBackoff,InputWindowCalculator,RouteEstimator,SourceChunker,DeterministicSummary,GenerationTimeEstimator,SummaryResult) and knows nothing of the walkers (generationDoesNotKnowTheWalkers). Logs viaorg.slf4j.Logger(a private static final field per class), not a MavenLog— this is what makes the module Maven-free; Maven's ownmaven-slf4j-provider(ships since Maven ≥ 3.1) makes these lines surface as ordinary[INFO]/[WARN]output inside a plugin execution with zero glue, and the CLI ships an SLF4J binding for the same log lines outside Maven.document/— the.ai.mdmodel + codecs (AiMdDocument,AiMdHeader,AiMdDocumentCodec,AiMdHeaderCodec,AiMdRewritePolicy,AiMdChildEntryLineFormatter,AiMdLeadExtractor).prompt/—PromptTemplateLoader(reads everytemplateFileof aconfig.PromptDefinition, relative to the configuration'sprofileDirectory, and every prompt key a rule uses without a definition from<profileDirectory>/<key>.md, before the prompts are registered),PreparedPrompt,PromptCatalog,PromptPreparer,GenerationRequest(the prompt key, the file and its text: what a provider answers). The fact counters are read the same way (facts.FactDefinitionLoader);support.ProfileFileSupportis the shared file convention. The measured profile (prompts + fact counters) lives once in the repo-rootprofiles/v3/(profiles/README.md); the plugin's self-test profile, the model-card benchmark, the examples and the plugin-it fixture all name only keys and read it from there, so do not paste a prompt text or a regex into a configuration again. The*FactPatternsTestclasses (Sql,JavaStructure,Shell,Perl,Xml,EnterpriseXml,Jvm,View,Contract,Ops) read the shipped.tsvfiles, never copies, and count throughFactExtractor.counts, so the[ignore]lines (regions blanked before counting: POD, heredocs, comments) and the[raw]and[distinct]counters apply as in production.ProfileFactPatternsLinearityTestruns every pattern of every.tsvof the profile over repeated adversarial lines, and over the same lines without their line break repeated into one long line (a pattern that rescans to its line end from every opener is quadratic only there), and counts the characters the matcher reads: four times the input may read at most six times as many, so a quadratic pattern fails it on any machine, none may reach the time limitsupport.ReadBudgetgives a pattern (READS_PER_CHARper character plusREAD_ALLOWANCE), and none may overflow the stack (a group repeated without a possessive or bounded quantifier recurses once per repetition injava.util.regex). A new facts file is measured without a change to it. The measure isFactPatternLinearity, written in Java 8 without JUnit, so thelinearity-jdk8job ofpublish.ymlruns it on Java 8 as well (it compiles the one class with--release 8): keep that class free of anything newer than Java 8.provider/— the AI backend abstraction:GenerationProvider(AutoCloseable),GenerationProviderFactory(looks up"mock"/"llamacpp-jni"/"openai-compatible"; a model definition's ownprovideroverrides the run'sgenerationProvider),MockGenerationProvider,LlamaCppJniGenerationProvider,OpenAiCompatibleGenerationProvider(HTTP to<baseUrl>/chat/completions, andlistModels()from<baseUrl>/modelsintoRemoteModels, key from the env varapiKeyEnvnames; its pure logic lives in the PIT-gatedOpenAiCompatibleProviderSupport; withrequestsPerMinuteevery request first passes theRequestRateLimiterwindow shared by all providers of one server, at the limit of the request's own model, which waits on aConditioninstead ofThread.sleep),ProviderConfig(one model's configuration for whichever provider runs it, built throughProviderConfig.builder().modelPath(modelPath); the positional constructor is private, and every value the caller does not name defaults to the matchingModelDefinition.DEFAULT_*) +ProviderConfigFactory(the pure 44-field mapping from a resolvedModelDefinitionto the native binding's parameter objects — extracted from the old mojo so it is unit- and PIT-testable without a Maven runtime),CompletionParser.support/— foundation helpers with no dependency on anything above them:ChecksumSupport,TimeSupport,SourcePaths,SourceExcludeFilter,ReadBudget(the time limit of a fact counter's and acontentMatchespattern, in characters read),UrlUserInfo(masks a URL'suser:password@, query and fragment in a log line, a message or the CLI's configuration echo),SourceLines(a source is read once with\nline endings: checksum, plan, prompt and chunks see the same text),DirectoryLinks(a symbolic link or a Windows junction to a directory, which no walk enters below its root; a root that is a link is walked as its target, every path named by the link),Shebang(the interpreter a#!line names:fileInterpretersand theinterpreterscondition),GeneratorVersion(srcmorph's own version, the header'sG),Java8CompatibilityHelper,ConvertToRecord,ReplaceWithLibrary(marks a copy of a library class whose release is not out yet;ReplaceWithLibraryTestfails once the library class is on the classpath, seeTODO.md).
Architecture rules (CoreArchitectureTest, ArchUnit): coreIsMavenFree (the load-bearing rule
above), layeredArchitecture (engine on top → indexer (with indexer.generation) →
provider/document/routing → prompt → facts → config → support, each layer with the exact
set of layers that use it), generationDoesNotKnowTheWalkers, noPackageCycles, loggersArePrivateStaticFinal, noSystemExit,
noTestFrameworksInProduction, noJavaUtilLogging, noSystemOutOrErrInProduction,
noInternalJdkImports, noPublicMutableFields, noNewRandom, noThreadSleep,
jniConfinedToProvider (only the provider package may touch the llama.cpp JNI binding),
exportedApiNamesNoInternalType (no public signature of config or engine, the packages
module-info.java exports, names a type of another package of the library: a module-path consumer
could not use it).
Test suite (srcmorph/src/test/java/net/ladenthin/srcmorph/, package-renamed 1:1 with production):
~110 test classes, incl. jqwik properties, an ArchUnit suite, a Lincheck race test
(AtomicCounterLincheckTest), and the model-backed real tests gated on
src/test/resources/SmolLM2-135M-Instruct-Q3_K_M.gguf. LlamaCppJniKnobSweepTest drives every
model knob at a non-default value through a real generation (one case per knob, ~35 s for all of
them): a knob is exercised only when the native binding accepts the value derived from it, which is
what the mapping unit tests and the mock-provider suite structurally cannot see -- both provider
defects fixed in 1.2.0 were of exactly that shape. Its reflective completeness check fails when a knob
is neither swept nor listed in NOT_SWEPT with a reason, so a knob added later reds the class until
somebody decides how it is covered. PIT mutation testing: mutationThreshold
100 over an explicit targetClasses list in srcmorph/pom.xml — currently 92 entries (nested classes counted) across
every package, all killed at 100%. All three modules are
PIT-gated now: srcmorph-cli (29/29) and srcmorph-maven-plugin (79/79) carry their own
pitest-maven executions at the same threshold, and CI runs the goal reactor-wide. The natives come from net.ladenthin:llama-platform (a pom
naming the CPU natives jar of every desktop platform — since llama 6.0.0 net.ladenthin:llama is the
classes only); the gpu-cuda/gpu-vulkan profiles and -Dllama.classifier=<natives jar> (profile
gpu-natives) add a GPU module jar next to them (since llama 6.0.0 one ggml backend module, which
ggml loads when its vendor runtime is installed; otherwise the CPU modules run). They live here; the jcstress and
vmlens profiles/tests currently still live in the plugin module (they were not moved in the
extraction — see that module's section below), not here.
net.ladenthin:srcmorph-cli, packaging jar, package root net.ladenthin.srcmorph.cli. A BAF-style
CLI driven by a single JSON or YAML configuration file:
cli/Main.java— reads the file with the core'sSrcMorphConfigurationFileLoader(the file's directory is the default base directory,${name}comes from the system properties, an unknown command fails naming the commands);--help/-hprints the usage, a wrong argument count fails with it; echoes the parsed configuration back (re-serialized as both JSON and YAML) for review before anything runs; noSystem.exitanywhere — a failure propagates as an unchecked exception out ofmain(String[]). Dispatches onCConfiguration'scommandfield to one or morenet.ladenthin.srcmorph.engine.*engines.cli/configuration/CConfiguration/CCommand— public-mutable-field JavaBeans (the BAFcli.configuration.CConfigurationconvention; carved out of thenoPublicMutableFieldsArchUnit rule via this package's explicit exception), filled from aSrcMorphConfigurationFilebyMain.fromFile.CCommandisPlan | Check | GenerateFileIndex | AggregatePackages | AggregateProject | All | Calibrate | ListModels, each with the one-linesummary()the usage prints;ListModelsreads the top-levelmodelFiltertoo, and the package and project phases take only the top-levelpackageRules/projectRules(a copy ofsrcMorphwith those rules, the sections the plugin's aggregate goals read from the same file): the package phase exactly one rule, the project phase none or one (EngineSupport.requiredPhaseRule/optionalPhaseRule).Checkrunscheck()of the three engines (the package phase only when configured): the plan, the profile files and every model, without loading one.examples/build-your-own-jar/srcmorph.yamlis the plugin'ssrcmorph-selftest.yamlfor the CLI (gpt-oss-20b + the two Granite presets only, like the profile);BuildYourOwnJarSelfTestParityTestreads both and fails when they drift. The default isPlan(safe: no model load, nothing written).- No runnable jar is built or published here (since 1.4.0).
mvn packageproduces only the thinsrcmorph-clijar (its manifest namesnet.ladenthin.srcmorph.cli.Main, sojbangcan run it). Users build the runnable jar withexamples/build-your-own-jar/pom.xml:srcmorph-clifrom Central,llama-platformexcluded, the one natives jar of the OS/arch picked by an OS-activated profile (-Dnatives=overrides), an optional GPU module via-Dgpu=<classifier>, packed byjar-with-dependenciesintotarget/srcmorph.jar. Up to 1.3.0 this module built a fat jar on everypackageand CI released 15 of them on GitHub; there are too many OS/CPU/GPU combinations to keep doing that. - Declares its own SLF4J binding (
org.slf4j:slf4j-simple, runtime scope) — unlike the library (consumer picks any SLF4J binding) and the plugin (gets one for free from Maven's ownmaven-slf4j-provider), a standalonejava -jarprocess needs to bring its own or every log line is silently dropped. It is not logback: see "Java 8 bytecode floor" below. The logging defaults (INFO, stdout, timestamps) areexamples/build-your-own-jar/simplelogger.properties, which that pom packs into the user's jar; the publishedsrcmorph-clijar carries none, so an embedder's own configuration is never overridden. - Architecture rules (
CliArchitectureTest):cliIsLeaf(nothing else in the reactor may depend on this module — it is the leaf-most consumer),noPublicMutableFields(with theconfigurationpackage carve-out),noSystemExit,mavenFree(must never depend on the Maven Plugin API — that boundary belongs to the plugin module),noTestFrameworksInProduction,noInternalJdkImports,loggersArePrivateStaticFinal. - Tests:
MainTest,ConfigBindingTest(round-trips a privatesrc/test/resources/test-fixtures/minimal-generate.{json,yaml}pair through both parsers),ExamplesConfigBindingTest(sweeps every shippedexamples/config_*.{json,yaml}fixture — the public, documented examples — through the same strict mappers),CliEndToEndTest(drives every command against the mock provider end to end, no forked process,ListModelsagainst a loopback stub, binding the printed template back into a configuration).
Renamed in the final migration step: coordinates net.ladenthin:srcmorph-maven-plugin (was
net.ladenthin:llamacpp-ai-index-maven-plugin), package net.ladenthin.maven.srcmorph.mojo (was
net.ladenthin.maven.llamacpp.aiindex.mojo), goal prefix srcmorph (was ai-index), every
@Parameter property now spelled srcmorph.* (e.g. srcmorph.skip, srcmorph.file.skip,
srcmorph.planOnly, srcmorph.configurationFile — was aiIndex.*).
The old coordinates were kept alive on Maven Central via a one-time relocation-stub publish (see
"Project Overview" above and its own paragraph below) — never describe the plugin using the old
coordinates/package/properties in new documentation or code. The plugin's contents stay thin: it
depends on net.ladenthin:srcmorph (compile scope) for everything except the mojo classes
themselves (five goals, RuleSection).
- The plugin is configured by the CLI's file (since 1.4.0),
<configurationFile>(srcmorph.configurationFile, default${project.basedir}/srcmorph.yaml); it has no XML parameters for models, rules, prompts or paths.AbstractSrcMorphMojo.buildConfiguration(RuleSection)reads the file with the core's loader and fills what it leaves unset from Maven:baseDirectory(${project.basedir}),subtrees(the source directory and the resource directories that exist below the base; a resource directory that holds the source directory is left out) andprojectName(generatorVersion, the header'sG, is srcmorph's own version in the CLI and the plugin alike:support.GeneratorVersion, filled in by the core's resource filtering);${name}in the file is a Maven property (user over project properties over the project's own values such asproject.basedirover system), which is how the self-test's-Dai.*reachsrcmorph-selftest.yaml.RuleSectionpicks the goal's rules:FILES(generate,calibrate),PACKAGE(aggregate-packages),PROJECT(aggregate-project);CheckMojo(srcmorph:check) checks all three. The remaining parameters are run switches the file cannot see:srcmorph.forceandsrcmorph.planOnly(trueoverrides the file), and the skip flags. The descriptor states Maven 3.6.3 and Java 1.8 (requiredMavenVersion/requiredJavaVersionof maven-plugin-plugin; plugin-it asserts both). The class wasAbstractAiIndexMojoup to 1.4.0. - Skip flags stay mojo-side (
skip,skipFile,skipPackage,skipProject) — a Maven lifecycle concern, not part ofSrcMorphConfiguration; an engine built from a configuration always executes when asked. SeeMojoPhaseSkipTest. - Two property namespaces — do NOT confuse them (this has tripped audits). The published mojo
@Parameters are thesrcmorph.*set (srcmorph.configurationFile,srcmorph.skip,srcmorph.force,srcmorph.planOnly, the three phase skips). Theai.*names in the pluginpom.xml+ README (ai.model,ai.gpuLayers,ai.mainGpu,ai.devices,ai.modelDir,ai.profileDir,ai.index.output.directory) are repo-local Maven build properties thatsrcmorph-selftest.yamlnames as${ai.*}, overridable with-Dai.*— they are not mojo parameters, and downstream consumers set the same knobs in their own configuration file. So-Dai.gpuLayers=12etc. are correct as documented; do not "fix" them tosrcmorph.*. - Architecture rules (
PluginArchitectureTest): Maven-annotation confinement tomojo, every mojo extendsAbstractMojo, plus this module's slice of the shared conventions. - jcstress (
jcstress/OversizeStrategyRace.java) and vmlens (vmlens/VmlensInterleavingSmokeTest.java) tests/profiles currently live in this module, not insrcmorph— they were not relocated during the core extraction. - The plugin is exercised AS A PLUGIN only by the
plugin-itCI job (.github/plugin-it.sh+ the fixture in.github/plugin-it/), never by this module's unit tests. That distinction matters when adding a@Parameter:MojoGoalTestand friends set the field, so they cannot see thepropertystring, what Maven injects (${project.*},${session.userProperties}), the goal prefix or the generated descriptor — a renamed property used to ship green. The IT installs the reactor (-pl srcmorph-maven-plugin -am, which excludessrcmorph-cli), then runs the fixture through a real Maven lifecycle with themockprovider: no GGUF, no GPU, no network. Its fixture (pom.xmlwith the goals only,srcmorph.yaml) has the shape of the worked example in this module'sREADME.md; no test reads the README itself, so keep the two in step by hand. Its last step plans the module's ownsrcmorph-selftestprofile. It gatespublish-snapshotandpublish-release. A trap when extending it, found by falsifying assertions rather than by reading: the fixture must not get asettings.xmlwith a<pluginGroups>entry —mvn srcmorph:generateresolves without one (Maven matches the prefix against the descriptor of the plugin the fixture declares), while adding one opens a second path through repository metadata that maps the prefix by artifactId and thereby masks a changed<goalPrefix>completely, on a pristine runner as well. The general lesson for a fixture-based test: an element the fixture sets to a value that equals the production default, or a pattern that matches no file that exists, is not covered by the run — it is invisible to it. The subtrees (now filled by Maven,src/extra/javareached only as a resource directory) and the excludes started out that way here. - Full goal/parameter reference:
srcmorph-maven-plugin/README.md.
Not a module in this reactor anymore. It existed briefly as a minimal 4th reactor module — not
a renamed copy of the plugin above, and not a child of srcmorph-parent (no <parent> at all).
Its entire pom.xml was groupId + artifactId (llamacpp-ai-index-maven-plugin) + a version
pinned independently at 1.0.4 + <distributionManagement><relocation> pointing at
net.ladenthin:srcmorph-maven-plugin:1.1.1. No source, no tests, no dependencies. Its sole purpose
was so a consumer still declaring the old Maven coordinates gets redirected by Maven to the renamed
plugin — published once, verified working end-to-end from a clean environment, then removed from
active development: the published 1.0.4 artifact is permanent on Maven Central regardless of
this repo's module list, and it will never need another release. Anyone still depending on the old
coordinates continues to be redirected correctly; nothing here needs to change again for that to
keep working.
mvn compile # Compiles every module (Java + generates nothing native; pure Java reactor)
mvn test # Runs every module's tests
mvn package # Builds all four reactor projects: parent pom + 3 jars
mvn install # Installs all four into ~/.m2 (needed before iterating on a single module — see below)Maven resolves inter-module dependencies (srcmorph-maven-plugin and srcmorph-cli both
depend on net.ladenthin:srcmorph) via the local repository, not in-reactor classes, unless you use
-pl/-am:
# Build/install the core first if you're iterating on the CLI or the plugin against local core changes:
mvn -pl srcmorph -am install -DskipTests
# Then work on just one module:
mvn -pl srcmorph-cli test
mvn -pl srcmorph-maven-plugin testmvn test -o # requires a warm ~/.m2/repository cache
mvn package -o -DskipTestsmvn -pl srcmorph-maven-plugin srcmorph:generate -P srcmorph-selftestmvn install -DskipTests
mvn -f examples/build-your-own-jar/pom.xml package -Dsrcmorph.version=1.5.0-SNAPSHOT
java -jar examples/build-your-own-jar/target/srcmorph.jar examples/config_All.jsonSee examples/ (repo root) for ready-to-run config_*.json/.yaml + paired run_*.sh/.bat
launcher scripts, all using the mock provider (no GGUF model required).
Every module uses JUnit Jupiter + Hamcrest; MockGenerationProvider gives fully deterministic tests
with no model or JNI dependency. Model-backed tests (in srcmorph) are gated on
srcmorph/src/test/resources/SmolLM2-135M-Instruct-Q3_K_M.gguf and self-skip when the native library
is unavailable.
srcmorph— the bulk of the test suite (framework-free logic); see that module's section above.srcmorph-cli—MainTest,ConfigBindingTest,ExamplesConfigBindingTest,CliArchitectureTest,CliEndToEndTest,BuildYourOwnJarSelfTestParityTest.srcmorph-maven-plugin—PluginArchitectureTest,AbstractSrcMorphMojoTest(the configuration file and what Maven fills),MojoGoalTest(every goal against a mock configuration),MojoPhaseSkipTest, plus the jcstress/vmlens tests noted above.
See TEST_WRITING_GUIDE.md (repo root, applies to every module) for full conventions.
srcmorph and srcmorph-cli log via org.slf4j.Logger (private static final Logger LOGGER = ...,
enforced by each module's own loggersArePrivateStaticFinal ArchUnit rule). The plugin module's mojos
still use AbstractMojo#getLog() (a Maven Log) at the mojo boundary only — everything they delegate
to below that boundary is SLF4J.
- JSpecify
@Nullable/@NonNull(default) annotations; NullAway + Checker Framework enforce this at compile time in every module. Mark nullable return types and parameters explicitly. - Prefer early null/empty guards with a logged warning over silent skips.
Every meaningful literal (string keys, header field names, node types, version strings) must be a
public static final or private static final named constant with Javadoc.
All source files must include the Apache 2.0 license header wrapped in // @formatter:off /
// @formatter:on (or the file type's equivalent comment syntax — see examples/ for the #/REM/
XML-comment conventions used there; JSON/YAML example fixtures carry no inline header, see
REUSE.toml).
Immutable value types are Java records where practical (e.g. AiMdDocument, AiMdHeader,
PreparedPrompt, GenerationRequest, GenerateResult).
Every module's maven-surefire-plugin configuration forces <useModulePath>false</useModulePath>.
Each module ships a module-info.java, but it is release metadata for module-path consumers only —
this reactor's own build, tests, and every real consumer today load these jars on the plain classpath
(the production bytecode targets Java 8, where module-info.class is inert). Leaving Surefire's
module-path auto-detection on would patch test classes into the named module and then also require
every test-only dependency (e.g. archunit-junit5) to be explicitly module-readable, which
module-info.java intentionally does not declare — so classpath mode is not a workaround, it is the
actually-representative test environment.
| Workflow | Trigger | Purpose |
|---|---|---|
publish.yml |
Push, PR, manual dispatch | Unified build/test/coverage/package pipeline; publishes snapshots and Maven Central releases |
codeql.yml |
Schedule/Push | GitHub CodeQL security scanning |
scorecard.yml |
Schedule / Push | OpenSSF Scorecard supply-chain security analysis |
osv-scanner.yml |
Schedule / Push / PR | Google OSV-Scanner dependency vulnerability scan |
reuse.yml |
Push / PR | FSFE REUSE license-compliance check (fsfe/reuse-action) |
claude-code-review.yml |
PR | AI-powered code review |
claude.yml |
Issue/PR comment with @claude |
Claude Code interactive assistant |
publish.yml is adapted to the 3-module reactor; only the core's jacoco report is uploaded (the
CLI's and the plugin's are not aggregated).
| Dependency | Version | Used by |
|---|---|---|
net.ladenthin:llama + llama-platform (pom) |
6.0.0 | srcmorph (provider package only) — llama.cpp JNI binding (classes) + the CPU natives jars; its own SLF4J binding is excluded transitively (see "Java 8 bytecode floor") |
org.slf4j:slf4j-api |
2.0.20 (converged in the parent) | srcmorph, srcmorph-cli, the plugin |
org.slf4j:slf4j-simple |
2.0.20 (converged in the parent) | srcmorph-cli (runtime binding) |
ch.qos.logback:logback-classic |
1.6.7 (converged in the parent) | srcmorph (test scope only — ListAppender capture) |
com.fasterxml.jackson.core:jackson-databind |
pinned in parent | srcmorph (SrcMorphConfigurationFileLoader, JSON), srcmorph-cli |
com.fasterxml.jackson.dataformat:jackson-dataformat-yaml |
pinned in parent | srcmorph (SrcMorphConfigurationFileLoader, YAML), srcmorph-cli |
org.apache.maven:maven-plugin-api |
3.10.0 | srcmorph-maven-plugin (provided); the descriptor states Maven 3.6.3 regardless |
org.apache.maven.plugin-tools:maven-plugin-annotations |
3.16.0 | srcmorph-maven-plugin (provided) |
Test-only (every module): org.junit.jupiter:junit-jupiter, org.hamcrest:hamcrest,
com.tngtech.archunit:archunit-junit5. srcmorph additionally uses jqwik (pinned ≤ 1.9.3 — see the
jqwik policy link below), JMH, jcstress, Lincheck, vmlens.
After modifying or creating any .java file, in whichever module it lives:
- For
*Test.javafiles, follow the workspace version chain:../workspace/guides/test/TEST_WRITING_GUIDE-8.md(baseline) and this repo's ownTEST_WRITING_GUIDE.md(repo-wide supplement; applies to every module — there is one guide file at the repo root, not one per module). - For production sources, follow the workspace version chain:
../workspace/guides/src/CODE_WRITING_GUIDE-8.md(baseline) and this repo's ownCODE_WRITING_GUIDE.md. - Apply all fixable violations automatically; report only those that cannot be resolved without a large refactor.
See ../workspace/workflows/pull-request-workflow.md.
- Local-first — by default all AI inference runs locally via llama.cpp; no cloud API calls, no
data leaves the machine. A remote model is an explicit per-model opt-in (
provideropenai-compatible), and its API key is only ever read from an environment variable. - Deterministic indexing — the same source produces the same
.ai.mdskeleton (deterministic header); only the AI-generated body varies. - Incremental updates — files with existing summaries are skipped unless
force=true; checksums detect source changes. - One configuration file — the CLI and the Maven plugin read the same JSON or YAML file
(
SrcMorphConfigurationFileLoader) into the sameSrcMorphConfiguration; the plugin only fills what Maven knows about the project. - Provider abstraction — AI backends are pluggable through
GenerationProvider; the mock provider enables fully deterministic tests everywhere. - Configuration-driven prompts & rule-based routing — prompt templates and the
rulesrouting rules (composableconditiontree, priority, skip, exactly one fallback) are data, never hardcoded in Java; seeSrcMorphConfiguration's Javadoc and each engine's own Javadoc for thegenerate/aggregate-packages/aggregate-project/calibratesemantics. - Staged, always-green migration — the plugin's public coordinates never changed out from under an
existing consumer mid-migration; the rename to
srcmorph-maven-pluginwas a deliberately isolated step, with a relocation stub for the old coordinates.
Production code in all three modules targets Java 8 (release 8), so every class a
consumer's JVM can load must be class-file major 52 or lower. Two entries exist only for that,
and both are easy to undo by accident:
slf4j-simple, not logback, issrcmorph-cli's shipped SLF4J binding. Every logback release from 1.4.0 on is Java 11 bytecode, soLogbackServiceProvidercannot load on Java 8 — SLF4J'sServiceLoaderfinds it at startup and the JVM throwsUnsupportedClassVersionErrorbefore a single log line is written. The Java 8 line (1.3.x) is end-of-life and every logback CVE disclosed since has been fixed only in 1.5.x/1.6.x with no backport, so it is not an option either.slf4j-simpleis six classes from the same release train asslf4j-api, with no configuration or socket layer for a CVE to live in. logback stays, but test scope only, forSummaryGeneratorTest'sListAppender.checker-qualisprovidedscope, not a pinned old version. It is major 55 from 4.0.0 on and its annotations are@Retention(RUNTIME), so anything reflecting over an annotated element (Jackson does — the CLI binds its whole configuration with it) loads them. Pinning the shipped copy to the last Java 8 line (3.55.1) does not work: the Nullness Checker resolves its own qualifiers through javac's symbol table, i.e. the compile classpath, so a 3.x checker-qual under the 4.x processor fails every build withCould not load type: org.checkerframework.framework.qual.DoesNotUnrefineReceiver. Processor and qualifiers must share a major version.providedsatisfies both: 4.3.1 where the checker needs it, and excluded from consumers' graph and from anyjar-with-dependenciesbuilt from it (that descriptor takes scoperuntime).<optional>true</optional>alone would not have been enough — that descriptor filters on scope only. Safe because no source in this reactor importsorg.checkerframework.
The gate: the java/verify-bytecode action of bernardladenthin/actions (its verify-bytecode-version.sh).
It opens every .class in every jar it is given and fails on any whose class-file major version
exceeds max-major:
- uses: bernardladenthin/actions/java/verify-bytecode@<commit> # v1.x.y
with:
max-major: "52"
paths: | # jars or directories, one per line
smoke-jars
allow: | # optional: '<jar-basename>:<entry-path>' globs to toleratePaths may be jars or directories (searched recursively for *.jar), so one invocation covers a
whole artifact set. module-info.class and META-INF/versions/** are skipped unconditionally —
a classpath JVM never loads either, which is why a release 9 module-info is fine. allow
takes globs matched against <jar-basename>:<entry-path> for anything else that must be
tolerated. Exit codes: 0 clean, 1 violations, 2 nothing to scan (an empty input is a failure,
never a pass). Wired into the smoke-jar job at max-major 52, over the user-built srcmorph.jar
(the CLI with its whole runtime classpath) and the plugin jar.
See ../workspace/policies/javadoc-conventions.md.
See ../workspace/policies/spotbugs-suppressions.md.
Each module has its own spotbugs-exclude.xml (srcmorph/spotbugs-exclude.xml,
srcmorph-cli/spotbugs-exclude.xml, srcmorph-maven-plugin/spotbugs-exclude.xml).
See ../workspace/policies/spotless-formatting.md.
Run mvn spotless:apply before every commit that touches .java files (reactor-wide from the root, or
scoped to one module with -pl).
See ../workspace/policies/jqwik-prompt-injection.md.
jqwik is a test dependency of srcmorph only.
See ../workspace/policies/lombok-config.md.
lombok.config lives once at the repo root and is inherited by every module (Lombok walks up the
directory tree from each source file looking for lombok.config).
See ../workspace/policies/ci-test-diagnostics.md.
See ../workspace/policies/pit-mutation-testing.md.
Run PIT with the lifecycle prefix. Reactor-wide (what CI does):
mvn test-compile org.pitest:pitest-maven:mutationCoverage; or scoped to one module with
-f srcmorph/pom.xml. All three modules gate at mutationThreshold 100 — srcmorph (1959 mutations on 2026-11-05),
srcmorph-maven-plugin (79, the mojo classes) and srcmorph-cli (29). The CLI's
Main.main(String[]) is the one documented exclusion: it is the process entry point, and the
smoke-jar release-gating job already runs the real java -jar artifact and asserts
Main#run end. in its output, which is an end-to-end check a unit mutant cannot reach.
LlamaCppJniGenerationProvider is split so the gate can reach it, and the split is load-bearing.
Everything the provider does that does not touch the native handle lives in
provider.LlamaCppJniProviderSupport, which is on the gate; the provider itself is not. That is not
tidiness. PIT re-runs every test covering a mutated line, and while the pure logic sat next to
model() the only way to gate any of it was to gate model() too -- a ~100-line ModelParameters
chain whose sole exerciser is LlamaCppJniKnobSweepTest, 36 cases that each load a GGUF (22.9 s).
Excluding those tests instead does not work: model()'s mutants would then have no coverage, and a
NO_COVERAGE mutant fails a threshold-100 gate exactly like a survivor. Keep the boundary at
"touches the native handle" -- moving a pure method back into the provider silently drops it off
the gate, and moving an impure one into the support class reds it.
The extension paid for itself immediately: the class contributed 23 mutations and five survived,
all real gaps (the two known*Values separator boundaries, both seed guards, and the
drySequenceBreakers branch). None could have been seen before, because a class that generates no
mutants cannot move the number -- which is exactly why the gate read a stable 775/775 straight
through the 1.1.0-era dry_penalty_last_n regression and through its fix.
Cost, measured on one machine rather than estimated: 11:34 min at 807 mutations before, 12:14 min
at 830 after -- about 40 s for 23 mutations. excludedTestClasses was considered and is not
used: it would remove a test class from mutant matching for every target class, not just this one,
and the measurement says it is not needed. (The intermediate 15:57 min reading was inflated by the
five survivors: PIT exhausts every covering test for a mutant that never dies, while a killed one
stops at the first failure.)
Two classes are permanently off the gate, and this is worth not re-litigating. Both have
survivors that are equivalent mutants, unkillable through the public API rather than merely
untested. document.AiMdHeaderCodec: the colon guard in read is reached only after
startsWith(HEADER_FIELD_PREFIX), so colonIndex is either -1 or >= 2 — the < 0 boundary
mutant differs only at the unreachable 0, and the +1 -> -1 mutant only at an empty field key,
which values.put("", value) swallows because no header field is keyed "". indexer.generation.SourceChunker
(28/34): its three observable boundaries are pinned (maxChars == 1, the end < length guard,
the lastNewline > pos guard), but six mutants have no observable effect at all — the ArrayList
capacity hint, return chunks vs emptyList() on empty input, two clamps the surrounding
Math.max absorbs, the loop head the end >= length break already guarantees, and select's
total <= maxChunks, where the equality branch computes the identity mapping. Reaching 100% on
either would mean exposing internals or deleting a deliberately defensive guard. The orchestration
classes (the walking indexers SourceFileIndexer / PackageIndexer / ProjectIndexer,
SummaryGenerator, the four multi-step engines) and the JNI provider stay out for a
different reason: they own provider lifecycles or a native context rather than pure logic. The pure
parts of indexer (IndexPlan, RouteEstimator, MapReduceMath, ...) and the plugin's
mojos are on their gates.
The core's module-info.java exports config and engine only (and support to the CLI alone);
the other packages are the implementation, and exportedApiNamesNoInternalType keeps their types out
of the exported signatures, so a result an engine returns is read through its own methods (the
reports' renderings), not through an indexer or provider type.
Each module ships a module-info.java compiled in a separate release 9 execution, and each module's
Javadoc runs in classpath mode (<source> resolves to 8), which is the only thing keeping it
clear of the JPMS module-mode javadoc trap that bit BAF. Before raising the Java / javadoc source
level to ≥ 9 in any module, read
../workspace/policies/jpms-module-descriptor.md.
srcmorph releases only the Maven artifacts: the four POMs and the three modules' jar, sources
and javadoc, each with a detached GPG .asc, on Central and as GitHub release assets.
.github/release-assets.json is {"schema": 1}: no extra file rules. Up to 1.3.0 the publish jobs
also built, signed and attached one srcmorph-cli fat jar per desktop GPU module of
net.ladenthin:llama (15 per release, never on Central); 1.4.0 dropped them together with
sign-fatjars.sh, verify-classifier-fatjars.sh and the license collector that only they needed.
Every publication goes through the one gate of bernardladenthin/actions (full text: docs/publication.md).
check-snapshot / check-tag run java/check-release-ref: a release publishes only from the tag
v<version> of a non-SNAPSHOT version, a snapshot only a -SNAPSHOT version and never from a tag.
The publish jobs stage and sign the Central files locally (-DskipUpload=true deploy) and end in
java/finalize-publication, which collects what .github/release-assets.json names (Maven modules
are discovered from the POMs), checks it -- exact membership, every signature with gpg --verify,
each Central file byte-equal to its GitHub twin -- and freezes it into one package. Only after that
package is uploaded does the job output assets_complete=true; a missing file or signature fails
there, and nothing is published. Three pairs of consumers each need only that output, never each
other: github-snapshot / github-release (java/publish-github: the rolling snapshot
pre-release is serialized, never lets an older commit or run replace a newer one, prunes only after a
complete upload and starts as a draft; a versioned tag is refused), central-snapshot /
central-release (java/publish-central, no rebuild, no re-signing) and attest-snapshot /
attest-release (java/attest-publication). The jobs themselves stay in this workflow
(environment, permissions, concurrency); java/check-publication checks their wiring in every pull
request.
The publish jobs collect the deploy-signed Maven outputs with --maven-only into
central-assets/, and finalize-publication reads them from there (--maven-assets).
srcmorph-specific smoke. The smoke-jar job (needs: startgate, gates both publish jobs) takes
the path a user takes: mvn install of the reactor, then examples/build-your-own-jar with
srcmorph.version and llama.version read from the reactor, so the example pom itself is under test
on every pull request. It then runs the java/smoke-fatjar-cli action of bernardladenthin/actions
(BAF runs it too) from examples/ against config_Plan.json, asserting exit 0 plus Main#run end. in the output.
A last step runs the same plan on the module path (java -p ... -m net.ladenthin.srcmorph.cli/...,
the CLI's runtime dependencies without the pom entry and llama's natives jars): the only place the
module-info.java files run, as every test runs on the classpath.
Plan with the mock provider needs no GGUF, no GPU and no network, which makes this the cheapest
possible real launch of the CLI. Do not "strengthen" it to config_All.json over a real source
tree: the example configs are tuned for a small demo tree, so All against this repo's own
sources fails by design (19 files exceed the demo model's context window with onOversize=fail) —
that would make the smoke non-deterministic, not more thorough. The shipped Plan example plans
the one file of the demo tree examples/src/main/java; the step that counts it runs from the
repository root (examples/config_Plan.json), so a relative path resolved against the working
directory instead of the file's directory fails it. The tree has to stay,
because a configured subtree that does not exist fails the run, and its file has to stay below the
examples' mock window, or onOversize=fail fails the smoke. That window is what the mock model's
contextSize (4096) leaves next to the profile's fallback prompt, so a longer prompt shrinks it: at
2048 a prompt change of 2026-11-02 left no room at all.
dependencyConvergence is enabled (maven-enforcer) in each of the 3 reactor modules;
jspecify/checker-qual are pinned in the reactor parent's dependencyManagement (next to the
existing slf4j-api/logback-classic/jackson pins) because net.ladenthin:llama brings both
transitively. Convention + the excludedScopes gotcha + merge-discipline guidance (this repo's
main was actually broken by exactly this pattern once — Dependabot PR #169) are in
../workspace/policies/dependency-convergence-pinning.md.
The CI code the four Java repositories (java-llama.cpp, BitcoinAddressFinder, srcmorph,
streambuffer) share lives once in bernardladenthin/actions: composite actions for single steps (uses: bernardladenthin/actions/<common|java>/<action>@<commit> # v1.x.y), reusable workflows for whole
jobs (CodeQL, Maven dependency submission, REUSE, OSV-Scanner, SonarQube -- the workflow files here
only name the triggers), and templates for the files this repository has to carry itself.
Dependabot moves the pins with every release of that repository. Until 2026-10 the same code was
four byte-identical copies held together by a .github/shared-files.sha256 manifest per repository.
The repository-checks job of publish.yml (gating both publish jobs) runs its checks, configured
in .github/actions-config.json:
- templates: every file this repository keeps equal to a template there (community files,
licenses,
.editorconfig,.gitattributes,.java-version,.mvn/, Dependabot, the workflow callers,scorecard.yml, the Claude workflows) still equals it, up to the repository's name and the action pins. To change one, change the template in bernardladenthin/actions;python3 -m actionlib.common.templates --write(with itslib/onPYTHONPATH) writes it here; - release gate: every job gates both publish jobs unless
.github/release-gate-exemptions.txtnames it with a reason; - run scripts:
bash -nover every bashrun:script of the workflows and local actions, so a broken script (a lost line continuation, say) fails here instead of in the job running it; - artifact timeouts: every
upload-artifact/download-artifactstep times out after the repository variableARTIFACT_TIMEOUT_MINUTES, else 20 minutes (the workflow's top-levelenvreads it;../workspace/policies/ci-artifact-timeouts.md), instead of GitHub's 360; - Dependabot: every entry of
.github/dependabot.yml(the template's) runs weekly on Saturday and has a group -- minor and patch updates as one pull request per ecosystem, a major update as one of its own; - Maven versions (warnings only): a dependency or plugin (incl. the Spotless formatter version)
used here in another version than in a sibling of the
java-mavenfamily (each sibling's POMs come from its own configuration), and Kotlin Gradle plugins behind the POMs' Kotlin; - publication: the publication jobs are wired as the actions expect, and a dry run of
.github/release-assets.jsonagainst the real POMs collects exactly what it promises.
Dependabot pull requests do not run publish.yml: its startgate job, which every other
job needs, is skipped for a pull request Dependabot opens or rebases (github.actor). The merge
to main runs the pipeline; a push of a person to the branch, or a dispatch on it, runs it too.
The JDK every workflow uses is .java-version (setup-java's java-version-file), a template of
the java set. Why a repository instead of copies:
../workspace/crossrepostatus.md.
Open TODOs for this repo live in TODO.md. Cross-repo status
tracking lives in ../workspace/crossrepostatus.md.