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

.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,107 @@ 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('kind-less containers honour the figure template', () => {
+    const tree = u('root', [
+      u('container', { identifier: 'fig-1' }, [
+        u('caption', [u('paragraph', [u('text', 'My figure')])]),
+      ]),
+    ]);
+    const state = new ReferenceState('main.md', {
+      frontmatter: { numbering: { all: { enabled: true }, figure: { template: 'Fig. %s' } } },
+      vfile: new VFile(),
+    });
+    enumerateTargetsTransform(tree, { state });
+    addContainerCaptionNumbersTransform(tree, new VFile(), { state });
+    const captionParagraph = (tree as any).children[0].children[0].children[0];
+    expect(toText(captionParagraph.children[0])).toBe('Fig. 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,15 @@ 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"`);
+  // containers without a kind are figures (matching kindFromNode)
+  const effectiveKind = kind || 'figure';
+  const template =
+    numbering?.[effectiveKind]?.template ?? getDefaultNumberedReferenceTemplate(effectiveKind);
   return `${template}:`;
 }
 
@@ -1053,7 +1058,11 @@ export function addContainerCaptionNumbersTransform(
   containers
     .filter((container: Container) => container.enumerator)
     .forEach((container: Container) => {
-      const target = opts.state.getTarget(container.identifier)?.node;
+      // Resolve the providing page state once: it serves both the target
+      // lookup and the numbering selection below. Single-page states do not
+      // resolve without a page argument but carry the numbering directly.
+      const stateProvider = opts.state.resolveStateProvider(container.identifier);
+      const target = (stateProvider ?? opts.state).getTarget(container.identifier)?.node;
       if (!target?.enumerator) return;
       // Only look for direct caption children
       let para = select(
@@ -1077,10 +1086,12 @@ export function addContainerCaptionNumbersTransform(
           html_id: (container as any).html_id,
           enumerator: target.enumerator,
         };
+        const numbering =
+          stateProvider?.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