@wildwinter/toolkit 0.2.0 → 0.2.2

package/dist/extensions.d.cts

@@ -150,6 +150,17 @@ declare function resolvedClaims(manifest: Manifest, host: HostName, chosen?: Rea
 declare function claimClashes(claims: readonly ResolvedClaim[]): Problem[];
 /** One manifest's declarations for one host and node kind, or undefined. */
 declare function targetOf(manifest: Manifest | undefined, host: HostName, kind: string): TargetDecl | undefined;
+/**
+ * A claim as a host draws and checks its field: the claim's label, help, value help and constraints, over the
+ * host's own declaration for what the claim leaves out (an enum's or flags' values, a quality's stages, the
+ * default). The host's vocabulary stands when the claim names none, as the host's ladder always does.
+ */
+declare function effectiveClaim<C extends ClaimDecl>(claim: C, hostDecl: {
+    readonly type?: string;
+    readonly values?: readonly string[];
+    readonly stages?: readonly string[];
+    readonly default?: unknown;
+}): C;
 
 /** What the host knows about its nodes, for references. */
 interface ValueContext {
@@ -198,6 +209,8 @@ declare function renameStages(target: TargetDecl, entry: Readonly<Record<string,
  *                   sorted by key, or in the authored order with `order: "preserve"`
  *   object(fields)  named keys by their own strategy, every other key by `other`
  *                   (atomic when absent)
+ *   comments        a list of comment threads, merged message by message
+ *                   (`mergeComments`)
  */
 type Strategy = {
     readonly kind: "atomic";
@@ -216,9 +229,12 @@ type Strategy = {
     readonly kind: "object";
     readonly fields: Readonly<Record<string, Strategy>>;
     readonly other?: Strategy;
+} | {
+    readonly kind: "comments";
 };
 declare const ATOMIC: Strategy;
 declare const SET: Strategy;
+declare const COMMENTS: Strategy;
 declare const mapOf: (of: Strategy) => Strategy;
 declare const keyedBy: (key: string, of: Strategy, opts?: {
     order?: "sorted" | "preserve";
@@ -256,6 +272,25 @@ interface TreeMergeOptions {
 declare function stableStringify(value: unknown): string;
 /** Three-way merge `base`, `ours` and `theirs` by `strategy`. A clash keeps ours. */
 declare function mergeTree(strategy: Strategy, base: unknown, ours: unknown, theirs: unknown, opts?: TreeMergeOptions): TreeMergeResult;
+/**
+ * Three-way merge two lists of comment threads, the shape both families'
+ * comments share: `{ id, messages: [{ author, ts, body, deleted? }], resolved?,
+ * ...}`. Lifted from Patter's merge (patterkit design/family-parity-2026-10.md
+ * item 5), where a thread merged whole made two replies to one thread clash.
+ *
+ * - Messages are keyed by author and timestamp, and are the union of both
+ *   sides', oldest first. A withdrawn message (a tombstone: body emptied,
+ *   `deleted` set) stays withdrawn whichever side withdrew it, and a message a
+ *   side removed outright, or lost with its whole thread, counts as withdrawn
+ *   by that side. One message edited two ways is a clash that keeps ours.
+ * - A thread's other fields (its anchor, its marker, `resolved`) merge one by
+ *   one, a field changed two ways being a clash; a thread one side removed
+ *   takes the other side's.
+ * - A thread with nothing readable left goes, as the editors drop it.
+ *
+ * Threads come back oldest first, by their first message, then by id.
+ */
+declare function mergeComments(base: unknown, ours: unknown, theirs: unknown, opts?: TreeMergeOptions): TreeMergeResult;
 /** How a value of this type merges (the README's table). */
 declare function strategyForType(decl: TypeDecl): Strategy;
 /** How one node's entry merges: field by field, each by its type. */
@@ -310,4 +345,4 @@ declare const atKey: (base: string, key: string) => string;
 /** `base` and then list position `i`. */
 declare const atIndex: (base: string, i: number) => string;
 
-export { ATOMIC, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, entryProblems, extensionDataStrategy, keyedBy, manifestProblems, mapOf, markUnresolved, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };
+export { ATOMIC, COMMENTS, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };

package/dist/extensions.d.ts

@@ -150,6 +150,17 @@ declare function resolvedClaims(manifest: Manifest, host: HostName, chosen?: Rea
 declare function claimClashes(claims: readonly ResolvedClaim[]): Problem[];
 /** One manifest's declarations for one host and node kind, or undefined. */
 declare function targetOf(manifest: Manifest | undefined, host: HostName, kind: string): TargetDecl | undefined;
+/**
+ * A claim as a host draws and checks its field: the claim's label, help, value help and constraints, over the
+ * host's own declaration for what the claim leaves out (an enum's or flags' values, a quality's stages, the
+ * default). The host's vocabulary stands when the claim names none, as the host's ladder always does.
+ */
+declare function effectiveClaim<C extends ClaimDecl>(claim: C, hostDecl: {
+    readonly type?: string;
+    readonly values?: readonly string[];
+    readonly stages?: readonly string[];
+    readonly default?: unknown;
+}): C;
 
 /** What the host knows about its nodes, for references. */
 interface ValueContext {
@@ -198,6 +209,8 @@ declare function renameStages(target: TargetDecl, entry: Readonly<Record<string,
  *                   sorted by key, or in the authored order with `order: "preserve"`
  *   object(fields)  named keys by their own strategy, every other key by `other`
  *                   (atomic when absent)
+ *   comments        a list of comment threads, merged message by message
+ *                   (`mergeComments`)
  */
 type Strategy = {
     readonly kind: "atomic";
@@ -216,9 +229,12 @@ type Strategy = {
     readonly kind: "object";
     readonly fields: Readonly<Record<string, Strategy>>;
     readonly other?: Strategy;
+} | {
+    readonly kind: "comments";
 };
 declare const ATOMIC: Strategy;
 declare const SET: Strategy;
+declare const COMMENTS: Strategy;
 declare const mapOf: (of: Strategy) => Strategy;
 declare const keyedBy: (key: string, of: Strategy, opts?: {
     order?: "sorted" | "preserve";
@@ -256,6 +272,25 @@ interface TreeMergeOptions {
 declare function stableStringify(value: unknown): string;
 /** Three-way merge `base`, `ours` and `theirs` by `strategy`. A clash keeps ours. */
 declare function mergeTree(strategy: Strategy, base: unknown, ours: unknown, theirs: unknown, opts?: TreeMergeOptions): TreeMergeResult;
+/**
+ * Three-way merge two lists of comment threads, the shape both families'
+ * comments share: `{ id, messages: [{ author, ts, body, deleted? }], resolved?,
+ * ...}`. Lifted from Patter's merge (patterkit design/family-parity-2026-10.md
+ * item 5), where a thread merged whole made two replies to one thread clash.
+ *
+ * - Messages are keyed by author and timestamp, and are the union of both
+ *   sides', oldest first. A withdrawn message (a tombstone: body emptied,
+ *   `deleted` set) stays withdrawn whichever side withdrew it, and a message a
+ *   side removed outright, or lost with its whole thread, counts as withdrawn
+ *   by that side. One message edited two ways is a clash that keeps ours.
+ * - A thread's other fields (its anchor, its marker, `resolved`) merge one by
+ *   one, a field changed two ways being a clash; a thread one side removed
+ *   takes the other side's.
+ * - A thread with nothing readable left goes, as the editors drop it.
+ *
+ * Threads come back oldest first, by their first message, then by id.
+ */
+declare function mergeComments(base: unknown, ours: unknown, theirs: unknown, opts?: TreeMergeOptions): TreeMergeResult;
 /** How a value of this type merges (the README's table). */
 declare function strategyForType(decl: TypeDecl): Strategy;
 /** How one node's entry merges: field by field, each by its type. */
@@ -310,4 +345,4 @@ declare const atKey: (base: string, key: string) => string;
 /** `base` and then list position `i`. */
 declare const atIndex: (base: string, i: number) => string;
 
-export { ATOMIC, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, entryProblems, extensionDataStrategy, keyedBy, manifestProblems, mapOf, markUnresolved, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };
+export { ATOMIC, COMMENTS, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };

package/dist/extensions.js

@@ -396,7 +396,7 @@ function targetProblems(host, kind, target, path, settings, out) {
     if (!SCALAR_TYPES.includes(claim.type)) {
       out.push(err2("claim-type", atKey(at, "type"), "a claim presents a host field, which is a scalar"));
     } else {
-      typeProblems(host, claim, at, false, out);
+      typeProblems(host, claim, at, false, out, true);
     }
     if (typeof claim.setting !== "string" || !settings.has(claim.setting)) {
       out.push(err2("claim-setting", atKey(at, "setting"), `a claim names its field through a setting, and "${String(claim.setting)}" is not one of the manifest's settings`));
@@ -439,7 +439,7 @@ function fieldListProblems(host, fields, path, topLevel, out) {
     }
   });
 }
-function typeProblems(host, decl, path, named, out) {
+function typeProblems(host, decl, path, named, out, claim = false) {
   const typeAt = atKey(path, "type");
   if (decl.type === "string") {
     out.push(err2("string-type", typeAt, 'the text type is spelled "text"'));
@@ -455,6 +455,7 @@ function typeProblems(host, decl, path, named, out) {
     case "enum":
     case "flags": {
       const values = decl.values;
+      if (claim && values === void 0) break;
       if (!Array.isArray(values) || values.length === 0) {
         out.push(err2("values-empty", at("values"), `an ${decl.type === "enum" ? "enum" : "flags field"} lists its values`));
         sound = false;
@@ -473,6 +474,7 @@ function typeProblems(host, decl, path, named, out) {
       break;
     }
     case "quality": {
+      if (claim && decl.stages === void 0) break;
       for (const p of qualityDeclarationProblems(decl.stages)) {
         out.push(err2(
           `quality-${p.kind === "default-not-a-stage" ? "default" : p.kind}`,
@@ -532,7 +534,11 @@ function typeProblems(host, decl, path, named, out) {
     }
   }
   if (decl.renamedStages !== void 0) renamedStagesProblems(decl, at("renamedStages"), out);
-  if (decl.valueHelp !== void 0) {
+  if (decl.valueHelp !== void 0 && claim) {
+    if (!isObject(decl.valueHelp) || !["enum", "flags", "quality"].includes(decl.type)) {
+      out.push(err2("value-help", at("valueHelp"), "value help describes the values of an enum or flags field, or a quality's stages"));
+    }
+  } else if (decl.valueHelp !== void 0) {
     const vocabulary = decl.type === "quality" ? decl.stages : decl.type === "enum" || decl.type === "flags" ? decl.values : void 0;
     if (vocabulary === void 0 || !isObject(decl.valueHelp)) {
       out.push(err2("value-help", at("valueHelp"), "value help describes the values of an enum or flags field, or a quality's stages"));
@@ -613,10 +619,19 @@ function targetOf(manifest, host, kind) {
   const kinds = manifest?.targets[host];
   return kinds !== void 0 && own(kinds, kind) ? kinds[kind] : void 0;
 }
+function effectiveClaim(claim, hostDecl) {
+  return {
+    ...claim,
+    ...claim.values === void 0 && hostDecl.values !== void 0 ? { values: hostDecl.values } : {},
+    ...claim.stages === void 0 && hostDecl.stages !== void 0 ? { stages: hostDecl.stages } : {},
+    ...claim.default === void 0 && hostDecl.default !== void 0 ? { default: hostDecl.default } : {}
+  };
+}
 
 // src/extensions/merge.ts
 var ATOMIC = { kind: "atomic" };
 var SET = { kind: "set" };
+var COMMENTS = { kind: "comments" };
 var mapOf = (of) => ({ kind: "map", of });
 var keyedBy = (key, of, opts) => ({
   kind: "keyed",
@@ -659,6 +674,7 @@ function hasShape(spec, v) {
       return true;
     case "set":
     case "keyed":
+    case "comments":
       return Array.isArray(v);
     case "map":
     case "object":
@@ -698,6 +714,8 @@ function mergeValue(spec, b, o, t, id, path, ctx) {
     }
     case "keyed":
       return mergeKeyed(spec, asArr(b), o, t, path, ctx);
+    case "comments":
+      return mergeThreads(asArr(b), o, t, path, ctx);
   }
 }
 function mergeKeyed(spec, B, O, T, path, ctx) {
@@ -776,6 +794,70 @@ function preservedOrder(B, O, T, survivors, path, ctx) {
   for (const k of [...survivors.keys()].sort()) if (!result.includes(k)) result.push(k);
   return result;
 }
+function mergeComments(base, ours, theirs, opts) {
+  return mergeTree(COMMENTS, base, ours, theirs, opts);
+}
+function mergeThreads(B, O, T, path, ctx) {
+  const index = (arr) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const c of arr) if (isObject(c) && typeof c["id"] === "string") m.set(c["id"], c);
+    return m;
+  };
+  const Bm = index(B), Om = index(O), Tm = index(T);
+  const out = [];
+  for (const id of /* @__PURE__ */ new Set([...Bm.keys(), ...Om.keys(), ...Tm.keys()])) {
+    const b = Bm.get(id), o = Om.get(id), t = Tm.get(id);
+    const here = `${path}[${id}]`;
+    if (o === void 0 && t === void 0) continue;
+    if (![b, o, t].some((c) => Array.isArray(c?.["messages"]))) {
+      const v = o !== void 0 && t !== void 0 ? merge3(b, o, t, id, here, ctx) : b !== void 0 && ctx.eq(o ?? t, b) ? void 0 : o ?? t;
+      if (isObject(v)) out.push(v);
+      continue;
+    }
+    const messages = mergeMessages(b, o, t, id, here, ctx);
+    if (messages.length === 0 || messages.every((m) => m["deleted"] === true)) continue;
+    const fields = {};
+    if (o !== void 0 && t !== void 0) {
+      const B0 = b ?? {};
+      const flag = (c, k) => k === "resolved" ? c[k] === true ? true : void 0 : c[k];
+      for (const k of /* @__PURE__ */ new Set([...Object.keys(o), ...Object.keys(t), ...Object.keys(B0)])) {
+        if (k === "messages") continue;
+        const v = merge3(flag(B0, k), flag(o, k), flag(t, k), id, `${here}.${k}`, ctx);
+        if (v !== void 0) fields[k] = v;
+      }
+    } else {
+      for (const [k, v] of Object.entries(o ?? t)) if (k !== "messages") fields[k] = v;
+    }
+    out.push({ ...fields, messages });
+  }
+  const first = (c) => {
+    const m = asArr(c["messages"])[0];
+    return isObject(m) && typeof m["ts"] === "string" ? m["ts"] : "";
+  };
+  return out.sort((x, y) => first(x).localeCompare(first(y)) || String(x["id"]).localeCompare(String(y["id"])));
+}
+function mergeMessages(b, o, t, id, here, ctx) {
+  const keyOf = (m) => `${String(m["author"] ?? "")}|${String(m["ts"] ?? "")}`;
+  const index = (c) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const x of asArr(c?.["messages"])) if (isObject(x)) m.set(keyOf(x), x);
+    return m;
+  };
+  const Bm = index(b), Om = index(o), Tm = index(t);
+  const out = [];
+  for (const k of /* @__PURE__ */ new Set([...Bm.keys(), ...Om.keys(), ...Tm.keys()])) {
+    const mb = Bm.get(k), mo = Om.get(k), mt = Tm.get(k);
+    if ([mb, mo, mt].some((m) => m?.["deleted"] === true) || mb !== void 0 && (mo === void 0 || mt === void 0)) {
+      out.push({ ...mo ?? mt ?? mb, body: "", deleted: true });
+    } else if (mo !== void 0 && mt !== void 0) {
+      out.push(merge3(mb, mo, mt, id, `${here}.messages[${k}]`, ctx));
+    } else {
+      out.push(mo ?? mt);
+    }
+  }
+  const ts = (m) => String(m["ts"] ?? "");
+  return out.sort((x, y) => ts(x).localeCompare(ts(y)) || String(x["author"] ?? "").localeCompare(String(y["author"] ?? "")));
+}
 function strategyForType(decl) {
   switch (decl.type) {
     case "flags":
@@ -883,6 +965,6 @@ function orphanedEntries(data, exists) {
   return out;
 }
 
-export { ATOMIC, HOSTS, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, SCALAR_TYPES, SET, UNRESOLVED_KEY, VALUE_TYPES, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, entryProblems, extensionDataStrategy, keyedBy, manifestProblems, mapOf, markUnresolved, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };
+export { ATOMIC, COMMENTS, HOSTS, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, SCALAR_TYPES, SET, UNRESOLVED_KEY, VALUE_TYPES, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };
 //# sourceMappingURL=extensions.js.map
 //# sourceMappingURL=extensions.js.map