@sightmap/sightmap 0.1.0

package/dist/index.js

@@ -0,0 +1,650 @@
+// 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 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/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/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
+import { readFile, readdir } from "fs/promises";
+import { join, extname, relative, resolve as resolve2 } from "path";
+async function loadDirectory(dir, opts = {}) {
+  const absDir = resolve2(dir);
+  const root = opts.diagnosticRoot !== void 0 ? resolve2(opts.diagnosticRoot) : absDir;
+  const files = await collectYamlFiles(absDir);
+  files.sort();
+  const fragments = [];
+  const loadDiagnostics = [];
+  for (const file of files) {
+    const relPath = relative(root, file);
+    const text = await readFile(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 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/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;
+  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/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/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/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 resolve3 } 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(resolve3(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;
+}
+export {
+  DUPLICATE_ROUTE,
+  DUPLICATE_VIEW_NAME,
+  MERGE_COLLISION_COMPONENT,
+  MERGE_COLLISION_VIEW,
+  PARSE_ERROR,
+  ROUTE_SHADOWING,
+  SCHEMA_VALIDATION_FAILED,
+  SELECTOR_SYNTAX,
+  UNKNOWN_SOURCE,
+  UNKNOWN_VERSION,
+  explain,
+  lint,
+  loadDirectory,
+  match,
+  merge,
+  parse,
+  validate
+};
+//# sourceMappingURL=index.js.map