@meantjs/profile 0.0.0-stage → 0.1.0

package/src/tags.mjs

@@ -0,0 +1,90 @@
+/**
+ * Tag storage and position enumeration. TagIndex, `positions` are moved verbatim from scripts/validate.mjs;
+ * LayeredTags is the multi-profile merge of spec section 8.
+ */
+import { edgeKey } from "./address.mjs";
+
+// ---------------------------------------------------------------- tag index
+
+/** Tags reachable at a position: node tags < edge tags < method-position tags (spec §8). */
+export class TagIndex {
+  constructor() { this.byKey = new Map(); }
+  add(key, tag, entry) {
+    if (!this.byKey.has(key)) this.byKey.set(key, {});
+    this.byKey.get(key)[tag] = entry;
+  }
+  at({ key, parent, ref }, iface) {
+    const nodeTags = this.byKey.get(`n:${iface.unwrapOpt(ref).ref}`);
+    const edgeTags = parent ? this.byKey.get(edgeKey(parent)) : undefined;
+    const posTags = this.byKey.get(key);
+    if (!nodeTags && !edgeTags && !posTags) return undefined;
+    return { ...(nodeTags ?? {}), ...(edgeTags ?? {}), ...(posTags ?? {}) };
+  }
+}
+
+/** Every value position of a method side, with canonical key, parent edge and display address. */
+export function* positions(iface, methodName, side, maxDepth = 8) {
+  const m = iface.methods.get(methodName);
+  const tuple = side === "args" ? m.args : m.results;
+  const sideKey = side === "args" ? "arg" : "res";
+  function* rec(ref, parent, ids, display, index, depth, seen) {
+    const key = `m:${methodName}|${sideKey}|${index}|${ids.join("/")}`;
+    const { ref: r } = iface.unwrapOpt(ref);
+    const cyclic = seen.has(r) || depth >= maxDepth;
+    yield { ref, parent, key, display, cyclic };
+    if (cyclic) return;
+    const n = iface.node(r);
+    const next = new Set(seen).add(r);
+    if (n.kind === "record" || n.kind === "variant") {
+      for (const f of n.fields) {
+        yield* rec(f.type, { container: r, kind: n.kind, id: f.id }, [...ids, String(f.id)], `${display}.${iface.fieldName(r, f.id)}`, index, depth + 1, next);
+      }
+    } else if (n.kind === "vec" && !iface.isBlob(r)) {
+      yield* rec(n.inner, { container: r, kind: "vec" }, [...ids, "[]"], `${display}[]`, index, depth + 1, next);
+    }
+  }
+  for (let i = 0; i < tuple.length; i++) {
+    yield* rec(tuple[i], null, [], `${methodName}${side === "args" ? "" : "->"}(${i})`, i, 0, new Set());
+  }
+}
+
+/**
+ * Spec section 8, merging. One TagIndex per layer, highest precedence first (author, third_party, pack, inferred).
+ *   - Within a layer: a method-position tag beats a `type:` edge tag beats a whole-declaration tag (TagIndex.at).
+ *   - Across layers: the first layer that has the tag at the position wins; the same tag in lower layers is overridden.
+ * Merging is per tag per position: other tags on the position are kept.
+ */
+export class LayeredTags {
+  /** @param layers Array<{ name: string, index: TagIndex }> */
+  constructor(layers) { this.layers = layers; }
+
+  static #first(parts) {
+    let out;
+    for (const t of parts) {
+      if (!t) continue;
+      out ??= {};
+      for (const k of Object.keys(t)) if (!(k in out)) out[k] = t[k];
+    }
+    return out;
+  }
+
+  /** Effective tags at a value position (undefined when none). */
+  at(pos, iface) { return LayeredTags.#first(this.layers.map((l) => l.index.at(pos, iface))); }
+
+  /** Effective tags on a method (always an object). */
+  methodTags(name) { return LayeredTags.#first(this.layers.map((l) => l.index.byKey.get(`m:${name}`))) ?? {}; }
+
+  /** Every candidate per tag at a value position, highest layer first: { tag -> [entry, ...] }. */
+  candidates(pos, iface) { return this.#collect(this.layers.map((l) => l.index.at(pos, iface))); }
+
+  candidatesAtMethod(name) { return this.#collect(this.layers.map((l) => l.index.byKey.get(`m:${name}`))); }
+
+  #collect(parts) {
+    const out = {};
+    for (const t of parts) {
+      if (!t) continue;
+      for (const [k, v] of Object.entries(t)) (out[k] ??= []).push(v);
+    }
+    return out;
+  }
+}

package/src/util.mjs

@@ -0,0 +1,16 @@
+import { sha256Hex } from "./sha256.mjs";
+
+// The pure label helpers live in idl.mjs, so that the address entry loads nothing else.
+export { U32_MAX, idlHash } from "./idl.mjs";
+
+/** RFC 8785 (JCS) canonical JSON for the value shapes profiles use. */
+export function jcs(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(jcs).join(",")}]`;
+  const keys = Object.keys(v).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${jcs(v[k])}`).join(",")}}`;
+}
+
+export function profileId(doc) {
+  return `candid-profile:v0:sha256:${sha256Hex(jcs(doc))}`;
+}

package/src/validate.mjs

@@ -0,0 +1,49 @@
+/**
+ * Single-profile validation: the behavior of the original scripts/validate.mjs, as a library call.
+ * A pack is checked against its own `binds.requires` fragment; a canister profile against the given interface.
+ */
+import { profileId } from "./util.mjs";
+import { compileInterface } from "./compile.mjs";
+import { analyzeProfiles } from "./analyze.mjs";
+import { resolvedForm } from "./resolved.mjs";
+import { schemaDiagnostics } from "./schema-core.mjs";
+
+/**
+ * @param doc            the parsed profile
+ * @param opts.validateSchema  from createSchemaValidator()
+ * @param opts.did       Candid source text of the interface (canister profiles; packs use binds.requires)
+ * @param opts.didLabel  how E_CANDID names the .did (a path)
+ * @param opts.resolved  also return the resolved form
+ * @returns { ok, profile_id?, interface_id?, methods?, annotations?, diagnostics, resolved? }
+ */
+export async function validateProfile(doc, opts) {
+  const diagnostics = [];
+  const diag = (severity, code, at, message) => diagnostics.push({ severity, code, at, message });
+
+  if (!opts.validateSchema(doc)) {
+    diagnostics.push(...schemaDiagnostics(opts.validateSchema));
+    return { ok: false, diagnostics };
+  }
+  const pid = profileId(doc);
+
+  let didSource;
+  if (doc.kind === "pack") didSource = doc.binds.requires;
+  else if (opts.did !== undefined && opts.did !== null) didSource = opts.did;
+  else {
+    diag("warning", "W_NO_INTERFACE", "", "canister profile without --did: semantic checks skipped");
+    return { ok: true, profile_id: pid, diagnostics };
+  }
+  const compiled = await compileInterface(didSource);
+  if (compiled.failure) {
+    for (const d of compiled.failure) diag("error", "E_CANDID", doc.kind === "pack" ? "binds.requires" : opts.didLabel, `${d.code}: ${d.message}`);
+    return { ok: false, profile_id: pid, diagnostics };
+  }
+  const { iface } = compiled;
+  const rebinding = doc.kind === "canister" && doc.binds.interface_id !== iface.interfaceId;
+  const analysis = analyzeProfiles(iface, [{ doc, pid, rebinding, apply: false }], { attribute: false });
+
+  const ok = !analysis.diagnostics.some((d) => d.severity === "error");
+  const result = { ok, profile_id: pid, interface_id: iface.interfaceId, methods: iface.methods.size, annotations: doc.annotations.length, diagnostics: analysis.diagnostics };
+  if (opts.resolved) result.resolved = resolvedForm(iface, [{ doc, pid }], analysis.layered, analysis.diagnostics);
+  return result;
+}