ci: refactor generate-docs process

Signed-off-by: Emilien Escalle <emilien.escalle@escemi.com>

Author: neilime

.env

@@ -0,0 +1,91 @@
+<!-- header:start -->
+
+# GitHub Action: Generate Documentation
+
+<div align="center">
+  <img src="https://opengraph.githubassets.com/ed19fc749543a82f50dbc89c5b6e8bba6ee7cd408bad3a0d6748179b2681f1ec/hoverkraft-tech/public-docs" width="60px" align="center" alt="Generate Documentation" />
+</div>
+
+---
+
+<!-- header:end -->
+<!-- badges:start -->
+
+[![Marketplace](https://img.shields.io/badge/Marketplace-generate--documentation-blue?logo=github-actions)](https://github.com/marketplace/actions/generate-documentation)
+[![Release](https://img.shields.io/github/v/release/hoverkraft-tech/public-docs)](https://github.com/hoverkraft-tech/public-docs/releases)
+[![License](https://img.shields.io/github/license/hoverkraft-tech/public-docs)](http://choosealicense.com/licenses/mit/)
+[![Stars](https://img.shields.io/github/stars/hoverkraft-tech/public-docs?style=social)](https://img.shields.io/github/stars/hoverkraft-tech/public-docs?style=social)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/hoverkraft-tech/public-docs/blob/main/CONTRIBUTING.md)
+
+<!-- badges:end -->
+<!-- overview:start -->
+
+## Overview
+
+Generate project metadata pages
+
+Features:
+
+- Scans all repositories in the organization
+- Categorizes projects by type
+- Generates the projects overview page
+- Updates homepage with featured projects
+
+<!-- overview:end -->
+<!-- usage:start -->
+
+## Usage
+
+```yaml
+- uses: hoverkraft-tech/public-docs/.github/actions/generate-docs@fca4a9a32575438db28e9b8ad81d97758eca84c4 # main
+  with:
+    # GitHub token used to authenticate repository queries.
+    # This input is required.
+    github-token: ""
+```
+
+<!-- usage:end -->
+<!-- inputs:start -->
+
+## Inputs
+
+| **Input**          | **Description**                                       | **Required** | **Default** |
+| ------------------ | ----------------------------------------------------- | ------------ | ----------- |
+| **`github-token`** | GitHub token used to authenticate repository queries. | **true**     | -           |
+
+<!-- inputs:end -->
+<!-- secrets:start -->
+<!-- secrets:end -->
+<!-- outputs:start -->
+<!-- outputs:end -->
+<!-- examples:start -->
+<!-- examples:end -->
+<!-- contributing:start -->
+
+## Contributing
+
+Contributions are welcome! Please see the [contributing guidelines](https://github.com/hoverkraft-tech/public-docs/blob/main/CONTRIBUTING.md) for more details.
+
+<!-- contributing:end -->
+<!-- security:start -->
+<!-- security:end -->
+<!-- license:start -->
+
+## License
+
+This project is licensed under the MIT License.
+
+SPDX-License-Identifier: MIT
+
+Copyright © 2025 hoverkraft-tech
+
+For more details, see the [license](http://choosealicense.com/licenses/mit/).
+
+<!-- license:end -->
+<!-- generated:start -->
+
+---
+
+This documentation was automatically generated by [CI Dokumentor](https://github.com/hoverkraft-tech/ci-dokumentor).
+
+<!-- generated:end -->

.github/actions/generate-docs/README.md

@@ -0,0 +1,34 @@
+name: Generate Documentation
+description: |
+  Generate project metadata pages
+
+  Features:
+
+  - Scans all repositories in the organization
+  - Categorizes projects by type
+  - Generates the projects overview page
+  - Updates homepage with featured projects
+
+inputs:
+  github-token:
+    description: GitHub token used to authenticate repository queries.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Node.js and install dependencies
+      uses: hoverkraft-tech/ci-github-nodejs/actions/setup-node@6809332ced7647b3d52300a47d65657283f3395e # 0.16.0
+      with:
+        working-directory: ${{ github.action_path }}
+
+    - name: Generate documentation from repositories
+      uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      env:
+        TEMPLATE_NAME: ${{ inputs.template-name }}
+        NODE_PATH: ${{ github.action_path }}/node_modules
+      with:
+        github-token: ${{ inputs.github-token }}
+        script: |
+          const { run } = require('${{ github.action_path }}/generate-docs.js');
+          await run({ github });

.github/actions/generate-docs/action.yml

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+const { DocumentationGenerator } = require("./lib/documentation-generator");
+
+async function run({ github }) {
+  try {
+    const generator = new DocumentationGenerator({ github });
+    await generator.run();
+  } catch (error) {
+    console.error("❌ Error during generation:", error);
+    throw error;
+  }
+}
+
+module.exports = { run };

.github/actions/generate-docs/generate-docs.js

@@ -0,0 +1,97 @@
+const ejs = require("ejs");
+const fs = require("fs");
+const { resolveIcon } = require("./resolve-icon");
+const { PROJECTS_MD_TEMPLATE } = require("../constants");
+
+class ProjectsContentBuilder {
+  constructor({ templatePath } = {}) {
+    this.templatePath = templatePath || PROJECTS_MD_TEMPLATE;
+    this.template = fs.readFileSync(this.templatePath, "utf8");
+  }
+
+  build({ categories, repositories, generatedAt }) {
+    const stats = this.buildStats(repositories, generatedAt);
+    const categoryModels = this.buildCategoryModels(categories);
+
+    return ejs.render(
+      this.template,
+      {
+        stats,
+        categories: categoryModels,
+      },
+      { filename: this.templatePath }
+    );
+  }
+
+  buildStats(repositories, generatedAt) {
+    const totalRepos = repositories.length;
+    const totalStars = repositories.reduce(
+      (sum, repository) => sum + (repository.stargazers_count || 0),
+      0
+    );
+    const languages = [
+      ...new Set(
+        repositories.map((repository) => repository.language).filter(Boolean)
+      ),
+    ];
+    const primaryLanguages = languages.slice(0, 5);
+
+    return {
+      totalRepos,
+      totalStars,
+      languageCount: languages.length,
+      languagesSummary:
+        primaryLanguages.length > 0
+          ? primaryLanguages.join(", ")
+          : "various stacks",
+      generatedDate: generatedAt.toISOString().split("T")[0],
+    };
+  }
+
+  buildCategoryModels(categories) {
+    return Object.entries(categories)
+      .filter(([, repositories]) => repositories.length > 0)
+      .map(([name, repositories]) => ({
+        name,
+        repositories: repositories.map((repository) =>
+          this.buildRepositoryModel(repository)
+        ),
+      }));
+  }
+
+  buildRepositoryModel(repository) {
+    return {
+      name: repository.name,
+      htmlUrl: repository.html_url,
+      icon: resolveIcon(repository),
+      language: repository.language || "Unknown",
+      stars: repository.stargazers_count || 0,
+      lastUpdated: this.formatDate(repository.updated_at),
+      description: repository.description || "No description available.",
+      topics: (repository.topics || []).slice(0, 5),
+      homepage: repository.homepage,
+    };
+  }
+
+  formatDate(dateString) {
+    if (!dateString) {
+      return "Unknown";
+    }
+
+    const date = new Date(dateString);
+
+    if (Number.isNaN(date.getTime())) {
+      return "Unknown";
+    }
+
+    return date.toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+    });
+  }
+}
+
+module.exports = {
+  ProjectsContentBuilder,
+};

.github/actions/generate-docs/lib/builders/projects-content-builder.js

@@ -0,0 +1,10 @@
+function buildProfile(repository) {
+  return {
+    name: (repository.name || "").toLowerCase(),
+    description: (repository.description || "").toLowerCase(),
+    topics: new Set(repository.topics || []),
+  };
+}
+module.exports = {
+  buildProfile,
+};

.github/actions/generate-docs/lib/builders/repository-profile.js

@@ -0,0 +1,12 @@
+const { ICON_RULES } = require("../rules");
+const { buildProfile } = require("./repository-profile");
+
+function resolveIcon(repository) {
+  const profile = buildProfile(repository);
+  const rule = ICON_RULES.find((candidate) => candidate.predicate(profile));
+  return rule ? rule.icon : "🔧";
+}
+
+module.exports = {
+  resolveIcon,
+};

.github/actions/generate-docs/lib/builders/resolve-icon.js

@@ -0,0 +1,49 @@
+const path = require("path");
+
+const ACTION_ROOT = path.join(__dirname, "..");
+const REPO_ROOT = path.join(ACTION_ROOT, "..", "..", "..");
+const APPLICATION_ROOT = path.join(REPO_ROOT, "application");
+const DOCS_DIR = path.join(APPLICATION_ROOT, "docs");
+const PROJECTS_MD_PATH = path.join(DOCS_DIR, "projects.md");
+const HOMEPAGE_PATH = path.join(APPLICATION_ROOT, "src", "pages", "index.tsx");
+const TEMPLATE_DIR = path.join(__dirname, "templates");
+const PROJECTS_MD_TEMPLATE = path.join(TEMPLATE_DIR, "projects.md.ejs");
+const FEATURED_REPOSITORY_LIMIT = 6;
+const HOMEPAGE_CARD_LIMIT = 3;
+
+const OWNER = process.env.GITHUB_REPOSITORY_OWNER;
+
+if (!OWNER) {
+  throw new Error(
+    "GITHUB_REPOSITORY_OWNER environment variable must be set for documentation generation."
+  );
+}
+
+const REPOSITORY_SLUG = process.env.GITHUB_REPOSITORY;
+
+if (!REPOSITORY_SLUG) {
+  throw new Error(
+    "GITHUB_REPOSITORY environment variable must be set for documentation generation."
+  );
+}
+
+const [, REPOSITORY_NAME] = REPOSITORY_SLUG.split("/");
+
+if (!REPOSITORY_NAME) {
+  throw new Error(
+    `Unable to determine repository name from GITHUB_REPOSITORY='${REPOSITORY_SLUG}'.`
+  );
+}
+
+const IGNORED_REPOSITORIES = new Set([REPOSITORY_NAME]);
+
+module.exports = {
+  OWNER,
+  DOCS_DIR,
+  PROJECTS_MD_PATH,
+  HOMEPAGE_PATH,
+  PROJECTS_MD_TEMPLATE,
+  IGNORED_REPOSITORIES,
+  FEATURED_REPOSITORY_LIMIT,
+  HOMEPAGE_CARD_LIMIT,
+};

.github/actions/generate-docs/lib/constants.js

@@ -0,0 +1,83 @@
+const fs = require("fs").promises;
+const {
+  OWNER,
+  IGNORED_REPOSITORIES,
+  PROJECTS_MD_PATH,
+} = require("./constants");
+const { CATEGORY_RULES } = require("./rules");
+const {
+  GitHubRepositoryService,
+} = require("./services/github-repository-service");
+const { RepositoryFilter } = require("./repository-filter");
+const { RepositoryCategorizer } = require("./repository-categorizer");
+const {
+  ProjectsContentBuilder,
+} = require("./builders/projects-content-builder");
+const {
+  HomepageProjectsUpdater,
+} = require("./homepage/homepage-projects-updater");
+
+class DocumentationGenerator {
+  constructor({ github }) {
+    this.repositoryService = new GitHubRepositoryService(github);
+    this.repositoryFilter = new RepositoryFilter({
+      ignoredNames: IGNORED_REPOSITORIES,
+    });
+    this.repositoryCategorizer = new RepositoryCategorizer(CATEGORY_RULES);
+    this.projectsContentBuilder = new ProjectsContentBuilder();
+    this.homepageUpdater = new HomepageProjectsUpdater();
+  }
+
+  async run() {
+    console.log("🚀 Starting documentation generation...");
+
+    const rawRepositories =
+      await this.repositoryService.fetchOrganizationRepositories(OWNER);
+
+    const showcaseRepositories = this.repositoryFilter.apply(rawRepositories);
+    const categories =
+      this.repositoryCategorizer.categorize(showcaseRepositories);
+
+    await this.writeProjectsAssets({
+      categories,
+      repositories: showcaseRepositories,
+      generatedAt: new Date(),
+    });
+
+    const pinnedRepositoryNames =
+      await this.repositoryService.fetchOrganizationPinnedRepositories(OWNER);
+
+    await this.homepageUpdater.update(rawRepositories, pinnedRepositoryNames);
+
+    console.log("✅ Documentation generation completed!");
+    this.logSummary(categories);
+  }
+
+  async writeProjectsAssets({ categories, repositories, generatedAt }) {
+    const markdown = this.projectsContentBuilder.build({
+      categories,
+      repositories,
+      generatedAt,
+    });
+
+    await fs.writeFile(PROJECTS_MD_PATH, markdown, "utf8");
+
+    console.log("📄 Generated files:");
+    console.log("   - docs/projects.md");
+    console.log("   - Updated src/pages/index.tsx");
+  }
+
+  logSummary(categories) {
+    console.log("\n📊 Repository Summary:");
+
+    Object.entries(categories).forEach(([category, repositories]) => {
+      if (repositories.length > 0) {
+        console.log(`   ${category}: ${repositories.length} projects`);
+      }
+    });
+  }
+}
+
+module.exports = {
+  DocumentationGenerator,
+};