drupal-mcp-connector 2.19.1 → 2.20.0

package/src/tools/reports-content.js

@@ -15,7 +15,9 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
-import { collectEntities, fieldValue, daysSince } from "../lib/reports-support.js";
+import {
+  collectEntities, fieldValue, fieldPresence, isEmptyFieldValue, requestedFieldNames, FIELDS_NOT_VISIBLE_NOTE, daysSince,
+} from "../lib/reports-support.js";
 import { bodyHtml, extractAnchors, classifyLink, normalizePath } from "../lib/audit-support.js";
 import {
   assertDraftLangcode, isMissingTranslationEndpoint, readTranslationInventory, supportsSentinelDraft,
@@ -554,7 +556,13 @@ const DEFAULT_META_FIELDS = ["field_meta_tags", "field_metatag", "metatag", "fie
  * Report structured-meta (SEO) coverage for a content type: how many sampled
  * nodes populate each meta field (metatag module, meta description, etc.).
  * Complements drupal_report_seo_audit's heuristic checks with explicit
- * per-field coverage.
+ * per-field coverage. Reads scalar and relationship fields.
+ *
+ * An absent key is not an empty value (#341). A field whose key is absent from
+ * every sampled node has `present: false` and `coverage: null` (unknown, not
+ * 0); when the caller named it, it is also listed in `notVisible`. When none of
+ * the checked fields is visible on any node the report flags no node, because
+ * JSON:API leaves a field the account may not view out of the response.
  *
  * @param {object} args - { site?, type?, fields?, sampleSize? }.
  * @returns {Promise<object>} Per-field coverage and nodes missing all meta.
@@ -565,7 +573,9 @@ async function seoMetaCoverage({ site: siteName, type, fields, sampleSize = 100
   assertReadAllowed(sec, "node", type);
   const backend = await resolveBackend(site);
   const contentType = type || "article";
-  const metaFields = fields && fields.length ? fields : DEFAULT_META_FIELDS;
+  const named = requestedFieldNames(fields);
+  const requested = named.length > 0;
+  const metaFields = requested ? named : DEFAULT_META_FIELDS;
   const nodes = await collectEntities(
     backend,
     { entityType: "node", bundle: contentType, sort: [{ field: "changed", dir: "desc" }] },
@@ -578,13 +588,24 @@ async function seoMetaCoverage({ site: siteName, type, fields, sampleSize = 100
     let any = false;
     for (const f of metaFields) {
       const stat = coverage.get(f);
-      const v = fieldValue(n, [f]);
-      if (v !== undefined) stat.present = true;
-      if (!isEmpty(v)) { stat.populated++; any = true; }
+      const { present, value } = fieldPresence(n, f);
+      if (present) stat.present = true;
+      if (present && !isEmptyFieldValue(value)) { stat.populated++; any = true; }
     }
     if (!any) missingAll.push({ id: n.id, title: n.title, path: n.url });
   }
 
+  const anyVisible = metaFields.some((f) => coverage.get(f).present);
+  const unknown = nodes.length > 0 && !anyVisible;
+  const notVisible = metaFields.filter((f) => !coverage.get(f).present);
+  const notes = [];
+  if (unknown) {
+    notes.push(
+      "None of the checked meta fields is present on any sampled node (the keys are missing, not empty). " +
+      "They may be denied to this account or not exist on this content type, so no node was counted as missing meta."
+    );
+  }
+
   return {
     contentType,
     scanned: nodes.length,
@@ -594,30 +615,17 @@ async function seoMetaCoverage({ site: siteName, type, fields, sampleSize = 100
       return [f, {
         present: stat.present,
         populated: stat.populated,
-        coverage: nodes.length ? Number((stat.populated / nodes.length).toFixed(2)) : 0,
+        coverage: stat.present ? Number((stat.populated / nodes.length).toFixed(2)) : (nodes.length ? null : 0),
       }];
     })),
-    nodesMissingAllMeta: missingAll.length,
-    findings: missingAll,
+    ...(requested && nodes.length ? { notVisible } : {}),
+    ...(requested && nodes.length && notVisible.length ? { notVisibleNote: FIELDS_NOT_VISIBLE_NOTE } : {}),
+    nodesMissingAllMeta: unknown ? null : missingAll.length,
+    ...(notes.length ? { note: notes.join(" ") } : {}),
+    findings: unknown ? [] : missingAll,
   };
 }
 
-/**
- * Whether a field value counts as empty (scalar, {value} object, array, ref).
- * @param {*} v Field value.
- * @returns {boolean}
- */
-function isEmpty(v) {
-  if (v === undefined || v === null || v === "") return true;
-  if (Array.isArray(v)) return v.length === 0;
-  if (typeof v === "object") {
-    if ("value" in v) return v.value === undefined || v.value === null || v.value === "";
-    if ("id" in v) return !v.id;
-    return Object.keys(v).length === 0;
-  }
-  return false;
-}
-
 // ---------------------------------------------------------------------------
 // Definitions & handlers
 // ---------------------------------------------------------------------------
@@ -714,7 +722,7 @@ export const definitions = [
   },
   {
     name: "drupal_report_seo_meta_coverage",
-    description: "Report structured-meta (SEO) coverage for a content type: how many sampled nodes populate each meta field (metatag, meta description). Complements drupal_report_seo_audit with explicit per-field coverage.",
+    description: "Report structured-meta (SEO) coverage for a content type: how many sampled nodes populate each meta field (metatag, meta description). Complements drupal_report_seo_audit with explicit per-field coverage. Reads scalar and entity-reference fields. A field absent from every sampled node has `present: false` and `coverage: null` (unknown, not 0), and is listed in `notVisible` when you named it. When none of the checked fields is visible, no node is flagged and `nodesMissingAllMeta` is null: JSON:API leaves out a field this account may not view.",
     inputSchema: {
       type: "object",
       properties: {

package/src/tools/reports-extra.js

@@ -13,7 +13,8 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertReadAllowed, assertEntityTypeAllowed } from "../lib/security.js";
-import { collectEntities, fieldValue } from "../lib/reports-support.js";
+import { collectEntities, fieldPresence } from "../lib/reports-support.js";
+import { httpStatusOf } from "../lib/error-status.js";
 
 /** Author base fields that only ever point at `user`. */
 const AUTHOR_BASE_FIELDS = new Set(["uid", "revision_uid"]);
@@ -41,17 +42,15 @@ function isEntityTypeDenied(sec, entityType) {
 /**
  * Classify a getEntity failure. Only a 404 (or an unaddressable ref) is an
  * orphan. Connector policy, Drupal 401/403, and other failures are
- * unverifiable — and must not share one reason.
+ * unverifiable — and must not share one reason. The response status decides
+ * (see `httpStatusOf`); a "404" in the path or the detail does not (#355).
  * @param {unknown} err
  * @returns {"missing"|"forbidden"|"failed"}
  */
-function classifyTargetError(err) {
-  const msg = String(err?.message || err || "");
-  const statusMatch = msg.match(/\bDrupal (\d{3})\b/i);
-  const status = statusMatch ? Number(statusMatch[1]) : NaN;
+export function classifyTargetError(err) {
+  const status = httpStatusOf(err);
   if (status === 404) return "missing";
   if (status === 401 || status === 403) return "forbidden";
-  if (/\b404\b/.test(msg) && !/\b40[13]\b/.test(msg)) return "missing";
   return "failed";
 }
 
@@ -77,24 +76,6 @@ function isEmptyValue(value) {
   return false;
 }
 
-/**
- * Read a field value from a canonical entity, looking in `fields` first and then
- * `relationships` (so a single `field` argument works for both scalar fields and
- * entity-reference fields).
- * @param {object} entity Canonical entity.
- * @param {string} field Field machine name.
- * @returns {{value: *, present: boolean}} The resolved value and whether the key existed at all.
- */
-function readField(entity, field) {
-  const fromField = fieldValue(entity, [field]);
-  if (fromField !== undefined) return { value: fromField, present: true };
-  const rels = new Map(Object.entries(entity.relationships ?? {}));
-  if (rels.has(field)) {
-    return { value: rels.get(field), present: true };
-  }
-  return { value: undefined, present: false };
-}
-
 /**
  * Flatten a relationship value into an array of { id, entityType, bundle } refs,
  * dropping null/empty entries.
@@ -158,6 +139,14 @@ async function unpublished({ site: siteName, type, limit = 50 }) {
  * Sampling-bounded: flags `approximate` when the scan hits the sample cap while
  * more results remain.
  *
+ * An absent key is not an empty value (#337). JSON:API leaves a field out of
+ * the resource when the account may not view it, and keeps the key with an
+ * empty value when the field is merely empty. When the key is absent from
+ * EVERY sampled entity the report cannot know whether any value is missing,
+ * so it returns `notVisible: true` with no findings instead of flagging every
+ * entity. When only some entities omit the key, each finding carries a
+ * `reason` of `empty` or `absent`. No extra request is made per entity.
+ *
  * @param {object} args - { site?, type?, field, sampleSize? }. `field` is required.
  * @returns {Promise<object>} Per-entity findings plus scan metadata.
  * @throws {Error} If no field is supplied.
@@ -176,24 +165,43 @@ async function missingField({ site: siteName, type, field, sampleSize = 100 }) {
     sampleSize
   );
   const findings = [];
+  let totalAbsent = 0;
   for (const e of entities) {
-    const { value } = readField(e, field);
-    if (isEmptyValue(value)) {
-      findings.push({ id: e.id, title: e.title, field, status: e.status ? "published" : "unpublished", path: e.url });
+    const { present, value } = fieldPresence(e, field);
+    if (!present) totalAbsent++;
+    if (!present || isEmptyValue(value)) {
+      findings.push({
+        id: e.id, title: e.title, field, reason: present ? "empty" : "absent",
+        status: e.status ? "published" : "unpublished", path: e.url,
+      });
     }
   }
   const approximate = entities.length >= sampleSize;
+  const notes = [];
+  if (approximate) notes.push("Result is sampling-bounded; more entities may exist beyond the sample cap.");
+  const base = { contentType, field, scanned: entities.length, sampled: entities.length, sampleSize, approximate };
+
+  if (entities.length > 0 && totalAbsent === entities.length) {
+    notes.unshift(
+      `"${field}" is absent from every sampled entity (the key is missing, not empty). ` +
+      "It may be denied to this account or not exist on this bundle, or the name may be wrong. " +
+      "Drupal leaves a field the account may not view out of the response with no marker, so this report cannot tell whether any value is missing. " +
+      "No entity was counted as missing the field."
+    );
+    return { ...base, notVisible: true, totalMissing: null, totalEmpty: 0, totalAbsent, note: notes.join(" "), findings: [] };
+  }
+  if (totalAbsent > 0) {
+    notes.push(
+      `${totalAbsent} sampled ${totalAbsent === 1 ? "entity omits" : "entities omit"} "${field}" entirely (reason "absent"). ` +
+      "Drupal leaves a field the account may not view out of the response, so those may be access-denied rather than empty."
+    );
+  }
   return {
-    contentType,
-    field,
-    scanned: entities.length,
-    sampled: entities.length,
-    sampleSize,
-    approximate,
+    ...base,
     totalMissing: findings.length,
-    note: approximate
-      ? "Result is sampling-bounded; more entities may exist beyond the sample cap."
-      : undefined,
+    totalEmpty: findings.length - totalAbsent,
+    totalAbsent,
+    note: notes.length ? notes.join(" ") : undefined,
     findings,
   };
 }
@@ -330,7 +338,7 @@ export const definitions = [
   },
   {
     name: "drupal_report_missing_field",
-    description: "Find entities of a content type where a given field is empty (e.g. a missing meta description, image, or summary). Works for scalar fields and entity-reference fields. Sampling-bounded — flags 'approximate' when the scan is capped.",
+    description: "Find entities of a content type where a given field is empty (e.g. a missing meta description, image, or summary). Works for scalar fields and entity-reference fields. Sampling-bounded — flags 'approximate' when the scan is capped. An absent field is not an empty one: JSON:API leaves out a field this account may not view. When the field is absent from every sampled entity the result is `notVisible: true` with no findings (the field may be denied to this account, not exist on the bundle, or be misspelled) instead of every entity counted as missing. Otherwise each finding has `reason` 'empty' (key present, no value) or 'absent' (key missing, possibly access-denied).",
     inputSchema: {
       type: "object", required: ["field"],
       properties: {

package/src/tools/reports.js

@@ -11,7 +11,7 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import { resolveSecurityConfig, assertReadAllowed } from "../lib/security.js";
-import { collectEntities, gatedReport, fieldValue, daysSince } from "../lib/reports-support.js";
+import { collectEntities, gatedReport, fieldValue, fieldPresence, isEmptyFieldValue, requestedFieldNames, FIELDS_NOT_VISIBLE_NOTE, daysSince } from "../lib/reports-support.js";
 import { fetchRenderedMetaDescriptions } from "../lib/metatag-audit.js";
 
 // ---------------------------------------------------------------------------
@@ -171,14 +171,28 @@ async function recentlyPublished({ site: siteName, type, limit = 20 }) {
   };
 }
 
+/** Field names checked when the caller names none. Guesses: a bundle rarely has all of them. */
+const DEFAULT_COMPLETENESS_FIELDS = ["body", "summary", "metaDescription", "field_meta_description", "image", "field_image", "tags", "field_tags"];
+
 /**
  * Field completeness: what % of sampled nodes have optional fields populated.
- * A field absent on every sampled node is treated as "not on this content
- * type" and dropped from the results rather than counted as empty.
+ * Reads scalar fields and relationship (entity-reference) fields; a
+ * relationship with no target is empty.
+ *
+ * An absent key is not an empty value (#341). JSON:API keeps the key of an
+ * empty field and leaves out a field the account may not view. A node that
+ * omits the key is counted as `absent` and stays out of the percentage. A
+ * field the caller named that is absent from EVERY sampled node is listed in
+ * `notVisible` instead of being scored; one of the tool's own default guesses
+ * in the same state is dropped. Nothing is claimed when no node was sampled.
+ *
+ * Sampling-bounded: `approximate` is true when the scan hits `sampleSize`.
  *
  * @param {object} args - { site?, type, fields?, sampleSize? }. `type` is
  *   required; `fields` defaults to common SEO/editorial field names.
- * @returns {Promise<object>} Per-field populated/empty counts and percentages.
+ * @returns {Promise<{contentType: string, sampleSize: number, approximate: boolean,
+ *   fields: Array<{field: string, populated: number, empty: number, absent: number, completenessPercent: ?number}>,
+ *   notVisible?: string[], notVisibleNote?: string, note?: string}>}
  * @throws {Error} If no content type is supplied.
  * @throws {SecurityError} If reading the content type is not permitted.
  */
@@ -188,40 +202,51 @@ async function fieldCompleteness({ site: siteName, type, fields, sampleSize = 10
   assertReadAllowed(sec, "node", type);
   if (!type) throw new Error("fieldCompleteness requires a content type.");
   const backend = await resolveBackend(site);
-  const fieldsToCheck = (fields && fields.length)
-    ? fields
-    : ["body", "summary", "metaDescription", "field_meta_description", "image", "field_image", "tags", "field_tags"];
+  const named = requestedFieldNames(fields);
+  const requested = named.length > 0;
+  const fieldsToCheck = requested ? named : DEFAULT_COMPLETENESS_FIELDS;
   const entities = await collectEntities(
     backend,
     { entityType: "node", bundle: type, filters: [{ field: "status", op: "eq", value: true }] },
     sampleSize
   );
-  const results = fieldsToCheck.map((field) => {
-    let populated = 0, empty = 0, missing = 0;
+  const rows = fieldsToCheck.map((field) => {
+    let populated = 0, empty = 0, absent = 0;
     for (const e of entities) {
-      const v = fieldValue(e, [field]);
-      if (v === undefined) {
-        missing++;
-      } else if (v === null || v === "" || (typeof v === "object" && !v?.value && !(Array.isArray(v) && v.length))) {
-        empty++;
-      } else {
-        populated++;
-      }
+      const { present, value } = fieldPresence(e, field);
+      if (!present) absent++;
+      else if (isEmptyFieldValue(value)) empty++;
+      else populated++;
     }
     const checked = populated + empty;
     return {
-      field,
-      populated,
-      empty,
-      notOnContentType: (missing === entities.length && entities.length > 0) ? true : undefined,
+      field, populated, empty, absent,
       completenessPercent: checked > 0 ? Math.round((populated / checked) * 100) : null,
     };
-  }).filter((r) => !r.notOnContentType);
+  });
+  const sampled = entities.length > 0;
+  const invisible = (row) => sampled && row.absent === entities.length;
+  const notVisible = rows.filter(invisible).map((row) => row.field);
+  const scored = rows.filter((row) => !invisible(row));
+
+  const approximate = entities.length >= sampleSize;
+  const notes = [];
+  if (!sampled) notes.push("No published nodes of this content type were sampled, so no field could be scored.");
+  if (approximate) notes.push("Result is sampling-bounded; more nodes may exist beyond the sample cap.");
+  if (scored.some((row) => row.absent > 0)) {
+    notes.push(
+      "Some sampled nodes omit a field entirely (`absent`). Drupal leaves a field the account may not view out of the response, " +
+      "so those may be access-denied rather than empty. They are not counted in completenessPercent."
+    );
+  }
   return {
     contentType: type,
     sampleSize: entities.length,
-    approximate: false,
-    fields: results.sort((a, b) => (a.completenessPercent ?? 0) - (b.completenessPercent ?? 0)),
+    approximate,
+    fields: scored.sort((a, b) => (a.completenessPercent ?? 0) - (b.completenessPercent ?? 0)),
+    ...(requested && sampled ? { notVisible } : {}),
+    ...(requested && notVisible.length ? { notVisibleNote: FIELDS_NOT_VISIBLE_NOTE } : {}),
+    note: notes.length ? notes.join(" ") : undefined,
   };
 }
 
@@ -583,7 +608,7 @@ export const definitions = [
   },
   {
     name: "drupal_report_field_completeness",
-    description: "Score how completely optional fields are filled in for a content type. Finds nodes missing summaries, images, meta descriptions, tags, etc.",
+    description: "Score how completely optional fields are filled in for a content type. Finds nodes missing summaries, images, meta descriptions, tags, etc. Reads scalar and entity-reference fields; a reference with no target is empty. Sampling-bounded — flags 'approximate' when the scan hits sampleSize. An absent field is not an empty one: JSON:API leaves out a field this account may not view. A node that omits the key is counted as `absent` and stays out of completenessPercent. A field you name that is absent from every sampled node is listed in `notVisible` and not scored (it may be denied to this account, not exist on the content type, or be misspelled). Default field guesses that are absent are dropped.",
     inputSchema: {
       type: "object", required: ["type"],
       properties: {

package/src/tools/scheduler.js

@@ -29,7 +29,7 @@ import { resolveSecurityConfig, assertWriteAllowed, redactCanonicalEntity } from
  * @param {Error} err - The error thrown by the backend write.
  * @returns {boolean}
  */
-function looksLikeUnknownField(err) {
+export function looksLikeUnknownField(err) {
   const msg = String(err?.message || err || "");
   return /unknown|not exist|no field|invalid field|unrecognized|publish_on|unpublish_on/i.test(msg);
 }

package/src/tools/structure.js

@@ -20,6 +20,7 @@ import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
 import { assertDraftLangcode } from "../lib/sentinel-draft.js";
+import { httpStatusOf } from "../lib/error-status.js";
 
 const MENU_LINK_TYPE = "menu_link_content";
 const BLOCK_TYPE = "block_content";
@@ -30,9 +31,18 @@ const BLOCK_TYPE = "block_content";
 // a transient path-validator/access-cache race (it warms during the first
 // attempt), so a single retry clears it. Prefer an `entity:node/<id>` target
 // over `internal:/<alias>` to avoid the alias-resolution step entirely.
-const INACCESSIBLE_PATH_RE = /\b422\b[\s\S]*inaccessible/i;
+const INACCESSIBLE_PATH_RE = /inaccessible/i;
 const MENU_LINK_RETRY_DELAY_MS = 250;
 
+/**
+ * Whether an error is the transient "422 path inaccessible" menu-link race.
+ * @param {unknown} err The error thrown by the backend write.
+ * @returns {boolean}
+ */
+export function isInaccessiblePathError(err) {
+  return httpStatusOf(err) === 422 && INACCESSIBLE_PATH_RE.test(String(err?.message));
+}
+
 /**
  * Resolve after `ms` milliseconds.
  * @param {number} ms Delay in milliseconds.
@@ -52,7 +62,7 @@ async function writeMenuLinkWithRetry(fn) {
   try {
     return await fn();
   } catch (err) {
-    if (!INACCESSIBLE_PATH_RE.test(String(err?.message))) throw err;
+    if (!isInaccessiblePathError(err)) throw err;
     await sleep(MENU_LINK_RETRY_DELAY_MS);
     return fn();
   }

package/src/tools/translations.js

@@ -40,6 +40,7 @@ import {
   supportsSentinelDraft,
 } from "../lib/sentinel-draft.js";
 import { mapTranslationRow } from "../lib/translation-rows.js";
+import { dryRunChecks, PREFLIGHT_SENTINEL_DRAFT } from "../lib/dry-run-checks.js";
 
 const LIST_NOTE =
   "Live languages are those on the default revision. Working languages are the " +
@@ -175,6 +176,9 @@ async function createTranslation({
     return {
       dryRun: true, operation: "create_translation", entityType, bundle: type, id,
       langcode: targetLang, attributes: drafted, ...(relationships ? { relationships } : {}),
+      // createTranslationDraft throws unless the site confirmed a non-saving
+      // preflight of this exact payload, so the claim holds when we get here.
+      ...dryRunChecks({ operation: "create_translation", preflight: PREFLIGHT_SENTINEL_DRAFT }),
     };
   }
 
@@ -244,7 +248,7 @@ export const definitions = [
         attributes:    { type: "object", description: "Translated field values keyed by Drupal machine name" },
         relationships: { type: "object", description: "JSON:API relationships. Use for image alt (same file UUID, meta.alt)." },
         revisionId:    { type: "string", description: "Paragraph revision id the host already pins. Required for Home-shaped non-default pins." },
-        dryRun:        { type: "boolean", description: "Validate without saving" },
+        dryRun:        { type: "boolean", description: "Validate without saving. Sentinel's non-saving translation preflight receives the real fields, applies them through field access and validates the entity. The result's `checks` block says what was checked." },
       },
     },
   },