@pseolint/core 0.4.3 → 0.5.3

package/dist/ai/tools/sample-template.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+/**
+ * Stratified URL sampler. Two modes:
+ *   - No `template`: stratified sample across all template clusters in `urls`,
+ *     proportional to sqrt(cluster size). Good for "give me N representative
+ *     URLs from this entire sitemap."
+ *   - With `template`: restrict to URLs matching the named template, then
+ *     simple random sample of size `n`. Good for "give me 5 examples from the
+ *     /city/ template specifically."
+ */
+export declare const sampleTemplateTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType<{
+        urls: string[];
+        n: number;
+        template?: string | undefined;
+    }, unknown, z.core.$ZodTypeInternals<{
+        urls: string[];
+        n: number;
+        template?: string | undefined;
+    }, unknown>>;
+    outputSchema: z.ZodType<{
+        sample: string[];
+        sampledFrom: number;
+        template: null;
+    } | {
+        sample: string[];
+        sampledFrom: number;
+        template: string;
+    }, unknown, z.core.$ZodTypeInternals<{
+        sample: string[];
+        sampledFrom: number;
+        template: null;
+    } | {
+        sample: string[];
+        sampledFrom: number;
+        template: string;
+    }, unknown>>;
+    toAiTool(): import("ai").Tool<{
+        urls: string[];
+        n: number;
+        template?: string | undefined;
+    }, import("./types.js").ToolResult<{
+        sample: string[];
+        sampledFrom: number;
+        template: null;
+    } | {
+        sample: string[];
+        sampledFrom: number;
+        template: string;
+    }>>;
+    run(input: {
+        urls: string[];
+        n: number;
+        template?: string | undefined;
+    }, ctx?: import("./types.js").ToolExecuteContext): Promise<import("./types.js").ToolResult<{
+        sample: string[];
+        sampledFrom: number;
+        template: null;
+    } | {
+        sample: string[];
+        sampledFrom: number;
+        template: string;
+    }>>;
+};
+//# sourceMappingURL=sample-template.d.ts.map

package/dist/ai/tools/sample-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample-template.d.ts","sourceRoot":"","sources":["../../../src/ai/tools/sample-template.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2CxB;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8B7B,CAAC"}

package/dist/ai/tools/sample-template.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { stratifiedSample } from "../../stratified-sample.js";
+import { normalizePathToTemplate } from "../../site-classifier.js";
+import { defineTool } from "./types.js";
+/**
+ * Match the same normalizer that `detect_templates` uses so a template key
+ * produced by one tool is usable as the `template` filter on the other.
+ * `stratified-sample.ts` ships a different (stricter) normalizer for its
+ * cluster-aware sampling, but for orchestrator handoff we need
+ * detect_templates ↔ sample_template to agree on keys.
+ */
+function urlToTemplateKey(url) {
+    try {
+        return normalizePathToTemplate(new URL(url).pathname || "/");
+    }
+    catch {
+        const path = url.split("?")[0].split("#")[0];
+        return normalizePathToTemplate(path.startsWith("/") ? path : `/${path}`);
+    }
+}
+const inputSchema = z.object({
+    urls: z.array(z.string()).min(1).describe("URL pool to sample from."),
+    n: z
+        .number()
+        .int()
+        .positive()
+        .max(500)
+        .describe("Sample size. Capped at 500 to bound LLM input tokens."),
+    template: z
+        .string()
+        .optional()
+        .describe("When provided, restrict sampling to URLs matching this template (as produced by detect_templates / inferUrlTemplate). When omitted, samples stratified across all detected templates."),
+});
+const outputSchema = z.object({
+    sample: z.array(z.string()),
+    sampledFrom: z.number().int().nonnegative(),
+    template: z.string().nullable(),
+});
+/**
+ * Stratified URL sampler. Two modes:
+ *   - No `template`: stratified sample across all template clusters in `urls`,
+ *     proportional to sqrt(cluster size). Good for "give me N representative
+ *     URLs from this entire sitemap."
+ *   - With `template`: restrict to URLs matching the named template, then
+ *     simple random sample of size `n`. Good for "give me 5 examples from the
+ *     /city/ template specifically."
+ */
+export const sampleTemplateTool = defineTool({
+    name: "sample_template",
+    description: "Sample URLs from a list. Without `template`, returns N URLs stratified across all detected templates (good for 'representative sample of this sitemap'). With `template`, restricts to URLs matching that template (good for 'give me 5 example pages from the /city/ template'). Capped at n=500 to keep LLM context manageable.",
+    inputSchema,
+    outputSchema,
+    async execute({ urls, n, template }) {
+        if (template === undefined) {
+            const sample = stratifiedSample(urls, n);
+            return { sample, sampledFrom: urls.length, template: null };
+        }
+        const matching = urls.filter((u) => urlToTemplateKey(u) === template);
+        if (matching.length === 0) {
+            return { sample: [], sampledFrom: 0, template };
+        }
+        if (matching.length <= n) {
+            return { sample: matching, sampledFrom: matching.length, template };
+        }
+        // Simple shuffle-then-take (deterministic enough for orchestrator use; the
+        // LLM picks N, our job is to produce N distinct URLs from the cluster).
+        const shuffled = [...matching];
+        for (let i = shuffled.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+        }
+        return { sample: shuffled.slice(0, n), sampledFrom: matching.length, template };
+    },
+});
+//# sourceMappingURL=sample-template.js.map

package/dist/ai/tools/sample-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample-template.js","sourceRoot":"","sources":["../../../src/ai/tools/sample-template.ts"],"names":[],"mappings":"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"}

package/dist/ai/tools/types.d.ts

@@ -0,0 +1,73 @@
+import type { ZodType } from "zod";
+/**
+ * Tool execution context. The AI SDK passes this as the second argument to
+ * `execute` — we surface only the fields tools care about (currently just
+ * the abort signal). Tools that don't need it can ignore the context.
+ */
+export interface ToolExecuteContext {
+    /**
+     * Aborted when the orchestrator session aborts. Tools that perform I/O
+     * (fetch_page, query_serp, ask_ai_engine, etc.) should thread this into
+     * their underlying fetch calls so in-flight network work cancels
+     * promptly when the session ends.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Tool definition consumed by `defineTool`. Each orchestrator tool exposes a
+ * Zod-typed input + output schema, a description (used by the LLM to decide
+ * when to call the tool), and an `execute` function.
+ *
+ * The `name` field doubles as the registry key — `orchestratorTools[name]`
+ * resolves to the AI-SDK tool object generated from this definition.
+ */
+export interface ToolDefinition<I, O> {
+    name: string;
+    description: string;
+    inputSchema: ZodType<I>;
+    outputSchema: ZodType<O>;
+    execute: (input: I, ctx?: ToolExecuteContext) => Promise<O>;
+}
+/** Successful tool result wrapped in a discriminated union for LLM consumption. */
+export interface ToolOk<O> {
+    ok: true;
+    data: O;
+}
+/**
+ * Tool error result. Errors are returned as data, not thrown — the orchestrator
+ * loop must keep going. Throwing here would terminate the AI-SDK stream and
+ * lose partial session progress.
+ */
+export interface ToolErr {
+    ok: false;
+    error: string;
+    errorCode: "INPUT_VALIDATION" | "OUTPUT_VALIDATION" | "EXECUTE_ERROR";
+}
+export type ToolResult<O> = ToolOk<O> | ToolErr;
+/**
+ * Wraps a tool definition in:
+ *   - input validation (delegated to AI SDK + duplicated in `.run` for tests)
+ *   - output validation (catches tool bugs that produce malformed outputs)
+ *   - error capture (turns thrown exceptions into `{ ok: false, error }` payloads)
+ *
+ * Returns an object exposing both `.toAiTool()` (for the orchestrator) and
+ * `.run()` (for direct test invocation). The AI SDK tool() and our test runner
+ * share the same error shape so tests assert exactly what the LLM will see.
+ */
+export declare function defineTool<I, O>(def: ToolDefinition<I, O>): {
+    name: string;
+    description: string;
+    inputSchema: ZodType<I, unknown, import("zod/v4/core").$ZodTypeInternals<I, unknown>>;
+    outputSchema: ZodType<O, unknown, import("zod/v4/core").$ZodTypeInternals<O, unknown>>;
+    /**
+     * AI SDK tool object — pass into `streamText({ tools: { name: t.toAiTool() } })`.
+     * The SDK invokes `execute(input, { abortSignal, toolCallId, ... })`; we
+     * lift `abortSignal` into our `ToolExecuteContext.signal` so I/O tools
+     * can cancel in-flight fetches when the session aborts.
+     */
+    toAiTool(): import("ai").Tool<I, ToolResult<O>>;
+    /** Direct invocation for unit tests. Validates input + output. Optional `ctx` for signal-aware tests. */
+    run(input: I, ctx?: ToolExecuteContext): Promise<ToolResult<O>>;
+};
+export type DefinedTool<I, O> = ReturnType<typeof defineTool<I, O>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/ai/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/ai/tools/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7D;AAED,mFAAmF;AACnF,MAAM,WAAW,MAAM,CAAC,CAAC;IACvB,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,kBAAkB,GAAG,mBAAmB,GAAG,eAAe,CAAC;CACvE;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;;;;;IAyBtD;;;;;OAKG;;IASH,yGAAyG;eACxF,CAAC,QAAQ,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;EAYxE;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,IAAI,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC"}

package/dist/ai/tools/types.js

@@ -0,0 +1,64 @@
+import { tool } from "ai";
+/**
+ * Wraps a tool definition in:
+ *   - input validation (delegated to AI SDK + duplicated in `.run` for tests)
+ *   - output validation (catches tool bugs that produce malformed outputs)
+ *   - error capture (turns thrown exceptions into `{ ok: false, error }` payloads)
+ *
+ * Returns an object exposing both `.toAiTool()` (for the orchestrator) and
+ * `.run()` (for direct test invocation). The AI SDK tool() and our test runner
+ * share the same error shape so tests assert exactly what the LLM will see.
+ */
+export function defineTool(def) {
+    async function executeWithCapture(input, ctx) {
+        let output;
+        try {
+            output = await def.execute(input, ctx);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return { ok: false, error: `tool ${def.name} threw: ${message}`, errorCode: "EXECUTE_ERROR" };
+        }
+        const parsed = def.outputSchema.safeParse(output);
+        if (!parsed.success) {
+            return {
+                ok: false,
+                error: `tool ${def.name} produced invalid output: ${parsed.error.message}`,
+                errorCode: "OUTPUT_VALIDATION",
+            };
+        }
+        return { ok: true, data: parsed.data };
+    }
+    return {
+        name: def.name,
+        description: def.description,
+        inputSchema: def.inputSchema,
+        outputSchema: def.outputSchema,
+        /**
+         * AI SDK tool object — pass into `streamText({ tools: { name: t.toAiTool() } })`.
+         * The SDK invokes `execute(input, { abortSignal, toolCallId, ... })`; we
+         * lift `abortSignal` into our `ToolExecuteContext.signal` so I/O tools
+         * can cancel in-flight fetches when the session aborts.
+         */
+        toAiTool() {
+            return tool({
+                description: def.description,
+                inputSchema: def.inputSchema,
+                execute: async (input, options) => executeWithCapture(input, { signal: options?.abortSignal }),
+            });
+        },
+        /** Direct invocation for unit tests. Validates input + output. Optional `ctx` for signal-aware tests. */
+        async run(input, ctx) {
+            const inputParsed = def.inputSchema.safeParse(input);
+            if (!inputParsed.success) {
+                return {
+                    ok: false,
+                    error: `tool ${def.name} got invalid input: ${inputParsed.error.message}`,
+                    errorCode: "INPUT_VALIDATION",
+                };
+            }
+            return executeWithCapture(inputParsed.data, ctx);
+        },
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/ai/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/ai/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAqD1B;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAO,GAAyB;IACxD,KAAK,UAAU,kBAAkB,CAAC,KAAQ,EAAE,GAAwB;QAClE,IAAI,MAAS,CAAC;QACd,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC3D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAG,CAAC,IAAI,WAAW,OAAO,EAAE,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;QAChG,CAAC;QACD,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,QAAQ,GAAG,CAAC,IAAI,6BAA6B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE;gBAC1E,SAAS,EAAE,mBAAmB;aAC/B,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IAED,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B;;;;;WAKG;QACH,QAAQ;YACN,OAAO,IAAI,CAAC;gBACV,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,OAAO,EAAE,KAAK,EAAE,KAAQ,EAAE,OAAuC,EAAE,EAAE,CACnE,kBAAkB,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;aAC9D,CAAC,CAAC;QACL,CAAC;QACD,yGAAyG;QACzG,KAAK,CAAC,GAAG,CAAC,KAAQ,EAAE,GAAwB;YAC1C,MAAM,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACrD,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBACzB,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,KAAK,EAAE,QAAQ,GAAG,CAAC,IAAI,uBAAuB,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE;oBACzE,SAAS,EAAE,kBAAkB;iBAC9B,CAAC;YACJ,CAAC;YACD,OAAO,kBAAkB,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ai/tools/validate-jsonld.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export declare const validateJsonLdTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType<{
+        pageId: string;
+    }, unknown, z.core.$ZodTypeInternals<{
+        pageId: string;
+    }, unknown>>;
+    outputSchema: z.ZodType<{
+        url: string;
+        blocks: {
+            index: number;
+            types: string[];
+            hasContext: boolean;
+            missingRequired: string[];
+            ok: boolean;
+        }[];
+        totalBlocks: number;
+        okBlocks: number;
+    }, unknown, z.core.$ZodTypeInternals<{
+        url: string;
+        blocks: {
+            index: number;
+            types: string[];
+            hasContext: boolean;
+            missingRequired: string[];
+            ok: boolean;
+        }[];
+        totalBlocks: number;
+        okBlocks: number;
+    }, unknown>>;
+    toAiTool(): import("ai").Tool<{
+        pageId: string;
+    }, import("./types.js").ToolResult<{
+        url: string;
+        blocks: {
+            index: number;
+            types: string[];
+            hasContext: boolean;
+            missingRequired: string[];
+            ok: boolean;
+        }[];
+        totalBlocks: number;
+        okBlocks: number;
+    }>>;
+    run(input: {
+        pageId: string;
+    }, ctx?: import("./types.js").ToolExecuteContext): Promise<import("./types.js").ToolResult<{
+        url: string;
+        blocks: {
+            index: number;
+            types: string[];
+            hasContext: boolean;
+            missingRequired: string[];
+            ok: boolean;
+        }[];
+        totalBlocks: number;
+        okBlocks: number;
+    }>>;
+};
+//# sourceMappingURL=validate-jsonld.d.ts.map

package/dist/ai/tools/validate-jsonld.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-jsonld.d.ts","sourceRoot":"","sources":["../../../src/ai/tools/validate-jsonld.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgDxB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyC7B,CAAC"}

package/dist/ai/tools/validate-jsonld.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { parseHtmlPage } from "../../parser.js";
+import { resolvePage } from "../orchestrator/page-cache.js";
+import { defineTool } from "./types.js";
+const inputSchema = z.object({
+    pageId: z.string().describe("Page reference returned by fetch_page."),
+});
+const REQUIRED_PROPERTIES_BY_TYPE = {
+    Article: ["headline", "datePublished", "author"],
+    NewsArticle: ["headline", "datePublished", "author"],
+    BlogPosting: ["headline", "datePublished", "author"],
+    Product: ["name"],
+    FAQPage: ["mainEntity"],
+    HowTo: ["name", "step"],
+    Recipe: ["name", "recipeIngredient", "recipeInstructions"],
+    Event: ["name", "startDate", "location"],
+    Organization: ["name"],
+    LocalBusiness: ["name", "address"],
+    Person: ["name"],
+    BreadcrumbList: ["itemListElement"],
+    VideoObject: ["name", "description", "thumbnailUrl", "uploadDate"],
+};
+const outputSchema = z.object({
+    url: z.string(),
+    blocks: z.array(z.object({
+        index: z.number().int().nonnegative(),
+        types: z.array(z.string()),
+        hasContext: z.boolean(),
+        missingRequired: z.array(z.string()),
+        ok: z.boolean(),
+    })),
+    totalBlocks: z.number().int().nonnegative(),
+    okBlocks: z.number().int().nonnegative(),
+});
+function typesOf(block) {
+    if (typeof block !== "object" || block === null)
+        return [];
+    const t = block["@type"];
+    if (typeof t === "string")
+        return [t];
+    if (Array.isArray(t))
+        return t.filter((x) => typeof x === "string");
+    return [];
+}
+export const validateJsonLdTool = defineTool({
+    name: "validate_jsonld",
+    description: "Validate JSON-LD blocks on a previously-fetched page against Schema.org required-property expectations (Article needs headline/datePublished/author; FAQPage needs mainEntity; Product needs name; Event needs name/startDate/location; etc.). Reports per-block missing fields. Use this to inform `add_jsonld` patch proposals.",
+    inputSchema,
+    outputSchema,
+    async execute({ pageId }) {
+        const entry = resolvePage(pageId);
+        const parsed = parseHtmlPage(entry.html, entry.url);
+        const blocks = parsed.jsonLd.map((block, index) => {
+            if (typeof block !== "object" || block === null) {
+                return { index, types: [], hasContext: false, missingRequired: [], ok: false };
+            }
+            const obj = block;
+            const types = typesOf(block);
+            const hasContext = obj["@context"] !== undefined;
+            const missing = new Set();
+            for (const t of types) {
+                const required = REQUIRED_PROPERTIES_BY_TYPE[t] ?? [];
+                for (const prop of required) {
+                    if (obj[prop] === undefined)
+                        missing.add(prop);
+                }
+            }
+            return {
+                index,
+                types,
+                hasContext,
+                missingRequired: Array.from(missing).sort(),
+                ok: hasContext && missing.size === 0 && types.length > 0,
+            };
+        });
+        return {
+            url: parsed.url,
+            blocks,
+            totalBlocks: blocks.length,
+            okBlocks: blocks.filter((b) => b.ok).length,
+        };
+    },
+});
+//# sourceMappingURL=validate-jsonld.js.map

package/dist/ai/tools/validate-jsonld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-jsonld.js","sourceRoot":"","sources":["../../../src/ai/tools/validate-jsonld.ts"],"names":[],"mappings":"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"}

package/dist/auditor.d.ts

@@ -10,5 +10,9 @@ import { type SiteClassification } from "./site-classifier.js";
  * preserved by reference.
  */
 export declare function applyScoringProfileOverrides(findings: RuleResult[], classification: SiteClassification | undefined): RuleResult[];
+export declare function parseSitemapUrlsWithLastmod(xml: string): Array<{
+    url: string;
+    lastmod?: string;
+}>;
 export declare function auditSource(source: string, options?: AuditOptions): Promise<AuditSummary>;
 //# sourceMappingURL=auditor.d.ts.map

package/dist/auditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AAyDA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAWZ,UAAU,EAGX,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAgB,KAAK,kBAAkB,EAAiB,MAAM,sBAAsB,CAAC;AAwhB5F;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,UAAU,EAAE,EACtB,cAAc,EAAE,kBAAkB,GAAG,SAAS,GAC7C,UAAU,EAAE,CAed;AAquBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA0wB/F"}
+{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AA8DA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAaZ,UAAU,EAGX,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAgB,KAAK,kBAAkB,EAAiB,MAAM,sBAAsB,CAAC;AA8xB5F;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,UAAU,EAAE,EACtB,cAAc,EAAE,kBAAkB,GAAG,SAAS,GAC7C,UAAU,EAAE,CAed;AA8VD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBjG;AA2fD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA68B/F"}