@puzzle-ui/seo 0.0.0-stage → 0.5.0

package/dist/tanstack/index.d.ts

@@ -0,0 +1,18 @@
+import { SeoRouteOptions } from "../server/types.js";
+export interface TanStackServerRouteContext {
+  request: Request;
+}
+export type TanStackSeoRouteHandler = (context: TanStackServerRouteContext) => Promise<Response>;
+export interface TanStackSeoRoutes {
+  /**
+   * Mount on a dynamic root route, e.g. /$seoFile.
+   *
+   * Handles the sitemap index and every generated sitemap file.
+   */
+  sitemapGET: TanStackSeoRouteHandler;
+  /**
+   * Mount on the static /robots.txt route.
+   */
+  robotsGET: TanStackSeoRouteHandler;
+}
+export declare const createTanStackSeoRoutes: (options: SeoRouteOptions) => TanStackSeoRoutes;

package/dist/tanstack/index.js

@@ -0,0 +1,12 @@
+import { createSeoRouteHandlers } from "../server/routes.js";
+// src/tanstack/index.ts
+const createTanStackSeoRoutes = (options) => {
+	const handlers = createSeoRouteHandlers(options);
+	return {
+		sitemapGET: ({ request }) => handlers.sitemap(request),
+		robotsGET: ({ request }) => handlers.robots(request)
+	};
+};
+export { createTanStackSeoRoutes };
+
+//# sourceMappingURL=index.js.map

package/dist/tanstack/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/tanstack/index.ts"],"sourcesContent":["import { createSeoRouteHandlers } from \"../server\";\n\nimport type { SeoRouteOptions } from \"../server\";\n\nexport interface TanStackServerRouteContext {\n  request: Request;\n}\n\nexport type TanStackSeoRouteHandler = (\n  context: TanStackServerRouteContext,\n) => Promise<Response>;\n\nexport interface TanStackSeoRoutes {\n  /**\n   * Mount on a dynamic root route, e.g. /$seoFile.\n   *\n   * Handles the sitemap index and every generated sitemap file.\n   */\n  sitemapGET: TanStackSeoRouteHandler;\n\n  /**\n   * Mount on the static /robots.txt route.\n   */\n  robotsGET: TanStackSeoRouteHandler;\n}\n\nexport const createTanStackSeoRoutes = (\n  options: SeoRouteOptions,\n): TanStackSeoRoutes => {\n  const handlers = createSeoRouteHandlers(options);\n\n  return {\n    sitemapGET: ({ request }) => handlers.sitemap(request),\n    robotsGET: ({ request }) => handlers.robots(request),\n  };\n};\n"],"mappings":";;AA0BA,MAAa,2BACX,YACsB;CACtB,MAAM,WAAW,uBAAuB,OAAO;CAE/C,OAAO;EACL,aAAa,EAAE,cAAc,SAAS,QAAQ,OAAO;EACrD,YAAY,EAAE,cAAc,SAAS,OAAO,OAAO;CACrD;AACF"}

package/dist/testing/diagnostics.cjs

@@ -0,0 +1,27 @@
+// src/testing/diagnostics.ts
+const formatIssue = (issue, options) => {
+	const parts = [
+		`[${issue.severity.toUpperCase()}]`,
+		`[${issue.source}]`,
+		issue.code,
+		issue.message
+	];
+	if (options.includePaths !== false) {
+		const location = issue.path ?? issue.nodeId;
+		if (location) parts.push(`Path: ${location}`);
+	}
+	if (options.includeSuggestions !== false && issue.suggestion) parts.push(`Suggestion: ${issue.suggestion}`);
+	if (issue.docsUrl) parts.push(`Documentation: ${issue.docsUrl}`);
+	return parts.join(" — ");
+};
+const formatSeoDiagnostics = (report, options = {}) => {
+	const lines = report.issues.map((issue) => formatIssue(issue, options));
+	if (options.includeSummary !== false) {
+		const { errors, warnings, infos, total } = report.summary;
+		lines.push("", `SEO validation: ${report.valid ? "PASSED" : "FAILED"}`, `Mode: ${report.mode}`, `Issues: ${total}`, `Errors: ${errors}`, `Warnings: ${warnings}`, `Info: ${infos}`);
+	}
+	return lines.join("\n");
+};
+exports.formatSeoDiagnostics = formatSeoDiagnostics;
+
+//# sourceMappingURL=diagnostics.cjs.map

package/dist/testing/diagnostics.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.cjs","names":[],"sources":["../../src/testing/diagnostics.ts"],"sourcesContent":["import type {\n  SeoValidationReport,\n  SeoValidationIssue,\n} from \"../validation/types\";\n\nimport type { SeoDiagnosticFormatOptions } from \"./types\";\n\nconst formatIssue = (\n  issue: SeoValidationIssue,\n  options: SeoDiagnosticFormatOptions,\n): string => {\n  const parts = [\n    `[${issue.severity.toUpperCase()}]`,\n    `[${issue.source}]`,\n    issue.code,\n    issue.message,\n  ];\n\n  if (options.includePaths !== false) {\n    const location = issue.path ?? issue.nodeId;\n\n    if (location) {\n      parts.push(`Path: ${location}`);\n    }\n  }\n\n  if (options.includeSuggestions !== false && issue.suggestion) {\n    parts.push(`Suggestion: ${issue.suggestion}`);\n  }\n\n  if (issue.docsUrl) {\n    parts.push(`Documentation: ${issue.docsUrl}`);\n  }\n\n  return parts.join(\" — \");\n};\n\nexport const formatSeoDiagnostics = (\n  report: SeoValidationReport,\n  options: SeoDiagnosticFormatOptions = {},\n): string => {\n  const lines = report.issues.map((issue) => formatIssue(issue, options));\n\n  if (options.includeSummary !== false) {\n    const { errors, warnings, infos, total } = report.summary;\n\n    lines.push(\n      \"\",\n      `SEO validation: ${report.valid ? \"PASSED\" : \"FAILED\"}`,\n      `Mode: ${report.mode}`,\n      `Issues: ${total}`,\n      `Errors: ${errors}`,\n      `Warnings: ${warnings}`,\n      `Info: ${infos}`,\n    );\n  }\n\n  return lines.join(\"\\n\");\n};\n"],"mappings":";AAOA,MAAM,eACJ,OACA,YACW;CACX,MAAM,QAAQ;EACZ,IAAI,MAAM,SAAS,YAAY,EAAE;EACjC,IAAI,MAAM,OAAO;EACjB,MAAM;EACN,MAAM;CACR;CAEA,IAAI,QAAQ,iBAAiB,OAAO;EAClC,MAAM,WAAW,MAAM,QAAQ,MAAM;EAErC,IAAI,UACF,MAAM,KAAK,SAAS,UAAU;CAElC;CAEA,IAAI,QAAQ,uBAAuB,SAAS,MAAM,YAChD,MAAM,KAAK,eAAe,MAAM,YAAY;CAG9C,IAAI,MAAM,SACR,MAAM,KAAK,kBAAkB,MAAM,SAAS;CAG9C,OAAO,MAAM,KAAK,KAAK;AACzB;AAEA,MAAa,wBACX,QACA,UAAsC,CAAC,MAC5B;CACX,MAAM,QAAQ,OAAO,OAAO,KAAK,UAAU,YAAY,OAAO,OAAO,CAAC;CAEtE,IAAI,QAAQ,mBAAmB,OAAO;EACpC,MAAM,EAAE,QAAQ,UAAU,OAAO,UAAU,OAAO;EAElD,MAAM,KACJ,IACA,mBAAmB,OAAO,QAAQ,WAAW,YAC7C,SAAS,OAAO,QAChB,WAAW,SACX,WAAW,UACX,aAAa,YACb,SAAS,OACX;CACF;CAEA,OAAO,MAAM,KAAK,IAAI;AACxB"}

package/dist/testing/diagnostics.d.cts

@@ -0,0 +1,3 @@
+import { SeoValidationReport } from "../validation/types.cjs";
+import { SeoDiagnosticFormatOptions } from "./types.cjs";
+export declare const formatSeoDiagnostics: (report: SeoValidationReport, options?: SeoDiagnosticFormatOptions) => string;

package/dist/testing/diagnostics.d.ts

@@ -0,0 +1,3 @@
+import { SeoValidationReport } from "../validation/types.js";
+import { SeoDiagnosticFormatOptions } from "./types.js";
+export declare const formatSeoDiagnostics: (report: SeoValidationReport, options?: SeoDiagnosticFormatOptions) => string;

package/dist/testing/diagnostics.js

@@ -0,0 +1,27 @@
+// src/testing/diagnostics.ts
+const formatIssue = (issue, options) => {
+	const parts = [
+		`[${issue.severity.toUpperCase()}]`,
+		`[${issue.source}]`,
+		issue.code,
+		issue.message
+	];
+	if (options.includePaths !== false) {
+		const location = issue.path ?? issue.nodeId;
+		if (location) parts.push(`Path: ${location}`);
+	}
+	if (options.includeSuggestions !== false && issue.suggestion) parts.push(`Suggestion: ${issue.suggestion}`);
+	if (issue.docsUrl) parts.push(`Documentation: ${issue.docsUrl}`);
+	return parts.join(" — ");
+};
+const formatSeoDiagnostics = (report, options = {}) => {
+	const lines = report.issues.map((issue) => formatIssue(issue, options));
+	if (options.includeSummary !== false) {
+		const { errors, warnings, infos, total } = report.summary;
+		lines.push("", `SEO validation: ${report.valid ? "PASSED" : "FAILED"}`, `Mode: ${report.mode}`, `Issues: ${total}`, `Errors: ${errors}`, `Warnings: ${warnings}`, `Info: ${infos}`);
+	}
+	return lines.join("\n");
+};
+export { formatSeoDiagnostics };
+
+//# sourceMappingURL=diagnostics.js.map

package/dist/testing/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","names":[],"sources":["../../src/testing/diagnostics.ts"],"sourcesContent":["import type {\n  SeoValidationReport,\n  SeoValidationIssue,\n} from \"../validation/types\";\n\nimport type { SeoDiagnosticFormatOptions } from \"./types\";\n\nconst formatIssue = (\n  issue: SeoValidationIssue,\n  options: SeoDiagnosticFormatOptions,\n): string => {\n  const parts = [\n    `[${issue.severity.toUpperCase()}]`,\n    `[${issue.source}]`,\n    issue.code,\n    issue.message,\n  ];\n\n  if (options.includePaths !== false) {\n    const location = issue.path ?? issue.nodeId;\n\n    if (location) {\n      parts.push(`Path: ${location}`);\n    }\n  }\n\n  if (options.includeSuggestions !== false && issue.suggestion) {\n    parts.push(`Suggestion: ${issue.suggestion}`);\n  }\n\n  if (issue.docsUrl) {\n    parts.push(`Documentation: ${issue.docsUrl}`);\n  }\n\n  return parts.join(\" — \");\n};\n\nexport const formatSeoDiagnostics = (\n  report: SeoValidationReport,\n  options: SeoDiagnosticFormatOptions = {},\n): string => {\n  const lines = report.issues.map((issue) => formatIssue(issue, options));\n\n  if (options.includeSummary !== false) {\n    const { errors, warnings, infos, total } = report.summary;\n\n    lines.push(\n      \"\",\n      `SEO validation: ${report.valid ? \"PASSED\" : \"FAILED\"}`,\n      `Mode: ${report.mode}`,\n      `Issues: ${total}`,\n      `Errors: ${errors}`,\n      `Warnings: ${warnings}`,\n      `Info: ${infos}`,\n    );\n  }\n\n  return lines.join(\"\\n\");\n};\n"],"mappings":";AAOA,MAAM,eACJ,OACA,YACW;CACX,MAAM,QAAQ;EACZ,IAAI,MAAM,SAAS,YAAY,EAAE;EACjC,IAAI,MAAM,OAAO;EACjB,MAAM;EACN,MAAM;CACR;CAEA,IAAI,QAAQ,iBAAiB,OAAO;EAClC,MAAM,WAAW,MAAM,QAAQ,MAAM;EAErC,IAAI,UACF,MAAM,KAAK,SAAS,UAAU;CAElC;CAEA,IAAI,QAAQ,uBAAuB,SAAS,MAAM,YAChD,MAAM,KAAK,eAAe,MAAM,YAAY;CAG9C,IAAI,MAAM,SACR,MAAM,KAAK,kBAAkB,MAAM,SAAS;CAG9C,OAAO,MAAM,KAAK,KAAK;AACzB;AAEA,MAAa,wBACX,QACA,UAAsC,CAAC,MAC5B;CACX,MAAM,QAAQ,OAAO,OAAO,KAAK,UAAU,YAAY,OAAO,OAAO,CAAC;CAEtE,IAAI,QAAQ,mBAAmB,OAAO;EACpC,MAAM,EAAE,QAAQ,UAAU,OAAO,UAAU,OAAO;EAElD,MAAM,KACJ,IACA,mBAAmB,OAAO,QAAQ,WAAW,YAC7C,SAAS,OAAO,QAChB,WAAW,SACX,WAAW,UACX,aAAa,YACb,SAAS,OACX;CACF;CAEA,OAAO,MAAM,KAAK,IAAI;AACxB"}

package/dist/testing/fixture.cjs

@@ -0,0 +1,80 @@
+const require_graph = require("../core/graph.cjs");
+const require_validate = require("../validation/validate.cjs");
+const require_diagnostics = require("./diagnostics.cjs");
+// src/testing/fixture.ts
+const getBaseUrl = (fixture) => String(fixture.config.siteUrl);
+const resolveFixtureGraph = (fixture) => {
+	if (fixture.graph) return fixture.graph;
+	return require_graph.buildSeoGraph(fixture.nodes ?? [], { baseUrl: getBaseUrl(fixture) });
+};
+const createSeoTestFixture = (fixture) => {
+	if (fixture.graph && fixture.nodes) throw new Error("Provide either graph or nodes when creating an SEO test fixture, not both.");
+	if (!fixture.config?.siteUrl) throw new Error("SEO test fixtures require a valid siteUrl.");
+	const graph = resolveFixtureGraph(fixture);
+	return {
+		config: fixture.config,
+		graph,
+		metadata: fixture.metadata
+	};
+};
+const filterIssues = (report, options) => {
+	return report.issues.filter((issue) => {
+		if (options.validateSchema === false && issue.source === "schema") return false;
+		if (options.validateMetadata === false && issue.source === "metadata") return false;
+		if (options.validateReferences === false && issue.code === "unresolved-reference") return false;
+		return true;
+	});
+};
+const createFilteredReport = (report, issues) => {
+	const summary = {
+		errors: 0,
+		warnings: 0,
+		infos: 0,
+		total: issues.length
+	};
+	for (const issue of issues) switch (issue.severity) {
+		case "error":
+			summary.errors += 1;
+			break;
+		case "warning":
+			summary.warnings += 1;
+			break;
+		case "info": summary.infos += 1;
+	}
+	return {
+		...report,
+		valid: summary.errors === 0,
+		issues,
+		summary
+	};
+};
+const runSeoTest = (fixture, options = {}) => {
+	const graph = resolveFixtureGraph(fixture);
+	const report = require_validate.validateSeo({
+		graph,
+		metadata: options.validateMetadata === false ? void 0 : fixture.metadata
+	}, {
+		mode: options.strict ? "strict" : "warn",
+		baseUrl: getBaseUrl(fixture)
+	});
+	const filteredIssues = filterIssues(report, options);
+	const filteredReport = createFilteredReport(report, filteredIssues);
+	const errors = filteredIssues.filter((issue) => issue.severity === "error").map((issue) => issue.message);
+	const warnings = filteredIssues.filter((issue) => issue.severity === "warning").map((issue) => issue.message);
+	return {
+		passed: filteredReport.valid,
+		errors,
+		warnings,
+		report: filteredReport
+	};
+};
+const assertSeoTest = (fixture, options = {}) => {
+	const result = runSeoTest(fixture, options);
+	if (!result.passed) throw new Error(require_diagnostics.formatSeoDiagnostics(result.report));
+	return result;
+};
+exports.assertSeoTest = assertSeoTest;
+exports.createSeoTestFixture = createSeoTestFixture;
+exports.runSeoTest = runSeoTest;
+
+//# sourceMappingURL=fixture.cjs.map

package/dist/testing/fixture.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.cjs","names":["buildSeoGraph","validateSeo","formatSeoDiagnostics"],"sources":["../../src/testing/fixture.ts"],"sourcesContent":["import { buildSeoGraph } from \"../core\";\n\nimport type { SeoGraph } from \"../core\";\n\nimport { validateSeo } from \"../validation\";\n\nimport type { SeoValidationIssue, SeoValidationReport } from \"../validation\";\n\nimport type { SeoTestFixture, SeoTestOptions, SeoTestResult } from \"./types\";\n\nimport { formatSeoDiagnostics } from \"./diagnostics\";\n\nconst getBaseUrl = (fixture: SeoTestFixture): string =>\n  String(fixture.config.siteUrl);\n\nconst resolveFixtureGraph = (fixture: SeoTestFixture): SeoGraph => {\n  if (fixture.graph) {\n    return fixture.graph;\n  }\n\n  return buildSeoGraph(fixture.nodes ?? [], {\n    baseUrl: getBaseUrl(fixture),\n  });\n};\n\nexport const createSeoTestFixture = (\n  fixture: SeoTestFixture,\n): SeoTestFixture => {\n  if (fixture.graph && fixture.nodes) {\n    throw new Error(\n      \"Provide either graph or nodes when creating an SEO test fixture, not both.\",\n    );\n  }\n\n  if (!fixture.config?.siteUrl) {\n    throw new Error(\"SEO test fixtures require a valid siteUrl.\");\n  }\n\n  const graph = resolveFixtureGraph(fixture);\n\n  return {\n    config: fixture.config,\n    graph,\n    metadata: fixture.metadata,\n  };\n};\n\nconst filterIssues = (\n  report: SeoValidationReport,\n  options: SeoTestOptions,\n): SeoValidationIssue[] => {\n  return report.issues.filter((issue) => {\n    if (options.validateSchema === false && issue.source === \"schema\") {\n      return false;\n    }\n\n    if (options.validateMetadata === false && issue.source === \"metadata\") {\n      return false;\n    }\n\n    if (\n      options.validateReferences === false &&\n      issue.code === \"unresolved-reference\"\n    ) {\n      return false;\n    }\n\n    return true;\n  });\n};\n\nconst createFilteredReport = (\n  report: SeoValidationReport,\n  issues: SeoValidationIssue[],\n): SeoValidationReport => {\n  const summary = {\n    errors: 0,\n    warnings: 0,\n    infos: 0,\n    total: issues.length,\n  };\n\n  for (const issue of issues) {\n    switch (issue.severity) {\n      case \"error\":\n        summary.errors += 1;\n        break;\n      case \"warning\":\n        summary.warnings += 1;\n        break;\n      case \"info\":\n        summary.infos += 1;\n        break;\n    }\n  }\n\n  return {\n    ...report,\n    valid: summary.errors === 0,\n    issues,\n    summary,\n  };\n};\n\nexport const runSeoTest = (\n  fixture: SeoTestFixture,\n  options: SeoTestOptions = {},\n): SeoTestResult => {\n  const graph = resolveFixtureGraph(fixture);\n\n  const report = validateSeo(\n    {\n      graph,\n      metadata:\n        options.validateMetadata === false ? undefined : fixture.metadata,\n    },\n    {\n      mode: options.strict ? \"strict\" : \"warn\",\n      baseUrl: getBaseUrl(fixture),\n    },\n  );\n\n  const filteredIssues = filterIssues(report, options);\n  const filteredReport = createFilteredReport(report, filteredIssues);\n\n  const errors = filteredIssues\n    .filter((issue) => issue.severity === \"error\")\n    .map((issue) => issue.message);\n\n  const warnings = filteredIssues\n    .filter((issue) => issue.severity === \"warning\")\n    .map((issue) => issue.message);\n\n  return {\n    passed: filteredReport.valid,\n    errors,\n    warnings,\n    report: filteredReport,\n  };\n};\n\nexport const assertSeoTest = (\n  fixture: SeoTestFixture,\n  options: SeoTestOptions = {},\n): SeoTestResult => {\n  const result = runSeoTest(fixture, options);\n\n  if (!result.passed) {\n    throw new Error(formatSeoDiagnostics(result.report));\n  }\n\n  return result;\n};\n"],"mappings":";;;;AAYA,MAAM,cAAc,YAClB,OAAO,QAAQ,OAAO,OAAO;AAE/B,MAAM,uBAAuB,YAAsC;CACjE,IAAI,QAAQ,OACV,OAAO,QAAQ;CAGjB,OAAOA,cAAAA,cAAc,QAAQ,SAAS,CAAC,GAAG,EACxC,SAAS,WAAW,OAAO,EAC7B,CAAC;AACH;AAEA,MAAa,wBACX,YACmB;CACnB,IAAI,QAAQ,SAAS,QAAQ,OAC3B,MAAM,IAAI,MACR,4EACF;CAGF,IAAI,CAAC,QAAQ,QAAQ,SACnB,MAAM,IAAI,MAAM,4CAA4C;CAG9D,MAAM,QAAQ,oBAAoB,OAAO;CAEzC,OAAO;EACL,QAAQ,QAAQ;EAChB;EACA,UAAU,QAAQ;CACpB;AACF;AAEA,MAAM,gBACJ,QACA,YACyB;CACzB,OAAO,OAAO,OAAO,QAAQ,UAAU;EACrC,IAAI,QAAQ,mBAAmB,SAAS,MAAM,WAAW,UACvD,OAAO;EAGT,IAAI,QAAQ,qBAAqB,SAAS,MAAM,WAAW,YACzD,OAAO;EAGT,IACE,QAAQ,uBAAuB,SAC/B,MAAM,SAAS,wBAEf,OAAO;EAGT,OAAO;CACT,CAAC;AACH;AAEA,MAAM,wBACJ,QACA,WACwB;CACxB,MAAM,UAAU;EACd,QAAQ;EACR,UAAU;EACV,OAAO;EACP,OAAO,OAAO;CAChB;CAEA,KAAK,MAAM,SAAS,QAClB,QAAQ,MAAM,UAAd;EACE,KAAK;GACH,QAAQ,UAAU;GAClB;EACF,KAAK;GACH,QAAQ,YAAY;GACpB;EACF,KAAK,QACH,QAAQ,SAAS;CAErB;CAGF,OAAO;EACL,GAAG;EACH,OAAO,QAAQ,WAAW;EAC1B;EACA;CACF;AACF;AAEA,MAAa,cACX,SACA,UAA0B,CAAC,MACT;CAClB,MAAM,QAAQ,oBAAoB,OAAO;CAEzC,MAAM,SAASC,iBAAAA,YACb;EACE;EACA,UACE,QAAQ,qBAAqB,QAAQ,KAAA,IAAY,QAAQ;CAC7D,GACA;EACE,MAAM,QAAQ,SAAS,WAAW;EAClC,SAAS,WAAW,OAAO;CAC7B,CACF;CAEA,MAAM,iBAAiB,aAAa,QAAQ,OAAO;CACnD,MAAM,iBAAiB,qBAAqB,QAAQ,cAAc;CAElE,MAAM,SAAS,eACZ,QAAQ,UAAU,MAAM,aAAa,OAAO,CAAC,CAC7C,KAAK,UAAU,MAAM,OAAO;CAE/B,MAAM,WAAW,eACd,QAAQ,UAAU,MAAM,aAAa,SAAS,CAAC,CAC/C,KAAK,UAAU,MAAM,OAAO;CAE/B,OAAO;EACL,QAAQ,eAAe;EACvB;EACA;EACA,QAAQ;CACV;AACF;AAEA,MAAa,iBACX,SACA,UAA0B,CAAC,MACT;CAClB,MAAM,SAAS,WAAW,SAAS,OAAO;CAE1C,IAAI,CAAC,OAAO,QACV,MAAM,IAAI,MAAMC,oBAAAA,qBAAqB,OAAO,MAAM,CAAC;CAGrD,OAAO;AACT"}

package/dist/testing/fixture.d.cts

@@ -0,0 +1,4 @@
+import { SeoTestFixture, SeoTestOptions, SeoTestResult } from "./types.cjs";
+export declare const createSeoTestFixture: (fixture: SeoTestFixture) => SeoTestFixture;
+export declare const runSeoTest: (fixture: SeoTestFixture, options?: SeoTestOptions) => SeoTestResult;
+export declare const assertSeoTest: (fixture: SeoTestFixture, options?: SeoTestOptions) => SeoTestResult;

package/dist/testing/fixture.d.ts

@@ -0,0 +1,4 @@
+import { SeoTestFixture, SeoTestOptions, SeoTestResult } from "./types.js";
+export declare const createSeoTestFixture: (fixture: SeoTestFixture) => SeoTestFixture;
+export declare const runSeoTest: (fixture: SeoTestFixture, options?: SeoTestOptions) => SeoTestResult;
+export declare const assertSeoTest: (fixture: SeoTestFixture, options?: SeoTestOptions) => SeoTestResult;

package/dist/testing/fixture.js

@@ -0,0 +1,78 @@
+import { buildSeoGraph } from "../core/graph.js";
+import { validateSeo } from "../validation/validate.js";
+import { formatSeoDiagnostics } from "./diagnostics.js";
+// src/testing/fixture.ts
+const getBaseUrl = (fixture) => String(fixture.config.siteUrl);
+const resolveFixtureGraph = (fixture) => {
+	if (fixture.graph) return fixture.graph;
+	return buildSeoGraph(fixture.nodes ?? [], { baseUrl: getBaseUrl(fixture) });
+};
+const createSeoTestFixture = (fixture) => {
+	if (fixture.graph && fixture.nodes) throw new Error("Provide either graph or nodes when creating an SEO test fixture, not both.");
+	if (!fixture.config?.siteUrl) throw new Error("SEO test fixtures require a valid siteUrl.");
+	const graph = resolveFixtureGraph(fixture);
+	return {
+		config: fixture.config,
+		graph,
+		metadata: fixture.metadata
+	};
+};
+const filterIssues = (report, options) => {
+	return report.issues.filter((issue) => {
+		if (options.validateSchema === false && issue.source === "schema") return false;
+		if (options.validateMetadata === false && issue.source === "metadata") return false;
+		if (options.validateReferences === false && issue.code === "unresolved-reference") return false;
+		return true;
+	});
+};
+const createFilteredReport = (report, issues) => {
+	const summary = {
+		errors: 0,
+		warnings: 0,
+		infos: 0,
+		total: issues.length
+	};
+	for (const issue of issues) switch (issue.severity) {
+		case "error":
+			summary.errors += 1;
+			break;
+		case "warning":
+			summary.warnings += 1;
+			break;
+		case "info": summary.infos += 1;
+	}
+	return {
+		...report,
+		valid: summary.errors === 0,
+		issues,
+		summary
+	};
+};
+const runSeoTest = (fixture, options = {}) => {
+	const graph = resolveFixtureGraph(fixture);
+	const report = validateSeo({
+		graph,
+		metadata: options.validateMetadata === false ? void 0 : fixture.metadata
+	}, {
+		mode: options.strict ? "strict" : "warn",
+		baseUrl: getBaseUrl(fixture)
+	});
+	const filteredIssues = filterIssues(report, options);
+	const filteredReport = createFilteredReport(report, filteredIssues);
+	const errors = filteredIssues.filter((issue) => issue.severity === "error").map((issue) => issue.message);
+	const warnings = filteredIssues.filter((issue) => issue.severity === "warning").map((issue) => issue.message);
+	return {
+		passed: filteredReport.valid,
+		errors,
+		warnings,
+		report: filteredReport
+	};
+};
+const assertSeoTest = (fixture, options = {}) => {
+	const result = runSeoTest(fixture, options);
+	if (!result.passed) throw new Error(formatSeoDiagnostics(result.report));
+	return result;
+};
+export { assertSeoTest, createSeoTestFixture, runSeoTest };
+
+//# sourceMappingURL=fixture.js.map

package/dist/testing/fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.js","names":[],"sources":["../../src/testing/fixture.ts"],"sourcesContent":["import { buildSeoGraph } from \"../core\";\n\nimport type { SeoGraph } from \"../core\";\n\nimport { validateSeo } from \"../validation\";\n\nimport type { SeoValidationIssue, SeoValidationReport } from \"../validation\";\n\nimport type { SeoTestFixture, SeoTestOptions, SeoTestResult } from \"./types\";\n\nimport { formatSeoDiagnostics } from \"./diagnostics\";\n\nconst getBaseUrl = (fixture: SeoTestFixture): string =>\n  String(fixture.config.siteUrl);\n\nconst resolveFixtureGraph = (fixture: SeoTestFixture): SeoGraph => {\n  if (fixture.graph) {\n    return fixture.graph;\n  }\n\n  return buildSeoGraph(fixture.nodes ?? [], {\n    baseUrl: getBaseUrl(fixture),\n  });\n};\n\nexport const createSeoTestFixture = (\n  fixture: SeoTestFixture,\n): SeoTestFixture => {\n  if (fixture.graph && fixture.nodes) {\n    throw new Error(\n      \"Provide either graph or nodes when creating an SEO test fixture, not both.\",\n    );\n  }\n\n  if (!fixture.config?.siteUrl) {\n    throw new Error(\"SEO test fixtures require a valid siteUrl.\");\n  }\n\n  const graph = resolveFixtureGraph(fixture);\n\n  return {\n    config: fixture.config,\n    graph,\n    metadata: fixture.metadata,\n  };\n};\n\nconst filterIssues = (\n  report: SeoValidationReport,\n  options: SeoTestOptions,\n): SeoValidationIssue[] => {\n  return report.issues.filter((issue) => {\n    if (options.validateSchema === false && issue.source === \"schema\") {\n      return false;\n    }\n\n    if (options.validateMetadata === false && issue.source === \"metadata\") {\n      return false;\n    }\n\n    if (\n      options.validateReferences === false &&\n      issue.code === \"unresolved-reference\"\n    ) {\n      return false;\n    }\n\n    return true;\n  });\n};\n\nconst createFilteredReport = (\n  report: SeoValidationReport,\n  issues: SeoValidationIssue[],\n): SeoValidationReport => {\n  const summary = {\n    errors: 0,\n    warnings: 0,\n    infos: 0,\n    total: issues.length,\n  };\n\n  for (const issue of issues) {\n    switch (issue.severity) {\n      case \"error\":\n        summary.errors += 1;\n        break;\n      case \"warning\":\n        summary.warnings += 1;\n        break;\n      case \"info\":\n        summary.infos += 1;\n        break;\n    }\n  }\n\n  return {\n    ...report,\n    valid: summary.errors === 0,\n    issues,\n    summary,\n  };\n};\n\nexport const runSeoTest = (\n  fixture: SeoTestFixture,\n  options: SeoTestOptions = {},\n): SeoTestResult => {\n  const graph = resolveFixtureGraph(fixture);\n\n  const report = validateSeo(\n    {\n      graph,\n      metadata:\n        options.validateMetadata === false ? undefined : fixture.metadata,\n    },\n    {\n      mode: options.strict ? \"strict\" : \"warn\",\n      baseUrl: getBaseUrl(fixture),\n    },\n  );\n\n  const filteredIssues = filterIssues(report, options);\n  const filteredReport = createFilteredReport(report, filteredIssues);\n\n  const errors = filteredIssues\n    .filter((issue) => issue.severity === \"error\")\n    .map((issue) => issue.message);\n\n  const warnings = filteredIssues\n    .filter((issue) => issue.severity === \"warning\")\n    .map((issue) => issue.message);\n\n  return {\n    passed: filteredReport.valid,\n    errors,\n    warnings,\n    report: filteredReport,\n  };\n};\n\nexport const assertSeoTest = (\n  fixture: SeoTestFixture,\n  options: SeoTestOptions = {},\n): SeoTestResult => {\n  const result = runSeoTest(fixture, options);\n\n  if (!result.passed) {\n    throw new Error(formatSeoDiagnostics(result.report));\n  }\n\n  return result;\n};\n"],"mappings":";;;;AAYA,MAAM,cAAc,YAClB,OAAO,QAAQ,OAAO,OAAO;AAE/B,MAAM,uBAAuB,YAAsC;CACjE,IAAI,QAAQ,OACV,OAAO,QAAQ;CAGjB,OAAO,cAAc,QAAQ,SAAS,CAAC,GAAG,EACxC,SAAS,WAAW,OAAO,EAC7B,CAAC;AACH;AAEA,MAAa,wBACX,YACmB;CACnB,IAAI,QAAQ,SAAS,QAAQ,OAC3B,MAAM,IAAI,MACR,4EACF;CAGF,IAAI,CAAC,QAAQ,QAAQ,SACnB,MAAM,IAAI,MAAM,4CAA4C;CAG9D,MAAM,QAAQ,oBAAoB,OAAO;CAEzC,OAAO;EACL,QAAQ,QAAQ;EAChB;EACA,UAAU,QAAQ;CACpB;AACF;AAEA,MAAM,gBACJ,QACA,YACyB;CACzB,OAAO,OAAO,OAAO,QAAQ,UAAU;EACrC,IAAI,QAAQ,mBAAmB,SAAS,MAAM,WAAW,UACvD,OAAO;EAGT,IAAI,QAAQ,qBAAqB,SAAS,MAAM,WAAW,YACzD,OAAO;EAGT,IACE,QAAQ,uBAAuB,SAC/B,MAAM,SAAS,wBAEf,OAAO;EAGT,OAAO;CACT,CAAC;AACH;AAEA,MAAM,wBACJ,QACA,WACwB;CACxB,MAAM,UAAU;EACd,QAAQ;EACR,UAAU;EACV,OAAO;EACP,OAAO,OAAO;CAChB;CAEA,KAAK,MAAM,SAAS,QAClB,QAAQ,MAAM,UAAd;EACE,KAAK;GACH,QAAQ,UAAU;GAClB;EACF,KAAK;GACH,QAAQ,YAAY;GACpB;EACF,KAAK,QACH,QAAQ,SAAS;CAErB;CAGF,OAAO;EACL,GAAG;EACH,OAAO,QAAQ,WAAW;EAC1B;EACA;CACF;AACF;AAEA,MAAa,cACX,SACA,UAA0B,CAAC,MACT;CAClB,MAAM,QAAQ,oBAAoB,OAAO;CAEzC,MAAM,SAAS,YACb;EACE;EACA,UACE,QAAQ,qBAAqB,QAAQ,KAAA,IAAY,QAAQ;CAC7D,GACA;EACE,MAAM,QAAQ,SAAS,WAAW;EAClC,SAAS,WAAW,OAAO;CAC7B,CACF;CAEA,MAAM,iBAAiB,aAAa,QAAQ,OAAO;CACnD,MAAM,iBAAiB,qBAAqB,QAAQ,cAAc;CAElE,MAAM,SAAS,eACZ,QAAQ,UAAU,MAAM,aAAa,OAAO,CAAC,CAC7C,KAAK,UAAU,MAAM,OAAO;CAE/B,MAAM,WAAW,eACd,QAAQ,UAAU,MAAM,aAAa,SAAS,CAAC,CAC/C,KAAK,UAAU,MAAM,OAAO;CAE/B,OAAO;EACL,QAAQ,eAAe;EACvB;EACA;EACA,QAAQ;CACV;AACF;AAEA,MAAa,iBACX,SACA,UAA0B,CAAC,MACT;CAClB,MAAM,SAAS,WAAW,SAAS,OAAO;CAE1C,IAAI,CAAC,OAAO,QACV,MAAM,IAAI,MAAM,qBAAqB,OAAO,MAAM,CAAC;CAGrD,OAAO;AACT"}

package/dist/testing/index.cjs

@@ -0,0 +1,9 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_inspect = require("./inspect.cjs");
+const require_diagnostics = require("./diagnostics.cjs");
+const require_fixture = require("./fixture.cjs");
+exports.assertSeoTest = require_fixture.assertSeoTest;
+exports.createSeoTestFixture = require_fixture.createSeoTestFixture;
+exports.formatSeoDiagnostics = require_diagnostics.formatSeoDiagnostics;
+exports.inspectSeoGraph = require_inspect.inspectSeoGraph;
+exports.runSeoTest = require_fixture.runSeoTest;

package/dist/testing/index.d.cts

@@ -0,0 +1,5 @@
+import { SeoDiagnosticFormatOptions, SeoGraphInspection, SeoGraphNodeInspection, SeoTestFixture, SeoTestOptions, SeoTestResult } from "./types.cjs";
+import { inspectSeoGraph } from "./inspect.cjs";
+import { formatSeoDiagnostics } from "./diagnostics.cjs";
+import { assertSeoTest, createSeoTestFixture, runSeoTest } from "./fixture.cjs";
+export { type SeoDiagnosticFormatOptions, type SeoGraphInspection, type SeoGraphNodeInspection, type SeoTestFixture, type SeoTestOptions, type SeoTestResult, assertSeoTest, createSeoTestFixture, formatSeoDiagnostics, inspectSeoGraph, runSeoTest };

package/dist/testing/index.d.ts

@@ -0,0 +1,5 @@
+import { SeoDiagnosticFormatOptions, SeoGraphInspection, SeoGraphNodeInspection, SeoTestFixture, SeoTestOptions, SeoTestResult } from "./types.js";
+import { inspectSeoGraph } from "./inspect.js";
+import { formatSeoDiagnostics } from "./diagnostics.js";
+import { assertSeoTest, createSeoTestFixture, runSeoTest } from "./fixture.js";
+export { type SeoDiagnosticFormatOptions, type SeoGraphInspection, type SeoGraphNodeInspection, type SeoTestFixture, type SeoTestOptions, type SeoTestResult, assertSeoTest, createSeoTestFixture, formatSeoDiagnostics, inspectSeoGraph, runSeoTest };

package/dist/testing/index.js

@@ -0,0 +1,4 @@
+import { inspectSeoGraph } from "./inspect.js";
+import { formatSeoDiagnostics } from "./diagnostics.js";
+import { assertSeoTest, createSeoTestFixture, runSeoTest } from "./fixture.js";
+export { assertSeoTest, createSeoTestFixture, formatSeoDiagnostics, inspectSeoGraph, runSeoTest };

package/dist/testing/inspect.cjs

@@ -0,0 +1,63 @@
+const require_graph = require("../core/graph.cjs");
+// src/testing/inspect.ts
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const getTypes = (node) => {
+	const value = node["@type"];
+	return (Array.isArray(value) ? value : [value]).filter((type) => typeof type === "string" && type.length > 0).map((type) => type.split("/").pop() ?? type).sort();
+};
+const collectReferences = (value, references) => {
+	if (Array.isArray(value)) {
+		for (const item of value) collectReferences(item, references);
+		return;
+	}
+	if (!isObject(value)) return;
+	if (typeof value["@id"] === "string" && Object.keys(value).every((key) => key === "@id")) {
+		references.add(value["@id"]);
+		return;
+	}
+	for (const nestedValue of Object.values(value)) collectReferences(nestedValue, references);
+};
+const inspectSeoGraph = (graph, options = {}) => {
+	const nodes = Array.isArray(graph["@graph"]) ? graph["@graph"] : [];
+	const typeCounts = {};
+	const references = /* @__PURE__ */ new Set();
+	const inspectedNodes = nodes.map((node) => {
+		const types = getTypes(node);
+		for (const type of types) typeCounts[type] = (typeCounts[type] ?? 0) + 1;
+		collectReferences(node, references);
+		return {
+			id: typeof node["@id"] === "string" ? node["@id"] : void 0,
+			types,
+			properties: Object.keys(node).filter((property) => !property.startsWith("__puzzle")).sort()
+		};
+	});
+	const graphIds = new Set(nodes.map((node) => node["@id"]).filter((id) => typeof id === "string"));
+	const unresolvedReferences = [...references].filter((reference) => {
+		if (graphIds.has(reference)) return false;
+		if (reference.startsWith("#")) return true;
+		if (!options.baseUrl) return false;
+		try {
+			const target = new URL(reference);
+			const base = new URL(options.baseUrl);
+			return target.origin === base.origin;
+		} catch {
+			return false;
+		}
+	}).sort();
+	const validation = require_graph.validateSeoGraph(graph, {
+		baseUrl: options.baseUrl,
+		strictReferences: true,
+		allowedExternalReferences: true
+	});
+	return {
+		nodeCount: nodes.length,
+		typeCounts,
+		nodes: inspectedNodes,
+		references: [...references].sort(),
+		unresolvedReferences,
+		valid: validation.valid
+	};
+};
+exports.inspectSeoGraph = inspectSeoGraph;
+
+//# sourceMappingURL=inspect.cjs.map

package/dist/testing/inspect.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.cjs","names":["validateSeoGraph"],"sources":["../../src/testing/inspect.ts"],"sourcesContent":["import type { SeoGraph, SeoNode } from \"../core/types\";\n\nimport { validateSeoGraph } from \"../core\";\n\nimport type { SeoGraphInspection } from \"./types\";\n\nconst isObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nconst getTypes = (node: SeoNode): string[] => {\n  const value = node[\"@type\"];\n  const types = Array.isArray(value) ? value : [value];\n\n  return types\n    .filter(\n      (type): type is string => typeof type === \"string\" && type.length > 0,\n    )\n    .map((type) => type.split(\"/\").pop() ?? type)\n    .sort();\n};\n\nconst collectReferences = (value: unknown, references: Set<string>): void => {\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      collectReferences(item, references);\n    }\n\n    return;\n  }\n\n  if (!isObject(value)) {\n    return;\n  }\n\n  if (\n    typeof value[\"@id\"] === \"string\" &&\n    Object.keys(value).every((key) => key === \"@id\")\n  ) {\n    references.add(value[\"@id\"]);\n    return;\n  }\n\n  for (const nestedValue of Object.values(value)) {\n    collectReferences(nestedValue, references);\n  }\n};\n\nexport const inspectSeoGraph = (\n  graph: SeoGraph,\n  options: {\n    baseUrl?: string;\n  } = {},\n): SeoGraphInspection => {\n  const nodes = Array.isArray(graph[\"@graph\"]) ? graph[\"@graph\"] : [];\n\n  const typeCounts: Record<string, number> = {};\n  const references = new Set<string>();\n\n  const inspectedNodes = nodes.map((node) => {\n    const types = getTypes(node);\n\n    for (const type of types) {\n      typeCounts[type] = (typeCounts[type] ?? 0) + 1;\n    }\n\n    collectReferences(node, references);\n\n    return {\n      id: typeof node[\"@id\"] === \"string\" ? node[\"@id\"] : undefined,\n      types,\n      properties: Object.keys(node)\n        .filter((property) => !property.startsWith(\"__puzzle\"))\n        .sort(),\n    };\n  });\n\n  const graphIds = new Set(\n    nodes\n      .map((node) => node[\"@id\"])\n      .filter((id): id is string => typeof id === \"string\"),\n  );\n\n  const unresolvedReferences = [...references]\n    .filter((reference) => {\n      if (graphIds.has(reference)) {\n        return false;\n      }\n\n      // Only local references are considered unresolved.\n      if (reference.startsWith(\"#\")) {\n        return true;\n      }\n\n      if (!options.baseUrl) {\n        return false;\n      }\n\n      try {\n        const target = new URL(reference);\n        const base = new URL(options.baseUrl);\n\n        return target.origin === base.origin;\n      } catch {\n        return false;\n      }\n    })\n    .sort();\n\n  const validation = validateSeoGraph(graph, {\n    baseUrl: options.baseUrl,\n    strictReferences: true,\n    allowedExternalReferences: true,\n  });\n\n  return {\n    nodeCount: nodes.length,\n    typeCounts,\n    nodes: inspectedNodes,\n    references: [...references].sort(),\n    unresolvedReferences,\n    valid: validation.valid,\n  };\n};\n"],"mappings":";;AAMA,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAErE,MAAM,YAAY,SAA4B;CAC5C,MAAM,QAAQ,KAAK;CAGnB,QAFc,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK,EAAA,CAGhD,QACE,SAAyB,OAAO,SAAS,YAAY,KAAK,SAAS,CACtE,CAAC,CACA,KAAK,SAAS,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAC5C,KAAK;AACV;AAEA,MAAM,qBAAqB,OAAgB,eAAkC;CAC3E,IAAI,MAAM,QAAQ,KAAK,GAAG;EACxB,KAAK,MAAM,QAAQ,OACjB,kBAAkB,MAAM,UAAU;EAGpC;CACF;CAEA,IAAI,CAAC,SAAS,KAAK,GACjB;CAGF,IACE,OAAO,MAAM,WAAW,YACxB,OAAO,KAAK,KAAK,CAAC,CAAC,OAAO,QAAQ,QAAQ,KAAK,GAC/C;EACA,WAAW,IAAI,MAAM,MAAM;EAC3B;CACF;CAEA,KAAK,MAAM,eAAe,OAAO,OAAO,KAAK,GAC3C,kBAAkB,aAAa,UAAU;AAE7C;AAEA,MAAa,mBACX,OACA,UAEI,CAAC,MACkB;CACvB,MAAM,QAAQ,MAAM,QAAQ,MAAM,SAAS,IAAI,MAAM,YAAY,CAAC;CAElE,MAAM,aAAqC,CAAC;CAC5C,MAAM,6BAAa,IAAI,IAAY;CAEnC,MAAM,iBAAiB,MAAM,KAAK,SAAS;EACzC,MAAM,QAAQ,SAAS,IAAI;EAE3B,KAAK,MAAM,QAAQ,OACjB,WAAW,SAAS,WAAW,SAAS,KAAK;EAG/C,kBAAkB,MAAM,UAAU;EAElC,OAAO;GACL,IAAI,OAAO,KAAK,WAAW,WAAW,KAAK,SAAS,KAAA;GACpD;GACA,YAAY,OAAO,KAAK,IAAI,CAAC,CAC1B,QAAQ,aAAa,CAAC,SAAS,WAAW,UAAU,CAAC,CAAC,CACtD,KAAK;EACV;CACF,CAAC;CAED,MAAM,WAAW,IAAI,IACnB,MACG,KAAK,SAAS,KAAK,MAAM,CAAC,CAC1B,QAAQ,OAAqB,OAAO,OAAO,QAAQ,CACxD;CAEA,MAAM,uBAAuB,CAAC,GAAG,UAAU,CAAC,CACzC,QAAQ,cAAc;EACrB,IAAI,SAAS,IAAI,SAAS,GACxB,OAAO;EAIT,IAAI,UAAU,WAAW,GAAG,GAC1B,OAAO;EAGT,IAAI,CAAC,QAAQ,SACX,OAAO;EAGT,IAAI;GACF,MAAM,SAAS,IAAI,IAAI,SAAS;GAChC,MAAM,OAAO,IAAI,IAAI,QAAQ,OAAO;GAEpC,OAAO,OAAO,WAAW,KAAK;EAChC,QAAQ;GACN,OAAO;EACT;CACF,CAAC,CAAC,CACD,KAAK;CAER,MAAM,aAAaA,cAAAA,iBAAiB,OAAO;EACzC,SAAS,QAAQ;EACjB,kBAAkB;EAClB,2BAA2B;CAC7B,CAAC;CAED,OAAO;EACL,WAAW,MAAM;EACjB;EACA,OAAO;EACP,YAAY,CAAC,GAAG,UAAU,CAAC,CAAC,KAAK;EACjC;EACA,OAAO,WAAW;CACpB;AACF"}

package/dist/testing/inspect.d.cts

@@ -0,0 +1,5 @@
+import { SeoGraph } from "../core/types.cjs";
+import { SeoGraphInspection } from "./types.cjs";
+export declare const inspectSeoGraph: (graph: SeoGraph, options?: {
+  baseUrl?: string;
+}) => SeoGraphInspection;

package/dist/testing/inspect.d.ts

@@ -0,0 +1,5 @@
+import { SeoGraph } from "../core/types.js";
+import { SeoGraphInspection } from "./types.js";
+export declare const inspectSeoGraph: (graph: SeoGraph, options?: {
+  baseUrl?: string;
+}) => SeoGraphInspection;

package/dist/testing/inspect.js

@@ -0,0 +1,63 @@
+import { validateSeoGraph } from "../core/graph.js";
+// src/testing/inspect.ts
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const getTypes = (node) => {
+	const value = node["@type"];
+	return (Array.isArray(value) ? value : [value]).filter((type) => typeof type === "string" && type.length > 0).map((type) => type.split("/").pop() ?? type).sort();
+};
+const collectReferences = (value, references) => {
+	if (Array.isArray(value)) {
+		for (const item of value) collectReferences(item, references);
+		return;
+	}
+	if (!isObject(value)) return;
+	if (typeof value["@id"] === "string" && Object.keys(value).every((key) => key === "@id")) {
+		references.add(value["@id"]);
+		return;
+	}
+	for (const nestedValue of Object.values(value)) collectReferences(nestedValue, references);
+};
+const inspectSeoGraph = (graph, options = {}) => {
+	const nodes = Array.isArray(graph["@graph"]) ? graph["@graph"] : [];
+	const typeCounts = {};
+	const references = /* @__PURE__ */ new Set();
+	const inspectedNodes = nodes.map((node) => {
+		const types = getTypes(node);
+		for (const type of types) typeCounts[type] = (typeCounts[type] ?? 0) + 1;
+		collectReferences(node, references);
+		return {
+			id: typeof node["@id"] === "string" ? node["@id"] : void 0,
+			types,
+			properties: Object.keys(node).filter((property) => !property.startsWith("__puzzle")).sort()
+		};
+	});
+	const graphIds = new Set(nodes.map((node) => node["@id"]).filter((id) => typeof id === "string"));
+	const unresolvedReferences = [...references].filter((reference) => {
+		if (graphIds.has(reference)) return false;
+		if (reference.startsWith("#")) return true;
+		if (!options.baseUrl) return false;
+		try {
+			const target = new URL(reference);
+			const base = new URL(options.baseUrl);
+			return target.origin === base.origin;
+		} catch {
+			return false;
+		}
+	}).sort();
+	const validation = validateSeoGraph(graph, {
+		baseUrl: options.baseUrl,
+		strictReferences: true,
+		allowedExternalReferences: true
+	});
+	return {
+		nodeCount: nodes.length,
+		typeCounts,
+		nodes: inspectedNodes,
+		references: [...references].sort(),
+		unresolvedReferences,
+		valid: validation.valid
+	};
+};
+export { inspectSeoGraph };
+
+//# sourceMappingURL=inspect.js.map

package/dist/testing/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","names":[],"sources":["../../src/testing/inspect.ts"],"sourcesContent":["import type { SeoGraph, SeoNode } from \"../core/types\";\n\nimport { validateSeoGraph } from \"../core\";\n\nimport type { SeoGraphInspection } from \"./types\";\n\nconst isObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nconst getTypes = (node: SeoNode): string[] => {\n  const value = node[\"@type\"];\n  const types = Array.isArray(value) ? value : [value];\n\n  return types\n    .filter(\n      (type): type is string => typeof type === \"string\" && type.length > 0,\n    )\n    .map((type) => type.split(\"/\").pop() ?? type)\n    .sort();\n};\n\nconst collectReferences = (value: unknown, references: Set<string>): void => {\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      collectReferences(item, references);\n    }\n\n    return;\n  }\n\n  if (!isObject(value)) {\n    return;\n  }\n\n  if (\n    typeof value[\"@id\"] === \"string\" &&\n    Object.keys(value).every((key) => key === \"@id\")\n  ) {\n    references.add(value[\"@id\"]);\n    return;\n  }\n\n  for (const nestedValue of Object.values(value)) {\n    collectReferences(nestedValue, references);\n  }\n};\n\nexport const inspectSeoGraph = (\n  graph: SeoGraph,\n  options: {\n    baseUrl?: string;\n  } = {},\n): SeoGraphInspection => {\n  const nodes = Array.isArray(graph[\"@graph\"]) ? graph[\"@graph\"] : [];\n\n  const typeCounts: Record<string, number> = {};\n  const references = new Set<string>();\n\n  const inspectedNodes = nodes.map((node) => {\n    const types = getTypes(node);\n\n    for (const type of types) {\n      typeCounts[type] = (typeCounts[type] ?? 0) + 1;\n    }\n\n    collectReferences(node, references);\n\n    return {\n      id: typeof node[\"@id\"] === \"string\" ? node[\"@id\"] : undefined,\n      types,\n      properties: Object.keys(node)\n        .filter((property) => !property.startsWith(\"__puzzle\"))\n        .sort(),\n    };\n  });\n\n  const graphIds = new Set(\n    nodes\n      .map((node) => node[\"@id\"])\n      .filter((id): id is string => typeof id === \"string\"),\n  );\n\n  const unresolvedReferences = [...references]\n    .filter((reference) => {\n      if (graphIds.has(reference)) {\n        return false;\n      }\n\n      // Only local references are considered unresolved.\n      if (reference.startsWith(\"#\")) {\n        return true;\n      }\n\n      if (!options.baseUrl) {\n        return false;\n      }\n\n      try {\n        const target = new URL(reference);\n        const base = new URL(options.baseUrl);\n\n        return target.origin === base.origin;\n      } catch {\n        return false;\n      }\n    })\n    .sort();\n\n  const validation = validateSeoGraph(graph, {\n    baseUrl: options.baseUrl,\n    strictReferences: true,\n    allowedExternalReferences: true,\n  });\n\n  return {\n    nodeCount: nodes.length,\n    typeCounts,\n    nodes: inspectedNodes,\n    references: [...references].sort(),\n    unresolvedReferences,\n    valid: validation.valid,\n  };\n};\n"],"mappings":";;AAMA,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAErE,MAAM,YAAY,SAA4B;CAC5C,MAAM,QAAQ,KAAK;CAGnB,QAFc,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK,EAAA,CAGhD,QACE,SAAyB,OAAO,SAAS,YAAY,KAAK,SAAS,CACtE,CAAC,CACA,KAAK,SAAS,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAC5C,KAAK;AACV;AAEA,MAAM,qBAAqB,OAAgB,eAAkC;CAC3E,IAAI,MAAM,QAAQ,KAAK,GAAG;EACxB,KAAK,MAAM,QAAQ,OACjB,kBAAkB,MAAM,UAAU;EAGpC;CACF;CAEA,IAAI,CAAC,SAAS,KAAK,GACjB;CAGF,IACE,OAAO,MAAM,WAAW,YACxB,OAAO,KAAK,KAAK,CAAC,CAAC,OAAO,QAAQ,QAAQ,KAAK,GAC/C;EACA,WAAW,IAAI,MAAM,MAAM;EAC3B;CACF;CAEA,KAAK,MAAM,eAAe,OAAO,OAAO,KAAK,GAC3C,kBAAkB,aAAa,UAAU;AAE7C;AAEA,MAAa,mBACX,OACA,UAEI,CAAC,MACkB;CACvB,MAAM,QAAQ,MAAM,QAAQ,MAAM,SAAS,IAAI,MAAM,YAAY,CAAC;CAElE,MAAM,aAAqC,CAAC;CAC5C,MAAM,6BAAa,IAAI,IAAY;CAEnC,MAAM,iBAAiB,MAAM,KAAK,SAAS;EACzC,MAAM,QAAQ,SAAS,IAAI;EAE3B,KAAK,MAAM,QAAQ,OACjB,WAAW,SAAS,WAAW,SAAS,KAAK;EAG/C,kBAAkB,MAAM,UAAU;EAElC,OAAO;GACL,IAAI,OAAO,KAAK,WAAW,WAAW,KAAK,SAAS,KAAA;GACpD;GACA,YAAY,OAAO,KAAK,IAAI,CAAC,CAC1B,QAAQ,aAAa,CAAC,SAAS,WAAW,UAAU,CAAC,CAAC,CACtD,KAAK;EACV;CACF,CAAC;CAED,MAAM,WAAW,IAAI,IACnB,MACG,KAAK,SAAS,KAAK,MAAM,CAAC,CAC1B,QAAQ,OAAqB,OAAO,OAAO,QAAQ,CACxD;CAEA,MAAM,uBAAuB,CAAC,GAAG,UAAU,CAAC,CACzC,QAAQ,cAAc;EACrB,IAAI,SAAS,IAAI,SAAS,GACxB,OAAO;EAIT,IAAI,UAAU,WAAW,GAAG,GAC1B,OAAO;EAGT,IAAI,CAAC,QAAQ,SACX,OAAO;EAGT,IAAI;GACF,MAAM,SAAS,IAAI,IAAI,SAAS;GAChC,MAAM,OAAO,IAAI,IAAI,QAAQ,OAAO;GAEpC,OAAO,OAAO,WAAW,KAAK;EAChC,QAAQ;GACN,OAAO;EACT;CACF,CAAC,CAAC,CACD,KAAK;CAER,MAAM,aAAa,iBAAiB,OAAO;EACzC,SAAS,QAAQ;EACjB,kBAAkB;EAClB,2BAA2B;CAC7B,CAAC;CAED,OAAO;EACL,WAAW,MAAM;EACjB;EACA,OAAO;EACP,YAAY,CAAC,GAAG,UAAU,CAAC,CAAC,KAAK;EACjC;EACA,OAAO,WAAW;CACpB;AACF"}

package/dist/testing/types.d.cts

@@ -0,0 +1,40 @@
+import { SeoConfig } from "../context/types.cjs";
+import { SeoGraph, SeoNode } from "../core/types.cjs";
+import { SeoPageMetadata } from "../metadata/types.cjs";
+import { SeoValidationReport } from "../validation/types.cjs";
+export interface SeoTestFixture {
+  config: SeoConfig;
+  nodes?: SeoNode[];
+  graph?: SeoGraph;
+  metadata?: SeoPageMetadata;
+}
+export interface SeoTestResult {
+  passed: boolean;
+  errors: string[];
+  warnings: string[];
+  report: SeoValidationReport;
+}
+export interface SeoTestOptions {
+  strict?: boolean;
+  validateSchema?: boolean;
+  validateMetadata?: boolean;
+  validateReferences?: boolean;
+}
+export interface SeoGraphNodeInspection {
+  id?: string;
+  types: string[];
+  properties: string[];
+}
+export interface SeoGraphInspection {
+  nodeCount: number;
+  typeCounts: Record<string, number>;
+  nodes: SeoGraphNodeInspection[];
+  references: string[];
+  unresolvedReferences: string[];
+  valid: boolean;
+}
+export interface SeoDiagnosticFormatOptions {
+  includeSuggestions?: boolean;
+  includePaths?: boolean;
+  includeSummary?: boolean;
+}

package/dist/testing/types.d.ts

@@ -0,0 +1,40 @@
+import { SeoConfig } from "../context/types.js";
+import { SeoGraph, SeoNode } from "../core/types.js";
+import { SeoPageMetadata } from "../metadata/types.js";
+import { SeoValidationReport } from "../validation/types.js";
+export interface SeoTestFixture {
+  config: SeoConfig;
+  nodes?: SeoNode[];
+  graph?: SeoGraph;
+  metadata?: SeoPageMetadata;
+}
+export interface SeoTestResult {
+  passed: boolean;
+  errors: string[];
+  warnings: string[];
+  report: SeoValidationReport;
+}
+export interface SeoTestOptions {
+  strict?: boolean;
+  validateSchema?: boolean;
+  validateMetadata?: boolean;
+  validateReferences?: boolean;
+}
+export interface SeoGraphNodeInspection {
+  id?: string;
+  types: string[];
+  properties: string[];
+}
+export interface SeoGraphInspection {
+  nodeCount: number;
+  typeCounts: Record<string, number>;
+  nodes: SeoGraphNodeInspection[];
+  references: string[];
+  unresolvedReferences: string[];
+  valid: boolean;
+}
+export interface SeoDiagnosticFormatOptions {
+  includeSuggestions?: boolean;
+  includePaths?: boolean;
+  includeSummary?: boolean;
+}

package/dist/urls/index.cjs

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_normalize = require("./normalize.cjs");
+exports.isSameSeoOrigin = require_normalize.isSameSeoOrigin;
+exports.isValidSeoUrl = require_normalize.isValidSeoUrl;
+exports.normalizeSeoOrigin = require_normalize.normalizeSeoOrigin;
+exports.normalizeSeoPath = require_normalize.normalizeSeoPath;
+exports.normalizeSeoUrl = require_normalize.normalizeSeoUrl;
+exports.resolveSeoUrls = require_normalize.resolveSeoUrls;

package/dist/urls/index.d.cts

@@ -0,0 +1,3 @@
+import { SeoOriginOptions, SeoUrlOptions, SeoUrlResult, SeoUrlValidationIssue } from "./types.cjs";
+import { isSameSeoOrigin, isValidSeoUrl, normalizeSeoOrigin, normalizeSeoPath, normalizeSeoUrl, resolveSeoUrls } from "./normalize.cjs";
+export { type SeoOriginOptions, type SeoUrlOptions, type SeoUrlResult, type SeoUrlValidationIssue, isSameSeoOrigin, isValidSeoUrl, normalizeSeoOrigin, normalizeSeoPath, normalizeSeoUrl, resolveSeoUrls };

package/dist/urls/index.d.ts

@@ -0,0 +1,3 @@
+import { SeoOriginOptions, SeoUrlOptions, SeoUrlResult, SeoUrlValidationIssue } from "./types.js";
+import { isSameSeoOrigin, isValidSeoUrl, normalizeSeoOrigin, normalizeSeoPath, normalizeSeoUrl, resolveSeoUrls } from "./normalize.js";
+export { type SeoOriginOptions, type SeoUrlOptions, type SeoUrlResult, type SeoUrlValidationIssue, isSameSeoOrigin, isValidSeoUrl, normalizeSeoOrigin, normalizeSeoPath, normalizeSeoUrl, resolveSeoUrls };

package/dist/urls/index.js

@@ -0,0 +1 @@
+export { isSameSeoOrigin, isValidSeoUrl, normalizeSeoOrigin, normalizeSeoPath, normalizeSeoUrl, resolveSeoUrls } from "./normalize.js";