Add --max-clause-depth option (#656)

stevespringett · web-flow · commit f7d2f4cfcfae · 2025-09-16T11:26:00.000-07:00
diff --git a/spec/index.html b/spec/index.html
@@ -55,6 +55,7 @@ <h1>Options</h1>
       <tr><td>`--assets-dir`</td><td>`assetsDir`</td><td>Directory in which to place assets when using `--assets=external`. Defaults to "assets".</td></tr>
       <tr><td>`--lint-spec`</td><td>`lintSpec`</td><td>Enforce some style and correctness checks.</td></tr>
       <tr><td>`--error-formatter`</td><td></td><td>The <a href="https://eslint.org/docs/user-guide/formatters/">eslint formatter</a> to be used for printing warnings and errors when using `--verbose`. Either the name of a built-in eslint formatter or the package name of an installed eslint compatible formatter.</td></tr>
+      <tr><td>`--max-clause-depth N`</td><td></td><td>Warn when clauses exceed a nesting depth of N, and cause those clauses to be numbered by incrementing their parent clause's number rather than by nesting a new number within their parent clause.</td></tr>
       <tr><td>`--strict`</td><td></td><td>Exit with an error if there are warnings. Cannot be used with `--watch`.</td></tr>
       <tr><td>`--multipage`</td><td></td><td>Emit a distinct page for each top-level clause.</td></tr>
     </table>
diff --git a/src/args.ts b/src/args.ts
@@ -67,6 +67,12 @@ export const options = [
     description:
       'The formatter for warnings and errors; either a path prefixed with "." or "./", or package name, of an installed eslint compatible formatter (default: eslint-formatter-codeframe)',
   },
+  {
+    name: 'max-clause-depth',
+    type: Number,
+    description:
+      'The maximum nesting depth for clauses; exceeding this will cause a warning. Defaults to no limit.',
+  },
   {
     name: 'multipage',
     type: Boolean,
diff --git a/src/clauseNums.ts b/src/clauseNums.ts
@@ -9,6 +9,8 @@ export default function iterator(spec: Spec): ClauseNumberIterator {
   const ids: (string | number[])[] = [];
   let inAnnex = false;
   let currentLevel = 0;
+  let hasWarnedForExcessNesting = false;
+  const MAX_LEVELS = spec.opts.maxClauseDepth ?? Infinity;
 
   return {
     next(clauseStack: Clause[], node: HTMLElement) {
@@ -22,28 +24,47 @@ export default function iterator(spec: Spec): ClauseNumberIterator {
           message: 'clauses cannot follow annexes',
         });
       }
-      if (level - currentLevel > 1) {
+      if (level - currentLevel > 1 && (level < MAX_LEVELS || currentLevel < MAX_LEVELS - 1)) {
         spec.warn({
           type: 'node',
           node,
-          ruleId: 'skipped-caluse',
+          ruleId: 'skipped-clause',
           message: 'clause is being numbered without numbering its parent clause',
         });
       }
+      if (!hasWarnedForExcessNesting && level + 1 > (spec.opts.maxClauseDepth ?? Infinity)) {
+        spec.warn({
+          type: 'node',
+          node,
+          ruleId: 'max-clause-depth',
+          message: `clause exceeds maximum nesting depth of ${spec.opts.maxClauseDepth}`,
+        });
+        hasWarnedForExcessNesting = true;
+      }
 
       const nextNum = annex ? nextAnnexNum : nextClauseNum;
 
-      if (level === currentLevel) {
-        ids[currentLevel] = nextNum(clauseStack, node);
-      } else if (level > currentLevel) {
-        ids.push(nextNum(clauseStack, node));
+      if (level >= MAX_LEVELS) {
+        if (ids.length === MAX_LEVELS) {
+          const lastLevelIndex = MAX_LEVELS - 1;
+          const lastLevel = ids[lastLevelIndex] as number[];
+          lastLevel[lastLevel.length - 1]++;
+        } else {
+          while (ids.length < MAX_LEVELS) {
+            ids.push([1]);
+          }
+        }
       } else {
-        ids.length = level + 1;
-        ids[level] = nextNum(clauseStack, node);
+        if (level === currentLevel) {
+          ids[currentLevel] = nextNum(clauseStack, node);
+        } else if (level > currentLevel) {
+          ids.push(nextNum(clauseStack, node));
+        } else {
+          ids.length = level + 1;
+          ids[level] = nextNum(clauseStack, node);
+        }
       }
-
-      currentLevel = level;
-
+      currentLevel = Math.min(level, MAX_LEVELS - 1);
       return ids.flat().join('.');
     },
   };
diff --git a/src/cli.ts b/src/cli.ts
@@ -113,6 +113,9 @@ const build = debounce(async function build() {
     if (args['mark-effects']) {
       opts.markEffects = true;
     }
+    if (args['max-clause-depth']) {
+      opts.maxClauseDepth = args['max-clause-depth'];
+    }
     if (args['no-toc'] != null) {
       opts.toc = !args['no-toc'];
     }
diff --git a/src/ecmarkup.ts b/src/ecmarkup.ts
@@ -32,6 +32,7 @@ export interface Options {
   copyright?: boolean;
   date?: Date;
   location?: string;
+  maxClauseDepth?: number;
   multipage?: boolean;
   extraBiblios?: ExportedBiblio[];
   contributors?: string;
diff --git a/test/baselines/generated-reference/max-clause-depth.html b/test/baselines/generated-reference/max-clause-depth.html
@@ -0,0 +1,46 @@
+<!doctype html>
+<head><meta name="viewport" content="width=device-width, initial-scale=1"><meta charset="utf-8">
+<link rel="icon" href="img/favicon.ico">
+</head>
+
+<body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+  <li><span>Toggle pinning of the current clause</span><code>p</code></li>
+  <li><span>Jump to the <i>n</i><sup>th</sup> pin</span><code>1-9</code></li>
+  <li><span>Jump to the 10<sup>th</sup> pin</span><code>0</code></li>
+  <li><span>Jump to the most recent link target</span><code>`</code></li>
+</ul></div><div id="menu-toggle"><svg xmlns="http://www.w3.org/2000/svg" style="width:100%; height:100%; stroke:currentColor" viewBox="0 0 120 120" width="54" height="54">
+      <title>Menu</title>
+      <path stroke-width="10" stroke-linecap="round" d="M30,60 h60  M30,30 m0,5 h60  M30,90 m0,-5 h60"></path>
+    </svg></div><div id="menu-spacer" class="menu-spacer"></div><div id="menu"><div id="menu-search"><input type="text" id="menu-search-box" placeholder="Search..."><div id="menu-search-results" class="inactive"></div></div><div id="menu-pins"><div class="menu-pane-header">Pins<button class="unpin-all">clear</button></div><ul id="menu-pins-list"></ul></div><div class="menu-pane-header">Table of Contents</div><div id="menu-toc"><ol class="toc"><li><span class="item-toggle">+</span><a href="#one" title="One"><span class="secnum">1</span> One</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#two" title="Two"><span class="secnum">1.1</span> Two</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#three" title="Three"><span class="secnum">1.2</span> Three</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#four" title="four"><span class="secnum">1.3</span> four</a></li></ol></li><li><span class="item-toggle">+</span><a href="#three-again" title="Three Again"><span class="secnum">1.4</span> Three Again</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#four-again" title="Four Again"><span class="secnum">1.5</span> Four Again</a></li></ol></li></ol></li><li><span class="item-toggle-none"></span><a href="#two-again" title="Two Again"><span class="secnum">1.6</span> Two Again</a></li></ol></li><li><span class="item-toggle-none"></span><a href="#one-again" title="One Again"><span class="secnum">2</span> One Again</a></li></ol></div></div><div id="spec-container">
+
+<emu-clause id="one">
+  <h1><span class="secnum">1</span> One</h1>
+  <emu-clause id="two">
+    <h1><span class="secnum">1.1</span> Two</h1>
+    <!-- EXPECT_WARNING { "ruleId": "max-clause-depth", "message": "clause exceeds maximum nesting depth of 2" } -->
+    <emu-clause id="three">
+      <h1><span class="secnum">1.2</span> Three</h1>
+      <emu-clause id="four">
+        <h1><span class="secnum">1.3</span> four</h1>
+      </emu-clause>
+    </emu-clause>
+    <emu-clause id="three-again">
+      <h1><span class="secnum">1.4</span> Three Again</h1>
+      <emu-clause id="four-again">
+        <h1><span class="secnum">1.5</span> Four Again</h1>
+      </emu-clause>
+    </emu-clause>
+  </emu-clause>
+  <emu-clause id="two-again">
+    <h1><span class="secnum">1.6</span> Two Again</h1>
+  </emu-clause>
+</emu-clause>
+<emu-clause id="one-again">
+  <h1><span class="secnum">2</span> One Again</h1>
+</emu-clause>
+</div></body>
diff --git a/test/baselines/sources/max-clause-depth.html b/test/baselines/sources/max-clause-depth.html
@@ -0,0 +1,35 @@
+<head>
+<link rel="icon" href="img/favicon.ico">
+</head>
+
+<pre class=metadata>
+  copyright: false
+  assets: none
+  maxClauseDepth: 2
+</pre>
+
+<emu-clause id="one">
+  <h1>One</h1>
+  <emu-clause id="two">
+    <h1>Two</h1>
+    <!-- EXPECT_WARNING { "ruleId": "max-clause-depth", "message": "clause exceeds maximum nesting depth of 2" } -->
+    <emu-clause id="three">
+      <h1>Three</h1>
+      <emu-clause id="four">
+        <h1>four</h1>
+      </emu-clause>
+    </emu-clause>
+    <emu-clause id="three-again">
+      <h1>Three Again</h1>
+      <emu-clause id="four-again">
+        <h1>Four Again</h1>
+      </emu-clause>
+    </emu-clause>
+  </emu-clause>
+  <emu-clause id="two-again">
+    <h1>Two Again</h1>
+  </emu-clause>
+</emu-clause>
+<emu-clause id="one-again">
+  <h1>One Again</h1>
+</emu-clause>
diff --git a/test/clauseIds.js b/test/clauseIds.js
@@ -7,7 +7,7 @@ describe('clause id generation', () => {
   let iter;
 
   beforeEach(() => {
-    iter = sectionNums();
+    iter = sectionNums({ opts: {} });
   });
 
   specify('generating clause ids', () => {
diff --git a/test/errors.js b/test/errors.js
@@ -1237,4 +1237,49 @@ ${M}      </pre>
       `);
     });
   });
+
+  describe('max clause depth', () => {
+    it('max depth', async () => {
+      await assertError(
+        positioned`
+          <emu-clause id="one">
+            <h1>One</h1>
+            ${M}<emu-clause id="two">
+              <h1>Two</h1>
+            </emu-clause>
+            <emu-clause id="two-again">
+              <h1>Not warned</h1>
+            </emu-clause>
+          </emu-clause>
+        `,
+        {
+          ruleId: 'max-clause-depth',
+          nodeType: 'emu-clause',
+          message: 'clause exceeds maximum nesting depth of 1',
+        },
+        {
+          maxClauseDepth: 1,
+        },
+      );
+    });
+
+    it('negative', async () => {
+      await assertErrorFree(
+        `
+          <emu-clause id="one">
+            <h1>One</h1>
+            <emu-clause id="two">
+              <h1>Two</h1>
+            </emu-clause>
+            <emu-clause id="two-again">
+              <h1>Not warned</h1>
+            </emu-clause>
+          </emu-clause>
+        `,
+        {
+          maxClauseDepth: 2,
+        },
+      );
+    });
+  });
 });

Original file line number	Diff line number	Diff line change
`@@ -113,6 +113,9 @@ const build = debounce(async function build() {`
`113`	`113`	`if (args['mark-effects']) {`
`114`	`114`	`opts.markEffects = true;`
`115`	`115`	`}`
	`116`	`+ if (args['max-clause-depth']) {`
	`117`	`+ opts.maxClauseDepth = args['max-clause-depth'];`
	`118`	`+ }`
`116`	`119`	`if (args['no-toc'] != null) {`
`117`	`120`	`opts.toc = !args['no-toc'];`
`118`	`121`	`}`