Skip to content

Commit 9af9f7d

Browse files
fix: strip leading BOM before SKILL.md frontmatter detection (#471)
* fix(build_context): strip leading BOMs before manifest frontmatter detection decode_text() decodes with plain utf-8, which never strips a byte-order mark, so a BOM-prefixed SKILL.md left content[0] == U+FEFF and the content.startswith("---") sniff in _parse_manifest returned an empty manifest. Every manifest-gated analyzer then early-exits as not_applicable/manifest_absent, so LP1-LP4 and TP1-TP4 stop contributing findings for that skill. Strip leading BOMs in a loop, scoped to delimiter detection. decode_text() itself is left alone because P2/TP1/P9 treat U+FEFF in file bodies as a hidden-character injection signal. Signed-off-by: Mohammed Alkindi <[email protected]> * fix(multi_skill): strip leading BOM before raw-byte frontmatter sniff _extract_skill_name checks prefix.startswith(b"---") on raw bytes before decoding, so a BOM-prefixed sub-skill fell through to the fallback and was listed under its directory name instead of the name: declared in its frontmatter. Byte-level counterpart to the same strip in build_context._parse_manifest. Signed-off-by: Mohammed Alkindi <[email protected]> * fix(excessive_agency): match leading BOM in SKILL.md frontmatter bounds _frontmatter_bounds anchored on \A---, so a BOM-prefixed SKILL.md returned None and EA5 silently reported no frontmatter model pin. This is the third frontmatter sniff in the same class as the two already fixed on this branch. The BOM is absorbed into the opening match rather than stripped, because the offsets this function returns index the caller's original content: _ea5_findings slices it and derives line numbers and context from it, so removing characters would shift every reported position by one. Signed-off-by: Narendran Raghavan <[email protected]> --------- Signed-off-by: Mohammed Alkindi <[email protected]> Signed-off-by: Narendran Raghavan <[email protected]>
1 parent 83bc10c commit 9af9f7d

6 files changed

Lines changed: 108 additions & 1 deletion

File tree

‎src/skillspector/multi_skill.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,11 @@ def _extract_skill_name(skill_dir: Path, *, budget: _DetectionBudget) -> str:
540540
raise _read_error("multi_skill_manifest_content") from exc
541541

542542
prefix = observed[:MAX_MULTI_SKILL_MANIFEST_FRONTMATTER_BYTES]
543+
while prefix.startswith(b"\xef\xbb\xbf"):
544+
# Byte-level counterpart to the BOM strip in build_context._parse_manifest:
545+
# this sniff runs on raw bytes before decode, so a BOM-prefixed SKILL.md
546+
# would otherwise fall through to `fallback` (the directory name) below.
547+
prefix = prefix[3:]
543548
if not prefix.startswith(b"---"):
544549
return fallback
545550
content = prefix.decode("utf-8", errors="replace")

‎src/skillspector/nodes/analyzers/static_patterns_excessive_agency.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,10 @@ def _frontmatter_bounds(content: str, file_path: str) -> tuple[int, int] | None:
196196
"""Return the YAML-frontmatter byte offsets for a SKILL.md file."""
197197
if file_path.rsplit("/", 1)[-1].lower() != "skill.md":
198198
return None
199-
opening = re.match(r"\A---[ \t]*\r?\n", content)
199+
# A leading BOM is matched here rather than stripped: the offsets this
200+
# function returns index the caller's original `content` (line numbers and
201+
# context are derived from it), so removing characters would shift them.
202+
opening = re.match(r"\A\ufeff*---[ \t]*\r?\n", content)
200203
if opening is None:
201204
return None
202205
closing = re.search(r"^---[ \t]*$", content[opening.end() :], re.MULTILINE)

‎src/skillspector/nodes/build_context.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2405,6 +2405,15 @@ def _check_runtime() -> None:
24052405
runtime_limit=runtime_limit,
24062406
)
24072407
return {}
2408+
while content.startswith("\ufeff"):
2409+
# decode_text() decodes with plain "utf-8", which never strips a
2410+
# leading byte-order mark (only "utf-8-sig" does), so a BOM-prefixed
2411+
# SKILL.md leaves content[0] == "\ufeff" and the delimiter check below
2412+
# silently sees {} instead of the frontmatter. Strip leading BOMs here,
2413+
# scoped to delimiter detection — decode_text() itself stays untouched
2414+
# because P2/TP1/P9 treat U+FEFF as a hidden-character injection signal
2415+
# in file bodies.
2416+
content = content[1:]
24082417
if not content.startswith("---"):
24092418
return {}
24102419
end_match = re.search(r"\n---\s*\n", content[3:])

‎tests/nodes/test_build_context.py‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -837,6 +837,55 @@ def test_build_context_skill_md_lowercase(tmp_path: Path) -> None:
837837
assert "references/guide.md" in result["components"]
838838

839839

840+
def test_build_context_parses_manifest_with_utf8_bom(tmp_path: Path) -> None:
841+
"""A leading UTF-8 BOM before the frontmatter delimiter must not blank the manifest.
842+
843+
Regression guard: ``decode_text()`` decodes with plain "utf-8", which does not
844+
strip a leading byte-order mark (only "utf-8-sig" does), so
845+
``content[0] == "\\ufeff"`` and the naive ``content.startswith("---")`` check in
846+
``_parse_manifest`` used to fail silently, returning ``{}`` with no ledger record.
847+
"""
848+
(tmp_path / "SKILL.md").write_bytes(
849+
b"\xef\xbb\xbf---\nname: bom-skill\ndescription: has a leading BOM\n---\n# Skill\n"
850+
)
851+
state: SkillspectorState = {"skill_path": str(tmp_path)}
852+
result = build_context(state)
853+
854+
assert result["manifest"]["name"] == "bom-skill"
855+
assert result["manifest"]["description"] == "has a leading BOM"
856+
857+
858+
def test_build_context_parses_manifest_without_bom_identically(tmp_path: Path) -> None:
859+
"""Regression guard: the BOM-free sibling of the fixture above parses identically."""
860+
(tmp_path / "SKILL.md").write_bytes(
861+
b"---\nname: bom-skill\ndescription: has a leading BOM\n---\n# Skill\n"
862+
)
863+
state: SkillspectorState = {"skill_path": str(tmp_path)}
864+
result = build_context(state)
865+
866+
assert result["manifest"]["name"] == "bom-skill"
867+
assert result["manifest"]["description"] == "has a leading BOM"
868+
869+
870+
def test_build_context_parses_manifest_with_stacked_utf8_bom(tmp_path: Path) -> None:
871+
"""A doubled leading BOM must not reproduce the original silent ``{}`` manifest.
872+
873+
Regression guard: the single-strip fix (``if content.startswith("\\ufeff")``)
874+
only removes one BOM, so ``content[0] == "\\ufeff"`` again after the strip and
875+
``content.startswith("---")`` still fails on a stacked BOM. ``_parse_manifest``
876+
strips leading BOMs in a loop so repeated markers are all removed.
877+
"""
878+
(tmp_path / "SKILL.md").write_bytes(
879+
b"\xef\xbb\xbf\xef\xbb\xbf---\nname: stacked-bom-skill\ndescription: doubled BOM\n"
880+
b"---\n# Skill\n"
881+
)
882+
state: SkillspectorState = {"skill_path": str(tmp_path)}
883+
result = build_context(state)
884+
885+
assert result["manifest"]["name"] == "stacked-bom-skill"
886+
assert result["manifest"]["description"] == "doubled BOM"
887+
888+
840889
def test_build_context_parses_manifest_from_cached_snapshot_after_file_disappears(
841890
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
842891
) -> None:

‎tests/test_multi_skill.py‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,32 @@ def test_skill_names_extracted_from_frontmatter(self, multi_skill_dir: Path) ->
128128
names = {s.name for s in result.skills}
129129
assert names == {"weather-lookup", "email-sender", "file-manager"}
130130

131+
def test_skill_name_extracted_from_bom_prefixed_frontmatter(self, tmp_path: Path) -> None:
132+
"""A BOM-prefixed sub-skill resolves to its declared `name:`, not the directory name.
133+
134+
Regression guard: `_extract_skill_name` sniffs raw bytes for a leading
135+
`b"---"` before decoding. A UTF-8 BOM (`b"\\xef\\xbb\\xbf"`) in front of that
136+
delimiter used to defeat the sniff and silently fall back to `skill_dir.name`
137+
instead of the frontmatter's declared name.
138+
"""
139+
clean_dir = tmp_path / "clean-skill"
140+
clean_dir.mkdir()
141+
(clean_dir / "SKILL.md").write_bytes(
142+
b"---\nname: clean-declared-name\ndescription: no BOM\n---\n# Clean\n"
143+
)
144+
145+
bom_dir = tmp_path / "bom-dir-name"
146+
bom_dir.mkdir()
147+
(bom_dir / "SKILL.md").write_bytes(
148+
b"\xef\xbb\xbf---\nname: bom-declared-name\ndescription: has a BOM\n---\n# BOM\n"
149+
)
150+
151+
result = detect_skills(tmp_path)
152+
153+
names = {s.relative_path: s.name for s in result.skills}
154+
assert names["clean-skill"] == "clean-declared-name"
155+
assert names["bom-dir-name"] == "bom-declared-name"
156+
131157
def test_structured_skill_subdir_detected(self, tmp_path: Path) -> None:
132158
"""An immediate subdirectory with a valid AISOP/AISP bundle is detected."""
133159
sub = tmp_path / "workflow-bundle"

‎tests/unit/test_patterns_new.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,21 @@ def test_ea5_frontmatter_pin_is_medium(self, key: str) -> None:
260260
"selection_key": key,
261261
}
262262

263+
def test_ea5_frontmatter_pin_detected_through_leading_bom(self) -> None:
264+
"""A BOM-prefixed SKILL.md must not hide the frontmatter model pin."""
265+
content = "\ufeff---\nname: example\nmodel: claude-sonnet-4-6\n---\n\n# Example\n"
266+
findings = ea_mod.analyze(content, "SKILL.md", "markdown")
267+
ea5 = [finding for finding in findings if finding.rule_id == "EA5"]
268+
assert len(ea5) == 1
269+
assert ea5[0].severity == Severity.MEDIUM
270+
# The BOM is matched, not stripped, so offsets still index the original
271+
# content and the reported line matches the no-BOM case exactly.
272+
assert ea5[0].location.start_line == 3
273+
assert ea5[0].evidence == {
274+
"selection_surface": "frontmatter",
275+
"selection_key": "model",
276+
}
277+
263278
def test_ea5_frontmatter_identity_uses_the_complete_declaration(self) -> None:
264279
shared = "gpt-" + "a" * 220
265280
findings = [

0 commit comments

Comments
 (0)