tutuca 0.9.21 → 0.9.23

package/dist/tutuca-cli.js

@@ -67,13 +67,10 @@ MODULE CONVENTION
       -> Component[]                      // results of tutuca's component()
 
     export function getExamples()         // required for render/doctor
-      -> {
-           title: string,
-           description?: string,
-           groups?: [{ title, description?, items: Example[] }],
-           items:  Example[]              // at least one of items/groups
-         }
-      where Example = { title, description?, value, view? }
+      -> Section | Section[]              // single section or an array
+      where Section = { title: string, description?: string,
+                        items: Example[] }
+      and   Example = { title, description?, value, view? }
       and   value   = an instance returned by <Component>.make(...)
       and   view    = a view name (defaults to "main")
 
@@ -85,21 +82,20 @@ MODULE CONVENTION
 
     export function getRoot()             // optional; returned by info
 
-  The legacy flat \`getExamples() -> Example[]\` shape and the legacy
-  \`getStoryBookSection()\` name both fail fast with EXAMPLES_SHAPE_MISMATCH.
+  The legacy \`getStoryBookSection()\` name fails fast with
+  EXAMPLES_SHAPE_MISMATCH — rename it to \`getExamples\`.
 
 COMMANDS (require <module-path>)
   info
       Summarize which getX() exports are present and count components,
-      macros, request handlers, examples, and groups. Good first step.
+      macros, request handlers, examples, and sections. Good first step.
 
   list
       List each component with its declared views and fields (name, type).
 
   examples
-      Print the module's example section: title, description, flat items
-      and/or grouped items. Each item shows its resolved component name
-      and view.
+      Print the module's example sections: title, description, items.
+      Each item shows its resolved component name and view.
 
   docs [name]
       Generate API docs (methods, input handlers, fields with their
@@ -219,8 +215,8 @@ class ComponentList {
 }
 
 class ExampleIndex {
-  constructor({ section }) {
-    this.section = section;
+  constructor({ sections }) {
+    this.sections = sections;
   }
 }
 
@@ -231,10 +227,11 @@ class ComponentDocs {
 }
 
 class LintFinding {
-  constructor({ id, level, info }) {
+  constructor({ id, level, info, context = {} }) {
     this.id = id;
     this.level = level;
     this.info = info;
+    this.context = context;
   }
 }
 
@@ -268,7 +265,6 @@ class LintReport {
 
 class RenderedExample {
   constructor({
-    groupTitle = null,
     title,
     description = null,
     componentName,
@@ -276,7 +272,6 @@ class RenderedExample {
     html,
     error = null
   }) {
-    this.groupTitle = groupTitle;
     this.title = title;
     this.description = description;
     this.componentName = componentName;
@@ -286,13 +281,20 @@ class RenderedExample {
   }
 }
 
-class RenderBatch {
-  constructor({ section, items }) {
-    this.section = section;
+class RenderedSection {
+  constructor({ title, description = null, items }) {
+    this.title = title;
+    this.description = description;
     this.items = items;
   }
+}
+
+class RenderBatch {
+  constructor({ sections }) {
+    this.sections = sections;
+  }
   get hasErrors() {
-    return this.items.some((i) => i.error !== null);
+    return this.sections.some((s) => s.items.some((i) => i.error !== null));
   }
 }
 
@@ -326,59 +328,41 @@ function resolveComponentName(value, components) {
   return null;
 }
 
-class ExampleGroup {
-  constructor({ title, description = null, items }) {
-    this.title = title;
-    this.description = description;
-    this.items = items;
-  }
-}
-
 class ExampleSection {
-  constructor({ title, description = null, groups = [], items = [] }) {
+  constructor({ title, description = null, items = [] }) {
     this.title = title;
     this.description = description;
-    this.groups = groups;
     this.items = items;
   }
-  *flatten() {
-    for (const item of this.items) {
-      yield { groupTitle: null, example: item };
-    }
-    for (const group of this.groups) {
-      for (const item of group.items) {
-        yield { groupTitle: group.title, example: item };
-      }
-    }
-  }
 }
 
 class NormalizedModule {
-  constructor({ mod, path = null, components, macros, requestHandlers, section, root }) {
+  constructor({ mod, path = null, components, macros, requestHandlers, sections, root }) {
     this.mod = mod;
     this.path = path;
     this.components = components;
     this.macros = macros;
     this.requestHandlers = requestHandlers;
-    this.section = section;
+    this.sections = sections;
     this.root = root;
   }
 }
-function parseExample(raw, index, components) {
+function shapeError(message, where) {
+  const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: ${message}`);
+  err.code = EXAMPLES_SHAPE_MISMATCH;
+  err.where = where;
+  return err;
+}
+function parseExample(raw, index, components, parentPath) {
+  const where = `${parentPath}.items[${index}]`;
   if (!raw || typeof raw !== "object") {
-    const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: example at index ${index} is not an object`);
-    err.code = EXAMPLES_SHAPE_MISMATCH;
-    throw err;
+    throw shapeError(`example at ${where} is not an object`, where);
   }
   if (raw.value === undefined && raw.item !== undefined) {
-    const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: example at index ${index} uses legacy "item" key; rename to "value"`);
-    err.code = EXAMPLES_SHAPE_MISMATCH;
-    throw err;
+    throw shapeError(`example at ${where} uses legacy "item" key; rename to "value"`, where);
   }
   if (raw.value === undefined) {
-    const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: example at index ${index} missing "value"`);
-    err.code = EXAMPLES_SHAPE_MISMATCH;
-    throw err;
+    throw shapeError(`example at ${where} missing "value"`, where);
   }
   return new Example({
     title: raw.title ?? `Example ${index + 1}`,
@@ -388,42 +372,29 @@ function parseExample(raw, index, components) {
     componentName: resolveComponentName(raw.value, components)
   });
 }
-function parseGroup(raw, index, components) {
-  if (!raw || typeof raw !== "object" || !Array.isArray(raw.items)) {
-    const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: group at index ${index} must have an "items" array`);
-    err.code = EXAMPLES_SHAPE_MISMATCH;
-    throw err;
+function parseSection(raw, components, where) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw shapeError(`section at ${where} must be an object { title, description?, items }`, where);
+  }
+  const items = Array.isArray(raw.items) ? raw.items.map((e, i) => parseExample(e, i, components, where)) : [];
+  if (items.length === 0) {
+    throw shapeError(`section at ${where} has no items`, where);
   }
-  return new ExampleGroup({
-    title: raw.title ?? `Group ${index + 1}`,
+  return new ExampleSection({
+    title: raw.title ?? "Examples",
     description: raw.description ?? null,
-    items: raw.items.map((e, i) => parseExample(e, i, components))
+    items
   });
 }
-function parseSection(raw, components) {
+function parseSections(raw, components) {
+  const where = "examples";
   if (Array.isArray(raw)) {
-    const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: getExamples() returned a flat array; expected a section ` + `object { title, description?, groups?, items }.`);
-    err.code = EXAMPLES_SHAPE_MISMATCH;
-    throw err;
+    return raw.map((r, i) => parseSection(r, components, `${where}[${i}]`));
   }
   if (!raw || typeof raw !== "object") {
-    const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: getExamples() must return a section object`);
-    err.code = EXAMPLES_SHAPE_MISMATCH;
-    throw err;
-  }
-  const items = Array.isArray(raw.items) ? raw.items.map((e, i) => parseExample(e, i, components)) : [];
-  const groups = Array.isArray(raw.groups) ? raw.groups.map((g, i) => parseGroup(g, i, components)) : [];
-  if (items.length === 0 && groups.length === 0) {
-    const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: getExamples() returned a section with no items or groups`);
-    err.code = EXAMPLES_SHAPE_MISMATCH;
-    throw err;
+    throw shapeError("getExamples() must return a section object or an array of section objects", where);
   }
-  return new ExampleSection({
-    title: raw.title ?? "Examples",
-    description: raw.description ?? null,
-    groups,
-    items
-  });
+  return [parseSection(raw, components, where)];
 }
 function normalizeModule(mod, { path = null } = {}) {
   const present = new Set;
@@ -439,15 +410,13 @@ function normalizeModule(mod, { path = null } = {}) {
       present.add(key);
   }
   if (present.has("getStoryBookSection") && !present.has("getExamples")) {
-    const err = new Error(`${EXAMPLES_SHAPE_MISMATCH}: module exports getStoryBookSection; rename it to getExamples.`);
-    err.code = EXAMPLES_SHAPE_MISMATCH;
-    throw err;
+    throw shapeError("module exports getStoryBookSection; rename it to getExamples.", "module");
   }
   const components = present.has("getComponents") ? mod.getComponents() : [];
   const macros = present.has("getMacros") ? mod.getMacros() : null;
   const requestHandlers = present.has("getRequestHandlers") ? mod.getRequestHandlers() : null;
   const root = present.has("getRoot") ? mod.getRoot() : null;
-  const section = present.has("getExamples") ? parseSection(mod.getExamples(), components) : null;
+  const sections = present.has("getExamples") ? parseSections(mod.getExamples(), components) : [];
   return {
     normalized: new NormalizedModule({
       mod,
@@ -455,7 +424,7 @@ function normalizeModule(mod, { path = null } = {}) {
       components,
       macros,
       requestHandlers,
-      section,
+      sections,
       root
     }),
     present
@@ -469,14 +438,17 @@ function describeModule(mod, { path = null } = {}) {
     components: normalized.components.length,
     macros: normalized.macros ? Object.keys(normalized.macros).length : 0,
     requestHandlers: normalized.requestHandlers ? Object.keys(normalized.requestHandlers).length : 0,
-    examples: normalized.section ? normalized.section.items.length + normalized.section.groups.reduce((n, g) => n + g.items.length, 0) : 0,
-    groups: normalized.section ? normalized.section.groups.length : 0
+    examples: normalized.sections.reduce((n, s) => n + s.items.length, 0),
+    sections: normalized.sections.length
   };
   const warnings = [];
   if (!normalized.components.length)
     warnings.push("module exports no components");
-  if (!normalized.section)
+  if (!present.has("getExamples")) {
     warnings.push("module exports no getExamples()");
+  } else if (normalized.sections.length === 0) {
+    warnings.push("getExamples() returned no sections");
+  }
   return new ModuleInfo({ path, present, counts, warnings });
 }
 
@@ -517,7 +489,7 @@ function fmtModuleInfo(info) {
   lines.push(`Components: ${info.counts.components}`);
   lines.push(`Macros: ${info.counts.macros}`);
   lines.push(`Request handlers: ${info.counts.requestHandlers}`);
-  lines.push(`Examples: ${info.counts.examples} (groups: ${info.counts.groups})`);
+  lines.push(`Examples: ${info.counts.examples} (sections: ${info.counts.sections})`);
   if (info.warnings.length) {
     lines.push("");
     lines.push("Warnings:");
@@ -541,18 +513,13 @@ function fmtComponentList(list) {
 `);
 }
 function fmtExampleIndex(idx) {
-  if (!idx.section)
+  if (idx.sections.length === 0)
     return "(no examples)";
   const lines = [];
-  const s = idx.section;
-  lines.push(`${s.title}${s.description ? ` — ${s.description}` : ""}`);
-  for (const item of s.items) {
-    lines.push(`  - ${item.title}${item.description ? ` — ${item.description}` : ""} [${item.componentName}${item.view !== "main" ? `/${item.view}` : ""}]`);
-  }
-  for (const group of s.groups) {
-    lines.push(`  [${group.title}]${group.description ? ` — ${group.description}` : ""}`);
-    for (const item of group.items) {
-      lines.push(`    - ${item.title}${item.description ? ` — ${item.description}` : ""} [${item.componentName}${item.view !== "main" ? `/${item.view}` : ""}]`);
+  for (const s of idx.sections) {
+    lines.push(`${s.title}${s.description ? ` — ${s.description}` : ""}`);
+    for (const item of s.items) {
+      lines.push(`  - ${item.title}${item.description ? ` — ${item.description}` : ""} [${item.componentName}${item.view !== "main" ? `/${item.view}` : ""}]`);
     }
   }
   return lines.join(`
@@ -604,8 +571,9 @@ function fmtLintReport(rep) {
     lines.push(`${c.componentName}:`);
     for (const f of c.findings) {
       const tag = f.level.toUpperCase();
+      const view = f.context?.viewName ? ` view=${f.context.viewName}` : "";
       const extra = fmtFindingInfo(f.info);
-      lines.push(`  [${tag}] ${f.id}${extra ? ` (${extra})` : ""}`);
+      lines.push(`  [${tag}] ${f.id}${view}${extra ? ` (${extra})` : ""}`);
     }
   }
   lines.push("");
@@ -614,21 +582,16 @@ function fmtLintReport(rep) {
 `);
 }
 function fmtRenderBatch(batch) {
-  if (batch.items.length === 0)
+  const totalItems = batch.sections.reduce((n, s) => n + s.items.length, 0);
+  if (totalItems === 0)
     return "(no examples rendered)";
   const lines = [];
-  if (batch.section) {
-    lines.push(`${batch.section.title}${batch.section.description ? ` — ${batch.section.description}` : ""}`);
-  }
-  let currentGroup = undefined;
-  for (const item of batch.items) {
-    if (item.groupTitle !== currentGroup) {
-      currentGroup = item.groupTitle;
-      if (currentGroup)
-        lines.push(`  [${currentGroup}]`);
+  for (const section of batch.sections) {
+    lines.push(`${section.title}${section.description ? ` — ${section.description}` : ""}`);
+    for (const item of section.items) {
+      const status = item.error ? `ERROR: ${item.error.message}` : `${item.html.length} bytes`;
+      lines.push(`  ${item.title} [${item.componentName}] — ${status}`);
     }
-    const status = item.error ? `ERROR: ${item.error.message}` : `${item.html.length} bytes`;
-    lines.push(`  ${item.title} [${item.componentName}] — ${status}`);
   }
   return lines.join(`
 `);
@@ -711,67 +674,53 @@ function fmtComponentDocs2(docs) {
 async function fmtRenderBatch2(batch, { pretty = false } = {}) {
   const prettify = pretty ? (await import("prettier")).format : null;
   const lines = [];
-  if (batch.section) {
-    lines.push(`# ${batch.section.title}`);
-    if (batch.section.description)
+  for (const section of batch.sections) {
+    lines.push(`# ${section.title}`);
+    if (section.description)
       lines.push(`
-${batch.section.description}`);
+${section.description}`);
     lines.push("");
-  }
-  let currentGroup = undefined;
-  for (const item of batch.items) {
-    if (item.groupTitle !== currentGroup) {
-      currentGroup = item.groupTitle;
-      if (currentGroup)
-        lines.push(`## ${currentGroup}
-`);
-    }
-    const depth = currentGroup ? "###" : "##";
-    lines.push(`${depth} ${item.title}
+    for (const item of section.items) {
+      lines.push(`## ${item.title}
 `);
-    if (item.description)
-      lines.push(`${item.description}
+      if (item.description)
+        lines.push(`${item.description}
 `);
-    if (item.error) {
-      lines.push("```");
-      lines.push(`ERROR: ${item.error.message}`);
+      if (item.error) {
+        lines.push("```");
+        lines.push(`ERROR: ${item.error.message}`);
+        lines.push("```\n");
+        continue;
+      }
+      let html = item.html;
+      if (prettify) {
+        try {
+          html = (await prettify(html, { parser: "html" })).trimEnd();
+        } catch {}
+      }
+      lines.push("```html");
+      lines.push(html);
       lines.push("```\n");
-      continue;
-    }
-    let html = item.html;
-    if (prettify) {
-      try {
-        html = (await prettify(html, { parser: "html" })).trimEnd();
-      } catch {}
     }
-    lines.push("```html");
-    lines.push(html);
-    lines.push("```\n");
   }
   return lines.join(`
 `);
 }
 function fmtExampleIndex2(idx) {
-  if (!idx.section)
+  if (idx.sections.length === 0)
     return "_(no examples)_";
-  const s = idx.section;
-  const lines = [`# ${s.title}`];
-  if (s.description)
-    lines.push("", s.description);
-  if (s.items.length) {
-    lines.push("");
-    for (const item of s.items) {
-      lines.push(`- **${item.title}** — \`${item.componentName}\`${item.description ? ` — ${item.description}` : ""}`);
+  const lines = [];
+  for (const s of idx.sections) {
+    lines.push(`# ${s.title}`);
+    if (s.description)
+      lines.push("", s.description);
+    if (s.items.length) {
+      lines.push("");
+      for (const item of s.items) {
+        lines.push(`- **${item.title}** — \`${item.componentName}\`${item.description ? ` — ${item.description}` : ""}`);
+      }
     }
-  }
-  for (const group of s.groups) {
-    lines.push("", `## ${group.title}`);
-    if (group.description)
-      lines.push("", group.description);
     lines.push("");
-    for (const item of group.items) {
-      lines.push(`- **${item.title}** — \`${item.componentName}\`${item.description ? ` — ${item.description}` : ""}`);
-    }
   }
   return lines.join(`
 `);
@@ -785,7 +734,8 @@ function fmtLintReport2(rep) {
       continue;
     }
     for (const f of c.findings) {
-      lines.push(`- **${f.level.toUpperCase()}** \`${f.id}\``);
+      const view = f.context?.viewName ? ` — view: \`${f.context.viewName}\`` : "";
+      lines.push(`- **${f.level.toUpperCase()}** \`${f.id}\`${view}`);
     }
     lines.push("");
   }
@@ -799,7 +749,7 @@ function fmtModuleInfo2(info) {
   lines.push(`- Components: ${info.counts.components}`);
   lines.push(`- Macros: ${info.counts.macros}`);
   lines.push(`- Request handlers: ${info.counts.requestHandlers}`);
-  lines.push(`- Examples: ${info.counts.examples} (groups: ${info.counts.groups})`);
+  lines.push(`- Examples: ${info.counts.examples} (sections: ${info.counts.sections})`);
   if (info.warnings.length) {
     lines.push("", "## Warnings", "");
     for (const w of info.warnings)
@@ -875,19 +825,22 @@ var supports4 = new Set(["RenderBatch"]);
 async function format4(result, { pretty = false } = {}) {
   const prettify = pretty ? (await import("prettier")).format : null;
   const parts = [];
-  for (const item of result.items) {
-    if (item.error) {
-      parts.push(`<!-- ERROR ${item.title}: ${item.error.message} -->`);
-      continue;
-    }
-    let html = item.html;
-    if (prettify) {
-      try {
-        html = (await prettify(html, { parser: "html" })).trimEnd();
-      } catch {}
+  for (const section of result.sections) {
+    parts.push(`<!-- === ${section.title} === -->`);
+    for (const item of section.items) {
+      if (item.error) {
+        parts.push(`<!-- ERROR ${item.title}: ${item.error.message} -->`);
+        continue;
+      }
+      let html = item.html;
+      if (prettify) {
+        try {
+          html = (await prettify(html, { parser: "html" })).trimEnd();
+        } catch {}
+      }
+      parts.push(`<!-- ${item.title} -->`);
+      parts.push(html);
     }
-    parts.push(`<!-- ${item.title} -->`);
-    parts.push(html);
   }
   return parts.join(`
 `);
@@ -1000,10 +953,7 @@ __export(exports_examples, {
 
 // tools/core/list-examples.js
 function listExamples(normalized) {
-  if (!normalized.section) {
-    return new ExampleIndex({ section: null });
-  }
-  return new ExampleIndex({ section: normalized.section });
+  return new ExampleIndex({ sections: normalized.sections });
 }
 
 // tools/cli/commands/examples.js
@@ -2895,18 +2845,20 @@ var LEVEL_WARN = "warn";
 var LEVEL_ERROR = "error";
 var LEVEL_HINT = "hint";
 function checkComponent(Comp, lx = new LintContext) {
-  const referencedAlters = new Set;
-  const referencedInputs = new Set;
-  const referencedComputed = new Set;
-  checkEventHandlersHaveImpls(lx, Comp, referencedInputs);
-  checkConsistentAttrs(lx, Comp, referencedAlters, referencedComputed);
-  for (const name in Comp.views) {
-    checkView(lx, Comp.views[name], Comp, referencedAlters, referencedComputed);
-  }
-  checkUnreferencedAlterHandlers(lx, Comp, referencedAlters);
-  checkUnreferencedInputHandlers(lx, Comp, referencedInputs);
-  checkUnreferencedComputed(lx, Comp, referencedComputed);
-  return lx;
+  return lx.push({ componentName: Comp.name }, () => {
+    const referencedAlters = new Set;
+    const referencedInputs = new Set;
+    const referencedComputed = new Set;
+    checkEventHandlersHaveImpls(lx, Comp, referencedInputs);
+    checkConsistentAttrs(lx, Comp, referencedAlters, referencedComputed);
+    for (const name in Comp.views) {
+      lx.push({ viewName: name }, () => checkView(lx, Comp.views[name], Comp, referencedAlters, referencedComputed));
+    }
+    checkUnreferencedAlterHandlers(lx, Comp, referencedAlters);
+    checkUnreferencedInputHandlers(lx, Comp, referencedInputs);
+    checkUnreferencedComputed(lx, Comp, referencedComputed);
+    return lx;
+  });
 }
 function checkView(lx, view, Comp, referencedAlters, referencedComputed) {
   checkRenderItInLoop(lx, view);
@@ -2914,17 +2866,45 @@ function checkView(lx, view, Comp, referencedAlters, referencedComputed) {
   checkKnownHandlerNames(lx, view, Comp, referencedAlters, referencedComputed);
 }
 function checkRenderItInLoop(lx, view) {
-  const { nodes } = view.ctx;
-  for (let i = 0;i < nodes.length; i++) {
-    const node = nodes[i];
+  let hasRenderIt = false;
+  for (const node of view.ctx.nodes) {
     if (node.constructor.name === "RenderItNode") {
-      const next = nodes[i + 1];
-      const nextName = next?.constructor.name;
-      if (nextName !== "EachNode" && nextName !== "RenderEachNode") {
-        lx.error(RENDER_IT_OUTSIDE_OF_LOOP, { node });
-      }
+      hasRenderIt = true;
+      break;
     }
   }
+  if (!hasRenderIt)
+    return;
+  walkForRenderIt(lx, view.anode, 0);
+}
+function walkForRenderIt(lx, node, loopDepth) {
+  if (node === null || node === undefined)
+    return;
+  switch (node.constructor.name) {
+    case "RenderItNode":
+      if (loopDepth === 0)
+        lx.error(RENDER_IT_OUTSIDE_OF_LOOP, { node });
+      return;
+    case "EachNode":
+      walkForRenderIt(lx, node.node, loopDepth + 1);
+      return;
+    case "ShowNode":
+    case "HideNode":
+    case "ScopeNode":
+    case "SlotNode":
+    case "PushViewNameNode":
+    case "MacroNode":
+    case "RenderOnceNode":
+      walkForRenderIt(lx, node.node, loopDepth);
+      return;
+    case "DomNode":
+    case "FragmentNode":
+      for (const child of node.childs)
+        walkForRenderIt(lx, child, loopDepth);
+      return;
+    default:
+      return;
+  }
 }
 var NO_WRAPPERS = {};
 function checkEventModifiers(lx, view) {
@@ -2981,46 +2961,48 @@ function checkEventHandlersHaveImpls(lx, Comp, referencedInputs) {
   const { input, views, Class } = Comp;
   const { prototype: proto } = Class;
   for (const viewName in views) {
-    const view = views[viewName];
-    for (const event of view.ctx.events) {
-      for (const handler of event.handlers) {
-        const { handlerVal } = handler.handlerCall;
-        const hvName = handlerVal?.constructor.name;
-        if (hvName === "InputHandlerNameVal") {
-          referencedInputs?.add(handlerVal.name);
-          if (input[handlerVal.name] === undefined) {
-            lx.warn(INPUT_HANDLER_NOT_IMPLEMENTED, {
-              name: handlerVal.name,
-              handler,
-              event
-            });
-            if (proto[handlerVal.name] !== undefined) {
-              lx.hint(INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER, {
+    lx.push({ viewName }, () => {
+      const view = views[viewName];
+      for (const event of view.ctx.events) {
+        for (const handler of event.handlers) {
+          const { handlerVal } = handler.handlerCall;
+          const hvName = handlerVal?.constructor.name;
+          if (hvName === "InputHandlerNameVal") {
+            referencedInputs?.add(handlerVal.name);
+            if (input[handlerVal.name] === undefined) {
+              lx.warn(INPUT_HANDLER_NOT_IMPLEMENTED, {
                 name: handlerVal.name,
                 handler,
                 event
               });
+              if (proto[handlerVal.name] !== undefined) {
+                lx.hint(INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER, {
+                  name: handlerVal.name,
+                  handler,
+                  event
+                });
+              }
             }
-          }
-        } else if (hvName === "RawFieldVal") {
-          referencedInputs?.add(handlerVal.name);
-          if (proto[handlerVal.name] === undefined) {
-            lx.warn(INPUT_HANDLER_METHOD_NOT_IMPLEMENTED, {
-              name: handlerVal.name,
-              handler,
-              event
-            });
-            if (input[handlerVal.name] !== undefined) {
-              lx.hint(INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD, {
+          } else if (hvName === "RawFieldVal") {
+            referencedInputs?.add(handlerVal.name);
+            if (proto[handlerVal.name] === undefined) {
+              lx.warn(INPUT_HANDLER_METHOD_NOT_IMPLEMENTED, {
                 name: handlerVal.name,
                 handler,
                 event
               });
+              if (input[handlerVal.name] !== undefined) {
+                lx.hint(INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD, {
+                  name: handlerVal.name,
+                  handler,
+                  event
+                });
+              }
             }
           }
         }
       }
-    }
+    });
   }
 }
 function checkConsistentAttrVal(lx, val, fields, proto, computed, scope, alter, referencedAlters, referencedComputed) {
@@ -3069,39 +3051,41 @@ function checkConsistentAttrs(lx, Comp, referencedAlters, referencedComputed) {
   const { prototype: proto } = Class;
   const { fields } = Class.getMetaClass();
   for (const viewName in views) {
-    const view = views[viewName];
-    for (const attr of view.ctx.attrs) {
-      const { attrs, wrapperAttrs, textChild } = attr;
-      if (attrs?.constructor.name === "DynAttrs") {
-        for (const attr2 of attrs.items) {
-          if (attr2?.constructor.name === "Attr") {
-            checkConsistentAttrVal(lx, attr2.val, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+    lx.push({ viewName }, () => {
+      const view = views[viewName];
+      for (const attr of view.ctx.attrs) {
+        const { attrs, wrapperAttrs, textChild } = attr;
+        if (attrs?.constructor.name === "DynAttrs") {
+          for (const attr2 of attrs.items) {
+            if (attr2?.constructor.name === "Attr") {
+              checkConsistentAttrVal(lx, attr2.val, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+            }
           }
         }
-      }
-      if (wrapperAttrs !== null) {
-        for (const w of wrapperAttrs) {
-          if (w.name === "each") {
-            if (w.whenVal)
-              checkConsistentAttrVal(lx, w.whenVal, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
-            if (w.enrichWithVal)
-              checkConsistentAttrVal(lx, w.enrichWithVal, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
-            if (w.loopWithVal)
-              checkConsistentAttrVal(lx, w.loopWithVal, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
-          } else if (w.name !== "scope") {
-            checkConsistentAttrVal(lx, w.val, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+        if (wrapperAttrs !== null) {
+          for (const w of wrapperAttrs) {
+            if (w.name === "each") {
+              if (w.whenVal)
+                checkConsistentAttrVal(lx, w.whenVal, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+              if (w.enrichWithVal)
+                checkConsistentAttrVal(lx, w.enrichWithVal, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+              if (w.loopWithVal)
+                checkConsistentAttrVal(lx, w.loopWithVal, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+            } else if (w.name !== "scope") {
+              checkConsistentAttrVal(lx, w.val, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+            }
           }
         }
+        if (textChild) {
+          checkConsistentAttrVal(lx, textChild, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+        }
       }
-      if (textChild) {
-        checkConsistentAttrVal(lx, textChild, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
-      }
-    }
-    for (const node of view.ctx.nodes) {
-      if (node.val) {
-        checkConsistentAttrVal(lx, node.val, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+      for (const node of view.ctx.nodes) {
+        if (node.val) {
+          checkConsistentAttrVal(lx, node.val, fields, proto, computed, scope, alter, referencedAlters, referencedComputed);
+        }
       }
-    }
+    });
   }
 }
 function checkUnreferencedAlterHandlers(lx, Comp, referencedAlters) {
@@ -3129,6 +3113,16 @@ function checkUnreferencedComputed(lx, Comp, referencedComputed) {
 class LintContext {
   constructor() {
     this.reports = [];
+    this.frame = {};
+  }
+  push(patch, fn) {
+    const prev = this.frame;
+    this.frame = { ...prev, ...patch };
+    try {
+      return fn();
+    } finally {
+      this.frame = prev;
+    }
   }
   error(id, info) {
     this.report(id, info, LEVEL_ERROR);
@@ -3140,7 +3134,7 @@ class LintContext {
     this.report(id, info, LEVEL_HINT);
   }
   report(id, info = {}, level = LEVEL_ERROR) {
-    this.reports.push({ id, info, level });
+    this.reports.push({ id, info, level, context: { ...this.frame } });
   }
 }
 
@@ -8810,36 +8804,39 @@ function renderToHTML(document2, components, macros, rootState, ParseContext2) {
 
 // tools/core/render.js
 function renderExamples(normalized, env, { name = null, title = null, view = null } = {}) {
-  const { section } = normalized;
-  if (!section) {
-    return new RenderBatch({ section: null, items: [] });
-  }
-  const items = [];
-  for (const { groupTitle, example } of section.flatten()) {
-    const componentName = example.componentName;
-    if (name !== null && componentName !== name)
-      continue;
-    if (title !== null && example.title !== title)
-      continue;
-    const viewName = view ?? example.view ?? "main";
-    let html = "";
-    let error = null;
-    try {
-      html = renderToHTML(env.document, normalized.components, normalized.macros, example.value, env.ParseContext);
-    } catch (e) {
-      error = { message: e.message, stack: e.stack };
-    }
-    items.push(new RenderedExample({
-      groupTitle,
-      title: example.title,
-      description: example.description,
-      componentName,
-      view: viewName,
-      html,
-      error
+  const sections = [];
+  for (const section of normalized.sections) {
+    const items = [];
+    for (const example of section.items) {
+      const componentName = example.componentName;
+      if (name !== null && componentName !== name)
+        continue;
+      if (title !== null && example.title !== title)
+        continue;
+      const viewName = view ?? example.view ?? "main";
+      let html = "";
+      let error = null;
+      try {
+        html = renderToHTML(env.document, normalized.components, normalized.macros, example.value, env.ParseContext);
+      } catch (e) {
+        error = { message: e.message, stack: e.stack };
+      }
+      items.push(new RenderedExample({
+        title: example.title,
+        description: example.description,
+        componentName,
+        view: viewName,
+        html,
+        error
+      }));
+    }
+    sections.push(new RenderedSection({
+      title: section.title,
+      description: section.description,
+      items
     }));
   }
-  return new RenderBatch({ section, items });
+  return new RenderBatch({ sections });
 }
 
 // tools/cli/commands/render.js
@@ -8965,7 +8962,18 @@ async function main() {
   try {
     await cmd.run(commandArgs, opts);
   } catch (e) {
-    if (e?.code === "EXAMPLES_SHAPE_MISMATCH" || e?.code?.startsWith?.("ERR_PARSE_ARGS_")) {
+    if (e?.code === "EXAMPLES_SHAPE_MISMATCH") {
+      const parts = [];
+      if (opts.module)
+        parts.push(opts.module);
+      if (e.where)
+        parts.push(`@ ${e.where}`);
+      const prefix = parts.length ? `[${parts.join(" ")}] ` : "";
+      process.stderr.write(`tutuca: ${prefix}${e.message}
+`);
+      process.exit(1);
+    }
+    if (e?.code?.startsWith?.("ERR_PARSE_ARGS_")) {
       process.stderr.write(`tutuca: ${e.message}
 `);
       process.exit(1);