@pas7/llm-seo 0.1.6 → 0.3.0

package/README.md

@@ -12,6 +12,7 @@ Deterministic LLM SEO artifacts generator & validator for modern static sites (N
 One config in, deterministic artifacts out:
 - generate `llms.txt` and `llms-full.txt`
 - build canonical URLs from manifest items
+- support mixed routing per manifest section (`prefix`, `suffix`, `locale-segment`, `custom`)
 - lint policy constraints (restricted claims, duplicates, empty sections)
 - check generated files in CI with explicit exit codes
 
@@ -42,10 +43,18 @@ export default {
     hubs: ['/services', '/blog', '/projects', '/cases', '/contact'],
   },
   manifests: {
-    blog: [
-      { slug: '/blog/llm-seo-basics', locales: ['en', 'uk'] },
-      { slug: '/blog/canonical-strategy', locales: ['en'] },
-    ],
+    blog: {
+      sectionPath: '/blog',
+      routeStyle: 'locale-segment',
+      items: [
+        { slug: '/llm-seo-basics', locales: ['en', 'uk'] },
+        { slug: '/canonical-strategy', locales: ['en'] },
+      ],
+    },
+    contactPages: {
+      routeStyle: 'suffix',
+      items: [{ slug: '/contact', locales: ['en', 'uk'] }],
+    },
   },
   contact: {
     email: 'contact@example.com',
@@ -101,6 +110,7 @@ llm-seo check [options]
 Options:
   -c, --config <path>   Path to config file
   --fail-on <level>     fail threshold: warn|error (default: error)
+  --check-machine-hints-live  Live-check machine hint URLs over HTTP
   -v, --verbose         Verbose logs
 ```
 
@@ -146,6 +156,18 @@ import {
 
 Use helpers from `@pas7/llm-seo/adapters/next` to normalize manifest items and build scripts.
 See [`examples/next-static-export`](./examples/next-static-export).
+For hybrid section routing, use `createSectionManifest(...)` and `applySectionCanonicalOverrides(...)`.
+Works with `@pas7/nextjs-sitemap-hreflang` in one build pipeline:
+
+```bash
+llm-seo generate --config llm-seo.config.ts
+next build
+nextjs-sitemap-hreflang check --in out/sitemap.xml --fail-on-missing
+llm-seo check --config llm-seo.config.ts --fail-on error
+```
+
+Hybrid routing example:
+- [`examples/next-static-export-hybrid-routing`](./examples/next-static-export-hybrid-routing)
 
 ## Contributing and Security
 

package/dist/adapters/index.d.ts

@@ -1,3 +1,4 @@
-export { BuildHookOptions, BuildHookResult, BuildScriptsResult, CreateManifestFromDataOptions, CreateManifestFromPagesDirOptions, CreateNextConfigOptions, CreateRobotsLlmsPolicySnippetOptions, FromNextContentManifestOptions, GenerateBuildScriptsOptions, NextConfigResult, NextContentManifest, NextManifestOptions, createManifestFromData, createManifestFromPagesDir, createNextConfig, createNextPlugin, createRobotsLlmsPolicySnippet, extractPagePaths, fromNextContentManifest, generateBuildScripts, generateNextManifest, postBuildHook } from './next/index.js';
-import '../manifest.schema-B_z3rxRV.js';
+export { ApplySectionCanonicalOverridesOptions, BuildHookOptions, BuildHookResult, BuildScriptsResult, CreateManifestFromDataOptions, CreateManifestFromPagesDirOptions, CreateNextConfigOptions, CreateRobotsLlmsPolicySnippetOptions, CreateSectionManifestOptions, FromNextContentManifestOptions, GenerateBuildScriptsOptions, NextConfigResult, NextContentManifest, NextManifestOptions, SectionFieldMapper, applySectionCanonicalOverrides, createManifestFromData, createManifestFromPagesDir, createNextConfig, createNextPlugin, createRobotsLlmsPolicySnippet, createSectionManifest, extractPagePaths, fromNextContentManifest, generateBuildScripts, generateNextManifest, postBuildHook } from './next/index.js';
+import '../config.schema-CI5OBbhQ.js';
 import 'zod';
+import '../canonical-from-manifest-BKpEmouS.js';

package/dist/adapters/index.js

@@ -2,6 +2,230 @@ import { existsSync } from 'fs';
 import { readFile, readdir } from 'fs/promises';
 import { join } from 'path';
 
+// src/adapters/next/manifest.ts
+
+// src/core/normalize/url.ts
+function normalizePath(path, preserveTrailingSlash = false) {
+  if (!path || path === "/") {
+    return "/";
+  }
+  const hadTrailingSlash = path.endsWith("/") && path !== "/";
+  let normalized = path.startsWith("/") ? path : `/${path}`;
+  normalized = normalized.replace(/\/{2,}/g, "/");
+  const segments = [];
+  const parts = normalized.split("/");
+  for (const part of parts) {
+    if (part === "." || part === "") {
+      continue;
+    } else if (part === "..") {
+      if (segments.length > 0) {
+        segments.pop();
+      }
+    } else {
+      segments.push(part);
+    }
+  }
+  let result = "/" + segments.join("/");
+  if (preserveTrailingSlash && hadTrailingSlash && result !== "/") {
+    result += "/";
+  }
+  return result;
+}
+function joinUrlParts(...parts) {
+  if (parts.length === 0) {
+    return "/";
+  }
+  const filteredParts = parts.filter((part) => part.length > 0);
+  if (filteredParts.length === 0) {
+    return "/";
+  }
+  const joined = filteredParts.map((part) => {
+    let p = part.replace(/^\/+/, "");
+    p = p.replace(/\/+$/, "");
+    return p;
+  }).filter((p) => p.length > 0).join("/");
+  return joined.length > 0 ? `/${joined}` : "/";
+}
+function normalizeUrl(options) {
+  const { baseUrl, path, trailingSlash, stripQuery = true, stripHash = true } = options;
+  let parsedBase;
+  try {
+    parsedBase = new URL(baseUrl);
+  } catch {
+    throw new TypeError(`Invalid baseUrl: ${baseUrl}`);
+  }
+  const shouldPreserveTrailingSlash = trailingSlash === "preserve";
+  const normalizedPath = normalizePath(path, shouldPreserveTrailingSlash);
+  let finalPath = normalizedPath;
+  if (trailingSlash === "always") {
+    if (!finalPath.endsWith("/")) {
+      finalPath = `${finalPath}/`;
+    }
+  } else if (trailingSlash === "never") {
+    if (finalPath !== "/" && finalPath.endsWith("/")) {
+      finalPath = finalPath.slice(0, -1);
+    }
+  }
+  const protocol = parsedBase.protocol.toLowerCase();
+  let hostname = parsedBase.hostname.toLowerCase();
+  let port = parsedBase.port;
+  if (port) {
+    const isDefaultPort = protocol === "http:" && port === "80" || protocol === "https:" && port === "443";
+    if (!isDefaultPort) {
+      hostname = `${hostname}:${port}`;
+    }
+  }
+  let fullUrl = `${protocol}//${hostname}${finalPath}`;
+  if (!stripQuery && parsedBase.search) {
+    fullUrl += parsedBase.search;
+  }
+  if (!stripHash && parsedBase.hash) {
+    fullUrl += parsedBase.hash;
+  }
+  return fullUrl;
+}
+
+// src/core/normalize/sort.ts
+function compareStrings(a, b) {
+  return a.localeCompare(b, "en", { sensitivity: "case", numeric: true });
+}
+function sortStrings(items) {
+  return [...items].sort(compareStrings);
+}
+function sortBy(items, keyFn) {
+  return [...items].sort((a, b) => compareStrings(keyFn(a), keyFn(b)));
+}
+function stableSortStrings(items) {
+  return [...items].sort((a, b) => a.localeCompare(b, "en", { sensitivity: "case", numeric: true }));
+}
+
+// src/core/canonical/locale.ts
+function selectCanonicalLocale(options) {
+  const { defaultLocale, availableLocales } = options;
+  if (!availableLocales || availableLocales.length === 0) {
+    return null;
+  }
+  const validLocales = availableLocales.filter(
+    (locale) => typeof locale === "string" && locale.length > 0
+  );
+  if (validLocales.length === 0) {
+    return null;
+  }
+  if (defaultLocale && validLocales.includes(defaultLocale)) {
+    return defaultLocale;
+  }
+  const sorted = stableSortStrings(validLocales);
+  return sorted[0] ?? null;
+}
+
+// src/core/canonical/canonical-from-manifest.ts
+function buildBaseUrlWithSubdomain(baseUrl, locale, strategy, defaultLocale) {
+  if (strategy !== "subdomain" || locale === defaultLocale) {
+    return baseUrl;
+  }
+  try {
+    const parsed = new URL(baseUrl);
+    return `${parsed.protocol}//${locale}.${parsed.host}`;
+  } catch {
+    return baseUrl;
+  }
+}
+function createCanonicalUrlForItem(item, options) {
+  const {
+    baseUrl,
+    routePrefix,
+    defaultLocale,
+    trailingSlash,
+    localeStrategy,
+    routeStyle,
+    sectionName,
+    sectionPath,
+    pathnameFor
+  } = options;
+  if (item.canonicalOverride && typeof item.canonicalOverride === "string") {
+    return item.canonicalOverride;
+  }
+  const availableLocales = item.locales ?? [defaultLocale];
+  const canonicalLocale = selectCanonicalLocale({
+    defaultLocale,
+    availableLocales
+  });
+  const locale = canonicalLocale ?? defaultLocale;
+  const sectionBase = normalizeSectionPath(sectionPath ?? routePrefix ?? "");
+  const effectiveRouteStyle = routeStyle ?? inferRouteStyleFromLocaleStrategy(localeStrategy);
+  const normalizedSlug = normalizeItemSlug(item.slug, sectionBase);
+  const customPath = effectiveRouteStyle === "custom" ? pathnameFor?.({
+    item,
+    sectionName: sectionName ?? "",
+    slug: normalizedSlug,
+    locale,
+    defaultLocale,
+    sectionPath: sectionBase
+  }) : void 0;
+  const resolvedPath = customPath ?? buildPathFromRouteStyle({
+    routeStyle: effectiveRouteStyle,
+    sectionPath: sectionBase,
+    slug: normalizedSlug,
+    locale,
+    defaultLocale
+  });
+  const effectiveBaseUrl = buildBaseUrlWithSubdomain(baseUrl, locale, localeStrategy, defaultLocale);
+  return normalizeUrl({
+    baseUrl: effectiveBaseUrl,
+    path: resolvedPath,
+    trailingSlash,
+    stripQuery: true,
+    stripHash: true
+  });
+}
+function inferRouteStyleFromLocaleStrategy(strategy) {
+  if (strategy !== "prefix") {
+    return "custom";
+  }
+  return "prefix";
+}
+function buildPathFromRouteStyle(args) {
+  const { routeStyle, sectionPath, slug, locale, defaultLocale } = args;
+  const includeLocale = locale !== defaultLocale;
+  if (routeStyle === "locale-segment") {
+    return joinUrlParts(sectionPath, locale, slug);
+  }
+  if (routeStyle === "suffix") {
+    if (includeLocale) {
+      return joinUrlParts(sectionPath, slug, locale);
+    }
+    return joinUrlParts(sectionPath, slug);
+  }
+  if (routeStyle === "custom") {
+    return joinUrlParts(sectionPath, slug);
+  }
+  if (includeLocale) {
+    return joinUrlParts(locale, sectionPath, slug);
+  }
+  return joinUrlParts(sectionPath, slug);
+}
+function normalizeSectionPath(sectionPath) {
+  if (!sectionPath || sectionPath === "/") {
+    return "";
+  }
+  return sectionPath.startsWith("/") ? sectionPath : `/${sectionPath}`;
+}
+function normalizeItemSlug(slug, sectionPath) {
+  const normalizedSlug = slug.startsWith("/") ? slug : `/${slug}`;
+  if (!sectionPath) {
+    return normalizedSlug;
+  }
+  if (normalizedSlug === sectionPath) {
+    return "/";
+  }
+  const withSlash = `${sectionPath}/`;
+  if (normalizedSlug.startsWith(withSlash)) {
+    const relative = normalizedSlug.slice(withSlash.length);
+    return relative ? `/${relative}` : "/";
+  }
+  return normalizedSlug;
+}
+
 // src/adapters/next/manifest.ts
 function fromNextContentManifest(manifest, options = {}) {
   const { slugPrefix = "", defaultLocale } = options;
@@ -35,6 +259,132 @@ function fromNextContentManifest(manifest, options = {}) {
     return result;
   });
 }
+function createSectionManifest(options) {
+  const {
+    items,
+    sectionName,
+    sectionPath,
+    routeStyle,
+    defaultLocale,
+    defaultLocaleOverride,
+    pathnameFor,
+    slugKey = "slug",
+    localesKey = "locales",
+    updatedAtKey = "updatedAt",
+    publishedAtKey = "publishedAt",
+    priorityKey = "priority",
+    canonicalOverrideKey = "canonicalOverride",
+    titleFrom = "title",
+    descriptionFrom = "description"
+  } = options;
+  const normalizedItems = items.map((item) => {
+    const rawSlug = readStringField(item, slugKey);
+    if (!rawSlug) {
+      return null;
+    }
+    const normalized = {
+      slug: rawSlug.startsWith("/") ? rawSlug : `/${rawSlug}`
+    };
+    const locales = readStringArrayField(item, localesKey);
+    if (locales.length > 0) {
+      normalized.locales = locales;
+    } else if (defaultLocale) {
+      normalized.locales = [defaultLocale];
+    }
+    const updatedAt = readStringField(item, updatedAtKey);
+    if (updatedAt) {
+      normalized.updatedAt = updatedAt;
+    }
+    const publishedAt = readStringField(item, publishedAtKey);
+    if (publishedAt) {
+      normalized.publishedAt = publishedAt;
+    }
+    const priority = readNumberField(item, priorityKey);
+    if (priority !== void 0) {
+      normalized.priority = priority;
+    }
+    const canonicalOverride = readStringField(item, canonicalOverrideKey);
+    if (canonicalOverride) {
+      normalized.canonicalOverride = canonicalOverride;
+    }
+    const title = readMappedString(item, titleFrom);
+    if (title) {
+      normalized.title = title;
+    }
+    const description = readMappedString(item, descriptionFrom);
+    if (description) {
+      normalized.description = description;
+    }
+    return normalized;
+  }).filter((item) => item !== null);
+  const sortedItems = sortBy(normalizedItems, (item) => {
+    const locales = item.locales?.join(",") ?? "";
+    return `${item.slug}|${locales}`;
+  });
+  return {
+    items: sortedItems,
+    ...sectionName && { sectionName },
+    ...sectionPath && { sectionPath },
+    ...routeStyle && { routeStyle },
+    ...defaultLocaleOverride && { defaultLocaleOverride },
+    ...pathnameFor && { pathnameFor }
+  };
+}
+function applySectionCanonicalOverrides(options) {
+  const {
+    section,
+    baseUrl,
+    defaultLocale,
+    trailingSlash = "never",
+    localeStrategy = "prefix"
+  } = options;
+  const mappedItems = section.items.map((item) => {
+    const canonicalOptions = {
+      baseUrl,
+      defaultLocale: section.defaultLocaleOverride ?? defaultLocale,
+      trailingSlash,
+      localeStrategy,
+      ...section.routeStyle && { routeStyle: section.routeStyle },
+      ...section.sectionPath && {
+        sectionPath: section.sectionPath,
+        routePrefix: section.sectionPath
+      },
+      ...section.sectionName && { sectionName: section.sectionName },
+      ...section.pathnameFor && { pathnameFor: section.pathnameFor }
+    };
+    const canonicalOverride = createCanonicalUrlForItem(item, canonicalOptions);
+    return {
+      ...item,
+      canonicalOverride
+    };
+  });
+  return {
+    ...section,
+    items: mappedItems
+  };
+}
+function readStringField(item, key) {
+  const value = item[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function readNumberField(item, key) {
+  const value = item[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readStringArrayField(item, key) {
+  const value = item[key];
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+function readMappedString(item, mapper) {
+  if (typeof mapper === "function") {
+    const value = mapper(item);
+    return typeof value === "string" && value.length > 0 ? value : void 0;
+  }
+  return readStringField(item, mapper);
+}
 function parseFrontmatter(content) {
   const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
   const match = content.match(frontmatterRegex);
@@ -222,17 +572,6 @@ function generateNextManifest(options, buildManifest) {
   };
 }
 
-// src/core/normalize/sort.ts
-function compareStrings(a, b) {
-  return a.localeCompare(b, "en", { sensitivity: "case", numeric: true });
-}
-function sortStrings(items) {
-  return [...items].sort(compareStrings);
-}
-function sortBy(items, keyFn) {
-  return [...items].sort((a, b) => compareStrings(keyFn(a), keyFn(b)));
-}
-
 // src/core/normalize/text.ts
 function normalizeLineEndings(text, lineEndings) {
   const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
@@ -396,7 +735,7 @@ function generateLlmsTxt(manifest, _options) {
 
 // src/core/generate/llms-full-txt.ts
 function createLlmsFullTxt(options) {
-  const { config, canonicalUrls, manifestItems } = options;
+  const { config, canonicalUrls, manifestItems, manifestEntries } = options;
   const lineEndings = config.format?.lineEndings ?? "lf";
   const lines = [];
   lines.push(`# ${config.brand.name} - Full LLM Context`);
@@ -413,6 +752,10 @@ function createLlmsFullTxt(options) {
     lines.push(`Organization: ${config.brand.org}`);
   }
   lines.push(`Locales: ${config.brand.locales.join(", ")}`);
+  const lastUpdated = getLastUpdatedDate(manifestItems);
+  if (lastUpdated) {
+    lines.push(`Last Updated: ${lastUpdated}`);
+  }
   lines.push("");
   if (canonicalUrls.length > 0) {
     lines.push("## All Canonical URLs");
@@ -450,11 +793,16 @@ function createLlmsFullTxt(options) {
       lines.push("");
     }
   }
-  const hasSocial = config.contact?.social?.twitter || config.contact?.social?.linkedin || config.contact?.social?.github;
-  const hasBooking = config.booking?.url;
-  if (hasSocial || hasBooking) {
-    lines.push("## Social & Booking");
+  const hasContact = config.contact?.email || config.contact?.phone || config.contact?.social?.twitter || config.contact?.social?.linkedin || config.contact?.social?.github || config.booking?.url;
+  if (hasContact) {
+    lines.push("## Contact");
     lines.push("");
+    if (config.contact?.email) {
+      lines.push(`- Email: ${config.contact.email}`);
+    }
+    if (config.contact?.phone) {
+      lines.push(`- Phone: ${config.contact.phone}`);
+    }
     if (config.contact?.social?.twitter) {
       lines.push(`- Twitter: ${config.contact.social.twitter}`);
     }
@@ -498,7 +846,16 @@ function createLlmsFullTxt(options) {
         lines.push(`- [${hub}](${hub}) - ${getHubLabel2(hub)}`);
       }
     }
-    if (manifestItems.length > 0) {
+    if (manifestEntries && manifestEntries.length > 0) {
+      const sortedEntries = sortBy(manifestEntries, (entry) => {
+        return `${entry.item.slug}|${entry.canonicalUrl}`;
+      });
+      for (const entry of sortedEntries) {
+        const title = entry.item.title ?? entry.item.slug;
+        const locales = entry.item.locales?.join(", ") ?? config.brand.locales[0] ?? "en";
+        lines.push(`- [${title}](${entry.canonicalUrl}) (${locales})`);
+      }
+    } else if (manifestItems.length > 0) {
       const sortedItems = sortBy(manifestItems, (item) => item.slug);
       for (const item of sortedItems) {
         const url = item.canonicalOverride ?? `${config.site.baseUrl}${item.slug}`;
@@ -519,6 +876,24 @@ function createLlmsFullTxt(options) {
     lineCount: finalLines.length
   };
 }
+function getLastUpdatedDate(items) {
+  const timestamps = [];
+  for (const item of items) {
+    if (item.updatedAt) {
+      timestamps.push(item.updatedAt);
+    } else if (item.publishedAt) {
+      timestamps.push(item.publishedAt);
+    }
+  }
+  if (timestamps.length === 0) {
+    return null;
+  }
+  const latest = timestamps.map((value) => new Date(value)).filter((value) => !Number.isNaN(value.getTime())).sort((a, b) => b.getTime() - a.getTime())[0];
+  if (!latest) {
+    return null;
+  }
+  return latest.toISOString().slice(0, 10);
+}
 function getHubLabel2(hub) {
   const labels = {
     "/services": "Services overview",
@@ -668,6 +1043,6 @@ function createNextPlugin() {
   };
 }
 
-export { createManifestFromData, createManifestFromPagesDir, createNextConfig, createNextPlugin, createRobotsLlmsPolicySnippet, extractPagePaths, fromNextContentManifest, generateBuildScripts, generateNextManifest, postBuildHook };
+export { applySectionCanonicalOverrides, createManifestFromData, createManifestFromPagesDir, createNextConfig, createNextPlugin, createRobotsLlmsPolicySnippet, createSectionManifest, extractPagePaths, fromNextContentManifest, generateBuildScripts, generateNextManifest, postBuildHook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map