@ac-kit/format-yaml 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @ac-kit/format-yaml
 
+## 0.2.0
+
+### Minor Changes
+
+- a5c4d66: - **Breaking:** `parseYaml` throws `YamlParseError` instead of a bare
+    `Error("parse YAML")`. The parser produces a list of diagnostics, each with a
+    code, a character range and a line and column, and all of it was being
+    collapsed into one opaque `Error` whose only useful content was its `cause` —
+    so a caller reporting a bad config file had to reach through an undocumented
+    wrapper, and only ever saw the first problem. `YamlParseError` extends
+    `SyntaxError` and carries `diagnostics`, one entry per problem found, with
+    `code`, `startOffset`, `endOffset`, `line` and `column`; its message is the
+    parser's own, which already names the position, suffixed with a count when
+    there is more than one, and `cause` stays set to the first underlying
+    diagnostic. Conversion to a plain value still fails as before — an alias bound
+    or a reviver throwing is wrapped in `Error("parse YAML", { cause })`, because
+    it is not a syntax fault. Code matching on the old `"parse YAML"` message for
+    malformed input has to catch `YamlParseError` instead.
+  - The alias-expansion bound is now this package's contract, as
+    `DEFAULT_YAML_MAX_ALIAS_COUNT`. An anchor referenced from inside another
+    anchor expands multiplicatively — the "billion laughs" denial of service — and
+    `maxAliasCount` is the only thing between untrusted YAML and an unbounded
+    allocation, yet the value in force was whatever `yaml` happened to default to,
+    undocumented here and free to change under us. `parseYaml` now passes it
+    explicitly and exports it, so the protection is stated rather than inherited,
+    and `YamlParseStream` gets the same bound. A caller-supplied `maxAliasCount`
+    still wins in either direction: raise it, tighten it, or set `-1` to turn the
+    check off. It applies where a document becomes a plain value, so
+    `parseYamlDocument` and `parseAllYamlDocuments` do not enforce it — they
+    return nodes; pass the constant to the document's own `toJS()` there.
+  - Custom tags are writable without depending on `yaml` directly.
+    `YamlParseOptions` has always accepted `customTags`, while the package
+    exported none of the types that option needs — so anyone defining a tag had to
+    add `yaml` to their own dependencies to name a `ScalarTag`, and the package
+    advertised a contract it did not hand over. The node, tag and visitor model is
+    now re-exported under `Yaml`-prefixed names: `YamlScalarTag`,
+    `YamlCollectionTag`, `YamlTags`, `YamlNode`, `YamlDocument`, `YamlScalar`,
+    `YamlMap`, `YamlSeq`, `YamlAlias`, `YamlPair`, `YamlSchema`, the `isYaml…`
+    guards, `visitYaml` / `visitYamlAsync`, `yamlToJs`, and the context types a
+    tag's own callbacks are typed against. The prefix is not decoration: the
+    package's entry point is a flat barrel, and bare `Node` and `Document` would
+    shadow the DOM globals in the browsers this portable package targets.
+  - New `resolveYamlAsyncTags(node)`. A tag whose `resolve` is declared `async`
+    hands the composer a `Promise`, which it stores as the scalar's value
+    verbatim, so `toJS()` serialises the promise rather than what it settles to.
+    Awaiting the tree once, between composing it and reading it, is what makes an
+    async tag usable at all.
+  - New `addYamlTagDirective(source, handle, prefix)`. A `%TAG` directive is
+    per-document and must precede that document's `---`, so a handle cannot be
+    injected once into a multi-document stream. Each document is inspected and
+    patched on its own, existing directives are joined rather than duplicated, and
+    the `---` and `...` markers the grammar then requires are inserted.
+  - Dropped the `./file` subpath from `publishConfig.exports`. It pointed at
+    `./dist/file.js`, which no `src/file.ts` ever produced, and the development
+    `exports` map never declared it, so the published package advertised an entry
+    point that threw `ERR_MODULE_NOT_FOUND` on import.
+
+### Patch Changes
+
+- Updated dependencies [a5c4d66]
+- Updated dependencies [a5c4d66]
+  - @ac-kit/core@0.3.0
+  - @ac-kit/format-core@0.1.2
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -23,9 +23,64 @@ for (const document of parseAllYamlDocuments(manifestSource)) {
 - `parseAllYamlDocuments` — every document in a multi-document stream.
 - `editYaml` / `createYamlEdits` — change one value, leaving the rest of the
   source as it was.
+- `addYamlTagDirective` — inject a `%TAG` handle into source text, once per
+  document, leaving existing directives and boundaries alone.
+- `resolveYamlAsyncTags` — settle the promises an async custom tag leaves in the
+  node tree.
+- `YamlParseError` — malformed input, carrying every diagnostic with its line
+  and column.
+- The `yaml` node and tag model under `Yaml`-prefixed names — `YamlScalarTag`,
+  `YamlCollectionTag`, `YamlNode`, `YamlDocument`, `YamlScalar`, the
+  `isYaml…` guards, `visitYaml` / `visitYamlAsync`, `yamlToJs` — so a custom tag
+  needs no direct dependency on `yaml`.
 - `YamlParseStream`, `YamlPrintStream`, and the document-oriented stream
   variants — `TransformStream`s over `@ac-kit/format-core`.
 
+## Custom tags
+
+A tag resolves a value of its own; declaring `resolve` `async` leaves a
+`Promise` sitting in the node tree, which `toJS()` would serialise as-is.
+`resolveYamlAsyncTags` awaits the tree once, between composing it and reading
+it:
+
+```ts
+import {
+  parseYamlDocument,
+  resolveYamlAsyncTags,
+  type YamlScalarTag,
+} from "@ac-kit/format-yaml";
+
+const includeTag: YamlScalarTag = {
+  tag: "!include",
+  resolve: async (path) => await readConfig(path),
+};
+
+const document = parseYamlDocument(source, { customTags: [includeTag] });
+await resolveYamlAsyncTags(document);
+document.toJS();
+```
+
+A tag handle has to be declared by a `%TAG` directive before the document that
+uses it, so it cannot be added once to a multi-document file.
+`addYamlTagDirective` patches each document that lacks the handle, inserting the
+`---` and `...` markers the grammar then requires:
+
+```ts
+addYamlTagDirective(source, "!inv!", "tag:example.com,2024:");
+```
+
+## Alias bounds
+
+`parseYaml` caps alias expansion at `DEFAULT_YAML_MAX_ALIAS_COUNT` (100). An
+anchor referenced from inside another anchor expands multiplicatively — the
+"billion laughs" denial of service — and this bound is what keeps untrusted YAML
+from allocating without limit. Pass your own `maxAliasCount` to raise it, lower
+it, or disable the check with `-1`.
+
+The bound applies when a document is converted to a plain value, so
+`parseYamlDocument` and `parseAllYamlDocuments` do not enforce it: they hand
+back nodes. Pass `maxAliasCount` to the document's own `toJS()` there.
+
 Portable: no Node.js built-ins, so it runs unchanged in browsers, Deno, Bun and
 edge runtimes.
 

package/dist/add-tag-directive.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ensures every document in `source` declares `handle` as a `%TAG` prefix,
+ * returning the updated source.
+ *
+ * A `%TAG` directive is per-document and must precede that document's `---`, so
+ * a handle cannot be injected once for a multi-document stream: each document
+ * is inspected and patched on its own. A document already declaring the same
+ * handle, or the same prefix under a different handle, is left alone.
+ *
+ * Existing document boundaries, directives and comments are preserved; a `...`
+ * end marker is inserted where the YAML grammar requires one before a directive
+ * that follows another document. An empty `source` yields a single empty
+ * document carrying the directive.
+ *
+ * Linear in the token count of `source`, over one `yaml.Parser` pass.
+ *
+ * @param source YAML source text.
+ * @param handle Tag handle to ensure, e.g. `"!inv!"`.
+ * @param prefix Tag prefix the handle expands to, e.g.
+ *   `"tag:example.com,2024:"`.
+ */
+export declare function addYamlTagDirective(source: string, handle: string, prefix: string): string;
+//# sourceMappingURL=add-tag-directive.d.ts.map

package/dist/add-tag-directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-tag-directive.d.ts","sourceRoot":"","sources":["../src/add-tag-directive.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACZ,MAAM,CA4HR"}

package/dist/add-tag-directive.js

@@ -0,0 +1,127 @@
+import * as yaml from "yaml";
+/**
+ * Ensures every document in `source` declares `handle` as a `%TAG` prefix,
+ * returning the updated source.
+ *
+ * A `%TAG` directive is per-document and must precede that document's `---`, so
+ * a handle cannot be injected once for a multi-document stream: each document
+ * is inspected and patched on its own. A document already declaring the same
+ * handle, or the same prefix under a different handle, is left alone.
+ *
+ * Existing document boundaries, directives and comments are preserved; a `...`
+ * end marker is inserted where the YAML grammar requires one before a directive
+ * that follows another document. An empty `source` yields a single empty
+ * document carrying the directive.
+ *
+ * Linear in the token count of `source`, over one `yaml.Parser` pass.
+ *
+ * @param source YAML source text.
+ * @param handle Tag handle to ensure, e.g. `"!inv!"`.
+ * @param prefix Tag prefix the handle expands to, e.g.
+ *   `"tag:example.com,2024:"`.
+ */
+export function addYamlTagDirective(source, handle, prefix) {
+    if (source.trim() === "") {
+        return `%TAG ${handle} ${prefix}\n---\n`;
+    }
+    const directiveLine = `%TAG ${handle} ${prefix}\n`;
+    const tokens = Array.from(new yaml.Parser().parse(source));
+    // Applied in reverse so an earlier insertion cannot shift a later offset.
+    const insertions = [];
+    for (const [index, token] of tokens.entries()) {
+        if (token.type !== "document") {
+            continue;
+        }
+        const docStartToken = token.start.find((item) => item.type === "doc-start");
+        const docStartOffset = docStartToken?.offset ?? token.offset;
+        let hasHandle = false;
+        let hasPrefix = false;
+        let lastDirectiveEndOffset = null;
+        let foundExplicitDocEnd = false;
+        let foundDocBoundary = false;
+        let isPreviousDocStartMarkerOnly = false;
+        // Walk back to this document's own directives, stopping at its predecessor.
+        for (let j = index - 1; j >= 0; j--) {
+            const previous = tokens[j];
+            if (previous === undefined) {
+                break;
+            }
+            if (previous.type === "doc-end") {
+                foundExplicitDocEnd = true;
+                foundDocBoundary = true;
+                break;
+            }
+            if (previous.type === "document") {
+                foundDocBoundary = true;
+                const previousDocStart = previous.start.find((item) => item.type === "doc-start");
+                if (previousDocStart !== undefined && !previous.value) {
+                    isPreviousDocStartMarkerOnly = true;
+                }
+                break;
+            }
+            if (previous.type !== "directive" ||
+                !previous.source.startsWith("%TAG ")) {
+                continue;
+            }
+            if (previous.source.startsWith(`%TAG ${handle} `)) {
+                hasHandle = true;
+            }
+            if (/^%TAG\s+\S+\s+(.+)$/.exec(previous.source)?.[1] === prefix) {
+                hasPrefix = true;
+            }
+            const directiveEnd = previous.offset + previous.source.length;
+            if (lastDirectiveEndOffset === null ||
+                directiveEnd > lastDirectiveEndOffset) {
+                lastDirectiveEndOffset = directiveEnd;
+            }
+        }
+        if (hasHandle || hasPrefix) {
+            continue;
+        }
+        if (lastDirectiveEndOffset !== null) {
+            // Join the existing directive block rather than opening a second one.
+            const directiveEnd = lastDirectiveEndOffset;
+            const newlinesAfterDirective = token.start.filter((item) => item.type === "newline" &&
+                item.offset > directiveEnd &&
+                item.offset < docStartOffset);
+            let insertOffset = directiveEnd;
+            if (source[insertOffset] === "\n") {
+                insertOffset++;
+            }
+            for (const _ of newlinesAfterDirective) {
+                if (source[insertOffset] === "\n") {
+                    insertOffset++;
+                }
+            }
+            insertions.push({ offset: insertOffset, text: directiveLine });
+        }
+        else if (foundDocBoundary &&
+            !foundExplicitDocEnd &&
+            !isPreviousDocStartMarkerOnly) {
+            // A directive after another document needs an explicit end marker first.
+            insertions.push({
+                offset: docStartOffset,
+                text: `...\n${directiveLine}`,
+            });
+        }
+        else {
+            insertions.push({ offset: docStartOffset, text: directiveLine });
+        }
+        if (docStartToken === undefined) {
+            // Directives oblige the document to open with an explicit `---`.
+            insertions.push({
+                offset: docStartOffset,
+                text: docStartOffset >= source.length ? "\n---\n" : "---\n",
+            });
+        }
+    }
+    let result = source;
+    for (const insertion of insertions.reverse()) {
+        result =
+            result.slice(0, insertion.offset) +
+                insertion.text +
+                result.slice(insertion.offset);
+    }
+    return result;
+}
+//# sourceMappingURL=add-tag-directive.js.map

package/dist/add-tag-directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-tag-directive.js","sourceRoot":"","sources":["../src/add-tag-directive.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+import type * as yaml from "yaml";
+/** One parser diagnostic, with where in the source it applies. */
+export type YamlDiagnostic = {
+    /** The `yaml` error code, e.g. `BAD_INDENT` or `MISSING_CHAR`. */
+    readonly code: string;
+    readonly message: string;
+    /** Character offsets into the source the diagnostic covers. */
+    readonly startOffset: number;
+    readonly endOffset: number;
+    /** 1-based line, absent when `prettyErrors: false` suppressed line counting. */
+    readonly line?: number;
+    /** 1-based column, absent under the same condition as {@link line}. */
+    readonly column?: number;
+};
+/**
+ * Input that is not well-formed YAML, carrying every diagnostic the parser
+ * produced rather than only the first.
+ */
+export declare class YamlParseError extends SyntaxError {
+    readonly diagnostics: readonly YamlDiagnostic[];
+    constructor(errors: readonly yaml.YAMLError[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,IAAI,MAAM,MAAM,CAAC;AAElC,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC9C,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAEhD,YAAY,MAAM,EAAE,SAAS,IAAI,CAAC,SAAS,EAAE,EAY5C;CACD"}

package/dist/errors.js

@@ -0,0 +1,29 @@
+/**
+ * Input that is not well-formed YAML, carrying every diagnostic the parser
+ * produced rather than only the first.
+ */
+export class YamlParseError extends SyntaxError {
+    diagnostics;
+    constructor(errors) {
+        const [first, ...rest] = errors;
+        super(first === undefined
+            ? "Invalid YAML"
+            : rest.length === 0
+                ? first.message
+                : `${first.message} (and ${rest.length} further error${rest.length === 1 ? "" : "s"})`, { cause: first });
+        this.name = "YamlParseError";
+        this.diagnostics = errors.map(toDiagnostic_);
+    }
+}
+function toDiagnostic_(error) {
+    const [startOffset, endOffset] = error.pos;
+    const start = error.linePos?.[0];
+    return {
+        code: error.code,
+        message: error.message,
+        startOffset,
+        endOffset,
+        ...(start === undefined ? {} : { line: start.line, column: start.col }),
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,WAAW;IACrC,WAAW,CAA4B;IAEhD,YAAY,MAAiC;QAC5C,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;QAChC,KAAK,CACJ,KAAK,KAAK,SAAS;YAClB,CAAC,CAAC,cAAc;YAChB,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;gBAClB,CAAC,CAAC,KAAK,CAAC,OAAO;gBACf,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,SAAS,IAAI,CAAC,MAAM,iBAAiB,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,EACxF,EAAE,KAAK,EAAE,KAAK,EAAE,CAChB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC9C,CAAC;CACD;AAED,SAAS,aAAa,CAAC,KAAqB;IAC3C,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC;IAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IACjC,OAAO;QACN,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,WAAW;QACX,SAAS;QACT,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;KACvE,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,10 +1,25 @@
+export * from "./add-tag-directive.js";
 export * from "./document-parse-stream.js";
 export * from "./document-print-stream.js";
 export * from "./documents-parse-stream.js";
 export * from "./documents-print-stream.js";
 export * from "./edit.js";
+export * from "./errors.js";
 export * from "./parse-stream.js";
 export * from "./parse.js";
 export * from "./print-stream.js";
 export * from "./print.js";
+export * from "./resolve-async-tags.js";
+/**
+ * The `yaml` node, tag and visitor model, re-exported so a caller can write a
+ * custom tag without taking its own dependency on `yaml`.
+ *
+ * Names are `Yaml`-prefixed rather than kept as upstream. This package's index
+ * is a flat `export *`, so a bare `Node`, `Document`, `Scalar` or `Schema`
+ * would sit beside `YamlParseStream` and `parseYaml` under names that say
+ * nothing about YAML — and `Node` and `Document` are DOM globals, which this
+ * package, being portable, is expected to be imported alongside.
+ */
+export { isAlias as isYamlAlias, isCollection as isYamlCollection, isDocument as isYamlDocument, isMap as isYamlMap, isNode as isYamlNode, isPair as isYamlPair, isScalar as isYamlScalar, isSeq as isYamlSeq, visit as visitYaml, visitAsync as visitYamlAsync, Alias as YamlAlias, Document as YamlDocument, YAMLMap as YamlMap, Pair as YamlPair, Scalar as YamlScalar, Schema as YamlSchema, YAMLSeq as YamlSeq, type asyncVisitor as YamlAsyncVisitor, type CollectionTag as YamlCollectionTag, type Node as YamlNode, type ParsedNode as YamlParsedNode, type Range as YamlRange, type ScalarTag as YamlScalarTag, type TagId as YamlTagId, type Tags as YamlTags, type visitor as YamlVisitor, } from "yaml";
+export { toJS as yamlToJs, type CreateNodeContext as YamlCreateNodeContext, type StringifyContext as YamlStringifyContext, type ToJSContext as YamlToJsContext, } from "yaml/util";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AAExC;;;;;;;;;GASG;AAEH,OAAO,EACN,OAAO,IAAI,WAAW,EACtB,YAAY,IAAI,gBAAgB,EAChC,UAAU,IAAI,cAAc,EAC5B,KAAK,IAAI,SAAS,EAClB,MAAM,IAAI,UAAU,EACpB,MAAM,IAAI,UAAU,EACpB,QAAQ,IAAI,YAAY,EACxB,KAAK,IAAI,SAAS,EAClB,KAAK,IAAI,SAAS,EAClB,UAAU,IAAI,cAAc,EAC5B,KAAK,IAAI,SAAS,EAClB,QAAQ,IAAI,YAAY,EACxB,OAAO,IAAI,OAAO,EAClB,IAAI,IAAI,QAAQ,EAChB,MAAM,IAAI,UAAU,EACpB,MAAM,IAAI,UAAU,EACpB,OAAO,IAAI,OAAO,EAClB,KAAK,YAAY,IAAI,gBAAgB,EACrC,KAAK,aAAa,IAAI,iBAAiB,EACvC,KAAK,IAAI,IAAI,QAAQ,EACrB,KAAK,UAAU,IAAI,cAAc,EACjC,KAAK,KAAK,IAAI,SAAS,EACvB,KAAK,SAAS,IAAI,aAAa,EAC/B,KAAK,KAAK,IAAI,SAAS,EACvB,KAAK,IAAI,IAAI,QAAQ,EACrB,KAAK,OAAO,IAAI,WAAW,GAC3B,MAAM,MAAM,CAAC;AACd,OAAO,EACN,IAAI,IAAI,QAAQ,EAChB,KAAK,iBAAiB,IAAI,qBAAqB,EAC/C,KAAK,gBAAgB,IAAI,oBAAoB,EAC7C,KAAK,WAAW,IAAI,eAAe,GACnC,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,10 +1,25 @@
+export * from "./add-tag-directive.js";
 export * from "./document-parse-stream.js";
 export * from "./document-print-stream.js";
 export * from "./documents-parse-stream.js";
 export * from "./documents-print-stream.js";
 export * from "./edit.js";
+export * from "./errors.js";
 export * from "./parse-stream.js";
 export * from "./parse.js";
 export * from "./print-stream.js";
 export * from "./print.js";
+export * from "./resolve-async-tags.js";
+/**
+ * The `yaml` node, tag and visitor model, re-exported so a caller can write a
+ * custom tag without taking its own dependency on `yaml`.
+ *
+ * Names are `Yaml`-prefixed rather than kept as upstream. This package's index
+ * is a flat `export *`, so a bare `Node`, `Document`, `Scalar` or `Schema`
+ * would sit beside `YamlParseStream` and `parseYaml` under names that say
+ * nothing about YAML — and `Node` and `Document` are DOM globals, which this
+ * package, being portable, is expected to be imported alongside.
+ */
+export { isAlias as isYamlAlias, isCollection as isYamlCollection, isDocument as isYamlDocument, isMap as isYamlMap, isNode as isYamlNode, isPair as isYamlPair, isScalar as isYamlScalar, isSeq as isYamlSeq, visit as visitYaml, visitAsync as visitYamlAsync, Alias as YamlAlias, Document as YamlDocument, YAMLMap as YamlMap, Pair as YamlPair, Scalar as YamlScalar, Schema as YamlSchema, YAMLSeq as YamlSeq, } from "yaml";
+export { toJS as yamlToJs, } from "yaml/util";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AAExC;;;;;;;;;GASG;AAEH,OAAO,EACN,OAAO,IAAI,WAAW,EACtB,YAAY,IAAI,gBAAgB,EAChC,UAAU,IAAI,cAAc,EAC5B,KAAK,IAAI,SAAS,EAClB,MAAM,IAAI,UAAU,EACpB,MAAM,IAAI,UAAU,EACpB,QAAQ,IAAI,YAAY,EACxB,KAAK,IAAI,SAAS,EAClB,KAAK,IAAI,SAAS,EAClB,UAAU,IAAI,cAAc,EAC5B,KAAK,IAAI,SAAS,EAClB,QAAQ,IAAI,YAAY,EACxB,OAAO,IAAI,OAAO,EAClB,IAAI,IAAI,QAAQ,EAChB,MAAM,IAAI,UAAU,EACpB,MAAM,IAAI,UAAU,EACpB,OAAO,IAAI,OAAO,GAUlB,MAAM,MAAM,CAAC;AACd,OAAO,EACN,IAAI,IAAI,QAAQ,GAIhB,MAAM,WAAW,CAAC"}

package/dist/parse-stream.d.ts

@@ -1,4 +1,4 @@
-import * as yaml from "yaml";
+import type * as yaml from "yaml";
 export type YamlParseStreamOptions = yaml.ParseOptions & yaml.DocumentOptions & yaml.SchemaOptions;
 /** Buffers a byte stream and emits one parsed YAML value on flush. */
 export declare class YamlParseStream extends TransformStream<Uint8Array, unknown> {

package/dist/parse-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-stream.d.ts","sourceRoot":"","sources":["../src/parse-stream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,YAAY,GACrD,IAAI,CAAC,eAAe,GACpB,IAAI,CAAC,aAAa,CAAC;AAEpB,sEAAsE;AACtE,qBAAa,eAAgB,SAAQ,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC;IACxE,YAAY,OAAO,GAAE,sBAA2B,EAO/C;CACD"}
+{"version":3,"file":"parse-stream.d.ts","sourceRoot":"","sources":["../src/parse-stream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,IAAI,MAAM,MAAM,CAAC;AAIlC,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,YAAY,GACrD,IAAI,CAAC,eAAe,GACpB,IAAI,CAAC,aAAa,CAAC;AAEpB,sEAAsE;AACtE,qBAAa,eAAgB,SAAQ,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC;IACxE,YAAY,OAAO,GAAE,sBAA2B,EAI/C;CACD"}

package/dist/parse-stream.js

@@ -1,9 +1,9 @@
 import { wholeTextParseTransformer } from "@ac-kit/format-core";
-import * as yaml from "yaml";
+import { parseYaml } from "./parse.js";
 /** Buffers a byte stream and emits one parsed YAML value on flush. */
 export class YamlParseStream extends TransformStream {
     constructor(options = {}) {
-        super(wholeTextParseTransformer((source) => yaml.parse(source, options), "YAML"));
+        super(wholeTextParseTransformer((source) => parseYaml(source, options), "YAML"));
     }
 }
 //# sourceMappingURL=parse-stream.js.map

package/dist/parse-stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse-stream.js","sourceRoot":"","sources":["../src/parse-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAM7B,sEAAsE;AACtE,MAAM,OAAO,eAAgB,SAAQ,eAAoC;IACxE,YAAY,OAAO,GAA2B,EAAE;QAC/C,KAAK,CACJ,yBAAyB,CACxB,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAY,EAClD,MAAM,CACN,CACD,CAAC;IACH,CAAC;CACD"}
+{"version":3,"file":"parse-stream.js","sourceRoot":"","sources":["../src/parse-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAMvC,sEAAsE;AACtE,MAAM,OAAO,eAAgB,SAAQ,eAAoC;IACxE,YAAY,OAAO,GAA2B,EAAE;QAC/C,KAAK,CACJ,yBAAyB,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CACzE,CAAC;IACH,CAAC;CACD"}

package/dist/parse.d.ts

@@ -1,9 +1,36 @@
 import * as yaml from "yaml";
 export type YamlParseOptions = yaml.ParseOptions & yaml.DocumentOptions & yaml.SchemaOptions & yaml.ToJSOptions;
-/** Parses a YAML string into a plain JS value. */
+/**
+ * Alias expansions allowed while converting a document to a plain value, unless
+ * the caller passes its own `maxAliasCount`.
+ *
+ * An anchor referenced from inside another anchor expands multiplicatively —
+ * the "billion laughs" denial of service — and this bound is the only thing
+ * between untrusted YAML and an unbounded allocation. `-1` disables the check,
+ * `0` rejects every alias.
+ */
+export declare const DEFAULT_YAML_MAX_ALIAS_COUNT = 100;
+/**
+ * Parses a YAML string into a plain JS value.
+ *
+ * Throws {@link YamlParseError} for malformed input, carrying every diagnostic
+ * with its position. Alias expansion is bounded by
+ * {@link DEFAULT_YAML_MAX_ALIAS_COUNT}.
+ */
 export declare function parseYaml(source: string, options?: YamlParseOptions): unknown;
-/** Parses a YAML string into a {@link yaml.Document} (CST-level). */
+/**
+ * Parses a YAML string into a {@link yaml.Document} (CST-level).
+ *
+ * Error-tolerant, as `yaml`'s own `parseDocument` is: diagnostics stay on the
+ * returned document's `errors`, so partially valid source is still inspectable.
+ * Hand them to {@link YamlParseError} to turn them into a throw. `maxAliasCount`
+ * bounds `toJS()`, not this call.
+ */
 export declare function parseYamlDocument(source: string, options?: yaml.ParseOptions & yaml.DocumentOptions & yaml.SchemaOptions): yaml.Document;
-/** Parses all YAML documents from a multi-document string. */
+/**
+ * Parses all YAML documents from a multi-document string.
+ *
+ * Error-tolerant in the same way as {@link parseYamlDocument}.
+ */
 export declare function parseAllYamlDocuments(source: string, options?: yaml.ParseOptions & yaml.DocumentOptions & yaml.SchemaOptions): yaml.Document[];
 //# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,GAC/C,IAAI,CAAC,eAAe,GACpB,IAAI,CAAC,aAAa,GAClB,IAAI,CAAC,WAAW,CAAC;AAElB,kDAAkD;AAClD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAM7E;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,aAAa,GACrE,IAAI,CAAC,QAAQ,CAEf;AAED,8DAA8D;AAC9D,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,aAAa,GACrE,IAAI,CAAC,QAAQ,EAAE,CAEjB"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAK7B,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,GAC/C,IAAI,CAAC,eAAe,GACpB,IAAI,CAAC,aAAa,GAClB,IAAI,CAAC,WAAW,CAAC;AAElB;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAmB7E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,aAAa,GACrE,IAAI,CAAC,QAAQ,CAEf;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,aAAa,GACrE,IAAI,CAAC,QAAQ,EAAE,CAEjB"}

package/dist/parse.js

@@ -1,18 +1,58 @@
 import * as yaml from "yaml";
-/** Parses a YAML string into a plain JS value. */
+import { warn } from "yaml/util";
+import { YamlParseError } from "./errors.js";
+/**
+ * Alias expansions allowed while converting a document to a plain value, unless
+ * the caller passes its own `maxAliasCount`.
+ *
+ * An anchor referenced from inside another anchor expands multiplicatively —
+ * the "billion laughs" denial of service — and this bound is the only thing
+ * between untrusted YAML and an unbounded allocation. `-1` disables the check,
+ * `0` rejects every alias.
+ */
+export const DEFAULT_YAML_MAX_ALIAS_COUNT = 100;
+/**
+ * Parses a YAML string into a plain JS value.
+ *
+ * Throws {@link YamlParseError} for malformed input, carrying every diagnostic
+ * with its position. Alias expansion is bounded by
+ * {@link DEFAULT_YAML_MAX_ALIAS_COUNT}.
+ */
 export function parseYaml(source, options) {
+    const logLevel = options?.logLevel ?? "warn";
+    const document = yaml.parseDocument(source, options);
+    for (const warning of document.warnings) {
+        warn(logLevel, warning);
+    }
+    if (document.errors.length > 0 && logLevel !== "silent") {
+        throw new YamlParseError(document.errors);
+    }
     try {
-        return yaml.parse(source, options);
+        return document.toJS({
+            maxAliasCount: DEFAULT_YAML_MAX_ALIAS_COUNT,
+            ...options,
+        });
     }
     catch (error) {
         throw new Error("parse YAML", { cause: error });
     }
 }
-/** Parses a YAML string into a {@link yaml.Document} (CST-level). */
+/**
+ * Parses a YAML string into a {@link yaml.Document} (CST-level).
+ *
+ * Error-tolerant, as `yaml`'s own `parseDocument` is: diagnostics stay on the
+ * returned document's `errors`, so partially valid source is still inspectable.
+ * Hand them to {@link YamlParseError} to turn them into a throw. `maxAliasCount`
+ * bounds `toJS()`, not this call.
+ */
 export function parseYamlDocument(source, options) {
     return yaml.parseDocument(source, options);
 }
-/** Parses all YAML documents from a multi-document string. */
+/**
+ * Parses all YAML documents from a multi-document string.
+ *
+ * Error-tolerant in the same way as {@link parseYamlDocument}.
+ */
 export function parseAllYamlDocuments(source, options) {
     return yaml.parseAllDocuments(source, options);
 }

package/dist/parse.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAO7B,kDAAkD;AAClD,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,OAA0B;IACnE,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,CAAC;AACF,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,iBAAiB,CAChC,MAAc,EACd,OAAuE;IAEvE,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,qBAAqB,CACpC,MAAc,EACd,OAAuE;IAEvE,OAAO,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAO7C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,OAA0B;IACnE,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAErD,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACzC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACzD,MAAM,IAAI,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,CAAC;QACJ,OAAO,QAAQ,CAAC,IAAI,CAAC;YACpB,aAAa,EAAE,4BAA4B;YAC3C,GAAG,OAAO;SACV,CAAC,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAChC,MAAc,EACd,OAAuE;IAEvE,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACpC,MAAc,EACd,OAAuE;IAEvE,OAAO,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC"}

package/dist/resolve-async-tags.d.ts

@@ -0,0 +1,14 @@
+import * as yaml from "yaml";
+/**
+ * Settles every `Promise` an async custom tag left behind in `node`.
+ *
+ * A `ScalarTag.resolve` declared `async` hands the composer a `Promise`, which
+ * it stores as the scalar's value verbatim — so `toJS()` would serialise the
+ * promise rather than what it settles to. Awaiting the tree once, between
+ * composing it and reading it, is what makes an async tag usable.
+ *
+ * Mutates `node` in place. Linear in the number of nodes; the awaits run in
+ * document order, not concurrently.
+ */
+export declare function resolveYamlAsyncTags(node: yaml.Node | yaml.Document | null): Promise<void>;
+//# sourceMappingURL=resolve-async-tags.d.ts.map

package/dist/resolve-async-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-async-tags.d.ts","sourceRoot":"","sources":["../src/resolve-async-tags.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACzC,IAAI,EAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,GACpC,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/resolve-async-tags.js

@@ -0,0 +1,23 @@
+import { isPromise } from "@ac-kit/core";
+import * as yaml from "yaml";
+/**
+ * Settles every `Promise` an async custom tag left behind in `node`.
+ *
+ * A `ScalarTag.resolve` declared `async` hands the composer a `Promise`, which
+ * it stores as the scalar's value verbatim — so `toJS()` would serialise the
+ * promise rather than what it settles to. Awaiting the tree once, between
+ * composing it and reading it, is what makes an async tag usable.
+ *
+ * Mutates `node` in place. Linear in the number of nodes; the awaits run in
+ * document order, not concurrently.
+ */
+export async function resolveYamlAsyncTags(node) {
+    await yaml.visitAsync(node, {
+        async Scalar(_key, scalar) {
+            if (isPromise(scalar.value)) {
+                scalar.value = await scalar.value;
+            }
+        },
+    });
+}
+//# sourceMappingURL=resolve-async-tags.js.map

package/dist/resolve-async-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-async-tags.js","sourceRoot":"","sources":["../src/resolve-async-tags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,IAAsC;IAEtC,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE;QAC3B,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM;YACxB,IAAI,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,MAAM,CAAC,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC;YACnC,CAAC;QACF,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ac-kit/format-yaml",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "YAML parse and print streams over @ac-kit/format-core.",
   "keywords": [
     "config",
@@ -26,14 +26,12 @@
   "sideEffects": false,
   "main": "./dist/index.js",
   "exports": {
-    ".": "./dist/index.js",
-    "./file": "./dist/file.js"
+    ".": "./dist/index.js"
   },
   "publishConfig": {
     "main": "./dist/index.js",
     "exports": {
-      ".": "./dist/index.js",
-      "./file": "./dist/file.js"
+      ".": "./dist/index.js"
     },
     "access": "public"
   },
@@ -46,8 +44,8 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@ac-kit/core": "^0.2.0",
-    "@ac-kit/format-core": "^0.1.1",
+    "@ac-kit/core": "^0.3.0",
+    "@ac-kit/format-core": "^0.1.2",
     "@types/node": "^26.5.1",
     "yaml": "^2.9.0"
   },