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}