@seo-partner/adapters 0.0.0-stage → 1.0.3

package/src/ast-merger.ts

@@ -0,0 +1,123 @@
+export interface MetadataFields {
+  title?: string;
+  description?: string;
+  canonical?: string;
+  openGraph?: {
+    title?: string;
+    description?: string;
+    url?: string;
+    siteName?: string;
+  };
+}
+
+export interface AstMergeResult {
+  mergedCode: string;
+  modified: boolean;
+  hasComplexDynamicLogic: boolean;
+  isClientComponent: boolean;
+  changes: Array<{
+    field: string;
+    before?: string | null;
+    after: string;
+  }>;
+}
+
+export function mergePageMetadataInPlace(
+  sourceCode: string,
+  newMeta: MetadataFields,
+): AstMergeResult {
+  const isClientComponent = /^\s*['"]use client['"]/m.test(sourceCode);
+  const hasGenerateMetadata = /\bexport\s+(async\s+)?function\s+generateMetadata\b/.test(sourceCode);
+
+  if (hasGenerateMetadata) {
+    return {
+      mergedCode: sourceCode,
+      modified: false,
+      hasComplexDynamicLogic: true,
+      isClientComponent,
+      changes: [],
+    };
+  }
+
+  const changes: Array<{ field: string; before?: string | null; after: string }> = [];
+
+  // Match existing `export const metadata = { ... }` or `export const metadata: Metadata = { ... }`
+  const metadataRegex = /(export\s+const\s+metadata(?:\s*:\s*\w+)?\s*=\s*\{)([\s\S]*?)(\};?)/m;
+  const match = metadataRegex.exec(sourceCode);
+
+  if (match) {
+    const prefix = match[1] ?? '';
+    let body = match[2] ?? '';
+    const suffix = match[3] ?? '';
+
+    // Check title
+    if (newMeta.title && !/\btitle\s*:/m.test(body)) {
+      const val = newMeta.title;
+      body = `\n  title: '${val.replace(/'/g, "\\'")}',` + body;
+      changes.push({ field: 'title', before: null, after: val });
+    }
+
+    // Check description
+    if (newMeta.description && !/\bdescription\s*:/m.test(body)) {
+      const val = newMeta.description;
+      body = `\n  description: '${val.replace(/'/g, "\\'")}',` + body;
+      changes.push({ field: 'description', before: null, after: val });
+    }
+
+    // Check alternates / canonical
+    if (newMeta.canonical && !/\balternates\s*:/m.test(body)) {
+      const val = newMeta.canonical;
+      body = body + `\n  alternates: {\n    canonical: '${val}',\n  },`;
+      changes.push({ field: 'alternates.canonical', before: null, after: val });
+    }
+
+    // Check openGraph
+    if (newMeta.openGraph && !/\bopenGraph\s*:/m.test(body)) {
+      const ogTitle = newMeta.openGraph.title ?? newMeta.title ?? '';
+      const ogDesc = newMeta.openGraph.description ?? newMeta.description ?? '';
+      body = body + `\n  openGraph: {\n    title: '${ogTitle.replace(/'/g, "\\'")}',\n    description: '${ogDesc.replace(/'/g, "\\'")}',\n  },`;
+      changes.push({ field: 'openGraph', before: null, after: ogTitle });
+    }
+
+    const mergedCode = sourceCode.replace(metadataRegex, `${prefix}${body}\n${suffix}`);
+    return {
+      mergedCode,
+      modified: changes.length > 0,
+      hasComplexDynamicLogic: false,
+      isClientComponent,
+      changes,
+    };
+  }
+
+  // No existing metadata block: create one
+  const entries: string[] = [];
+  if (newMeta.title) {
+    entries.push(`  title: '${newMeta.title.replace(/'/g, "\\'")}',`);
+    changes.push({ field: 'title', before: null, after: newMeta.title });
+  }
+  if (newMeta.description) {
+    entries.push(`  description: '${newMeta.description.replace(/'/g, "\\'")}',`);
+    changes.push({ field: 'description', before: null, after: newMeta.description });
+  }
+  if (newMeta.canonical) {
+    entries.push(`  alternates: {\n    canonical: '${newMeta.canonical}',\n  },`);
+    changes.push({ field: 'alternates.canonical', before: null, after: newMeta.canonical });
+  }
+  if (newMeta.openGraph) {
+    const ogTitle = newMeta.openGraph.title ?? newMeta.title ?? '';
+    const ogDesc = newMeta.openGraph.description ?? newMeta.description ?? '';
+    entries.push(`  openGraph: {\n    title: '${ogTitle.replace(/'/g, "\\'")}',\n    description: '${ogDesc.replace(/'/g, "\\'")}',\n  },`);
+    changes.push({ field: 'openGraph', before: null, after: ogTitle });
+  }
+
+  const newExport = `\nexport const metadata = {\n${entries.join('\n')}\n};\n`;
+  const mergedCode = sourceCode + newExport;
+
+  return {
+    mergedCode,
+    modified: true,
+    hasComplexDynamicLogic: false,
+    isClientComponent,
+    changes,
+  };
+}

package/src/astro-adapter.ts

@@ -0,0 +1,155 @@
+import path from 'node:path';
+import type { DiscoveredRoute, ExtractedRouteData } from '@seo-partner/core';
+import type { AdapterCapabilities, AdapterVersion, FrameworkAdapter } from './contract.js';
+import { parseAstroOrMarkdown } from './parsers/astro-parser.js';
+import { normalizeRoutePattern } from './parsers/route-normalizer.js';
+import { LayoutResolver } from './parsers/layout-resolver.js';
+
+export class AstroAdapter implements FrameworkAdapter {
+  public readonly id = 'astro';
+  public readonly name = 'Astro';
+  public readonly version: AdapterVersion = '1.0';
+  public readonly capabilities: AdapterCapabilities = {
+    routes: true,
+    metadata: true,
+    headings: true,
+    internalLinks: true,
+    jsonLd: true,
+    images: true,
+    robotsAndSitemap: true,
+  };
+
+  private readonly layoutResolver = new LayoutResolver();
+
+  public async detect(
+    projectRoot: string,
+    filePaths: ReadonlyArray<string>,
+    contentsByPath: ReadonlyMap<string, string>,
+  ): Promise<boolean> {
+    for (const filePath of filePaths) {
+      const normalized = filePath.replace(/\\/g, '/');
+      if (
+        normalized === 'astro.config.mjs' ||
+        normalized === 'astro.config.ts' ||
+        normalized === 'astro.config.js' ||
+        normalized === 'astro.config.cjs'
+      ) {
+        return true;
+      }
+      if (normalized === 'package.json') {
+        const content = contentsByPath.get(filePath) ?? '';
+        if (content.includes('"astro"') || content.includes('"@astrojs/')) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  public async discoverRoutes(
+    projectRoot: string,
+    filePaths: ReadonlyArray<string>,
+    contentsByPath: ReadonlyMap<string, string>,
+    sitemapPaths: ReadonlySet<string>,
+  ): Promise<ReadonlyArray<DiscoveredRoute>> {
+    const routes: DiscoveredRoute[] = [];
+
+    // Pre-cache layouts from src/layouts/**
+    for (const filePath of filePaths) {
+      const normalized = filePath.replace(/\\/g, '/');
+      if (normalized.startsWith('src/layouts/') && normalized.endsWith('.astro')) {
+        const content = contentsByPath.get(filePath) ?? '';
+        const parsed = parseAstroOrMarkdown(
+          {
+            pattern: '',
+            filePath,
+            routerKind: 'astro',
+            renderingMode: 'static',
+            isPrivate: false,
+            inSitemap: false,
+          },
+          content,
+        );
+        this.layoutResolver.registerLayout({
+          filePath,
+          htmlLang: parsed.routeData.htmlLang,
+          title: parsed.routeData.title,
+          description: parsed.routeData.description,
+          canonical: parsed.routeData.canonical,
+          robots: parsed.routeData.robots,
+        });
+      }
+    }
+
+    for (const filePath of filePaths) {
+      const normalized = filePath.replace(/\\/g, '/');
+      if (!normalized.startsWith('src/pages/')) continue;
+      if (!/\.(astro|md|mdx|html)$/i.test(normalized)) continue;
+
+      const relativeInsidePages = normalized.slice('src/pages/'.length);
+      const pattern = normalizeRoutePattern(relativeInsidePages, 'astro');
+      const inSitemap = sitemapPaths.has(pattern);
+
+      routes.push({
+        pattern,
+        filePath,
+        routerKind: 'astro',
+        renderingMode: 'static',
+        isPrivate: false,
+        inSitemap,
+      });
+    }
+
+    return routes;
+  }
+
+  public async extractRoute(
+    projectRoot: string,
+    route: DiscoveredRoute,
+    fileContent: string,
+  ): Promise<ExtractedRouteData> {
+    const parsed = parseAstroOrMarkdown(route, fileContent);
+    let extracted = parsed.routeData;
+
+    // Apply layout inheritance: check layout candidates
+    const layoutCandidates = [
+      'src/layouts/BaseLayout.astro',
+      'src/layouts/Layout.astro',
+      'src/layouts/MainLayout.astro',
+      'src/layouts/DefaultLayout.astro',
+    ];
+    extracted = this.layoutResolver.applyInheritance(extracted, layoutCandidates);
+
+    return extracted;
+  }
+}
+
+
+export interface AstroMetaFields {
+  title?: string;
+  description?: string;
+  canonical?: string;
+}
+
+export function patchAstroTemplate(
+  sourceCode: string,
+  meta: AstroMetaFields,
+): string {
+  let result = sourceCode;
+
+  const entries: string[] = [];
+  if (meta.title) entries.push(`title: "${meta.title.replace(/"/g, '\\"')}"`);
+  if (meta.description) entries.push(`description: "${meta.description.replace(/"/g, '\\"')}"`);
+  if (meta.canonical) entries.push(`canonical: "${meta.canonical}"`);
+
+  const seoVarBlock = `const seoMeta = {\n  ${entries.join(',\n  ')}\n};\n`;
+
+  const frontmatterMatch = /^---\s*\n([\s\S]*?)\n---/m.exec(result);
+  if (frontmatterMatch) {
+    result = result.replace(/^---\s*\n/m, `---\n${seoVarBlock}`);
+  } else {
+    result = `---\n${seoVarBlock}---\n\n` + result;
+  }
+
+  return result;
+}

package/src/blog-scaffold-generator.ts

@@ -0,0 +1,153 @@
+import type { FrameworkType } from '@seo-partner/core';
+
+export interface BlogScaffoldFile {
+  relativePath: string;
+  code: string;
+  description: string;
+}
+
+export function generateBlogScaffold(
+  framework: FrameworkType,
+  pillarTitle = 'Actualités et Guides SEO',
+): BlogScaffoldFile[] {
+  switch (framework) {
+    case 'next_app':
+      return [
+        {
+          relativePath: 'app/blog/page.tsx',
+          code: `import type { Metadata } from 'next';
+import Link from 'next/link';
+
+export const metadata: Metadata = {
+  title: '${pillarTitle} | Blog',
+  description: 'Découvrez nos guides d\\\'experts et analyses approfondies.',
+  alternates: {
+    canonical: '/blog',
+  },
+};
+
+export default function BlogIndexPage() {
+  return (
+    <main className="max-w-4xl mx-auto py-12 px-4">
+      <h1 className="text-3xl font-bold mb-8">${pillarTitle}</h1>
+      <p className="text-gray-600 mb-6">Explorez nos articles et guides complets pour approfondir vos compétences.</p>
+    </main>
+  );
+}
+`,
+          description: 'Page d\'index du blog Next.js App Router',
+        },
+        {
+          relativePath: 'app/blog/[slug]/page.tsx',
+          code: `import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+
+interface Props {
+  params: { slug: string };
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  return {
+    title: \`Article: \${params.slug} | Blog\`,
+    description: 'Guide complet et recommandations pratiques.',
+  };
+}
+
+export default function BlogPostPage({ params }: Props) {
+  return (
+    <article className="max-w-3xl mx-auto py-12 px-4 prose">
+      <h1>Détail de l\\\'article : {params.slug}</h1>
+    </article>
+  );
+}
+`,
+          description: 'Route dynamique d\'article Next.js App Router',
+        },
+      ];
+
+    case 'nuxt':
+      return [
+        {
+          relativePath: 'pages/blog/index.vue',
+          code: `<script setup lang="ts">
+useSeoMeta({
+  title: '${pillarTitle} | Blog',
+  description: 'Guides d\\\'experts et ressources pratiques.',
+});
+</script>
+
+<template>
+  <main class="blog-index">
+    <h1>${pillarTitle}</h1>
+  </main>
+</template>
+`,
+          description: 'Page d\'index du blog Nuxt 3',
+        },
+      ];
+
+    case 'astro':
+      return [
+        {
+          relativePath: 'src/pages/blog/index.astro',
+          code: `---
+const pageTitle = "${pillarTitle}";
+---
+<html>
+  <head>
+    <title>{pageTitle}</title>
+    <meta name="description" content="Guides et analyses éditoriales d\\\'experts." />
+  </head>
+  <body>
+    <main>
+      <h1>{pageTitle}</h1>
+    </main>
+  </body>
+</html>
+`,
+          description: 'Page d\'index du blog Astro',
+        },
+      ];
+
+    case 'laravel':
+      return [
+        {
+          relativePath: 'resources/views/blog/index.blade.php',
+          code: `@extends('layouts.app')
+
+@section('title', '${pillarTitle}')
+
+@push('meta')
+  <meta name="description" content="Retrouvez nos guides et articles spécialisés.">
+@endpush
+
+@section('content')
+  <div class="container py-5">
+    <h1>${pillarTitle}</h1>
+  </div>
+@endsection
+`,
+          description: 'Vue d\'index du blog Laravel Blade',
+        },
+      ];
+
+    default:
+      return [
+        {
+          relativePath: 'blog/index.php',
+          code: `<?php
+$pageTitle = '${pillarTitle}';
+$metaDescription = 'Guides et ressources d\\\'experts.';
+require_once __DIR__ . '/../includes/header.php';
+?>
+<main class="container">
+  <h1><?php echo htmlspecialchars($pageTitle); ?></h1>
+</main>
+<?php require_once __DIR__ . '/../includes/footer.php'; ?>
+`,
+          description: 'Script d\'index du blog PHP',
+        },
+      ];
+  }
+}
+

package/src/contract.ts

@@ -0,0 +1,40 @@
+import type { DiscoveredRoute, ExtractedRouteData } from '@seo-partner/core';
+
+export type AdapterVersion = '1.0';
+
+export interface AdapterCapabilities {
+  readonly routes: boolean;
+  readonly metadata: boolean;
+  readonly headings: boolean;
+  readonly internalLinks: boolean;
+  readonly jsonLd: boolean;
+  readonly images: boolean;
+  readonly robotsAndSitemap: boolean;
+}
+
+export interface FrameworkAdapter {
+  readonly id: string;
+  readonly name: string;
+  readonly version: AdapterVersion;
+  readonly capabilities: AdapterCapabilities;
+
+  detect(
+    projectRoot: string,
+    filePaths: ReadonlyArray<string>,
+    contentsByPath: ReadonlyMap<string, string>,
+  ): Promise<boolean>;
+
+  discoverRoutes(
+    projectRoot: string,
+    filePaths: ReadonlyArray<string>,
+    contentsByPath: ReadonlyMap<string, string>,
+    sitemapPaths: ReadonlySet<string>,
+  ): Promise<ReadonlyArray<DiscoveredRoute>>;
+
+  extractRoute(
+    projectRoot: string,
+    route: DiscoveredRoute,
+    fileContent: string,
+  ): Promise<ExtractedRouteData>;
+}
+

package/src/detector.ts

@@ -0,0 +1,46 @@
+import type { FrameworkAdapter } from './contract.js';
+import { NextJsAdapter } from './nextjs-adapter.js';
+import { AstroAdapter } from './astro-adapter.js';
+import { NuxtAdapter } from './nuxt-adapter.js';
+import { SvelteKitAdapter } from './sveltekit-adapter.js';
+import { RemixAdapter } from './remix-adapter.js';
+import { PhpAdapter } from './php-adapter.js';
+import { DjangoAdapter } from './django-adapter.js';
+import { StaticAdapter } from './static-adapter.js';
+
+/**
+ * Detection order contract (strictly prioritized to avoid ambiguities):
+ * 1. Next.js
+ * 2. Astro
+ * 3. Nuxt 3
+ * 4. SvelteKit
+ * 5. Remix / React Router v7
+ * 6. PHP (Laravel / Symfony / Native)
+ * 7. Django (Python)
+ * 8. Static HTML
+ */
+export const BUILTIN_ADAPTERS: ReadonlyArray<FrameworkAdapter> = [
+  new NextJsAdapter(),
+  new AstroAdapter(),
+  new NuxtAdapter(),
+  new SvelteKitAdapter(),
+  new RemixAdapter(),
+  new PhpAdapter(),
+  new DjangoAdapter(),
+  new StaticAdapter(),
+];
+
+export async function detectActiveAdapters(
+  projectRoot: string,
+  filePaths: ReadonlyArray<string>,
+  contentsByPath: ReadonlyMap<string, string>,
+): Promise<ReadonlyArray<FrameworkAdapter>> {
+  const active: FrameworkAdapter[] = [];
+  for (const adapter of BUILTIN_ADAPTERS) {
+    const matched = await adapter.detect(projectRoot, filePaths, contentsByPath);
+    if (matched) {
+      active.push(adapter);
+    }
+  }
+  return active;
+}

package/src/django-adapter.ts

@@ -0,0 +1,173 @@
+import path from 'node:path';
+import type { DiscoveredRoute, ExtractedRouteData } from '@seo-partner/core';
+import type { AdapterCapabilities, AdapterVersion, FrameworkAdapter } from './contract.js';
+import { parseDjangoUrls, parseDjangoViews } from './parsers/python-url-parser.js';
+import { parseDjangoTemplate } from './parsers/dtl-parser.js';
+import { LayoutResolver } from './parsers/layout-resolver.js';
+
+export class DjangoAdapter implements FrameworkAdapter {
+  public readonly id = 'django';
+  public readonly name = 'Django';
+  public readonly version: AdapterVersion = '1.0';
+  public readonly capabilities: AdapterCapabilities = {
+    routes: true,
+    metadata: true,
+    headings: true,
+    internalLinks: true,
+    jsonLd: true,
+    images: true,
+    robotsAndSitemap: true,
+  };
+
+  private readonly layoutResolver = new LayoutResolver();
+
+  public async detect(
+    projectRoot: string,
+    filePaths: ReadonlyArray<string>,
+    contentsByPath: ReadonlyMap<string, string>,
+  ): Promise<boolean> {
+    for (const filePath of filePaths) {
+      const normalized = filePath.replace(/\\/g, '/');
+      if (
+        normalized === 'manage.py' ||
+        normalized.endsWith('/manage.py') ||
+        normalized === 'wsgi.py' ||
+        normalized.endsWith('/wsgi.py') ||
+        normalized === 'asgi.py' ||
+        normalized.endsWith('/asgi.py') ||
+        normalized.endsWith('settings.py')
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  public async discoverRoutes(
+    projectRoot: string,
+    filePaths: ReadonlyArray<string>,
+    contentsByPath: ReadonlyMap<string, string>,
+    sitemapPaths: ReadonlySet<string>,
+  ): Promise<ReadonlyArray<DiscoveredRoute>> {
+    const routes: DiscoveredRoute[] = [];
+
+    // 1. Pre-cache all base templates (e.g. templates/base.html, templates/*/base.html)
+    for (const filePath of filePaths) {
+      const normalized = filePath.replace(/\\/g, '/');
+      if (normalized.endsWith('.html')) {
+        const content = contentsByPath.get(filePath) ?? '';
+        if (
+          normalized.endsWith('base.html') ||
+          content.includes('<!DOCTYPE html>') ||
+          content.includes('<html')
+        ) {
+          const parsed = parseDjangoTemplate(
+            {
+              pattern: '',
+              filePath,
+              routerKind: 'django',
+              renderingMode: 'dynamic',
+              isPrivate: false,
+              inSitemap: false,
+            },
+            content,
+          );
+          this.layoutResolver.registerLayout({
+            filePath,
+            htmlLang: parsed.routeData.htmlLang,
+            title: parsed.routeData.title,
+            description: parsed.routeData.description,
+            canonical: parsed.routeData.canonical,
+            robots: parsed.routeData.robots,
+          });
+        }
+      }
+    }
+
+    // 2. Parse all views.py to build viewName -> templateName mapping
+    const viewToTemplate = new Map<string, string>();
+    for (const filePath of filePaths) {
+      const normalized = filePath.replace(/\\/g, '/');
+      if (normalized.endsWith('views.py')) {
+        const content = contentsByPath.get(filePath) ?? '';
+        const mappings = parseDjangoViews(content);
+        for (const m of mappings) {
+          viewToTemplate.set(m.viewName, m.templateName);
+        }
+      }
+    }
+
+    // 3. Parse all urls.py to discover routes
+    for (const filePath of filePaths) {
+      const normalized = filePath.replace(/\\/g, '/');
+      if (!normalized.endsWith('urls.py')) continue;
+
+      const content = contentsByPath.get(filePath) ?? '';
+      const patterns = parseDjangoUrls(content);
+
+      for (const p of patterns) {
+        const targetTemplateName = viewToTemplate.get(p.viewName);
+        let resolvedFilePath = filePath;
+
+        if (targetTemplateName) {
+          // Find matching template in filePaths
+          const found = filePaths.find((fp) => {
+            const norm = fp.replace(/\\/g, '/');
+            return norm.endsWith(`/${targetTemplateName}`) || norm === targetTemplateName;
+          });
+          if (found) {
+            resolvedFilePath = found;
+          }
+        } else {
+          // Conventional fallback: check for templates/<viewName>.html
+          const fallback = filePaths.find((fp) => {
+            const norm = fp.replace(/\\/g, '/');
+            return (
+              norm.endsWith(`/${p.viewName}.html`) ||
+              norm.endsWith(`templates/${p.viewName}.html`)
+            );
+          });
+          if (fallback) {
+            resolvedFilePath = fallback;
+          }
+        }
+
+        const inSitemap = sitemapPaths.has(p.pattern) || sitemapPaths.has(`${p.pattern}/`);
+
+        routes.push({
+          pattern: p.pattern,
+          filePath: resolvedFilePath,
+          routerKind: 'django',
+          renderingMode: 'dynamic',
+          isPrivate: false,
+          inSitemap,
+        });
+      }
+    }
+
+    return routes;
+  }
+
+  public async extractRoute(
+    projectRoot: string,
+    route: DiscoveredRoute,
+    fileContent: string,
+  ): Promise<ExtractedRouteData> {
+    const parsed = parseDjangoTemplate(route, fileContent);
+    let extracted = parsed.routeData;
+
+    // Resolve base template inheritance
+    const candidates: string[] = [];
+    if (parsed.extendsTemplate) {
+      candidates.push(parsed.extendsTemplate);
+      candidates.push(`templates/${parsed.extendsTemplate}`);
+    }
+    candidates.push('templates/base.html');
+    candidates.push('base.html');
+
+    extracted = this.layoutResolver.applyInheritance(extracted, candidates);
+
+    return extracted;
+  }
+}
+