Code numbering: honour scope in book mode and template in captions

Two gaps in `code` (enumerable code-block) numbering relative to the
other enumerable kinds:

- `code` was missing from AUTO_PREFIX_KINDS, so `numbering.code.scope`
  and the book-mode chapter prefix never applied (listings enumerated
  1, 2, ... instead of 1.1, 1.2, ... 2.1)
- getCaptionLabel ignored the configured numbering templates, so a
  `template: "Listing %s"` rendered references as "Listing 1" but the
  caption header as "Program 1"; captions now resolve the template the
  same way cross-references do (defaults unchanged, since fillNumbering
  always supplies the built-in template)

Fixes #47

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mmcky

.changeset/code-numbering.md

@@ -0,0 +1,5 @@
+---
+"myst-transforms": patch
+---
+
+Code (enumerable code-block) numbering now matches the other enumerable kinds: `numbering.code.scope` applies the chapter/section prefix in book mode (e.g. `Listing 1.1`), and the caption noun follows the configured `numbering[kind].template` (e.g. `Listing %s`) instead of always using the built-in default, so captions and cross-references agree.

packages/myst-transforms/src/enumerate.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from 'vitest';
 import {
   addChildrenFromTargetNode,
+  addContainerCaptionNumbersTransform,
   MultiPageReferenceResolver,
   ReferenceState,
   enumerateTargetsTransform,
@@ -1213,3 +1214,92 @@ describe('initializeTargetCounts', () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------
+// #47: code (enumerable code-block) numbering — scope + caption noun.
+// ---------------------------------------------------------------------
+
+describe('code numbering (#47)', () => {
+  const numbering = {
+    book: { enabled: true },
+    all: { enabled: true },
+    title: { enabled: true },
+    heading_1: { enabled: true },
+    code: { scope: 'chapter', template: 'Listing %s' },
+  };
+  test('code containers pick up the chapter prefix in book mode', () => {
+    const tree = u('root', [
+      u('container', { kind: 'code', identifier: 'list-1' }),
+      u('container', { kind: 'code', identifier: 'list-2' }),
+    ]);
+    const ch1 = new ReferenceState('ch1.md', {
+      frontmatter: { numbering },
+      vfile: new VFile(),
+    });
+    enumerateTargetsTransform(tree, { state: ch1 });
+    expect(ch1.getTarget('list-1')?.node.enumerator).toBe('1.1');
+    expect(ch1.getTarget('list-2')?.node.enumerator).toBe('1.2');
+    // next chapter: counter resets, prefix advances
+    const tree2 = u('root', [u('container', { kind: 'code', identifier: 'list-3' })]);
+    const ch2 = new ReferenceState('ch2.md', {
+      frontmatter: { numbering },
+      previousCounts: ch1.targetCounts,
+      vfile: new VFile(),
+    });
+    enumerateTargetsTransform(tree2, { state: ch2 });
+    expect(ch2.getTarget('list-3')?.node.enumerator).toBe('2.1');
+  });
+  test('code containers honour section scope', () => {
+    const tree = u('root', [
+      u('heading', { identifier: 's1', depth: 2 }),
+      u('container', { kind: 'code', identifier: 'list-1' }),
+      u('heading', { identifier: 's2', depth: 2 }),
+      u('container', { kind: 'code', identifier: 'list-2' }),
+    ]);
+    const state = new ReferenceState('ch1.md', {
+      frontmatter: {
+        numbering: {
+          ...numbering,
+          heading_2: { enabled: true },
+          code: { scope: 'section', template: 'Listing %s' },
+        },
+      },
+      vfile: new VFile(),
+    });
+    enumerateTargetsTransform(tree, { state });
+    expect(state.getTarget('list-1')?.node.enumerator).toBe('1.1.1');
+    expect(state.getTarget('list-2')?.node.enumerator).toBe('1.2.1');
+  });
+  test('caption noun follows the configured template', () => {
+    const tree = u('root', [
+      u('container', { kind: 'code', identifier: 'list-1' }, [
+        u('caption', [u('paragraph', [u('text', 'My listing')])]),
+      ]),
+    ]);
+    const state = new ReferenceState('ch1.md', {
+      frontmatter: { numbering },
+      vfile: new VFile(),
+    });
+    enumerateTargetsTransform(tree, { state });
+    addContainerCaptionNumbersTransform(tree, new VFile(), { state });
+    const captionParagraph = (tree as any).children[0].children[0].children[0];
+    expect(captionParagraph.children[0].type).toBe('captionNumber');
+    expect(toText(captionParagraph.children[0])).toBe('Listing 1.1:');
+  });
+  test('caption noun falls back to the default without a template', () => {
+    const tree = u('root', [
+      u('container', { kind: 'code', identifier: 'list-1' }, [
+        u('caption', [u('paragraph', [u('text', 'My listing')])]),
+      ]),
+    ]);
+    const state = new ReferenceState('main.md', {
+      frontmatter: { numbering: { all: { enabled: true } } },
+      vfile: new VFile(),
+    });
+    enumerateTargetsTransform(tree, { state });
+    addContainerCaptionNumbersTransform(tree, new VFile(), { state });
+    const captionParagraph = (tree as any).children[0].children[0].children[0];
+    // the default template uses a non-breaking space ('Program\u00a0%s')
+    expect(toText(captionParagraph.children[0])).toBe('Program\u00a01:');
+  });
+});

packages/myst-transforms/src/enumerate.ts

@@ -53,6 +53,7 @@ const AUTO_PREFIX_KINDS = new Set<string>([
   'subequation',
   'table',
   'exercise',
+  'code',
 ]);
 
 /**
@@ -1029,11 +1030,13 @@ export const enumerateTargetsPlugin: Plugin<[StateOptions], GenericParent, Gener
     enumerateTargetsTransform(tree, opts);
   };
 
-function getCaptionLabel(kind?: Container['kind'], subcontainer?: boolean) {
+function getCaptionLabel(kind?: Container['kind'], subcontainer?: boolean, numbering?: Numbering) {
   if (subcontainer && (kind === 'equation' || kind === 'subequation')) return `(%s)`;
   if (subcontainer) return `({subEnumerator})`;
   if (!kind) return 'Figure %s:';
-  const template = getDefaultNumberedReferenceTemplate(kind);
+  // The caption noun follows the configured template, matching what
+  // cross-references render (e.g. `numbering.code.template: "Listing %s"`)
+  const template = numbering?.[kind]?.template ?? getDefaultNumberedReferenceTemplate(kind);
   return `${template}:`;
 }
 
@@ -1077,10 +1080,15 @@ export function addContainerCaptionNumbersTransform(
           html_id: (container as any).html_id,
           enumerator: target.enumerator,
         };
+        // Page-level resolvers need the identifier's page; a single-page
+        // ReferenceState carries the numbering directly
+        const numbering =
+          opts.state.resolveStateProvider(container.identifier)?.numbering ??
+          (opts.state as { numbering?: Numbering }).numbering;
         fillReferenceEnumerators(
           file,
           captionNumber,
-          getCaptionLabel(container.kind, container.subcontainer),
+          getCaptionLabel(container.kind, container.subcontainer, numbering),
           target,
         );
         // The caption number is in the paragraph, it needs a link to the figure container