Metadata-Version: 2.4
Name: sightmap
Version: 0.3.0
Summary: Library and CLI for the Sightmap spec — parse, validate, merge, match, explain, lint.
Project-URL: Homepage, https://sightmap.org
Project-URL: Repository, https://github.com/sightmap/sightmap-python
Project-URL: Changelog, https://github.com/sightmap/sightmap-python/blob/main/CHANGELOG.md
Author: Sightmap maintainers
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,sdk,sightmap,yaml
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: cssselect>=1.2
Requires-Dist: jsonschema>=4.20
Requires-Dist: pydantic>=2.6
Requires-Dist: ruamel-yaml>=0.18
Description-Content-Type: text/markdown

# sightmap

Official Python SDK and CLI for the [Sightmap spec](https://sightmap.org) — a YAML format that teaches agents how to see and use a web app's views, components, and API requests.

- **Spec & docs:** [sightmap.org](https://sightmap.org) · [github.com/sightmap/spec](https://github.com/sightmap/spec)
- **Package:** [`sightmap`](https://pypi.org/project/sightmap/) on PyPI
- **JavaScript/TypeScript SDK:** [`@sightmap/sightmap`](https://www.npmjs.com/package/@sightmap/sightmap)

```bash
pip install sightmap
```

## CLI

```bash
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](https://github.com/sightmap/spec/blob/main/docs/authoring-conventions.md#canonical-formatting-rules) 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

```bash
# 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`:

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

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

## Library

```python
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](https://sightmap.org) and [`spec/v1/schema.md`](https://github.com/sightmap/spec/blob/main/spec/v1/schema.md) in the spec repo.

### Diagnostics

Lint and validate share a `Diagnostic` shape:

```python
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`](https://github.com/sightmap/spec) — spec source, governance, conformance fixtures
- [`sightmap/.github`](https://github.com/sightmap/.github) — Code of Conduct, Security policy, Support
- [`sightmap/sightmap-js`](https://github.com/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`](src/sightmap/vendored/SPEC-PIN.md) for the current pin and bump procedure.

## License

MIT — see [LICENSE](LICENSE).
