adapt-authoring-core 1.3.2 → 1.3.4

package/adapt-authoring.json

@@ -2,6 +2,7 @@
   "module": false,
   "documentation": {
     "enable": true,
+    "manualCover": "docs/cover-manual.md",
     "manualIndex": "docs/index-manual.md",
     "sourceIndex": "docs/index-backend.md",
     "manualPages": {
@@ -22,6 +23,7 @@
     "manualPlugins": [
       "docs/plugins/binscripts.js",
       "docs/plugins/coremodules.js",
+      "docs/plugins/index-manual.js",
       "docs/plugins/licensing.js"
     ]
   }

package/docs/plugins/index-manual.js

@@ -0,0 +1,263 @@
+import https from 'https'
+
+/**
+ * Documentation plugin that generates a list of contributors
+ * from all adapt-authoring-* repositories in the adapt-security organisation.
+ */
+export default class Contributors {
+  ICON_SIZE = 55
+  BORDER_WIDTH = 3
+  MIN_CONTRIBUTIONS = 25
+
+  constructor (app, config, outputDir) {
+    this.org = 'adapt-security'
+    this.repoPrefix = 'adapt-authoring'
+    this.perPage = 100
+    this.excludeUsers = ['dependabot[bot]', 'dependabot-preview[bot]', 'greenkeeper[bot]', 'semantic-release-bot', 'snyk-bot']
+    // Contribution tiers
+    this.tiers = [
+      { name: 'gold', count: 3, border: '#FFD700' },
+      { name: 'silver', count: 6, border: '#C0C0C0' },
+      { name: 'bronze', count: 10, border: '#CD7F32' },
+      { name: 'contributor' }
+    ]
+  }
+
+  async run () {
+    this.manualFile = 'index-manual.md'
+    this.replace = { CONTRIBUTORS: await this.generateContributorsList() }
+  }
+
+  /**
+   * Makes an HTTPS GET request to the GitHub API
+   */
+  async githubRequest (path) {
+    return new Promise((resolve, reject) => {
+      const options = {
+        hostname: 'api.github.com',
+        path,
+        method: 'GET',
+        headers: {
+          'User-Agent': 'adapt-authoring-docs',
+          Accept: 'application/vnd.github.v3+json'
+        }
+      }
+
+      // Add auth token if available (increases rate limit)
+      if (process.env.GITHUB_TOKEN) {
+        options.headers.Authorization = `token ${process.env.GITHUB_TOKEN}`
+      }
+
+      const req = https.request(options, res => {
+        let data = ''
+        res.on('data', chunk => { data += chunk })
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(data))
+          } catch (e) {
+            reject(new Error(`Failed to parse GitHub response: ${e.message}`))
+          }
+        })
+      })
+
+      req.on('error', reject)
+      req.end()
+    })
+  }
+
+  /**
+   * Fetches all repositories matching the prefix from the organisation
+   */
+  async fetchRepos () {
+    const repos = []
+    let page = 1
+
+    while (true) {
+      const response = await this.githubRequest(
+        `/orgs/${this.org}/repos?per_page=${this.perPage}&page=${page}`
+      )
+
+      if (!Array.isArray(response) || response.length === 0) break
+
+      const matchingRepos = response
+        .filter(repo => repo.name.startsWith(this.repoPrefix))
+        .map(repo => repo.name)
+
+      repos.push(...matchingRepos)
+
+      if (response.length < this.perPage) break
+      page++
+    }
+
+    return repos
+  }
+
+  /**
+   * Fetches contributors for a single repository
+   */
+  async fetchRepoContributors (repoName) {
+    const contributors = []
+    let page = 1
+
+    while (true) {
+      const response = await this.githubRequest(
+        `/repos/${this.org}/${repoName}/contributors?per_page=${this.perPage}&page=${page}`
+      )
+
+      if (!Array.isArray(response) || response.length === 0) break
+
+      contributors.push(...response)
+
+      if (response.length < this.perPage) break
+      page++
+    }
+
+    return contributors
+  }
+
+  /**
+   * Aggregates contributors across all repositories
+   */
+  async aggregateContributors () {
+    const repos = await this.fetchRepos()
+    const contributorMap = new Map()
+
+    for (const repo of repos) {
+      try {
+        const contributors = await this.fetchRepoContributors(repo)
+
+        for (const contributor of contributors) {
+          if (this.excludeUsers.includes(contributor.login)) continue
+          if (contributor.type !== 'User') continue
+
+          if (contributorMap.has(contributor.login)) {
+            const existing = contributorMap.get(contributor.login)
+            existing.contributions += contributor.contributions
+          } else {
+            contributorMap.set(contributor.login, {
+              login: contributor.login,
+              avatarUrl: contributor.avatar_url,
+              profileUrl: contributor.html_url,
+              contributions: contributor.contributions
+            })
+          }
+        }
+      } catch (e) {
+        console.warn(`Failed to fetch contributors for ${repo}: ${e.message}`)
+      }
+    }
+
+    // Sort by contributions (descending) and return as array
+    return Array.from(contributorMap.values())
+      .sort((a, b) => b.contributions - a.contributions)
+  }
+
+  /**
+   * Determines the tier for a contributor based on rank and contribution count
+   */
+  getTier (contributor, rank) {
+    let position = 0
+    for (const tier of this.tiers) {
+      const tierMax = position + (tier.count || Infinity)
+      const rankMatch = !tier.count || (rank > position && rank <= tierMax)
+      const minContributions = tier.count ? this.MIN_CONTRIBUTIONS : 0
+      const countMatch = contributor.contributions >= minContributions
+
+      if (rankMatch && countMatch) {
+        return tier
+      }
+      position = tierMax
+    }
+    return this.tiers[this.tiers.length - 1]
+  }
+
+  /**
+   * Generates the HTML for a single contributor avatar
+   */
+  contributorToHtml (contributor, tier) {
+    const hexClipPath = 'polygon(50% 0%, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%)'
+    const isHexagon = tier.name !== 'contributor'
+
+    const wrapperStyle = [
+      `width: ${this.ICON_SIZE}px`,
+      `height: ${this.ICON_SIZE}px`,
+      isHexagon ? `clip-path: ${hexClipPath}` : 'border-radius: 50%',
+      tier.border ? `background: ${tier.border}` : '',
+      'display: inline-block',
+      'transition: transform 0.2s'
+    ].filter(Boolean).join('; ')
+
+    const imgSize = this.ICON_SIZE - (this.BORDER_WIDTH * 2)
+
+    const imgStyle = [
+      `width: ${imgSize}px`,
+      `height: ${imgSize}px`,
+      isHexagon ? `clip-path: ${hexClipPath}` : 'border-radius: 50%',
+      'display: block',
+      `margin: ${this.BORDER_WIDTH}px`
+    ].join('; ')
+
+    return `<a href="${contributor.profileUrl}" title="${contributor.login} (${contributor.contributions} contributions)" target="_blank" rel="noopener" style="${wrapperStyle}"><img src="${contributor.avatarUrl}" alt="${contributor.login}" class="contributor-avatar contributor-${tier.name}" style="${imgStyle}" /></a>`
+  }
+
+  /**
+   * Generates the full contributors list HTML
+   */
+  async generateContributorsList () {
+    try {
+      const contributors = await this.aggregateContributors()
+
+      if (contributors.length === 0) {
+        return '<p>No contributors found.</p>'
+      }
+
+      // Group contributors by tier
+      const tierGroups = new Map()
+      contributors.forEach((contributor, index) => {
+        const tier = this.getTier(contributor, index + 1)
+        if (!tierGroups.has(tier.name)) {
+          tierGroups.set(tier.name, [])
+        }
+        tierGroups.get(tier.name).push(this.contributorToHtml(contributor, tier))
+      })
+
+      // Generate HTML for each tier row
+      const rows = Array.from(tierGroups.entries())
+        .map(([tierName, avatars]) =>
+          `<div class="contributors-row contributors-${tierName}">\n${avatars.join('\n')}\n</div>`
+        )
+        .join('\n')
+
+      return `<div class="contributors-grid">\n${rows}\n</div>
+      <style>
+      .contributors-grid {
+        margin: 0 auto;
+        max-width: 600px;
+        padding: 20px 0;
+      }
+
+      .contributors-row {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: center;
+        gap: 4px;
+        margin-bottom: 12px;
+        text-align: center;
+      }
+
+      .contributors-grid a:hover {
+        transform: scale(1.1);
+      }
+
+      .contributor-avatar {
+        object-fit: cover;
+        vertical-align: middle;
+      }
+      </style>`
+    } catch (e) {
+      console.error('Failed to generate contributors list:', e)
+      return '<p>Unable to load contributors list.</p>'
+    }
+  }
+}

package/docs/plugins/index-manual.md

@@ -0,0 +1,47 @@
+# Adapt Authoring Tool Developer guides
+
+Welcome to the technical documentation for the Adapt authoring tool — a web-based application for creating responsive, multi-device e-learning content built on the [Adapt Framework](https://github.com/adaptlearning/adapt_framework).
+
+The authoring tool provides a user-friendly interface for building courses without needing to write code, while its modular architecture gives developers the flexibility to extend and customise virtually every aspect of the system. Whether you're looking to build custom plugins, integrate with external services, or contribute to the core codebase, you're in the right place.
+
+## What makes it tick
+
+The authoring tool is built on a few key principles:
+
+- **Modular by design** — The entire application is composed of discrete modules that can be swapped, extended, or replaced. Need custom authentication? Write an auth plugin. Want to store data differently? Create a new database adapter.
+
+- **Schema-driven** — Content types, validation rules, and UI forms are all defined using JSON schemas. This means you can add new content types or modify existing ones without touching application code.
+
+- **RESTful API** — Every feature is accessible via a comprehensive REST API, making it straightforward to integrate with other systems or build custom tooling.
+
+- **Built for collaboration** — Multi-user support with role-based permissions lets teams work together on courses with appropriate access controls.
+
+## About this documentation
+
+This documentation covers the technical side of the authoring tool — how it works under the hood and how to extend it. You'll find guides on writing custom modules, working with the database, creating schemas, and contributing to the project.
+
+If you're looking for help using the authoring tool to create courses, check out the user guides on the [Adapt Learning community site](https://www.adaptlearning.org/).
+
+## Where to start
+
+New to the codebase? Here are some good starting points:
+
+- **[Folder Structure](folder-structure)** — Get familiar with how the application is organised
+- **[Writing a Module](writing-a-module)** — Learn the basics of creating your own module
+- **[Schemas Introduction](schemas-introduction)** — Understand how schemas drive the application
+- **[Hooks](hooks)** — See how to tap into the application lifecycle
+
+## Get involved
+
+The Adapt authoring tool is open source and we welcome contributions. You can find the source code and report issues on GitHub:
+
+- [adapt-security](https://github.com/adapt-security) — Authoring tool repositories
+- [adaptlearning](https://github.com/adaptlearning) — Adapt Framework and community plugins
+
+## Contributors
+
+A huge thank you to everyone who has contributed to the Adapt authoring tool. This project wouldn't be possible without the time and effort of our community.
+
+{{{CONTRIBUTORS}}}
+
+<div class="big-text">Happy coding!</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-core",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "A bundle of reusable 'core' functionality",
   "homepage": "https://github.com/adapt-security/adapt-authoring-core",
   "license": "GPL-3.0",