001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.console;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020
021import java.util.*;
022import java.util.regex.*;
023import java.util.stream.*;
024
025import org.apache.juneau.marshall.collections.*;
026
027/**
028 * Static check of a page contract's message-bus wiring: rule R-10 (every
029 * subscription has a publisher), rule R-11 (every {@code publisher:"server"} topic rides a bridge downstream), and the
030 * E-40..E-54 and E-58 shape rules on {@code topics}, {@code bridges}, card {@code publishes} / {@code subscribes} and ribbon
031 * {@code target} / {@code publish} items.
032 *
033 * <p>
034 * The same rule runs in the browser as {@code JuneauViews.bus.wiring.validate}, and both read the shared corpus
035 * {@code bus-wiring-corpus.json}.  The JS side reports the subset that only the running page can act on (E-JS-41,
036 * E-JS-47, E-JS-52); this class reports everything.
037 *
038 * <p>
039 * Every problem is collected; nothing is thrown.  Callers decide how loud to be: the page render, the
040 * template validator and C3's {@code PageSpec.build()} each turn the list into their own failure.
041 *
042 * <h2 class='section'>Example:</h2>
043 * <p class='bjava'>
044 *   JsonMap <jv>contract</jv> = JsonMap.<jsm>ofString</jsm>(<jv>pageJson</jv>);
045 *   <jk>for</jk> (<jk>var</jk> <jv>p</jv> : BusWiringValidator.<jsm>validate</jsm>(<jv>contract</jv>, CardTypeRegistry.<jsm>standard</jsm>()))
046 *     System.<jsf>err</jsf>.println(<jv>p</jv>.code() + <js>" "</js> + <jv>p</jv>.message());
047 *   <jc>// E-41 card 'tasks' subscribes to 'selection:changes' but nothing publishes it; card 'changes' does not enable selection</jc>
048 * </p>
049 *
050 * @since 10.0.0
051 */
052@SuppressWarnings({
053   "java:S1192", // Repeated literals are contract wire keys; named constants would obscure the contract shape.
054   "java:S3776" // Validation and rendering chains many independent guards; splitting them adds no clarity.
055})
056public final class BusWiringValidator {
057
058   /**
059    * One wiring problem.
060    *
061    * <h2 class='section'>Example:</h2>
062    * <p class='bjava'>
063    *   <jk>var</jk> <jv>p</jv> = <jk>new</jk> BusWiringValidator.Problem(<js>"E-52"</js>,
064    *     <js>"topic 'ops.jobs' is declared publisher=server but no bridge carries it downstream"</js>);
065    *   <jv>p</jv>.toString();   <jc>// "E-52 topic 'ops.jobs' is declared ..."</jc>
066    * </p>
067    *
068    * @param code The Java code, {@code E-40}..{@code E-54}, {@code E-58} or {@code E-71}..{@code E-77}.
069    * @param message The message, without the code.
070    */
071   public record Problem(String code, String message) {
072      @Override
073      public String toString() {
074         return code + " " + message;
075      }
076   }
077
078   static final String E40 = "invalid topic '%s': expected family[:key] (see the topic syntax)";
079   static final String E41 = "card '%s' subscribes to '%s' but nothing publishes it%s";
080   static final String E41_SUGGEST = "; did you mean '%s'?";
081   static final String E41_NOT_ENABLED = "; card '%s' does not enable %s";
082   static final String E42 = "topic '%s' names card '%s', which is not on this page";
083   static final String E43_PUBLISH = "card '%s' (type '%s') does not publish '%s'";
084   static final String E43_OP = "card '%s' (type '%s') does not handle op '%s'";
085   static final String E44 = "card '%s' (type '%s') has no role '%s'; accepted: %s";
086   static final String E45_FRAMEWORK = "'%s' is a framework family; framework topics are implicit and may not be declared";
087   static final String E45_NAMESPACE = "custom topic family '%s' must be namespaced (e.g. 'app.%s')";
088   static final String E46 = "topic '%s' is declared with retain=%s here and retain=%s at %s";
089   static final String E47_TOKEN = "card '%s': token '{%s}' in %s is not mapped by any params subscription";
090   static final String E47_MAP = "card '%s': params subscription needs map";
091   static final String E48 = "ribbon item %s on card '%s': %s";
092   static final String E49 = "card '%s' subscribes to its own topic '%s'; use ctx.subscribe with {echo:true} in JS if this is intended";
093   static final String E51 = "bridge '%s': %s";
094   static final String E52 = "topic '%s' is declared publisher=server but no bridge carries it downstream";
095   static final String E53 = "bridge '%s' sends '%s' upstream, but no topics entry or card publishes declares it";
096   static final String E54 = "bridge '%s' may not carry framework state topic '%s' (only job:*, and cmd:<cardId> downstream)";
097   static final String E58 = "terminal card '%s' has input: true but %s";
098   static final String E72 = "chart card '%s' on.%s targets '%s', which the card does not publish";
099   static final String E73 = "'%s' sends cmd '%s' to group '%s', which no chart card declares";
100   /** E-74 text; {@code Fn}, {@code ChartDef} and {@code ChartCardType} (console-ui-freemarker) throw it too. */
101   public static final String E74 = "'%s' is not a valid %s name";
102   static final String E76 = "data source '%s': %s";
103   /** E-77 text; {@code DashboardSpec}, {@code Section} and {@code PersistSpec} (console-ui-freemarker) throw it too. */
104   public static final String E77 = "dashboard '%s': %s";
105   static final String E71 = "topic '%s' needs exactly one source publisher; found %s";
106
107   /** Names for $fn, decorators, sections, parsers, builders and transforms (rule R-E5); juneau-charts.js has the same literal. */
108   @SuppressWarnings({
109      "java:S5998" // Pattern text is pinned to the identical literal in the JS files; possessive quantifiers are not valid JS
110   })
111   public static final Pattern EXTENSION_NAME = Pattern.compile("^[a-z][a-zA-Z0-9]*(\\.[a-z][a-zA-Z0-9-]*)*$");
112   /** ECharts event names a chart card's {@code on} may use. */
113   public static final Pattern EVENT_NAME = Pattern.compile("^[a-z][a-z0-9_]{0,31}$");
114
115   // Topic grammar: one copy, owned by Topics.
116   static final Set<String> FRAMEWORK_FAMILIES = Topics.FRAMEWORK_FAMILIES;
117   static final Pattern TOPIC = Topics.TOPIC;
118   /** Scope placeholders a handler subscription topic may carry. */
119   static final Pattern HANDLER_PLACEHOLDER = Pattern.compile("\\{(rowKey|tabId|cardId)\\}");
120   static final Pattern CUSTOM_DECL = Topics.CUSTOM_PUBLICATION;
121   static final Pattern UNNAMESPACED = Pattern.compile("^([a-z][a-z0-9-]{0,31})(:([A-Za-z0-9_.-]{1,128}|\\*))?$");
122   static final Pattern BRIDGE_ID = Topics.ID;
123   static final Pattern SAME_ORIGIN_PATH = Pattern.compile("^/(?![/\\\\])\\S*$");
124   static final Pattern URL_TOKEN = Pattern.compile("\\{([A-Za-z0-9_-]+)\\}");
125
126   /** Families whose key is a card id. */
127   static final Set<String> CARD_FAMILIES = Set.of("card", "selection", "filter", "redraw", "detail", "bulk", "cmd", "zoom", "legend");
128   /** Roles the shell implements for every card type. */
129   static final Set<String> SHELL_ROLES = Set.of("refresh", "params");
130   /** The {@code cmd:} op each targetable ribbon item sends. */
131   static final Map<String,String> RIBBON_OPS = Map.of(
132      "refresh", "reload", "option", "set-filter", "optionGroup", "set-filter",
133      "pausePolling", "pause-polling", "collapseAll", "collapse-all");
134   /** The card type a data source reports in E-43 (R-E3a). */
135   static final String SOURCE_TYPE = "dataSource";
136   /** The cmd ops a data source handles: refresh, and reload (what a targeted ribbon refresh item sends). */
137   static final Set<String> SOURCE_OPS = Set.of("refresh", "reload");
138   /** Datatables families that need a catalog key to be published. */
139   static final Set<String> DATATABLES_OPT_IN = Set.of("selection", "detail", "bulk");
140   /** Largest edit distance a "did you mean" suggestion may have. */
141   static final int SUGGEST_MAX_DISTANCE = 3;
142
143   private BusWiringValidator() {}
144
145   /**
146    * Checks a page contract's bus wiring.
147    *
148    * @param contract The page contract (the {@code #juneau-page} JSON).
149    * @param registry Card types, for implicit topics, accepted roles and ops.  Unregistered types are skipped.
150    * @return Every problem, in contract order: {@code topics}, then each card, then {@code dataSources}
151    *    (E-74, then E-71 sorted by topic, then derived-source cycles as E-76 sorted by each cycle's smallest id),
152    *    then ids (E-76/E-77), then {@code bridges}, then R-11, then the terminal-input rule (E-58).
153    */
154   public static List<Problem> validate(JsonMap contract, CardTypeRegistry registry) {
155      return new Run(contract, registry).run();
156   }
157
158   /** {@code pattern} equals {@code topic}, or is {@code family:*} and {@code topic} is a concrete {@code family:key}. */
159   static boolean topicMatches(String pattern, String topic) {
160      if (pattern.equals(topic))
161         return true;
162      if (! pattern.endsWith(":*"))
163         return false;
164      var prefix = pattern.substring(0, pattern.length() - 1);
165      return topic.length() > prefix.length() && topic.startsWith(prefix);
166   }
167
168   /** Levenshtein distance. */
169   static int distance(String a, String b) {
170      var prev = new int[b.length() + 1];
171      var cur = new int[b.length() + 1];
172      for (var j = 0; j <= b.length(); j++)
173         prev[j] = j;
174      for (var i = 1; i <= a.length(); i++) {
175         cur[0] = i;
176         for (var j = 1; j <= b.length(); j++) {
177            var cost = a.charAt(i - 1) == b.charAt(j - 1) ? 0 : 1;
178            cur[j] = Math.min(Math.min(cur[j - 1] + 1, prev[j] + 1), prev[j - 1] + cost);
179         }
180         var t = prev;
181         prev = cur;
182         cur = t;
183      }
184      return prev[b.length()];
185   }
186
187   private static final class Run {
188      final CardTypeRegistry registry;
189      final List<Problem> problems = new ArrayList<>();
190      final List<Map<?,?>> topics;
191      final List<Map<?,?>> bridges;
192      final Map<String,Map<?,?>> cards = new LinkedHashMap<>();
193      /** Ids of cards found inside another card, and nested ids that repeat another card's id. */
194      final Set<String> nestedIds = new HashSet<>();
195      final Set<String> nestedDuplicates = new TreeSet<>();
196      final List<Map<?,?>> dataSources;
197      final List<Map<?,?>> sections;
198      /** The contract's {@code dashboard} object, or an empty map. */
199      final Map<?,?> dashboard;
200      /** Ids of the data sources, and of the rail sections (the sole owner of {@code filter:<sectionId>}, R-E7). */
201      final Set<String> sourceIds = new HashSet<>();
202      final Set<String> sectionIds = new HashSet<>();
203      /** {@code contract.dashboard.id}, the E-77 name slot; {@code "<none>"} when absent. */
204      final String dashId;
205      /** Ids a card-keyed family key may name: cards, data sources (R-E3a) and dashboard rail sections (R-E7). */
206      final Set<String> targets = new HashSet<>();
207      /** data:<id> topic to its number of source publishers (R-E1). */
208      final Map<String,Integer> dataPublishers = new TreeMap<>();
209      /** data:<id> topics something on the page reads (R-E1). */
210      final Set<String> dataReads = new TreeSet<>();
211      /** Every topic or pattern something on the page publishes (R-10 rules 2-6), sorted for the suggestion. */
212      final TreeSet<String> published = new TreeSet<>();
213      /** topic -> [retain, where] of its first declaration (E-46). */
214      final Map<String,Object[]> retains = new HashMap<>();
215
216      Run(JsonMap contract, CardTypeRegistry registry) {
217         this.registry = registry;
218         topics = maps(contract.get("topics"));
219         bridges = maps(contract.get("bridges"));
220         flatten(maps(contract.get("cards")), false);
221         dataSources = maps(contract.get("dataSources"));
222         var dash = contract.get("dashboard") instanceof Map<?,?> d ? d : Map.of();
223         dashboard = dash;
224         var rail = dash.get("rail") instanceof Map<?,?> r ? r : Map.of();
225         sections = maps(rail.get("sections"));
226         dashId = str(dash.get("id")) != null ? str(dash.get("id")) : "<none>";
227         targets.addAll(cards.keySet());
228         for (var s : dataSources) if (str(s.get("id")) != null) sourceIds.add(str(s.get("id")));
229         for (var s : sections) if (str(s.get("id")) != null) sectionIds.add(str(s.get("id")));
230         targets.addAll(sourceIds);
231         targets.addAll(sectionIds);
232      }
233
234      // Adds each card, then (recursively) the cards its handler says it holds, so every later pass sees nested cards.
235      void flatten(List<Map<?,?>> list, boolean nested) {
236         for (var c : list) {
237            var id = str(c.get("id"));
238            if (id != null) {
239               if (cards.containsKey(id)) {
240                  if (nested || nestedIds.contains(id))
241                     nestedDuplicates.add(id);
242               } else {
243                  cards.put(id, c);
244               }
245               if (nested)
246                  nestedIds.add(id);
247            }
248            var type = str(c.get("type"));
249            if (type != null && registry.isRegistered(type))
250               flatten(maps(registry.handler(type).nestedCards(json(c))), true);
251         }
252      }
253
254      List<Problem> run() {
255         collectPublishers();
256         for (var i = 0; i < topics.size(); i++)
257            checkTopicDecl(i, topics.get(i));
258         for (var c : cards.values())
259            checkCard(c);
260         checkDataSources();
261         checkDataTopics();
262         checkDerivedCycles();
263         checkIds();
264         checkDashboard();
265         checkBridges();
266         checkServerTopics();
267         checkTerminalInput();
268         return List.copyOf(problems);
269      }
270
271      void add(String code, String format, Object... args) {
272         problems.add(new Problem(code, f(format, args)));
273      }
274
275      // ---- R-10 publishers --------------------------------------------------------------------------------------
276
277      void collectPublishers() {
278         for (var c : cards.values()) {
279            var id = str(c.get("id"));
280            published.add("card:" + id);
281            var type = str(c.get("type"));
282            if (type != null && registry.isRegistered(type))
283               published.addAll(registry.handler(type).implicitTopics(json(c)));
284            for (var p : maps(c.get("publishes")))
285               addCustom(str(p.get("topic")));
286            for (var item : ribbon(c))
287               if ("publish".equals(str(item.get("type"))))
288                  addCustom(str(item.get("topic")));
289         }
290         for (var t : topics) {
291            var topic = str(t.get("topic"));
292            if ("job:*".equals(topic))
293               published.add(topic);
294            else if (topic != null && topic.startsWith("data:") && "script".equals(str(t.get("publisher")))) {
295               published.add(topic);
296               dataPublishers.merge(topic, 1, Integer::sum);
297            }
298            else
299               addCustom(topic);
300         }
301         for (var id : sourceIds) {
302            published.add("data:" + id);
303            dataPublishers.merge("data:" + id, 1, Integer::sum);
304         }
305         // A section's filter:<id> is read through the sectionIds check in checkPublisher; it is added here only so that
306         // the "did you mean" suggestion can offer it (pinned by corpus c67).
307         for (var s : sections)
308            if (str(s.get("id")) != null)
309               published.add("filter:" + str(s.get("id")));
310         for (var b : bridges) {
311            var id = str(b.get("id"));
312            if (id != null)
313               published.add("bridge:" + id);
314            for (var d : strings(b.get("downstream")))
315               if (d.startsWith("job:"))
316                  published.add(d);
317         }
318      }
319
320      void addCustom(String topic) {
321         if (topic != null && CUSTOM_DECL.matcher(topic).matches())
322            published.add(topic);
323      }
324
325      boolean isPublished(String topic) {
326         for (var p : published)
327            if (topicMatches(p, topic))
328               return true;
329         return false;
330      }
331
332      String suggest(String topic) {
333         String best = null;
334         var bestDistance = SUGGEST_MAX_DISTANCE + 1;
335         for (var p : published) {
336            var d = distance(topic, p);
337            if (d < bestDistance) {
338               best = p;
339               bestDistance = d;
340            }
341         }
342         return best == null ? "" : f(E41_SUGGEST, best);
343      }
344
345      // ---- declarations (E-40, E-45, E-46) ----------------------------------------------------------------------
346
347      void checkTopicDecl(int index, Map<?,?> decl) {
348         var topic = str(decl.get("topic"));
349         if ("job:*".equals(topic)) {
350            if (! "server".equals(str(decl.get("publisher"))))
351               add("E-45", E45_FRAMEWORK, "job");
352            return;
353         }
354         if (topic != null && topic.startsWith("data:") && TOPIC.matcher(topic).matches()) {
355            // A page-declared data: topic is published by a page script, and the bus keeps its last value (R-E4).
356            if (! "script".equals(str(decl.get("publisher"))) || ! Boolean.TRUE.equals(decl.get("retain")))
357               add("E-45", E45_FRAMEWORK, "data");
358            return;
359         }
360         checkDeclared(topic, decl.get("retain"), "topics[" + index + "]", null);
361      }
362
363      /** @param cardId The declaring card, or {@code null} for a page-level topics entry. */
364      void checkDeclared(String topic, Object retain, String where, String cardId) {
365         if (topic != null && cardId != null) {
366            var card = cards.get(cardId);
367            if (card != null && "chart".equals(str(card.get("type"))) && (topic.equals("zoom:" + cardId) || topic.equals("legend:" + cardId))) {
368               // Retained chart state: TopicDecl.toPublicationMap requires retain(true).
369               if (! Boolean.TRUE.equals(retain))
370                  add("E-45", E45_FRAMEWORK, family(topic));
371               return;
372            }
373         }
374         if (topic != null && CUSTOM_DECL.matcher(topic).matches()) {
375            var first = retains.putIfAbsent(topic, new Object[] { retain, where });
376            if (first != null && neq(first[0], retain))
377               add("E-46", E46, topic, retain, first[0], first[1]);
378            return;
379         }
380         var family = topic == null ? null : family(topic);
381         if (family != null && FRAMEWORK_FAMILIES.contains(family))
382            add("E-45", E45_FRAMEWORK, family);
383         else if (topic != null && UNNAMESPACED.matcher(topic).matches())
384            add("E-45", E45_NAMESPACE, family, family);
385         else
386            add("E-40", E40, topic);
387      }
388
389      // ---- cards ------------------------------------------------------------------------------------------------
390
391      void checkCard(Map<?,?> card) {
392         var id = str(card.get("id"));
393         for (var p : maps(card.get("publishes")))
394            checkDeclared(str(p.get("topic")), p.get("retain"), "card '" + id + "'", id);
395         var params = new LinkedHashSet<String>();
396         var hasParams = false;
397         for (var s : maps(card.get("subscribes"))) {
398            checkSubscription(card, s);
399            if ("params".equals(str(s.get("as")))) {
400               hasParams = true;
401               if (s.get("map") instanceof Map<?,?> m)
402                  m.keySet().forEach(k -> params.add(String.valueOf(k)));
403               else
404                  add("E-47", E47_MAP, id);
405            }
406         }
407         var items = ribbon(card);
408         for (var i = 0; i < items.size(); i++)
409            checkRibbonItem(card, i, items.get(i));
410         if (hasParams) {
411            checkTokens(id, "src", str(card.get("src")), params);
412            checkTokens(id, "dataUrl", str(view(card).get("dataUrl")), params);
413         }
414         if ("chart".equals(str(card.get("type"))))
415            checkChart(card);
416      }
417
418      // Keys a legacy flat chart card reads as helper keys (mirrors ChartDef.HELPER_KEYS in the freemarker module).
419      private static final List<String> LEGACY_HELPER_KEYS = List.of("x", "y", "series", "stacked", "orientation", "legend", "label",
420         "value", "center", "scale", "symbolSize", "groupBy", "size", "color", "tileFields");
421
422      // R-E2 (E-72), R-E5 (E-74) for one chart card.
423      void checkChart(Map<?,?> card) {
424         var id = str(card.get("id"));
425         var pubs = maps(card.get("publishes")).stream().map(p -> str(p.get("topic"))).filter(Objects::nonNull).collect(Collectors.toSet());
426         if (card.get("on") instanceof Map<?,?> on)
427            for (var e : on.entrySet()) {
428               var ev = String.valueOf(e.getKey());
429               var t = e.getValue() instanceof String ts ? ts : null;
430               if (! EVENT_NAME.matcher(ev).matches())
431                  add("E-74", E74, ev, "event");
432               if (t == null || ! pubs.contains(t))
433                  add("E-72", E72, id, ev, t != null ? t : "<not a string: " + e.getValue() + ">");
434            }
435         for (var d : maps(card.get("decorators"))) {
436            var use = str(d.get("use"));
437            if (use == null || ! EXTENSION_NAME.matcher(use).matches())
438               add("E-74", E74, use, "decorator");
439            walkFns(d);
440         }
441         walkFns(card.get("option"));
442         walkFns(card.get("patch"));
443         // helper values can be $fn markers (ChartDef.symbolSizeBy); a legacy flat card carries the helper keys at top level.
444         walkFns(card.get("helper"));
445         // A legacy flat body (only when it names a kind, as ChartCardType does) is walked as one map of its helper keys, so
446         // the series key skips series[*].data exactly like ChartCardType.
447         if (card.containsKey("kind")) {
448            var legacy = new LinkedHashMap<String,Object>();
449            for (var k : LEGACY_HELPER_KEYS)
450               if (card.containsKey(k))
451                  legacy.put(k, card.get(k));
452            walkFns(legacy);
453         }
454      }
455
456      // $fn markers: an object whose only keys are $fn and, optionally, args.  dataset[*].source and series[*].data are
457      // rows of data, never extension references, so they are not walked.
458      void walkFns(Object o) {
459         if (o instanceof Map<?,?> m) {
460            if (m.containsKey("$fn") && m.keySet().stream().allMatch(k -> "$fn".equals(k) || "args".equals(k))) {
461               var n = str(m.get("$fn"));
462               if (n == null || ! EXTENSION_NAME.matcher(n).matches())
463                  add("E-74", E74, n, "$fn");
464            }
465            for (var e : m.entrySet()) {
466               if ("dataset".equals(e.getKey()))
467                  walkSkipping(e.getValue(), "source");
468               else if ("series".equals(e.getKey()))
469                  walkSkipping(e.getValue(), "data");
470               else
471                  walkFns(e.getValue());
472            }
473         } else if (o instanceof List<?> l) {
474            l.forEach(this::walkFns);
475         }
476      }
477
478      /** Walks {@code o} (a map or a list of maps) without descending into the {@code skip} key of each map. */
479      void walkSkipping(Object o, String skip) {
480         if (o instanceof List<?> l) {
481            l.forEach(x -> walkSkipping(x, skip));
482         } else if (o instanceof Map<?,?> m) {
483            for (var e : m.entrySet())
484               if (! skip.equals(e.getKey()))
485                  walkFns(e.getValue());
486         }
487      }
488
489      // R-E3b (E-73): a cmd with target "group" needs a group some chart card declares.
490      void checkGroupCmd(String from, String key, Map<?,?> item) {
491         if (! (item.get("payload") instanceof Map<?,?> p) || ! "group".equals(str(p.get("target"))))
492            return;
493         var target = cards.get(key);
494         // Only a chart card has a group; a data source or another card type is not a group member.
495         if (target == null || ! "chart".equals(str(target.get("type"))) || str(target.get("group")) != null)
496            return;
497         var groups = cards.values().stream().filter(c -> "chart".equals(str(c.get("type")))).map(c -> str(c.get("group")))
498            .filter(Objects::nonNull).collect(Collectors.toCollection(TreeSet::new));
499         add("E-73", E73, from, str(p.get("op")), groups.isEmpty() ? "<none>" : "<none> (page groups: " + String.join(", ", groups) + ")");
500      }
501
502      // R-E6 (E-76 / E-77): ids are unique across cards, data sources and rail sections.
503      void checkIds() {
504         for (var id : nestedDuplicates)
505            add("E-76", "card '%s': %s", id, "id is declared more than once across nested cards");
506         var seenSources = new HashSet<String>();
507         for (var s : dataSources) {
508            var sid = str(s.get("id"));
509            if (sid == null) continue;
510            if (cards.containsKey(sid))
511               add("E-76", E76, sid, "id duplicates card '" + sid + "'");
512            else if (! seenSources.add(sid))
513               add("E-76", E76, sid, "id duplicates data source '" + sid + "'");
514         }
515         var seenSections = new HashSet<String>();
516         for (var s : sections) {
517            var sid = str(s.get("id"));
518            if (sid == null) continue;
519            if (cards.containsKey(sid))
520               add("E-77", E77, dashId, "section id '" + sid + "' duplicates card '" + sid + "'");
521            else if (sourceIds.contains(sid))
522               add("E-77", E77, dashId, "section id '" + sid + "' duplicates data source '" + sid + "'");
523            else if (! seenSections.add(sid))
524               add("E-77", E77, dashId, "section id '" + sid + "' duplicates section '" + sid + "'");
525         }
526      }
527
528      // E-77 page-level dashboard rules; the rest of E-77 is checked when the dashboard is built.
529      void checkDashboard() {
530         if (dashboard.isEmpty())
531            return;
532         var declared = new HashSet<String>();
533         for (var t : topics) {
534            var name = str(t.get("topic"));
535            if (name != null && name.startsWith("data:"))
536               declared.add(name);
537         }
538         sourceIds.stream().map(id -> "data:" + id).forEach(declared::add);
539         if (dashboard.get("status") instanceof List<?> status)
540            for (var o : status)
541               if (o instanceof String t && ! declared.contains(t))
542                  add("E-77", E77, dashId, "status topic '" + t + "' is not a declared data source");
543         for (var s : sections)
544            if ("choice".equals(str(s.get("kind"))) && ! declared.contains("data:" + str(s.get("source"))))
545               add("E-77", E77, dashId, "choice section '" + str(s.get("id")) + "' names source '" + str(s.get("source"))
546                  + "', which is not a declared data source");
547      }
548
549      // R-E1 inputs from derived sources, and R-E5 (E-74) for parser, builder and transform names.
550      void checkDataSources() {
551         for (var s : dataSources) {
552            if ("derived".equals(str(s.get("kind"))) && str(s.get("from")) != null)
553               dataReads.add("data:" + str(s.get("from")));
554            checkExtensionName(s.get("parser"), "parser");
555            checkExtensionName(s.get("builder"), "builder");
556            for (var t : maps(s.get("transforms")))
557               checkExtensionName(t.get("use"), "transform");
558         }
559      }
560
561      void checkExtensionName(Object name, String what) {
562         if (name != null && ! EXTENSION_NAME.matcher(String.valueOf(name)).matches())
563            add("E-74", E74, name, what);
564      }
565
566      // R-E1 (E-71): every data topic read or published has exactly one source publisher.
567      void checkDataTopics() {
568         var all = new TreeSet<>(dataReads);
569         all.addAll(dataPublishers.keySet());
570         for (var t : all) {
571            var n = dataPublishers.getOrDefault(t, 0);
572            if (n != 1)
573               add("E-71", E71, t, n);
574         }
575      }
576
577      // E-76: a derived source's input chain must not loop back on itself.  Each cycle is reported once, named from its
578      // smallest id; an input that is not a derived source ends the walk (a missing one is E-71 above).
579      void checkDerivedCycles() {
580         var from = new TreeMap<String,String>();
581         // A duplicate id is already E-76 from the duplicate-id rule; only the first derived entry for an id is walked.
582         for (var s : dataSources)
583            if ("derived".equals(str(s.get("kind"))) && str(s.get("id")) != null && str(s.get("from")) != null)
584               from.putIfAbsent(str(s.get("id")), str(s.get("from")));
585         var done = new HashSet<String>();
586         var cycles = new TreeMap<String,List<String>>();
587         for (var start : from.keySet()) {
588            var path = new ArrayList<String>();
589            var id = start;
590            while (id != null && from.containsKey(id) && ! done.contains(id) && ! path.contains(id)) {
591               path.add(id);
592               id = from.get(id);
593            }
594            if (id != null && path.contains(id)) {
595               var cycle = path.subList(path.indexOf(id), path.size());
596               var min = Collections.min(cycle);
597               var offset = cycle.indexOf(min);
598               var rotated = new ArrayList<String>();
599               for (var i = 0; i < cycle.size(); i++)
600                  rotated.add(cycle.get((offset + i) % cycle.size()));
601               cycles.put(min, rotated);
602            }
603            done.addAll(path);
604         }
605         for (var e : cycles.entrySet()) {
606            var c = e.getValue();
607            if (c.size() == 1)
608               add("E-76", E76, e.getKey(), "derived source '" + e.getKey() + "' references itself");
609            else
610               add("E-76", E76, e.getKey(), "derived source cycle: " + String.join(" -> ", c) + " -> " + e.getKey());
611         }
612      }
613
614      void checkTokens(String id, String field, String url, Set<String> mapped) {
615         if (url == null)
616            return;
617         var seen = new HashSet<String>();
618         var m = URL_TOKEN.matcher(url);
619         while (m.find())
620            if (! mapped.contains(m.group(1)) && seen.add(m.group(1)))
621               add("E-47", E47_TOKEN, id, m.group(1), field);
622      }
623
624      void checkSubscription(Map<?,?> card, Map<?,?> sub) {
625         var id = str(card.get("id"));
626         var topic = str(sub.get("topic"));
627         if (sub.get("handler") != null) {
628            // Handler subscription: the topic may carry scope placeholders, which are only known at run time, so a
629            // templated topic is checked for grammar alone.  No role applies (a role is the card class's own method).
630            var templated = topic != null && HANDLER_PLACEHOLDER.matcher(topic).find();
631            var concrete = topic == null ? null : HANDLER_PLACEHOLDER.matcher(topic).replaceAll("x");
632            if (concrete == null || ! TOPIC.matcher(concrete).matches())
633               add("E-40", E40, topic);
634            else if (! templated)
635               checkPublisher(id, topic);
636            return;
637         }
638         if (topic == null || ! TOPIC.matcher(topic).matches())
639            add("E-40", E40, topic);
640         else
641            checkPublisher(id, topic);
642         checkRole(card, str(sub.get("as")));
643      }
644
645      void checkPublisher(String id, String topic) {
646         var family = family(topic);
647         var key = key(topic);
648         if ("data".equals(family) && key != null) {
649            dataReads.add(topic);   // R-E1 counts publishers in checkDataTopics (E-71), not E-41
650            return;
651         }
652         if (FRAMEWORK_FAMILIES.contains(family) && key != null) {
653            if (CARD_FAMILIES.contains(family)) {
654               if (key.equals(id)) {
655                  add("E-49", E49, id, topic);
656                  return;
657               }
658               var target = cards.get(key);
659               if (target == null) {
660                  if (! targets.contains(key))
661                     add("E-42", E42, topic, key);
662                  // R-E3a: any cmd: may name a data source or section; R-E7: a section owns filter:<sectionId>.
663                  // Every other family keyed to a source or section has no publisher (R-E3a), so it is E-41
664                  // unless a declared topic matches it (isPublished covers script-declared topics, e.g. a wildcard).
665                  else if (! family.equals("cmd") && ! (family.equals("filter") && sectionIds.contains(key)) && ! isPublished(topic))
666                     add("E-41", E41, id, topic, suggest(topic));
667                  return;
668               }
669               if (family.equals("card") || family.equals("cmd"))
670                  return;
671               var type = str(target.get("type"));
672               if (type == null || ! registry.isRegistered(type) || published.contains(topic))
673                  return;
674               if ("datatables".equals(type) && DATATABLES_OPT_IN.contains(family))
675                  add("E-41", E41, id, topic, f(E41_NOT_ENABLED, key, family));
676               else
677                  add("E-43", E43_PUBLISH, key, type, topic);
678               return;
679            }
680            // probe: and badge: are owned by toolkit runtimes the contract does not describe; JS checks them.
681            if (family.equals("probe") || family.equals("badge"))
682               return;
683         }
684         if (! isPublished(topic))
685            add("E-41", E41, id, topic, suggest(topic));
686      }
687
688      void checkRole(Map<?,?> card, String as) {
689         if (as == null || SHELL_ROLES.contains(as))
690            return;
691         var type = str(card.get("type"));
692         if (type == null || ! registry.isRegistered(type))
693            return;
694         var roles = registry.handler(type).acceptedRoles();
695         if (roles == null || roles.contains(as))
696            return;
697         var accepted = new TreeSet<>(SHELL_ROLES);
698         accepted.addAll(roles);
699         add("E-44", E44, str(card.get("id")), type, as, String.join(", ", accepted));
700      }
701
702      // ---- ribbon items (E-42, E-43, E-48) ----------------------------------------------------------------------
703
704      void checkRibbonItem(Map<?,?> card, int index, Map<?,?> item) {
705         var id = str(card.get("id"));
706         var type = str(item.get("type"));
707         var label = "#" + index + " (" + type + ")";
708         if ("publish".equals(type)) {
709            checkPublishItem(id, label, item);
710            return;
711         }
712         var target = item.get("target");
713         if (target == null)
714            return;
715         if (type == null || ! RIBBON_OPS.containsKey(type)) {
716            add("E-48", E48, label, id, "'target' is not allowed on a '" + type + "' item");
717            return;
718         }
719         var tid = str(target);
720         var tc = tid == null ? null : cards.get(tid);
721         var op = RIBBON_OPS.get(type);
722         if (tc == null) {
723            if (tid == null || ! targets.contains(tid))
724               add("E-42", E42, "cmd:" + tid, tid);
725            // The op the ribbon actually sends (a refresh item sends "reload") must be one a source handles (R-E3a).
726            else if (sourceIds.contains(tid) && ! SOURCE_OPS.contains(op))
727               add("E-43", E43_OP, tid, SOURCE_TYPE, op);
728            return;
729         }
730         var ttype = str(tc.get("type"));
731         if (ttype != null && registry.isRegistered(ttype)) {
732            var ops = registry.handler(ttype).acceptedOps();
733            if (ops != null && ! ops.contains(op)) {
734               add("E-43", E43_OP, tid, ttype, op);
735               return;
736            }
737         }
738         if (op.equals("set-filter") && ! tid.equals(id)) {
739            var option = str(item.get("id"));
740            if (! declaredOptions(tc).contains(option))
741               add("E-48", E48, label, id, "option '" + option + "' is not declared on target card '" + tid + "'");
742         }
743      }
744
745      void checkPublishItem(String id, String label, Map<?,?> item) {
746         if (str(item.get("title")) == null)
747            add("E-48", E48, label, id, "a publish item needs a title");
748         var topic = str(item.get("topic"));
749         if (topic == null || ! TOPIC.matcher(topic).matches()) {
750            add("E-40", E40, topic);
751            return;
752         }
753         var family = family(topic);
754         if (FRAMEWORK_FAMILIES.contains(family)) {
755            var key = key(topic);
756            if (family.equals("cmd") && key != null) {
757               if (! targets.contains(key))
758                  add("E-42", E42, topic, key);
759               else {
760                  checkSourceOp(key, item);
761                  checkGroupCmd(id, key, item);
762               }
763               return;
764            }
765            add("E-48", E48, label, id, "'" + topic + "' is a framework topic; a publish item may only publish custom topics or cmd:<cardId>");
766            return;
767         }
768         if (! declaredCustom(topic, Set.of("script", "server", "ribbon"), true))
769            add("E-48", E48, label, id, "topic '" + topic + "' is not declared in topics or by any card's publishes");
770      }
771
772      // R-E3a (E-43): a data source handles only SOURCE_OPS; a payload without an op passes.
773      void checkSourceOp(String key, Map<?,?> item) {
774         if (! sourceIds.contains(key) || cards.containsKey(key) || ! (item.get("payload") instanceof Map<?,?> p))
775            return;
776         var op = str(p.get("op"));
777         if (op != null && ! SOURCE_OPS.contains(op))
778            add("E-43", E43_OP, key, SOURCE_TYPE, op);
779      }
780
781      /**
782       * The option ids a card declares on its own ribbon: its untargeted (or self-targeted) {@code option} and
783       * {@code optionGroup} items.  The {@code tableCatalog} has no {@code filterOptions} key, so the ribbon is the
784       * only place an option id can be declared.
785       */
786      Set<String> declaredOptions(Map<?,?> card) {
787         var out = new HashSet<String>();
788         var cid = str(card.get("id"));
789         for (var item : ribbon(card)) {
790            var type = str(item.get("type"));
791            var target = str(item.get("target"));
792            if (("option".equals(type) || "optionGroup".equals(type)) && (target == null || target.equals(cid)) && str(item.get("id")) != null)
793               out.add(str(item.get("id")));
794         }
795         return out;
796      }
797
798      // ---- bridges (E-51, E-53, E-54) and R-11 (E-52) -----------------------------------------------------------
799
800      void checkBridges() {
801         var seen = new HashSet<String>();
802         for (var b : bridges) {
803            var id = str(b.get("id"));
804            var name = id == null ? "?" : id;
805            if (id == null || ! BRIDGE_ID.matcher(id).matches())
806               add("E-51", E51, name, "id must match " + BRIDGE_ID.pattern());
807            else if (! seen.add(id))
808               add("E-51", E51, name, "duplicate id");
809            var transport = str(b.get("transport"));
810            if (! "sse".equals(transport) && ! "websocket".equals(transport))
811               add("E-51", E51, name, "unknown transport '" + transport + "'");
812            var session = str(b.get("session"));
813            if (session == null || ! SAME_ORIGIN_PATH.matcher(session).matches())
814               add("E-51", E51, name, "session must be a same-origin path, got '" + session + "'");
815            var max = b.get("maxAttempts");
816            if (max != null && ! ((max instanceof Integer || max instanceof Long) && ((Number)max).longValue() >= 1))
817               add("E-51", E51, name, "maxAttempts must be an integer of at least 1");
818            var down = strings(b.get("downstream"));
819            var up = strings(b.get("upstream"));
820            if (! up.isEmpty() && ! "websocket".equals(transport))
821               add("E-51", E51, name, "upstream is only allowed on a websocket bridge");
822            for (var d : down)
823               checkDownstream(name, d);
824            for (var u : up)
825               checkUpstream(name, u);
826            for (var d : down)
827               if (up.contains(d))
828                  add("E-51", E51, name, "topic '" + d + "' is both downstream and upstream");
829         }
830      }
831
832      void checkDownstream(String bridge, String topic) {
833         if (! "job:*".equals(topic) && ! TOPIC.matcher(topic).matches() && ! CUSTOM_DECL.matcher(topic).matches()) {
834            add("E-51", E51, bridge, "invalid topic '" + topic + "'");
835            return;
836         }
837         var family = family(topic);
838         if (FRAMEWORK_FAMILIES.contains(family)) {
839            var key = key(topic);
840            if (family.equals("job"))
841               return;
842            if (family.equals("cmd") && key != null) {
843               if (! cards.containsKey(key))
844                  add("E-42", E42, topic, key);
845               return;
846            }
847            add("E-54", E54, bridge, topic);
848            return;
849         }
850         if (! declaredCustom(topic, Set.of("server"), false))
851            add("E-51", E51, bridge, "downstream '" + topic + "' is not declared in topics with publisher=server");
852      }
853
854      void checkUpstream(String bridge, String topic) {
855         if (! TOPIC.matcher(topic).matches() && ! CUSTOM_DECL.matcher(topic).matches()) {
856            add("E-51", E51, bridge, "invalid topic '" + topic + "'");
857            return;
858         }
859         if (FRAMEWORK_FAMILIES.contains(family(topic))) {
860            add("E-54", E54, bridge, topic);
861            return;
862         }
863         if (! declaredCustom(topic, Set.of("script", "ribbon"), true))
864            add("E-53", E53, bridge, topic);
865      }
866
867      /** A top-level topics entry with one of {@code publishers}, or (when {@code cardPublishes}) a card's publishes, matches. */
868      boolean declaredCustom(String topic, Set<String> publishers, boolean cardPublishes) {
869         for (var t : topics) {
870            var decl = str(t.get("topic"));
871            if (decl != null && str(t.get("publisher")) != null && publishers.contains(str(t.get("publisher"))) && topicMatches(decl, topic))
872               return true;
873         }
874         if (cardPublishes)
875            for (var c : cards.values())
876               for (var p : maps(c.get("publishes"))) {
877                  var decl = str(p.get("topic"));
878                  if (decl != null && topicMatches(decl, topic))
879                     return true;
880               }
881         return false;
882      }
883
884      /** E-58: a terminal card with {@code input: true} must carry the whole input wiring (publish, subscribe, server topic, bridge). */
885      @SuppressWarnings({
886         "java:S135" // Guard clauses keep the card filtering readable
887      })
888      void checkTerminalInput() {
889         for (var c : cards.values()) {
890            if (! "terminal".equals(str(c.get("type"))))
891               continue;
892            if (! (c.get("terminal") instanceof Map<?,?> term) || ! Boolean.TRUE.equals(term.get("input")))
893               continue;
894            var id = str(c.get("id"));
895            var publishes = false;
896            for (var p : maps(c.get("publishes")))
897               publishes |= "term.input".equals(str(p.get("topic")));
898            if (! publishes)
899               add("E-58", E58, id, "its publishes lacks 'term.input'");
900            var subscribes = false;
901            for (var s : maps(c.get("subscribes")))
902               subscribes |= "term.input-status".equals(str(s.get("topic"))) && "input-status".equals(str(s.get("as")));
903            if (! subscribes)
904               add("E-58", E58, id, "its subscribes lacks 'term.input-status' as 'input-status'");
905            var declared = false;
906            for (var t : topics)
907               declared |= "term.input-status".equals(str(t.get("topic"))) && "server".equals(str(t.get("publisher")));
908            if (! declared)
909               add("E-58", E58, id, "no topics entry declares 'term.input-status' with publisher=server");
910            var bridged = false;
911            for (var b : bridges)
912               bridged |= "websocket".equals(str(b.get("transport"))) && strings(b.get("upstream")).contains("term.input")
913                  && strings(b.get("downstream")).contains("term.input-status");
914            if (! bridged)
915               add("E-58", E58, id, "no websocket bridge carries 'term.input' upstream and 'term.input-status' downstream");
916         }
917      }
918
919      void checkServerTopics() {
920         for (var t : topics) {
921            var topic = str(t.get("topic"));
922            // A data: topic published by the server is already E-45 (it must be script-published).
923            if (topic == null || topic.startsWith("data:") || ! "server".equals(str(t.get("publisher"))))
924               continue;
925            var covered = false;
926            for (var b : bridges)
927               for (var d : strings(b.get("downstream")))
928                  covered |= topicMatches(d, topic);
929            if (! covered)
930               add("E-52", E52, topic);
931         }
932      }
933   }
934
935   // ---- JSON helpers -----------------------------------------------------------------------------------------------
936
937   static String family(String topic) {
938      var i = topic.indexOf(':');
939      return i < 0 ? topic : topic.substring(0, i);
940   }
941
942   static String key(String topic) {
943      var i = topic.indexOf(':');
944      return i < 0 ? null : topic.substring(i + 1);
945   }
946
947   static String str(Object o) {
948      return o instanceof String s ? s : null;
949   }
950
951   @SuppressWarnings({
952      "java:S1452" // wildcard return reflects heterogeneous element types
953   })
954   static List<Map<?,?>> maps(Object o) {
955      var out = new ArrayList<Map<?,?>>();
956      if (o instanceof List<?> l)
957         for (var e : l)
958            if (e instanceof Map<?,?> m)
959               out.add(m);
960      return out;
961   }
962
963   static List<String> strings(Object o) {
964      var out = new ArrayList<String>();
965      if (o instanceof List<?> l)
966         for (var e : l)
967            if (e instanceof String s)
968               out.add(s);
969      return out;
970   }
971
972   /** A datatables card's catalog (its {@code table}), or the card itself for every other shape. */
973   @SuppressWarnings({
974      "java:S1452" // wildcard return reflects heterogeneous element types
975   })
976   static Map<?,?> view(Map<?,?> card) {
977      return card.get("table") instanceof Map<?,?> t ? t : card;
978   }
979
980   @SuppressWarnings({
981      "java:S1452" // wildcard return reflects heterogeneous element types
982   })
983   static List<Map<?,?>> ribbon(Map<?,?> card) {
984      return maps(view(card).get("ribbon"));
985   }
986
987   @SuppressWarnings({
988      "unchecked" // Narrows a JSON-shaped Map<?,?> to Map<String,Object>; its keys are always strings.
989   })
990   static JsonMap json(Map<?,?> m) {
991      if (m instanceof JsonMap j)
992         return j;
993      var j = new JsonMap();
994      j.putAll((Map<String,Object>)m);
995      return j;
996   }
997}