ata-validator 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 0.16.0 - 2026-05-23
+
+### Added
+
+- `defineSchema` helper and the exported `JSONSchema` type. Wrap a plain schema object in `defineSchema(...)` to author it inline in TypeScript with keyword autocomplete and value checking, no `as const` needed. It is an identity function at runtime, so the returned object drops straight into `Validator`, `toStandaloneModule`, and the rest of the API. Requires TypeScript >= 5.0 for the `const` type parameter.
+- OpenAPI `nullable` keyword. `{ type: 'string', nullable: true }` accepts `null` alongside the declared type, matching OpenAPI 3.0 schemas.
+
+### Fixed
+
+- `coerceTypes` with `type: 'array'` wraps a scalar into a single-element array instead of leaving it unchanged.
+- Codegen resolves a `$defs` entry that carries a fragment `$id` and is reached through a pointer `$ref`.
+- Preprocessing (defaults, coercion, `removeAdditional`) guards against `null` and non-object data instead of throwing.
+
+## 0.15.1 - 2026-05-23
+
+### Fixed
+
+- Coercion, defaults, and `removeAdditional` now follow a cross-schema `$ref` to the referenced shape. A whole-schema reference like `{ $ref: 'shared#' }` (used for shared route schemas) or a property reference like `{ id: { $ref: 'shared#/properties/id' } }` is preprocessed instead of skipped.
+- The compile cache now keys on referenced schema content, not just the `$id`. Two validators that share a root schema string and an `$id` pointing at different schemas no longer reuse the wrong compiled function.
+
 ## 0.15.0 - 2026-05-18
 
 ### Added

package/README.md

@@ -158,6 +158,28 @@ if (result.valid) {
 
 The same pattern works with Zod-from-JSON-Schema, Valibot, or a hand-written `type User = {...}` alongside a JSON Schema literal. `Validator<T>` makes no library-specific assumption.
 
+#### Authoring a schema inline: `defineSchema`
+
+If you would rather write a plain JSON Schema object than reach for a schema library, wrap it in `defineSchema`. It returns the schema untouched at runtime, but in TypeScript it gives you keyword autocomplete and an error when a value has the wrong shape, with no `as const` needed.
+
+```ts
+import { defineSchema, Validator } from 'ata-validator'
+
+const userSchema = defineSchema({
+  type: 'object',
+  properties: {
+    id: { type: 'integer', minimum: 1 },
+    role: { type: 'string', enum: ['admin', 'user'] },
+  },
+  required: ['id'],
+})
+
+// type: 123 or required: 'id' would be a compile error here.
+const v = new Validator(userSchema)
+```
+
+The exported `JSONSchema` type is also available directly if you want to annotate a schema yourself. Custom and vendor keywords are allowed, so exotic schemas still type-check. Requires TypeScript >= 5.0.
+
 ### Cross-Schema `$ref`
 
 ```javascript

package/index.d.ts

@@ -75,6 +75,95 @@ export function renderJSON(errors: RichValidationError[], opts?: JSONRenderOptio
 /** A user-supplied format checker. Receives the candidate value, returns true if valid. */
 export type FormatChecker = (value: string) => boolean;
 
+/** The seven primitive `type` values defined by JSON Schema. */
+export type JSONSchemaTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null';
+
+/**
+ * A hand-written type for authoring JSON Schema (draft 2020-12) objects inline
+ * in TypeScript. Known keywords are typed, so you get autocomplete and an error
+ * when a value has the wrong shape (e.g. `type: 123` or `required: 'id'`).
+ * Unknown keywords are permitted, so custom/vendor keywords do not error.
+ *
+ * Pair it with {@link defineSchema} for inline authoring without `as const`.
+ */
+export interface JSONSchema {
+  $id?: string;
+  $schema?: string;
+  $ref?: string;
+  $defs?: Record<string, JSONSchema>;
+  definitions?: Record<string, JSONSchema>;
+  $comment?: string;
+
+  type?: JSONSchemaTypeName | JSONSchemaTypeName[];
+  enum?: ReadonlyArray<unknown>;
+  const?: unknown;
+
+  title?: string;
+  description?: string;
+  default?: unknown;
+  examples?: ReadonlyArray<unknown>;
+  deprecated?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+
+  // object
+  properties?: Record<string, JSONSchema>;
+  required?: ReadonlyArray<string>;
+  additionalProperties?: boolean | JSONSchema;
+  patternProperties?: Record<string, JSONSchema>;
+  propertyNames?: JSONSchema;
+  minProperties?: number;
+  maxProperties?: number;
+  dependentRequired?: Record<string, ReadonlyArray<string>>;
+  dependentSchemas?: Record<string, JSONSchema>;
+
+  // array
+  items?: JSONSchema | ReadonlyArray<JSONSchema>;
+  prefixItems?: ReadonlyArray<JSONSchema>;
+  additionalItems?: boolean | JSONSchema;
+  contains?: JSONSchema;
+  minContains?: number;
+  maxContains?: number;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+
+  // string
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+
+  // number
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+
+  // composition
+  allOf?: ReadonlyArray<JSONSchema>;
+  anyOf?: ReadonlyArray<JSONSchema>;
+  oneOf?: ReadonlyArray<JSONSchema>;
+  not?: JSONSchema;
+  if?: JSONSchema;
+  then?: JSONSchema;
+  else?: JSONSchema;
+
+  /** OpenAPI compatibility: ata honors `nullable` as a JSON Schema extension. */
+  nullable?: boolean;
+
+  /** Custom and vendor keywords are allowed without error. */
+  [keyword: string]: unknown;
+}
+
 export type ValidationResult<T = unknown> =
   | { valid: true;  data: T;       errors: ValidationError[] }
   | { valid: false; data?: never;  errors: ValidationError[] };
@@ -253,3 +342,25 @@ export const SIMDJSON_PADDING: number;
  * build-time integrations (Vite plugin, custom build steps).
  */
 export function toTypeScript(schema: object, options?: { name?: string }): string;
+
+/**
+ * Authoring helper for writing a JSON Schema inline in TypeScript. Returns the
+ * schema unchanged at runtime; its purpose is to apply the {@link JSONSchema}
+ * type so you get keyword autocomplete and an error on malformed values, while
+ * the `const` type parameter preserves the literal shape (no `as const` needed).
+ *
+ * ```ts
+ * import { defineSchema, Validator } from 'ata-validator';
+ *
+ * const user = defineSchema({
+ *   type: 'object',
+ *   properties: { id: { type: 'integer', minimum: 1 } },
+ *   required: ['id'],
+ * });
+ *
+ * const v = new Validator(user);
+ * ```
+ *
+ * Requires TypeScript >= 5.0 for the `const` type parameter.
+ */
+export declare function defineSchema<const S extends JSONSchema>(schema: S): S;

package/index.js

@@ -8,7 +8,7 @@ const {
   compileToJSCodegenWithErrors,
   compileToJSCombined,
 } = require("./lib/js-compiler");
-const { normalizeDraft7 } = require("./lib/draft7");
+const { normalizeDraft7, normalizeNullable } = require("./lib/draft7");
 const { classify } = require("./lib/shape-classifier");
 const { buildTier0Plan, tier0Validate } = require("./lib/tier0");
 
@@ -242,6 +242,8 @@ function buildPreprocessCodegen(schema, options) {
       } else if (t === 'boolean') {
         lines.push(`if(d[${k}]==='true'||d[${k}]==='1')d[${k}]=true`);
         lines.push(`if(d[${k}]==='false'||d[${k}]==='0')d[${k}]=false`);
+      } else if (t === 'array' && options.coerceTypes === 'array') {
+        lines.push(`if(${k} in d&&d[${k}]!==undefined&&!Array.isArray(d[${k}]))d[${k}]=[d[${k}]]`);
       }
     }
   }
@@ -256,6 +258,9 @@ function buildPreprocessCodegen(schema, options) {
   }
 
   if (lines.length === 0) return null;
+  // Data may legitimately be null or a non-object (e.g. a `['object','null']`
+  // schema), so the per-property mutations must not run on it.
+  lines.unshift(`if(d===null||typeof d!=='object')return`);
   try {
     return new Function('d', lines.join('\n'));
   } catch {
@@ -350,6 +355,7 @@ function buildSchemaMap(schemas) {
   if (Array.isArray(schemas)) {
     for (const s of schemas) {
       normalizeDraft7(s)
+      normalizeNullable(s)
       const id = s.$id
       if (!id) throw new Error('Schema in schemas option must have $id')
       map.set(id, s)
@@ -357,12 +363,26 @@ function buildSchemaMap(schemas) {
   } else {
     for (const [key, s] of Object.entries(schemas)) {
       normalizeDraft7(s)
+      normalizeNullable(s)
       map.set(s.$id || key, s)
     }
   }
   return map
 }
 
+// Compile-cache key for a root schema plus its external schemas. Must include
+// the external schema CONTENT, not just their $ids: two validators can share a
+// root schema string and the same $id while pointing that $id at different
+// schemas (separate app instances, test suites, multi-tenant). Keying on $id
+// alone reuses the wrong compiled validator and silently mis-validates.
+function compileCacheKey(schemaStr, schemaMap) {
+  if (!schemaMap || schemaMap.size === 0) return schemaStr
+  const parts = []
+  for (const [id, s] of schemaMap) parts.push(id + '=' + JSON.stringify(s))
+  parts.sort()
+  return schemaStr + '\0' + parts.join('\0')
+}
+
 // Resolve a relative URI ref against a base URI
 function resolveRelativeRef(ref, baseId) {
   if (!baseId || ref.includes('://') || ref.startsWith('#')) return ref
@@ -371,6 +391,66 @@ function resolveRelativeRef(ref, baseId) {
   return baseId.substring(0, lastSlash + 1) + ref
 }
 
+// Resolve a cross-schema $ref to its target schema for preprocessing purposes.
+// Handles whole-schema refs (`shared#`), relative-id matching, and JSON pointer
+// fragments (`shared#/properties/id`). Returns null for local-only refs or when
+// the target cannot be found. Used only to read `type`/`properties` for
+// coercion/defaults/removeAdditional, never for validation.
+function resolveRefForPreprocess(ref, schemaMap) {
+  if (!schemaMap || schemaMap.size === 0 || typeof ref !== 'string') return null
+  const hashIdx = ref.indexOf('#')
+  const baseId = hashIdx >= 0 ? ref.slice(0, hashIdx) : ref
+  const fragment = hashIdx >= 0 ? ref.slice(hashIdx + 1) : ''
+  if (!baseId) return null
+  let base = null
+  if (schemaMap.has(baseId)) base = schemaMap.get(baseId)
+  else if (!ref.includes('://')) {
+    for (const [id, s] of schemaMap) {
+      if (id.endsWith('/' + baseId)) { base = s; break }
+    }
+  }
+  if (!base) return null
+  if (!fragment) return base
+  let target = base
+  for (const part of fragment.split('/')) {
+    if (part === '') continue
+    if (target == null || typeof target !== 'object') return null
+    target = target[part.replace(/~1/g, '/').replace(/~0/g, '~')]
+  }
+  return target == null ? null : target
+}
+
+// Preprocessing (coerce/defaults/removeAdditional) reads `schema.properties` and
+// each property's `type`. When the data shape lives behind a cross-schema $ref
+// (a whole-schema ref like Fastify's `params: { $ref: 'shared#' }`, or a
+// property ref like `{ id: { $ref: 'shared#/properties/id' } }`), follow the
+// ref so the preprocessor can see the referenced shape. Returns the schema with
+// such refs resolved, cloning only when a substitution is made.
+function resolveSchemaForPreprocess(schema, schemaMap) {
+  if (!schema || typeof schema !== 'object' || !schemaMap || schemaMap.size === 0) return schema
+  let s = schema
+  // Whole-schema ref (only when it has no own properties, to avoid dropping
+  // sibling keywords on schemas that mix $ref with properties).
+  if (s.$ref && !s.properties) {
+    const t = resolveRefForPreprocess(s.$ref, schemaMap)
+    if (t && typeof t === 'object') s = t
+  }
+  if (!s.properties) return s
+  // Property-level refs: substitute the resolved target so coercion sees `type`.
+  let cloned = null
+  for (const key of Object.keys(s.properties)) {
+    const p = s.properties[key]
+    if (p && typeof p === 'object' && p.$ref && !p.type) {
+      const t = resolveRefForPreprocess(p.$ref, schemaMap)
+      if (t && typeof t === 'object') {
+        if (!cloned) { cloned = Object.assign({}, s); cloned.properties = Object.assign({}, s.properties) }
+        cloned.properties[key] = t
+      }
+    }
+  }
+  return cloned || s
+}
+
 class Validator {
   constructor(schema, opts) {
     const options = opts || {};
@@ -386,6 +466,8 @@ class Validator {
 
     // Draft 7 normalization — convert keywords to 2020-12 equivalents in-place
     normalizeDraft7(schemaObj);
+    // OpenAPI nullable -> type union with 'null'
+    normalizeNullable(schemaObj);
 
     this._schemaStr = null; // lazy: computed on first use
     this._schemaObj = schemaObj;
@@ -531,9 +613,7 @@ class Validator {
 
     // Check cache first -- reuse compiled functions for same schema
     const sm = this._schemaMap.size > 0 ? this._schemaMap : null;
-    const mapKey = this._schemaMap.size > 0
-      ? this._schemaStr + '\0' + [...this._schemaMap.keys()].sort().join('\0')
-      : this._schemaStr;
+    const mapKey = compileCacheKey(this._schemaStr, this._schemaMap);
     // Custom formats are JS functions: bypass the compile cache since they can
     // differ between validators that share the same schema string.
     const cached = this._userFormats ? null : _compileCache.get(mapKey);
@@ -559,13 +639,17 @@ class Validator {
     }
     this._jsFn = jsFn;
 
-    // Data mutators -- try codegen first (12x faster), fallback to closure arrays
-    let preprocess = buildPreprocessCodegen(schemaObj, options);
+    // Data mutators -- try codegen first (12x faster), fallback to closure arrays.
+    // Follow cross-refs so coercion/defaults/removeAdditional see the referenced
+    // shape (e.g. Fastify `params: { $ref: 'shared#' }` or property refs like
+    // `{ id: { $ref: 'shared#/properties/id' } }`).
+    const preprocessSchema = resolveSchemaForPreprocess(schemaObj, this._schemaMap);
+    let preprocess = buildPreprocessCodegen(preprocessSchema, options);
     if (!preprocess) {
-      const applyDefaults = buildDefaultsApplier(schemaObj);
-      const applyCoerce = options.coerceTypes ? buildCoercer(schemaObj) : null;
+      const applyDefaults = buildDefaultsApplier(preprocessSchema);
+      const applyCoerce = options.coerceTypes ? buildCoercer(preprocessSchema) : null;
       const applyRemove = options.removeAdditional
-        ? buildRemover(schemaObj)
+        ? buildRemover(preprocessSchema)
         : null;
       const mutators = [applyRemove, applyCoerce, applyDefaults].filter(Boolean);
       preprocess =
@@ -999,6 +1083,7 @@ class Validator {
     }
     // Apply Draft 7 normalization if needed
     normalizeDraft7(schema)
+    normalizeNullable(schema)
     this._schemaMap.set(schema.$id, schema)
   }
 
@@ -1007,9 +1092,7 @@ class Validator {
     if (typeof process !== 'undefined' && process.env && process.env.ATA_FORCE_NAPI) return;
     if (!this._schemaStr) this._schemaStr = JSON.stringify(this._schemaObj);
     const sm = this._schemaMap.size > 0 ? this._schemaMap : null;
-    const mapKey = this._schemaMap.size > 0
-      ? this._schemaStr + '\0' + [...this._schemaMap.keys()].sort().join('\0')
-      : this._schemaStr;
+    const mapKey = compileCacheKey(this._schemaStr, this._schemaMap);
     // Custom formats are JS functions: skip the shared cache so different
     // validators with the same schema string but different formats don't collide.
     const cached = this._userFormats ? null : _compileCache.get(mapKey);
@@ -1569,6 +1652,14 @@ function attachSuggestions (errors, data) {
   return errors;
 }
 
+// Authoring helper: identity at runtime. Its only job is to attach the
+// JSONSchema type (see index.d.ts) to an inline schema object so TypeScript
+// gives autocomplete and value checking while authoring. Returns the schema
+// untouched so it can be passed straight to Validator, toStandaloneModule, etc.
+function defineSchema (schema) {
+  return schema;
+}
+
 module.exports = {
   Validator,
   compile,
@@ -1578,6 +1669,7 @@ module.exports = {
   SIMDJSON_PADDING,
   parseJSON,
   toTypeScript,
+  defineSchema,
   renderPretty,
   renderCompact,
   renderJSON,

package/index.mjs

@@ -1,3 +1,3 @@
 import mod from './index.js';
-export const { Validator, validate, version, createPaddedBuffer, SIMDJSON_PADDING, renderPretty, renderCompact, renderJSON } = mod;
+export const { Validator, validate, version, createPaddedBuffer, SIMDJSON_PADDING, defineSchema, renderPretty, renderCompact, renderJSON } = mod;
 export default mod;

package/lib/draft7.js

@@ -79,4 +79,51 @@ function _normalize(schema) {
   }
 }
 
-module.exports = { isDraft7, normalizeDraft7 }
+// OpenAPI `nullable: true` is not JSON Schema. Convert it to a union with
+// 'null' (`{ type: 'X', nullable: true }` -> `{ type: ['X', 'null'] }`), the
+// same shape AJV produces under its `nullable` option. Recurses only through
+// schema-bearing keywords so it never touches data values (default, const, etc.).
+function normalizeNullable(schema) {
+  if (typeof schema !== 'object' || schema === null) return schema
+  _normalizeNullable(schema)
+  return schema
+}
+
+function _normalizeNullable(schema) {
+  if (typeof schema !== 'object' || schema === null) return
+
+  if (schema.nullable === true && schema.type !== undefined) {
+    if (Array.isArray(schema.type)) {
+      if (!schema.type.includes('null')) schema.type = schema.type.concat('null')
+    } else {
+      schema.type = [schema.type, 'null']
+    }
+  }
+  if ('nullable' in schema) delete schema.nullable
+
+  const objSubs = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']
+  for (const key of objSubs) {
+    if (schema[key] && typeof schema[key] === 'object') {
+      for (const v of Object.values(schema[key])) {
+        if (typeof v === 'object' && v !== null) _normalizeNullable(v)
+      }
+    }
+  }
+  const arrSubs = ['allOf', 'anyOf', 'oneOf', 'prefixItems']
+  for (const key of arrSubs) {
+    if (Array.isArray(schema[key])) {
+      for (const s of schema[key]) {
+        if (typeof s === 'object' && s !== null) _normalizeNullable(s)
+      }
+    }
+  }
+  const singleSubs = ['items', 'contains', 'not', 'if', 'then', 'else',
+                       'additionalProperties', 'propertyNames', 'unevaluatedItems', 'unevaluatedProperties']
+  for (const key of singleSubs) {
+    if (typeof schema[key] === 'object' && schema[key] !== null) {
+      _normalizeNullable(schema[key])
+    }
+  }
+}
+
+module.exports = { isDraft7, normalizeDraft7, normalizeNullable }

package/lib/js-compiler.js

@@ -690,6 +690,23 @@ function canResolveDynamicRefs(target, callingSchema, schemaMap) {
 
 // Recursively check if a schema can be safely compiled to JS codegen.
 // Returns false if any sub-schema contains features codegen gets wrong.
+// Does the schema (recursively) contain an anchor-style `$ref` equal to anchorId
+// (e.g. `$ref: '#address'`)? Used to keep codegen away from anchor refs it can't
+// resolve in the combined/error paths.
+function schemaHasAnchorRef(node, anchorId) {
+  if (!node || typeof node !== 'object') return false
+  if (Array.isArray(node)) {
+    for (const x of node) if (schemaHasAnchorRef(x, anchorId)) return true
+    return false
+  }
+  if (node.$ref === anchorId) return true
+  for (const k in node) {
+    if (k === '$ref') continue
+    if (schemaHasAnchorRef(node[k], anchorId)) return true
+  }
+  return false
+}
+
 function codegenSafe(schema, schemaMap) {
   if (typeof schema === 'boolean') return true
   if (typeof schema !== 'object' || schema === null) return true
@@ -799,7 +816,15 @@ function codegenSafe(schema, schemaMap) {
       if (/[~/"']/.test(name)) return false // special chars in def name
       if (typeof def === 'boolean') return false
       if (typeof def === 'object' && def !== null) {
-        if (def.$id) return false // $id in $defs creates new resolution scope — bail
+        // A non-fragment $id (e.g. 'sub.json', 'http://...') opens a new base URI
+        // scope — bail. A fragment-only $id ('#name') is a draft-07 anchor; it is
+        // safe to codegen when reached by JSON pointer (#/definitions/name), but the
+        // combined/error codegen paths do not resolve anchor refs (`$ref: '#name'`)
+        // to it, so bail if the schema anchor-references this def.
+        if (def.$id) {
+          if (!def.$id.startsWith('#')) return false
+          if (schemaHasAnchorRef(schema, def.$id)) return false
+        }
         if (def.$ref) return false // nested ref chain — bail
         if (!codegenSafe(def, schemaMap)) return false
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile to per-schema ESM modules with zero validator dependency. Generic Validator<T> for TypeBox/Zod/Valibot composition. Optional runtime API. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
@@ -42,7 +42,7 @@
     "rebuild": "cmake-js rebuild --target ata",
     "prebuild": "pkg-prebuilds-copy --baseDir build/Release --source ata.node --name=ata --strip --napi_version=10",
     "prebuild-all": "npm run prebuild -- --arch x64 && npm run prebuild -- --arch arm64",
-    "test": "node test.js && node tests/test_no_native.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_typed_validator_runner.js && node tests/test_error_codes_lock.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node benchmark/bench_aot_size.mjs",
+    "test": "node test.js && node tests/test_no_native.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_nullable.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node benchmark/bench_aot_size.mjs",
     "bench:size": "node benchmark/bench_aot_size.mjs",
     "test:suite": "node tests/run_suite.js",
     "test:compat": "node tests/test_compat.js",

package/scripts/check-doc-coverage.js

@@ -10,7 +10,7 @@ const doc = fs.readFileSync(path.join(__dirname, '..', 'docs', 'error-codes.md')
 const missing = [];
 const placeholder = [];
 for (const code of all()) {
-  const headingRe = new RegExp(`^### ${code} `, 'm');
+  const headingRe = new RegExp(`^### ${code}\\b`, 'm');
   if (!headingRe.test(doc)) {
     missing.push(code);
     continue;