sightmap 0.3.0

Library and CLI for the Sightmap spec — parse, validate, merge, match, explain, lint.

sightmap

Official Python SDK and CLI for the Sightmap spec — a YAML format that teaches agents how to see and use a web app's views, components, and API requests.

• Spec & docs: sightmap.org · github.com/sightmap/spec
• Package: sightmap on PyPI
• JavaScript/TypeScript SDK: @sightmap/sightmap

pip install sightmap

CLI

sightmap validate [path]                                         # default path: .sightmap
sightmap lint [path] [--strict] [--rules <list>]
sightmap match <url> [path] [--method <m>] [--require-view]
sightmap explain <query> [path] [--by name|path] [--type view|component|request] [--require-hit]
sightmap fmt [path] [--check | --write]
sightmap check [path] [--strict]

sightmap fmt [PATH] [--check | --write]

Canonical YAML formatter for .sightmap/*.yaml. Idempotent. Validates against schema before formatting; refuses to rewrite parse-invalid or schema-invalid input. See authoring-conventions.md for the rules.

• --check (default): exit non-zero if any file is not canonical; print unified diff. Suitable for CI.
• --write: rewrite files in place, atomically.

sightmap check [PATH] [--strict]

Composite CI gate: runs validate and fmt --check in one pass.

• Default: errors fail; warnings reported but exit 0.
• --strict: warnings also fail. Recommended for CI on protected branches.

Every command supports --json for machine-readable output and --cwd <dir> for invocation from outside the project.

Examples

# Validate the schema of every YAML file under .sightmap/
$ sightmap validate
ok    .sightmap/views.yaml
ok    .sightmap/components.yaml
2 file(s) checked.

# Resolve everything an agent needs to drive the URL /list/abc123
$ sightmap match /list/abc123
view  ListDetailScreen  (route /list/*)
  source  app/list/[id].py
comp  BottomTabBar  global  selector=[role="tablist"]
...

# Find every entry tied to a particular source file
$ sightmap explain 'app/views/home.py'
4 hit(s) for "app/views/home.py":
  view       Home               matched_as=path  src=app/views/home.py
  component  HomeHeader         matched_as=path  src=app/views/home.py
  ...

Exit codes

• 0 — success
• 1 — logical failure (validation error, --strict warning, --require-view/--require-hit miss)
• 2 — usage error

--json envelope

Every command emits the same top-level shape so agents can dispatch on command:

{
  "ok": true,
  "command": "match",
  "diagnostics": [],
  "result": { "...": "command-specific" }
}

Inside result, fields use snake_case keys (Pythonic; the JS SDK uses camelCase).

Library

from sightmap import (
    parse, validate, merge, load_directory,
    match, explain, lint,
)

sightmap = load_directory(".sightmap")

r = match(sightmap, url="/search")
print(r.view.name if r.view else None, len(r.components))

hits = explain(sightmap, "src/components/foo.py")
issues = lint(sightmap, root=".")

parse() raises on invalid input; validate() returns a non-throwing Result. Downstream code should consume validate(), not parse(). parse() is sugar for end-user code that knows the input is valid.

For canonical spec semantics — schema fields, route glob syntax, scope rules, and the design rationale — see sightmap.org and spec/v1/schema.md in the spec repo.

Diagnostics

Lint and validate share a Diagnostic shape:

from sightmap import Diagnostic, Severity
# Diagnostic(severity, code, message, file=None, path=None, loc=None, source=None)

Codes are stable, kebab-case, and exported as constants:

Code	Severity	Source
parse-error	error	parse / load_directory
schema-validation-failed	error	validate
unknown-version	error	validate
merge-collision-view	warning	merge / load_directory
merge-collision-component	warning	merge / load_directory
duplicate-view-name	warning	lint
duplicate-route	warning	lint
route-shadowing	warning	lint
unknown-source	warning	lint
selector-syntax	warning	lint

Codes are stable across SDK versions and match the JS SDK's vocabulary so cross-SDK tooling that dispatches on code stays portable. The JSON shape inside result and the surface attribute names are translated to each language's idiom (snake_case here, camelCase in JS).

Project resources

Org-wide policy lives in adjacent repos:

• sightmap/spec — spec source, governance, conformance fixtures
• sightmap/.github — Code of Conduct, Security policy, Support
• sightmap/sightmap-js — JavaScript/TypeScript SDK

Spec pin

This package vendors sightmap.schema.json from the spec repo at a specific SHA. See src/sightmap/vendored/SPEC-PIN.md for the current pin and bump procedure.

License

MIT — see LICENSE.