blob: 304aa13f82892d8bd4371516ca9de486be1c4ce8 [file] [edit]
# Copyright 2026 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
"""SHAC checks for SKILL.md skills, dynamic workflows, and .agents configs."""
load("./common.star", "cipd_platform_name", "get_fuchsia_dir", "os_exec")
def _run_skill_linter(ctx, extra_args, rel_files):
exe_interp = "%s/prebuilt/third_party/python3/%s/bin/python3" % (
get_fuchsia_dir(ctx),
cipd_platform_name(ctx),
)
exe_script = "%s/scripts/skill_linter/skill_linter.py" % get_fuchsia_dir(ctx)
file_paths = [ctx.scm.root + "/" + f for f in rel_files]
return os_exec(
ctx,
[exe_interp, exe_script] + extra_args + file_paths,
env = {
"PYTHONPATH": get_fuchsia_dir(ctx) + "/third_party/pyyaml/src/lib",
},
ok_retcodes = [0, 1],
).wait()
def _skill_format(ctx):
"""Validates frontmatter and formats modified SKILL.md files."""
skill_files = ctx.scm.affected_files(glob = ["**/SKILL.md"])
if not skill_files:
return
res = _run_skill_linter(ctx, ["--suggest-fix-in-json"], skill_files)
# Check for failure to produce JSON.
if not res.stdout.strip().startswith("["):
ctx.emit.finding(
level = "error",
message = "Skill linter error:\n%s" % res.stderr,
)
return
findings = json.decode(res.stdout)
for finding in findings:
ctx.emit.finding(
level = finding["level"],
filepath = finding["filepath"],
message = finding["message"],
replacements = finding.get("replacements"),
)
_MAX_SPECIFIED_FILES = 50
def _workflow_manifest_for_path(path):
parts = path.split("/")
for i in range(len(parts) - 2):
if parts[i] in (".agents", "_agents") and parts[i + 1] == "workflows":
return "/".join(parts[:i + 3] + ["workflow.json"])
return None
def _agent_customizations_lint(ctx):
"""Lints skills, saved dynamic workflows, and .agents discovery configs."""
skill_and_json_map = ctx.scm.affected_files(glob = [
"**/SKILL.md",
"**/.agents/agents.json",
"**/.agents/plugins.json",
"**/.agents/rules.json",
"**/.agents/skills.json",
"**/.agents/workflows.json",
"**/_agents/agents.json",
"**/_agents/plugins.json",
"**/_agents/rules.json",
"**/_agents/skills.json",
"**/_agents/workflows.json",
])
workflow_files_map = ctx.scm.affected_files(
glob = [
"**/.agents/workflows/**",
"**/_agents/workflows/**",
],
include_deleted = True,
)
target_files_map = dict(skill_and_json_map)
target_files_map.update(workflow_files_map)
if not target_files_map:
return
# SHAC's `gitCheckout` backend (`shac check` and `shac check --all`) sets a
# non-empty `meta.action` on files modified or deleted in git and `""` on
# untouched tracked files. Passing `include_deleted = True` keeps
# deletion-only CLs git-backed. On a clean checkout (`HEAD == upstream`)
# under `shac check --all`, every tracked file has `meta.action == ""`
# (`git_backed == False`), which is distinguished from `specifiedFiles`
# (`shac check <file>...`) by `len(affected_all) > _MAX_SPECIFIED_FILES`.
affected_all = ctx.scm.affected_files(include_deleted = True)
git_backed = any([m.action for m in affected_all.values()])
modified_files = [f for f, meta in target_files_map.items() if meta.action]
if git_backed:
if not modified_files:
return
target_files = modified_files
else:
if len(affected_all) > _MAX_SPECIFIED_FILES:
return
target_files = list(target_files_map.keys())
deleted_set = set([f for f, m in affected_all.items() if m.action == "D"])
changed_set = (
set([f for f, m in affected_all.items() if m.action and m.action != "D"]) if git_backed else set(affected_all.keys())
)
deleted_wf_manifests = set([
m_path
for f, meta in workflow_files_map.items()
if meta.action == "D"
for m_path in [_workflow_manifest_for_path(f)]
if m_path
])
tracked_set = set(ctx.scm.all_files())
res = _run_skill_linter(
ctx,
[
"--lint-json",
"--repo-root",
ctx.scm.root,
"--fuchsia-root",
get_fuchsia_dir(ctx),
],
target_files,
)
if not res.stdout.strip().startswith("["):
ctx.emit.finding(
level = "error",
message = "Skill and workflow linter error:\n%s" % res.stderr,
)
return
findings = json.decode(res.stdout)
for finding in findings:
filepath = finding["filepath"]
level = finding["level"]
line = finding.get("line")
message = finding["message"]
if filepath in changed_set or (
level == "error" and
filepath in deleted_wf_manifests and
filepath in tracked_set and
filepath not in deleted_set
):
ctx.emit.finding(
level = level,
filepath = filepath,
line = line,
message = message,
)
elif level == "error":
if filepath in tracked_set and filepath not in deleted_set:
# Untouched tracked sibling file in a workflow dir: downgrade
# pre-existing errors to warning consistently across diff and
# `--all` modes while omitting untouched sibling warnings.
ctx.emit.finding(
level = "warning",
filepath = filepath,
line = line,
message = message,
)
else:
# Sibling file in workflow dir is untracked in SCM; emit as a
# repo-level error naming the untracked file and line.
loc = "%s:%s" % (filepath, line) if line else filepath
ctx.emit.finding(
level = level,
message = "[%s] %s" % (loc, message),
)
def register_skills_checks():
shac.register_check(shac.check(_skill_format, formatter = True))
shac.register_check(_agent_customizations_lint)