@amritk/lint 0.5.3 → 0.6.0

package/AI.md

@@ -30,7 +30,7 @@ import { lintDocument } from '@amritk/lint'
 import { createAsyncApiRuleset } from '@amritk/lint/rules/asyncapi'
 import { resolveRefs } from '@amritk/resolve-refs' // any resolver will do
 
-// Recommended rules only: 48 of 56. For all 56, pass the `all` modifier:
+// Recommended rules only: 54 of 62. For all 62, pass the `all` modifier:
 //   createAsyncApiRuleset({ extends: [['asyncapi', 'all']] })
 const ruleset = createAsyncApiRuleset()
 
@@ -91,7 +91,7 @@ createAsyncApiRuleset({
 7. **`createRuleset` is memoized** per `(definition object, basePath,
    restrictTo)`. Mutating a definition you already passed in will not rebuild the
    ruleset — pass a fresh object instead.
-8. **Most AsyncAPI rules are gated per major** (11 of the 56 apply to both).
+8. **Most AsyncAPI rules are gated per major** (11 of the 62 apply to both).
    The 3.x-only rules are named with an `asyncapi-3-` prefix
    (`asyncapi-3-operation-description`) and the 2.x ones are not, because 3.0
    moved operations to the top level and tags under `info`. Re-severitying
@@ -133,6 +133,6 @@ createAsyncApiRuleset({
 |---|---|
 | `@amritk/lint` | core engine, `lintDocument`/`fixDocument`, built-in functions |
 | `@amritk/lint/rules/openapi` | OpenAPI 2.0/3.0/3.1/3.2 preset — 66 rules, plus `oasFixers` |
-| `@amritk/lint/rules/asyncapi` | AsyncAPI 2.0–2.6 / 3.0 preset — 56 rules, no fixers |
+| `@amritk/lint/rules/asyncapi` | AsyncAPI 2.0–2.6 / 3.0 preset — 62 rules, no fixers |
 
 Install: `bun add @amritk/lint`.

package/dist/rules/asyncapi/asyncapi.js

@@ -369,6 +369,7 @@ const V3_MESSAGE_TRAITS = [
   "$.components.messageTraits[*]"
 ];
 const V3_ALL_MESSAGES = [...V3_MESSAGES, ...V3_MESSAGE_TRAITS];
+const V3_PAYLOADS = V3_ALL_MESSAGES.map((given) => `${given}.payload`);
 const v3Rules = {
   "asyncapi-3-channel-no-empty-parameter": {
     description: "Channel address must not have an empty parameter substitution pattern.",
@@ -424,6 +425,16 @@ const v3Rules = {
     severity: "error",
     then: { function: "asyncApiHeadersObject", functionOptions: { multiFormat: true } }
   },
+  "asyncapi-3-message-examples": {
+    description: "Message examples must be valid against the payload and headers schemas.",
+    formats: ["aas3"],
+    // Messages only, for the same reason as the 2.x twin: the pass folds traits
+    // in and reports against whichever array the merge took, so matching each
+    // trait location as well printed the identical finding twice.
+    given: V3_MESSAGES,
+    severity: "error",
+    then: { function: "asyncApiMessageExamples", functionOptions: { multiFormat: true } }
+  },
   "asyncapi-3-operation-description": {
     description: "Operation must have a description.",
     formats: ["aas3"],
@@ -438,10 +449,33 @@ const v3Rules = {
     severity: "error",
     then: { function: "asyncApiSecurity", functionOptions: { objectType: "Operation" } }
   },
+  "asyncapi-3-payload": {
+    description: "Payloads must be valid against the AsyncAPI Schema object.",
+    formats: ["aas3"],
+    // Given the message rather than the payload, exactly as the 2.x twin is, so
+    // traits are folded in before the payload is read.
+    given: V3_ALL_MESSAGES,
+    severity: "error",
+    then: { function: "asyncApiPayload", functionOptions: { multiFormat: true } }
+  },
+  "asyncapi-3-payload-default": {
+    description: "Payload default must be valid against its schema.",
+    formats: ["aas3"],
+    given: V3_PAYLOADS,
+    severity: "error",
+    then: { function: "asyncApiSchemaValidation", functionOptions: { type: "default", multiFormat: true } }
+  },
+  "asyncapi-3-payload-examples": {
+    description: "Payload examples must be valid against their schema.",
+    formats: ["aas3"],
+    given: V3_PAYLOADS,
+    severity: "error",
+    then: { function: "asyncApiSchemaValidation", functionOptions: { type: "examples", multiFormat: true } }
+  },
   "asyncapi-3-payload-unsupported-schemaFormat": {
     description: "Message payload validation is only supported with an unspecified schemaFormat.",
     formats: ["aas3"],
-    given: V3_ALL_MESSAGES.map((given) => `${given}.payload`),
+    given: V3_PAYLOADS,
     severity: "info",
     resolved: false,
     then: {
@@ -450,6 +484,26 @@ const v3Rules = {
       functionOptions: { match: "^application/vnd\\.aai\\.asyncapi([+;])" }
     }
   },
+  "asyncapi-3-schema-default": {
+    description: "Schema default must be valid against its schema.",
+    formats: ["aas3"],
+    // No parameter locations here: a 3.0 Channel Parameter Object has no
+    // `schema` at all — it carries `enum`, `default` and `examples` as plain
+    // strings — so `components.schemas` is the only place a reusable Schema
+    // Object is written. Each entry is a Multi Format Schema Object or a bare
+    // Schema Object, which is why this unwraps rather than reading `default`
+    // straight off the node.
+    given: "$.components.schemas[*]",
+    severity: "error",
+    then: { function: "asyncApiSchemaValidation", functionOptions: { type: "default", multiFormat: true } }
+  },
+  "asyncapi-3-schema-examples": {
+    description: "Schema examples must be valid against their schema.",
+    formats: ["aas3"],
+    given: "$.components.schemas[*]",
+    severity: "error",
+    then: { function: "asyncApiSchemaValidation", functionOptions: { type: "examples", multiFormat: true } }
+  },
   "asyncapi-3-server-security": {
     // 3.0 keeps `security` on the Server Object, in the same
     // Reference-or-inline-scheme shape `asyncapi-3-operation-security` checks.

package/dist/rules/asyncapi/functions/asyncapi-headers-object.js

@@ -1,4 +1,5 @@
 import { isObject } from "./helpers.js";
+import { splitMultiFormatSchema } from "./multi-format-schema.js";
 import { isAsyncApiSchemaFormat } from "./schema-format.js";
 const MESSAGE = 'Headers schema type must be "object"';
 const asyncApiHeadersObject = (headers, options, context) => {
@@ -8,15 +9,17 @@ const asyncApiHeadersObject = (headers, options, context) => {
     return [];
   if (typeof headers["$ref"] === "string")
     return [];
-  if (options?.multiFormat === true && Object.hasOwn(headers, "schema")) {
-    if (!isAsyncApiSchemaFormat(headers["schemaFormat"]))
-      return [];
-    const inner = headers["schema"];
-    if (!isObject(inner))
-      return [{ message: MESSAGE, path: [...context.path, "schema"] }];
-    if (typeof inner["$ref"] === "string" || inner["type"] === "object")
-      return [];
-    return [{ message: MESSAGE, path: [...context.path, "schema"] }];
+  if (options?.multiFormat === true) {
+    const { schemaFormat, schema: inner, path } = splitMultiFormatSchema(headers);
+    if (path.length > 0) {
+      if (!isAsyncApiSchemaFormat(schemaFormat))
+        return [];
+      if (!isObject(inner))
+        return [{ message: MESSAGE, path: [...context.path, ...path] }];
+      if (typeof inner["$ref"] === "string" || inner["type"] === "object")
+        return [];
+      return [{ message: MESSAGE, path: [...context.path, ...path] }];
+    }
   }
   return headers["type"] === "object" ? [] : [{ message: MESSAGE, path: [...context.path] }];
 };

package/dist/rules/asyncapi/functions/asyncapi-message-examples.d.ts

@@ -1,8 +1,17 @@
 import type { RulesetFunction } from '../../../core/types.js';
+/** Options for {@link asyncApiMessageExamples}. */
+export type IAsyncApiMessageExamplesOptions = {
+    /**
+     * Whether `payload` and `headers` may each be a Multi Format Schema Object
+     * (`{ schemaFormat, schema }`). That shape is 3.0 only, and it is also where
+     * that major states the schema language — 2.x states it once, on the message.
+     */
+    multiFormat?: boolean;
+};
 /**
  * Checks every entry of a Message Object's `examples` against the message's own
  * `payload` and `headers` schemas. Traits are folded in first, so an example is
  * judged against the message a tool would actually assemble rather than against
  * the half of it written inline.
  */
-export declare const asyncApiMessageExamples: RulesetFunction;
+export declare const asyncApiMessageExamples: RulesetFunction<unknown, IAsyncApiMessageExamplesOptions | undefined>;

package/dist/rules/asyncapi/functions/asyncapi-message-examples.js

@@ -1,5 +1,6 @@
 import { schema as schemaFunction } from "../../../functions/index.js";
 import { isObject, mergeTraits } from "./helpers.js";
+import { splitMultiFormatSchema } from "./multi-format-schema.js";
 import { isAsyncApiSchemaFormat } from "./schema-format.js";
 const examplesOrigin = (message) => {
   const traits = message["traits"];
@@ -12,7 +13,8 @@ const examplesOrigin = (message) => {
   }
   return ["examples"];
 };
-const asyncApiMessageExamples = (input, _options, context) => {
+const PARTS = ["payload", "headers"];
+const asyncApiMessageExamples = (input, options, context) => {
   if (!isObject(input))
     return [];
   const message = mergeTraits(input);
@@ -20,17 +22,23 @@ const asyncApiMessageExamples = (input, _options, context) => {
   if (!Array.isArray(examples))
     return [];
   const origin = examplesOrigin(input);
-  const payloadIsSchema = isAsyncApiSchemaFormat(message["schemaFormat"]);
+  const schemaOf = (part) => {
+    if (options?.multiFormat !== true) {
+      return part === "headers" || isAsyncApiSchemaFormat(message["schemaFormat"]) ? message[part] : void 0;
+    }
+    const { schemaFormat, schema } = splitMultiFormatSchema(message[part]);
+    return isAsyncApiSchemaFormat(schemaFormat) ? schema : void 0;
+  };
+  const schemas = { payload: schemaOf("payload"), headers: schemaOf("headers") };
   const results = [];
   examples.forEach((example, index) => {
     if (!isObject(example))
       return;
-    for (const part of ["payload", "headers"]) {
-      if (example[part] === void 0)
-        continue;
-      if (part === "payload" && !payloadIsSchema)
+    for (const part of PARTS) {
+      const partSchema = schemas[part];
+      if (example[part] === void 0 || partSchema === void 0)
         continue;
-      const findings = schemaFunction(example[part], { schema: isObject(message[part]) ? message[part] : {}, allErrors: true, skipUnusableSchema: true }, { ...context, path: [...context.path, ...origin, index, part] });
+      const findings = schemaFunction(example[part], { schema: isObject(partSchema) ? partSchema : {}, allErrors: true, skipUnusableSchema: true }, { ...context, path: [...context.path, ...origin, index, part] });
       if (findings)
         results.push(...findings);
     }

package/dist/rules/asyncapi/functions/asyncapi-payload.d.ts

@@ -11,4 +11,14 @@ import type { RulesetFunction } from '../../../core/types.js';
  * payload came to be judged as JSON Schema and reported at error severity.
  * `asyncapi-payload-unsupported-schemaFormat` reports those separately.
  */
-export declare const asyncApiPayload: RulesetFunction;
+/** Options for {@link asyncApiPayload}. */
+export type IAsyncApiPayloadOptions = {
+    /**
+     * Whether the payload may be a Multi Format Schema Object (`{ schemaFormat,
+     * schema }`). That shape is 3.0 only: the format that used to sit on the
+     * message now sits on the payload, so the gate reads a different place — and
+     * the schema to judge lives one level further down.
+     */
+    multiFormat?: boolean;
+};
+export declare const asyncApiPayload: RulesetFunction<unknown, IAsyncApiPayloadOptions | undefined>;

package/dist/rules/asyncapi/functions/asyncapi-payload.js

@@ -1,6 +1,7 @@
 import { schema as schemaFunction } from "../../../functions/index.js";
 import { asyncApiSchemaVersion, loadAsyncApiSchema } from "../schemas/index.js";
 import { isObject, mergeTraits } from "./helpers.js";
+import { splitMultiFormatSchema } from "./multi-format-schema.js";
 import { isAsyncApiSchemaFormat } from "./schema-format.js";
 const payloadSchemaId = (version) => `http://asyncapi.com/definitions/${version}.0/schema.json`;
 const payloadSchemas = /* @__PURE__ */ new Map();
@@ -13,19 +14,20 @@ const payloadSchema = (version) => {
   }
   return wrapper;
 };
-const asyncApiPayload = (message, _options, context) => {
+const asyncApiPayload = (message, options, context) => {
   if (!isObject(message))
     return [];
   const merged = mergeTraits(message);
-  if (!isAsyncApiSchemaFormat(merged["schemaFormat"]))
+  const written = merged["payload"];
+  if (written === void 0)
     return [];
-  const payload = merged["payload"];
-  if (payload === void 0)
+  const payload = options?.multiFormat === true ? splitMultiFormatSchema(written) : { schemaFormat: merged["schemaFormat"], schema: written, path: [] };
+  if (!isAsyncApiSchemaFormat(payload.schemaFormat))
     return [];
   const version = asyncApiSchemaVersion(isObject(context.document.data) ? context.document.data["asyncapi"] : void 0);
   if (version === void 0)
     return [];
-  return schemaFunction(payload, { schema: payloadSchema(version), allErrors: true }, { ...context, path: [...context.path, "payload"] }) ?? [];
+  return schemaFunction(payload.schema, { schema: payloadSchema(version), allErrors: true }, { ...context, path: [...context.path, "payload", ...payload.path] }) ?? [];
 };
 export {
   asyncApiPayload

package/dist/rules/asyncapi/functions/asyncapi-schema-validation.d.ts

@@ -1,11 +1,22 @@
 import type { RulesetFunction } from '../../../core/types.js';
-/** Options for {@link asyncApiSchemaValidation}: which sibling of the schema to check. */
+/** Options for {@link asyncApiSchemaValidation}: which sibling of the schema to check, and how the schema is wrapped. */
 export type IAsyncApiSchemaValidationOptions = {
     type: 'default' | 'examples';
+    /**
+     * Whether the matched node may be a Multi Format Schema Object (`{
+     * schemaFormat, schema }`) rather than a bare Schema Object. That shape is 3.0
+     * only, where a payload — and a `components.schemas` entry — can be written in
+     * Avro or Protobuf. A `default` under one of those is not JSON Schema data and
+     * cannot be judged, so it is left to
+     * `asyncapi-3-payload-unsupported-schemaFormat` to mention the format at all.
+     */
+    multiFormat?: boolean;
 };
 /**
  * Validates a Schema Object's own `default` or `examples` against that same
- * schema. The rule targets the schema (via a `^` parent selector), so the input
- * here is the schema and the values under test sit inside it.
+ * schema. In 2.x the rule targets the schema through a `^` parent selector, so
+ * the input is the schema and the values under test sit inside it; in 3.0 the
+ * rule targets the payload (or `components.schemas` entry) directly, because the
+ * wrapper has to be unwrapped before either can be found.
  */
 export declare const asyncApiSchemaValidation: RulesetFunction<unknown, IAsyncApiSchemaValidationOptions>;

package/dist/rules/asyncapi/functions/asyncapi-schema-validation.js

@@ -1,12 +1,20 @@
 import { schema as schemaFunction } from "../../../functions/index.js";
 import { isObject } from "./helpers.js";
+import { splitMultiFormatSchema } from "./multi-format-schema.js";
+import { isAsyncApiSchemaFormat } from "./schema-format.js";
 const asyncApiSchemaValidation = (input, options, context) => {
-  if (!isObject(input) || options?.type === void 0)
+  if (options?.type === void 0)
     return [];
-  const targets = options.type === "default" ? [{ path: ["default"], value: input["default"] }] : Array.isArray(input["examples"]) ? input["examples"].map((value, index) => ({ path: ["examples", index], value })) : [];
+  const source = options.multiFormat === true ? splitMultiFormatSchema(input) : { schemaFormat: void 0, schema: input, path: [] };
+  if (!isAsyncApiSchemaFormat(source.schemaFormat))
+    return [];
+  const schema = source.schema;
+  if (!isObject(schema))
+    return [];
+  const targets = options.type === "default" ? Object.hasOwn(schema, "default") ? [{ path: ["default"], value: schema["default"] }] : [] : Array.isArray(schema["examples"]) ? schema["examples"].map((value, index) => ({ path: ["examples", index], value })) : [];
   const results = [];
   for (const target of targets) {
-    const findings = schemaFunction(target.value, { schema: input, allErrors: true, skipUnusableSchema: true }, { ...context, path: [...context.path, ...target.path] });
+    const findings = schemaFunction(target.value, { schema, allErrors: true, skipUnusableSchema: true }, { ...context, path: [...context.path, ...source.path, ...target.path] });
     if (findings)
       results.push(...findings);
   }

package/dist/rules/asyncapi/functions/index.d.ts

@@ -5,11 +5,12 @@ export { asyncApiChannelParameters } from './asyncapi-channel-parameters.js';
 export { asyncApiChannelServers } from './asyncapi-channel-servers.js';
 export { asyncApiDocumentSchema } from './asyncapi-document-schema.js';
 export { asyncApiHeadersObject, type IAsyncApiHeadersOptions } from './asyncapi-headers-object.js';
-export { asyncApiMessageExamples } from './asyncapi-message-examples.js';
+export { asyncApiMessageExamples, type IAsyncApiMessageExamplesOptions } from './asyncapi-message-examples.js';
 export { asyncApiMessageIdUnique } from './asyncapi-message-id-unique.js';
 export { asyncApiOperationIdUnique } from './asyncapi-operation-id-unique.js';
-export { asyncApiPayload } from './asyncapi-payload.js';
+export { asyncApiPayload, type IAsyncApiPayloadOptions } from './asyncapi-payload.js';
 export { asyncApiSchemaValidation, type IAsyncApiSchemaValidationOptions } from './asyncapi-schema-validation.js';
 export { asyncApiSecurity, type IAsyncApiSecurityOptions } from './asyncapi-security.js';
+export { type MultiFormatSchema, splitMultiFormatSchema } from './multi-format-schema.js';
 /** The AsyncAPI-specific custom functions, keyed by name for ruleset `then` references. */
 export declare const aasFunctions: FunctionRegistry;

package/dist/rules/asyncapi/functions/index.js

@@ -22,6 +22,7 @@ import { asyncApiOperationIdUnique as asyncApiOperationIdUnique2 } from "./async
 import { asyncApiPayload as asyncApiPayload2 } from "./asyncapi-payload.js";
 import { asyncApiSchemaValidation as asyncApiSchemaValidation2 } from "./asyncapi-schema-validation.js";
 import { asyncApiSecurity as asyncApiSecurity2 } from "./asyncapi-security.js";
+import { splitMultiFormatSchema } from "./multi-format-schema.js";
 const aasFunctions = {
   aasServerVariables,
   aasTagsUnique,
@@ -49,5 +50,6 @@ export {
   asyncApiOperationIdUnique2 as asyncApiOperationIdUnique,
   asyncApiPayload2 as asyncApiPayload,
   asyncApiSchemaValidation2 as asyncApiSchemaValidation,
-  asyncApiSecurity2 as asyncApiSecurity
+  asyncApiSecurity2 as asyncApiSecurity,
+  splitMultiFormatSchema
 };

package/dist/rules/asyncapi/functions/multi-format-schema.d.ts

@@ -0,0 +1,25 @@
+import type { JsonPath } from '../../../core/types.js';
+/** An AsyncAPI 3.0 payload or headers node, split into the schema it holds and the language that schema is written in. */
+export type MultiFormatSchema = {
+    /** The wrapper's `schemaFormat`, or `undefined` when the node is a bare Schema Object. */
+    schemaFormat: unknown;
+    /** The Schema Object itself: the wrapper's `schema`, or the whole node when it is bare. */
+    schema: unknown;
+    /** How to get from the matched node down to `schema` — `['schema']` when wrapped, empty when bare. */
+    path: JsonPath;
+};
+/**
+ * Splits an AsyncAPI 3.0 Multi Format Schema Object (`{ schemaFormat, schema }`)
+ * into its parts, passing a bare Schema Object through untouched.
+ *
+ * 3.0 moved `schemaFormat` off the message and onto the payload/headers wrapper,
+ * so this is where "is this even an AsyncAPI Schema Object?" gets answered for
+ * that major — the question 2.x answers once, on the message.
+ *
+ * An own `schema` key is what makes it a wrapper, which is exactly how the
+ * bundled 3.0 meta-schema decides (`anySchema.json`: `if: { required: ['schema']
+ * }`). `schemaFormat` is optional on the wrapper and defaults to the AsyncAPI
+ * dialect, so demanding it too would leave a plain `{ schema: … }` judged as a
+ * schema whose only keyword is one no dialect defines.
+ */
+export declare const splitMultiFormatSchema: (node: unknown) => MultiFormatSchema;

package/dist/rules/asyncapi/functions/multi-format-schema.js

@@ -0,0 +1,5 @@
+import { isObject } from "./helpers.js";
+const splitMultiFormatSchema = (node) => isObject(node) && Object.hasOwn(node, "schema") ? { schemaFormat: node["schemaFormat"], schema: node["schema"], path: ["schema"] } : { schemaFormat: void 0, schema: node, path: [] };
+export {
+  splitMultiFormatSchema
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/lint",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "A fast, format-agnostic JSON/YAML style-guide linter with JSON Schema and custom rules.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -69,7 +69,7 @@
     }
   },
   "dependencies": {
-    "@amritk/runtime-validators": "^0.13.1",
+    "@amritk/runtime-validators": "^0.14.0",
     "@amritk/yaml": "^0.7.2",
     "jsonc-parser": "^3.3.1"
   },