Skip to content

Commit f64b625

Browse files
committed
test: specify graph kernel pilot contract
1 parent a2f4fc0 commit f64b625

6 files changed

Lines changed: 180 additions & 7 deletions

File tree

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"schema_version": 1,
3+
"id": "archunit-java-issue-002-pilot",
4+
"branch": "campaign/issue-002-graph-kernel",
5+
"profile": "profile.toml",
6+
"tasks": [
7+
{
8+
"task": "tasks/001-build-baseline.json",
9+
"issue": 1,
10+
"contract": "contracts/001-build-baseline",
11+
"initially_completed": true
12+
},
13+
{
14+
"task": "tasks/002-graph-kernel.json",
15+
"issue": 2,
16+
"contract": "contracts/002-graph-kernel"
17+
}
18+
]
19+
}

‎.archunitdev/campaign.template.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@
1212
},
1313
{
1414
"task": "tasks/002-graph-kernel.json",
15-
"issue": 2
15+
"issue": 2,
16+
"contract": "contracts/002-graph-kernel"
1617
},
1718
{
1819
"task": "tasks/003-patterns.json",
Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
package dev.archunitjava.contract;
2+
3+
import static org.junit.jupiter.api.Assertions.assertEquals;
4+
import static org.junit.jupiter.api.Assertions.assertFalse;
5+
import static org.junit.jupiter.api.Assertions.assertNotEquals;
6+
import static org.junit.jupiter.api.Assertions.assertThrows;
7+
import static org.junit.jupiter.api.Assertions.assertTrue;
8+
9+
import dev.archunitjava.graph.DependencyEvidence;
10+
import dev.archunitjava.graph.DependencyGraph;
11+
import dev.archunitjava.graph.DependencyKind;
12+
import dev.archunitjava.graph.GraphNode;
13+
import dev.archunitjava.graph.GraphValidationException;
14+
import dev.archunitjava.graph.LocationId;
15+
import dev.archunitjava.graph.MemberId;
16+
import dev.archunitjava.graph.ModuleId;
17+
import dev.archunitjava.graph.PackageId;
18+
import dev.archunitjava.graph.TypeId;
19+
import java.util.List;
20+
import java.util.function.Function;
21+
import org.junit.jupiter.api.Test;
22+
23+
final class GraphKernelContractTest {
24+
@Test
25+
void identifiersHaveTypedStableKeysAndRejectAmbiguousText() {
26+
PackageId namedPackage = PackageId.named("com.example.api");
27+
PackageId unnamedPackage = PackageId.unnamed();
28+
TypeId type = TypeId.ofBinaryName("com.example.api.Outer$Inner");
29+
MemberId member = MemberId.of(type, "call", "(Ljava/lang/String;)V");
30+
ModuleId module = ModuleId.named("com.example.module");
31+
LocationId location = LocationId.ofResourcePath("classes/com/example/api/Outer$Inner.class");
32+
33+
assertEquals("com.example.api", namedPackage.qualifiedName());
34+
assertTrue(unnamedPackage.isUnnamed());
35+
assertEquals("com.example.api.Outer$Inner", type.binaryName());
36+
assertEquals(type, member.owner());
37+
assertEquals("call", member.name());
38+
assertEquals("(Ljava/lang/String;)V", member.descriptor());
39+
assertEquals("com.example.module", module.name());
40+
assertEquals("classes/com/example/api/Outer$Inner.class", location.resourcePath());
41+
assertNotEquals(PackageId.named("same").stableKey(), TypeId.ofBinaryName("same").stableKey());
42+
43+
rejects(List.of("", " ", ".com", "com.", "com..example", "com/example"), PackageId::named);
44+
rejects(List.of("", " ", ".Type", "com..Type", "com/Type", "Lcom.Type;", "[Lcom.Type;"),
45+
TypeId::ofBinaryName);
46+
rejects(List.of("", " ", ".module", "module.", "com..module", "com/module"), ModuleId::named);
47+
rejects(List.of("", " ", "/absolute.class", "C:/absolute.class", "../escape.class",
48+
"classes/../escape.class", "classes\\Type.class"), LocationId::ofResourcePath);
49+
50+
assertThrows(IllegalArgumentException.class, () -> PackageId.named(null));
51+
assertThrows(IllegalArgumentException.class, () -> TypeId.ofBinaryName(null));
52+
assertThrows(IllegalArgumentException.class, () -> ModuleId.named(null));
53+
assertThrows(IllegalArgumentException.class, () -> LocationId.ofResourcePath(null));
54+
assertThrows(IllegalArgumentException.class, () -> MemberId.of(type, "", "I"));
55+
assertThrows(IllegalArgumentException.class, () -> MemberId.of(type, "bad name", "I"));
56+
assertThrows(IllegalArgumentException.class, () -> MemberId.of(type, "value", ""));
57+
assertThrows(IllegalArgumentException.class, () -> MemberId.of(type, "value", "bad descriptor"));
58+
}
59+
60+
@Test
61+
void parallelEdgesMergeDuplicateFreeEvidenceAndIterateDeterministically() {
62+
TypeId api = TypeId.ofBinaryName("com.example.Api");
63+
TypeId isolated = TypeId.ofBinaryName("com.example.Isolated");
64+
TypeId service = TypeId.ofBinaryName("com.example.Service");
65+
MemberId caller = MemberId.of(api, "invoke", "()V");
66+
DependencyEvidence later = DependencyEvidence.at(
67+
LocationId.ofResourcePath("classes/com/example/Z.class"), caller, 21, 8);
68+
DependencyEvidence earlier = DependencyEvidence.at(
69+
LocationId.ofResourcePath("classes/com/example/A.class"), caller, 4, 3);
70+
71+
DependencyGraph graph = DependencyGraph.builder()
72+
.addNode(service)
73+
.addNode(api)
74+
.addNode(isolated)
75+
.addDependency(api, service, DependencyKind.METHOD_CALL, later)
76+
.addDependency(api, service, DependencyKind.METHOD_CALL, earlier)
77+
.addDependency(api, service, DependencyKind.METHOD_CALL, earlier)
78+
.addDependency(api, service, DependencyKind.FIELD_TYPE, later)
79+
.build();
80+
81+
assertEquals(List.of(api, isolated, service), graph.nodes().stream().map(GraphNode::id).toList());
82+
assertEquals(2, graph.edges().size());
83+
var methodCall = graph.edges().stream()
84+
.filter(edge -> edge.kind() == DependencyKind.METHOD_CALL)
85+
.findFirst()
86+
.orElseThrow();
87+
assertEquals(api, methodCall.origin());
88+
assertEquals(service, methodCall.target());
89+
assertEquals(List.of(earlier, later), methodCall.evidence());
90+
91+
DependencyGraph reverseInsertion = DependencyGraph.builder()
92+
.addNode(isolated)
93+
.addNode(api)
94+
.addNode(service)
95+
.addDependency(api, service, DependencyKind.FIELD_TYPE, later)
96+
.addDependency(api, service, DependencyKind.METHOD_CALL, earlier)
97+
.addDependency(api, service, DependencyKind.METHOD_CALL, later)
98+
.build();
99+
assertEquals(graph.nodes(), reverseInsertion.nodes());
100+
assertEquals(graph.edges(), reverseInsertion.edges());
101+
}
102+
103+
@Test
104+
void builtGraphsAreImmutableSnapshotsAndPreserveIsolatedNodes() {
105+
TypeId source = TypeId.ofBinaryName("com.example.Source");
106+
TypeId target = TypeId.ofBinaryName("com.example.Target");
107+
TypeId isolated = TypeId.ofBinaryName("com.example.Isolated");
108+
DependencyEvidence evidence = DependencyEvidence.at(
109+
LocationId.ofResourcePath("classes/com/example/Source.class"));
110+
DependencyGraph.Builder builder = DependencyGraph.builder()
111+
.addNode(source)
112+
.addNode(target)
113+
.addNode(isolated)
114+
.addDependency(source, target, DependencyKind.METHOD_CALL, evidence);
115+
116+
DependencyGraph snapshot = builder.build();
117+
builder.addNode(TypeId.ofBinaryName("com.example.AddedLater"));
118+
119+
assertEquals(3, snapshot.nodes().size());
120+
assertTrue(snapshot.nodes().stream().map(GraphNode::id).anyMatch(isolated::equals));
121+
assertFalse(snapshot.nodes().stream().map(GraphNode::id)
122+
.anyMatch(TypeId.ofBinaryName("com.example.AddedLater")::equals));
123+
assertThrows(UnsupportedOperationException.class, () -> snapshot.nodes().clear());
124+
assertThrows(UnsupportedOperationException.class, () -> snapshot.edges().clear());
125+
assertThrows(UnsupportedOperationException.class, () -> snapshot.edges().getFirst().evidence().clear());
126+
}
127+
128+
@Test
129+
void graphConstructionRejectsUnknownEndpoints() {
130+
TypeId known = TypeId.ofBinaryName("com.example.Known");
131+
TypeId missing = TypeId.ofBinaryName("com.example.Missing");
132+
DependencyEvidence evidence = DependencyEvidence.at(
133+
LocationId.ofResourcePath("classes/com/example/Known.class"));
134+
135+
GraphValidationException error = assertThrows(
136+
GraphValidationException.class,
137+
() -> DependencyGraph.builder()
138+
.addNode(known)
139+
.addDependency(known, missing, DependencyKind.METHOD_CALL, evidence)
140+
.build());
141+
142+
assertTrue(error.getMessage().contains(missing.stableKey()));
143+
}
144+
145+
private static <T> void rejects(List<String> values, Function<String, T> factory) {
146+
for (String value : values) {
147+
assertThrows(IllegalArgumentException.class, () -> factory.apply(value), () -> "accepted " + value);
148+
}
149+
}
150+
}

‎.archunitdev/github-issues.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
"phase:foundation",
2121
"type:feature",
2222
"contract:specified",
23-
"contract:missing",
23+
"contract:executable",
2424
"workflow:dependency-ready"
2525
],
2626
"initially_completed": false

‎docs/issues/002-graph-kernel.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Implement stable identifiers, dependency kinds, evidence, nodes, edges, and an i
1818
## Workflow
1919

2020
- Task specification: `.archunitdev/tasks/002-graph-kernel.json`
21-
- Executable contract overlay: not authored; do not schedule
21+
- Executable contract overlay: `.archunitdev/contracts/002-graph-kernel/`
2222
- Phase: `foundation`
2323
- Type: `feature`
2424
- Depends on: #1

‎scripts/generate_backlog_assets.py‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ class Item:
2121
kind: str = "feature"
2222
non_goals: tuple[str, ...] = ()
2323
initially_completed: bool = False
24+
contract_ready: bool = False
2425

2526
@property
2627
def task_id(self) -> str:
@@ -44,6 +45,7 @@ def item(
4445
kind: str = "feature",
4546
non_goals: tuple[str, ...] = (),
4647
initially_completed: bool = False,
48+
contract_ready: bool = False,
4749
) -> Item:
4850
return Item(
4951
number,
@@ -57,6 +59,7 @@ def item(
5759
kind,
5860
non_goals,
5961
initially_completed,
62+
contract_ready,
6063
)
6164

6265

@@ -73,7 +76,7 @@ def item(
7376
("pom.xml", "mvnw", "mvnw.cmd", ".mvn/**", ".github/workflows/ci.yml", "src/main/java/dev/archunitjava/ArchUnitJava.java", "src/test/java/dev/archunitjava/ArchUnitJavaTest.java"), "foundation", kind="infrastructure", initially_completed=True),
7477
item(2, "graph-kernel", "Foundation: deterministic Java dependency-graph kernel",
7578
"Implement stable identifiers, dependency kinds, evidence, nodes, edges, and an immutable deterministic graph.", (1,),
76-
("Package, type, member, module, and location identifiers reject invalid or ambiguous values.", "Parallel edges merge evidence without duplicates and all iteration is stable.", "Graph construction rejects unknown endpoints and preserves isolated nodes."), MAIN, "foundation"),
79+
("Package, type, member, module, and location identifiers reject invalid or ambiguous values.", "Parallel edges merge evidence without duplicates and all iteration is stable.", "Graph construction rejects unknown endpoints and preserves isolated nodes."), MAIN, "foundation", contract_ready=True),
7780
item(3, "patterns", "Foundation: Java-aware glob, regex, and qualified-name patterns",
7881
"Compile user patterns once and match paths, packages, binary names, and source-style type names with explicit semantics.", (1,),
7982
("Path and qualified-name separators have distinct documented glob rules.", "Regex and exact patterns share immutable matcher descriptions.", "Malformed patterns fail as user errors before analysis starts."), MAIN, "foundation"),
@@ -324,7 +327,7 @@ def main() -> None:
324327
f"phase:{entry.phase}",
325328
f"type:{entry.kind}",
326329
"contract:specified",
327-
"contract:executable" if entry.initially_completed else "contract:missing",
330+
"contract:executable" if entry.contract_ready or entry.initially_completed else "contract:missing",
328331
"workflow:completed" if entry.initially_completed else (
329332
"workflow:dependency-ready"
330333
if set(entry.dependencies) <= completed_numbers
@@ -404,7 +407,7 @@ def _issue_body(entry: Item, blocks: list[int]) -> str:
404407
"## Workflow\n\n"
405408
f"- Task specification: `.archunitdev/tasks/{entry.task_name}`\n"
406409
f"- Executable contract overlay: "
407-
f"{f'`.archunitdev/contracts/{entry.number:03d}-{entry.slug}/`' if entry.initially_completed else 'not authored; do not schedule'}\n"
410+
f"{f'`.archunitdev/contracts/{entry.number:03d}-{entry.slug}/`' if entry.contract_ready or entry.initially_completed else 'not authored; do not schedule'}\n"
408411
f"- Phase: `{entry.phase}`\n"
409412
f"- Type: `{entry.kind}`\n"
410413
f"- Depends on: {depends}\n"
@@ -466,7 +469,7 @@ def _campaign(by_number: dict[int, Item]) -> dict[str, object]:
466469
{
467470
"task": f"tasks/{by_number[number].task_name}",
468471
"issue": number,
469-
**({"contract": f"contracts/{number:03d}-{by_number[number].slug}"} if by_number[number].initially_completed else {}),
472+
**({"contract": f"contracts/{number:03d}-{by_number[number].slug}"} if by_number[number].contract_ready or by_number[number].initially_completed else {}),
470473
**({"initially_completed": True} if by_number[number].initially_completed else {}),
471474
}
472475
for number in order

0 commit comments

Comments
 (0)