@wootsup/yt-builder-mcp 1.9.0 → 1.11.0

package/dist/tools/pages/handlers-audit.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `pages_audit` handler — Task 6 of the pages_audit implementation plan
+ * (2026-07-19-04). Kept in its OWN file (not `handlers-read.ts`, already
+ * 981 LoC) per the plan's explicit instruction.
+ *
+ * The handler is a thin REST-to-MCP adapter: `GET /pages/audit` already
+ * returns the FULL, severity-sorted, deterministic sweep
+ * ({@see \WootsUp\BuilderMcp\Pages\Audit\PageAuditService::audit()}); this
+ * file only (a) forwards the optional filters as query params, (b) renders
+ * a COMPACT truncate-tolerant text-leg table (never the raw JSON dump —
+ * design §5), and (c) carries the complete, UNTRIMMED payload in
+ * `structuredContent` via `structuredResult` (mirrors
+ * `local-content/handlers.ts` — `applyMaxChars` only ever clips the text
+ * leg, never `structuredContent`).
+ *
+ * @license MIT
+ */
+import type { RestClient } from '../../client.js';
+import { type ToolResult } from '../tool-builder.js';
+import { type PagesTarget } from './target.js';
+/** Design §2 — the four check categories `checks[]` filters on. */
+type CheckCategory = 'seo' | 'structure' | 'content' | 'links';
+/**
+ * The human-locatable address of ONE audit hit (B-3/B-5 — mirrors the PHP
+ * `FindingLocator::toArray()` wire shape verbatim).
+ *
+ * `path` stays the machine write address (RFC-6901 JSON-Pointer); the rest is
+ * what a HUMAN needs to find that element in the YOOtheme customizer. Per the
+ * PHP null-key policy the four always-meaningful fields (`path`, `breadcrumb`,
+ * `element_type`, `repeat`) are ALWAYS emitted — `element_type: ''` means "the
+ * path no longer resolves" — while the genuinely optional ones are OMITTED
+ * rather than sent as null. `prop` / `name` ride ALONGSIDE the locator fields
+ * on the checks that need them (which prop of a link element is empty, which
+ * anchor name collided).
+ */
+export interface FindingLocator {
+    readonly path: string;
+    readonly breadcrumb: string;
+    readonly element_type: string;
+    readonly element_name?: string | null;
+    readonly heading_source?: string | null;
+    readonly content_snippet?: string | null;
+    readonly repeat: number;
+    readonly prop?: string | null;
+    readonly name?: string | null;
+    readonly [extra: string]: unknown;
+}
+/**
+ * PERF-4 / PROD-2 — the DEFAULT ceiling (chars of serialised JSON) on the
+ * `structuredContent` leg of one `pages_audit` result.
+ *
+ * There was NO ceiling at all: `applyMaxChars` clips only `content[0].text`
+ * (it says so in its own docblock), `max_chars` has no default, and the
+ * projection forwarded `findings` verbatim. Measured on this transport: **349.1
+ * KB (~89k tokens)** for a site sweep and **193.9 KB (~50k tokens)** for ONE
+ * busy page — against 12,000 chars for the identical request on the in-process
+ * native transport. A single tool result could eat most of a context window.
+ *
+ * WHY 48,000 and not the native handler's 12,000:
+ *
+ *   - The two transports carry DIFFERENT things under that number. Native emits
+ *     ONE payload — the audit JSON rendered as the text the model reads — so
+ *     12,000 chars is the whole result. Here the legs are separate: the text leg
+ *     is independently bounded ({@link LOCATOR_LINES_PER_FINDING} = 15 locators
+ *     per finding) and `structuredContent` is the MACHINE leg an agent drills
+ *     into for the exact paths it is about to write to. Sharing one constant
+ *     across that boundary would make each transport's budget wrong for the
+ *     other's payload.
+ *   - 48,000 chars ≈ 12k tokens at 4 chars/token — a bounded, predictable slice
+ *     of a context window, and still a ~7× cut from the measured 349 KB.
+ *   - It is above every realistic SINGLE-page audit (the headline case: ~100
+ *     hits × ~250 chars of locator ≈ 25 KB), so the capability that motivated
+ *     locators is never shed on a normal page — only pathological ones degrade.
+ *
+ * `max_chars` overrides it in BOTH directions (the schema's range is
+ * 200…100,000), which is why the `max_chars` describe on THIS tool states that
+ * it bounds both legs while the shared one still says text-only.
+ */
+export declare const STRUCTURED_BUDGET_CHARS = 48000;
+/**
+ * The per-page-entry keys the evidence rung KEEPS — mirrors
+ * `McpPagesAuditHandler::PAGE_IDENTITY_KEYS`, and is pinned against the value
+ * PHP derives from its own constant by
+ * `tests/contracts/audit-shrink-ladder.test.ts`.
+ *
+ * An allow-list, not a drop-list, on purpose: evidence keys are check-SPECIFIC
+ * (`paths`, `alt_paths`, `anchors`, `generic_alts`, `skips`, `dead_anchors`,
+ * `long_headings`, `first_headline_path`, `cluster_id`, `iterated`, …) and a
+ * new check on the HOST adds new ones this package has never heard of. A
+ * drop-list would silently stop shedding the day a host ships one; an
+ * allow-list keeps identity + counts protected by construction.
+ */
+export declare const PAGE_IDENTITY_KEYS: readonly string[];
+/**
+ * BUGS-2 — the raw per-hit evidence arrays that are a PROVABLE DUPLICATE of the
+ * locators riding on the same page entry, and may therefore be shed BEFORE a
+ * single locator is thinned. Mirrors
+ * `McpPagesAuditHandler::REDUNDANT_EVIDENCE_KEYS`; same contract test pins it.
+ *
+ * "Provable" means every field the array element carries also rides on the
+ * locator built from the SAME hit, host-side in `AuditCheckRegistry`:
+ * `paths` → path (+ the locator adds heading_source + repeat, which a bare
+ * pointer cannot express), `alt_paths` → path (+ prop), `dead_anchors` →
+ * {path,name}, `anchors` → {path,reason,text}, `generic_alts` →
+ * {path,prop,text}, `long_headings` → {path,length}.
+ *
+ * DELIBERATELY ABSENT: `skips` (heading-skip). Its elements are
+ * `{path, from, to}` and that check builds its locator with no from/to rider,
+ * so the jumped heading levels ride on that array and nothing else. It is shed
+ * by the allow-list rung instead.
+ *
+ * Being a DROP-list this one is allowed to be incomplete — a new host check's
+ * array simply is not shed EARLY, and the allow-list rung behind it still sheds
+ * everything. Opposite failure modes on purpose: this one under-sheds, the
+ * other cannot.
+ */
+export declare const REDUNDANT_EVIDENCE_KEYS: readonly string[];
+export interface PagesAuditArgs {
+    readonly types?: readonly string[];
+    readonly checks?: readonly CheckCategory[];
+    readonly thin_content_threshold?: number;
+    readonly stale_after_months?: number;
+    readonly max_chars?: number;
+    /** A-6: scope the sweep to ONE page (exactly one member — handler-validated). */
+    readonly target?: PagesTarget;
+}
+export declare function handlePagesAudit(client: RestClient, { types, checks, thin_content_threshold, stale_after_months, max_chars, target }: PagesAuditArgs): Promise<ToolResult>;
+export {};
+//# sourceMappingURL=handlers-audit.d.ts.map

package/dist/tools/pages/handlers-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers-audit.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/handlers-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAUH,KAAK,WAAW,EACnB,MAAM,aAAa,CAAC;AAErB,mEAAmE;AACnE,KAAK,aAAa,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC;AAuND;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAQ9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAU/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAOpD,CAAC;AA0VF,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CACjC;AAED,wBAAsB,gBAAgB,CAClC,MAAM,EAAE,UAAU,EAClB,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,cAAc,GACjG,OAAO,CAAC,UAAU,CAAC,CA0LrB"}