feat: add recursive child schemas

Author: Peter Stenger

README.md

@@ -373,6 +373,57 @@ Schemas validate the tag's flat attribute object. The tag name is implicit from
 
 Attribute values are coerced by JSON Schema (`"2"` can satisfy an integer, valueless attributes become `true`). Attribute values containing mustache are treated as unknown runtime values, so value-dependent schema errors are waived while presence and unknown-attribute checks still run.
 
+Custom tags can also declare parent-owned child schemas. Child schemas validate a direct child tag's flat attribute object only in the context of that parent:
+
+```jsonc
+{
+  "customTags": [
+    {
+      "name": "pl-multiple-choice",
+      "schema": "elements/pl-multiple-choice/pl-multiple-choice.schema.json",
+      "children": {
+        "tags": [
+          {
+            "name": "pl-answer",
+            "schema": "elements/pl-multiple-choice/pl-answer.schema.json",
+          },
+        ],
+      },
+    },
+    { "name": "pl-answer" },
+  ],
+}
+```
+
+`children.mode` defaults to `"strict"`, so the example above allows only direct `<pl-answer>` HTML elements under `<pl-multiple-choice>`. Set `"mode": "loose"` to keep unlisted direct child elements allowed while still schema-validating listed child tags when they appear. Mustache sections are transparent for this check: `<pl-answer>` inside `{{#cond}}...{{/cond}}` still counts as a direct child of the surrounding parent element.
+
+Parent-owned child schemas do not create a global schema for the child tag. A bare `<pl-answer>` outside `<pl-multiple-choice>` is recognized by `{ "name": "pl-answer" }`, but it does not use the multiple-choice-specific child schema.
+
+If a child tag is declared only inside `children.tags` and is not listed as a top-level `customTags` entry, it is recognized only as a child-owned tag and may appear only as a direct child of the parent tags that declared it. Listing the same tag at the top level means it can also appear in any other context.
+
+`children.tags` can be nested recursively. Each level still validates only direct children, so this keeps `<pl-answer>` scoped to `<pl-multiple-choice>` while giving `<pl-answer>` its own allowed direct child tags:
+
+```jsonc
+{
+  "customTags": [
+    {
+      "name": "pl-multiple-choice",
+      "children": {
+        "tags": [
+          {
+            "name": "pl-answer",
+            "schema": "elements/pl-multiple-choice/pl-answer.schema.json",
+            "children": {
+              "tags": [{ "name": "pl-answer-feedback" }],
+            },
+          },
+        ],
+      },
+    },
+  ],
+}
+```
+
 Example schema:
 
 ```jsonc
@@ -395,13 +446,16 @@ Schemas must declare draft-06 using `http://json-schema.org/draft-06/schema#` (t
 
 Schema diagnostics are phrased in HTML/element terms rather than JSON-Schema vocabulary, so template authors aren't asked to translate `instancePath` and `additionalProperty` back into the markup they wrote. Examples:
 
-| Schema constraint                 | Diagnostic                                                                       |
-| --------------------------------- | -------------------------------------------------------------------------------- |
-| `required: ["answers-name"]`      | `<pl-multiple-choice> is missing required attribute "answers-name".`             |
-| `additionalProperties: false`     | `Unknown attribute "extra" on <pl-multiple-choice>.`                             |
-| `properties.display.enum`         | `Attribute "display" on <pl-multiple-choice> must be one of: "block", "inline".` |
-| `properties.size.type: "integer"` | `Attribute "size" on <pl-multiple-choice> must be integer.`                      |
-| `properties.weight.minimum: 0`    | `Attribute "weight" on <pl-multiple-choice> must be >= 0.`                       |
+| Schema constraint                 | Diagnostic                                                                                      |
+| --------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `required: ["answers-name"]`      | `<pl-multiple-choice> is missing required attribute "answers-name".`                            |
+| `additionalProperties: false`     | `Unknown attribute "extra" on <pl-multiple-choice>.`                                            |
+| strict unlisted child             | `<pl-multiple-choice> only allows these child elements: <pl-answer>.`                           |
+| child-only tag outside its parent | `<pl-answer> may only appear as a direct child of these parent elements: <pl-multiple-choice>.` |
+| child `additionalProperties`      | `Unknown attribute "ranking" on <pl-answer> inside <pl-multiple-choice>.`                       |
+| `properties.display.enum`         | `Attribute "display" on <pl-multiple-choice> must be one of: "block", "inline".`                |
+| `properties.size.type: "integer"` | `Attribute "size" on <pl-multiple-choice> must be integer.`                                     |
+| `properties.weight.minimum: 0`    | `Attribute "weight" on <pl-multiple-choice> must be >= 0.`                                      |
 
 Constraints without a rewriter fall through to ajv's localized text. Every diagnostic carries `ruleName: "customTagSchema"` and points at the element or attribute — see [Disabling Lint Rules](#disabling-lint-rules) to silence them per-region.
 

js/cli/check.ts

@@ -23,6 +23,7 @@ import type {
   SchemaRegistry,
 } from '../shared/customTagSchemaLoader.js';
 import type { TagValidator } from '../shared/tagValidators.js';
+import { collectCustomTagNames } from '../shared/customCodeTags.js';
 
 // ── Types ──
 
@@ -387,7 +388,7 @@ export async function run(args: string[]): Promise<number> {
   const errorOutput: string[] = [];
 
   const rules = config?.rules;
-  const customTagNames = config?.customTags?.map((t) => t.name);
+  const customTagNames = collectCustomTagNames(config?.customTags);
   const customRules = config?.customRules;
   const ruleFilterBase = configDir ?? cwd;
 

js/linter/customTagSchemaChecker.ts

@@ -3,10 +3,16 @@ import localizeEn from 'ajv-i18n/localize/en/index.js';
 import type { BalanceNode } from './htmlBalanceChecker.js';
 import type { FixableError } from './mustacheChecks.js';
 import type {
+  ChildTagSchemaConfig,
+  CompiledChildTagConfig,
   CompiledTagSchema,
   SchemaRegistry,
 } from '../shared/customTagSchemaLoader.js';
-import { getTagName, isHtmlElementType } from '../shared/nodeHelpers.js';
+import {
+  getTagName,
+  isHtmlElementType,
+  isMustacheSection,
+} from '../shared/nodeHelpers.js';
 
 interface AttributeInfo {
   attrNode: BalanceNode;
@@ -236,23 +242,32 @@ function attributeNameForError(error: ErrorObject): string | null {
   return pathSegments(error.instancePath)[0] ?? null;
 }
 
-function messageForError(error: ErrorObject, tag: string): string {
+function tagContext(tag: string, parentTag?: string): string {
+  return parentTag ? `<${tag}> inside <${parentTag}>` : `<${tag}>`;
+}
+
+function messageForError(
+  error: ErrorObject,
+  tag: string,
+  parentTag?: string,
+): string {
+  const context = tagContext(tag, parentTag);
   if (
     error.keyword === 'required' &&
     typeof error.params.missingProperty === 'string'
   ) {
-    return `<${tag}> is missing required attribute "${error.params.missingProperty}".`;
+    return `${context} is missing required attribute "${error.params.missingProperty}".`;
   }
   if (
     error.keyword === 'additionalProperties' &&
     typeof error.params.additionalProperty === 'string'
   ) {
-    return `Unknown attribute "${error.params.additionalProperty}" on <${tag}>.`;
+    return `Unknown attribute "${error.params.additionalProperty}" on ${context}.`;
   }
   const attrName = attributeNameForError(error);
   const phrase = constraintPhrase(error);
   if (attrName && phrase) {
-    return `Attribute "${attrName}" on <${tag}> must ${phrase}.`;
+    return `Attribute "${attrName}" on ${context} must ${phrase}.`;
   }
   return error.message ?? 'does not satisfy custom tag schema';
 }
@@ -284,7 +299,11 @@ function isBranchOf(child: ErrorObject, wrapper: ErrorObject): boolean {
   );
 }
 
-function mergeErrors(errors: ErrorObject[], tag: string): MergedError[] {
+function mergeErrors(
+  errors: ErrorObject[],
+  tag: string,
+  parentTag?: string,
+): MergedError[] {
   const byPath = new Map<string, ErrorObject[]>();
   for (const error of errors) {
     const list = byPath.get(error.instancePath);
@@ -318,15 +337,15 @@ function mergeErrors(errors: ErrorObject[], tag: string): MergedError[] {
       if (attrName && phrases.length > 0) {
         result.push({
           error: altWrapper,
-          message: `Attribute "${attrName}" on <${tag}> must ${phrases.join(' or ')}.`,
+          message: `Attribute "${attrName}" on ${tagContext(tag, parentTag)} must ${phrases.join(' or ')}.`,
         });
         continue;
       }
     }
     const wrappers = new Set(['if', 'allOf']);
     for (const error of group) {
       if (wrappers.has(error.keyword) && group.length > 1) continue;
-      result.push({ error, message: messageForError(error, tag) });
+      result.push({ error, message: messageForError(error, tag, parentTag) });
     }
   }
   return result;
@@ -335,6 +354,7 @@ function mergeErrors(errors: ErrorObject[], tag: string): MergedError[] {
 function validateElement(
   compiled: CompiledTagSchema,
   element: BalanceNode,
+  parentTag?: string,
 ): FixableError[] {
   const tag = getTagName(element)?.toLowerCase();
   if (!tag) return [];
@@ -346,29 +366,143 @@ function validateElement(
     (error) => !mentionsDynamicAttribute(error, built.context, compiled.schema),
   );
   localizeEn(errors.filter((error) => error.keyword !== 'errorMessage'));
-  return mergeErrors(errors, tag).map(({ error, message }) => ({
+  return mergeErrors(errors, tag, parentTag).map(({ error, message }) => ({
     node: nodeForError(error, built.context),
     message,
   }));
 }
 
+function collectDirectHtmlChildren(
+  node: BalanceNode,
+  out: BalanceNode[] = [],
+): BalanceNode[] {
+  for (const child of node.children) {
+    if (isHtmlElementType(child)) {
+      out.push(child);
+    } else if (isMustacheSection(child)) {
+      collectDirectHtmlChildren(child, out);
+    }
+  }
+  return out;
+}
+
+function strictChildMessage(parentTag: string, allowedTags: string[]): string {
+  const tags = allowedTags.map((tag) => `<${tag}>`).join(', ');
+  return `<${parentTag}> only allows these child elements: ${tags}.`;
+}
+
+function orphanChildMessage(tag: string, parentTags: string[]): string {
+  const tags = parentTags.map((parentTag) => `<${parentTag}>`).join(', ');
+  return `<${tag}> may only appear as a direct child of these parent elements: ${tags}.`;
+}
+
+function childrenForElement(
+  tag: string,
+  scopedConfig: CompiledChildTagConfig | undefined,
+  globalChildren: Map<string, ChildTagSchemaConfig>,
+): ChildTagSchemaConfig | undefined {
+  return scopedConfig?.children ?? globalChildren.get(tag);
+}
+
 export function checkCustomTagSchemas(
   rootNode: BalanceNode,
   registry: SchemaRegistry | undefined,
 ): FixableError[] {
-  if (!registry || registry.schemas.size === 0) return [];
+  if (
+    !registry ||
+    (registry.schemas.size === 0 && registry.children.size === 0)
+  ) {
+    return [];
+  }
   const errors: FixableError[] = [];
   const schemas = registry.schemas;
+  const children = registry.children;
+  const topLevelTags = registry.topLevelTags;
+  const childParents = registry.childParents;
+
+  function shouldSkipOrphanForStrictParent(
+    tag: string,
+    parentChildren: ChildTagSchemaConfig | undefined,
+  ): boolean {
+    return parentChildren?.mode === 'strict' && !parentChildren.tags.has(tag);
+  }
 
-  function visit(node: BalanceNode): void {
+  function visit(
+    node: BalanceNode,
+    directParentTag: string | undefined,
+    scopedConfig: CompiledChildTagConfig | undefined,
+    parentChildren: ChildTagSchemaConfig | undefined,
+  ): void {
     if (isHtmlElementType(node)) {
       const tag = getTagName(node)?.toLowerCase();
+      if (tag && !topLevelTags.has(tag)) {
+        const allowedParents = childParents.get(tag);
+        if (
+          allowedParents &&
+          !allowedParents.has(directParentTag ?? '') &&
+          !shouldSkipOrphanForStrictParent(tag, parentChildren)
+        ) {
+          errors.push({
+            node,
+            message: orphanChildMessage(tag, Array.from(allowedParents)),
+          });
+        }
+      }
       const compiled = tag ? schemas.get(tag) : undefined;
       if (compiled) errors.push(...validateElement(compiled, node));
+      const childConfig = tag
+        ? childrenForElement(tag, scopedConfig, children)
+        : undefined;
+      if (tag && childConfig) {
+        const allowedTags = Array.from(childConfig.tags.keys());
+        for (const child of collectDirectHtmlChildren(node)) {
+          const childTag = getTagName(child)?.toLowerCase();
+          if (!childTag) continue;
+          const childEntry = childConfig.tags.get(childTag);
+          if (!childEntry) {
+            if (childConfig.mode === 'strict') {
+              errors.push({
+                node: child,
+                message: strictChildMessage(tag, allowedTags),
+              });
+            }
+            continue;
+          }
+          if (childEntry.schema) {
+            errors.push(...validateElement(childEntry.schema, child, tag));
+          }
+        }
+      }
+      for (const child of node.children) {
+        if (isHtmlElementType(child) || isMustacheSection(child)) {
+          const childTag = isHtmlElementType(child)
+            ? getTagName(child)?.toLowerCase()
+            : undefined;
+          const childEntry =
+            childTag && childConfig
+              ? childConfig.tags.get(childTag)
+              : undefined;
+          visit(child, tag, childEntry, childConfig);
+        } else {
+          visit(child, directParentTag, scopedConfig, parentChildren);
+        }
+      }
+      return;
+    }
+    for (const child of node.children) {
+      if (isHtmlElementType(child)) {
+        const childTag = getTagName(child)?.toLowerCase();
+        const childEntry =
+          childTag && parentChildren
+            ? parentChildren.tags.get(childTag)
+            : undefined;
+        visit(child, directParentTag, childEntry, parentChildren);
+      } else {
+        visit(child, directParentTag, scopedConfig, parentChildren);
+      }
     }
-    for (const child of node.children) visit(child);
   }
 
-  visit(rootNode);
+  visit(rootNode, undefined, undefined, undefined);
   return errors;
 }