Refactor/monorepo with spec-driven development by wildan3105 · Pull Request #321 · wildan3105/github-langs

wildan3105 · 2026-02-14T08:09:21Z

Description

Major overhaul

Also:

fixes Migrate from github restful API to graphql for better performance of search result #318
fixes Enter to search #316
fixes Fullstack app skeleton #302
fixes CSS file occassionally updated on random #296
fixes Migrate import sass #293
fixes Intermittent bad gateway for not found user #287
fixes Update dependencies #284
fixes Enable hot-reload whenever *.js changes #274
fixes Add timeout request #257
fixes Github langs v2 #231
fixes Functionality test cases #178
fixes Better code structure #166
fixes Differentiate between original & forked repositories #161

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Other (security config, docs update, etc.)

Screenshot of change (if there's UI update)

…backend-spec.md

.github/workflows/backend-ci.yml

+    name: Docker Build
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: ./backend
+          push: false
+          tags: gitlingo-backend:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max


To fix the problem, add an explicit permissions: block that grants only the minimal rights needed by these jobs. Since the jobs only check out code, set up Node, run tests/lint/build, upload coverage to Codecov, and build a Docker image without pushing, they only need read access to the repository contents.

The most straightforward fix without changing functionality is to add a workflow-level permissions: block right after the name: and before on::

permissions: contents: read

This will apply to both test and docker jobs, restricting GITHUB_TOKEN to read-only repository contents, which is sufficient for actions/checkout@v4 and the other used actions. No other scopes (like packages, pull-requests, or id-token) are required based on the provided snippet, and we are not pushing Docker images or writing to GitHub APIs.

Concretely:

Edit .github/workflows/backend-ci.yml.

Insert the permissions: block near the top of the file (e.g., between line 1 and line 3, after name: Backend CI and the blank line).

No imports, methods, or additional definitions are needed, as this is purely a workflow configuration change.

- Destructure profile and repositories from fetchRepositories result - Display profile information including providerUserId - Replace all instances of repos with repositories

wildan3105 · 2026-02-14T10:18:52Z

@copilot please review

Copilot · 2026-02-14T10:18:59Z

@wildan3105 I've opened a new pull request, #322, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull request overview

This PR is a large refactor toward a spec-driven monorepo, replacing the legacy JS/Handlebars implementation with a new TypeScript backend under backend/ that follows a DDD + ports/adapters architecture and exposes a JSON API (/health, /api/v1/search) aligned with the new backend specification.

Changes:

Remove the legacy Express + Handlebars web app, client JS assets, and Mocha-based utility tests.
Introduce a new backend/ TypeScript service (DDD structure, GitHub GraphQL adapter, validation, error handling) plus Jest unit/integration tests.
Add/update specs, task docs, Docker/CI setup, and sample API responses to support spec-driven development.

Reviewed changes

Copilot reviewed 86 out of 97 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tests/utils/language-colors-generator.test.js	Removed legacy Mocha test for language color generation.
tests/utils/emoji-generator.test.js	Removed legacy Mocha test for emoji generator.
src/utils/language-colors-generator.js	Removed legacy language color generator utility.
src/utils/emoji-generator.js	Removed legacy emoji generator utility.
src/pages/partials/head.handlebars	Removed legacy Handlebars head partial (old UI).
src/pages/partials/footer.handlebars	Removed legacy Handlebars footer partial (analytics snippet).
src/pages/partials/error.handlebars	Removed legacy error partial.
src/pages/partials/copyright.handlebars	Removed legacy copyright partial.
src/pages/partials/body.handlebars	Removed legacy main UI body (chart + search UI).
src/pages/layouts/main.handlebars	Removed legacy Handlebars layout wrapper.
src/config.js	Removed legacy config/constants for the old app.
src/api/routes.js	Removed legacy Express routes file.
src/api/octokit.js	Removed legacy REST-based Octokit wrapper.
src/api/controller.js	Removed legacy controller/aggregation logic (REST-based).
src/api/app.js	Removed legacy Express app entrypoint.
samples/400-response.json	Added sample error response payload for the new API contract.
samples/200-response.json	Added sample success response payload for the new API contract.
public/js/spinner.js	Removed legacy browser spinner script.
public/js/social.js	Removed legacy social share script.
public/js/language-colors.js	Removed legacy browser language-colors map.
public/js/chart.js	Removed legacy Chart.js integration script.
public/css/themes/_light.scss	Removed legacy theme styles.
public/css/themes/_dark.scss	Removed legacy theme styles.
public/css/base.scss	Removed legacy SCSS entrypoint for UI styling.
package.json	Removed legacy root package configuration (pre-monorepo).
gulpfile.js	Removed legacy gulp build pipeline (CSS).
eslint.config.mjs	Removed legacy root ESLint config.
docs/tasks/7-testing-polish.md	Added spec-driven task document for testing/polish steps.
docs/tasks/6-http-layer.md	Added spec-driven task document for HTTP layer design.
docs/tasks/5-application-layer.md	Added spec-driven task document for application/use-case layer.
docs/tasks/4-github-adapter.md	Added spec-driven task document for GitHub GraphQL adapter.
docs/tasks/3-project-structure.md	Added spec-driven task document for DDD project structure.
docs/tasks/2-init-deps.md	Added spec-driven task document for dependency initialization.
docs/tasks/1-setup-project.md	Added spec-driven task document for backend bootstrap.
docs/product-spec.md	Added product spec defining goals and refactor plan.
docs/backend-spec.md	Added backend architecture + API contract specification.
docker-compose.yaml	Removed legacy docker-compose setup.
README.md	Replaced root README with a placeholder for the refactor/monorepo docs.
Dockerfile	Removed legacy root Dockerfile.
CLAUDE.md	Added contributor/agent guidance tying work to specs + iteration practices.
.nvmrc	Updated Node version pinned for local development.
.github/workflows/backend-ci.yml	Added backend-focused CI workflow (lint/typecheck/test/build + Docker build).
backend/tsconfig.json	Added backend TypeScript compiler configuration.
backend/src/shared/types/common.ts	Added shared type aliases (provider/env/log level).
backend/src/shared/index.ts	Added shared barrel exports.
backend/src/shared/constants/providers.ts	Added provider enum + default provider constant.
backend/src/shared/constants/languageColors.ts	Added language color map + helpers for consistent coloring.
backend/src/shared/config/env.ts	Added dotenv-based config loader/validator.
backend/src/interfaces/validation/searchSchema.ts	Added Zod validation + middleware for `/api/v1/search`.
backend/src/interfaces/routes/searchRoutes.ts	Added search routes factory.
backend/src/interfaces/routes/index.ts	Added routes root with `/health` + mounting `/api/v1`.
backend/src/interfaces/middleware/errorHandler.ts	Added global Express error handler middleware.
backend/src/interfaces/index.ts	Added interfaces barrel exports.
backend/src/interfaces/controllers/SearchController.ts	Added controller mapping HTTP -> SearchService + error code -> status.
backend/src/infrastructure/providers/types/GitHubTypes.ts	Added GitHub GraphQL response types (infra-only).
backend/src/infrastructure/providers/GitHubGraphQLAdapter.ts	Added GitHub GraphQL provider adapter with pagination + error mapping.
backend/src/infrastructure/index.ts	Added infrastructure barrel exports.
backend/src/infrastructure/errors/ProviderError.ts	Added ProviderError type for infra failures + helpers.
backend/src/index.ts	Added backend entrypoint wiring middleware, DI, routes, and graceful shutdown.
backend/src/domain/ports/ProviderPort.ts	Added domain provider port contract returning profile + repositories.
backend/src/domain/models/index.ts	Added domain model barrel exports.
backend/src/domain/models/Repository.ts	Added provider-agnostic repository domain model.
backend/src/domain/models/Profile.ts	Added profile domain model.
backend/src/domain/models/LanguageStatistic.ts	Added language statistic domain model for chart-ready output.
backend/src/domain/index.ts	Added domain barrel exports.
backend/src/application/types/SearchResult.ts	Added success response type matching the spec contract.
backend/src/application/types/SearchError.ts	Added error response type matching the spec contract.
backend/src/application/services/SearchService.ts	Added use-case orchestration: aggregation, fork handling, color mapping, error transform.
backend/src/application/index.ts	Added application barrel exports.
backend/src/tests/unit/errorHandler.test.ts	Added unit tests for error handler middleware.
backend/src/tests/unit/SearchService.test.ts	Added unit tests for aggregation logic and error transformation.
backend/src/tests/unit/SearchController.test.ts	Added unit tests for controller status mapping and provider handling.
backend/src/tests/unit/ProviderError.test.ts	Added unit tests for ProviderError behavior.
backend/src/tests/unit/GitHubAdapter.test.ts	Added unit tests for GitHub adapter (mocked GraphQL).
backend/src/tests/setup.ts	Added Jest setup (env + timeouts).
backend/src/tests/integration/api.test.ts	Added integration tests for `/health` and `/api/v1/search`.
backend/package.json	Added backend package definition, scripts, and dependencies.
backend/jest.config.js	Added Jest + ts-jest config and coverage rules.
backend/eslint.config.js	Added backend ESLint config (TypeScript + Prettier).
backend/mocks/@octokit/graphql.js	Added manual mock for `@octokit/graphql` intended for network-interceptable tests.
backend/README.md	Added backend-specific README with setup, endpoints, and behavior notes.
backend/Dockerfile	Added backend production multi-stage Dockerfile + healthcheck.
backend/.prettierrc	Added Prettier configuration for backend TS formatting.
backend/.gitignore	Added backend-specific gitignore.
backend/.env.example	Added backend env example template.
backend/.dockerignore	Added backend dockerignore for smaller images.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-14T10:24:37Z

backend/src/index.ts

+  const limiter = rateLimit({
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    max: 100, // Max 100 requests per window
+    message: {
+      ok: false,
+      provider: 'unknown',
+      error: {
+        code: 'rate_limited',
+        message: 'Too many requests, please try again later',
+      },
+      meta: {
+        generatedAt: new Date().toISOString(),
+      },
+    },


express-rate-limit message is constructed once at startup, so meta.generatedAt will be stale and identical for all rate-limited responses. Consider using a handler (or a message function, if supported) to generate generatedAt per request.

Copilot · 2026-02-14T10:24:37Z

backend/__mocks__/@octokit/graphql.js

+      throw error;
+    }
+
+    return response.json();


This manual mock returns response.json() (which includes { data, errors }), but @octokit/graphql resolves to the unwrapped data payload. As written, tests that rely on this mock will see a different shape than production code. Consider returning const { data, errors } = await response.json() and throwing on errors, otherwise returning data.

Suggested change

return response.json();

const { data, errors } = await response.json();

if (errors && errors.length > 0) {

const graphQLError = new Error(errors[0]?.message || 'GraphQL error');

graphQLError.errors = errors;

throw graphQLError;

}

return data;

README.md

Copilot · 2026-02-14T10:24:38Z

backend/src/interfaces/validation/searchSchema.ts

+
+  provider: z.enum(Object.values(Providers)).default(DEFAULT_PROVIDER).optional(),
+});


z.enum(Object.values(Providers)) won’t type-check cleanly because Object.values() is string[] at compile time, but z.enum() expects a non-empty tuple of string literals. Consider defining a const PROVIDERS = ['github','gitlab','bitbucket'] as const (or casting to [string, ...string[]]) and using that for both the enum and the exported types.

What if I still want to use Providers? What should we do in this file?

@copilot answer the above question

Copilot · 2026-02-14T10:24:38Z

backend/src/interfaces/validation/searchSchema.ts

+  provider: z.enum(Object.values(Providers)).default(DEFAULT_PROVIDER).optional(),
+});


default(DEFAULT_PROVIDER).optional() likely defeats the defaulting behavior (optional can short-circuit to undefined). If you want a default provider when the param is missing, prefer .optional().default(DEFAULT_PROVIDER) or drop .optional() entirely.

Copilot · 2026-02-14T10:24:38Z

backend/src/application/services/SearchService.ts

+      // 2. Aggregate and count repositories by language
+      const series = this.aggregateLanguageStatistics(repositories);
+
+      // 3. Return successful result
+      return {
+        ok: true,
+        provider: this.provider.getProviderName(),
+        profile,
+        series,
+        metadata: {
+          generatedAt: new Date().toISOString(),
+          unit: 'repos',
+          limit: repositories.length,
+        },
+      };


metadata.limit is currently set to repositories.length, but the API contract/spec uses this as the response limit (e.g., top 20 languages) rather than the number of repos fetched. Also, series is not limited to the top N buckets. Consider introducing a constant (e.g., SERIES_LIMIT = 20), trimming/summing “others” if desired, and setting metadata.limit to that limit.

Copilot · 2026-02-14T10:24:39Z

backend/src/interfaces/middleware/errorHandler.ts

+import { Request, Response, NextFunction } from 'express';
+import pino from 'pino';
+import { isProduction } from '../../shared/config/env';
+
+const logger = pino();
+


The error handler creates its own pino() instance with default settings, which can diverge from the app-wide logger config (level, serializers, destinations) and makes logs harder to correlate. Consider passing the configured logger in (DI) or initializing it with config.logLevel so it matches the rest of the service.

Copilot · 2026-02-14T10:24:39Z

.nvmrc

@@ -1 +1 @@
-18.18.0
+24.3.0


Root .nvmrc is set to Node 24.3.0, but the backend CI matrix runs Node 20.x and backend/package.json requires >=20. Consider aligning .nvmrc to the CI/runtime baseline (or documenting that Node 24 is required for the repo) to avoid local/CI drift.

Suggested change

24.3.0

20

Copilot · 2026-02-14T10:24:39Z

backend/src/interfaces/validation/searchSchema.ts

+    // Validate query parameters (throws if invalid)
+    searchQuerySchema.parse(req.query);
+
+    // If validation passes, continue to controller
+    next();


The validation middleware parses req.query but discards the parsed/sanitized output, so downstream code still sees the untyped Express query object (e.g., string | string[]). Consider assigning const parsed = searchQuerySchema.parse(req.query) and attaching it to req (e.g., req.query = parsed as any or res.locals.searchQuery = parsed) so the controller can use the validated values.

Copilot · 2026-02-14T10:24:39Z

backend/src/interfaces/validation/searchSchema.ts

+      res.status(400).json({
+        ok: false,
+        provider: 'unknown',
+        error: {
+          code: 'validation_error',
+          message: 'Invalid query parameters',


Validation error responses always return provider: 'unknown', which diverges from the API contract/samples where provider is still set (typically github). Consider returning the default provider (or the validated provider, if present) to keep responses consistent for clients.

… response

…dar chart

…ecially forked repos

…esence and isVerified field value for user and org, respectively

Wildan Nahar added 13 commits February 14, 2026 12:46

feat: init spec-driven development

ee25e48

chore: use the latest, stable node

31500fe

feat: next iteration of the spec-driven; complete the 1st version of …

847ed8c

…backend-spec.md

feat(backend): initial backend setup

97c68a2

feat: setup deps

2746c4b

doc: add task lists

96ec464

feat: implement foundation

8480851

fix: ignore dist

67b0387

feat: initi mvp with graphql

7cbfa28

feat: app layer

4c08c9f

feat: http layer integration

34da9c5

test: add initial test and update readme

d51de46

fix: handle 404 not found

41a181c

github-advanced-security bot found potential problems Feb 14, 2026

View reviewed changes

Wildan Nahar added 8 commits February 14, 2026 17:25

fix tests

5f51690

test: increase coverage to over 80%

8dafec7

fix: update manual-test to use AccountData structure

6f971ab

- Destructure profile and repositories from fetchRepositories result - Display profile information including providerUserId - Replace all instances of repos with repositories

feat: use the actual all available lang colors

9d99638

chore: delete manual tests

dcd7ff5

doc: add info about forked repo

8840fb6

refactor: make gitlab and bitbucket unimplemented as they actually are

28ec631

fix test

75916f9

Copilot AI mentioned this pull request Feb 14, 2026

[WIP] Refactor monorepo structure with SDD #322

Closed

wildan3105 changed the title ~~Refactor/monorepo with sdd~~ Refactor/monorepo with spec-driven development Feb 14, 2026

wildan3105 requested a review from Copilot February 14, 2026 10:19

Copilot started reviewing on behalf of wildan3105 February 14, 2026 10:20 View session

Copilot AI reviewed Feb 14, 2026

View reviewed changes

Copilot AI mentioned this pull request Feb 14, 2026

Fix provider enum type casting for zod validation #323

Draft

Wildan Nahar added 30 commits February 15, 2026 12:04

frontend improvement: kpi or overview of stats

1ae6e98

frontend improvement: export dropdown - remove x and fb share

b5863e3

frontend improvement: smooth transitions

9cf6ae0

frontend improv: remove copy link

acd6c5c

frontend improvement: fix lint

83821ac

frontend improvement: loading state polish

a10f809

frontend improvement: micro states

c6204a7

feat: add optional location and websiteUrl for user and org's profile…

25db81a

… response

chore: handle nullish gracefully

d9db0e0

frontend improv: add optional location and websiteUrl for profile card

bdf81fc

frontend improv: add options (fork and unknown) next to search bar

07138c7

frontend improv: move forks and unknown options inside chart area

0f86745

frontend improv: always show 4 cards

564d12b

frontend improv: always show filter options if user is found

59aeed6

frontend improv: make fork and unknown false by default and remove ra…

964478b

…dar chart

feat: unify toolbar

3f87a72

frontend improv: micro polish

baba093

fix: resolve empty state when nothing happens

3c4c4ed

chore: remove github as its default provider

8ec7792

feat: add more info in profile card

38c7ea4

feat: change display from key to label to make it human-readable, esp…

ab2f0a0

…ecially forked repos

ui: add icon next to Advanced option

7570d00

doc: add similar projects in the readme

024c0d6

feat(backend): add isVerified field for profile depending on email pr…

964c2d4

…esence and isVerified field value for user and org, respectively

feat(frontend): update site title

0a62cde

feat: add verification badge for both user and org

a611f78

feat: createdAt field on the profile object

402be86

feat: add member since info

01c40bd

feat: handle ghe (self-host github)

bc21c9f

fix: lint

f7ff92b

@@ -1,5 +1,8 @@
             name: Backend CI
+            permissions:
+              contents: read
             on:
               push:
                 branches: [master, main, develop]

-    return response.json();
+    const { data, errors } = await response.json();
+    if (errors && errors.length > 0) {
+      const graphQLError = new Error(errors[0]?.message || 'GraphQL error');
+      graphQLError.errors = errors;
+      throw graphQLError;
+    }
+    return data;


		provider: z.enum(Object.values(Providers)).default(DEFAULT_PROVIDER).optional(),
		});

		@@ -1 +1 @@
		18.18.0
		24.3.0

Conversation

wildan3105 commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Screenshot of change (if there's UI update)

Uh oh!

Uh oh!

Check warning

Copilot Autofix

wildan3105 commented Feb 14, 2026

Uh oh!

Copilot AI commented Feb 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

wildan3105 Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

wildan3105 Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wildan3105 commented Feb 14, 2026 •

edited

Loading