@sightmap/sightmap 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,248 +1,11 @@
-/**
- * File-level memory entries — surfaced whenever any definition from this file is active.
- */
-type Memory = string[];
-/**
- * Freeform notes surfaced to agents at runtime in the [Guide] section.
- */
-type Memory1 = string[];
-/**
- * A CSS selector, or a list of alternative selectors tried in order.
- */
-type Selector = string | [string, ...string[]];
-/**
- * A sightmap file: one YAML document under .sightmap/ describing views, components, requests, and memory entries. See https://github.com/sightmap/spec/blob/main/spec/v1/schema.md for the human-readable reference.
- */
-interface SightmapV1 {
-    /**
-     * Must be 1 for files that conform to this version of the spec.
-     */
-    version: 1;
-    memory?: Memory;
-    views?: View[];
-    /**
-     * Global components — matched against every view.
-     */
-    components?: Component[];
-    /**
-     * Global requests — matched against every view.
-     */
-    requests?: Request[];
-}
-interface View {
-    name: string;
-    /**
-     * Glob pattern matched against the URL pathname. * matches one segment, ** matches any depth.
-     */
-    route: string;
-    description?: string;
-    source?: string;
-    memory?: Memory1;
-    components?: Component[];
-    requests?: Request[];
-}
-interface Component {
-    name: string;
-    selector: Selector;
-    source?: string;
-    description?: string;
-    memory?: Memory1;
-    /**
-     * Nested components. Selectors are scoped to the parent's matched subtree.
-     */
-    children?: Component[];
-}
-interface Request {
-    name: string;
-    /**
-     * Glob pattern. Express-style :param segments normalize to *.
-     */
-    route: string;
-    /**
-     * HTTP method filter. Case-insensitive; commonly GET, POST, PUT, PATCH, DELETE.
-     */
-    method?: string;
-    description?: string;
-    source?: string;
-    request?: Payload;
-    response?: Payload;
-    headers?: string[];
-    memory?: Memory1;
-}
-interface Payload {
-    fields?: Field[];
-}
-interface Field {
-    name: string;
-    type?: string;
-    description?: string;
-}
-
-type Severity = "error" | "warning" | "info";
-interface Diagnostic {
-    severity: Severity;
-    code: string;
-    message: string;
-    file?: string;
-    path?: string;
-    loc?: {
-        line: number;
-        column: number;
-    };
-    source?: string;
-}
-declare const PARSE_ERROR = "parse-error";
-declare const SCHEMA_VALIDATION_FAILED = "schema-validation-failed";
-declare const UNKNOWN_VERSION = "unknown-version";
-declare const MERGE_COLLISION_VIEW = "merge-collision-view";
-declare const MERGE_COLLISION_COMPONENT = "merge-collision-component";
-declare const DUPLICATE_VIEW_NAME = "duplicate-view-name";
-declare const DUPLICATE_ROUTE = "duplicate-route";
-declare const ROUTE_SHADOWING = "route-shadowing";
-declare const UNKNOWN_SOURCE = "unknown-source";
-declare const SELECTOR_SYNTAX = "selector-syntax";
-
-/**
- * A single-file fragment after parsing and selector normalization.
- * Branded to prevent querying an unmerged fragment.
- */
-interface SightmapFragment extends SightmapV1 {
-    readonly __brand: "SightmapFragment";
-    readonly __sourceFile?: string;
-}
-/**
- * A merged, queryable sightmap produced by `merge()` or `loadDirectory()`.
- */
-interface Sightmap {
-    readonly version: 1;
-    readonly views: readonly View[];
-    readonly globalComponents: readonly Component[];
-    readonly globalRequests: readonly Request[];
-    readonly fileMemory: readonly {
-        memory: string[];
-        sourceFile: string;
-    }[];
-    /**
-     * Diagnostics produced during merge (e.g. collisions, duplicate names across files).
-     * Lint diagnostics are returned separately by `lint()`.
-     */
-    readonly diagnostics: readonly Diagnostic[];
-    readonly __brand: "Sightmap";
-}
-interface ResolvedView {
-    name: string;
-    route: string;
-    source?: string;
-    description?: string;
-    memory: string[];
-    definedIn: {
-        file: string;
-        line?: number;
-    };
-}
-interface ResolvedComponent {
-    name: string;
-    selector: string[];
-    source?: string;
-    description?: string;
-    memory: string[];
-    parentChain: string[];
-    scope: "global" | "view-scoped";
-    /** Present iff `scope === "view-scoped"`. */
-    scopedToView?: string;
-    definedIn: {
-        file: string;
-        line?: number;
-    };
-}
-interface ResolvedRequest {
-    name: string;
-    route: string;
-    method?: string;
-    source?: string;
-    description?: string;
-    request?: {
-        fields: readonly Field[];
-    };
-    response?: {
-        fields: readonly Field[];
-    };
-    headers?: readonly string[];
-    memory: string[];
-    definedIn: {
-        file: string;
-        line?: number;
-    };
-}
-interface MatchResult {
-    view: ResolvedView | null;
-    components: ResolvedComponent[];
-    requests: ResolvedRequest[];
-    memory: string[];
-}
-type ExplainMatchedAs = "name" | "path" | "name-and-path";
-/**
- * Discriminated union: narrowing on `type` automatically narrows `entry`.
- *   if (hit.type === "view") { hit.entry.route; }  // no cast needed
- */
-type ExplainHit = {
-    type: "view";
-    matchedAs: ExplainMatchedAs;
-    entry: ResolvedView;
-} | {
-    type: "component";
-    matchedAs: ExplainMatchedAs;
-    entry: ResolvedComponent;
-} | {
-    type: "request";
-    matchedAs: ExplainMatchedAs;
-    entry: ResolvedRequest;
-};
-interface ExplainResult {
-    query: string;
-    hits: ExplainHit[];
-}
-/** Result returned by validate() — never throws. */
-type ValidateResult = {
-    ok: true;
-    value: SightmapFragment;
-} | {
-    ok: false;
-    diagnostics: readonly Diagnostic[];
-};
-
-interface ParseOptions {
-    /** Optional source file path; recorded on the fragment for canonical-order merging. */
-    sourceFile?: string;
-}
-/**
- * Parse a single sightmap file (YAML string or pre-parsed object).
- * Throws on parse error, missing version, or version mismatch.
- * Normalizes `selector: string` to `selector: [string]` everywhere.
- */
-declare function parse(input: string | object, opts?: ParseOptions): SightmapFragment;
+import { V as ValidateResult, S as Sightmap, D as Diagnostic, a as SightmapV1 } from './browser-ChD_xQt8.js';
+export { C as Component, b as DUPLICATE_ROUTE, c as DUPLICATE_VIEW_NAME, E as ExplainHit, d as ExplainMatchedAs, e as ExplainResult, F as Field, M as MERGE_COLLISION_COMPONENT, f as MERGE_COLLISION_VIEW, g as MatchResult, P as PARSE_ERROR, R as ROUTE_SHADOWING, h as Request, i as ResolvedComponent, j as ResolvedRequest, k as ResolvedView, l as SCHEMA_VALIDATION_FAILED, m as SELECTOR_SYNTAX, n as Severity, o as SightmapFragment, U as UNKNOWN_SOURCE, p as UNKNOWN_VERSION, q as View, r as explain, s as match, t as merge, u as parse } from './browser-ChD_xQt8.js';
 
 interface ValidateOptions {
     sourceFile?: string;
 }
 declare function validate(input: string | object, opts?: ValidateOptions): ValidateResult;
 
-/**
- * Merge fragments into a queryable Sightmap.
- *
- * Canonical order: fragments are sorted by `__sourceFile` (code-point order; locale-independent
- * for cross-environment determinism). Fragments without a `__sourceFile` sort first, and ES2019
- * sort stability preserves their input order. Within each fragment, declaration order is
- * preserved. The merged collection's order = (sourceFile order, then declaration order).
- *
- * Duplicate view names produce `merge-collision-view` warnings; duplicate global component
- * names produce `merge-collision-component`. The first occurrence wins.
- *
- * Returned arrays are fresh, but element objects (View/Component/Request) are shared with
- * the input fragments — callers must not mutate them.
- */
-declare function merge(fragments: SightmapFragment[]): Sightmap;
-
 interface LoadDirectoryOptions {
     /** Optional root for `file` fields in diagnostics. Default: the directory passed in. */
     diagnosticRoot?: string;
@@ -256,18 +19,6 @@ interface LoadDirectoryOptions {
  */
 declare function loadDirectory(dir: string, opts?: LoadDirectoryOptions): Promise<Sightmap>;
 
-interface MatchOptions {
-    url: string;
-    method?: string;
-}
-declare function match(sightmap: Sightmap, opts: MatchOptions): MatchResult;
-
-interface ExplainOptions {
-    by?: "name" | "path";
-    type?: "view" | "component" | "request";
-}
-declare function explain(sightmap: Sightmap, query: string, opts?: ExplainOptions): ExplainResult;
-
 interface LintOptions {
     /** Per-rule enable/disable. Default: all rules enabled. */
     rules?: Record<string, boolean>;
@@ -276,4 +27,11 @@ interface LintOptions {
 }
 declare function lint(sightmap: Sightmap, opts?: LintOptions): Promise<Diagnostic[]>;
 
-export { type Component, DUPLICATE_ROUTE, DUPLICATE_VIEW_NAME, type Diagnostic, type ExplainHit, type ExplainMatchedAs, type ExplainResult, type Field, MERGE_COLLISION_COMPONENT, MERGE_COLLISION_VIEW, type MatchResult, PARSE_ERROR, ROUTE_SHADOWING, type Request, type ResolvedComponent, type ResolvedRequest, type ResolvedView, SCHEMA_VALIDATION_FAILED, SELECTOR_SYNTAX, type Severity, type Sightmap, type SightmapFragment, UNKNOWN_SOURCE, UNKNOWN_VERSION, type ValidateResult, type View, explain, lint, loadDirectory, match, merge, parse, validate };
+/**
+ * Input shape for `format`: the value-side of `SightmapV1` plus any
+ * forward-compat unknown keys we should pass through.
+ */
+type FormatInput = SightmapV1 & Record<string, unknown>;
+declare function format(input: FormatInput): string;
+
+export { Diagnostic, type FormatInput, Sightmap, ValidateResult, format, lint, loadDirectory, validate };

package/dist/index.js

@@ -42,6 +42,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,
@@ -73,20 +79,25 @@ var SELECTOR_SYNTAX = "selector-syntax";
 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;
@@ -127,6 +138,7 @@ function validate(input, opts = {}) {
     });
     return { ok: false, diagnostics };
   }
+  const ajvValidate = getValidator();
   const ok = ajvValidate(obj);
   if (!ok) {
     for (const e of ajvValidate.errors ?? []) {
@@ -521,29 +533,35 @@ function routeShadowing(sightmap) {
   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
@@ -628,6 +646,32 @@ async function lint(sightmap, opts = {}) {
   }
   return out;
 }
+
+// src/format/index.ts
+import { stringify } from "yaml";
+var CANONICAL_KEY_ORDER = [
+  "version",
+  "memory",
+  "views",
+  "components",
+  "requests"
+];
+function format(input) {
+  const ordered = {};
+  for (const key of CANONICAL_KEY_ORDER) {
+    if (input[key] !== void 0) ordered[key] = input[key];
+  }
+  for (const key of Object.keys(input)) {
+    if (key.startsWith("__")) continue;
+    if (!(key in ordered)) ordered[key] = input[key];
+  }
+  const yaml3 = stringify(ordered, {
+    indent: 2,
+    lineWidth: 0,
+    minContentWidth: 0
+  });
+  return yaml3.endsWith("\n") ? yaml3 : yaml3 + "\n";
+}
 export {
   DUPLICATE_ROUTE,
   DUPLICATE_VIEW_NAME,
@@ -640,6 +684,7 @@ export {
   UNKNOWN_SOURCE,
   UNKNOWN_VERSION,
   explain,
+  format,
   lint,
   loadDirectory,
   match,