@amritk/mjst 0.25.1 → 0.26.0

package/README.md

@@ -437,7 +437,7 @@ Under `--table` only the content between `<!-- config-table-start -->
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="4">Also emit a coerceX alongside each validateX. It moves scalars toward the type the schema declares and then runs the very same validateX over the result, so a config value written the YAML way reads the same whether it came from a config file or an extension. The input is never modified and nothing is substituted: a value that cannot be coerced into a valid one reaches the validator untouched, so the error names what the caller actually wrote, with the keyword and params that rejected it. The table is Ajv's coerceTypes minus the cells where Ajv guesses — no whitespace-to-zero, no hex or Infinity strings, and nothing coerced to or from null — so every value this coerces, Ajv coerces to the same value, and the rest become errors rather than silent repairs. At a union it coerces only when exactly one of the offered types can take the value, and leaves a value that is already one of them alone, so the answer does not depend on the order the union was written in. Requires validators.</td>
+<td colspan="4">Also emit a coerceX alongside each validateX. It moves scalars toward the type the schema declares and then runs the very same validateX over the result, so a config value written the YAML way reads the same whether it came from a config file or an extension. The input is never modified and nothing is substituted: a value that cannot be coerced into a valid one reaches the validator untouched, so the error names what the caller actually wrote, with the keyword and params that rejected it. The table is Ajv's coerceTypes minus the cells where Ajv guesses — no whitespace-to-zero, no hex or Infinity strings, and nothing coerced to or from null, deliberately, since null usually means not set — so every scalar this coerces, Ajv coerces to the same value, and the rest become errors rather than silent repairs. Coercion reaches through $ref, allOf, if/then/else and unions. At a union a value that already matches a branch as written is left alone; otherwise each branch coerces it its own way, and the result is taken only when every branch that then accepts it agrees on it. So the answer does not depend on the order the union was written in, and a const false branch keeps false where Ajv turns it into the string false through an earlier string branch. A valid document comes back as the very same object, and against Ajv cloning its input first coerceX runs 5–36× faster on valid input and 1.4–2.1× faster on input that needs coercing. Requires validators.</td>
 </tr>
 <tr>
 <td>🔧 <code>repair</code></td>

package/dist/cli-config.d.ts

@@ -96,12 +96,26 @@ export type CliConfig = {
      *
      * The table is Ajv's `coerceTypes` minus the cells where Ajv guesses — no
      * whitespace-to-zero, no `0x`/`Infinity` strings, and nothing coerced to or
-     * from `null`. Every value this coerces, Ajv coerces to the same value, so
-     * moving off Ajv never changes a value; it turns some of Ajv's silent repairs
-     * into errors instead. At a union it coerces only when exactly one of the
-     * offered types can take the value, and leaves a value that is already one of
-     * them alone — so the answer does not depend on the order the union is
-     * written in, which under Ajv it does.
+     * from `null`. `null` is left alone deliberately: it usually means "not set",
+     * and reading it as `""`, `0` or `false` erases that. Every scalar this
+     * coerces, Ajv coerces to the same value; the cells Ajv guesses at become
+     * errors instead of silent repairs.
+     *
+     * Coercion reaches through `$ref`, `allOf`, `if`/`then`/`else` and unions. At
+     * a union (`anyOf`, `oneOf`, a `type` array) a value that already matches a
+     * branch as written is left alone. Otherwise each branch coerces it its own
+     * way, and the result is taken only when every branch that then accepts it
+     * agrees on it; two different readings leave the value as written for the
+     * validator to report. So the answer never depends on the order the union was
+     * written in, which under Ajv it does — Ajv coerces into the first branch that
+     * will take the value, and turns `false` into `"false"` through a string
+     * branch listed before a `const: false` one.
+     *
+     * A document that is already valid is answered by `isX` alone where that is a
+     * standalone guard, and handed back as the very same object. Against Ajv
+     * cloning its input first — which it must to leave the caller's document
+     * alone — `coerceX` runs 5–36× faster on valid input and 1.4–2.1× faster on
+     * input that needs coercing (`bench:validators:coerce`).
      *
      * Requires `validators`. `validateX` and `isX` are unchanged either way.
      */

package/dist/describe-resolve-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Turns a `ResolveError` message from `@amritk/resolve-refs` into the text the
+ * CLI shows.
+ *
+ * The resolver records a document that failed to load as `String(err)`, so the
+ * message opens with the error's class name — `Error: ENOENT: …`, `Error:
+ * Failed to parse …` — which tells the reader nothing and pushes the part that
+ * does to the right. Only that leading prefix is dropped; the library keeps its
+ * wording, since other callers may match on it. A confinement refusal also gets
+ * the `--allowed-roots` hint (see {@link withAllowedRootsHint}).
+ */
+export declare const describeResolveError: (message: string) => string;

package/dist/describe-resolve-error.js

@@ -0,0 +1,5 @@
+import { withAllowedRootsHint } from "./allowed-roots-hint.js";
+const describeResolveError = (message) => withAllowedRootsHint(message.startsWith("Error: ") ? message.slice("Error: ".length) : message);
+export {
+  describeResolveError
+};

package/dist/lint/resolver.d.ts

@@ -27,5 +27,10 @@ export type ResolverOptions = {
  * refs is resolved from disk **only when its source file reads back exactly as
  * the linted input** — so a piped document (`--stdin-filepath`) never resolves
  * against a different on-disk file — with remote fetching gated by `options`.
+ *
+ * A multi-document root (a YAML `---` stream) is resolved one document at a
+ * time, each as a root of its own — `#/…` points into the document the `$ref`
+ * is written in, and so does a `$ref` naming the root file — and the results
+ * are put back into the array the linter reads the stream as.
  */
 export declare const createLintResolver: (options?: ResolverOptions) => LintResolver;

package/dist/lint/resolver.js

@@ -3,19 +3,20 @@ import { dirname, resolve as resolvePath } from "node:path";
 import { createDocument, resolveSourceOriginFromMap } from "@amritk/lint";
 import { DiagnosticSeverity } from "@amritk/lint/types";
 import { resolveRefs, resolveRefsFromFile } from "@amritk/resolve-refs";
-import { parse as parseYaml } from "@amritk/yaml";
-import { withAllowedRootsHint } from "../allowed-roots-hint.js";
+import { describeResolveError } from "../describe-resolve-error.js";
 import { hasExternalRefs } from "../has-external-refs.js";
+import { parseYamlStrict } from "../parse-yaml-strict.js";
 const isRemote = (location) => /^https?:\/\//i.test(location);
+const parseReferencedYaml = (content, location) => parseYamlStrict(content, location, { what: "a $ref target", singleLine: true, uniqueKeys: false });
 const parseDoc = (content, location) => {
   if (/\.ya?ml$/i.test(location))
-    return parseYaml(content);
+    return parseReferencedYaml(content, location);
   if (/\.json$/i.test(location))
     return JSON.parse(content);
   try {
     return JSON.parse(content);
   } catch {
-    return parseYaml(content);
+    return parseReferencedYaml(content, location);
   }
 };
 const readsBackAs = (absolute, input) => {
@@ -52,7 +53,7 @@ const toFindings = (errors, root) => errors.map((error) => {
   const location = error.path.length > 0 ? root.getLocationForJsonPath(error.path, true) : void 0;
   const finding = {
     code: "unresolved-ref",
-    message: withAllowedRootsHint(error.message),
+    message: describeResolveError(error.message),
     path: error.path,
     severity: DiagnosticSeverity.Error,
     range: location?.range ?? DOCUMENT_START
@@ -61,6 +62,18 @@ const toFindings = (errors, root) => errors.map((error) => {
     finding.source = root.source;
   return finding;
 });
+const isMultiDocument = (document) => Array.isArray(document.data) && document.data.length > 1 && document.getLocationForJsonPath([]) === void 0;
+const rebaseOntoStream = ({ errors, origins, location }, index, rootLocation, into) => {
+  if (origins) {
+    for (const [node, origin] of origins) {
+      if (into.has(node))
+        continue;
+      const inThisDocument = origin.location === location;
+      into.set(node, inThisDocument ? { location: rootLocation, pointer: [index, ...origin.pointer] } : origin);
+    }
+  }
+  return errors.map((error) => ({ message: error.message, path: [index, ...error.path] }));
+};
 const createLintResolver = (options = {}) => {
   const fromFileOptions = {
     remote: options.remote ?? false,
@@ -70,26 +83,41 @@ const createLintResolver = (options = {}) => {
     trackOrigins: true
   };
   const extraRoots = (options.allowedRoots ?? []).map((root) => resolvePath(root));
+  const resolveDocument = async (data, absolute) => {
+    if (absolute !== void 0 && hasExternalRefs(data)) {
+      const result = await resolveRefsFromFile(absolute, {
+        ...fromFileOptions,
+        // The linter has parsed this very text already; hand that value over
+        // rather than have the root read and parsed a second time (the most
+        // expensive step of linting a large spec). It also keeps a root with a
+        // syntax error of its own (already a `parser` finding) out of the
+        // strict parse that referenced files get.
+        rootDocument: data,
+        ...extraRoots.length > 0 ? { allowedRoots: [dirname(absolute), ...extraRoots] } : {}
+      });
+      return { ...result, location: absolute };
+    }
+    return { ...resolveRefs(data, { trackOrigins: true }), location: "" };
+  };
   return async (document, { input }) => {
     const { source } = document;
-    if (source && hasExternalRefs(document.data)) {
-      const absolute = resolvePath(source);
-      if (readsBackAs(absolute, input)) {
-        const { resolved: resolved2, origins: origins2, errors: errors2 } = await resolveRefsFromFile(absolute, {
-          ...fromFileOptions,
-          ...extraRoots.length > 0 ? { allowedRoots: [dirname(absolute), ...extraRoots] } : {}
-        });
-        return {
-          resolved: resolved2,
-          sources: buildSourceSet(document, resolved2, origins2, absolute),
-          ...errors2.length > 0 ? { diagnostics: toFindings(errors2, document) } : {}
-        };
-      }
+    const absolute = source && hasExternalRefs(document.data) && readsBackAs(resolvePath(source), input) ? resolvePath(source) : void 0;
+    if (!isMultiDocument(document)) {
+      const { resolved: resolved2, origins: origins2, errors: errors2, location } = await resolveDocument(document.data, absolute);
+      return {
+        resolved: resolved2,
+        sources: buildSourceSet(document, resolved2, origins2, location),
+        ...errors2.length > 0 ? { diagnostics: toFindings(errors2, document) } : {}
+      };
     }
-    const { resolved, origins, errors } = resolveRefs(document.data, { trackOrigins: true });
+    const rootLocation = absolute ?? "";
+    const results = await Promise.all(document.data.map((data) => resolveDocument(data, absolute)));
+    const origins = /* @__PURE__ */ new Map();
+    const errors = results.flatMap((result, index) => rebaseOntoStream(result, index, rootLocation, origins));
+    const resolved = results.map((result) => result.resolved);
     return {
       resolved,
-      sources: buildSourceSet(document, resolved, origins, ""),
+      sources: buildSourceSet(document, resolved, origins, rootLocation),
       ...errors.length > 0 ? { diagnostics: toFindings(errors, document) } : {}
     };
   };

package/dist/load-asyncapi-document.js

@@ -3,24 +3,19 @@ import { resolve } from "node:path";
 import { assignKey } from "@amritk/helpers/assign-key";
 import { readKey } from "@amritk/helpers/read-key";
 import { resolveRefsFromFile } from "@amritk/resolve-refs";
-import { parseDocument } from "@amritk/yaml";
 import { hasExternalRefs } from "./has-external-refs.js";
+import { parseYamlStrict } from "./parse-yaml-strict.js";
 import { buildResolveOptions, formatResolveErrors } from "./resolve-policy.js";
-const parseDocumentText = (content, location) => {
+const parseDocumentText = (content, location, referenced = false) => {
   const text = content.charCodeAt(0) === 65279 ? content.slice(1) : content;
   if (/\.json$/i.test(location))
     return JSON.parse(text);
-  const doc = parseDocument(text);
-  if (doc.errors.length > 0) {
-    const details = doc.errors.slice(0, 5).map((error) => `  - ${error.message}`).join("\n");
-    throw new Error(`Failed to parse ${location} as YAML:
-${details}`);
-  }
-  if (doc.warnings.some((warning) => warning.code === "MULTIPLE_DOCUMENTS")) {
-    throw new Error(`${location} contains multiple YAML documents; an AsyncAPI document must be a single-document file.`);
-  }
-  return doc.toJS();
+  return parseYamlStrict(text, location, {
+    what: referenced ? "a $ref target" : "an AsyncAPI document",
+    singleLine: referenced
+  });
 };
+const parseReferencedText = (content, location) => parseDocumentText(content, location, true);
 const nodeAt = (root, pointer) => {
   let node = root;
   for (const segment of pointer) {
@@ -77,7 +72,10 @@ const loadAsyncApiDocument = async (config, documentPath) => {
     return document;
   const { resolved, errors, origins } = await resolveRefsFromFile(documentPath, {
     ...buildResolveOptions(config, documentPath),
-    parse: parseDocumentText,
+    // Parsed just above; without this the resolver would read and parse the
+    // whole document a second time.
+    rootDocument: document,
+    parse: parseReferencedText,
     trackOrigins: true
   });
   if (errors.length > 0)

package/dist/load-schema.js

@@ -10,7 +10,10 @@ const loadSchema = async (config, schemaPath) => {
     const data = JSON.parse(await readFile(schemaPath, "utf-8"));
     if (!hasExternalRefs(data))
       return data;
-    const { resolved, errors } = await resolveRefsFromFile(schemaPath, buildResolveOptions(config, schemaPath));
+    const { resolved, errors } = await resolveRefsFromFile(schemaPath, {
+      ...buildResolveOptions(config, schemaPath),
+      rootDocument: data
+    });
     if (errors.length > 0)
       throw new Error(formatResolveErrors(schemaPath, errors));
     return resolved;

package/dist/parse-yaml-strict.d.ts

@@ -0,0 +1,28 @@
+import { type ParseOptions } from '@amritk/yaml';
+export type ParseYamlStrictOptions = ParseOptions & {
+    /**
+     * What the file is required to be, for the multi-document message — `an
+     * AsyncAPI document`, `a $ref target` — so the reader learns why a perfectly
+     * valid YAML stream was refused.
+     */
+    what: string;
+    /**
+     * Join the listed problems into one line (`; `) instead of one `  - ` bullet
+     * per line. For reports that print one line per finding, where a line break
+     * in the message would read as a new, unlabelled finding.
+     */
+    singleLine?: boolean;
+};
+/**
+ * Parses `text` as a single YAML document and returns its value, throwing
+ * instead of handing back anything the parser had to guess at.
+ *
+ * `@amritk/yaml` collects problems rather than throwing, and `parse` returns
+ * the salvage of a malformed document as if it were fine — an unclosed `[`
+ * swallows the lines after it into a bogus key, and the caller builds on data
+ * the file does not contain. It also reads only the first document of a `---`
+ * stream, flagging the rest with a `MULTIPLE_DOCUMENTS` warning, so a file
+ * whose second half silently vanished would be reported as a success. Both are
+ * turned into an error here, naming `location` and each problem's `line:col`.
+ */
+export declare const parseYamlStrict: (text: string, location: string, options: ParseYamlStrictOptions) => unknown;

package/dist/parse-yaml-strict.js

@@ -0,0 +1,31 @@
+import { lineCounter, parseDocument } from "@amritk/yaml";
+const MAX_LISTED_PROBLEMS = 5;
+const describeParseErrors = (errors, text, location, singleLine) => {
+  const { linePos } = lineCounter(text);
+  const listed = errors.slice(0, MAX_LISTED_PROBLEMS).map((error) => {
+    const { line, col } = linePos(error.start);
+    return `${location}:${line}:${col}: ${error.message}`;
+  });
+  if (errors.length > MAX_LISTED_PROBLEMS)
+    listed.push(`\u2026and ${errors.length - MAX_LISTED_PROBLEMS} more`);
+  const body = singleLine ? ` ${listed.join("; ")}` : listed.map((problem) => `
+  - ${problem}`).join("");
+  return `Failed to parse YAML:${body}`;
+};
+const describeMultipleDocuments = (warning, text, location, what) => {
+  const { line, col } = lineCounter(text).linePos(warning.start);
+  return `${location}:${line}:${col}: this file contains multiple YAML documents (another one follows this marker); ${what} must be a single-document file.`;
+};
+const parseYamlStrict = (text, location, options) => {
+  const { what, singleLine, ...parseOptions } = options;
+  const doc = parseDocument(text, parseOptions);
+  if (doc.errors.length > 0)
+    throw new Error(describeParseErrors(doc.errors, text, location, singleLine));
+  const multiple = doc.warnings.find((warning) => warning.code === "MULTIPLE_DOCUMENTS");
+  if (multiple !== void 0)
+    throw new Error(describeMultipleDocuments(multiple, text, location, what));
+  return doc.toJS();
+};
+export {
+  parseYamlStrict
+};

package/dist/resolve-policy.js

@@ -1,5 +1,5 @@
 import { dirname, resolve } from "node:path";
-import { withAllowedRootsHint } from "./allowed-roots-hint.js";
+import { describeResolveError } from "./describe-resolve-error.js";
 const buildResolveOptions = (config, documentPath) => {
   const remote = (config.resolveRemote ?? false) || (config.allowedHosts?.length ?? 0) > 0;
   const extraRoots = (config.allowedRoots ?? []).map((root) => resolve(root));
@@ -11,7 +11,7 @@ const buildResolveOptions = (config, documentPath) => {
   };
 };
 const formatResolveErrors = (documentPath, errors) => {
-  const details = errors.map((error) => `  - ${withAllowedRootsHint(error.message)}`).join("\n");
+  const details = errors.map((error) => `  - ${describeResolveError(error.message)}`).join("\n");
   return `Failed to resolve $refs in ${documentPath}:
 ${details}`;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,16 +49,16 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@amritk/adapters": "^0.6.7",
+    "@amritk/adapters": "^0.6.8",
     "@amritk/api": "^0.16.6",
-    "@amritk/asyncapi": "^0.3.5",
-    "@amritk/generate-examples": "^0.8.9",
+    "@amritk/asyncapi": "^0.3.6",
+    "@amritk/generate-examples": "^0.8.10",
     "@amritk/generate-markdown": "^0.11.0",
-    "@amritk/helpers": "^0.23.3",
-    "@amritk/lint": "^0.6.2",
-    "@amritk/validation": "^0.3.2",
-    "@amritk/resolve-refs": "^0.8.0",
-    "@amritk/yaml": "^0.7.3",
+    "@amritk/helpers": "^0.24.0",
+    "@amritk/lint": "^0.7.0",
+    "@amritk/validation": "^0.4.0",
+    "@amritk/resolve-refs": "^0.9.0",
+    "@amritk/yaml": "^0.8.0",
     "fast-glob": "^3.3.2",
     "json-schema-typed": "^8.0.1",
     "yargs": "^17.7.2"