Timefold · Separating timefold-solver-core into nine modules using CodeLaser

In short

1. Nine modules, four changes to the published API, and no change to the tests

• The goal. timefold-solver-core — the core throughout this document — is one artifact. Anything that uses any part of it compiles against all of it. The goal was to separate it into modules that build in a fixed order, so a consumer takes only the part it needs — without changing what the library does.
• The obstacle. 978 classes in timefold-solver-core depend on each other in a loop. A module has to be built before whatever uses it. Inside a loop there is no first, so no boundary can be drawn anywhere in it.
• What was done. The loop was reduced first. A dependency-injection container was introduced into the core, so that classes are given what they need instead of creating it. Nine modules were then separated out, one at a time.
• Two modules cost nothing at all. util and neighborhood came out with no change to the published API.
• The rest needed four changes to the published API. Four types change package or declaration. Section 8 describes each with what forces it and what it costs a user. Three are forced by the module system. One was a judgement call, and was put to the operator rather than taken.
• No regression. The full test suite at the end is identical to a control build, module for module and not merely on totals: the same suites, the same tests, the same outcomes. It was run and compared after every step, and twice it disagreed and the work stopped until it agreed again. Section 10 gives the control and what it covers.
• What a consumer’s build has to pull in. Twenty-four modules in the timefold-solver repository build against the core — adapters, integrations, tools and benchmarks. Eleven of them declare a planning model and never construct a solver: those used to resolve 45% of the core’s compiled classes in order to compile, and now resolve 19%. The rest are unchanged, because code that runs a solve needs the engine either way. Section 9 has the table.
• How it was done. The CodeLaser engine holds a model of the source. It answers questions about it with counts, prices a proposed change before it is made, and ranks the alternatives. Claude works from those measurements — not from reading the source — chooses the next step, and issues it as a single operation that CodeLaser applies across the whole project. Sections 2 and 3 describe the setup.
• Where it ends up. Nine modules with a fixed build order, the shape of which is below and again in section 9.
• Two observations about the build. The API-compatibility filter matches classes only, so interfaces, enums and annotation types are not compared. And dependency:analyze reports a test-scoped dependency as unused when the tests still need it. Section 11.

The setup

2. The project setup

Four components were involved: the Timefold source, the CodeLaser engine, Claude Code, and the Maven build.

The Timefold source. A fresh clone of timefold-solver-core at upstream commit 9adba5acf5, on its own branch. The Timefold repository itself was never written to.

The CodeLaser engine. A refactoring and modernization engine. It reads the whole project once and builds a model of it — every type, every member, every reference from one to another. It answers questions from that model, and it changes code through operations rather than by editing text.

Claude Code. Drives the work. It puts questions to the model, receives measurements and ranked options back, chooses the next step from them, and issues it as one operation. It records what it expected each step to produce, and then what was actually measured.

The Maven build. Timefold’s own build, unchanged. After each step it compiles the project and runs the whole test suite.

Nothing in this work is decided from a description of the code. Every question is answered from the CodeLaser model as it stands at that moment, and every result is measured again after the change has landed.

The tool

3. How the CodeLaser engine works

This section describes what CodeLaser does that an editor and a compiler do not.

It holds a model of the code, not the text. The project is parsed once. What CodeLaser then holds is its structure: the types, what each one declares, and how the type hierarchies fit together. It also holds every reference from one place to another — calls, constructions, annotations, imports, and the javadoc links between them. The dependency graph follows from that.

So do the questions worth asking of it. "How many places create this class by name?" comes back as a number, not as a text search somebody has to read and judge. So does "what can this type still reach", and "what would this boundary cost".

It changes code as whole operations. Moving a set of classes is one instruction. It is one kind among many: this run used 59 different operations. Others extract a supertype, pull a member up a hierarchy, relocate static members, rewrite a declaration across every implementation of it, replace an expression wherever it occurs, or write a module descriptor.

Whichever it is, CodeLaser finds every place the change reaches and rewrites each one — imports, module declarations and build files included. One instruction in this run rewrote 5 603 places.

It refuses what it cannot do correctly. An operation that would leave the project not compiling is declined before anything is written. Almost nothing in this run was typed by hand. Where CodeLaser had no operation for a shape, that was recorded as a gap in CodeLaser rather than patched around.

It shows which types belong together. This is what decided where the boundaries went. From the type hierarchies and the call chains, CodeLaser reports which types form a group that reaches only inward. Such a group is a candidate module. For any set someone proposes, it reports how many references would still cross the line, and in which direction. Sets can then be compared by number instead of argued over.

The fifth separation was chosen that way. Three candidate sets were scored: 112 classes with one reference still crossing, 113 with none, and 140 with one again. The middle one was taken. It was the only one that left nothing behind.

It computes and ranks options. Given a proposed boundary it reports what that boundary would cost and what it would free, before anything is changed. In this run it also proposed relocations of its own and priced each one; ten of sixteen were taken.

It rebuilds its model after every change it makes. A change that leaves the project not compiling stops there, and the model is never out of step with the files on disk.

This run used 59 different operations across 548 calls. Some examples, from simple to more advanced:

The first two and the last change nothing; they answer a question. Most of the API is of that kind — querying the dependency graph, measuring a proposed boundary, scoring one arrangement against another. Of the 548 calls in this run, 301 changed nothing.

The starting position

4. What the module system requires, and why the core cannot simply be cut

Throughout this document, the core means timefold-solver-core — the single artifact this work started from — and the engine means the part of it that runs a solve.

The target is the Java Platform Module System — JPMS — which arrived in Java 9. Three of its rules decide everything that follows.

1. A module declares what it needs and what it offers. Each module carries a module-info.java naming the modules it requires and the packages it exports. Both are enforced by the compiler. Code that uses a type from a package another module has not exported does not compile, even though the class is on the path.
2. Modules are built in an order. Module B can use module A if A is built first. Two modules cannot require each other, in either direction, at any remove.
3. A package belongs to one module only. The same package name cannot appear in two of them. A candidate module cannot take three classes out of a five-class package and leave two behind. Packages move whole, or not at all.

Rule 2 is what makes timefold-solver-core hard to cut. 978 of its classes reach each other in a loop: A uses B, B uses C, and C uses A again. No order puts any one of them first, so no boundary can be drawn between any two of them. In a loop of 978 classes that applies to every pair in it.

Moving files does not help. A class moved from one side of a proposed boundary to the other takes its dependencies with it, so the loop is the same size afterwards. The loop shrinks only when a dependency is removed, which is what the first three steps of the work did.

Rule 3 decided more outcomes than the dependency graph did. More than once a boundary the dependencies allowed was still unavailable, because taking it would have split a package across two modules.

Method

5. The loop each step of the work went through

The work followed the same loop at every step: measure the code as it stands, get back a ranked set of possible moves, take one, and check the result against what was predicted.

1. Measure the source itself. Every figure in this document was derived from the Timefold source, on the branch the work ran on, at the moment it was needed. Nothing was carried in from elsewhere and nothing was assumed to still hold.
2. Establish that a step is possible before pricing it. Before any cost is estimated, CodeLaser is asked whether the boundary holds: graph.splitReadiness reports whether any package would end up split across two modules, and what the proposed module would still need from the one it is leaving. Nothing crossing means the step can go ahead. Operations can also be dry-run, and were, but a dry run checks one edit rather than deciding whether a boundary is sound.
3. Predict the outcome as a number, then compare. Each step was priced before it was made and scored afterwards. The tally is in section 12.
4. Make the change with an operation, not by hand. Every change to Java source goes through CodeLaser, which rewrites every place it reaches. Section 12 lists the few exceptions and what they were.
5. Gate on the tests, not only on the compiler. Everything is compiled, of course, and a change that does not compile never lands. But a clean compile says nothing about behaviour, so the standard is the whole test suite: no new failure, and a per-suite result identical to that step’s own starting point.
6. Score the step by measuring again. A result was never taken from what an operation reported having done. It was taken from a fresh measurement afterwards.

From the complete chain, steps 3 and 6 are the two most often skipped. They are cheap to run and they are what makes a claim checkable afterwards: without a prediction there is nothing for the measurement to disagree with. Step 5 is the expensive one — a full install is about nine minutes and the acceptance suite about fifty.

What was done

6. Stepwise overview of the split

Phase by phase

7. The nine steps, in more detail

The same nine steps as the table above, with what each was for and what it took. A step ended only when the whole test suite matched its own starting point.

The trade-off

8. Four changes to the published API, and what each unblocks

Four types changed package or were re-declared. Two happened in step 4, one in step 5 and one in step 6. Each is described below with what forced it.

Three of the four are consequences of the module system rather than choices. A package cannot live in two modules. So a type that has to end up in a different module from its neighbours must first leave the package it shares with them. The fourth was a judgement call.

Every one of them removed an obstacle that was blocking a separation. That is the case for making them, and it is a case that can be argued with.

The result

9. Nine modules, built in a fixed order

Assurance

10. How we know nothing broke

A control build was held at a fixed commit and never written to. After each significant step the whole project was tested and compared against that control, module by module rather than on totals.

The control sits partway through the work, at the commit immediately before the fourth separation. It already carries the container change and the first three separations. So the comparison covers everything from that point on — the remaining separations and both carves, which is where most of the file movement happened. The original starting point was never run through the full suite, so we make no claim about the phases before the control.

⭐ The two marked rows show the comparison doing its job. A comparison that never disagrees is not evidence that anything is being checked. This one disagreed twice: one extra failure, then 45 extra errors. Each time the work stopped until the numbers returned to the control.

⚠ About the 91 failures and 72 errors. They are present in the control, so nothing measured here introduced them. We are not claiming they were present before this work started, because that was never measured. The working record puts most of them down to two causes: the container change made earlier in this work, and a third-party tool used by one module. We did not fix them. They are quoted only because the claim is a comparison, and the numbers mean nothing without one.

The finished state also builds clean: the whole project installs with no errors, including dependency analysis, the API comparison and the framework’s build-time step.

Aside

11. Remark — two build checks cover less than they appear to

Separating a module means moving types between artifacts. Two checks in the build exist to catch what that can break. revapi compares the published API against the previous release. dependency:analyze reports declared dependencies that are not used. Both were relied on during this work, so both were examined.

Each turns out to cover less than its name suggests. Neither affects any result above, and both predate this work. They are written down because they are useful to know about.

Effort

12. Effort required to compute and perform the split

Included because it bears on whether the exercise is repeatable, not as a comparison with what it would take by hand.

One instruction is not one edit. A single operation moving a set of classes rewrites every reference to them across the project.

⭐ The score module is the clearest case. 27 classes moved, and the operation made 5 603 edits to keep the project compiling.

Almost nothing was typed by hand. Every Java edit went through a refactoring operation. The exceptions are enumerated: two one-line edits, five module descriptors, fourteen export grants, three whole-file rewrites, and eleven repairs of CodeLaser’s own output. That is 35 files, in a diff of 1 861.

⚠ These are counts of work, not of time. How long the exercise took is not reported here: most of it is the build waiting, and it says more about the machine than about the method.

Appendix

A. What was not done, and why

• No tenth module. A user-facing API split fails because api.solver genuinely mixes model and configuration types. A separate descriptor module has no consumer that wants descriptors without also building a solver. Both were measured and refused rather than attempted.
• 206 documentation links were downgraded, and left that way. This one needs explaining, because it is a defect in CodeLaser rather than a decision.

  During the largest separation, the move operation rewrote 206 {@link} references into {@code} in 114 files that did not move, across ten modules. In generated javadoc a {@link} is a hyperlink and {@code} is plain text, so the name is still written out and nothing fails to compile. It is a loss of navigation in the documentation, and no check reports it.

  It should not have done this. At the moment the move runs, the new module has no descriptor yet. So the operation cannot see that the reference will still resolve, and it takes the safe option. The reference does resolve: core passes the new module through to everything that reads it, and all ten of those modules read core.

  We left them alone. Re-linking 206 references across 114 files is a larger and riskier edit than the loss it repairs, and the fix belongs in the operation rather than in this codebase.

Appendix

B. Why the test suite, and not the compiler, was the gate

Section 5 gives running the whole test suite as the standard at every step, rather than a clean compile. A clean compile is faster and it is what most refactoring tools stop at. Three problems in this work show why it is not enough: each one compiled, and each was found by running.

Code that names a class only when it runs. A test that loads a class by its name in a string has no visible dependency on it. Nothing in the source says the two are connected, so no analysis of the source can say so either. The largest separation was expected to break tests of this kind, and the number was predicted before the move: 151. The first suite run afterwards produced 23 failures and 128 errors across 22 test classes — 151.

A framework that is told which artifacts to scan, by name. Quarkus builds an index at build time from a list of artifacts. When annotated classes moved into a new artifact, that artifact was not on the list, so the index no longer covered them. The compile was clean and the build-time step failed. The remedy was one line naming the new artifact.

CodeLaser changing files it was not moving. Six annotated varargs declarations and five imports were printed back wrongly in files outside the move, and one provides declaration was deleted where a requires should have been added. The compiler found all of them and each was repaired. The 206 documentation links in appendix A are the same class of problem, and are the one case nothing reported.

⚠ And a weakness in the procedure, from the same record. For three steps the routine check ran one module’s tests rather than the whole project’s, because it is much faster. Problems accumulated unseen during that window and had to be paid off later, all at once. The check was widened to the whole project afterwards, and it is the reason the acceptance figures in section 10 are whole-reactor runs rather than one module’s.

Appendix

C. How the figures here were checked

Every figure was verified against the file it is attributed to, mechanically rather than by reading back: 22 of 22 present in every source claimed.

The record is checkable in a second way. Runs are numbered as they are submitted, and the archive holds numbers 1 to 369 with no gaps, so no run is missing and every claim traces to one.

Where two sources disagreed, the underlying register settled it rather than a preference. One count of decisions differed between a summary and a narrative; counting the register directly gives 48.