@avocadostudio-ai/orchestrator-core 0.3.2 → 0.3.3

package/dist/checks/field-walk.js

@@ -0,0 +1,152 @@
+/*
+ * Flatten a page's block props into located, kind-tagged fields.
+ *
+ * Every rule in this directory reads the manifest to find what it cares about
+ * — an image, its alt text, a heading level — rather than naming a block type.
+ * That is not tidiness. A rule containing `Hero` is a rule that silently exempts
+ * every custom block an integrator registered, which is most of the blocks on
+ * the sites where this checker would earn its keep.
+ *
+ * Paths use the editable-target grammar (`cards[0].imageAlt`) so a finding can
+ * point at a field the property panel and the preview overlay already address,
+ * and so `proposedOps` can be written against the same string.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function definitionFor(manifest, type) {
+    return manifest.blocks.find((b) => b.type === type);
+}
+/**
+ * Which field set applies to one item of a polymorphic list.
+ *
+ * A discriminated list renders different fields per branch; using the merged
+ * union for every item would invent fields an item does not have, and a rule
+ * would then report a missing alt text on an item that has no image.
+ */
+function itemFieldsFor(list, item) {
+    const merged = (list.itemFields ?? {});
+    if (!list.discriminator || !list.itemFieldsByType || !isRecord(item))
+        return merged;
+    const branch = item[list.discriminator];
+    if (typeof branch !== "string")
+        return merged;
+    return list.itemFieldsByType[branch] ?? merged;
+}
+/** Longer than this and the panel would be showing a paragraph, not a name. */
+const BLOCK_LABEL_MAX = 48;
+/**
+ * What a reader would call this block: its first non-empty plain-text prop.
+ *
+ * Manifest-driven like everything else here — the first `text` field in
+ * declaration order is a block's heading on every built-in block and on every
+ * custom one we have seen, and asking for `props.title` by name would find
+ * nothing on a block that calls it `headline`.
+ *
+ * `richtext` is deliberately excluded: a body is not a name, and the first 48
+ * characters of one reads as a truncated sentence rather than a label.
+ */
+function labelForBlock(definition, props) {
+    for (const [key, meta] of Object.entries(definition.fields ?? {})) {
+        if (meta.kind !== "text")
+            continue;
+        const value = props[key];
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed)
+            continue;
+        return trimmed.length > BLOCK_LABEL_MAX ? `${trimmed.slice(0, BLOCK_LABEL_MAX - 1)}…` : trimmed;
+    }
+    return undefined;
+}
+function entriesForBlock(block, definition) {
+    if (!definition)
+        return [];
+    const props = isRecord(block.props) ? block.props : {};
+    const out = [];
+    const blockLabel = labelForBlock(definition, props);
+    const located = blockLabel ? { blockLabel } : {};
+    for (const [key, meta] of Object.entries(definition.fields ?? {})) {
+        out.push({
+            blockId: block.id,
+            blockType: block.type,
+            ...located,
+            path: key,
+            kind: meta.kind,
+            ...(meta.label ? { label: meta.label } : {}),
+            value: props[key],
+            container: ""
+        });
+    }
+    for (const [key, list] of Object.entries(definition.listFields ?? {})) {
+        const items = props[key];
+        if (!Array.isArray(items))
+            continue;
+        items.forEach((item, index) => {
+            const container = `${key}[${index}]`;
+            for (const [itemKey, meta] of Object.entries(itemFieldsFor(list, item))) {
+                out.push({
+                    blockId: block.id,
+                    blockType: block.type,
+                    ...located,
+                    path: `${container}.${itemKey}`,
+                    kind: meta.kind,
+                    ...(meta.label ? { label: meta.label } : {}),
+                    value: isRecord(item) ? item[itemKey] : undefined,
+                    container
+                });
+            }
+        });
+    }
+    return out;
+}
+export function walkPageFields(page, manifest) {
+    return page.blocks.flatMap((block) => entriesForBlock(block, definitionFor(manifest, block.type)));
+}
+/**
+ * Readable text inside a field value.
+ *
+ * A `text` field is a string. A `richtext` field is a ProseMirror document, or
+ * markdown, or — for a custom block registered with a loose schema — something
+ * else entirely. Collecting every `text` string in the tree handles all three
+ * without the caller having to know which it got, and returns "" for a shape
+ * this does not recognise rather than guessing.
+ */
+export function fieldText(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value.map(fieldText).filter(Boolean).join(" ");
+    if (isRecord(value)) {
+        const parts = [];
+        if (typeof value.text === "string")
+            parts.push(value.text);
+        if (Array.isArray(value.content))
+            parts.push(fieldText(value.content));
+        return parts.join(" ");
+    }
+    return "";
+}
+/**
+ * The page's fields, split per block, in block order.
+ *
+ * Paths and containers are *block-relative* — every block with an image has a
+ * field at `imageUrl`, every block with a list has a `cards[0]` — so any rule
+ * that indexes fields by path or container has to do it one block at a time. A
+ * page-wide index of either silently pairs one block's image with another
+ * block's alt text, which is a false negative on the page that has two heroes
+ * and a false positive with the wrong block in its evidence on the page that
+ * has two of anything else.
+ */
+export function groupByBlock(fields) {
+    const byBlock = new Map();
+    for (const field of fields) {
+        const list = byBlock.get(field.blockId);
+        if (list)
+            list.push(field);
+        else
+            byBlock.set(field.blockId, [field]);
+    }
+    return byBlock;
+}

package/dist/checks/index.d.ts

@@ -0,0 +1,5 @@
+export { runChecksForSession, scheduleChecksAfterApply, scheduleChecksAfterPublish, cancelScheduledChecks } from "./session-runner.ts";
+export { runDraftChecks, fingerprintFor, type RunChecksArgs } from "./run-checks.ts";
+export { DRAFT_RULES } from "./rules-draft.ts";
+export { walkPageFields, fieldText, groupByBlock } from "./field-walk.ts";
+export type { CheckRule, CheckContext, RuleFinding, FieldEntry, SiteView } from "./types.ts";

package/dist/checks/index.js

@@ -0,0 +1,4 @@
+export { runChecksForSession, scheduleChecksAfterApply, scheduleChecksAfterPublish, cancelScheduledChecks } from "./session-runner.js";
+export { runDraftChecks, fingerprintFor } from "./run-checks.js";
+export { DRAFT_RULES } from "./rules-draft.js";
+export { walkPageFields, fieldText, groupByBlock } from "./field-walk.js";

package/dist/checks/page-weight.d.ts

@@ -0,0 +1,22 @@
+import { type SiteConfig } from "@avocadostudio-ai/shared";
+import type { FieldEntry, SiteView } from "./types.ts";
+export type PageWeight = {
+    slug: string;
+    /** 0–1. Only meaningful as an ordering; the absolute value is not a quantity. */
+    weight: number;
+    /** Editorial inbound links, excluding site chrome and self-links. */
+    inbound: number;
+    /** Clicks from `/` over editorial links and named nav. Null when unreached. */
+    depth: number | null;
+    /** Named in `navLabels`/`navGroups`, or linked from nearly every page. */
+    named: boolean;
+    isHome: boolean;
+    /** Nothing on the site links here and nobody named it. See `named` below. */
+    isUnlinked: boolean;
+};
+export declare function computePageWeights(args: {
+    /** Every page on the site, not only the ones being scanned. */
+    pages: SiteView["pages"];
+    fieldsBySlug: Map<string, FieldEntry[]>;
+    config: SiteConfig;
+}): Map<string, PageWeight>;

package/dist/checks/page-weight.js

@@ -0,0 +1,200 @@
+import { resolveLink } from "@avocadostudio-ai/shared";
+/*
+ * How much a page matters, independently of what is wrong with it.
+ *
+ * The checker has always had severity — *how broken* — and no answer at all to
+ * *how much it matters*, so the panel could only be ordered by the one axis a
+ * reader does not have. On the live session that produced a list whose largest
+ * single source of findings was a test page, with the home page third.
+ *
+ * Nothing here needs analytics. A site states what it thinks is important in
+ * the pages it links to and the pages it names in its nav. This reads both.
+ * When traffic data arrives it replaces `weight` with a measured share and
+ * everything downstream is unchanged — which is why this returns one number per
+ * slug rather than exposing its inputs to the rules.
+ */
+/**
+ * The four contributions, summed to 1. Named so the ordering can be argued
+ * with, and deliberately coarse: this is a sort key, not a measurement, and
+ * every extra decimal place is a claim the inputs cannot support.
+ */
+const CONTRIBUTION = {
+    /** Every routed page is a real page someone can land on. */
+    base: 0.25,
+    /** Editorial links from elsewhere on the site — the strongest free signal. */
+    inbound: 0.45,
+    /** Named by hand in the site's nav config. */
+    named: 0.15,
+    /** Clicks from the home page over those links. */
+    depth: 0.15
+};
+/**
+ * Four inbound links and a fifth tells you nothing new. Without a ceiling this
+ * is really a page-count term, and the biggest site wins every time.
+ */
+const INBOUND_SATURATION = 4;
+/**
+ * A link that appears on this fraction of the site is chrome — a footer, a
+ * header, a card grid repeated on every page — not an editorial link.
+ *
+ * Without it the term inverts: put a page in the footer and it collects an
+ * inbound link from all 45 pages, so *every* footer-linked page saturates and
+ * inbound stops discriminating exactly where a real site leans on it most.
+ * Chrome still counts, but as a named page, which is what it is.
+ */
+const CHROME_LINK_FRACTION = 0.8;
+/** The home page is the home page. No combination of the terms should outrank it. */
+const HOME_WEIGHT = 1;
+const HOME_SLUG = "/";
+function depthScore(depth) {
+    if (depth === null)
+        return 0;
+    if (depth <= 0)
+        return 1;
+    if (depth === 1)
+        return 0.7;
+    if (depth === 2)
+        return 0.4;
+    if (depth === 3)
+        return 0.2;
+    return 0;
+}
+/**
+ * Slugs the site config names by hand.
+ *
+ * Read as *deliberately named*, never as *the pages in the nav* — and the
+ * distinction is the whole reason this comment exists. `buildNavItems` in
+ * site-sdk puts **every** draft slug in the header; `navLabels` only relabels
+ * them and `navGroups` only collapses them into dropdowns. So a page absent
+ * from both is still in the site's nav, one click from home.
+ *
+ * An earlier version read these maps as membership and floored anything outside
+ * them at 0.10 as an orphan — "reachable only by someone who already knows the
+ * URL", which is simply false here. On a site with no nav config, which is the
+ * ordinary case, that is every page but the home page, and burying real
+ * findings on real pages is a worse failure than the noise this ordering exists
+ * to fix.
+ *
+ * So a named page gets a small bonus for having been thought about, and an
+ * unnamed one is not accused of anything.
+ */
+function namedSlugs(config) {
+    const out = new Set();
+    for (const slug of Object.keys(config.navLabels ?? {}))
+        out.add(slug);
+    for (const children of Object.values(config.navGroups ?? {})) {
+        for (const slug of children)
+            out.add(slug);
+    }
+    return out;
+}
+/**
+ * Which pages link to which, from every link-ish field on the site.
+ *
+ * Resolution goes through `resolveLink` rather than a local `startsWith("/")`,
+ * for the reason that module was extracted: three places used to answer "is
+ * this a route, and does it exist" their own way and did not agree. It also
+ * matches a page by `meta.path`, so a locale-prefixed site's links land on the
+ * page they mean instead of counting as zero.
+ *
+ * Self-links are dropped — a page is not evidence of its own importance — and
+ * sources are a Set, because four links to `/pricing` in one block have told us
+ * one thing, not four.
+ */
+function buildLinkGraph(fieldsBySlug, pages) {
+    const sourcesByTarget = new Map();
+    for (const [slug, fields] of fieldsBySlug) {
+        for (const field of fields) {
+            if (field.kind !== "link" && field.kind !== "url")
+                continue;
+            const target = resolveLink(field.value, pages).page?.slug;
+            if (!target || target === slug)
+                continue;
+            const sources = sourcesByTarget.get(target);
+            if (sources)
+                sources.add(slug);
+            else
+                sourcesByTarget.set(target, new Set([slug]));
+        }
+    }
+    return sourcesByTarget;
+}
+/**
+ * Breadth-first from the home page over editorial links, plus a hop straight to
+ * anything named in the nav — a named page is one click from wherever you are.
+ *
+ * Returns an empty map for a site with no `/` at all, which a CMS-backed
+ * subtree legitimately is. Every page there scores on links alone.
+ */
+function depthsFromHome(slugs, sourcesByTarget, named) {
+    const outbound = new Map();
+    for (const [target, sources] of sourcesByTarget) {
+        for (const source of sources) {
+            const list = outbound.get(source);
+            if (list)
+                list.push(target);
+            else
+                outbound.set(source, [target]);
+        }
+    }
+    const depths = new Map();
+    if (!slugs.includes(HOME_SLUG))
+        return depths;
+    depths.set(HOME_SLUG, 0);
+    const queue = [HOME_SLUG];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const depth = depths.get(current);
+        const next = [...(outbound.get(current) ?? []), ...(current === HOME_SLUG ? named : [])];
+        for (const target of next) {
+            if (depths.has(target))
+                continue;
+            depths.set(target, depth + 1);
+            queue.push(target);
+        }
+    }
+    return depths;
+}
+export function computePageWeights(args) {
+    const { pages, fieldsBySlug, config } = args;
+    const slugs = pages.map((p) => p.slug);
+    const options = pages.map((p) => ({
+        slug: p.slug,
+        ...(p.meta?.path ? { path: p.meta.path } : {}),
+        ...(p.title ? { title: p.title } : {})
+    }));
+    const sourcesByTarget = buildLinkGraph(fieldsBySlug, options);
+    // A link carried on nearly every page is chrome. Fold it into the named term
+    // rather than letting it saturate inbound for every page in the footer.
+    const chromeThreshold = Math.max(2, Math.ceil(slugs.length * CHROME_LINK_FRACTION));
+    const chrome = new Set();
+    for (const [target, sources] of sourcesByTarget) {
+        if (sources.size >= chromeThreshold)
+            chrome.add(target);
+    }
+    const named = new Set([...namedSlugs(config), ...chrome]);
+    const depths = depthsFromHome(slugs, sourcesByTarget, named);
+    const weights = new Map();
+    for (const slug of slugs) {
+        const isHome = slug === HOME_SLUG;
+        const isNamed = named.has(slug);
+        const inbound = chrome.has(slug) ? 0 : (sourcesByTarget.get(slug)?.size ?? 0);
+        const depth = depths.get(slug) ?? null;
+        const weight = isHome
+            ? HOME_WEIGHT
+            : Math.min(HOME_WEIGHT, CONTRIBUTION.base +
+                CONTRIBUTION.inbound * Math.min(inbound / INBOUND_SATURATION, 1) +
+                (isNamed ? CONTRIBUTION.named : 0) +
+                CONTRIBUTION.depth * depthScore(depth));
+        weights.set(slug, {
+            slug,
+            weight: Math.round(weight * 1000) / 1000,
+            inbound,
+            depth,
+            named: isNamed,
+            isHome,
+            isUnlinked: !isHome && !isNamed && inbound === 0
+        });
+    }
+    return weights;
+}

package/dist/checks/rules-draft.d.ts

@@ -0,0 +1,2 @@
+import type { CheckRule } from "./types.ts";
+export declare const DRAFT_RULES: CheckRule[];