lint_artifact

Implementation Reference

• src/web_gui_mcp/lint/artifact.py:13-39 (handler)

  Core handler that runs specified lint checks (schema, security, html_size, accessibility, mobile, token_cost) on the input and returns results with ok flag.

  def lint_artifact_input(input_data: LintArtifactInput) -> LintArtifactOutput:
      issues: list[LintIssue] = []
      if input_data.spec is None and input_data.html is None:
          issues.append(
              LintIssue(
                  check="schema",
                  severity="error",
                  message="Provide either spec or html.",
              )
          )
      for check in input_data.checks:
          if check == "schema":
              _lint_schema(input_data, issues)
          elif check == "security":
              _lint_security(input_data, issues)
          elif check == "html_size":
              _lint_html_size(input_data, issues)
          elif check == "accessibility":
              _lint_accessibility(input_data, issues)
          elif check == "mobile":
              _lint_mobile(input_data, issues)
          elif check == "token_cost":
              _lint_token_cost(input_data, issues)
      return LintArtifactOutput(
          ok=not any(issue.severity == "error" for issue in issues),
          issues=issues,
      )

• src/web_gui_mcp/schema/tool_io.py:112-130 (schema)

  Pydantic schemas: LintArtifactInput (spec, html, checks list), LintArtifactOutput (ok flag, list of LintIssue), and LintIssue model.

  class LintIssue(ToolBaseModel):
      check: str
      severity: Literal["info", "warning", "error"]
      message: str
      path: str | None = None
  
  
  class LintArtifactInput(ToolBaseModel):
      spec: ArtifactSpec | None = None
      html: str | None = None
      checks: list[
          Literal["schema", "accessibility", "mobile", "security", "token_cost", "html_size"]
      ] = Field(default_factory=lambda: ["schema", "security", "html_size"])
  
  
  class LintArtifactOutput(ToolBaseModel):
      ok: bool
      issues: list[LintIssue]

• src/web_gui_mcp/mcp_tools.py:188-190 (registration)

  MCP tool registration decorator for lint_artifact, delegating to lint_artifact_handler.

  @mcp.tool()
  def lint_artifact(input: LintArtifactInput) -> LintArtifactOutput:
      return lint_artifact_handler(input)

• src/web_gui_mcp/mcp_tools.py:120-121 (handler)

  Thin bridge handler in mcp_tools.py that delegates to the core lint_artifact_input function.

  def lint_artifact_handler(input_data: LintArtifactInput) -> LintArtifactOutput:
      return lint_artifact_input(input_data)

• src/web_gui_mcp/lint/artifact.py:42-152 (helper)

  Helper functions: _lint_schema (validates spec present), _lint_security (checks for scripts/inline handlers), _lint_html_size (warns if >500KB), _lint_accessibility (lang/h1), _lint_mobile (viewport meta), _lint_token_cost (section/body/code sizes), and _iter_strings (recursive string traversal).

  def _lint_schema(input_data: LintArtifactInput, issues: list[LintIssue]) -> None:
      if input_data.spec is not None:
          issues.append(LintIssue(check="schema", severity="info", message="Spec is valid."))
  
  
  def _lint_security(input_data: LintArtifactInput, issues: list[LintIssue]) -> None:
      if input_data.spec is not None:
          for path, value in _iter_strings(input_data.spec.model_dump(mode="json", by_alias=True)):
              if RISKY_TEXT_RE.search(value):
                  issues.append(
                      LintIssue(
                          check="security",
                          severity="warning",
                          message="Spec contains text that will be escaped by the renderer.",
                          path=path,
                      )
                  )
      if input_data.html is not None:
          if INLINE_HANDLER_RE.search(input_data.html):
              issues.append(
                  LintIssue(
                      check="security",
                      severity="error",
                      message="HTML contains inline event-handler attributes.",
                  )
              )
          if JAVASCRIPT_URL_RE.search(input_data.html):
              issues.append(
                  LintIssue(
                      check="security",
                      severity="error",
                      message="HTML contains a javascript: URL.",
                  )
              )
  
  
  def _lint_html_size(input_data: LintArtifactInput, issues: list[LintIssue]) -> None:
      if input_data.html is not None:
          size = len(input_data.html.encode("utf-8"))
          if size > 500_000:
              issues.append(
                  LintIssue(
                      check="html_size",
                      severity="warning",
                      message=f"HTML is large for an artifact response: {size} bytes.",
                  )
              )
  
  
  def _lint_accessibility(input_data: LintArtifactInput, issues: list[LintIssue]) -> None:
      if input_data.html is None:
          return
      if "<html lang=" not in input_data.html:
          issues.append(
              LintIssue(check="accessibility", severity="warning", message="HTML is missing lang.")
          )
      if "<h1>" not in input_data.html:
          issues.append(
              LintIssue(check="accessibility", severity="warning", message="HTML is missing h1.")
          )
  
  
  def _lint_mobile(input_data: LintArtifactInput, issues: list[LintIssue]) -> None:
      if input_data.html is not None and 'name="viewport"' not in input_data.html:
          issues.append(
              LintIssue(check="mobile", severity="warning", message="HTML is missing viewport meta.")
          )
  
  
  def _lint_token_cost(input_data: LintArtifactInput, issues: list[LintIssue]) -> None:
      if input_data.spec is None:
          return
      spec = input_data.spec
      if len(spec.sections) > MAX_SECTIONS * 0.75:
          issues.append(
              LintIssue(check="token_cost", severity="warning", message="Spec has many sections.")
          )
      for index, section in enumerate(spec.sections):
          body = getattr(section, "body", "")
          code = getattr(section, "code", "")
          if len(body) > MAX_BODY_LENGTH * 0.75:
              issues.append(
                  LintIssue(
                      check="token_cost",
                      severity="warning",
                      message="Narrative body is close to maximum length.",
                      path=f"/sections/{index}/body",
                  )
              )
          if len(code) > MAX_CODE_LENGTH * 0.75:
              issues.append(
                  LintIssue(
                      check="token_cost",
                      severity="warning",
                      message="Code block is close to maximum length.",
                      path=f"/sections/{index}/code",
                  )
              )
  
  
  def _iter_strings(value: object, path: str = "") -> list[tuple[str, str]]:
      found: list[tuple[str, str]] = []
      if isinstance(value, str):
          found.append((path, value))
      elif isinstance(value, dict):
          for key, child in value.items():
              found.extend(_iter_strings(child, f"{path}/{key}"))
      elif isinstance(value, list):
          for index, child in enumerate(value):
              found.extend(_iter_strings(child, f"{path}/{index}"))
      return found