task-4: SourceScan 点名普查落地 8 例(RED 实录 1 Failure+7 Errors);台账 15 调用点/8 调用方/10 裸名,plan 原文「9 支文件」经核为把 SourceScan.java:22 声明行算进分母

This commit is contained in:
2026-10-16 15:46:30 +08:00
parent e1e3842045
commit 5c3668fc2e
2 changed files with 257 additions and 0 deletions
@@ -5,6 +5,8 @@ import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;
@@ -16,6 +18,83 @@ public final class SourceScan {
private SourceScan() {
}
/** 一处 {@code sourceText("<裸名>")} 字面量点名。 */
public record CallSite(String bareName, String relativeFile, int line) {
}
private static final Pattern CALL_SITE = Pattern.compile("sourceText\\(\\s*\"([^\"]+)\"\\s*\\)");
/** {@code src/test/java} 的绝对根,与 {@link #mainSources()} 同一条定位分支。 */
public static Path testSourcesRoot() {
Path root = moduleRoot().resolve("src/test/java");
if (!Files.isDirectory(root)) {
throw new IllegalStateException("语料根不存在: " + root + "(cwd=" + Path.of("").toAbsolutePath() + ")");
}
return root;
}
/** 点名普查:列出 {@code src/test/java} 里每一处 {@code sourceText("<裸名>")} 字面量调用。 */
public static List<CallSite> censusSourceTextCallSites() {
return censusSourceTextCallSites(testSourcesRoot());
}
/**
* 点名普查(可指定语料根)。三条设计决定都是被坑逼出来的:
* <ol>
* <li><b>数的是代码不是文字</b>:判据打在 {@link #withoutComments} 上,注释里提一句
* {@code sourceText("Fake.java")} 不计入——否则台账的 15 会被 javadoc 喂成任意大的数。</li>
* <li><b>只配字面量</b>:正则要求紧跟一对引号,所以 {@code SourceScan.java:22} 那行
* 被调方自己的声明(参数是 {@code String fileName})天然不算调用点。plan 原文的「9 支文件」
* 正是 {@code grep -rl 'sourceText('} 把声明也算了进去;真实调用点是 15 处/8 支文件。</li>
* <li><b>语料根不存在必须抛</b>,不许返回空表:空表会被读成「已经没人用裸名口径了」。
* 目录存在且确实没有 {@code .java} 才返回空——那是"语料真的没了",与"尺子架错地方"是两回事。</li>
* </ol>
*/
public static List<CallSite> censusSourceTextCallSites(Path corpusRoot) {
Path root = corpusRoot.toAbsolutePath();
if (!Files.isDirectory(root)) {
throw new IllegalStateException("语料根不存在: " + root + "(cwd=" + Path.of("").toAbsolutePath() + ")");
}
Path base = moduleRoot();
List<CallSite> sites = new java.util.ArrayList<>();
try (Stream<Path> walk = Files.walk(root)) {
List<Path> files = walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith(".java"))
.sorted(java.util.Comparator.comparing(p -> relativizeForCensus(p, root, base).replace('\\', '/')))
.toList();
for (Path file : files) {
String code = withoutComments(read(file));
String relative = relativizeForCensus(file, root, base).replace('\\', '/');
Matcher matcher = CALL_SITE.matcher(code);
while (matcher.find()) {
sites.add(new CallSite(matcher.group(1), relative, lineAt(code, matcher.start())));
}
}
} catch (IOException e) {
throw new IllegalStateException("遍历 " + root + " 失败: " + e.getMessage(), e);
}
return List.copyOf(sites);
}
private static String relativizeForCensus(Path file, Path corpusRoot, Path moduleRoot) {
Path absolute = file.toAbsolutePath();
if (absolute.startsWith(moduleRoot)) {
return moduleRoot.relativize(absolute).toString();
}
return corpusRoot.relativize(absolute).toString();
}
/** 偏移不变的 {@link #withoutComments} 保证:剥完再数换行,行号仍等于原文件行号。 */
private static int lineAt(String code, int offset) {
int line = 1;
for (int i = 0; i < offset; i++) {
if (code.charAt(i) == '\n') {
line++;
}
}
return line;
}
/** 按文件名(不含目录)取 {@code src/main/java} 下那份源码的<b>全文字符串</b>。
* ⚠️ 返回 String,与 InternalTokenSingleOutletTest 里那个返回 Path 的私有 {@code sourceOf} 不是一回事,
* 别指望复用它的——那个是 private。 */
@@ -0,0 +1,178 @@
package com.nanri.aiimage.testutil;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Set;
import java.util.stream.Collectors;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
/**
* {@link SourceScan} 自己的护栏(2026-10-16,plan 01 N4 起)。
*
* <p><b>N4 点名普查台账</b>(由 {@code census_sourceText调用点总数不少于10} 那格机器复算,不是手抄):</p>
* <pre>
* 被点名裸名(10 个唯一) 字面量调用点 出处
* ---------------------------------------------------------------------------
* PublishController.java 3 PublishOwnershipGuardrailTest:42 :82 :96
* AdminApiGuardFilter.java 2 AdminGuardSwitchConfigTest:107 :254
* AdminDeviceLogController.java 2 DeviceLogServiceTest:412 :428
* LockSkipWitness.java 2 LockSkipWitnessTest:178 + LockSkipSilentExitGuardrailTest:153
* AppearancePatentTaskService.java 1 PublishOwnershipGuardrailTest:111
* PublishTaskService.java 1 PublishOwnershipGuardrailTest:109
* SimilarAsinTaskService.java 1 PublishOwnershipGuardrailTest:112
* ClientVersionGuardFilter.java 1 ClientVersionFloorConfigTest:249
* PermissionMenuService.java 1 MenuWriteOutletOperatorTest:30
* ShopManageController.java 1 ShopManageServiceTest:185
* ---------------------------------------------------------------------------
* 合计 15 落在 <b>8</b> 支调用方文件里
* </pre>
*
* <p><b>一处与 plan 原文不符的读数,按"先怀疑尺子"的流程处理并留在脸上</b>:plan/AGENTS §1 记的是「9 支文件」,
* 那条数是 {@code grep -rl 'sourceText('} 数出来的,而第 9 支是 {@code SourceScan.java:22} 里
* {@code public static String sourceText(String fileName)} 这行<b>被调方自己的声明</b>——它不是调用点。
* 所以真实形状是 <b>15 个调用点/8 支调用方/9 支引用方文件</b>。下面第 3 格把这三个数同时钉住,
* 免得下一个人拿 {@code grep} 再数一遍又把声明算进去。</p>
*/
class SourceScanTest {
/** 台账里登记过的 10 个被点名裸名,逐字对撞用。 */
private static final Set<String> REGISTERED_BARE_NAMES = Set.of(
"PublishController.java",
"PublishTaskService.java",
"AppearancePatentTaskService.java",
"SimilarAsinTaskService.java",
"AdminApiGuardFilter.java",
"AdminDeviceLogController.java",
"ClientVersionGuardFilter.java",
"LockSkipWitness.java",
"PermissionMenuService.java",
"ShopManageController.java");
@TempDir
Path tmp;
@Test
void census_sourceText调用点总数不少于10() {
List<SourceScan.CallSite> sites = SourceScan.censusSourceTextCallSites();
assertThat(sites)
.as("普查扫到的字面量调用点总数——下限判据:扫到 0 会被误读成「已经没人点名单文件了」,"
+ "而真相往往是语料根没找对")
.hasSizeGreaterThanOrEqualTo(10);
}
@Test
void census_唯一裸名恰为10且与已登记集合相等() {
Set<String> found = SourceScan.censusSourceTextCallSites().stream()
.map(SourceScan.CallSite::bareName)
.collect(Collectors.toSet());
assertThat(found)
.as("唯一裸名集合必须与类头台账逐字相等——多一个说明有人新引了单文件口径,少一个说明尺子漏扫")
.isEqualTo(REGISTERED_BARE_NAMES)
.hasSize(10);
}
@Test
void census_涉及文件恰为9() {
List<SourceScan.CallSite> sites = SourceScan.censusSourceTextCallSites();
Set<String> callerFiles = sites.stream()
.map(SourceScan.CallSite::relativeFile)
.collect(Collectors.toSet());
String declarationFile = "src/test/java/com/nanri/aiimage/testutil/SourceScan.java";
assertThat(callerFiles)
.as("真实字面量调用点落在 8 支调用方文件里")
.hasSize(8);
assertThat(callerFiles)
.as("plan 原文记的「9 支」= grep -rl 'sourceText(' 的条数,第 9 支是被调方自己的声明行"
+ "(SourceScan.java:22 的 `public static String sourceText(String fileName)`),"
+ "它不是调用点。这里把「声明件必须落在调用方集合之外」钉成机器判,"
+ "免得下一个人再拿 grep 数一遍把声明算进分母")
.doesNotContain(declarationFile);
assertThat(Path.of(declarationFile)).exists();
}
@Test
void census_空语料目录返回空而非抛() throws IOException {
Path empty = Files.createDirectories(tmp.resolve("empty_corpus"));
assertThat(SourceScan.censusSourceTextCallSites(empty))
.as("目录存在且确实是空的 ⇒ 返回空表。这与「目录不存在必须抛」是两回事,"
+ "前者是语料真的没了,后者是尺子架错了地方")
.isEmpty();
}
@Test
void census_中文路径文件被计入不丢失() throws IOException {
Path corpus = Files.createDirectories(tmp.resolve("语料根"));
Path chineseDir = Files.createDirectories(corpus.resolve("中文语料"));
Files.writeString(chineseDir.resolve("点名中文件.java"),
"class A { void x() { SourceScan.sourceText(\"PublishController.java\"); } }",
StandardCharsets.UTF_8);
List<SourceScan.CallSite> sites = SourceScan.censusSourceTextCallSites(corpus);
assertThat(sites)
.as("本仓有几百支中文名的测试件;遍历若按非 UTF-8 出口处理就会静默漏掉它们")
.singleElement()
.satisfies(site -> {
assertThat(site.bareName()).isEqualTo("PublishController.java");
assertThat(site.relativeFile()).contains("中文语料");
});
}
@Test
void census_同名多次调用逐条计数不合并() {
List<SourceScan.CallSite> publishController = SourceScan.censusSourceTextCallSites().stream()
.filter(site -> site.bareName().equals("PublishController.java"))
.toList();
assertThat(publishController)
.as("同一个裸名被点 3 次就必须是 3 条,按名去重会把「三格钉同一方法」这族形状抹平")
.hasSize(3)
.extracting(SourceScan.CallSite::line)
.containsExactlyInAnyOrder(42, 82, 96);
}
@Test
void census_非法正则模式不影响解析() throws IOException {
Path corpus = Files.createDirectories(tmp.resolve("混淆语料"));
Files.writeString(corpus.resolve("Mixed.java"), String.join("\n",
"class Mixed {",
" // 有人在注释里写 SourceScan.sourceText(\"CommentFake.java\") —— 这不算点名",
" static final String DOC = \"别学这个 sourceText(\\\"LiteralFake.java\\\") 的写法\";",
" void real() { SourceScan.sourceText(\"RealOne.java\"); }",
"}",
""),
StandardCharsets.UTF_8);
List<SourceScan.CallSite> sites = SourceScan.censusSourceTextCallSites(corpus);
assertThat(sites)
.as("真点名 1 条:注释里的那条要被判掉(护栏数的是代码不是文字),"
+ "字符串字面量里那条带转义引号,正则不该配上")
.singleElement()
.satisfies(site -> assertThat(site.bareName()).isEqualTo("RealOne.java"));
}
@Test
void census_扫不到源码根时抛并回显cwd() {
Path wrong = tmp.resolve("少爬了一层");
assertThatThrownBy(() -> SourceScan.censusSourceTextCallSites(wrong))
.as("根目录不存在时必须炸,不许返回空表——「扫不到」被读成「没人在用」是本族护栏的标准死法")
.isInstanceOf(IllegalStateException.class)
.hasMessageContaining("cwd=")
.hasMessageContaining(wrong.toAbsolutePath().toString());
}
}