@sightmap/sightmap 0.2.0 → 0.3.0

package/README.md

@@ -20,6 +20,7 @@ sightmap lint [path] [--strict] [--rules <list>]
 sightmap check [path] [--stdin] [--level schema|quality]         # combined validate + lint
 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]                          # default path: .sightmap
 sightmap check-conventions [path]                                # default path: .
 ```
 
@@ -64,6 +65,19 @@ $ sightmap explain 'app/(tabs)/index.tsx'
   component  ArcCard            matchedAs=path  src=app/(tabs)/index.tsx
 ```
 
+### `sightmap fmt [path]`
+
+Canonicalize `.sightmap/*.yaml` files per the spec's normative formatting rules. Comment- and HEADER-preserving.
+
+```bash
+sightmap fmt --check         # exit 1 if any file is not canonical (CI mode)
+sightmap fmt --write         # rewrite non-canonical files in place
+```
+
+Diagnostics: `fmt.not-canonical` (warning), `fmt.parse-error` (error), `fmt.schema-invalid` (error). Files with parse or schema errors are left untouched.
+
+Exit codes: `0` (canonical / no rewrites needed), `1` (`--check` found non-canonical files), `2` (parse / schema / IO error).
+
 ### `sightmap check-conventions [path]`
 
 Validate that the repo at `<path>` (default `.`) follows the [filename conventions](https://github.com/sightmap/spec/blob/main/docs/repo-conventions.md) for SEPs (`seps/NNNN-{slug}.md`) and conformance fixtures (`conformance/NNN-{slug}.fixture/`). Exit code `0` if clean, `1` if any violations. Pass `--json` for machine-readable output.
@@ -162,6 +176,9 @@ Codes are stable, kebab-case, and exported as constants:
 | `convention.fixture-dirname`  | error    | `check-conventions`       |
 | `convention.invalid-slug`     | error    | `check-conventions`       |
 | `convention.unexpected-file`  | error    | `check-conventions`       |
+| `fmt.not-canonical`           | warning  | `fmt --check`             |
+| `fmt.parse-error`             | error    | `fmt`                     |
+| `fmt.schema-invalid`          | error    | `fmt`                     |
 
 Renames require an SEP. Future SDK ports (Python, Go) MUST emit identical codes for the same conditions.
 

package/dist/{browser-ChD_xQt8.d.ts → browser-2wvcIicU.d.ts}

@@ -101,6 +101,9 @@ declare const DUPLICATE_ROUTE = "duplicate-route";
 declare const ROUTE_SHADOWING = "route-shadowing";
 declare const UNKNOWN_SOURCE = "unknown-source";
 declare const SELECTOR_SYNTAX = "selector-syntax";
+declare const FMT_NOT_CANONICAL = "fmt.not-canonical";
+declare const FMT_PARSE_ERROR = "fmt.parse-error";
+declare const FMT_SCHEMA_INVALID = "fmt.schema-invalid";
 
 /**
  * A single-file fragment after parsing and selector normalization.
@@ -250,4 +253,4 @@ interface ExplainOptions {
 }
 declare function explain(sightmap: Sightmap, query: string, opts?: ExplainOptions): ExplainResult;
 
-export { type Component as C, type Diagnostic as D, type ExplainHit as E, type Field as F, MERGE_COLLISION_COMPONENT as M, PARSE_ERROR as P, ROUTE_SHADOWING as R, type Sightmap as S, UNKNOWN_SOURCE as U, type ValidateResult as V, type SightmapV1 as a, DUPLICATE_ROUTE as b, DUPLICATE_VIEW_NAME as c, type ExplainMatchedAs as d, type ExplainResult as e, MERGE_COLLISION_VIEW as f, type MatchResult as g, type Request as h, type ResolvedComponent as i, type ResolvedRequest as j, type ResolvedView as k, SCHEMA_VALIDATION_FAILED as l, SELECTOR_SYNTAX as m, type Severity as n, type SightmapFragment as o, UNKNOWN_VERSION as p, type View as q, explain as r, match as s, merge as t, parse as u };
+export { type Component as C, type Diagnostic as D, type ExplainHit as E, FMT_NOT_CANONICAL as F, MERGE_COLLISION_COMPONENT as M, PARSE_ERROR as P, ROUTE_SHADOWING as R, type Sightmap as S, UNKNOWN_SOURCE as U, type ValidateResult as V, type SightmapV1 as a, DUPLICATE_ROUTE as b, DUPLICATE_VIEW_NAME as c, type ExplainMatchedAs as d, type ExplainResult as e, FMT_PARSE_ERROR as f, FMT_SCHEMA_INVALID as g, type Field as h, MERGE_COLLISION_VIEW as i, type MatchResult as j, type Request as k, type ResolvedComponent as l, type ResolvedRequest as m, type ResolvedView as n, SCHEMA_VALIDATION_FAILED as o, SELECTOR_SYNTAX as p, type Severity as q, type SightmapFragment as r, UNKNOWN_VERSION as s, type View as t, explain as u, match as v, merge as w, parse as x };

package/dist/browser.d.ts

@@ -1 +1 @@
-export { E as ExplainHit, d as ExplainMatchedAs, e as ExplainResult, g as MatchResult, i as ResolvedComponent, j as ResolvedRequest, k as ResolvedView, S as Sightmap, o as SightmapFragment, r as explain, s as match, t as merge, u as parse } from './browser-ChD_xQt8.js';
+export { E as ExplainHit, d as ExplainMatchedAs, e as ExplainResult, j as MatchResult, l as ResolvedComponent, m as ResolvedRequest, n as ResolvedView, S as Sightmap, r as SightmapFragment, u as explain, v as match, w as merge, x as parse } from './browser-2wvcIicU.js';

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/parse.ts","../src/diagnostics.ts","../src/merge.ts","../src/routeMatch.ts","../src/resolver.ts","../src/match.ts","../src/explain.ts"],"sourcesContent":["import yaml from \"js-yaml\";\nimport type { SightmapFragment } from \"./sightmap.js\";\nimport type { Component } from \"./types.js\";\n\nexport interface ParseOptions {\n  /** Optional source file path; recorded on the fragment for canonical-order merging. */\n  sourceFile?: string;\n}\n\n/**\n * Parse a single sightmap file (YAML string or pre-parsed object).\n * Throws on parse error, missing version, or version mismatch.\n * Normalizes `selector: string` to `selector: [string]` everywhere.\n */\nexport function parse(input: string | object, opts: ParseOptions = {}): SightmapFragment {\n  let doc: unknown;\n  if (typeof input === \"string\") {\n    try {\n      doc = yaml.load(input);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new Error(`YAML parse error: ${msg}`);\n    }\n  } else {\n    // Shallow-clone caller's object so we don't mutate it.\n    doc = { ...input };\n  }\n\n  if (doc === null || typeof doc !== \"object\" || Array.isArray(doc)) {\n    throw new Error(\"Expected sightmap document to be an object at the root\");\n  }\n\n  const obj = doc as Record<string, unknown>;\n  if (obj[\"version\"] === undefined) {\n    throw new Error(\"Missing required `version` field\");\n  }\n  if (obj[\"version\"] !== 1) {\n    throw new Error(`Unsupported version: ${String(obj[\"version\"])} (expected 1)`);\n  }\n\n  // Normalize selectors recursively. Spread each view to avoid mutating\n  // shared view objects when the caller passed a pre-parsed input.\n  if (Array.isArray(obj[\"components\"])) {\n    obj[\"components\"] = (obj[\"components\"] as Component[]).map(normalizeComponent);\n  }\n  if (Array.isArray(obj[\"views\"])) {\n    obj[\"views\"] = (obj[\"views\"] as Array<Record<string, unknown>>).map((v) => {\n      const out = { ...v };\n      if (Array.isArray(out[\"components\"])) {\n        out[\"components\"] = (out[\"components\"] as Component[]).map(normalizeComponent);\n      }\n      return out;\n    });\n  }\n\n  const fragment = {\n    ...obj,\n    __brand: \"SightmapFragment\" as const,\n    ...(opts.sourceFile !== undefined ? { __sourceFile: opts.sourceFile } : {}),\n  } as SightmapFragment;\n  return fragment;\n}\n\nfunction normalizeComponent(c: Component): Component {\n  // Common migration error: `selectors` (plural) instead of `selector` (singular).\n  // The schema only accepts singular `selector`; the singular field already takes\n  // a string or string-array, so a plural alias would be redundant. Surface\n  // explicitly rather than silently dropping the value.\n  if ((c as unknown as Record<string, unknown>)[\"selectors\"] !== undefined && c.selector === undefined) {\n    const name = (c as { name?: string }).name ?? \"(unnamed)\";\n    throw new Error(\n      `Component \"${name}\": use \\`selector\\` (singular), not \\`selectors\\` (plural). ` +\n        `\\`selector\\` accepts either a single string or an array of strings.`,\n    );\n  }\n  const sel = c.selector;\n  const normalized: Component = {\n    ...c,\n    selector: typeof sel === \"string\" ? [sel] : (sel as [string, ...string[]]),\n  };\n  if (Array.isArray(c.children)) {\n    normalized.children = c.children.map(normalizeComponent);\n  }\n  return normalized;\n}\n","export type Severity = \"error\" | \"warning\" | \"info\";\n\nexport interface Diagnostic {\n  severity: Severity;\n  code: string;\n  message: string;\n  file?: string;\n  path?: string;\n  loc?: { line: number; column: number };\n  source?: string;\n}\n\n// Stable, kebab-case codes. Renames require an SEP.\nexport const PARSE_ERROR = \"parse-error\";\nexport const SCHEMA_VALIDATION_FAILED = \"schema-validation-failed\";\nexport const UNKNOWN_VERSION = \"unknown-version\";\nexport const MERGE_COLLISION_VIEW = \"merge-collision-view\";\nexport const MERGE_COLLISION_COMPONENT = \"merge-collision-component\";\nexport const DUPLICATE_VIEW_NAME = \"duplicate-view-name\";\nexport const DUPLICATE_ROUTE = \"duplicate-route\";\nexport const ROUTE_SHADOWING = \"route-shadowing\";\nexport const UNKNOWN_SOURCE = \"unknown-source\";\nexport const SELECTOR_SYNTAX = \"selector-syntax\";\n\n// Repo-conventions codes (WI-6). See docs/repo-conventions.md in the spec repo.\nexport const CONVENTION_SEP_FILENAME = \"convention.sep-filename\";\nexport const CONVENTION_FIXTURE_DIRNAME = \"convention.fixture-dirname\";\nexport const CONVENTION_INVALID_SLUG = \"convention.invalid-slug\";\nexport const CONVENTION_UNEXPECTED_FILE = \"convention.unexpected-file\";\n","import type { SightmapFragment, Sightmap } from \"./sightmap.js\";\nimport type { View, Component, Request } from \"./types.js\";\nimport {\n  MERGE_COLLISION_VIEW,\n  MERGE_COLLISION_COMPONENT,\n  type Diagnostic,\n} from \"./diagnostics.js\";\n\n/**\n * Merge fragments into a queryable Sightmap.\n *\n * Canonical order: fragments are sorted by `__sourceFile` (code-point order; locale-independent\n * for cross-environment determinism). Fragments without a `__sourceFile` sort first, and ES2019\n * sort stability preserves their input order. Within each fragment, declaration order is\n * preserved. The merged collection's order = (sourceFile order, then declaration order).\n *\n * Duplicate view names produce `merge-collision-view` warnings; duplicate global component\n * names produce `merge-collision-component`. The first occurrence wins.\n *\n * Returned arrays are fresh, but element objects (View/Component/Request) are shared with\n * the input fragments — callers must not mutate them.\n */\nexport function merge(fragments: SightmapFragment[]): Sightmap {\n  const sorted = [...fragments].sort((a, b) => {\n    const aFile = a.__sourceFile ?? \"\";\n    const bFile = b.__sourceFile ?? \"\";\n    return aFile < bFile ? -1 : aFile > bFile ? 1 : 0;\n  });\n\n  const views: View[] = [];\n  const globalComponents: Component[] = [];\n  const globalRequests: Request[] = [];\n  const fileMemory: { memory: string[]; sourceFile: string }[] = [];\n  const diagnostics: Diagnostic[] = [];\n\n  const seenViewNames = new Map<string, string>(); // name → sourceFile\n  const seenComponentNames = new Map<string, string>();\n\n  for (const f of sorted) {\n    const file = f.__sourceFile ?? \"<unknown>\";\n\n    for (const v of f.views ?? []) {\n      const prev = seenViewNames.get(v.name);\n      if (prev !== undefined) {\n        diagnostics.push({\n          severity: \"warning\",\n          code: MERGE_COLLISION_VIEW,\n          message: `View name \"${v.name}\" defined in both \"${prev}\" and \"${file}\"; first occurrence wins.`,\n          file,\n        });\n      } else {\n        seenViewNames.set(v.name, file);\n      }\n      views.push(v); // keep all views; first-match-wins is enforced at resolve time\n    }\n\n    for (const c of f.components ?? []) {\n      const prev = seenComponentNames.get(c.name);\n      if (prev !== undefined) {\n        diagnostics.push({\n          severity: \"warning\",\n          code: MERGE_COLLISION_COMPONENT,\n          message: `Component name \"${c.name}\" defined in both \"${prev}\" and \"${file}\"; first occurrence wins.`,\n          file,\n        });\n      } else {\n        seenComponentNames.set(c.name, file);\n      }\n      globalComponents.push(c);\n    }\n\n    for (const r of f.requests ?? []) {\n      globalRequests.push(r);\n    }\n\n    if (Array.isArray(f.memory) && f.memory.length > 0) {\n      fileMemory.push({ memory: [...f.memory], sourceFile: file });\n    }\n  }\n\n  return {\n    version: 1,\n    views,\n    globalComponents,\n    globalRequests,\n    fileMemory,\n    diagnostics,\n    __brand: \"Sightmap\",\n  };\n}\n","/**\n * Canonicalize a URL or pathname for matching.\n * - Accepts absolute URL or pathname.\n * - Strips scheme, host, query string, and fragment.\n * - Normalizes trailing slashes (except for the root \"/\").\n */\nexport function canonicalizeUrl(input: string): string {\n  let s = input;\n  // Strip absolute prefix.\n  const protoMatch = /^[a-z][a-z0-9+.-]*:\\/\\/[^/]*/i.exec(s);\n  if (protoMatch) {\n    s = s.slice(protoMatch[0].length) || \"/\";\n  }\n  // Strip fragment.\n  const hash = s.indexOf(\"#\");\n  if (hash !== -1) s = s.slice(0, hash);\n  // Strip query.\n  const q = s.indexOf(\"?\");\n  if (q !== -1) s = s.slice(0, q);\n  // Trailing slash.\n  if (s.length > 1 && s.endsWith(\"/\")) s = s.slice(0, -1);\n  return s;\n}\n\n/**\n * Test whether a glob route pattern matches a URL pathname.\n * Pattern syntax (per spec):\n *   - Literal segments match themselves\n *   - \"*\" matches exactly one path segment\n *   - \"**\" matches any depth of segments\n *   - \":param\" segments normalize to \"*\"\n *   - Matching is case-sensitive\n *   - Trailing slashes ignored\n */\nexport function routeMatch(pattern: string, url: string): boolean {\n  const p = normalizePattern(pattern);\n  const u = canonicalizeUrl(url);\n  const patternSegs = splitSegments(p);\n  const urlSegs = splitSegments(u);\n  return matchSegs(patternSegs, urlSegs);\n}\n\nfunction normalizePattern(p: string): string {\n  // Replace \":param\" segments with \"*\"\n  let s = p\n    .split(\"/\")\n    .map((seg) => (seg.startsWith(\":\") ? \"*\" : seg))\n    .join(\"/\");\n  if (s.length > 1 && s.endsWith(\"/\")) s = s.slice(0, -1);\n  return s;\n}\n\nfunction splitSegments(path: string): string[] {\n  if (path === \"/\" || path === \"\") return [];\n  const trimmed = path.startsWith(\"/\") ? path.slice(1) : path;\n  return trimmed.split(\"/\");\n}\n\nfunction matchSegs(pattern: string[], url: string[]): boolean {\n  if (pattern.length === 0 && url.length === 0) return true;\n  if (pattern.length === 0) return false;\n\n  const head = pattern[0]!;\n  const rest = pattern.slice(1);\n\n  if (head === \"**\") {\n    // Match zero or more segments.\n    if (rest.length === 0) return true;\n    for (let i = 0; i <= url.length; i++) {\n      if (matchSegs(rest, url.slice(i))) return true;\n    }\n    return false;\n  }\n\n  if (url.length === 0) return false;\n  if (head === \"*\" || head === url[0]) {\n    return matchSegs(rest, url.slice(1));\n  }\n  return false;\n}\n","import type {\n  Sightmap,\n  MatchResult,\n  ExplainHit,\n  ResolvedView,\n  ResolvedComponent,\n  ResolvedRequest,\n} from \"./sightmap.js\";\nimport type { View, Component, Request } from \"./types.js\";\nimport { routeMatch } from \"./routeMatch.js\";\n\nexport function resolveByUrl(\n  sightmap: Sightmap,\n  url: string,\n  method?: string,\n): MatchResult {\n  // First-match-wins on views.\n  let matchedView: View | null = null;\n  for (const v of sightmap.views) {\n    if (routeMatch(v.route, url)) {\n      matchedView = v;\n      break;\n    }\n  }\n\n  const components: ResolvedComponent[] = [];\n  for (const c of sightmap.globalComponents) {\n    components.push(...flattenComponent(c, [], \"global\", undefined));\n  }\n  if (matchedView !== null && Array.isArray(matchedView.components)) {\n    for (const c of matchedView.components) {\n      components.push(...flattenComponent(c, [], \"view-scoped\", matchedView.name));\n    }\n  }\n\n  const requests: ResolvedRequest[] = [];\n  const requestPool: Request[] = [\n    ...sightmap.globalRequests,\n    ...((matchedView?.requests ?? [])),\n  ];\n  for (const req of requestPool) {\n    if (!routeMatch(req.route, url)) continue;\n    if (method !== undefined && req.method !== undefined && req.method !== method) continue;\n    requests.push(toResolvedRequest(req));\n  }\n\n  const memory: string[] = [];\n  for (const fm of sightmap.fileMemory) memory.push(...fm.memory);\n  if (matchedView?.memory) memory.push(...matchedView.memory);\n\n  return {\n    view: matchedView !== null ? toResolvedView(matchedView) : null,\n    components,\n    requests,\n    memory,\n  };\n}\n\nexport function resolveByName(sightmap: Sightmap, name: string): ExplainHit[] {\n  const hits: ExplainHit[] = [];\n  for (const v of sightmap.views) {\n    if (v.name === name) hits.push({ type: \"view\", matchedAs: \"name\", entry: toResolvedView(v) });\n  }\n  for (const c of sightmap.globalComponents) {\n    for (const rc of flattenComponent(c, [], \"global\", undefined)) {\n      if (rc.name === name) hits.push({ type: \"component\", matchedAs: \"name\", entry: rc });\n    }\n  }\n  for (const v of sightmap.views) {\n    for (const c of v.components ?? []) {\n      for (const rc of flattenComponent(c, [], \"view-scoped\", v.name)) {\n        if (rc.name === name) hits.push({ type: \"component\", matchedAs: \"name\", entry: rc });\n      }\n    }\n  }\n  for (const r of sightmap.globalRequests) {\n    if (r.name === name) hits.push({ type: \"request\", matchedAs: \"name\", entry: toResolvedRequest(r) });\n  }\n  for (const v of sightmap.views) {\n    for (const r of v.requests ?? []) {\n      if (r.name === name) hits.push({ type: \"request\", matchedAs: \"name\", entry: toResolvedRequest(r) });\n    }\n  }\n  return hits;\n}\n\nexport function resolveBySourcePath(sightmap: Sightmap, path: string): ExplainHit[] {\n  const hits: ExplainHit[] = [];\n  for (const v of sightmap.views) {\n    if (v.source === path) hits.push({ type: \"view\", matchedAs: \"path\", entry: toResolvedView(v) });\n  }\n  for (const c of sightmap.globalComponents) {\n    for (const rc of flattenComponent(c, [], \"global\", undefined)) {\n      if (rc.source === path) hits.push({ type: \"component\", matchedAs: \"path\", entry: rc });\n    }\n  }\n  for (const v of sightmap.views) {\n    for (const c of v.components ?? []) {\n      for (const rc of flattenComponent(c, [], \"view-scoped\", v.name)) {\n        if (rc.source === path) hits.push({ type: \"component\", matchedAs: \"path\", entry: rc });\n      }\n    }\n  }\n  for (const r of sightmap.globalRequests) {\n    if (r.source === path) hits.push({ type: \"request\", matchedAs: \"path\", entry: toResolvedRequest(r) });\n  }\n  return hits;\n}\n\nfunction flattenComponent(\n  c: Component,\n  parentChain: string[],\n  scope: \"global\" | \"view-scoped\",\n  scopedToView: string | undefined,\n): ResolvedComponent[] {\n  const out: ResolvedComponent[] = [];\n  const selector = Array.isArray(c.selector) ? c.selector : [c.selector as unknown as string];\n  out.push({\n    name: c.name,\n    selector,\n    ...(c.source !== undefined ? { source: c.source } : {}),\n    ...(c.description !== undefined ? { description: c.description } : {}),\n    memory: c.memory ? [...c.memory] : [],\n    parentChain: [...parentChain],\n    scope,\n    ...(scopedToView !== undefined ? { scopedToView } : {}),\n    definedIn: { file: \"<unknown>\" },\n  });\n  for (const child of c.children ?? []) {\n    out.push(...flattenComponent(child, [...parentChain, c.name], scope, scopedToView));\n  }\n  return out;\n}\n\nfunction toResolvedView(v: View): ResolvedView {\n  return {\n    name: v.name,\n    route: v.route,\n    ...(v.source !== undefined ? { source: v.source } : {}),\n    ...(v.description !== undefined ? { description: v.description } : {}),\n    memory: v.memory ? [...v.memory] : [],\n    definedIn: { file: \"<unknown>\" },\n  };\n}\n\nfunction toResolvedRequest(r: Request): ResolvedRequest {\n  return {\n    name: r.name,\n    route: r.route,\n    ...(r.method !== undefined ? { method: r.method } : {}),\n    ...(r.source !== undefined ? { source: r.source } : {}),\n    ...(r.description !== undefined ? { description: r.description } : {}),\n    ...(r.request !== undefined ? { request: { fields: r.request.fields ?? [] } } : {}),\n    ...(r.response !== undefined ? { response: { fields: r.response.fields ?? [] } } : {}),\n    ...(r.headers !== undefined ? { headers: r.headers } : {}),\n    memory: r.memory ? [...r.memory] : [],\n    definedIn: { file: \"<unknown>\" },\n  };\n}\n","import type { Sightmap, MatchResult } from \"./sightmap.js\";\nimport { resolveByUrl } from \"./resolver.js\";\n\nexport interface MatchOptions {\n  url: string;\n  method?: string;\n}\n\nexport function match(sightmap: Sightmap, opts: MatchOptions): MatchResult {\n  return resolveByUrl(sightmap, opts.url, opts.method);\n}\n","import type { Sightmap, ExplainResult, ExplainHit, ExplainMatchedAs } from \"./sightmap.js\";\nimport { resolveByName, resolveBySourcePath } from \"./resolver.js\";\n\nexport interface ExplainOptions {\n  by?: \"name\" | \"path\";\n  type?: \"view\" | \"component\" | \"request\";\n}\n\nexport function explain(\n  sightmap: Sightmap,\n  query: string,\n  opts: ExplainOptions = {},\n): ExplainResult {\n  const byName = opts.by === \"path\" ? [] : resolveByName(sightmap, query);\n  const byPath = opts.by === \"name\" ? [] : resolveBySourcePath(sightmap, query);\n\n  // Merge: when an entry appears in both lookups, label as \"name-and-path\".\n  // Use entry identity (type + name) as the dedup key.\n  const key = (h: ExplainHit): string => `${h.type}:${h.entry.name}`;\n  const namedKeys = new Set(byName.map(key));\n  const pathKeys = new Set(byPath.map(key));\n\n  const merged: ExplainHit[] = [];\n  for (const h of byName) {\n    if (pathKeys.has(key(h))) {\n      merged.push(withMatchedAs(h, \"name-and-path\"));\n    } else {\n      merged.push(h);\n    }\n  }\n  for (const h of byPath) {\n    if (!namedKeys.has(key(h))) {\n      merged.push(h);\n    }\n    // (entries already in both have been pushed above with \"name-and-path\".)\n  }\n\n  const filtered =\n    opts.type !== undefined ? merged.filter((h) => h.type === opts.type) : merged;\n  return { query, hits: filtered };\n}\n\nfunction withMatchedAs(h: ExplainHit, matchedAs: ExplainMatchedAs): ExplainHit {\n  switch (h.type) {\n    case \"view\":\n      return { type: \"view\", matchedAs, entry: h.entry };\n    case \"component\":\n      return { type: \"component\", matchedAs, entry: h.entry };\n    case \"request\":\n      return { type: \"request\", matchedAs, entry: h.entry };\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/parse.ts","../src/diagnostics.ts","../src/merge.ts","../src/routeMatch.ts","../src/resolver.ts","../src/match.ts","../src/explain.ts"],"sourcesContent":["import yaml from \"js-yaml\";\nimport type { SightmapFragment } from \"./sightmap.js\";\nimport type { Component } from \"./types.js\";\n\nexport interface ParseOptions {\n  /** Optional source file path; recorded on the fragment for canonical-order merging. */\n  sourceFile?: string;\n}\n\n/**\n * Parse a single sightmap file (YAML string or pre-parsed object).\n * Throws on parse error, missing version, or version mismatch.\n * Normalizes `selector: string` to `selector: [string]` everywhere.\n */\nexport function parse(input: string | object, opts: ParseOptions = {}): SightmapFragment {\n  let doc: unknown;\n  if (typeof input === \"string\") {\n    try {\n      doc = yaml.load(input);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new Error(`YAML parse error: ${msg}`);\n    }\n  } else {\n    // Shallow-clone caller's object so we don't mutate it.\n    doc = { ...input };\n  }\n\n  if (doc === null || typeof doc !== \"object\" || Array.isArray(doc)) {\n    throw new Error(\"Expected sightmap document to be an object at the root\");\n  }\n\n  const obj = doc as Record<string, unknown>;\n  if (obj[\"version\"] === undefined) {\n    throw new Error(\"Missing required `version` field\");\n  }\n  if (obj[\"version\"] !== 1) {\n    throw new Error(`Unsupported version: ${String(obj[\"version\"])} (expected 1)`);\n  }\n\n  // Normalize selectors recursively. Spread each view to avoid mutating\n  // shared view objects when the caller passed a pre-parsed input.\n  if (Array.isArray(obj[\"components\"])) {\n    obj[\"components\"] = (obj[\"components\"] as Component[]).map(normalizeComponent);\n  }\n  if (Array.isArray(obj[\"views\"])) {\n    obj[\"views\"] = (obj[\"views\"] as Array<Record<string, unknown>>).map((v) => {\n      const out = { ...v };\n      if (Array.isArray(out[\"components\"])) {\n        out[\"components\"] = (out[\"components\"] as Component[]).map(normalizeComponent);\n      }\n      return out;\n    });\n  }\n\n  const fragment = {\n    ...obj,\n    __brand: \"SightmapFragment\" as const,\n    ...(opts.sourceFile !== undefined ? { __sourceFile: opts.sourceFile } : {}),\n  } as SightmapFragment;\n  return fragment;\n}\n\nfunction normalizeComponent(c: Component): Component {\n  // Common migration error: `selectors` (plural) instead of `selector` (singular).\n  // The schema only accepts singular `selector`; the singular field already takes\n  // a string or string-array, so a plural alias would be redundant. Surface\n  // explicitly rather than silently dropping the value.\n  if ((c as unknown as Record<string, unknown>)[\"selectors\"] !== undefined && c.selector === undefined) {\n    const name = (c as { name?: string }).name ?? \"(unnamed)\";\n    throw new Error(\n      `Component \"${name}\": use \\`selector\\` (singular), not \\`selectors\\` (plural). ` +\n        `\\`selector\\` accepts either a single string or an array of strings.`,\n    );\n  }\n  const sel = c.selector;\n  const normalized: Component = {\n    ...c,\n    selector: typeof sel === \"string\" ? [sel] : (sel as [string, ...string[]]),\n  };\n  if (Array.isArray(c.children)) {\n    normalized.children = c.children.map(normalizeComponent);\n  }\n  return normalized;\n}\n","export type Severity = \"error\" | \"warning\" | \"info\";\n\nexport interface Diagnostic {\n  severity: Severity;\n  code: string;\n  message: string;\n  file?: string;\n  path?: string;\n  loc?: { line: number; column: number };\n  source?: string;\n}\n\n// Stable, kebab-case codes. Renames require an SEP.\nexport const PARSE_ERROR = \"parse-error\";\nexport const SCHEMA_VALIDATION_FAILED = \"schema-validation-failed\";\nexport const UNKNOWN_VERSION = \"unknown-version\";\nexport const MERGE_COLLISION_VIEW = \"merge-collision-view\";\nexport const MERGE_COLLISION_COMPONENT = \"merge-collision-component\";\nexport const DUPLICATE_VIEW_NAME = \"duplicate-view-name\";\nexport const DUPLICATE_ROUTE = \"duplicate-route\";\nexport const ROUTE_SHADOWING = \"route-shadowing\";\nexport const UNKNOWN_SOURCE = \"unknown-source\";\nexport const SELECTOR_SYNTAX = \"selector-syntax\";\n\n// fmt CLI diagnostic codes (sightmap/spec docs/authoring-conventions.md#diagnostic-codes-authoring-side).\nexport const FMT_NOT_CANONICAL = \"fmt.not-canonical\";\nexport const FMT_PARSE_ERROR = \"fmt.parse-error\";\nexport const FMT_SCHEMA_INVALID = \"fmt.schema-invalid\";\n\n// Repo-conventions codes (WI-6). See docs/repo-conventions.md in the spec repo.\nexport const CONVENTION_SEP_FILENAME = \"convention.sep-filename\";\nexport const CONVENTION_FIXTURE_DIRNAME = \"convention.fixture-dirname\";\nexport const CONVENTION_INVALID_SLUG = \"convention.invalid-slug\";\nexport const CONVENTION_UNEXPECTED_FILE = \"convention.unexpected-file\";\n","import type { SightmapFragment, Sightmap } from \"./sightmap.js\";\nimport type { View, Component, Request } from \"./types.js\";\nimport {\n  MERGE_COLLISION_VIEW,\n  MERGE_COLLISION_COMPONENT,\n  type Diagnostic,\n} from \"./diagnostics.js\";\n\n/**\n * Merge fragments into a queryable Sightmap.\n *\n * Canonical order: fragments are sorted by `__sourceFile` (code-point order; locale-independent\n * for cross-environment determinism). Fragments without a `__sourceFile` sort first, and ES2019\n * sort stability preserves their input order. Within each fragment, declaration order is\n * preserved. The merged collection's order = (sourceFile order, then declaration order).\n *\n * Duplicate view names produce `merge-collision-view` warnings; duplicate global component\n * names produce `merge-collision-component`. The first occurrence wins.\n *\n * Returned arrays are fresh, but element objects (View/Component/Request) are shared with\n * the input fragments — callers must not mutate them.\n */\nexport function merge(fragments: SightmapFragment[]): Sightmap {\n  const sorted = [...fragments].sort((a, b) => {\n    const aFile = a.__sourceFile ?? \"\";\n    const bFile = b.__sourceFile ?? \"\";\n    return aFile < bFile ? -1 : aFile > bFile ? 1 : 0;\n  });\n\n  const views: View[] = [];\n  const globalComponents: Component[] = [];\n  const globalRequests: Request[] = [];\n  const fileMemory: { memory: string[]; sourceFile: string }[] = [];\n  const diagnostics: Diagnostic[] = [];\n\n  const seenViewNames = new Map<string, string>(); // name → sourceFile\n  const seenComponentNames = new Map<string, string>();\n\n  for (const f of sorted) {\n    const file = f.__sourceFile ?? \"<unknown>\";\n\n    for (const v of f.views ?? []) {\n      const prev = seenViewNames.get(v.name);\n      if (prev !== undefined) {\n        diagnostics.push({\n          severity: \"warning\",\n          code: MERGE_COLLISION_VIEW,\n          message: `View name \"${v.name}\" defined in both \"${prev}\" and \"${file}\"; first occurrence wins.`,\n          file,\n        });\n      } else {\n        seenViewNames.set(v.name, file);\n      }\n      views.push(v); // keep all views; first-match-wins is enforced at resolve time\n    }\n\n    for (const c of f.components ?? []) {\n      const prev = seenComponentNames.get(c.name);\n      if (prev !== undefined) {\n        diagnostics.push({\n          severity: \"warning\",\n          code: MERGE_COLLISION_COMPONENT,\n          message: `Component name \"${c.name}\" defined in both \"${prev}\" and \"${file}\"; first occurrence wins.`,\n          file,\n        });\n      } else {\n        seenComponentNames.set(c.name, file);\n      }\n      globalComponents.push(c);\n    }\n\n    for (const r of f.requests ?? []) {\n      globalRequests.push(r);\n    }\n\n    if (Array.isArray(f.memory) && f.memory.length > 0) {\n      fileMemory.push({ memory: [...f.memory], sourceFile: file });\n    }\n  }\n\n  return {\n    version: 1,\n    views,\n    globalComponents,\n    globalRequests,\n    fileMemory,\n    diagnostics,\n    __brand: \"Sightmap\",\n  };\n}\n","/**\n * Canonicalize a URL or pathname for matching.\n * - Accepts absolute URL or pathname.\n * - Strips scheme, host, query string, and fragment.\n * - Normalizes trailing slashes (except for the root \"/\").\n */\nexport function canonicalizeUrl(input: string): string {\n  let s = input;\n  // Strip absolute prefix.\n  const protoMatch = /^[a-z][a-z0-9+.-]*:\\/\\/[^/]*/i.exec(s);\n  if (protoMatch) {\n    s = s.slice(protoMatch[0].length) || \"/\";\n  }\n  // Strip fragment.\n  const hash = s.indexOf(\"#\");\n  if (hash !== -1) s = s.slice(0, hash);\n  // Strip query.\n  const q = s.indexOf(\"?\");\n  if (q !== -1) s = s.slice(0, q);\n  // Trailing slash.\n  if (s.length > 1 && s.endsWith(\"/\")) s = s.slice(0, -1);\n  return s;\n}\n\n/**\n * Test whether a glob route pattern matches a URL pathname.\n * Pattern syntax (per spec):\n *   - Literal segments match themselves\n *   - \"*\" matches exactly one path segment\n *   - \"**\" matches any depth of segments\n *   - \":param\" segments normalize to \"*\"\n *   - Matching is case-sensitive\n *   - Trailing slashes ignored\n */\nexport function routeMatch(pattern: string, url: string): boolean {\n  const p = normalizePattern(pattern);\n  const u = canonicalizeUrl(url);\n  const patternSegs = splitSegments(p);\n  const urlSegs = splitSegments(u);\n  return matchSegs(patternSegs, urlSegs);\n}\n\nfunction normalizePattern(p: string): string {\n  // Replace \":param\" segments with \"*\"\n  let s = p\n    .split(\"/\")\n    .map((seg) => (seg.startsWith(\":\") ? \"*\" : seg))\n    .join(\"/\");\n  if (s.length > 1 && s.endsWith(\"/\")) s = s.slice(0, -1);\n  return s;\n}\n\nfunction splitSegments(path: string): string[] {\n  if (path === \"/\" || path === \"\") return [];\n  const trimmed = path.startsWith(\"/\") ? path.slice(1) : path;\n  return trimmed.split(\"/\");\n}\n\nfunction matchSegs(pattern: string[], url: string[]): boolean {\n  if (pattern.length === 0 && url.length === 0) return true;\n  if (pattern.length === 0) return false;\n\n  const head = pattern[0]!;\n  const rest = pattern.slice(1);\n\n  if (head === \"**\") {\n    // Match zero or more segments.\n    if (rest.length === 0) return true;\n    for (let i = 0; i <= url.length; i++) {\n      if (matchSegs(rest, url.slice(i))) return true;\n    }\n    return false;\n  }\n\n  if (url.length === 0) return false;\n  if (head === \"*\" || head === url[0]) {\n    return matchSegs(rest, url.slice(1));\n  }\n  return false;\n}\n","import type {\n  Sightmap,\n  MatchResult,\n  ExplainHit,\n  ResolvedView,\n  ResolvedComponent,\n  ResolvedRequest,\n} from \"./sightmap.js\";\nimport type { View, Component, Request } from \"./types.js\";\nimport { routeMatch } from \"./routeMatch.js\";\n\nexport function resolveByUrl(\n  sightmap: Sightmap,\n  url: string,\n  method?: string,\n): MatchResult {\n  // First-match-wins on views.\n  let matchedView: View | null = null;\n  for (const v of sightmap.views) {\n    if (routeMatch(v.route, url)) {\n      matchedView = v;\n      break;\n    }\n  }\n\n  const components: ResolvedComponent[] = [];\n  for (const c of sightmap.globalComponents) {\n    components.push(...flattenComponent(c, [], \"global\", undefined));\n  }\n  if (matchedView !== null && Array.isArray(matchedView.components)) {\n    for (const c of matchedView.components) {\n      components.push(...flattenComponent(c, [], \"view-scoped\", matchedView.name));\n    }\n  }\n\n  const requests: ResolvedRequest[] = [];\n  const requestPool: Request[] = [\n    ...sightmap.globalRequests,\n    ...((matchedView?.requests ?? [])),\n  ];\n  for (const req of requestPool) {\n    if (!routeMatch(req.route, url)) continue;\n    if (method !== undefined && req.method !== undefined && req.method !== method) continue;\n    requests.push(toResolvedRequest(req));\n  }\n\n  const memory: string[] = [];\n  for (const fm of sightmap.fileMemory) memory.push(...fm.memory);\n  if (matchedView?.memory) memory.push(...matchedView.memory);\n\n  return {\n    view: matchedView !== null ? toResolvedView(matchedView) : null,\n    components,\n    requests,\n    memory,\n  };\n}\n\nexport function resolveByName(sightmap: Sightmap, name: string): ExplainHit[] {\n  const hits: ExplainHit[] = [];\n  for (const v of sightmap.views) {\n    if (v.name === name) hits.push({ type: \"view\", matchedAs: \"name\", entry: toResolvedView(v) });\n  }\n  for (const c of sightmap.globalComponents) {\n    for (const rc of flattenComponent(c, [], \"global\", undefined)) {\n      if (rc.name === name) hits.push({ type: \"component\", matchedAs: \"name\", entry: rc });\n    }\n  }\n  for (const v of sightmap.views) {\n    for (const c of v.components ?? []) {\n      for (const rc of flattenComponent(c, [], \"view-scoped\", v.name)) {\n        if (rc.name === name) hits.push({ type: \"component\", matchedAs: \"name\", entry: rc });\n      }\n    }\n  }\n  for (const r of sightmap.globalRequests) {\n    if (r.name === name) hits.push({ type: \"request\", matchedAs: \"name\", entry: toResolvedRequest(r) });\n  }\n  for (const v of sightmap.views) {\n    for (const r of v.requests ?? []) {\n      if (r.name === name) hits.push({ type: \"request\", matchedAs: \"name\", entry: toResolvedRequest(r) });\n    }\n  }\n  return hits;\n}\n\nexport function resolveBySourcePath(sightmap: Sightmap, path: string): ExplainHit[] {\n  const hits: ExplainHit[] = [];\n  for (const v of sightmap.views) {\n    if (v.source === path) hits.push({ type: \"view\", matchedAs: \"path\", entry: toResolvedView(v) });\n  }\n  for (const c of sightmap.globalComponents) {\n    for (const rc of flattenComponent(c, [], \"global\", undefined)) {\n      if (rc.source === path) hits.push({ type: \"component\", matchedAs: \"path\", entry: rc });\n    }\n  }\n  for (const v of sightmap.views) {\n    for (const c of v.components ?? []) {\n      for (const rc of flattenComponent(c, [], \"view-scoped\", v.name)) {\n        if (rc.source === path) hits.push({ type: \"component\", matchedAs: \"path\", entry: rc });\n      }\n    }\n  }\n  for (const r of sightmap.globalRequests) {\n    if (r.source === path) hits.push({ type: \"request\", matchedAs: \"path\", entry: toResolvedRequest(r) });\n  }\n  return hits;\n}\n\nfunction flattenComponent(\n  c: Component,\n  parentChain: string[],\n  scope: \"global\" | \"view-scoped\",\n  scopedToView: string | undefined,\n): ResolvedComponent[] {\n  const out: ResolvedComponent[] = [];\n  const selector = Array.isArray(c.selector) ? c.selector : [c.selector as unknown as string];\n  out.push({\n    name: c.name,\n    selector,\n    ...(c.source !== undefined ? { source: c.source } : {}),\n    ...(c.description !== undefined ? { description: c.description } : {}),\n    memory: c.memory ? [...c.memory] : [],\n    parentChain: [...parentChain],\n    scope,\n    ...(scopedToView !== undefined ? { scopedToView } : {}),\n    definedIn: { file: \"<unknown>\" },\n  });\n  for (const child of c.children ?? []) {\n    out.push(...flattenComponent(child, [...parentChain, c.name], scope, scopedToView));\n  }\n  return out;\n}\n\nfunction toResolvedView(v: View): ResolvedView {\n  return {\n    name: v.name,\n    route: v.route,\n    ...(v.source !== undefined ? { source: v.source } : {}),\n    ...(v.description !== undefined ? { description: v.description } : {}),\n    memory: v.memory ? [...v.memory] : [],\n    definedIn: { file: \"<unknown>\" },\n  };\n}\n\nfunction toResolvedRequest(r: Request): ResolvedRequest {\n  return {\n    name: r.name,\n    route: r.route,\n    ...(r.method !== undefined ? { method: r.method } : {}),\n    ...(r.source !== undefined ? { source: r.source } : {}),\n    ...(r.description !== undefined ? { description: r.description } : {}),\n    ...(r.request !== undefined ? { request: { fields: r.request.fields ?? [] } } : {}),\n    ...(r.response !== undefined ? { response: { fields: r.response.fields ?? [] } } : {}),\n    ...(r.headers !== undefined ? { headers: r.headers } : {}),\n    memory: r.memory ? [...r.memory] : [],\n    definedIn: { file: \"<unknown>\" },\n  };\n}\n","import type { Sightmap, MatchResult } from \"./sightmap.js\";\nimport { resolveByUrl } from \"./resolver.js\";\n\nexport interface MatchOptions {\n  url: string;\n  method?: string;\n}\n\nexport function match(sightmap: Sightmap, opts: MatchOptions): MatchResult {\n  return resolveByUrl(sightmap, opts.url, opts.method);\n}\n","import type { Sightmap, ExplainResult, ExplainHit, ExplainMatchedAs } from \"./sightmap.js\";\nimport { resolveByName, resolveBySourcePath } from \"./resolver.js\";\n\nexport interface ExplainOptions {\n  by?: \"name\" | \"path\";\n  type?: \"view\" | \"component\" | \"request\";\n}\n\nexport function explain(\n  sightmap: Sightmap,\n  query: string,\n  opts: ExplainOptions = {},\n): ExplainResult {\n  const byName = opts.by === \"path\" ? [] : resolveByName(sightmap, query);\n  const byPath = opts.by === \"name\" ? [] : resolveBySourcePath(sightmap, query);\n\n  // Merge: when an entry appears in both lookups, label as \"name-and-path\".\n  // Use entry identity (type + name) as the dedup key.\n  const key = (h: ExplainHit): string => `${h.type}:${h.entry.name}`;\n  const namedKeys = new Set(byName.map(key));\n  const pathKeys = new Set(byPath.map(key));\n\n  const merged: ExplainHit[] = [];\n  for (const h of byName) {\n    if (pathKeys.has(key(h))) {\n      merged.push(withMatchedAs(h, \"name-and-path\"));\n    } else {\n      merged.push(h);\n    }\n  }\n  for (const h of byPath) {\n    if (!namedKeys.has(key(h))) {\n      merged.push(h);\n    }\n    // (entries already in both have been pushed above with \"name-and-path\".)\n  }\n\n  const filtered =\n    opts.type !== undefined ? merged.filter((h) => h.type === opts.type) : merged;\n  return { query, hits: filtered };\n}\n\nfunction withMatchedAs(h: ExplainHit, matchedAs: ExplainMatchedAs): ExplainHit {\n  switch (h.type) {\n    case \"view\":\n      return { type: \"view\", matchedAs, entry: h.entry };\n    case \"component\":\n      return { type: \"component\", matchedAs, entry: h.entry };\n    case \"request\":\n      return { type: \"request\", matchedAs, entry: h.entry };\n  }\n}\n"],"mappings":";AAAA,OAAO,UAAU;AAcV,SAAS,MAAM,OAAwB,OAAqB,CAAC,GAAqB;AACvF,MAAI;AACJ,MAAI,OAAO,UAAU,UAAU;AAC7B,QAAI;AACF,YAAM,KAAK,KAAK,KAAK;AAAA,IACvB,SAAS,KAAK;AACZ,YAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC3D,YAAM,IAAI,MAAM,qBAAqB,GAAG,EAAE;AAAA,IAC5C;AAAA,EACF,OAAO;AAEL,UAAM,EAAE,GAAG,MAAM;AAAA,EACnB;AAEA,MAAI,QAAQ,QAAQ,OAAO,QAAQ,YAAY,MAAM,QAAQ,GAAG,GAAG;AACjE,UAAM,IAAI,MAAM,wDAAwD;AAAA,EAC1E;AAEA,QAAM,MAAM;AACZ,MAAI,IAAI,SAAS,MAAM,QAAW;AAChC,UAAM,IAAI,MAAM,kCAAkC;AAAA,EACpD;AACA,MAAI,IAAI,SAAS,MAAM,GAAG;AACxB,UAAM,IAAI,MAAM,wBAAwB,OAAO,IAAI,SAAS,CAAC,CAAC,eAAe;AAAA,EAC/E;AAIA,MAAI,MAAM,QAAQ,IAAI,YAAY,CAAC,GAAG;AACpC,QAAI,YAAY,IAAK,IAAI,YAAY,EAAkB,IAAI,kBAAkB;AAAA,EAC/E;AACA,MAAI,MAAM,QAAQ,IAAI,OAAO,CAAC,GAAG;AAC/B,QAAI,OAAO,IAAK,IAAI,OAAO,EAAqC,IAAI,CAAC,MAAM;AACzE,YAAM,MAAM,EAAE,GAAG,EAAE;AACnB,UAAI,MAAM,QAAQ,IAAI,YAAY,CAAC,GAAG;AACpC,YAAI,YAAY,IAAK,IAAI,YAAY,EAAkB,IAAI,kBAAkB;AAAA,MAC/E;AACA,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AAEA,QAAM,WAAW;AAAA,IACf,GAAG;AAAA,IACH,SAAS;AAAA,IACT,GAAI,KAAK,eAAe,SAAY,EAAE,cAAc,KAAK,WAAW,IAAI,CAAC;AAAA,EAC3E;AACA,SAAO;AACT;AAEA,SAAS,mBAAmB,GAAyB;AAKnD,MAAK,EAAyC,WAAW,MAAM,UAAa,EAAE,aAAa,QAAW;AACpG,UAAM,OAAQ,EAAwB,QAAQ;AAC9C,UAAM,IAAI;AAAA,MACR,cAAc,IAAI;AAAA,IAEpB;AAAA,EACF;AACA,QAAM,MAAM,EAAE;AACd,QAAM,aAAwB;AAAA,IAC5B,GAAG;AAAA,IACH,UAAU,OAAO,QAAQ,WAAW,CAAC,GAAG,IAAK;AAAA,EAC/C;AACA,MAAI,MAAM,QAAQ,EAAE,QAAQ,GAAG;AAC7B,eAAW,WAAW,EAAE,SAAS,IAAI,kBAAkB;AAAA,EACzD;AACA,SAAO;AACT;;;ACpEO,IAAM,uBAAuB;AAC7B,IAAM,4BAA4B;;;ACKlC,SAAS,MAAM,WAAyC;AAC7D,QAAM,SAAS,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,GAAG,MAAM;AAC3C,UAAM,QAAQ,EAAE,gBAAgB;AAChC,UAAM,QAAQ,EAAE,gBAAgB;AAChC,WAAO,QAAQ,QAAQ,KAAK,QAAQ,QAAQ,IAAI;AAAA,EAClD,CAAC;AAED,QAAM,QAAgB,CAAC;AACvB,QAAM,mBAAgC,CAAC;AACvC,QAAM,iBAA4B,CAAC;AACnC,QAAM,aAAyD,CAAC;AAChE,QAAM,cAA4B,CAAC;AAEnC,QAAM,gBAAgB,oBAAI,IAAoB;AAC9C,QAAM,qBAAqB,oBAAI,IAAoB;AAEnD,aAAW,KAAK,QAAQ;AACtB,UAAM,OAAO,EAAE,gBAAgB;AAE/B,eAAW,KAAK,EAAE,SAAS,CAAC,GAAG;AAC7B,YAAM,OAAO,cAAc,IAAI,EAAE,IAAI;AACrC,UAAI,SAAS,QAAW;AACtB,oBAAY,KAAK;AAAA,UACf,UAAU;AAAA,UACV,MAAM;AAAA,UACN,SAAS,cAAc,EAAE,IAAI,sBAAsB,IAAI,UAAU,IAAI;AAAA,UACrE;AAAA,QACF,CAAC;AAAA,MACH,OAAO;AACL,sBAAc,IAAI,EAAE,MAAM,IAAI;AAAA,MAChC;AACA,YAAM,KAAK,CAAC;AAAA,IACd;AAEA,eAAW,KAAK,EAAE,cAAc,CAAC,GAAG;AAClC,YAAM,OAAO,mBAAmB,IAAI,EAAE,IAAI;AAC1C,UAAI,SAAS,QAAW;AACtB,oBAAY,KAAK;AAAA,UACf,UAAU;AAAA,UACV,MAAM;AAAA,UACN,SAAS,mBAAmB,EAAE,IAAI,sBAAsB,IAAI,UAAU,IAAI;AAAA,UAC1E;AAAA,QACF,CAAC;AAAA,MACH,OAAO;AACL,2BAAmB,IAAI,EAAE,MAAM,IAAI;AAAA,MACrC;AACA,uBAAiB,KAAK,CAAC;AAAA,IACzB;AAEA,eAAW,KAAK,EAAE,YAAY,CAAC,GAAG;AAChC,qBAAe,KAAK,CAAC;AAAA,IACvB;AAEA,QAAI,MAAM,QAAQ,EAAE,MAAM,KAAK,EAAE,OAAO,SAAS,GAAG;AAClD,iBAAW,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,KAAK,CAAC;AAAA,IAC7D;AAAA,EACF;AAEA,SAAO;AAAA,IACL,SAAS;AAAA,IACT;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,SAAS;AAAA,EACX;AACF;;;ACnFO,SAAS,gBAAgB,OAAuB;AACrD,MAAI,IAAI;AAER,QAAM,aAAa,gCAAgC,KAAK,CAAC;AACzD,MAAI,YAAY;AACd,QAAI,EAAE,MAAM,WAAW,CAAC,EAAE,MAAM,KAAK;AAAA,EACvC;AAEA,QAAM,OAAO,EAAE,QAAQ,GAAG;AAC1B,MAAI,SAAS,GAAI,KAAI,EAAE,MAAM,GAAG,IAAI;AAEpC,QAAM,IAAI,EAAE,QAAQ,GAAG;AACvB,MAAI,MAAM,GAAI,KAAI,EAAE,MAAM,GAAG,CAAC;AAE9B,MAAI,EAAE,SAAS,KAAK,EAAE,SAAS,GAAG,EAAG,KAAI,EAAE,MAAM,GAAG,EAAE;AACtD,SAAO;AACT;AAYO,SAAS,WAAW,SAAiB,KAAsB;AAChE,QAAM,IAAI,iBAAiB,OAAO;AAClC,QAAM,IAAI,gBAAgB,GAAG;AAC7B,QAAM,cAAc,cAAc,CAAC;AACnC,QAAM,UAAU,cAAc,CAAC;AAC/B,SAAO,UAAU,aAAa,OAAO;AACvC;AAEA,SAAS,iBAAiB,GAAmB;AAE3C,MAAI,IAAI,EACL,MAAM,GAAG,EACT,IAAI,CAAC,QAAS,IAAI,WAAW,GAAG,IAAI,MAAM,GAAI,EAC9C,KAAK,GAAG;AACX,MAAI,EAAE,SAAS,KAAK,EAAE,SAAS,GAAG,EAAG,KAAI,EAAE,MAAM,GAAG,EAAE;AACtD,SAAO;AACT;AAEA,SAAS,cAAc,MAAwB;AAC7C,MAAI,SAAS,OAAO,SAAS,GAAI,QAAO,CAAC;AACzC,QAAM,UAAU,KAAK,WAAW,GAAG,IAAI,KAAK,MAAM,CAAC,IAAI;AACvD,SAAO,QAAQ,MAAM,GAAG;AAC1B;AAEA,SAAS,UAAU,SAAmB,KAAwB;AAC5D,MAAI,QAAQ,WAAW,KAAK,IAAI,WAAW,EAAG,QAAO;AACrD,MAAI,QAAQ,WAAW,EAAG,QAAO;AAEjC,QAAM,OAAO,QAAQ,CAAC;AACtB,QAAM,OAAO,QAAQ,MAAM,CAAC;AAE5B,MAAI,SAAS,MAAM;AAEjB,QAAI,KAAK,WAAW,EAAG,QAAO;AAC9B,aAAS,IAAI,GAAG,KAAK,IAAI,QAAQ,KAAK;AACpC,UAAI,UAAU,MAAM,IAAI,MAAM,CAAC,CAAC,EAAG,QAAO;AAAA,IAC5C;AACA,WAAO;AAAA,EACT;AAEA,MAAI,IAAI,WAAW,EAAG,QAAO;AAC7B,MAAI,SAAS,OAAO,SAAS,IAAI,CAAC,GAAG;AACnC,WAAO,UAAU,MAAM,IAAI,MAAM,CAAC,CAAC;AAAA,EACrC;AACA,SAAO;AACT;;;ACpEO,SAAS,aACd,UACA,KACA,QACa;AAEb,MAAI,cAA2B;AAC/B,aAAW,KAAK,SAAS,OAAO;AAC9B,QAAI,WAAW,EAAE,OAAO,GAAG,GAAG;AAC5B,oBAAc;AACd;AAAA,IACF;AAAA,EACF;AAEA,QAAM,aAAkC,CAAC;AACzC,aAAW,KAAK,SAAS,kBAAkB;AACzC,eAAW,KAAK,GAAG,iBAAiB,GAAG,CAAC,GAAG,UAAU,MAAS,CAAC;AAAA,EACjE;AACA,MAAI,gBAAgB,QAAQ,MAAM,QAAQ,YAAY,UAAU,GAAG;AACjE,eAAW,KAAK,YAAY,YAAY;AACtC,iBAAW,KAAK,GAAG,iBAAiB,GAAG,CAAC,GAAG,eAAe,YAAY,IAAI,CAAC;AAAA,IAC7E;AAAA,EACF;AAEA,QAAM,WAA8B,CAAC;AACrC,QAAM,cAAyB;AAAA,IAC7B,GAAG,SAAS;AAAA,IACZ,GAAK,aAAa,YAAY,CAAC;AAAA,EACjC;AACA,aAAW,OAAO,aAAa;AAC7B,QAAI,CAAC,WAAW,IAAI,OAAO,GAAG,EAAG;AACjC,QAAI,WAAW,UAAa,IAAI,WAAW,UAAa,IAAI,WAAW,OAAQ;AAC/E,aAAS,KAAK,kBAAkB,GAAG,CAAC;AAAA,EACtC;AAEA,QAAM,SAAmB,CAAC;AAC1B,aAAW,MAAM,SAAS,WAAY,QAAO,KAAK,GAAG,GAAG,MAAM;AAC9D,MAAI,aAAa,OAAQ,QAAO,KAAK,GAAG,YAAY,MAAM;AAE1D,SAAO;AAAA,IACL,MAAM,gBAAgB,OAAO,eAAe,WAAW,IAAI;AAAA,IAC3D;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEO,SAAS,cAAc,UAAoB,MAA4B;AAC5E,QAAM,OAAqB,CAAC;AAC5B,aAAW,KAAK,SAAS,OAAO;AAC9B,QAAI,EAAE,SAAS,KAAM,MAAK,KAAK,EAAE,MAAM,QAAQ,WAAW,QAAQ,OAAO,eAAe,CAAC,EAAE,CAAC;AAAA,EAC9F;AACA,aAAW,KAAK,SAAS,kBAAkB;AACzC,eAAW,MAAM,iBAAiB,GAAG,CAAC,GAAG,UAAU,MAAS,GAAG;AAC7D,UAAI,GAAG,SAAS,KAAM,MAAK,KAAK,EAAE,MAAM,aAAa,WAAW,QAAQ,OAAO,GAAG,CAAC;AAAA,IACrF;AAAA,EACF;AACA,aAAW,KAAK,SAAS,OAAO;AAC9B,eAAW,KAAK,EAAE,cAAc,CAAC,GAAG;AAClC,iBAAW,MAAM,iBAAiB,GAAG,CAAC,GAAG,eAAe,EAAE,IAAI,GAAG;AAC/D,YAAI,GAAG,SAAS,KAAM,MAAK,KAAK,EAAE,MAAM,aAAa,WAAW,QAAQ,OAAO,GAAG,CAAC;AAAA,MACrF;AAAA,IACF;AAAA,EACF;AACA,aAAW,KAAK,SAAS,gBAAgB;AACvC,QAAI,EAAE,SAAS,KAAM,MAAK,KAAK,EAAE,MAAM,WAAW,WAAW,QAAQ,OAAO,kBAAkB,CAAC,EAAE,CAAC;AAAA,EACpG;AACA,aAAW,KAAK,SAAS,OAAO;AAC9B,eAAW,KAAK,EAAE,YAAY,CAAC,GAAG;AAChC,UAAI,EAAE,SAAS,KAAM,MAAK,KAAK,EAAE,MAAM,WAAW,WAAW,QAAQ,OAAO,kBAAkB,CAAC,EAAE,CAAC;AAAA,IACpG;AAAA,EACF;AACA,SAAO;AACT;AAEO,SAAS,oBAAoB,UAAoB,MAA4B;AAClF,QAAM,OAAqB,CAAC;AAC5B,aAAW,KAAK,SAAS,OAAO;AAC9B,QAAI,EAAE,WAAW,KAAM,MAAK,KAAK,EAAE,MAAM,QAAQ,WAAW,QAAQ,OAAO,eAAe,CAAC,EAAE,CAAC;AAAA,EAChG;AACA,aAAW,KAAK,SAAS,kBAAkB;AACzC,eAAW,MAAM,iBAAiB,GAAG,CAAC,GAAG,UAAU,MAAS,GAAG;AAC7D,UAAI,GAAG,WAAW,KAAM,MAAK,KAAK,EAAE,MAAM,aAAa,WAAW,QAAQ,OAAO,GAAG,CAAC;AAAA,IACvF;AAAA,EACF;AACA,aAAW,KAAK,SAAS,OAAO;AAC9B,eAAW,KAAK,EAAE,cAAc,CAAC,GAAG;AAClC,iBAAW,MAAM,iBAAiB,GAAG,CAAC,GAAG,eAAe,EAAE,IAAI,GAAG;AAC/D,YAAI,GAAG,WAAW,KAAM,MAAK,KAAK,EAAE,MAAM,aAAa,WAAW,QAAQ,OAAO,GAAG,CAAC;AAAA,MACvF;AAAA,IACF;AAAA,EACF;AACA,aAAW,KAAK,SAAS,gBAAgB;AACvC,QAAI,EAAE,WAAW,KAAM,MAAK,KAAK,EAAE,MAAM,WAAW,WAAW,QAAQ,OAAO,kBAAkB,CAAC,EAAE,CAAC;AAAA,EACtG;AACA,SAAO;AACT;AAEA,SAAS,iBACP,GACA,aACA,OACA,cACqB;AACrB,QAAM,MAA2B,CAAC;AAClC,QAAM,WAAW,MAAM,QAAQ,EAAE,QAAQ,IAAI,EAAE,WAAW,CAAC,EAAE,QAA6B;AAC1F,MAAI,KAAK;AAAA,IACP,MAAM,EAAE;AAAA,IACR;AAAA,IACA,GAAI,EAAE,WAAW,SAAY,EAAE,QAAQ,EAAE,OAAO,IAAI,CAAC;AAAA,IACrD,GAAI,EAAE,gBAAgB,SAAY,EAAE,aAAa,EAAE,YAAY,IAAI,CAAC;AAAA,IACpE,QAAQ,EAAE,SAAS,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;AAAA,IACpC,aAAa,CAAC,GAAG,WAAW;AAAA,IAC5B;AAAA,IACA,GAAI,iBAAiB,SAAY,EAAE,aAAa,IAAI,CAAC;AAAA,IACrD,WAAW,EAAE,MAAM,YAAY;AAAA,EACjC,CAAC;AACD,aAAW,SAAS,EAAE,YAAY,CAAC,GAAG;AACpC,QAAI,KAAK,GAAG,iBAAiB,OAAO,CAAC,GAAG,aAAa,EAAE,IAAI,GAAG,OAAO,YAAY,CAAC;AAAA,EACpF;AACA,SAAO;AACT;AAEA,SAAS,eAAe,GAAuB;AAC7C,SAAO;AAAA,IACL,MAAM,EAAE;AAAA,IACR,OAAO,EAAE;AAAA,IACT,GAAI,EAAE,WAAW,SAAY,EAAE,QAAQ,EAAE,OAAO,IAAI,CAAC;AAAA,IACrD,GAAI,EAAE,gBAAgB,SAAY,EAAE,aAAa,EAAE,YAAY,IAAI,CAAC;AAAA,IACpE,QAAQ,EAAE,SAAS,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;AAAA,IACpC,WAAW,EAAE,MAAM,YAAY;AAAA,EACjC;AACF;AAEA,SAAS,kBAAkB,GAA6B;AACtD,SAAO;AAAA,IACL,MAAM,EAAE;AAAA,IACR,OAAO,EAAE;AAAA,IACT,GAAI,EAAE,WAAW,SAAY,EAAE,QAAQ,EAAE,OAAO,IAAI,CAAC;AAAA,IACrD,GAAI,EAAE,WAAW,SAAY,EAAE,QAAQ,EAAE,OAAO,IAAI,CAAC;AAAA,IACrD,GAAI,EAAE,gBAAgB,SAAY,EAAE,aAAa,EAAE,YAAY,IAAI,CAAC;AAAA,IACpE,GAAI,EAAE,YAAY,SAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC;AAAA,IACjF,GAAI,EAAE,aAAa,SAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC;AAAA,IACpF,GAAI,EAAE,YAAY,SAAY,EAAE,SAAS,EAAE,QAAQ,IAAI,CAAC;AAAA,IACxD,QAAQ,EAAE,SAAS,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;AAAA,IACpC,WAAW,EAAE,MAAM,YAAY;AAAA,EACjC;AACF;;;ACtJO,SAAS,MAAM,UAAoB,MAAiC;AACzE,SAAO,aAAa,UAAU,KAAK,KAAK,KAAK,MAAM;AACrD;;;ACFO,SAAS,QACd,UACA,OACA,OAAuB,CAAC,GACT;AACf,QAAM,SAAS,KAAK,OAAO,SAAS,CAAC,IAAI,cAAc,UAAU,KAAK;AACtE,QAAM,SAAS,KAAK,OAAO,SAAS,CAAC,IAAI,oBAAoB,UAAU,KAAK;AAI5E,QAAM,MAAM,CAAC,MAA0B,GAAG,EAAE,IAAI,IAAI,EAAE,MAAM,IAAI;AAChE,QAAM,YAAY,IAAI,IAAI,OAAO,IAAI,GAAG,CAAC;AACzC,QAAM,WAAW,IAAI,IAAI,OAAO,IAAI,GAAG,CAAC;AAExC,QAAM,SAAuB,CAAC;AAC9B,aAAW,KAAK,QAAQ;AACtB,QAAI,SAAS,IAAI,IAAI,CAAC,CAAC,GAAG;AACxB,aAAO,KAAK,cAAc,GAAG,eAAe,CAAC;AAAA,IAC/C,OAAO;AACL,aAAO,KAAK,CAAC;AAAA,IACf;AAAA,EACF;AACA,aAAW,KAAK,QAAQ;AACtB,QAAI,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,GAAG;AAC1B,aAAO,KAAK,CAAC;AAAA,IACf;AAAA,EAEF;AAEA,QAAM,WACJ,KAAK,SAAS,SAAY,OAAO,OAAO,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,IAAI;AACzE,SAAO,EAAE,OAAO,MAAM,SAAS;AACjC;AAEA,SAAS,cAAc,GAAe,WAAyC;AAC7E,UAAQ,EAAE,MAAM;AAAA,IACd,KAAK;AACH,aAAO,EAAE,MAAM,QAAQ,WAAW,OAAO,EAAE,MAAM;AAAA,IACnD,KAAK;AACH,aAAO,EAAE,MAAM,aAAa,WAAW,OAAO,EAAE,MAAM;AAAA,IACxD,KAAK;AACH,aAAO,EAAE,MAAM,WAAW,WAAW,OAAO,EAAE,MAAM;AAAA,EACxD;AACF;","names":[]}

package/dist/cli/index.js

@@ -22,6 +22,9 @@ var DUPLICATE_ROUTE = "duplicate-route";
 var ROUTE_SHADOWING = "route-shadowing";
 var UNKNOWN_SOURCE = "unknown-source";
 var SELECTOR_SYNTAX = "selector-syntax";
+var FMT_NOT_CANONICAL = "fmt.not-canonical";
+var FMT_PARSE_ERROR = "fmt.parse-error";
+var FMT_SCHEMA_INVALID = "fmt.schema-invalid";
 var CONVENTION_SEP_FILENAME = "convention.sep-filename";
 var CONVENTION_FIXTURE_DIRNAME = "convention.fixture-dirname";
 
@@ -270,6 +273,47 @@ function formatExplain(r) {
   }
   return lines.join("\n");
 }
+function formatFmtCheck(lines) {
+  const body = lines.map((l) => {
+    switch (l.status) {
+      case "ok":
+        return `${l.path}: ok`;
+      case "not-canonical":
+        return `${l.path}: not canonical (run \`sightmap fmt --write\` to fix)`;
+      case "error":
+        return `${l.path}: error`;
+      case "rewritten":
+        return `${l.path}: rewritten`;
+    }
+  }).join("\n");
+  const need = lines.filter((l) => l.status === "not-canonical").length;
+  const total = lines.length;
+  const summary = total === 0 ? `No YAML files found.` : need === 0 ? `
+
+All ${total} file(s) canonical.` : `
+
+${need} of ${total} file(s) need formatting.`;
+  return body + summary;
+}
+function formatFmtWrite(lines) {
+  const body = lines.map((l) => {
+    switch (l.status) {
+      case "ok":
+        return `${l.path}: ok`;
+      case "rewritten":
+        return `${l.path}: rewritten`;
+      case "error":
+        return `${l.path}: error`;
+      case "not-canonical":
+        return `${l.path}: not canonical`;
+    }
+  }).join("\n");
+  const rewritten = lines.filter((l) => l.status === "rewritten").length;
+  const summary = lines.length === 0 ? `No YAML files found.` : `
+
+${rewritten} file(s) rewritten.`;
+  return body + summary;
+}
 
 // src/cli/validate.ts
 async function runValidate(opts) {
@@ -1082,6 +1126,377 @@ async function runCheckConventions(opts) {
   return result.ok ? 0 : 1;
 }
 
+// src/cli/fmt.ts
+import { readFile as readFile3, stat as stat2, writeFile } from "fs/promises";
+import { resolve as resolve10, relative as relative5 } from "path";
+
+// src/format/canonicalize.ts
+import { parseDocument, isMap, isSeq, isScalar } from "yaml";
+
+// src/format/canonical-rules.ts
+var TOP_LEVEL_KEY_ORDER = [
+  "version",
+  "memory",
+  "views",
+  "components",
+  "requests"
+];
+var VIEW_KEY_ORDER = [
+  "name",
+  "route",
+  "description",
+  "components",
+  "memory",
+  "requests"
+];
+var COMPONENT_KEY_ORDER = [
+  "name",
+  "selector",
+  "description",
+  "children",
+  "memory"
+];
+var REQUEST_KEY_ORDER = [
+  "name",
+  "route",
+  "method",
+  "description",
+  "source",
+  "request",
+  "response",
+  "headers",
+  "memory"
+];
+function compareByName(a, b) {
+  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+function compareRequests(a, b) {
+  if (a.route !== b.route) return a.route < b.route ? -1 : 1;
+  const am = a.method ?? "";
+  const bm = b.method ?? "";
+  return am < bm ? -1 : am > bm ? 1 : 0;
+}
+
+// src/format/canonicalize.ts
+function canonicalize(input, opts) {
+  const doc = parseDocument(input, { keepSourceTokens: false });
+  const first = doc.errors[0];
+  if (first !== void 0) {
+    const loc = first.linePos?.[0] ? { line: first.linePos[0].line, column: first.linePos[0].col } : void 0;
+    return {
+      kind: "parse-error",
+      diagnostics: [
+        {
+          severity: "error",
+          code: FMT_PARSE_ERROR,
+          message: first.message,
+          file: opts.file,
+          ...loc !== void 0 ? { loc } : {}
+        }
+      ]
+    };
+  }
+  const v = validate(input, { sourceFile: opts.file });
+  if (!v.ok) {
+    const diagnostics = v.diagnostics.map((d) => ({
+      ...d,
+      severity: "error",
+      code: FMT_SCHEMA_INVALID,
+      file: opts.file
+    }));
+    return { kind: "schema-invalid", diagnostics };
+  }
+  if (isMap(doc.contents)) {
+    reorderTopLevelKeys(doc.contents);
+    reorderEntriesUnder(doc.contents, "views", VIEW_KEY_ORDER);
+    reorderEntriesUnder(doc.contents, "components", COMPONENT_KEY_ORDER);
+    reorderEntriesUnder(doc.contents, "requests", REQUEST_KEY_ORDER);
+    forEachViewEntry(doc.contents, (view) => {
+      reorderEntriesUnder(view, "components", COMPONENT_KEY_ORDER);
+      reorderEntriesUnder(view, "requests", REQUEST_KEY_ORDER);
+      forEachComponentEntry(view, "components", (cmp) => {
+        reorderChildrenRecursive(cmp);
+      });
+    });
+    forEachComponentEntry(doc.contents, "components", (cmp) => {
+      reorderChildrenRecursive(cmp);
+    });
+    sortTopLevelSeq(doc.contents, "views", (a, b) => {
+      const an = scalarPropFromMapItem(a, "name");
+      const bn = scalarPropFromMapItem(b, "name");
+      return compareByName({ name: an ?? "" }, { name: bn ?? "" });
+    });
+    sortTopLevelSeq(doc.contents, "components", (a, b) => {
+      const an = scalarPropFromMapItem(a, "name");
+      const bn = scalarPropFromMapItem(b, "name");
+      return compareByName({ name: an ?? "" }, { name: bn ?? "" });
+    });
+    sortTopLevelSeq(doc.contents, "requests", (a, b) => {
+      return compareRequests(
+        { route: scalarPropFromMapItem(a, "route") ?? "", method: scalarPropFromMapItem(a, "method") },
+        { route: scalarPropFromMapItem(b, "route") ?? "", method: scalarPropFromMapItem(b, "method") }
+      );
+    });
+    visitAllScalars(doc, (scalar) => {
+      if (typeof scalar.value !== "string") return;
+      scalar.type = chooseQuoteType(scalar.value);
+    });
+    normalizeBlankLines(doc);
+  }
+  const output = serialize(doc);
+  return { kind: "canonical", text: output, changed: output !== input };
+}
+function reorderTopLevelKeys(map) {
+  reorderMapKeys(map, TOP_LEVEL_KEY_ORDER);
+}
+function reorderMapKeys(map, keyOrder) {
+  const items = map.items;
+  const byKey = /* @__PURE__ */ new Map();
+  const unknownInOrder = [];
+  for (const item of items) {
+    const key = scalarKey(item);
+    if (key === null) {
+      unknownInOrder.push(item);
+      continue;
+    }
+    if (keyOrder.includes(key)) {
+      byKey.set(key, item);
+    } else {
+      unknownInOrder.push(item);
+    }
+  }
+  const reordered = [];
+  for (const k of keyOrder) {
+    const p = byKey.get(k);
+    if (p !== void 0) reordered.push(p);
+  }
+  reordered.push(...unknownInOrder);
+  map.items = reordered;
+}
+function reorderEntriesUnder(map, key, keyOrder) {
+  const seq = lookupSeq(map, key);
+  if (seq === null) return;
+  for (const item of seq.items) {
+    if (isMap(item)) reorderMapKeys(item, keyOrder);
+  }
+}
+function forEachViewEntry(root, fn) {
+  const seq = lookupSeq(root, "views");
+  if (seq === null) return;
+  for (const item of seq.items) {
+    if (isMap(item)) fn(item);
+  }
+}
+function forEachComponentEntry(root, key, fn) {
+  const seq = lookupSeq(root, key);
+  if (seq === null) return;
+  for (const item of seq.items) {
+    if (isMap(item)) fn(item);
+  }
+}
+function reorderChildrenRecursive(cmp) {
+  const children = lookupSeq(cmp, "children");
+  if (children === null) return;
+  for (const child of children.items) {
+    if (!isMap(child)) continue;
+    reorderMapKeys(child, COMPONENT_KEY_ORDER);
+    reorderChildrenRecursive(child);
+  }
+}
+function lookupSeq(map, key) {
+  for (const item of map.items) {
+    if (scalarKey(item) === key && isSeq(item.value)) return item.value;
+  }
+  return null;
+}
+function scalarKey(pair) {
+  const k = pair.key ?? null;
+  if (k === null) return null;
+  const v = typeof k === "object" && k !== null && "value" in k ? k.value : k;
+  return typeof v === "string" ? v : null;
+}
+function sortTopLevelSeq(root, key, cmp) {
+  const seq = lookupSeq(root, key);
+  if (seq === null) return;
+  seq.items = seq.items.slice().sort(cmp);
+}
+function scalarPropFromMapItem(item, key) {
+  if (!isMap(item)) return void 0;
+  for (const pair of item.items) {
+    if (scalarKey(pair) !== key) continue;
+    const v = pair.value;
+    if (v !== null && typeof v === "object" && "value" in v) {
+      const inner = v.value;
+      return typeof inner === "string" ? inner : void 0;
+    }
+    return typeof v === "string" ? v : void 0;
+  }
+  return void 0;
+}
+function visitAllScalars(doc, fn) {
+  walk(doc.contents, fn);
+}
+function walk(node, fn) {
+  if (node === null || node === void 0) return;
+  if (isScalar(node)) {
+    fn(node);
+    return;
+  }
+  if (isMap(node)) {
+    for (const pair of node.items) {
+      walk(pair.key, fn);
+      walk(pair.value, fn);
+    }
+    return;
+  }
+  if (isSeq(node)) {
+    for (const item of node.items) walk(item, fn);
+  }
+}
+function normalizeBlankLines(doc) {
+  const root = doc.contents;
+  if (!isMap(root)) return;
+  const firstPair = root.items[0];
+  if (firstPair !== void 0) {
+    const keyNode = firstPair.key;
+    const docMutable = doc;
+    const keyComment = keyNode?.commentBefore;
+    const docComment = docMutable.commentBefore;
+    if (typeof keyComment === "string" && keyComment.length > 0) {
+      docMutable.commentBefore = keyComment;
+      keyNode.commentBefore = null;
+    }
+    const hasHeader = typeof docMutable.commentBefore === "string" && docMutable.commentBefore.length > 0 || typeof docComment === "string" && docComment.length > 0;
+    firstPair.spaceBefore = hasHeader;
+  }
+  for (const key of ["views", "components", "requests"]) {
+    const seq = lookupSeq(root, key);
+    if (seq === null) continue;
+    seq.items.forEach((item, idx) => {
+      if (typeof item === "object" && item !== null) {
+        item.spaceBefore = idx > 0;
+      }
+    });
+    for (const item of seq.items) {
+      if (isMap(item)) clearInnerBlankLines(item);
+    }
+  }
+}
+function clearInnerBlankLines(map) {
+  for (const pair of map.items) {
+    pair.spaceBefore = false;
+    if (isSeq(pair.value)) {
+      for (const item of pair.value.items) {
+        if (typeof item === "object" && item !== null) {
+          item.spaceBefore = false;
+        }
+        if (isMap(item)) clearInnerBlankLines(item);
+      }
+    } else if (isMap(pair.value)) {
+      clearInnerBlankLines(pair.value);
+    }
+  }
+}
+function chooseQuoteType(value) {
+  if (requiresDoubleQuotes(value)) return "QUOTE_DOUBLE";
+  if (value.includes('"')) return "QUOTE_SINGLE";
+  if (isPlainSafe(value)) return "PLAIN";
+  return "QUOTE_SINGLE";
+}
+function requiresDoubleQuotes(s) {
+  return /[\x00-\x1f]/.test(s);
+}
+function isPlainSafe(s) {
+  if (s.length === 0) return false;
+  const first = s[0];
+  if ("-?:,[]{}#&*!|>'\"%@`".includes(first)) return false;
+  if (first === " " || first === "	") return false;
+  if (s.includes(": ")) return false;
+  if (s.includes(" #")) return false;
+  if (/^(true|false|null|~|y|n|yes|no|on|off|True|False|Null|Yes|No|On|Off|TRUE|FALSE|NULL|YES|NO|ON|OFF)$/.test(s)) return false;
+  if (/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(s)) return false;
+  if (/^0[xob]/.test(s)) return false;
+  return true;
+}
+function serialize(doc) {
+  const out = doc.toString({
+    indent: 2,
+    lineWidth: 0,
+    minContentWidth: 0,
+    blockQuote: "literal"
+  });
+  return out.endsWith("\n") ? out : out + "\n";
+}
+
+// src/cli/fmt.ts
+async function runFmt(opts) {
+  const target = resolve10(opts.cwd, opts.path);
+  const files = (await resolveTarget(target)).sort();
+  const fileResults = [];
+  const diagnostics = [];
+  for (const file of files) {
+    const relPath = relative5(opts.cwd, file);
+    await processFile(file, relPath, opts, fileResults, diagnostics);
+  }
+  const errCount = diagnostics.filter((d) => d.severity === "error").length;
+  const warnCount = diagnostics.filter((d) => d.severity === "warning").length;
+  const ok = errCount === 0 && warnCount === 0;
+  if (opts.json) {
+    emitJson(
+      makeEnvelope({
+        command: "fmt",
+        ok,
+        diagnostics,
+        result: { files: fileResults }
+      })
+    );
+  } else {
+    const lines = fileResults.map((f) => {
+      const hasErr = diagnostics.some((d) => d.severity === "error" && d.file === f.path);
+      if (hasErr) return { path: f.path, status: "error" };
+      if (opts.write) {
+        return { path: f.path, status: f.changed ? "rewritten" : "ok" };
+      }
+      return { path: f.path, status: f.matchesExpected ? "ok" : "not-canonical" };
+    });
+    const out = opts.write ? formatFmtWrite(lines) : formatFmtCheck(lines);
+    process.stdout.write(out + "\n");
+  }
+  if (errCount > 0) return 2;
+  if (warnCount > 0) return 1;
+  return 0;
+}
+async function resolveTarget(target) {
+  const st = await stat2(target);
+  if (st.isFile()) return [target];
+  return collectYamlFiles(target);
+}
+async function processFile(absPath, relPath, opts, fileResults, diagnostics) {
+  const text = await readFile3(absPath, "utf8");
+  const result = canonicalize(text, { file: relPath });
+  if (result.kind === "parse-error" || result.kind === "schema-invalid") {
+    diagnostics.push(...result.diagnostics);
+    fileResults.push(opts.write ? { path: relPath, changed: false } : { path: relPath, matchesExpected: false });
+    return;
+  }
+  if (opts.write) {
+    if (result.changed) {
+      await writeFile(absPath, result.text, "utf8");
+    }
+    fileResults.push({ path: relPath, changed: result.changed });
+    return;
+  }
+  fileResults.push({ path: relPath, matchesExpected: !result.changed });
+  if (result.changed) {
+    diagnostics.push({
+      severity: "warning",
+      code: FMT_NOT_CANONICAL,
+      message: "file is not in canonical form (run `sightmap fmt --write` to fix)",
+      file: relPath
+    });
+  }
+}
+
 // src/cli/index.ts
 var program = new Command();
 program.name("sightmap").description("CLI for the Sightmap spec \u2014 validate, lint, match, explain.").version("0.1.0");
@@ -1158,6 +1573,23 @@ program.command("check-conventions [path]").description("Validate repo filename
   });
   process.exit(code);
 });
+program.command("fmt [path]").description("Canonicalize .sightmap/*.yaml files (default --check; --write to fix in place).").option("--check", "exit non-zero if any file is not canonical (default mode)").option("--write", "rewrite non-canonical files in place").option("--json", "machine-readable output").action(
+  async (path, opts) => {
+    if (opts.check === true && opts.write === true) {
+      process.stderr.write("fatal: --check and --write are mutually exclusive\n");
+      process.exit(2);
+    }
+    const code = await runFmt({
+      path: path ?? ".sightmap",
+      cwd: program.opts().cwd,
+      check: opts.write !== true,
+      // default true unless --write
+      write: opts.write === true,
+      json: opts.json === true
+    });
+    process.exit(code);
+  }
+);
 program.parseAsync(process.argv).catch((err) => {
   process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}
 `);