contextlock 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
agentbom/registry.py ADDED
@@ -0,0 +1,120 @@
1
+ import re
2
+ from dataclasses import dataclass
3
+ from typing import Literal
4
+
5
+ from pathspec.patterns.gitignore.basic import GitIgnoreBasicPattern
6
+
7
+ from agentbom.models import Agent, ScriptLanguage
8
+
9
+ Format = Literal[
10
+ "mcp_json",
11
+ "vscode_mcp_json",
12
+ "claude_settings_json",
13
+ "nested_hooks_json",
14
+ "cursor_hooks_json",
15
+ "copilot_hooks_json",
16
+ "skill_md",
17
+ "rules_md",
18
+ "script",
19
+ ]
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class SourcePattern:
24
+ pattern: str
25
+ format: Format
26
+ agents: tuple[Agent, ...]
27
+
28
+
29
+ _CLAUDE_HOOK_AGENTS: tuple[Agent, ...] = ("claude_code", "cursor", "copilot")
30
+ _CLAUDE_SKILL_AGENTS: tuple[Agent, ...] = ("claude_code", "cursor", "vscode")
31
+ _AGENTS_SKILL_AGENTS: tuple[Agent, ...] = ("codex", "cursor")
32
+
33
+ SCRIPT_LANGUAGES: dict[str, ScriptLanguage] = {
34
+ ".sh": "shell",
35
+ ".bash": "shell",
36
+ ".zsh": "shell",
37
+ ".ps1": "powershell",
38
+ ".psm1": "powershell",
39
+ ".py": "python",
40
+ ".js": "javascript",
41
+ ".mjs": "javascript",
42
+ ".cjs": "javascript",
43
+ ".ts": "typescript",
44
+ ".mts": "typescript",
45
+ ".cts": "typescript",
46
+ ".rb": "ruby",
47
+ ".pl": "perl",
48
+ ".bat": "batch",
49
+ ".cmd": "batch",
50
+ }
51
+
52
+ # Directories whose scripts an agent runs, with the agents of the config row that runs them.
53
+ _SCRIPT_DIRECTORIES: tuple[tuple[str, tuple[Agent, ...]], ...] = (
54
+ (".claude/hooks/**/", _CLAUDE_HOOK_AGENTS),
55
+ (".cursor/hooks/**/", ("cursor",)),
56
+ (".codex/hooks/**/", ("codex",)),
57
+ (".github/hooks/**/", ("copilot",)),
58
+ ("**/.claude/skills/*/**/", _CLAUDE_SKILL_AGENTS),
59
+ (".agents/skills/*/**/", _AGENTS_SKILL_AGENTS),
60
+ (".cursor/skills/*/**/", ("cursor",)),
61
+ (".github/skills/*/**/", ("copilot",)),
62
+ )
63
+
64
+
65
+ def _script_rows() -> tuple[SourcePattern, ...]:
66
+ # gitwildmatch has no brace expansion, so each directory and extension is its own row.
67
+ return tuple(
68
+ SourcePattern(f"{directory}*{extension}", "script", agents)
69
+ for directory, agents in _SCRIPT_DIRECTORIES
70
+ for extension in SCRIPT_LANGUAGES
71
+ )
72
+
73
+
74
+ REGISTRY: tuple[SourcePattern, ...] = (
75
+ SourcePattern(".mcp.json", "mcp_json", ("claude_code", "vscode")),
76
+ SourcePattern(".cursor/mcp.json", "mcp_json", ("cursor",)),
77
+ SourcePattern(".vscode/mcp.json", "vscode_mcp_json", ("vscode",)),
78
+ SourcePattern(".claude/settings.json", "claude_settings_json", _CLAUDE_HOOK_AGENTS),
79
+ SourcePattern(".claude/settings.local.json", "claude_settings_json", _CLAUDE_HOOK_AGENTS),
80
+ SourcePattern(".codex/hooks.json", "nested_hooks_json", ("codex",)),
81
+ SourcePattern(".cursor/hooks.json", "cursor_hooks_json", ("cursor",)),
82
+ SourcePattern(".github/hooks/*.json", "copilot_hooks_json", ("copilot",)),
83
+ SourcePattern("**/.claude/skills/*/SKILL.md", "skill_md", _CLAUDE_SKILL_AGENTS),
84
+ SourcePattern(".agents/skills/*/SKILL.md", "skill_md", _AGENTS_SKILL_AGENTS),
85
+ SourcePattern(".cursor/skills/*/SKILL.md", "skill_md", ("cursor",)),
86
+ SourcePattern(".github/skills/*/SKILL.md", "skill_md", ("copilot",)),
87
+ SourcePattern("**/.claude/rules/**/*.md", "rules_md", ("claude_code", "vscode")),
88
+ SourcePattern(".claude/commands/**/*.md", "rules_md", ("claude_code",)),
89
+ SourcePattern(".claude/agents/**/*.md", "rules_md", ("claude_code",)),
90
+ SourcePattern("**/AGENTS.md", "rules_md", ("agents_md",)),
91
+ SourcePattern("**/CLAUDE.md", "rules_md", ("claude_code",)),
92
+ SourcePattern("**/CLAUDE.local.md", "rules_md", ("claude_code",)),
93
+ SourcePattern(".cursorrules", "rules_md", ("cursor",)),
94
+ SourcePattern("**/.cursor/rules/**/*.mdc", "rules_md", ("cursor",)),
95
+ SourcePattern(".github/copilot-instructions.md", "rules_md", ("copilot",)),
96
+ SourcePattern(".github/instructions/**/*.instructions.md", "rules_md", ("copilot",)),
97
+ SourcePattern(".github/prompts/**/*.prompt.md", "rules_md", ("vscode",)),
98
+ SourcePattern(".github/agents/**/*.md", "rules_md", ("copilot",)),
99
+ *_script_rows(),
100
+ )
101
+
102
+
103
+ def _compile(pattern: str) -> re.Pattern[str]:
104
+ anchored = pattern if pattern.startswith("**/") else f"/{pattern}"
105
+ regex = GitIgnoreBasicPattern(anchored).regex
106
+ if regex is None:
107
+ raise ValueError(f"registry pattern {pattern!r} matches nothing")
108
+ return regex
109
+
110
+
111
+ _COMPILED = tuple((row, _compile(row.pattern)) for row in REGISTRY)
112
+
113
+
114
+ def match_source(path: str) -> SourcePattern | None:
115
+ # fullmatch, because a gitignore pattern also matches every path under a
116
+ # directory of the same name, and only the file itself is a source.
117
+ for row, regex in _COMPILED:
118
+ if regex.fullmatch(path):
119
+ return row
120
+ return None
agentbom/report.py ADDED
@@ -0,0 +1,237 @@
1
+ import json
2
+ import re
3
+ import unicodedata
4
+ from typing import Any
5
+
6
+ from pydantic import JsonValue
7
+ from rich.console import Console
8
+ from rich.table import Table
9
+ from rich.text import Text
10
+
11
+ from agentbom.lockfile import LOCKFILE_NAME
12
+ from agentbom.models import (
13
+ Artifact,
14
+ Drift,
15
+ FieldChange,
16
+ Finding,
17
+ Hook,
18
+ McpServer,
19
+ RemoteLaunch,
20
+ ScanResult,
21
+ Script,
22
+ Settings,
23
+ Severity,
24
+ StdioLaunch,
25
+ )
26
+ from agentbom.policy import POLICY_FILENAME
27
+
28
+ SCHEMA_VERSION = 4
29
+ _SEVERITY_LABELS: dict[Severity, str] = {"high": "HIGH", "medium": "MED", "low": "LOW"}
30
+ _INVISIBLE_CATEGORIES = frozenset({"Cc", "Cf", "Co", "Cs", "Zl", "Zp"})
31
+ _BACKTICK_RUNS = re.compile("`+")
32
+
33
+
34
+ def render_json(result: ScanResult) -> str:
35
+ document = {
36
+ "schema_version": SCHEMA_VERSION,
37
+ "artifacts": [_artifact_document(artifact) for artifact in result.artifacts],
38
+ "drift": [item.model_dump(mode="json") for item in result.drift],
39
+ "policy_notes": list(result.policy_notes),
40
+ "suppressed": [item.model_dump(mode="json") for item in result.suppressed],
41
+ "errors": [error.model_dump(mode="json") for error in result.errors],
42
+ "findings": [finding.model_dump(mode="json") for finding in result.findings],
43
+ }
44
+ return json.dumps(document, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
45
+
46
+
47
+ def _artifact_document(artifact: Artifact) -> dict[str, Any]:
48
+ # Secrets live in env and header values, so only their keys leave the scanner.
49
+ match artifact:
50
+ case McpServer(launch=StdioLaunch() as launch):
51
+ document = artifact.model_dump(mode="json", exclude={"launch": {"env"}})
52
+ document["launch"]["env_keys"] = sorted(launch.env)
53
+ case McpServer(launch=RemoteLaunch() as launch):
54
+ document = artifact.model_dump(mode="json", exclude={"launch": {"headers"}})
55
+ document["launch"]["header_keys"] = sorted(launch.headers)
56
+ case Settings(env=env):
57
+ document = artifact.model_dump(mode="json", exclude={"env"})
58
+ document["env_keys"] = sorted(env)
59
+ case Hook():
60
+ document = artifact.model_dump(mode="json")
61
+ case _:
62
+ document = artifact.model_dump(mode="json", exclude={"body"})
63
+ document["id"] = artifact.id
64
+ document["content_hash"] = artifact.content_hash
65
+ return document
66
+
67
+
68
+ def summary_line(result: ScanResult) -> str:
69
+ counts = dict.fromkeys(("mcp_server", "skill", "hook", "rules", "script", "settings"), 0)
70
+ for artifact in result.artifacts:
71
+ counts[artifact.kind] += 1
72
+ return "Found: " + ", ".join(
73
+ [
74
+ _count(counts["mcp_server"], "MCP server"),
75
+ _count(counts["skill"], "skill"),
76
+ _count(counts["hook"], "hook"),
77
+ _count(counts["rules"], "rules file"),
78
+ _count(counts["script"], "script"),
79
+ _count(counts["settings"], "settings file"),
80
+ ]
81
+ )
82
+
83
+
84
+ def print_terminal(result: ScanResult, out: Console, err: Console, *, drift: bool) -> None:
85
+ out.print(Text(summary_line(result)), soft_wrap=True)
86
+ if result.artifacts:
87
+ table = Table()
88
+ for header in ("Kind", "Name", "Path", "Agents", "Detail"):
89
+ table.add_column(header, overflow="fold")
90
+ for artifact in result.artifacts:
91
+ table.add_row(
92
+ *(
93
+ Text(_visible(cell))
94
+ for cell in (
95
+ artifact.kind,
96
+ artifact.name,
97
+ artifact.source.path,
98
+ ", ".join(artifact.agents),
99
+ _detail(artifact),
100
+ )
101
+ )
102
+ )
103
+ out.print(table)
104
+ for line in body_lines(result, drift=drift):
105
+ out.print(Text(_visible(line)), soft_wrap=True)
106
+ print_errors(result, err)
107
+
108
+
109
+ def body_lines(result: ScanResult, *, drift: bool) -> list[str]:
110
+ """What the terminal and Markdown reports say after the inventory."""
111
+ lines = [finding_line(finding) for finding in result.findings]
112
+ lines.append(findings_total(result))
113
+ if result.suppressed:
114
+ count = len(result.suppressed)
115
+ noun = "finding" if count == 1 else "findings"
116
+ lines.append(f"{count} {noun} suppressed by {POLICY_FILENAME}.")
117
+ lines.extend(f"policy: {note}" for note in result.policy_notes)
118
+ if drift:
119
+ lines.extend(drift_lines(result.drift))
120
+ return lines
121
+
122
+
123
+ def render_markdown(result: ScanResult, *, command: str, drift: bool) -> str:
124
+ """A heading and one code block, so nothing from the repository renders as Markdown."""
125
+ lines = [summary_line(result), *body_lines(result, drift=drift)]
126
+ lines += [f"error: {error.path}: {error.message}" for error in result.errors]
127
+ text = "\n".join(_visible(line) for line in lines)
128
+ longest = max((len(run) for run in _BACKTICK_RUNS.findall(text)), default=0)
129
+ fence = "`" * max(3, longest + 1)
130
+ return f"### agentbom {command}: {_status(result)}\n\n{fence}text\n{text}\n{fence}\n"
131
+
132
+
133
+ def _status(result: ScanResult) -> str:
134
+ if result.errors:
135
+ return f"{len(result.errors)} error(s), so the result cannot be trusted"
136
+ return findings_total(result).removesuffix(".")
137
+
138
+
139
+ def print_errors(result: ScanResult, err: Console) -> None:
140
+ if result.errors:
141
+ err.print(Text(f"{len(result.errors)} error(s):"))
142
+ for error in result.errors:
143
+ err.print(Text(_visible(f"{error.path}: {error.message}")))
144
+
145
+
146
+ def drift_lines(drift: tuple[Drift, ...]) -> list[str]:
147
+ """The readable diff between the lockfile and the repository, ending in a total."""
148
+ lines: list[str] = []
149
+ for item in drift:
150
+ lines.append(f"{item.change.upper():<8} {item.artifact_id}")
151
+ for change in item.fields:
152
+ lines.extend(_field_lines(change))
153
+ if not drift:
154
+ return [*lines, f"No drift from {LOCKFILE_NAME}."]
155
+ noun = "difference" if len(drift) == 1 else "differences"
156
+ return [*lines, f"{len(drift)} {noun} from {LOCKFILE_NAME}."]
157
+
158
+
159
+ def _field_lines(change: FieldChange) -> list[str]:
160
+ if change.hidden:
161
+ note = "only a digest is locked; review the file's diff"
162
+ return [f" {change.field}: {change.change} ({note})"]
163
+ lines = [f" {change.field}:"]
164
+ if change.change != "added":
165
+ lines.extend(_value_lines("-", change.before))
166
+ if change.change != "removed":
167
+ lines.extend(_value_lines("+", change.after))
168
+ return lines
169
+
170
+
171
+ def _value_lines(mark: str, value: JsonValue) -> list[str]:
172
+ # A string prints raw unless it reads as JSON, so "false" and false never look alike.
173
+ if isinstance(value, str) and not _reads_as_json(value):
174
+ text = value
175
+ else:
176
+ text = json.dumps(value, ensure_ascii=False)
177
+ return [f" {mark} {line}" for line in text.split("\n")]
178
+
179
+
180
+ def _reads_as_json(text: str) -> bool:
181
+ try:
182
+ json.loads(text)
183
+ except (ValueError, RecursionError):
184
+ return False
185
+ return True
186
+
187
+
188
+ def finding_line(finding: Finding) -> str:
189
+ where = finding.location.path
190
+ if finding.location.line is not None:
191
+ where = f"{where}:{finding.location.line}"
192
+ return f"{_SEVERITY_LABELS[finding.severity]:<4} {finding.rule_id} {where} {finding.message}"
193
+
194
+
195
+ def findings_total(result: ScanResult) -> str:
196
+ if not result.findings:
197
+ return "No findings."
198
+ counts = dict.fromkeys(_SEVERITY_LABELS, 0)
199
+ for finding in result.findings:
200
+ counts[finding.severity] += 1
201
+ noun = "finding" if len(result.findings) == 1 else "findings"
202
+ return (
203
+ f"{len(result.findings)} {noun} "
204
+ f"({counts['high']} high, {counts['medium']} medium, {counts['low']} low)."
205
+ )
206
+
207
+
208
+ def _detail(artifact: Artifact) -> str:
209
+ match artifact:
210
+ case McpServer(launch=StdioLaunch(command=command)):
211
+ return command
212
+ case McpServer(launch=RemoteLaunch(url=url)):
213
+ return url
214
+ case Hook(commands=commands, url=url, handler_type=handler_type):
215
+ return next(iter(commands.values()), url or handler_type)
216
+ case Script(language=language):
217
+ return language
218
+ case _:
219
+ return ""
220
+
221
+
222
+ def _count(n: int, noun: str) -> str:
223
+ return f"{n} {noun}" if n == 1 else f"{n} {noun}s"
224
+
225
+
226
+ def _visible(text: str) -> str:
227
+ # Repo files are untrusted: escape control and format characters (ANSI
228
+ # escapes, bidi overrides, zero-width text) instead of sending them to a terminal.
229
+ return "".join(
230
+ _escape(char) if unicodedata.category(char) in _INVISIBLE_CATEGORIES else char
231
+ for char in text
232
+ )
233
+
234
+
235
+ def _escape(char: str) -> str:
236
+ code = ord(char)
237
+ return f"\\u{code:04x}" if code <= 0xFFFF else f"\\U{code:08x}"
@@ -0,0 +1,51 @@
1
+ from collections.abc import Iterable, Sequence
2
+ from typing import Protocol
3
+
4
+ from agentbom.models import SEVERITY_RANK, Artifact, Drift, Finding, RuleId
5
+ from agentbom.rules.abom_001_hidden_unicode import HiddenUnicode
6
+ from agentbom.rules.abom_002_remote_exec import RemoteScriptExecution
7
+ from agentbom.rules.abom_003_credential_paths import CredentialPathAccess
8
+ from agentbom.rules.abom_004_outbound_transfer import OutboundDataTransfer
9
+ from agentbom.rules.abom_005_unpinned import UnpinnedServer
10
+ from agentbom.rules.abom_006_drift import drift_findings
11
+ from agentbom.rules.abom_007_permissions import OverBroadPermissions
12
+ from agentbom.rules.abom_008_auto_run_hooks import AutoRunHooks
13
+ from agentbom.rules.abom_009_instruction_override import InstructionOverride
14
+ from agentbom.rules.abom_010_secrets import EmbeddedSecrets
15
+
16
+
17
+ class Rule(Protocol):
18
+ @property
19
+ def rule_id(self) -> RuleId: ...
20
+
21
+ def run(self, artifacts: Sequence[Artifact]) -> Iterable[Finding]: ...
22
+
23
+
24
+ RULES: tuple[Rule, ...] = (
25
+ HiddenUnicode(),
26
+ RemoteScriptExecution(),
27
+ CredentialPathAccess(),
28
+ OutboundDataTransfer(),
29
+ UnpinnedServer(),
30
+ OverBroadPermissions(),
31
+ AutoRunHooks(),
32
+ InstructionOverride(),
33
+ EmbeddedSecrets(),
34
+ )
35
+
36
+
37
+ def run_rules(artifacts: Sequence[Artifact], drift: Sequence[Drift] = ()) -> tuple[Finding, ...]:
38
+ findings = [finding for rule in RULES for finding in rule.run(artifacts)]
39
+ findings.extend(drift_findings(drift))
40
+ return tuple(sorted(findings, key=_finding_key))
41
+
42
+
43
+ def _finding_key(finding: Finding) -> tuple[int, str, str, int, str, str]:
44
+ return (
45
+ -SEVERITY_RANK[finding.severity],
46
+ finding.rule_id,
47
+ finding.location.path,
48
+ finding.location.line or 0,
49
+ finding.message,
50
+ finding.artifact_id,
51
+ )
@@ -0,0 +1,109 @@
1
+ """Sentences and negation, for rules that judge instructions written in prose."""
2
+
3
+ import re
4
+ from collections.abc import Iterator
5
+ from dataclasses import dataclass
6
+
7
+ from agentbom.rules._surfaces import Surface
8
+
9
+
10
+ @dataclass(frozen=True)
11
+ class Sentence:
12
+ start: int
13
+ text: str
14
+
15
+
16
+ _FENCE = re.compile(r"[ \t]*(?:```|~~~)")
17
+ # A Markdown list item, heading or quote starts a new block; any other line
18
+ # continues the paragraph above it, so a soft-wrapped sentence stays whole.
19
+ _BLOCK_START = re.compile(r"[ \t]*(?:[-*+][ \t]|\d+[.)][ \t]|#|>)")
20
+ _NUMBERED_ITEM = re.compile(r"[ \t]*\d+[.)][ \t]")
21
+ _HEADING = re.compile(r"[ \t]*#")
22
+ _TABLE_ROW = re.compile(r"[ \t]*\|")
23
+ _CELL_BORDER = re.compile(r"(?<!\\)\|")
24
+ _SENTENCE_END = re.compile(r"(?<=[.!?])(?<!\be\.g\.)(?<!\bi\.e\.)(?<!\betc\.)\s+")
25
+ _NEGATION = re.compile(
26
+ r"\b(?:"
27
+ r"(?:never|do\s+not|don['\u2019]t)(?!\s+(?:forget|hesitate|fail)\b)"
28
+ r"|must\s+not|mustn['\u2019]t|should\s+not|shouldn['\u2019]t"
29
+ r"|avoid(?:s|ing)?|refus(?:e|es|ing)|den(?:y|ies|ied)"
30
+ r"|not\s+allowed|prohibited|forbidden"
31
+ r"|without(?!\s+(?:asking|telling|notifying|informing|alerting|mentioning|showing"
32
+ r"|confirming|prompting|letting)\b)"
33
+ r")\b",
34
+ re.IGNORECASE,
35
+ )
36
+
37
+
38
+ def sentences(text: str) -> Iterator[Sentence]:
39
+ """Sentences of Markdown prose, each with its offset in `text`.
40
+
41
+ Paragraphs split on `.`, `!` or `?` before whitespace; list items, headings,
42
+ table cells and lines of a code block are sentences of their own.
43
+ """
44
+ for start, end in _blocks(text):
45
+ block = text[start:end]
46
+ cursor = 0
47
+ marker = _NUMBERED_ITEM.match(block)
48
+ for boundary in _SENTENCE_END.finditer(block, marker.end() if marker else 0):
49
+ yield from _trimmed(text, start + cursor, start + boundary.start())
50
+ cursor = boundary.end()
51
+ yield from _trimmed(text, start + cursor, end)
52
+
53
+
54
+ def negated(sentence: str) -> bool:
55
+ return _NEGATION.search(sentence) is not None
56
+
57
+
58
+ def regions(surface: Surface) -> Iterator[Sentence]:
59
+ """The parts of a surface a rule searches: all of a command or value, or each
60
+ prose sentence that does not negate what it says."""
61
+ if surface.context in ("skill_prose", "rules_prose"):
62
+ yield from (s for s in sentences(surface.text) if not negated(s.text))
63
+ else:
64
+ yield Sentence(0, surface.text)
65
+
66
+
67
+ def _blocks(text: str) -> Iterator[tuple[int, int]]:
68
+ open_start: int | None = None
69
+ open_end = 0
70
+ in_fence = False
71
+ offset = 0
72
+ for line in text.splitlines(keepends=True):
73
+ start, offset = offset, offset + len(line)
74
+ end = start + len(line.rstrip("\r\n"))
75
+ fence = _FENCE.match(line) is not None
76
+ standalone = fence or in_fence or not line.strip() or _TABLE_ROW.match(line)
77
+ if open_start is not None and (standalone or _BLOCK_START.match(line)):
78
+ yield open_start, open_end
79
+ open_start = None
80
+ if fence:
81
+ in_fence = not in_fence
82
+ elif in_fence:
83
+ yield start, end
84
+ elif _TABLE_ROW.match(line):
85
+ yield from _cells(line, start, end)
86
+ elif line.strip():
87
+ if open_start is None:
88
+ open_start = start
89
+ open_end = end
90
+ if _HEADING.match(line):
91
+ yield open_start, open_end
92
+ open_start = None
93
+ if open_start is not None:
94
+ yield open_start, open_end
95
+
96
+
97
+ def _cells(line: str, start: int, end: int) -> Iterator[tuple[int, int]]:
98
+ cursor = start
99
+ for border in _CELL_BORDER.finditer(line, 0, end - start):
100
+ yield cursor, start + border.start()
101
+ cursor = start + border.end()
102
+ yield cursor, end
103
+
104
+
105
+ def _trimmed(text: str, start: int, end: int) -> Iterator[Sentence]:
106
+ chunk = text[start:end]
107
+ stripped = chunk.strip()
108
+ if stripped:
109
+ yield Sentence(start + len(chunk) - len(chunk.lstrip()), stripped)
@@ -0,0 +1,92 @@
1
+ """The text each artifact exposes to text rules, and the context that text runs in."""
2
+
3
+ from collections.abc import Iterator, Mapping
4
+ from dataclasses import dataclass
5
+ from typing import Literal, assert_never
6
+
7
+ from agentbom.models import (
8
+ Artifact,
9
+ Hook,
10
+ McpServer,
11
+ RemoteLaunch,
12
+ Rules,
13
+ Script,
14
+ Settings,
15
+ Severity,
16
+ Skill,
17
+ StdioLaunch,
18
+ )
19
+
20
+ # executable: runs as a command or program. config: a value an agent passes to a
21
+ # server or process. skill_prose / rules_prose: instructions an agent reads.
22
+ Context = Literal["executable", "config", "skill_prose", "rules_prose"]
23
+
24
+ # A rule rates each context it applies to; a context missing from its table is skipped.
25
+ SeverityTable = Mapping[Context, Severity]
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class Surface:
30
+ artifact: Artifact
31
+ context: Context
32
+ field: str
33
+ text: str
34
+ line: int | None
35
+
36
+
37
+ def surfaces(artifact: Artifact) -> Iterator[Surface]:
38
+ match artifact:
39
+ case McpServer():
40
+ yield from _server_surfaces(artifact)
41
+ case Hook():
42
+ for shell, command in artifact.commands.items():
43
+ yield Surface(artifact, "executable", f"commands.{shell}", command, None)
44
+ if artifact.url is not None:
45
+ yield Surface(artifact, "config", "url", artifact.url, None)
46
+ case Script():
47
+ yield Surface(artifact, "executable", "body", artifact.body, 1)
48
+ case Skill():
49
+ if artifact.description is not None:
50
+ yield Surface(artifact, "skill_prose", "description", artifact.description, None)
51
+ yield Surface(artifact, "skill_prose", "body", artifact.body, artifact.body_line)
52
+ case Rules():
53
+ yield Surface(artifact, "rules_prose", "body", artifact.body, artifact.body_line)
54
+ case Settings():
55
+ for key, value in artifact.env.items():
56
+ yield Surface(artifact, "config", f"env.{key}", value, None)
57
+ case _:
58
+ assert_never(artifact)
59
+
60
+
61
+ def _server_surfaces(server: McpServer) -> Iterator[Surface]:
62
+ launch = server.launch
63
+ match launch:
64
+ case StdioLaunch():
65
+ command = " ".join((launch.command, *launch.args))
66
+ yield Surface(server, "executable", "command", command, None)
67
+ for key, value in launch.env.items():
68
+ yield Surface(server, "config", f"env.{key}", value, None)
69
+ case RemoteLaunch():
70
+ yield Surface(server, "config", "url", launch.url, None)
71
+ for key, value in launch.headers.items():
72
+ yield Surface(server, "config", f"headers.{key}", value, None)
73
+ case _:
74
+ assert_never(launch)
75
+
76
+
77
+ def field_label(surface: Surface) -> str:
78
+ """The surface's field, prefixed with its artifact's name when one file holds several."""
79
+ match surface.artifact:
80
+ case McpServer():
81
+ return f'server "{surface.artifact.name}" {surface.field}'
82
+ case Hook():
83
+ return f"hook {surface.artifact.name} {surface.field}"
84
+ case _:
85
+ return surface.field
86
+
87
+
88
+ def line_of(surface: Surface, offset: int) -> int | None:
89
+ """The file line of the character at `offset` in `surface.text`, when the surface has one."""
90
+ if surface.line is None:
91
+ return None
92
+ return surface.line + surface.text.count("\n", 0, offset)