Skip to content

Commit dc6d143

Browse files
test(frontmatter): model valid-header acceptance in TLA+ spec (#2465)
Co-authored-by: Elliott de Launay <edelauna@gmail.com>
1 parent 252d9ce commit dc6d143

4 files changed

Lines changed: 45 additions & 23 deletions

File tree

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
SPECIFICATION Spec
2+
CONSTANTS
3+
Variant = "CaseSensitive"
4+
INVARIANTS TypeOK NoExecutableEngine ValidDataAccepted
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
SPECIFICATION Spec
22
CONSTANTS
33
Variant = "Fixed"
4-
INVARIANTS TypeOK NoExecutableEngine
4+
INVARIANTS TypeOK NoExecutableEngine ValidDataAccepted

‎docs/architecture/tla/Frontmatter.tla‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,30 +3,34 @@
33
\* Callers: scanCommandDirectory, tryLoadCommand and SkillsManager (load, read, update). One guard serves all.
44
\* Source: the header language in a workspace command or skill file. Sink: the gray-matter engine call.
55
\* Failure: a file header selects an executable engine and the extension runs its code.
6-
\* Invariant: NoExecutableEngine. gray-matter is an oracle. Only the header language is modeled.
6+
\* Invariants: NoExecutableEngine and ValidDataAccepted. gray-matter is an oracle. Only the header language is modeled.
77
\* Expect: Fixed holds. None fails at once. NoBomStrip fails with a BOM and an executable header.
8-
\* Result: Fixed holds in 6 states. None fails in 1 state. NoBomStrip fails in 1 state, with a BOM.
8+
\* Expect: CaseSensitive fails ValidDataAccepted on an upper-case data header.
9+
\* Result: Fixed holds in 8 states. CaseSensitive fails ValidDataAccepted in 1 state, with upper-case YAML.
10+
\* Result: Before this change, Fixed held in 6 states. None fails in 1 state. NoBomStrip fails in 1 state, with a BOM.
911
\* Replay: gray-matter runs a js header in the real library. The guard in the code stops it.
1012
\* Not modeled: the YAML and JSON parsers. The file body.
1113
\* Cost: TLC runs in under 1 second. Agent time is not measured.
12-
\* Review: 1 covered (bot thread on double BOM, PR 2455), 0 added, 1 gap.
13-
\* Gap: PR 2456 bot thread on uppercase YAML. The spec models safety only, not false rejects. A test covers it.
14+
\* Review: 1 covered (bot thread on double BOM, PR 2455), 1 added, 0 gap.
15+
\* Added: PR 2456 bot thread on uppercase YAML. ValidDataAccepted and the CaseSensitive config model it.
16+
\* Gap: an upper-case JSON header passes the guard. gray-matter then throws "engine not registered". It is a safe false reject. The code is unchanged.
1417
\* Gap: a YAML tag such as !!js/function is not a header language. The spec cannot express it. A test covers it.
1518
\* Replay: two BOMs do not run code in gray-matter. It is a false alarm. A test case stays.
1619
\* Skills: the skill caller is the same input domain. The skill path was unguarded before this change.
1720
\* Property test: src/utils/__tests__/safeFrontmatter.spec.ts. Caller tests: SkillsManager.spec.ts, frontmatter-commands.spec.ts.
1821

19-
CONSTANT Variant \* "Fixed", "None" or "NoBomStrip"
22+
CONSTANT Variant \* "Fixed", "None", "NoBomStrip" or "CaseSensitive"
2023

2124
VARIABLE in
2225

23-
\* "exec" = js or javascript in any case. "data" = yaml, yml, json or no language.
26+
\* "exec" = js or javascript in any case. "data" = yaml, yml, json or no language, lower case.
27+
\* "upper" = yaml or yml with an upper-case letter. gray-matter does not lowercase json.
2428
\* "other" = any other name. gray-matter finds no engine for it.
25-
Inputs == [bom : BOOLEAN, lang : {"data", "exec", "other"}]
29+
Inputs == [bom : BOOLEAN, lang : {"data", "upper", "exec", "other"}]
2630

2731
\* The guard reads the header language. Without the BOM strip it misses the header.
28-
GuardSeesHeader(i) == Variant = "Fixed" \/ (Variant = "NoBomStrip" /\ ~i.bom)
29-
Rejected(i) == GuardSeesHeader(i) /\ i.lang # "data"
32+
GuardSeesHeader(i) == Variant \in {"Fixed", "CaseSensitive"} \/ (Variant = "NoBomStrip" /\ ~i.bom)
33+
Rejected(i) == GuardSeesHeader(i) /\ i.lang # "data" /\ (i.lang # "upper" \/ Variant = "CaseSensitive")
3034
Executed(i) == i.lang = "exec" /\ ~Rejected(i)
3135

3236
TypeOK == in \in Inputs
@@ -38,4 +42,7 @@ Spec == Init /\ [][Next]_in
3842
\* Safety: no input reaches an executable engine.
3943
NoExecutableEngine == ~Executed(in)
4044

45+
\* Liveness of valid files: a data header is never rejected.
46+
ValidDataAccepted == in.lang \in {"data", "upper"} => ~Rejected(in)
47+
4148
====

‎src/services/skills/__tests__/SkillsManager.spec.ts‎

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -218,19 +218,30 @@ describe("SkillsManager", () => {
218218
}
219219
})
220220

221-
it.each(["", "yaml", "json"])("accepts data-only %s metadata in skill operations", async (language) => {
222-
mockDirectoryExists.mockImplementation(async (dir: string) => dir === projectSkillsDir)
223-
mockRealpath.mockImplementation(async (value: string) => value)
224-
mockReaddir.mockImplementation(async (dir: string) => (dir === projectSkillsDir ? ["example"] : []))
225-
mockStat.mockResolvedValue({ isDirectory: () => true })
226-
mockFileExists.mockResolvedValue(true)
227-
const metadata =
228-
language === "json" ? '{"name":"example","description":"Example"}' : "name: example\ndescription: Example"
229-
mockReadFile.mockResolvedValue(`---${language}\n${metadata}\n---\nBody`)
230-
await skillsManager.discoverSkills()
231-
expect(skillsManager.getAllSkills()).toHaveLength(1)
232-
expect((await skillsManager.getSkillContent("example"))?.instructions).toBe("Body")
233-
})
221+
it.each(["", "yaml", "YAML", "yml", "YML", "json"])(
222+
"accepts data-only %s metadata in skill operations",
223+
async (language) => {
224+
const metadata =
225+
language === "json"
226+
? '{"name":"example","description":"Example skill"}'
227+
: "name: example\ndescription: Example skill"
228+
mockDirectoryExists.mockImplementation(async (dir: string) => dir === projectSkillsDir)
229+
mockRealpath.mockImplementation(async (value: string) => value)
230+
mockReaddir.mockImplementation(async (dir: string) => (dir === projectSkillsDir ? ["example"] : []))
231+
mockStat.mockResolvedValue({ isDirectory: () => true })
232+
mockFileExists.mockResolvedValue(true)
233+
mockReadFile.mockResolvedValue(`---${language}\n${metadata}\n---\nInstructions`)
234+
await skillsManager.discoverSkills()
235+
expect(skillsManager.getSkillsMetadata().map((skill) => skill.name)).toEqual(["example"])
236+
expect((await skillsManager.getSkillContent("example"))?.instructions).toBe("Instructions")
237+
await skillsManager.updateSkillModes("example", "project", ["code"])
238+
expect(mockWriteFile).toHaveBeenCalledWith(
239+
p(projectSkillsDir, "example", "SKILL.md"),
240+
expect.stringContaining("modeSlugs:"),
241+
"utf-8",
242+
)
243+
},
244+
)
234245

235246
describe("discoverSkills", () => {
236247
it("should discover skills from global directory", async () => {

0 commit comments

Comments
 (0)