mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
* refactor: remove redundant seams and preserve cleanup ownership * fix: validate PE resource extents before budget checks
498 lines
16 KiB
TypeScript
498 lines
16 KiB
TypeScript
import { expect, it } from "vitest";
|
|
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
|
|
import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
|
|
import { MANAGED_SKILL_FILES } from "./SetupSkill.js";
|
|
import { searchGuidanceOutputSchema } from "../contracts/guidanceContracts.js";
|
|
import { RetainedRegularFileCleanupFailure } from "./RegularFileRead.js";
|
|
import {
|
|
readGuidanceSectionWithReader,
|
|
searchGuidanceWithReader,
|
|
} from "./GuidanceAccess.js";
|
|
|
|
const moduleGuide = `# JavaScript applications\n\n## Read a module without repeating analysis\n\nFor an exact JavaScript module (javascript-module), select its source path and module identity:\n\n\`\`\`json\n{"node_id":"module:main.js","kind":"javascript-module"}\n\`\`\`\n`;
|
|
const guideFixture = async (path: string): Promise<string> =>
|
|
path === "references/javascript-applications.md"
|
|
? moduleGuide
|
|
: `# ${path}\n\nGeneral module guidance for pagination.\n`;
|
|
|
|
const valueOf = async (
|
|
request: ReturnType<typeof searchGuidanceWithReader>,
|
|
) => {
|
|
const result = await request;
|
|
if (!result.ok) throw result.error;
|
|
return searchGuidanceOutputSchema.parse(result.value);
|
|
};
|
|
|
|
it("ranks a focused JavaScript module section and retrieves it with its locator", async () => {
|
|
const resources = new ArtifactResourceScope();
|
|
const result = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "exact JavaScript module" },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
);
|
|
expect(result.status).toBe("matches");
|
|
if (result.status !== "matches") throw new Error("Expected guide matches");
|
|
expect(result.matches[0]).toMatchObject({
|
|
guide: "references/javascript-applications.md",
|
|
heading: "Read a module without repeating analysis",
|
|
matched_terms: ["exact", "javascript", "module"],
|
|
context: expect.stringContaining("javascript-module"),
|
|
});
|
|
const selected = result.matches[0];
|
|
if (selected === undefined) throw new Error("Expected selected guidance");
|
|
const retrieved = await readGuidanceSectionWithReader(
|
|
{ locator: selected.locator },
|
|
guideFixture,
|
|
resources,
|
|
);
|
|
if (!retrieved.ok) throw retrieved.error;
|
|
expect(retrieved.value).toMatchObject({
|
|
status: "section",
|
|
source: "installed_rea_guidance",
|
|
guide: selected.guide,
|
|
heading: selected.heading,
|
|
locator: selected.locator,
|
|
content: expect.stringContaining('"node_id":"module:main.js"'),
|
|
});
|
|
});
|
|
|
|
it("returns an honest no-match result and rejects empty queries and invalid bounds", async () => {
|
|
const resources = new ArtifactResourceScope();
|
|
expect(
|
|
await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "unlikely qzxv term" },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
),
|
|
).toMatchObject({
|
|
status: "no_matches",
|
|
total_matches: 0,
|
|
message: expect.stringContaining("does not indicate"),
|
|
});
|
|
expect(
|
|
await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "how do I frobnicate qzxv" },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
),
|
|
).toMatchObject({
|
|
status: "no_matches",
|
|
total_matches: 0,
|
|
});
|
|
expect(
|
|
await searchGuidanceWithReader({ query: " " }, guideFixture, resources),
|
|
).toMatchObject({ ok: false });
|
|
expect(
|
|
await searchGuidanceWithReader(
|
|
{ query: "x".repeat(2049) },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
).toMatchObject({ ok: false });
|
|
expect(
|
|
await searchGuidanceWithReader(
|
|
{ query: "module", limit: 21 },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
).toMatchObject({ ok: false });
|
|
});
|
|
|
|
it("does not treat Markdown headings inside fenced code as section boundaries", async () => {
|
|
const result = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "phantom-heading-token" },
|
|
async (path) =>
|
|
`${await guideFixture(path)}\n\n\`\`\`markdown\n# phantom-heading-token\n\`\`\`\n`,
|
|
new ArtifactResourceScope(),
|
|
),
|
|
);
|
|
expect(result.status).toBe("matches");
|
|
if (result.status !== "matches") throw new Error("Expected guide matches");
|
|
expect(result.matches.map(({ heading }) => heading)).not.toContain(
|
|
"phantom-heading-token",
|
|
);
|
|
});
|
|
|
|
it("refuses an oversized guide bundle instead of indexing partial content", async () => {
|
|
const result = await searchGuidanceWithReader(
|
|
{ query: "module" },
|
|
async (path) =>
|
|
path === "SKILL.md" ? "x".repeat(4_194_305) : guideFixture(path),
|
|
new ArtifactResourceScope(),
|
|
);
|
|
expect(result).toMatchObject({
|
|
ok: true,
|
|
value: { status: "bundle_unavailable" },
|
|
});
|
|
});
|
|
|
|
it("paginates deterministically without losing, duplicating, or reordering matches", async () => {
|
|
const readGuide = guideFixture;
|
|
const first = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "module", limit: 2 },
|
|
readGuide,
|
|
new ArtifactResourceScope(),
|
|
),
|
|
);
|
|
const repeat = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "module", limit: 2 },
|
|
readGuide,
|
|
new ArtifactResourceScope(),
|
|
),
|
|
);
|
|
expect(first).toEqual(repeat);
|
|
if (first.status !== "matches") throw new Error("Expected guide matches");
|
|
expect(first.has_more).toBe(true);
|
|
const all = first.matches.map(({ locator }) => locator);
|
|
let cursor = first.next_cursor;
|
|
while (cursor !== undefined) {
|
|
const page = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "module", limit: 2, cursor },
|
|
readGuide,
|
|
new ArtifactResourceScope(),
|
|
),
|
|
);
|
|
if (page.status !== "matches") throw new Error("Expected guide matches");
|
|
all.push(...page.matches.map(({ locator }) => locator));
|
|
cursor = page.next_cursor;
|
|
}
|
|
const complete = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "module", limit: 20 },
|
|
readGuide,
|
|
new ArtifactResourceScope(),
|
|
),
|
|
);
|
|
if (complete.status !== "matches") throw new Error("Expected guide matches");
|
|
expect(new Set(all).size).toBe(all.length);
|
|
expect(all).toEqual(complete.matches.map(({ locator }) => locator));
|
|
});
|
|
|
|
it("rejects malformed locators and reports changed or missing installed guides", async () => {
|
|
const resources = new ArtifactResourceScope();
|
|
const search = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "exact JavaScript module" },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
);
|
|
if (search.status !== "matches") throw new Error("Expected guide matches");
|
|
expect(
|
|
await readGuidanceSectionWithReader(
|
|
{ locator: "../../outside.md" },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
).toMatchObject({ ok: false });
|
|
const changedReader = async (path: string) =>
|
|
`${await guideFixture(path)}\nChanged after search.\n`;
|
|
const stale = await readGuidanceSectionWithReader(
|
|
{ locator: search.matches[0]?.locator },
|
|
changedReader,
|
|
resources,
|
|
);
|
|
expect(stale).toMatchObject({ ok: true, value: { status: "stale_locator" } });
|
|
const firstPage = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "module", limit: 1 },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
);
|
|
if (firstPage.status !== "matches" || firstPage.next_cursor === undefined)
|
|
throw new Error("Expected a continuation token");
|
|
expect(
|
|
await searchGuidanceWithReader(
|
|
{ query: "module", limit: 1, cursor: firstPage.next_cursor },
|
|
changedReader,
|
|
resources,
|
|
),
|
|
).toMatchObject({ ok: true, value: { status: "stale_continuation" } });
|
|
expect(
|
|
await searchGuidanceWithReader(
|
|
{ query: "different query", cursor: firstPage.next_cursor },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
).toMatchObject({ ok: false });
|
|
expect(
|
|
await searchGuidanceWithReader(
|
|
{ query: "module", cursor: "garbage" },
|
|
guideFixture,
|
|
resources,
|
|
),
|
|
).toMatchObject({ ok: false });
|
|
const missingReader = async (): Promise<string> => {
|
|
throw Object.assign(new Error("missing"), { code: "ENOENT" });
|
|
};
|
|
expect(
|
|
await searchGuidanceWithReader(
|
|
{ query: "module" },
|
|
missingReader,
|
|
resources,
|
|
),
|
|
).toMatchObject({ ok: true, value: { status: "bundle_unavailable" } });
|
|
expect(
|
|
await readGuidanceSectionWithReader(
|
|
{ locator: search.matches[0]?.locator },
|
|
missingReader,
|
|
resources,
|
|
),
|
|
).toMatchObject({ ok: true, value: { status: "bundle_unavailable" } });
|
|
});
|
|
|
|
it("returns cleanup failures separately and retains their owner until retry succeeds", async () => {
|
|
const resources = new ArtifactResourceScope();
|
|
let failRelease = true;
|
|
const failure = new RegularFileCleanupFailure({
|
|
path: "guidance file handle",
|
|
owner: {
|
|
close: async () => {
|
|
if (failRelease) throw new Error("descriptor close failed");
|
|
},
|
|
} as never,
|
|
outcome: { kind: "failed", cause: new Error("guide read failed") },
|
|
cleanupCause: new Error("descriptor close failed"),
|
|
});
|
|
const retainedFailure = new RetainedRegularFileCleanupFailure(failure);
|
|
resources.retain(retainedFailure.cleanupOwner);
|
|
const result = await searchGuidanceWithReader(
|
|
{ query: "module" },
|
|
async () => {
|
|
throw retainedFailure;
|
|
},
|
|
resources,
|
|
);
|
|
if (result.ok) throw new Error("Expected a retained cleanup failure");
|
|
expect(result.error).toMatchObject({ cleanupIncomplete: true });
|
|
expect(result.error.cleanupResources).toEqual(["guidance file handle"]);
|
|
expect(resources.hasPending).toBe(true);
|
|
failRelease = false;
|
|
await resources.close();
|
|
expect(resources.hasPending).toBe(false);
|
|
expect(result.error.cleanupIncomplete).toBe(false);
|
|
expect(result.error.cleanupResources).toEqual([]);
|
|
|
|
const freshResources = new ArtifactResourceScope();
|
|
freshResources.retain({
|
|
kind: "lease",
|
|
resource: "unrelated pending resource",
|
|
lease: { release: async () => undefined },
|
|
});
|
|
expect(
|
|
await searchGuidanceWithReader(
|
|
{ query: "module" },
|
|
async () => {
|
|
throw new Error("guide is unreadable");
|
|
},
|
|
freshResources,
|
|
),
|
|
).toMatchObject({
|
|
ok: true,
|
|
value: { status: "bundle_unavailable" },
|
|
});
|
|
await freshResources.close();
|
|
});
|
|
|
|
it("uses only the fixed managed guide inventory for injected reads", async () => {
|
|
const requested: string[] = [];
|
|
await searchGuidanceWithReader(
|
|
{ query: "module" },
|
|
async (path) => {
|
|
requested.push(path);
|
|
return guideFixture(path);
|
|
},
|
|
new ArtifactResourceScope(),
|
|
);
|
|
expect(requested).toEqual([...MANAGED_SKILL_FILES]);
|
|
});
|
|
|
|
const nestedGuide = [
|
|
"# Native guide",
|
|
"",
|
|
"Overview of native work.",
|
|
"",
|
|
"## Apple app resources",
|
|
"",
|
|
"Switch provider bundles here.",
|
|
"",
|
|
"## Native targets",
|
|
"",
|
|
"Annotations in Ghidra last until close.",
|
|
"",
|
|
"### Function annotations in Ghidra",
|
|
"",
|
|
"Rename functions; annotations last until close.",
|
|
"",
|
|
"## Combined recovery",
|
|
"",
|
|
"Recovery steps.",
|
|
"",
|
|
"### Step alpha",
|
|
"",
|
|
"Use alphaword here.",
|
|
"",
|
|
"### Step beta",
|
|
"",
|
|
"Use betaword here.",
|
|
"",
|
|
].join("\n");
|
|
const nestedReader = async (path: string): Promise<string> =>
|
|
path === "references/native-and-artifacts.md"
|
|
? nestedGuide
|
|
: `# ${path}\n\nUnrelated guidance.\n`;
|
|
const matchesFor = async (query: string, limit = 20) => {
|
|
const result = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query, limit },
|
|
nestedReader,
|
|
new ArtifactResourceScope(),
|
|
),
|
|
);
|
|
if (result.status !== "matches") throw new Error(`No matches: ${query}`);
|
|
return result.matches;
|
|
};
|
|
|
|
it("reports a focused subsection without repeating every enclosing parent", async () => {
|
|
const matches = await matchesFor("function annotations");
|
|
expect(matches).toEqual([
|
|
expect.objectContaining({
|
|
heading: "Function annotations in Ghidra",
|
|
match_scope: "section",
|
|
matched_terms: ["function", "annotations"],
|
|
}),
|
|
]);
|
|
expect(matches[0]).not.toHaveProperty("subsections");
|
|
expect(matches[0]).not.toHaveProperty("own_text_terms");
|
|
});
|
|
|
|
it("keeps a parent whose own text holds every term alongside its matching subsection", async () => {
|
|
const matches = await matchesFor("annotations close");
|
|
expect(
|
|
matches.map(({ heading, match_scope }) => [heading, match_scope]),
|
|
).toEqual([
|
|
["Function annotations in Ghidra", "section"],
|
|
["Native targets", "section"],
|
|
]);
|
|
expect(matches[1]?.context).not.toContain("Rename functions");
|
|
});
|
|
|
|
it("labels terms scattered across sibling subsections and points to where each occurs", async () => {
|
|
const matches = await matchesFor("switch provider annotations");
|
|
expect(matches).toHaveLength(1);
|
|
const [root] = matches;
|
|
expect(root).toMatchObject({
|
|
heading: "Native guide",
|
|
match_scope: "subsections",
|
|
matched_terms: ["switch", "provider", "annotations"],
|
|
content_length: nestedGuide.trim().length,
|
|
own_text_terms: [],
|
|
relevance: expect.stringContaining("no single subsection"),
|
|
});
|
|
expect(
|
|
root?.subsections?.map(({ heading, matched_terms }) => [
|
|
heading,
|
|
matched_terms,
|
|
]),
|
|
).toEqual([
|
|
["Apple app resources", ["switch", "provider"]],
|
|
["Native targets", ["annotations"]],
|
|
]);
|
|
const pointer = root?.subsections?.[0];
|
|
if (pointer === undefined) throw new Error("Expected a subsection pointer");
|
|
const read = await readGuidanceSectionWithReader(
|
|
{ locator: pointer.locator },
|
|
nestedReader,
|
|
new ArtifactResourceScope(),
|
|
);
|
|
expect(read).toMatchObject({
|
|
ok: true,
|
|
value: { status: "section", heading: "Apple app resources" },
|
|
});
|
|
const complete = await readGuidanceSectionWithReader(
|
|
{ locator: root?.locator },
|
|
nestedReader,
|
|
new ArtifactResourceScope(),
|
|
);
|
|
if (!complete.ok || complete.value.status !== "section")
|
|
throw new Error("Expected the complete parent section");
|
|
expect(complete.value.content).toHaveLength(root?.content_length ?? -1);
|
|
expect(complete.value.content).toContain("### Step beta");
|
|
});
|
|
|
|
it("separates a parent's own terms from those found in one subsection", async () => {
|
|
const [combined, ...rest] = await matchesFor("recovery alphaword");
|
|
expect(rest).toEqual([]);
|
|
expect(combined).toMatchObject({
|
|
heading: "Combined recovery",
|
|
match_scope: "subsections",
|
|
own_text_terms: ["recovery"],
|
|
});
|
|
expect(combined?.subsections?.map(({ heading }) => heading)).toEqual([
|
|
"Step alpha",
|
|
]);
|
|
});
|
|
|
|
it("ranks co-located terms before broader matches and treats heading words as own text", async () => {
|
|
const matches = await matchesFor("alphaword betaword");
|
|
expect(matches.map(({ heading }) => heading)).toEqual(["Combined recovery"]);
|
|
expect(await matchesFor("apple resources")).toEqual([
|
|
expect.objectContaining({
|
|
heading: "Apple app resources",
|
|
match_scope: "section",
|
|
}),
|
|
]);
|
|
// The scattered parent has a heading term and the higher score.
|
|
const focusedFirst = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: "recovery alphaword" },
|
|
async (path) =>
|
|
path === "SKILL.md"
|
|
? "# REA\n\n## Focused\n\nThe alphaword recovery recipe.\n"
|
|
: nestedReader(path),
|
|
new ArtifactResourceScope(),
|
|
),
|
|
);
|
|
if (focusedFirst.status !== "matches") throw new Error("Expected matches");
|
|
expect(
|
|
focusedFirst.matches.map(({ heading, match_scope }) => [
|
|
heading,
|
|
match_scope,
|
|
]),
|
|
).toEqual([
|
|
["Focused", "section"],
|
|
["Combined recovery", "subsections"],
|
|
]);
|
|
});
|
|
|
|
it("bounds subsection pointers and counts the remainder", async () => {
|
|
const terms = Array.from({ length: 10 }, (_, index) => `scatterterm${index}`);
|
|
const guide = [
|
|
"# Scattered",
|
|
"",
|
|
...terms.flatMap((term, index) => [`## Part ${index}`, "", term, ""]),
|
|
].join("\n");
|
|
const result = await valueOf(
|
|
searchGuidanceWithReader(
|
|
{ query: terms.join(" ") },
|
|
async (path) => (path === "SKILL.md" ? guide : `# ${path}\n`),
|
|
new ArtifactResourceScope(),
|
|
),
|
|
);
|
|
if (result.status !== "matches") throw new Error("Expected matches");
|
|
expect(result.matches).toHaveLength(1);
|
|
expect(result.matches[0]?.subsections).toHaveLength(8);
|
|
expect(result.matches[0]?.omitted_subsections).toBe(2);
|
|
});
|