@bakers-build/addon-name-refs 0.1.2-next.93 → 0.2.0

package/dist/src/index.js

@@ -1,5 +1,5 @@
 // BB-403: resolve entity NAMES into the relationship that references them, so
-// a skill writes `--label_names work:code` or `--environment_names staging`
+// a skill writes `--type_names bug` or `--environment_names staging`
 // instead of searching the collection, pulling a UUID out with jq, and
 // hand-building the linkage.
 //
@@ -19,28 +19,31 @@
 // committed config already has is unchanged. It contributes no preset
 // accumulator, so it is a plain sibling edge in `PERMITTED_SIBLINGS`.
 //
-// Adding a target is one RESOLVERS entry. The one thing that differs between
-// them is whether a name is unique on its own: `bb_term` names are, so a name
-// identifies a term outright. `bb_environment` names are unique only WITHIN A
-// PROJECT (BbEnvironmentUniquePerProject), so the same name legitimately
-// exists several times and picking one would be luck rather than resolution —
-// hence `scopeField`, and the narrowing it drives.
+// Adding a target is one RESOLVERS entry. Both kinds of name are unique only
+// within a parent. `bb_environment` names are unique WITHIN A PROJECT
+// (BbEnvironmentUniquePerProject), which the write carries directly — hence
+// `scopeField`. `bb_term` names (ticket type, recipe, label) are unique within
+// the ticket's WORKSPACE, reached through `scopeChain`; a term name missing
+// there is created there, so an agent never needs a lead to add vocabulary.
+/** A term resolver: workspace-scoped, created on first use. */
+const term = (field, noun, relationship, vid, single) => ({
+    field,
+    noun,
+    relationship,
+    type: `bb_term--${vid}`,
+    path: `bb_term/${vid}`,
+    title: `${noun[0]?.toUpperCase()}${noun.slice(1)} names (comma-separated ${vid} term names` +
+        `${single ? '; one name' : ''}; resolved in the ticket's workspace and ` +
+        'created there when missing, on the live write)',
+    scopeField: 'workspace_id',
+    scopeChain: 'project_id.group_id.workspace_id',
+    single,
+});
+const WORKSPACE_TYPE = 'bb_workspace--bb_workspace';
 const RESOLVERS = [
-    {
-        field: 'label_names',
-        noun: 'label',
-        relationship: 'labels',
-        type: 'bb_term--bb_labels',
-        path: 'bb_term/bb_labels',
-        title: 'Label names (comma-separated bb_labels names; ' +
-            'unique only within workspace_id — resolved to labels on the live write)',
-        // BB-531: bb_term names are unique within (workspace_id, vid), so the
-        // same name legitimately exists in several workspaces and a bare index
-        // would silently pick one. The workspace is reached from the payload via
-        // the chain project_id → group_id → workspace_id.
-        scopeField: 'workspace_id',
-        scopeChain: 'project_id.group_id.workspace_id',
-    },
+    term('type_names', 'ticket type', 'ticket_type', 'type', true),
+    term('recipe_names', 'recipe', 'recipe', 'recipe', true),
+    term('label_names', 'label', 'labels', 'label', false),
     {
         field: 'environment_names',
         noun: 'environment',
@@ -65,7 +68,7 @@ const MAX_PAGES = 10;
 /** Rows this resolver will walk before it refuses to resolve at all. */
 const MAX_ROWS = PAGE_LIMIT * MAX_PAGES;
 /**
- * How many known names an error may list. `bb_labels` is small; a future
+ * How many known names an error may list. A term bundle is small; a future
  * target need not be, and an error nobody can read is an error nobody reads.
  */
 const NAME_LIST_CAP = 20;
@@ -185,12 +188,12 @@ async function resolveChainScope(req, ctx, ref, data) {
 }
 /**
  * Does this operation schema declare this resolver's relationship over its
- * target type? Only the multi-valued (`items`) shape is recognised: both
- * targets are unlimited-cardinality, and the merge below writes an array, so
- * matching a single-valued relationship here would produce an invalid payload.
+ * target type, in the cardinality the resolver writes? A single resolver
+ * writes one object, a multi-valued one an array; matching the other shape
+ * would produce an invalid payload.
  */
 function declares(schema, ref) {
-    const targets = at(schema, 'properties', 'data', 'properties', 'relationships', 'properties', ref.relationship, 'properties', 'data', 'items', 'properties', 'type', 'enum');
+    const targets = at(schema, 'properties', 'data', 'properties', 'relationships', 'properties', ref.relationship, 'properties', 'data', ...(ref.single ? [] : ['items']), 'properties', 'type', 'enum');
     return Array.isArray(targets) && targets.includes(ref.type);
 }
 /** `/jsonapi`, however the config spelled it — with, without, or with a trailing slash. */
@@ -210,10 +213,19 @@ function normalisePrefix(raw) {
  * of handing an HTML error page to `JSON.parse`.
  */
 async function fetchDoc(ctx, url, what) {
+    return sendDoc(ctx, { method: 'GET', url }, `could not read ${what}`);
+}
+/** Send one JSON:API request and parse its document, or fail by name. */
+async function sendDoc(ctx, req, failure) {
+    const url = req.url;
     const res = await ctx.http.send(await ctx.auth.apply({
-        method: 'GET',
-        url,
-        headers: { Accept: 'application/vnd.api+json' },
+        ...req,
+        headers: {
+            Accept: 'application/vnd.api+json',
+            ...(req.body === undefined
+                ? {}
+                : { 'Content-Type': 'application/vnd.api+json' }),
+        },
     }));
     if (res.status < 200 || res.status >= 300) {
         const expiry = res.status === 401 || res.status === 403
@@ -221,15 +233,37 @@ async function fetchDoc(ctx, url, what) {
                 'and, unlike dropsh’s JSON:API client, cannot renew one, so an expired ' +
                 'token surfaces here instead of being refreshed. Re-authenticate and retry.'
             : '';
-        throw new Error(`could not read ${what}: HTTP ${res.status} from ${url}.${expiry}`);
+        throw new Error(`${failure}: HTTP ${res.status} from ${url}.${expiry}`);
     }
     try {
         return JSON.parse(res.body);
     }
     catch (cause) {
-        throw new Error(`could not read ${what}: ${url} answered ${res.status} but not JSON (${String(cause)})`);
+        throw new Error(`${failure}: ${url} answered ${res.status} but not JSON (${String(cause)})`);
     }
 }
+/** Create a term in a workspace and return its uuid. */
+async function createTerm(ctx, ref, name, workspaceId) {
+    const prefix = normalisePrefix(ctx.jsonapiPrefix);
+    const doc = await sendDoc(ctx, {
+        method: 'POST',
+        url: `${ctx.baseUrl.replace(/\/+$/, '')}${prefix}/${ref.path}`,
+        body: JSON.stringify({
+            data: {
+                type: ref.type,
+                attributes: { name },
+                relationships: {
+                    workspace_id: { data: { type: WORKSPACE_TYPE, id: workspaceId } },
+                },
+            },
+        }),
+    }, `could not create ${ref.noun} '${name}' in workspace '${workspaceId}'`);
+    const id = at(doc, 'data', 'id');
+    if (typeof id !== 'string') {
+        throw new Error(`could not create ${ref.noun} '${name}': the response carries no id`);
+    }
+    return id;
+}
 /**
  * The whole collection as name → candidates. One round trip regardless of how
  * many names were given, and it yields the known-names list the error needs.
@@ -289,15 +323,113 @@ function describe(candidates) {
         .map((c) => (c.scopeId === undefined ? c.id : `${c.id} (${c.scopeId})`))
         .join(', ');
 }
+/**
+ * One term name → its uuid in the ticket's workspace, created there when
+ * missing. Without a workspace (a create naming no project) nothing can be
+ * created and only an unambiguous existing name resolves.
+ */
+async function resolveTerm(ctx, ref, byName, name, workspaceId) {
+    const candidates = byName.get(name) ?? [];
+    if (workspaceId === undefined) {
+        const [only, ...rivals] = candidates;
+        if (only === undefined) {
+            throw new Error(`${ref.noun} name '${name}' does not exist in the ${ref.path} ` +
+                `vocabulary, and this write names no project_id whose workspace it ` +
+                `could be created in. Known names: ${knownNames(byName)}`);
+        }
+        if (rivals.length > 0) {
+            throw new Error(`${ref.noun} name '${name}' is ambiguous — ${candidates.length} ` +
+                `entries in ${ref.path} share it. Candidates: ${describe(candidates)}. ` +
+                `Pass the uuid directly on the ${ref.relationship} relationship instead.`);
+        }
+        return only.id;
+    }
+    const [match, ...extra] = candidates.filter((c) => c.scopeId === workspaceId);
+    if (extra.length > 0 && match !== undefined) {
+        throw new Error(`${ref.noun} name '${name}' is ambiguous even within workspace_id ` +
+            `'${workspaceId}': ${describe([match, ...extra])}. Pass the uuid ` +
+            `directly on the ${ref.relationship} relationship instead.`);
+    }
+    if (match !== undefined)
+        return match.id;
+    const id = await createTerm(ctx, ref, name, workspaceId);
+    byName.set(name, [...candidates, { id, scopeId: workspaceId }]);
+    return id;
+}
+/**
+ * One name → its uuid within the parent the write carries (`scopeField`),
+ * read off the entity under update when the payload omits it.
+ */
+async function resolveScoped(req, ctx, ref, data, byName, name, scopes) {
+    const candidates = byName.get(name) ?? [];
+    const [only, ...rivals] = candidates;
+    if (only === undefined) {
+        throw new Error(`${ref.noun} name '${name}' does not exist in the ${ref.path} ` +
+            `vocabulary. Known names: ${knownNames(byName)}`);
+    }
+    const scopeField = ref.scopeField;
+    if (scopeField === undefined) {
+        if (rivals.length > 0) {
+            throw new Error(`${ref.noun} name '${name}' is ambiguous — ${candidates.length} ` +
+                `entries in ${ref.path} share it. Candidates: ${describe(candidates)}. ` +
+                `Pass the uuid directly on the ${ref.relationship} relationship instead.`);
+        }
+        return only.id;
+    }
+    // A scoped resolver ALWAYS establishes a scope — including for a name that
+    // is unique across the whole collection today. Uniqueness is a property of
+    // the current rows, not of the name: `staging` is unique right up to the
+    // moment a second project creates one, and until then an unscoped write
+    // would attach another project's environment and report success. The scope
+    // the payload carries is free; otherwise it is read off the entity being
+    // updated (memoised: one read per write, however many names were given). A
+    // create has no entity yet, hence `undefined`.
+    let scopeId = relationshipId(data, scopeField);
+    if (scopeId === undefined) {
+        let pending = scopes.get(scopeField);
+        if (pending === undefined) {
+            pending =
+                ctx.operation === 'update'
+                    ? fetchScope(req, ctx, scopeField)
+                    : Promise.resolve(undefined);
+            scopes.set(scopeField, pending);
+        }
+        scopeId = await pending;
+    }
+    if (scopeId === undefined) {
+        throw new Error(rivals.length > 0
+            ? `${ref.noun} name '${name}' is ambiguous — ${candidates.length} ` +
+                `entries in ${ref.path} share it and the write carries no ` +
+                `${scopeField} to narrow them. Candidates: ${describe(candidates)}. ` +
+                `Pass the uuid directly on the ${ref.relationship} relationship instead.`
+            : `${ref.noun} name '${name}' cannot be resolved: ${ref.path} names are ` +
+                `unique only within ${scopeField}, and this write carries no ` +
+                `${scopeField} to narrow it — being the only '${name}' that exists ` +
+                `today does not make it this write's. Candidate: ${describe(candidates)}. ` +
+                `Name the ${scopeField}, or pass the uuid directly on the ` +
+                `${ref.relationship} relationship instead.`);
+    }
+    const [match, ...extra] = candidates.filter((c) => c.scopeId === scopeId);
+    if (match === undefined) {
+        const elsewhere = candidates.map((c) => c.scopeId ?? '(none)').join(', ');
+        throw new Error(`${ref.noun} name '${name}' does not exist in ${scopeField} ` +
+            `'${scopeId}'. It exists in: ${elsewhere}.`);
+    }
+    if (extra.length > 0) {
+        throw new Error(`${ref.noun} name '${name}' is ambiguous even within ${scopeField} ` +
+            `'${scopeId}': ${describe([match, ...extra])}. Pass the uuid directly ` +
+            `on the ${ref.relationship} relationship instead.`);
+    }
+    return match.id;
+}
 export function nameRefsPlugin() {
     // Per-instance, not module-level: one CLI invocation performs one write, so
     // these guard against a second lookup, and they keep tests isolated.
     const indexes = new Map();
     const scopes = new Map();
     /**
-     * Chain-scope resolutions, keyed by the resolver field (not by `scopeField`):
-     * several resolvers could share a scopeField but differ in their chain, and
-     * a chain resolution is a round trip we want to pay once per write.
+     * Chain-scope resolutions, keyed by the chain: the three term resolvers share
+     * one, and a chain resolution is a round trip we want to pay once per write.
      */
     const chainScopes = new Map();
     /**
@@ -381,6 +513,18 @@ export function nameRefsPlugin() {
                 ? { ...data.relationships }
                 : {};
             const declaredHere = offered.get(bundleKey(ctx.entityType, ctx.bundle));
+            const namesOf = (ref) => [
+                ...new Set(String(attributes[ref.field])
+                    .split(',')
+                    .map((name) => name.trim())
+                    .filter((name) => name.length > 0)),
+            ];
+            // Before any round trip: a single-valued field takes one name.
+            for (const ref of active) {
+                if (ref.single && namesOf(ref).length > 1) {
+                    throw new Error(`'${ref.field}' takes one name: ${ref.relationship} holds a single ${ref.noun}.`);
+                }
+            }
             for (const ref of active) {
                 // A name field on a bundle that has no such relationship. Reachable by
                 // a hand-built body or `--no-validate`, since the flag itself only
@@ -393,10 +537,7 @@ export function nameRefsPlugin() {
                         `Remove it, or write to a bundle that has ${ref.relationship}.`);
                 }
                 delete nextAttributes[ref.field];
-                const names = String(attributes[ref.field])
-                    .split(',')
-                    .map((name) => name.trim())
-                    .filter((name) => name.length > 0);
+                const names = namesOf(ref);
                 if (names.length === 0)
                     continue;
                 let index = indexes.get(ref.field);
@@ -405,120 +546,31 @@ export function nameRefsPlugin() {
                     indexes.set(ref.field, index);
                 }
                 const byName = await index;
-                const scopeField = ref.scopeField;
-                // The scope the payload already carries. Free — no round trip — so it
-                // narrows EVERY name, including an unambiguous one: a name that is
-                // unique across the whole collection can still belong to a different
-                // parent than the entity being written, and attaching it silently would
-                // be worse than the round trip we are saving. This shortcut only
-                // applies when the payload carries the SAME relationship the target's
-                // `scopeField` names; a chain resolver reaches the scope via a fetch
-                // and never gets a free read here.
-                const payloadScope = scopeField === undefined || ref.scopeChain !== undefined
-                    ? undefined
-                    : relationshipId(data, scopeField);
                 const resolved = [];
-                for (const name of names) {
-                    const candidates = byName.get(name) ?? [];
-                    const [only, ...rivals] = candidates;
-                    if (only === undefined) {
-                        throw new Error(`${ref.noun} name '${name}' does not exist in the ${ref.path} ` +
-                            `vocabulary. Known names: ${knownNames(byName)}`);
-                    }
-                    if (scopeField === undefined) {
-                        if (rivals.length > 0) {
-                            throw new Error(`${ref.noun} name '${name}' is ambiguous — ${candidates.length} ` +
-                                `entries in ${ref.path} share it. Candidates: ${describe(candidates)}. ` +
-                                `Pass the uuid directly on the ${ref.relationship} relationship instead.`);
-                        }
-                        resolved.push(only.id);
-                        continue;
+                if (ref.scopeChain !== undefined) {
+                    // A term always belongs to the ticket's workspace: one fetch walks
+                    // project → group → workspace, shared by all term fields of the write.
+                    let pending = chainScopes.get(ref.scopeChain);
+                    if (pending === undefined) {
+                        pending = resolveChainScope(req, ctx, ref, data);
+                        chainScopes.set(ref.scopeChain, pending);
                     }
-                    // A scoped resolver ALWAYS establishes a scope — including for a name
-                    // that is unique across the whole collection today. Uniqueness is a
-                    // property of the current rows, not of the name: `staging` is unique
-                    // right up to the moment a second project creates one, and until then
-                    // an unscoped write would attach another project's environment and
-                    // report success. A chain resolver reaches the scope via a single
-                    // fetch (project + group + workspace in one round trip); a direct
-                    // resolver reads the scope off the entity being updated (also
-                    // memoised: one read per write, however many names were given). A
-                    // create has no entity yet, hence `undefined`.
-                    //
-                    // A chain resolver fetches ONLY when there is something to narrow
-                    // (multiple candidates). A single candidate needs no workspace check
-                    // and skips the round trip — the unscoped-path fallback below
-                    // resolves it directly. That keeps a write with one label and a
-                    // `project_id` on the payload at one URL per resolver, matching the
-                    // pre-fix cost.
-                    let scopeId;
-                    if (ref.scopeChain !== undefined) {
-                        if (rivals.length > 0) {
-                            let pending = chainScopes.get(ref.field);
-                            if (pending === undefined) {
-                                pending = resolveChainScope(req, ctx, ref, data);
-                                chainScopes.set(ref.field, pending);
-                            }
-                            scopeId = await pending;
-                        }
+                    const workspaceId = await pending;
+                    for (const name of names) {
+                        resolved.push(await resolveTerm(ctx, ref, byName, name, workspaceId));
                     }
-                    else {
-                        scopeId = payloadScope;
-                        if (scopeId === undefined) {
-                            let pending = scopes.get(scopeField);
-                            if (pending === undefined) {
-                                pending =
-                                    ctx.operation === 'update'
-                                        ? fetchScope(req, ctx, scopeField)
-                                        : Promise.resolve(undefined);
-                                scopes.set(scopeField, pending);
-                            }
-                            scopeId = await pending;
-                        }
-                    }
-                    // No scope at all is a hard error for a direct resolver (an
-                    // environment name must belong to a project — never guess). A
-                    // chain resolver falls back to the unscoped path instead: when no
-                    // `project_id` can be derived, a single candidate resolves
-                    // (backward-compatible with pre-fix writes) and multiple
-                    // candidates raise the same "ambiguous" error an unscoped resolver
-                    // would, with the candidate workspaces named via `describe()`.
-                    if (scopeId === undefined) {
-                        if (ref.scopeChain !== undefined) {
-                            if (rivals.length > 0) {
-                                throw new Error(`${ref.noun} name '${name}' is ambiguous — ${candidates.length} ` +
-                                    `entries in ${ref.path} share it. Candidates: ${describe(candidates)}. ` +
-                                    `Pass the uuid directly on the ${ref.relationship} relationship instead.`);
-                            }
-                            resolved.push(only.id);
-                            continue;
-                        }
-                        throw new Error(rivals.length > 0
-                            ? `${ref.noun} name '${name}' is ambiguous — ${candidates.length} ` +
-                                `entries in ${ref.path} share it and the write carries no ` +
-                                `${scopeField} to narrow them. Candidates: ${describe(candidates)}. ` +
-                                `Pass the uuid directly on the ${ref.relationship} relationship instead.`
-                            : `${ref.noun} name '${name}' cannot be resolved: ${ref.path} names are ` +
-                                `unique only within ${scopeField}, and this write carries no ` +
-                                `${scopeField} to narrow it — being the only '${name}' that exists ` +
-                                `today does not make it this write's. Candidate: ${describe(candidates)}. ` +
-                                `Name the ${scopeField}, or pass the uuid directly on the ` +
-                                `${ref.relationship} relationship instead.`);
-                    }
-                    const [match, ...extra] = candidates.filter((c) => c.scopeId === scopeId);
-                    if (match === undefined) {
-                        const elsewhere = candidates
-                            .map((c) => c.scopeId ?? '(none)')
-                            .join(', ');
-                        throw new Error(`${ref.noun} name '${name}' does not exist in ${scopeField} ` +
-                            `'${scopeId}'. It exists in: ${elsewhere}.`);
+                }
+                else {
+                    for (const name of names) {
+                        resolved.push(await resolveScoped(req, ctx, ref, data, byName, name, scopes));
                     }
-                    if (extra.length > 0) {
-                        throw new Error(`${ref.noun} name '${name}' is ambiguous even within ${scopeField} ` +
-                            `'${scopeId}': ${describe([match, ...extra])}. Pass the uuid directly ` +
-                            `on the ${ref.relationship} relationship instead.`);
+                }
+                if (ref.single) {
+                    const [id] = resolved;
+                    if (id !== undefined) {
+                        relationships[ref.relationship] = { data: { type: ref.type, id } };
                     }
-                    resolved.push(match.id);
+                    continue;
                 }
                 const current = at(relationships, ref.relationship, 'data');
                 const existing = Array.isArray(current)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakers-build/addon-name-refs",
-  "version": "0.1.2-next.93",
+  "version": "0.2.0",
   "description": "bakers.build connection addon: resolve entity NAMES (--label_names, --environment_names) into the relationships that reference them, on the live write, via dropsh's extendOperationSchema and alterRequest hooks.",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,6 @@
     "dropsh": "^0.7.5"
   },
   "peerDependencies": {
-    "@bakers-build/core": "^0.1.2-next.93"
+    "@bakers-build/core": "^0.2.0"
   }
 }