@sightmap/sightmap 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,909 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/cli/validate.ts
+import { readFile } from "fs/promises";
+import { resolve as resolve2, relative } from "path";
+
+// src/validate.ts
+import yaml2 from "js-yaml";
+import { Ajv2020 } from "ajv/dist/2020.js";
+
+// src/diagnostics.ts
+var PARSE_ERROR = "parse-error";
+var SCHEMA_VALIDATION_FAILED = "schema-validation-failed";
+var UNKNOWN_VERSION = "unknown-version";
+var MERGE_COLLISION_VIEW = "merge-collision-view";
+var MERGE_COLLISION_COMPONENT = "merge-collision-component";
+var DUPLICATE_VIEW_NAME = "duplicate-view-name";
+var DUPLICATE_ROUTE = "duplicate-route";
+var ROUTE_SHADOWING = "route-shadowing";
+var UNKNOWN_SOURCE = "unknown-source";
+var SELECTOR_SYNTAX = "selector-syntax";
+
+// src/parse.ts
+import yaml from "js-yaml";
+function parse(input, opts = {}) {
+  let doc;
+  if (typeof input === "string") {
+    try {
+      doc = yaml.load(input);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`YAML parse error: ${msg}`);
+    }
+  } else {
+    doc = { ...input };
+  }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+    throw new Error("Expected sightmap document to be an object at the root");
+  }
+  const obj = doc;
+  if (obj["version"] === void 0) {
+    throw new Error("Missing required `version` field");
+  }
+  if (obj["version"] !== 1) {
+    throw new Error(`Unsupported version: ${String(obj["version"])} (expected 1)`);
+  }
+  if (Array.isArray(obj["components"])) {
+    obj["components"] = obj["components"].map(normalizeComponent);
+  }
+  if (Array.isArray(obj["views"])) {
+    obj["views"] = obj["views"].map((v) => {
+      const out = { ...v };
+      if (Array.isArray(out["components"])) {
+        out["components"] = out["components"].map(normalizeComponent);
+      }
+      return out;
+    });
+  }
+  const fragment = {
+    ...obj,
+    __brand: "SightmapFragment",
+    ...opts.sourceFile !== void 0 ? { __sourceFile: opts.sourceFile } : {}
+  };
+  return fragment;
+}
+function normalizeComponent(c) {
+  const sel = c.selector;
+  const normalized = {
+    ...c,
+    selector: typeof sel === "string" ? [sel] : sel
+  };
+  if (Array.isArray(c.children)) {
+    normalized.children = c.children.map(normalizeComponent);
+  }
+  return normalized;
+}
+
+// src/validate.ts
+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 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;
+  if (typeof input === "string") {
+    try {
+      doc = yaml2.load(input);
+    } catch (err) {
+      const e = err;
+      diagnostics.push({
+        severity: "error",
+        code: PARSE_ERROR,
+        message: e.message ?? "YAML parse error",
+        ...opts.sourceFile !== void 0 ? { file: opts.sourceFile } : {},
+        ...e.mark ? { loc: { line: (e.mark.line ?? 0) + 1, column: (e.mark.column ?? 0) + 1 } } : {}
+      });
+      return { ok: false, diagnostics };
+    }
+  } else {
+    doc = input;
+  }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+    diagnostics.push({
+      severity: "error",
+      code: SCHEMA_VALIDATION_FAILED,
+      message: "Expected document root to be an object",
+      ...opts.sourceFile !== void 0 ? { file: opts.sourceFile } : {}
+    });
+    return { ok: false, diagnostics };
+  }
+  const obj = doc;
+  if (obj["version"] !== 1) {
+    diagnostics.push({
+      severity: "error",
+      code: UNKNOWN_VERSION,
+      message: obj["version"] === void 0 ? "Missing required `version` field" : `Unsupported version: ${String(obj["version"])} (expected 1)`,
+      ...opts.sourceFile !== void 0 ? { file: opts.sourceFile } : {},
+      path: "/version"
+    });
+    return { ok: false, diagnostics };
+  }
+  const ok = ajvValidate(obj);
+  if (!ok) {
+    for (const e of ajvValidate.errors ?? []) {
+      diagnostics.push({
+        severity: "error",
+        code: SCHEMA_VALIDATION_FAILED,
+        message: `${e.instancePath || "(root)"} ${e.message ?? ""}`.trim(),
+        ...opts.sourceFile !== void 0 ? { file: opts.sourceFile } : {},
+        ...e.instancePath ? { path: e.instancePath } : {}
+      });
+    }
+    return { ok: false, diagnostics };
+  }
+  let value;
+  try {
+    value = parse(obj, opts.sourceFile !== void 0 ? { sourceFile: opts.sourceFile } : {});
+  } catch (err) {
+    diagnostics.push({
+      severity: "error",
+      code: SCHEMA_VALIDATION_FAILED,
+      message: err instanceof Error ? err.message : String(err),
+      ...opts.sourceFile !== void 0 ? { file: opts.sourceFile } : {}
+    });
+    return { ok: false, diagnostics };
+  }
+  return { ok: true, value };
+}
+
+// src/cli/_fsHelpers.ts
+import { readdir } from "fs/promises";
+import { join, extname } from "path";
+async function collectYamlFiles(dir) {
+  const out = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...await collectYamlFiles(p));
+    } else if (e.isFile()) {
+      const ext = extname(p).toLowerCase();
+      if (ext === ".yaml" || ext === ".yml") out.push(p);
+    }
+  }
+  return out;
+}
+
+// src/cli/envelope.ts
+function makeEnvelope(args) {
+  return {
+    ok: args.ok,
+    command: args.command,
+    diagnostics: [...args.diagnostics],
+    result: args.result
+  };
+}
+function emitJson(env) {
+  process.stdout.write(JSON.stringify(env, null, 2) + "\n");
+}
+
+// src/cli/humanFormat.ts
+var SEV_TAG = {
+  error: "ERROR",
+  warning: "warn ",
+  info: "info "
+};
+function formatDiagnostics(diags) {
+  if (diags.length === 0) return "";
+  const lines = diags.map((d) => {
+    const where = [d.file, d.path, d.loc ? `${d.loc.line}:${d.loc.column}` : null].filter(Boolean).join(" ");
+    return `${SEV_TAG[d.severity]} ${d.code}  ${where}
+      ${d.message}`;
+  });
+  return lines.join("\n");
+}
+function formatValidate(result, diags) {
+  const fileLines = result.files.map((f) => `${f.ok ? "ok   " : "FAIL "} ${f.path}`).join("\n");
+  const diagLines = formatDiagnostics(diags);
+  return [fileLines, "", diagLines, "", `${result.files.length} file(s) checked.`].filter(Boolean).join("\n");
+}
+function formatLint(diags) {
+  if (diags.length === 0) return "lint: no issues.";
+  return formatDiagnostics(diags);
+}
+function formatMatch(r) {
+  const lines = [];
+  if (r.view === null) {
+    lines.push("no view matched.");
+  } else {
+    lines.push(`view  ${r.view.name}  (route ${r.view.route})`);
+    if (r.view.source !== void 0) lines.push(`  source  ${r.view.source}`);
+  }
+  for (const c of r.components) {
+    const chain = c.parentChain.length > 0 ? ` (in ${c.parentChain.join(" > ")})` : "";
+    lines.push(`comp  ${c.name}${chain}  ${c.scope}  selector=${c.selector.join(" | ")}`);
+  }
+  for (const q of r.requests) {
+    lines.push(`req   ${q.name}  ${q.method ?? "ANY"} ${q.route}`);
+  }
+  if (r.memory.length > 0) {
+    lines.push("");
+    lines.push("[Guide]");
+    for (const m of r.memory) lines.push(`  - ${m}`);
+  }
+  return lines.join("\n");
+}
+function formatExplain(r) {
+  if (r.hits.length === 0) return `no hits for "${r.query}".`;
+  const lines = [`${r.hits.length} hit(s) for "${r.query}":`];
+  for (const h of r.hits) {
+    const e = h.entry;
+    lines.push(`  ${h.type}  ${e.name ?? "?"}  matchedAs=${h.matchedAs}${e.source !== void 0 ? `  src=${e.source}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+// src/cli/validate.ts
+async function runValidate(opts) {
+  const dir = resolve2(opts.cwd, opts.path);
+  const files = (await collectYamlFiles(dir)).sort();
+  const fileResults = [];
+  const diagnostics = [];
+  for (const file of files) {
+    const relPath = relative(opts.cwd, file);
+    const text = await readFile(file, "utf8");
+    const r = validate(text, { sourceFile: relPath });
+    fileResults.push({ path: relPath, ok: r.ok });
+    if (!r.ok) diagnostics.push(...r.diagnostics);
+  }
+  const ok = diagnostics.length === 0;
+  if (opts.json) {
+    emitJson(
+      makeEnvelope({
+        command: "validate",
+        ok,
+        diagnostics,
+        result: { files: fileResults }
+      })
+    );
+  } else {
+    process.stdout.write(formatValidate({ files: fileResults }, diagnostics) + "\n");
+  }
+  return ok ? 0 : 1;
+}
+
+// src/cli/lint.ts
+import { resolve as resolve5 } from "path";
+
+// src/loadDirectory.ts
+import { readFile as readFile2, readdir as readdir2 } from "fs/promises";
+import { join as join2, extname as extname2, relative as relative2, resolve as resolve3 } from "path";
+
+// src/merge.ts
+function merge(fragments) {
+  const sorted = [...fragments].sort((a, b) => {
+    const aFile = a.__sourceFile ?? "";
+    const bFile = b.__sourceFile ?? "";
+    return aFile < bFile ? -1 : aFile > bFile ? 1 : 0;
+  });
+  const views = [];
+  const globalComponents = [];
+  const globalRequests = [];
+  const fileMemory = [];
+  const diagnostics = [];
+  const seenViewNames = /* @__PURE__ */ new Map();
+  const seenComponentNames = /* @__PURE__ */ new Map();
+  for (const f of sorted) {
+    const file = f.__sourceFile ?? "<unknown>";
+    for (const v of f.views ?? []) {
+      const prev = seenViewNames.get(v.name);
+      if (prev !== void 0) {
+        diagnostics.push({
+          severity: "warning",
+          code: MERGE_COLLISION_VIEW,
+          message: `View name "${v.name}" defined in both "${prev}" and "${file}"; first occurrence wins.`,
+          file
+        });
+      } else {
+        seenViewNames.set(v.name, file);
+      }
+      views.push(v);
+    }
+    for (const c of f.components ?? []) {
+      const prev = seenComponentNames.get(c.name);
+      if (prev !== void 0) {
+        diagnostics.push({
+          severity: "warning",
+          code: MERGE_COLLISION_COMPONENT,
+          message: `Component name "${c.name}" defined in both "${prev}" and "${file}"; first occurrence wins.`,
+          file
+        });
+      } else {
+        seenComponentNames.set(c.name, file);
+      }
+      globalComponents.push(c);
+    }
+    for (const r of f.requests ?? []) {
+      globalRequests.push(r);
+    }
+    if (Array.isArray(f.memory) && f.memory.length > 0) {
+      fileMemory.push({ memory: [...f.memory], sourceFile: file });
+    }
+  }
+  return {
+    version: 1,
+    views,
+    globalComponents,
+    globalRequests,
+    fileMemory,
+    diagnostics,
+    __brand: "Sightmap"
+  };
+}
+
+// src/loadDirectory.ts
+async function loadDirectory(dir, opts = {}) {
+  const absDir = resolve3(dir);
+  const root = opts.diagnosticRoot !== void 0 ? resolve3(opts.diagnosticRoot) : absDir;
+  const files = await collectYamlFiles2(absDir);
+  files.sort();
+  const fragments = [];
+  const loadDiagnostics = [];
+  for (const file of files) {
+    const relPath = relative2(root, file);
+    const text = await readFile2(file, "utf8");
+    const r = validate(text, { sourceFile: relPath });
+    if (r.ok) {
+      fragments.push(r.value);
+    } else {
+      loadDiagnostics.push(...r.diagnostics);
+    }
+  }
+  const merged = merge(fragments);
+  return {
+    ...merged,
+    diagnostics: [...loadDiagnostics, ...merged.diagnostics]
+  };
+}
+async function collectYamlFiles2(dir) {
+  const out = [];
+  const entries = await readdir2(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const p = join2(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...await collectYamlFiles2(p));
+    } else if (e.isFile()) {
+      const ext = extname2(p).toLowerCase();
+      if (ext === ".yaml" || ext === ".yml") out.push(p);
+    }
+  }
+  return out;
+}
+
+// src/lintRules/duplicateName.ts
+function duplicateName(sightmap) {
+  const seen = /* @__PURE__ */ new Map();
+  const out = [];
+  sightmap.views.forEach((v) => {
+    const count = (seen.get(v.name) ?? 0) + 1;
+    seen.set(v.name, count);
+    if (count > 1) {
+      out.push({
+        severity: "warning",
+        code: DUPLICATE_VIEW_NAME,
+        message: `Duplicate view name "${v.name}" (occurrence ${count}).`
+      });
+    }
+  });
+  return out;
+}
+
+// src/lintRules/duplicateRoute.ts
+function duplicateRoute(sightmap) {
+  const seen = /* @__PURE__ */ new Map();
+  const out = [];
+  for (const v of sightmap.views) {
+    const prev = seen.get(v.route);
+    if (prev !== void 0) {
+      out.push({
+        severity: "warning",
+        code: DUPLICATE_ROUTE,
+        message: `Route "${v.route}" is defined by both "${prev}" and "${v.name}". Only "${prev}" will match.`
+      });
+    } else {
+      seen.set(v.route, v.name);
+    }
+  }
+  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);
+    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;
+      }
+    }
+  }
+  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 || "/";
+}
+
+// src/lintRules/unknownSource.ts
+import { stat } from "fs/promises";
+import { resolve as resolve4 } from "path";
+async function unknownSource(sightmap, opts = {}) {
+  const root = opts.root ?? process.cwd();
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const check = async (source, label) => {
+    if (source === void 0) return;
+    if (seen.has(source)) return;
+    seen.add(source);
+    try {
+      await stat(resolve4(root, source));
+    } catch {
+      out.push({
+        severity: "warning",
+        code: UNKNOWN_SOURCE,
+        message: `${label}: source path "${source}" does not exist on disk (relative to ${root}).`
+      });
+    }
+  };
+  for (const v of sightmap.views) {
+    await check(v.source, `view "${v.name}"`);
+    for (const c of v.components ?? []) {
+      await walkComponent(c, `component "${c.name}"`, check);
+    }
+  }
+  for (const c of sightmap.globalComponents) {
+    await walkComponent(c, `component "${c.name}"`, check);
+  }
+  for (const r of sightmap.globalRequests) {
+    await check(r.source, `request "${r.name}"`);
+  }
+  return out;
+}
+async function walkComponent(c, label, check) {
+  await check(c.source, label);
+  for (const child of c.children ?? []) {
+    await walkComponent(child, `component "${child.name}"`, check);
+  }
+}
+
+// src/lintRules/selectorSyntax.ts
+import { parse as parseSelector } from "css-what";
+function selectorSyntax(sightmap) {
+  const out = [];
+  const visit = (c, scope) => {
+    const selectors = Array.isArray(c.selector) ? c.selector : [c.selector];
+    selectors.forEach((sel, i) => {
+      try {
+        parseSelector(sel);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        out.push({
+          severity: "warning",
+          code: SELECTOR_SYNTAX,
+          message: `${scope}: selector at index ${i} ("${sel}") failed to parse: ${msg}`
+        });
+      }
+    });
+    for (const child of c.children ?? []) visit(child, `component "${child.name}"`);
+  };
+  for (const c of sightmap.globalComponents) visit(c, `component "${c.name}"`);
+  for (const v of sightmap.views) {
+    for (const c of v.components ?? []) visit(c, `component "${c.name}"`);
+  }
+  return out;
+}
+
+// src/lint.ts
+async function lint(sightmap, opts = {}) {
+  const enabled = (code) => opts.rules?.[code] !== false;
+  const out = [];
+  if (enabled("duplicate-view-name")) out.push(...duplicateName(sightmap));
+  if (enabled("duplicate-route")) out.push(...duplicateRoute(sightmap));
+  if (enabled("route-shadowing")) out.push(...routeShadowing(sightmap));
+  if (enabled("selector-syntax")) out.push(...selectorSyntax(sightmap));
+  if (enabled("unknown-source")) {
+    out.push(...await unknownSource(sightmap, opts.root !== void 0 ? { root: opts.root } : {}));
+  }
+  return out;
+}
+
+// src/cli/lint.ts
+async function runLint(opts) {
+  const dir = resolve5(opts.cwd, opts.path);
+  const sightmap = await loadDirectory(dir, { diagnosticRoot: opts.cwd });
+  const ruleConfig = parseRules(opts.rules);
+  const lintDiags = await lint(sightmap, {
+    ...ruleConfig !== void 0 ? { rules: ruleConfig } : {},
+    root: opts.cwd
+  });
+  const all = [...sightmap.diagnostics, ...lintDiags];
+  const hasError = all.some((d) => d.severity === "error");
+  const hasWarning = all.some((d) => d.severity === "warning");
+  let code = 0;
+  if (hasError) code = 1;
+  else if (opts.strict && hasWarning) code = 1;
+  if (opts.json) {
+    emitJson(
+      makeEnvelope({
+        command: "lint",
+        ok: code === 0,
+        diagnostics: all,
+        result: {}
+      })
+    );
+  } else {
+    process.stdout.write(formatLint(all) + "\n");
+  }
+  return code;
+}
+function parseRules(spec) {
+  if (spec === void 0) return void 0;
+  const out = {};
+  for (const tok of spec.split(",").map((s) => s.trim()).filter(Boolean)) {
+    if (tok.startsWith("-")) out[tok.slice(1)] = false;
+    else out[tok] = true;
+  }
+  return out;
+}
+
+// src/cli/match.ts
+import { resolve as resolve6 } from "path";
+
+// src/resolver.ts
+function resolveByUrl(sightmap, url, method) {
+  let matchedView = null;
+  for (const v of sightmap.views) {
+    if (routeMatch(v.route, url)) {
+      matchedView = v;
+      break;
+    }
+  }
+  const components = [];
+  for (const c of sightmap.globalComponents) {
+    components.push(...flattenComponent(c, [], "global", void 0));
+  }
+  if (matchedView !== null && Array.isArray(matchedView.components)) {
+    for (const c of matchedView.components) {
+      components.push(...flattenComponent(c, [], "view-scoped", matchedView.name));
+    }
+  }
+  const requests = [];
+  const requestPool = [
+    ...sightmap.globalRequests,
+    ...matchedView?.requests ?? []
+  ];
+  for (const req of requestPool) {
+    if (!routeMatch(req.route, url)) continue;
+    if (method !== void 0 && req.method !== void 0 && req.method !== method) continue;
+    requests.push(toResolvedRequest(req));
+  }
+  const memory = [];
+  for (const fm of sightmap.fileMemory) memory.push(...fm.memory);
+  if (matchedView?.memory) memory.push(...matchedView.memory);
+  return {
+    view: matchedView !== null ? toResolvedView(matchedView) : null,
+    components,
+    requests,
+    memory
+  };
+}
+function resolveByName(sightmap, name) {
+  const hits = [];
+  for (const v of sightmap.views) {
+    if (v.name === name) hits.push({ type: "view", matchedAs: "name", entry: toResolvedView(v) });
+  }
+  for (const c of sightmap.globalComponents) {
+    for (const rc of flattenComponent(c, [], "global", void 0)) {
+      if (rc.name === name) hits.push({ type: "component", matchedAs: "name", entry: rc });
+    }
+  }
+  for (const v of sightmap.views) {
+    for (const c of v.components ?? []) {
+      for (const rc of flattenComponent(c, [], "view-scoped", v.name)) {
+        if (rc.name === name) hits.push({ type: "component", matchedAs: "name", entry: rc });
+      }
+    }
+  }
+  for (const r of sightmap.globalRequests) {
+    if (r.name === name) hits.push({ type: "request", matchedAs: "name", entry: toResolvedRequest(r) });
+  }
+  for (const v of sightmap.views) {
+    for (const r of v.requests ?? []) {
+      if (r.name === name) hits.push({ type: "request", matchedAs: "name", entry: toResolvedRequest(r) });
+    }
+  }
+  return hits;
+}
+function resolveBySourcePath(sightmap, path) {
+  const hits = [];
+  for (const v of sightmap.views) {
+    if (v.source === path) hits.push({ type: "view", matchedAs: "path", entry: toResolvedView(v) });
+  }
+  for (const c of sightmap.globalComponents) {
+    for (const rc of flattenComponent(c, [], "global", void 0)) {
+      if (rc.source === path) hits.push({ type: "component", matchedAs: "path", entry: rc });
+    }
+  }
+  for (const v of sightmap.views) {
+    for (const c of v.components ?? []) {
+      for (const rc of flattenComponent(c, [], "view-scoped", v.name)) {
+        if (rc.source === path) hits.push({ type: "component", matchedAs: "path", entry: rc });
+      }
+    }
+  }
+  for (const r of sightmap.globalRequests) {
+    if (r.source === path) hits.push({ type: "request", matchedAs: "path", entry: toResolvedRequest(r) });
+  }
+  return hits;
+}
+function flattenComponent(c, parentChain, scope, scopedToView) {
+  const out = [];
+  const selector = Array.isArray(c.selector) ? c.selector : [c.selector];
+  out.push({
+    name: c.name,
+    selector,
+    ...c.source !== void 0 ? { source: c.source } : {},
+    ...c.description !== void 0 ? { description: c.description } : {},
+    memory: c.memory ? [...c.memory] : [],
+    parentChain: [...parentChain],
+    scope,
+    ...scopedToView !== void 0 ? { scopedToView } : {},
+    definedIn: { file: "<unknown>" }
+  });
+  for (const child of c.children ?? []) {
+    out.push(...flattenComponent(child, [...parentChain, c.name], scope, scopedToView));
+  }
+  return out;
+}
+function toResolvedView(v) {
+  return {
+    name: v.name,
+    route: v.route,
+    ...v.source !== void 0 ? { source: v.source } : {},
+    ...v.description !== void 0 ? { description: v.description } : {},
+    memory: v.memory ? [...v.memory] : [],
+    definedIn: { file: "<unknown>" }
+  };
+}
+function toResolvedRequest(r) {
+  return {
+    name: r.name,
+    route: r.route,
+    ...r.method !== void 0 ? { method: r.method } : {},
+    ...r.source !== void 0 ? { source: r.source } : {},
+    ...r.description !== void 0 ? { description: r.description } : {},
+    ...r.request !== void 0 ? { request: { fields: r.request.fields ?? [] } } : {},
+    ...r.response !== void 0 ? { response: { fields: r.response.fields ?? [] } } : {},
+    ...r.headers !== void 0 ? { headers: r.headers } : {},
+    memory: r.memory ? [...r.memory] : [],
+    definedIn: { file: "<unknown>" }
+  };
+}
+
+// src/match.ts
+function match(sightmap, opts) {
+  return resolveByUrl(sightmap, opts.url, opts.method);
+}
+
+// src/cli/match.ts
+async function runMatch(opts) {
+  const dir = resolve6(opts.cwd, opts.path);
+  const sightmap = await loadDirectory(dir, { diagnosticRoot: opts.cwd });
+  const result = match(sightmap, {
+    url: opts.url,
+    ...opts.method !== void 0 ? { method: opts.method } : {}
+  });
+  const code = opts.requireView && result.view === null ? 1 : 0;
+  if (opts.json) {
+    emitJson(
+      makeEnvelope({
+        command: "match",
+        ok: code === 0,
+        diagnostics: [...sightmap.diagnostics],
+        result
+      })
+    );
+  } else {
+    process.stdout.write(formatMatch(result) + "\n");
+  }
+  return code;
+}
+
+// src/cli/explain.ts
+import { resolve as resolve7 } from "path";
+
+// src/explain.ts
+function explain(sightmap, query, opts = {}) {
+  const byName = opts.by === "path" ? [] : resolveByName(sightmap, query);
+  const byPath = opts.by === "name" ? [] : resolveBySourcePath(sightmap, query);
+  const key = (h) => `${h.type}:${h.entry.name}`;
+  const namedKeys = new Set(byName.map(key));
+  const pathKeys = new Set(byPath.map(key));
+  const merged = [];
+  for (const h of byName) {
+    if (pathKeys.has(key(h))) {
+      merged.push(withMatchedAs(h, "name-and-path"));
+    } else {
+      merged.push(h);
+    }
+  }
+  for (const h of byPath) {
+    if (!namedKeys.has(key(h))) {
+      merged.push(h);
+    }
+  }
+  const filtered = opts.type !== void 0 ? merged.filter((h) => h.type === opts.type) : merged;
+  return { query, hits: filtered };
+}
+function withMatchedAs(h, matchedAs) {
+  switch (h.type) {
+    case "view":
+      return { type: "view", matchedAs, entry: h.entry };
+    case "component":
+      return { type: "component", matchedAs, entry: h.entry };
+    case "request":
+      return { type: "request", matchedAs, entry: h.entry };
+  }
+}
+
+// src/cli/explain.ts
+async function runExplain(opts) {
+  const dir = resolve7(opts.cwd, opts.path);
+  const sightmap = await loadDirectory(dir, { diagnosticRoot: opts.cwd });
+  const result = explain(sightmap, opts.query, {
+    ...opts.by !== void 0 ? { by: opts.by } : {},
+    ...opts.type !== void 0 ? { type: opts.type } : {}
+  });
+  const code = opts.requireHit && result.hits.length === 0 ? 1 : 0;
+  if (opts.json) {
+    emitJson(
+      makeEnvelope({
+        command: "explain",
+        ok: code === 0,
+        diagnostics: [...sightmap.diagnostics],
+        result
+      })
+    );
+  } else {
+    process.stdout.write(formatExplain(result) + "\n");
+  }
+  return code;
+}
+
+// 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");
+program.option("--cwd <dir>", "working directory (resolves [path] arguments)", process.cwd());
+program.command("validate [path]").description("Validate .sightmap/ against the schema.").option("--json", "machine-readable output").action(async (path, opts) => {
+  const code = await runValidate({
+    path: path ?? ".sightmap",
+    cwd: program.opts().cwd,
+    json: opts.json === true
+  });
+  process.exit(code);
+});
+program.command("lint [path]").description("Run quality checks beyond schema.").option("--json", "machine-readable output").option("--strict", "treat all warnings as errors (exit 1)").option("--rules <list>", "comma-separated list of rule codes to disable (prefix '-') or only-enable").action(async (path, opts) => {
+  const code = await runLint({
+    path: path ?? ".sightmap",
+    cwd: program.opts().cwd,
+    json: opts.json === true,
+    strict: opts.strict === true,
+    ...opts.rules !== void 0 ? { rules: opts.rules } : {}
+  });
+  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({
+      url,
+      path: path ?? ".sightmap",
+      cwd: program.opts().cwd,
+      json: opts.json === true,
+      requireView: opts.requireView === true,
+      ...opts.method !== void 0 ? { method: opts.method } : {}
+    });
+    process.exit(code);
+  }
+);
+program.command("explain <query> [path]").description("Look up sightmap entries by name and/or source path.").option("--by <kind>", "scope to 'name' or 'path'").option("--type <kind>", "scope to 'view', 'component', or 'request'").option("--json", "machine-readable output").option("--require-hit", "exit 1 if zero hits").action(
+  async (query, path, opts) => {
+    const code = await runExplain({
+      query,
+      path: path ?? ".sightmap",
+      cwd: program.opts().cwd,
+      json: opts.json === true,
+      requireHit: opts.requireHit === true,
+      ...opts.by !== void 0 ? { by: opts.by } : {},
+      ...opts.type !== void 0 ? { type: opts.type } : {}
+    });
+    process.exit(code);
+  }
+);
+program.parseAsync(process.argv).catch((err) => {
+  process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(2);
+});
+//# sourceMappingURL=index.js.map