Merge pull request #373 from the-hideout/achievement-documentation

Improve formatting/documentation for Achievement type

Author: Razzmatazzz

schema-dynamic.mjs

@@ -14,7 +14,7 @@ enum HandbookCategoryName {
     ${handbookCategories}
 }
 enum LanguageCode {
-	${languageCodes}
+    ${languageCodes}
 }
     `;
 };

schema-static.mjs

@@ -1,14 +1,47 @@
 export default `
+"""
+**In-game achievements players can earn by completing specific objectives.**
+"""
 type Achievement {
+  """
+  A unique 24-character hexadecimal identifier for the achievement. Follows a consistent format across all achievements.
+  """
   id: ID!
+  """
+  The display name of the achievement (e.g., "Welcome to Tarkov", "The Kappa Path").
+  """
   name: String!
+  """
+  Text describing the conditions required to unlock the achievement (e.g., "Neutralize Killa 15 times while playing as a PMC").
+  """
   description: String
+  """
+  Whether the achievement is hidden from players until unlocked (true) or visible from the start (false).
+  """
   hidden: Boolean!
+  """
+  Raw percentage of all players who have completed this achievement (e.g., 0.06, 43.48).
+  """
   playersCompletedPercent: Float!
+  """
+  Statistically adjusted percentage that accounts for active players, providing a more representative completion rate. Uses the percentage completion of Welcome to Tarkov as the baseline under the assumption that all active accounts have died once.
+  """
   adjustedPlayersCompletedPercent: Float
+  """
+  The game faction or player type this achievement is associated with. Values include "PMC", "All", or "Scavs".
+  """
   side: String
+  """
+  Lowercase, standardized version of the side field used for consistent sorting and filtering (e.g., "pmc", "all", "scavs").
+  """
   normalizedSide: String
+  """
+  The difficulty/rarity tier of the achievement. Values include "Common", "Rare", or "Legendary".
+  """
   rarity: String
+  """
+  Lowercase, standardized version of the rarity field used for consistent sorting and filtering (e.g., "common", "rare", "legendary").
+  """
   normalizedRarity: String
 }
 
@@ -1500,4 +1533,4 @@ type TraderResetTime {
   name: String @deprecated(reason: "Use Trader.name type instead.")
   resetTimestamp: String @deprecated(reason: "Use Trader.resetTime type instead.")
 }
-`;
+`

test-playground.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+/*
+  Local GraphQL Playground for static schema (SDL) development/testing.
+  - Runs a standalone server on http://localhost:4000/graphql
+  - Uses only the static SDL (schema-static.mjs) and stub scalars
+  - Does not use dynamic data or production API logic
+  - Useful for viewing schema docs and testing queries against the static schema
+  - Not used in production or deployment
+*/
+
+import http from 'http'
+import { createYoga } from 'graphql-yoga'
+import { makeExecutableSchema } from '@graphql-tools/schema'
+import staticSDL from './schema-static.mjs'
+
+// Stubs for custom scalars referenced in staticSDL
+const stubSDL = `
+  scalar LanguageCode
+  scalar ItemType
+  scalar ItemCategoryName
+  scalar HandbookCategoryName
+`
+
+// Build schema from static SDL and stubs
+const schema = makeExecutableSchema({
+    typeDefs: [staticSDL, stubSDL],
+    resolvers: {},
+})
+
+// Enable GraphiQL at /graphql for local exploration
+const yoga = createYoga({
+    schema,
+    graphiql: true,
+})
+
+// Start HTTP server on port 4000
+const server = http.createServer(yoga)
+const PORT = 4000
+server.listen(PORT, () => {
+    console.log(
+        `🚀 GraphQL Playground running at http://localhost:${PORT}/graphql`
+    )
+})