@sightmap/sightmap 0.1.0 → 0.2.1

package/dist/browser.js.map

@@ -0,0 +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":[]}

package/dist/cli/index.js

@@ -22,6 +22,8 @@ var DUPLICATE_ROUTE = "duplicate-route";
 var ROUTE_SHADOWING = "route-shadowing";
 var UNKNOWN_SOURCE = "unknown-source";
 var SELECTOR_SYNTAX = "selector-syntax";
+var CONVENTION_SEP_FILENAME = "convention.sep-filename";
+var CONVENTION_FIXTURE_DIRNAME = "convention.fixture-dirname";
 
 // src/parse.ts
 import yaml from "js-yaml";
@@ -67,6 +69,12 @@ function parse(input, opts = {}) {
   return fragment;
 }
 function normalizeComponent(c) {
+  if (c["selectors"] !== void 0 && c.selector === void 0) {
+    const name = c.name ?? "(unnamed)";
+    throw new Error(
+      `Component "${name}": use \`selector\` (singular), not \`selectors\` (plural). \`selector\` accepts either a single string or an array of strings.`
+    );
+  }
   const sel = c.selector;
   const normalized = {
     ...c,
@@ -82,20 +90,25 @@ function normalizeComponent(c) {
 import { existsSync, readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { resolve, dirname } from "path";
-var __dirname = dirname(fileURLToPath(import.meta.url));
-var schemaCandidates = [
-  resolve(__dirname, "./vendored/sightmap.schema.json"),
-  resolve(__dirname, "../vendored/sightmap.schema.json")
-];
-var schemaPath = schemaCandidates.find((p) => existsSync(p));
-if (schemaPath === void 0) {
-  throw new Error(
-    `vendored sightmap.schema.json not found. Looked in: ${schemaCandidates.join(", ")}`
-  );
+var _ajvValidate;
+function getValidator() {
+  if (_ajvValidate) return _ajvValidate;
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const schemaCandidates = [
+    resolve(__dirname, "./vendored/sightmap.schema.json"),
+    resolve(__dirname, "../vendored/sightmap.schema.json")
+  ];
+  const schemaPath = schemaCandidates.find((p) => existsSync(p));
+  if (schemaPath === void 0) {
+    throw new Error(
+      `vendored sightmap.schema.json not found. Looked in: ${schemaCandidates.join(", ")}`
+    );
+  }
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  _ajvValidate = ajv.compile(schema);
+  return _ajvValidate;
 }
-var schema = JSON.parse(readFileSync(schemaPath, "utf8"));
-var ajv = new Ajv2020({ allErrors: true, strict: false });
-var ajvValidate = ajv.compile(schema);
 function validate(input, opts = {}) {
   const diagnostics = [];
   let doc;
@@ -136,6 +149,7 @@ function validate(input, opts = {}) {
     });
     return { ok: false, diagnostics };
   }
+  const ajvValidate = getValidator();
   const ok = ajvValidate(obj);
   if (!ok) {
     for (const e of ajvValidate.errors ?? []) {
@@ -241,6 +255,12 @@ function formatMatch(r) {
   }
   return lines.join("\n");
 }
+function formatCheckConventions(diags) {
+  if (diags.length === 0) return "check-conventions: ok";
+  return formatDiagnostics(diags) + `
+
+${diags.length} convention violation(s).`;
+}
 function formatExplain(r) {
   if (r.hits.length === 0) return `no hits for "${r.query}".`;
   const lines = [`${r.hits.length} hit(s) for "${r.query}":`];
@@ -425,85 +445,41 @@ function duplicateRoute(sightmap) {
   return out;
 }
 
-// src/routeMatch.ts
-function canonicalizeUrl(input) {
-  let s = input;
-  const protoMatch = /^[a-z][a-z0-9+.-]*:\/\/[^/]*/i.exec(s);
-  if (protoMatch) {
-    s = s.slice(protoMatch[0].length) || "/";
-  }
-  const hash = s.indexOf("#");
-  if (hash !== -1) s = s.slice(0, hash);
-  const q = s.indexOf("?");
-  if (q !== -1) s = s.slice(0, q);
-  if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
-  return s;
-}
-function routeMatch(pattern, url) {
-  const p = normalizePattern(pattern);
-  const u = canonicalizeUrl(url);
-  const patternSegs = splitSegments(p);
-  const urlSegs = splitSegments(u);
-  return matchSegs(patternSegs, urlSegs);
-}
-function normalizePattern(p) {
-  let s = p.split("/").map((seg) => seg.startsWith(":") ? "*" : seg).join("/");
-  if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
-  return s;
-}
-function splitSegments(path) {
-  if (path === "/" || path === "") return [];
-  const trimmed = path.startsWith("/") ? path.slice(1) : path;
-  return trimmed.split("/");
-}
-function matchSegs(pattern, url) {
-  if (pattern.length === 0 && url.length === 0) return true;
-  if (pattern.length === 0) return false;
-  const head = pattern[0];
-  const rest = pattern.slice(1);
-  if (head === "**") {
-    if (rest.length === 0) return true;
-    for (let i = 0; i <= url.length; i++) {
-      if (matchSegs(rest, url.slice(i))) return true;
-    }
-    return false;
-  }
-  if (url.length === 0) return false;
-  if (head === "*" || head === url[0]) {
-    return matchSegs(rest, url.slice(1));
-  }
-  return false;
-}
-
 // src/lintRules/routeShadowing.ts
 function routeShadowing(sightmap) {
   const out = [];
   const views = sightmap.views;
   for (let j = 1; j < views.length; j++) {
     const later = views[j];
-    const representative = makeRepresentativeUrl(later.route);
+    const laterKey = matchSetKey(later.route);
+    const laterScore = specificity(later.route);
     for (let i = 0; i < j; i++) {
       const earlier = views[i];
       if (earlier.route === later.route) continue;
-      if (routeMatch(earlier.route, representative)) {
-        out.push({
-          severity: "warning",
-          code: ROUTE_SHADOWING,
-          message: `Route "${later.route}" (view "${later.name}") is shadowed by earlier route "${earlier.route}" (view "${earlier.name}"); first-match-wins makes it unreachable.`
-        });
-        break;
-      }
+      if (matchSetKey(earlier.route) !== laterKey) continue;
+      if (specificity(earlier.route) < laterScore) continue;
+      out.push({
+        severity: "warning",
+        code: ROUTE_SHADOWING,
+        message: `Route "${later.route}" (view "${later.name}") is shadowed by earlier route "${earlier.route}" (view "${earlier.name}"); they match the same URLs and the earlier route is at least as specific, making this route unreachable.`
+      });
+      break;
     }
   }
   return out;
 }
-function makeRepresentativeUrl(route) {
-  const result = route.split("/").filter((seg) => seg !== "**").map((seg) => {
-    if (seg === "*") return "__seg__";
-    if (seg.startsWith(":")) return "__seg__";
-    return seg;
-  }).join("/").replace(/^\/+/, "/");
-  return result || "/";
+function matchSetKey(route) {
+  return route.split("/").map((seg) => seg.startsWith(":") ? "*" : seg).join("/");
+}
+function specificity(route) {
+  let total = 0;
+  for (const seg of route.split("/")) {
+    if (seg === "" || seg === "**") continue;
+    if (seg === "*") total += 1;
+    else if (seg.startsWith(":")) total += 2;
+    else total += 3;
+  }
+  return total;
 }
 
 // src/lintRules/unknownSource.ts
@@ -631,6 +607,56 @@ function parseRules(spec) {
 // src/cli/match.ts
 import { resolve as resolve6 } from "path";
 
+// src/routeMatch.ts
+function canonicalizeUrl(input) {
+  let s = input;
+  const protoMatch = /^[a-z][a-z0-9+.-]*:\/\/[^/]*/i.exec(s);
+  if (protoMatch) {
+    s = s.slice(protoMatch[0].length) || "/";
+  }
+  const hash = s.indexOf("#");
+  if (hash !== -1) s = s.slice(0, hash);
+  const q = s.indexOf("?");
+  if (q !== -1) s = s.slice(0, q);
+  if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
+  return s;
+}
+function routeMatch(pattern, url) {
+  const p = normalizePattern(pattern);
+  const u = canonicalizeUrl(url);
+  const patternSegs = splitSegments(p);
+  const urlSegs = splitSegments(u);
+  return matchSegs(patternSegs, urlSegs);
+}
+function normalizePattern(p) {
+  let s = p.split("/").map((seg) => seg.startsWith(":") ? "*" : seg).join("/");
+  if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
+  return s;
+}
+function splitSegments(path) {
+  if (path === "/" || path === "") return [];
+  const trimmed = path.startsWith("/") ? path.slice(1) : path;
+  return trimmed.split("/");
+}
+function matchSegs(pattern, url) {
+  if (pattern.length === 0 && url.length === 0) return true;
+  if (pattern.length === 0) return false;
+  const head = pattern[0];
+  const rest = pattern.slice(1);
+  if (head === "**") {
+    if (rest.length === 0) return true;
+    for (let i = 0; i <= url.length; i++) {
+      if (matchSegs(rest, url.slice(i))) return true;
+    }
+    return false;
+  }
+  if (url.length === 0) return false;
+  if (head === "*" || head === url[0]) {
+    return matchSegs(rest, url.slice(1));
+  }
+  return false;
+}
+
 // src/resolver.ts
 function resolveByUrl(sightmap, url, method) {
   let matchedView = null;
@@ -852,6 +878,210 @@ async function runExplain(opts) {
   return code;
 }
 
+// src/cli/check.ts
+import { resolve as resolve8, relative as relative3 } from "path";
+async function runCheck(opts) {
+  const dir = resolve8(opts.cwd, opts.path);
+  const files = (await collectYamlFiles(dir)).sort();
+  const sightmap = await loadDirectory(dir, { diagnosticRoot: opts.cwd });
+  const diagnostics = [...sightmap.diagnostics];
+  if (opts.level === "quality") {
+    const lintDiags = await lint(sightmap, { root: opts.cwd });
+    diagnostics.push(...lintDiags);
+  }
+  const flagged = new Set(
+    diagnostics.filter((d) => d.file !== void 0).map((d) => d.file)
+  );
+  const fileResults = files.map((file) => {
+    const relPath = relative3(opts.cwd, file);
+    return { path: relPath, ok: !flagged.has(relPath) };
+  });
+  const ok = diagnostics.length === 0;
+  if (opts.json) {
+    emitJson(
+      makeEnvelope({
+        command: "check",
+        ok,
+        diagnostics,
+        result: {
+          files: fileResults,
+          level: opts.level,
+          views: sightmap.views.length
+        }
+      })
+    );
+  } else {
+    process.stdout.write(formatValidate({ files: fileResults }, diagnostics) + "\n");
+  }
+  return ok ? 0 : 1;
+}
+async function readAllStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function runCheckFromStdin(opts) {
+  const text = opts.input ?? await readAllStdin();
+  const sourceFile = "<stdin>";
+  const diagnostics = [];
+  const validation = validate(text, { sourceFile });
+  let viewCount = 0;
+  if (!validation.ok) {
+    diagnostics.push(...validation.diagnostics);
+  } else {
+    const sightmap = merge([validation.value]);
+    viewCount = sightmap.views.length;
+    if (opts.level === "quality") {
+      diagnostics.push(...sightmap.diagnostics);
+      const lintDiags = await lint(sightmap);
+      diagnostics.push(...lintDiags);
+    }
+  }
+  const ok = diagnostics.length === 0;
+  const fileResults = [{ path: sourceFile, ok }];
+  if (opts.json) {
+    emitJson(
+      makeEnvelope({
+        command: "check",
+        ok,
+        diagnostics,
+        result: { files: fileResults, level: opts.level, views: viewCount }
+      })
+    );
+  } else {
+    process.stdout.write(formatValidate({ files: fileResults }, diagnostics) + "\n");
+  }
+  return ok ? 0 : 1;
+}
+
+// src/cli/checkConventions.ts
+import { resolve as resolve9 } from "path";
+
+// src/conventions/walker.ts
+import { readdir as readdir3 } from "fs/promises";
+import { join as join3, relative as relative4 } from "path";
+import { existsSync as existsSync2 } from "fs";
+
+// src/conventions/slug.ts
+var SLUG_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function isValidSlug(s) {
+  return SLUG_REGEX.test(s);
+}
+
+// src/conventions/rules.ts
+var SEP_FILE_RE = /^seps\/(\d{4})-(.+)\.md$/;
+var FIXTURE_DIR_RE = /^conformance\/(\d{3})-(.+)\.fixture$/;
+function checkSepFilename(relPath) {
+  const m = relPath.match(SEP_FILE_RE);
+  if (!m) {
+    return mkFail(
+      CONVENTION_SEP_FILENAME,
+      relPath,
+      `SEP filename must match seps/NNNN-{slug}.md (got "${relPath}")`
+    );
+  }
+  const slug = m[2];
+  if (!isValidSlug(slug)) {
+    return mkFail(
+      CONVENTION_SEP_FILENAME,
+      relPath,
+      `SEP slug "${slug}" violates ^[a-z0-9]+(-[a-z0-9]+)*$`
+    );
+  }
+  return { ok: true };
+}
+function checkFixtureDirname(relPath) {
+  const m = relPath.match(FIXTURE_DIR_RE);
+  if (!m) {
+    if (relPath.startsWith("conformance/") && !relPath.endsWith(".fixture")) {
+      return mkFail(
+        CONVENTION_FIXTURE_DIRNAME,
+        relPath,
+        `fixture directory must match conformance/NNN-{slug}.fixture/ (got "${relPath}"); did you forget the .fixture suffix?`
+      );
+    }
+    return mkFail(
+      CONVENTION_FIXTURE_DIRNAME,
+      relPath,
+      `fixture directory must match conformance/NNN-{slug}.fixture/ (got "${relPath}")`
+    );
+  }
+  const slug = m[2];
+  if (!isValidSlug(slug)) {
+    return mkFail(
+      CONVENTION_FIXTURE_DIRNAME,
+      relPath,
+      `fixture slug "${slug}" violates ^[a-z0-9]+(-[a-z0-9]+)*$`
+    );
+  }
+  return { ok: true };
+}
+function mkFail(code, file, message) {
+  return {
+    ok: false,
+    diagnostics: [
+      {
+        severity: "error",
+        code,
+        message,
+        file
+      }
+    ]
+  };
+}
+
+// src/conventions/walker.ts
+var IGNORED_LEAF_NAMES = /* @__PURE__ */ new Set(["README.md", ".gitkeep", ".DS_Store"]);
+async function walkRepo(opts) {
+  const diagnostics = [];
+  const root = opts.root;
+  const sepsDir = join3(root, "seps");
+  if (existsSync2(sepsDir)) {
+    const entries = await readdir3(sepsDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isFile()) continue;
+      if (IGNORED_LEAF_NAMES.has(e.name)) continue;
+      if (!e.name.endsWith(".md")) continue;
+      const rel = relative4(root, join3(sepsDir, e.name));
+      const r = checkSepFilename(rel);
+      if (!r.ok && r.diagnostics) diagnostics.push(...r.diagnostics);
+    }
+  }
+  const confDir = join3(root, "conformance");
+  if (existsSync2(confDir)) {
+    const entries = await readdir3(confDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (IGNORED_LEAF_NAMES.has(e.name)) continue;
+      const rel = relative4(root, join3(confDir, e.name));
+      const r = checkFixtureDirname(rel);
+      if (!r.ok && r.diagnostics) diagnostics.push(...r.diagnostics);
+    }
+  }
+  return { ok: diagnostics.length === 0, diagnostics };
+}
+
+// src/cli/checkConventions.ts
+async function runCheckConventions(opts) {
+  const root = resolve9(opts.cwd, opts.path);
+  const result = await walkRepo({ root });
+  if (opts.json) {
+    emitJson(
+      makeEnvelope({
+        command: "check-conventions",
+        ok: result.ok,
+        diagnostics: result.diagnostics,
+        result: { root }
+      })
+    );
+  } else {
+    process.stdout.write(formatCheckConventions(result.diagnostics) + "\n");
+  }
+  return result.ok ? 0 : 1;
+}
+
 // 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");
@@ -874,6 +1104,25 @@ program.command("lint [path]").description("Run quality checks beyond schema.").
   });
   process.exit(code);
 });
+program.command("check [path]").description("Run schema + quality checks (combined validate + lint).").option("--json", "machine-readable output").option("--level <level>", "'schema' or 'quality' (default 'quality')", "quality").option("--stdin", "read sightmap content from stdin instead of a path").action(
+  async (path, opts) => {
+    const level = opts.level === "schema" ? "schema" : "quality";
+    if (opts.stdin === true) {
+      const stdinCode = await runCheckFromStdin({
+        level,
+        json: opts.json === true
+      });
+      process.exit(stdinCode);
+    }
+    const code = await runCheck({
+      path: path ?? ".sightmap",
+      cwd: program.opts().cwd,
+      level,
+      json: opts.json === true
+    });
+    process.exit(code);
+  }
+);
 program.command("match <url> [path]").description("Resolve sightmap context for a URL.").option("--method <m>", "HTTP method filter for requests").option("--json", "machine-readable output").option("--require-view", "exit 1 if no view matched").action(
   async (url, path, opts) => {
     const code = await runMatch({
@@ -901,6 +1150,14 @@ program.command("explain <query> [path]").description("Look up sightmap entries
     process.exit(code);
   }
 );
+program.command("check-conventions [path]").description("Validate repo filename conventions (SEPs, conformance fixtures).").option("--json", "machine-readable output").action(async (path, opts) => {
+  const code = await runCheckConventions({
+    path: path ?? ".",
+    cwd: program.opts().cwd,
+    json: opts.json === true
+  });
+  process.exit(code);
+});
 program.parseAsync(process.argv).catch((err) => {
   process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}
 `);