Merge pull request #2825 from codecrafters-io/feature/add-stage-list-item-components

Add Code example insights index page

Author: ryan-gang

.gitignore

@@ -29,4 +29,7 @@
 
 # broccoli-debug
 /DEBUG/
+
 .aider*
+.claude/
+.machtiani.ignore

app/components/course-admin/code-example-insights-index-page/stage-list-item/index.hbs

@@ -0,0 +1,42 @@
+<LinkTo
+  class="flex items-center justify-between flex-wrap gap-x-6 gap-y-2 py-3 group/stage-list-item hover:bg-gray-50 px-1"
+  data-test-code-example-insights-index-list-item
+  role="button"
+  @route="course.stage.code-examples"
+  @models={{array @stage.course.slug @stage.slug}}
+  target="_blank"
+  ...attributes
+>
+  <div class="min-w-0">
+    <div class="flex items-center flex-wrap gap-2">
+      <div class="font-semibold text-sm text-gray-700">{{@stage.name}}</div>
+      <svg viewBox="0 0 2 2" class="h-0.5 w-0.5 fill-current text-gray-300">
+        <circle cx="1" cy="1" r="1" />
+      </svg>
+      <CourseAdmin::CodeExampleInsightsIndexPage::StageListItem::Statistic
+        @statistic={{this.analysis.solutionsCountStatistic}}
+        @fallbackLabel="solutions"
+      />
+    </div>
+  </div>
+  <div class="flex flex-none items-center gap-x-2">
+    <CourseAdmin::CodeExampleInsightsIndexPage::StageListItem::Statistic
+      @statistic={{this.analysis.medianChangedLinesStatistic}}
+      @fallbackLabel="lines"
+    />
+    <svg viewBox="0 0 2 2" class="h-0.5 w-0.5 fill-current text-gray-300">
+      <circle cx="1" cy="1" r="1" />
+    </svg>
+    <CourseAdmin::CodeExampleInsightsIndexPage::StageListItem::Statistic
+      @statistic={{this.analysis.upvotesCountStatistic}}
+      @fallbackLabel="upvotes"
+    />
+    <svg viewBox="0 0 2 2" class="h-0.5 w-0.5 fill-current text-gray-300">
+      <circle cx="1" cy="1" r="1" />
+    </svg>
+    <CourseAdmin::CodeExampleInsightsIndexPage::StageListItem::Statistic
+      @statistic={{this.analysis.downvotesCountStatistic}}
+      @fallbackLabel="downvotes"
+    />
+  </div>
+</LinkTo>

app/components/course-admin/code-example-insights-index-page/stage-list-item/index.ts

@@ -0,0 +1,24 @@
+import Component from '@glimmer/component';
+import type CourseStageModel from 'codecrafters-frontend/models/course-stage';
+import type LanguageModel from 'codecrafters-frontend/models/language';
+
+interface Signature {
+  Element: HTMLAnchorElement;
+
+  Args: {
+    language: LanguageModel;
+    stage: CourseStageModel;
+  };
+}
+
+export default class StageListItemComponent extends Component<Signature> {
+  get analysis() {
+    return this.args.stage.communitySolutionsAnalyses.findBy('language', this.args.language);
+  }
+}
+
+declare module '@glint/environment-ember-loose/registry' {
+  export default interface Registry {
+    'CourseAdmin::CodeExampleInsightsIndexPage::StageListItem': typeof StageListItemComponent;
+  }
+}

app/components/course-admin/code-example-insights-index-page/stage-list-item/statistic.hbs

@@ -0,0 +1,26 @@
+<div class="inline-flex items-center gap-x-1 text-xs">
+  <div class="{{this.valueColorClasses}}">
+    {{#if (and @statistic @statistic.value)}}
+      <span class="font-semibold">
+        {{@statistic.value}}
+      </span>
+    {{else}}
+      -
+    {{/if}}
+  </div>
+  <div class="text-gray-400">
+    {{#if @statistic}}
+      {{@statistic.label}}
+    {{else if @fallbackLabel}}
+      {{@fallbackLabel}}
+    {{/if}}
+  </div>
+
+  {{#if @statistic}}
+    <EmberTooltip>
+      <div class="prose prose-sm prose-invert text-white">
+        {{markdown-to-html @statistic.explanationMarkdown}}
+      </div>
+    </EmberTooltip>
+  {{/if}}
+</div>

app/components/course-admin/code-example-insights-index-page/stage-list-item/statistic.ts

@@ -0,0 +1,32 @@
+import Component from '@glimmer/component';
+import type { CommunitySolutionsAnalysisStatistic } from 'codecrafters-frontend/models/community-solutions-analysis';
+
+interface Signature {
+  Element: HTMLDivElement;
+
+  Args: {
+    fallbackLabel?: string;
+    statistic?: CommunitySolutionsAnalysisStatistic;
+  };
+}
+
+export default class StatisticComponent extends Component<Signature> {
+  get valueColorClasses(): string {
+    if (!this.args.statistic) {
+      return 'text-gray-500';
+    }
+
+    return {
+      green: 'text-teal-500',
+      yellow: 'text-yellow-500',
+      red: 'text-red-500',
+      gray: 'text-gray-500',
+    }[this.args.statistic.color];
+  }
+}
+
+declare module '@glint/environment-ember-loose/registry' {
+  export default interface Registry {
+    'CourseAdmin::CodeExampleInsightsIndexPage::StageListItem::Statistic': typeof StatisticComponent;
+  }
+}

app/components/course-admin/header.ts

@@ -81,6 +81,14 @@ export default class CourseAdminHeaderComponent extends Component<Signature> {
         models: [this.args.course.slug],
         isActive: ['course-admin.stage-insights-index', 'course-admin.stage-insights'].includes(this.router.currentRouteName),
       },
+      {
+        icon: 'document-text',
+        name: 'Code Examples',
+        slug: 'code-examples',
+        route: 'course-admin.code-example-insights-index',
+        models: [this.args.course.slug],
+        isActive: ['course-admin.code-example-insights-index', 'course-admin.code-example-insights'].includes(this.router.currentRouteName),
+      },
       {
         icon: 'academic-cap',
         name: 'Evaluators',

app/controllers/course-admin/code-example-insights-index.ts

@@ -0,0 +1,21 @@
+import Controller from '@ember/controller';
+import { action } from '@ember/object';
+import { inject as service } from '@ember/service';
+import type RouterService from '@ember/routing/router-service';
+import type LanguageModel from 'codecrafters-frontend/models/language';
+import Store from '@ember-data/store';
+import type { ModelType } from 'codecrafters-frontend/routes/course-admin/code-example-insights-index';
+
+export default class CodeExampleInsightsIndexController extends Controller {
+  @service declare router: RouterService;
+  @service declare store: Store;
+
+  declare model: ModelType;
+
+  @action
+  onLanguageChange(language: LanguageModel) {
+    this.router.transitionTo({
+      queryParams: { language_slug: language.slug },
+    });
+  }
+}

app/models/community-solutions-analysis.ts

@@ -0,0 +1,130 @@
+import Model, { attr, belongsTo } from '@ember-data/model';
+import type CourseStageModel from './course-stage';
+import type LanguageModel from './language';
+
+export type CommunitySolutionsAnalysisStatistic = {
+  color: 'green' | 'yellow' | 'red' | 'gray';
+  explanationMarkdown: string;
+  label: string;
+  title: string;
+  value: string | null;
+};
+
+const solutionsCountThresholds = {
+  green: 100,
+  yellow: 15,
+};
+
+const upvotesCountThresholds = {
+  green: 5,
+  yellow: 1,
+};
+
+const downvotesCountThresholds = {
+  red: 3,
+  yellow: 3,
+};
+
+const downvotesCountExplanationMarkdown = `
+The number of downvotes on "scored" community solutions for this stage and language.
+
+Solutions are "scored" when they are recommended by our system. Downvotes indicate that users did not find these solutions helpful.
+`.trim();
+
+const medianChangedLinesExplanationMarkdown = `
+The median number of changed lines across all solutions for this stage and language.
+
+A high number may indicate that the stage requires extensive changes, while a low number typically indicates a more focused stage.
+`.trim();
+
+const solutionsCountExplanationMarkdown = `
+The number of community solutions available for this stage and language.
+
+A higher number indicates more examples for users to learn from.
+`.trim();
+
+const upvotesCountExplanationMarkdown = `
+The number of upvotes on "scored" community solutions for this stage and language.
+
+Solutions are "scored" when they are recommended by our system. Upvotes indicate that users found these solutions helpful.
+`.trim();
+
+export default class CommunitySolutionsAnalysisModel extends Model {
+  @belongsTo('course-stage', { async: false, inverse: 'communitySolutionsAnalyses' }) declare courseStage: CourseStageModel;
+  @belongsTo('language', { async: false, inverse: null }) declare language: LanguageModel;
+
+  @attr() declare changedLinesCountDistribution: Record<string, number>;
+  @attr('number') declare scoredSolutionDownvotesCount: number;
+  @attr('number') declare scoredSolutionUpvotesCount: number;
+  @attr('number') declare solutionsCount: number;
+
+  get downvotesCountStatistic(): CommunitySolutionsAnalysisStatistic {
+    return {
+      title: 'Downvotes on Scored Solutions',
+      label: 'downvotes',
+      value: this.scoredSolutionDownvotesCount !== undefined ? this.scoredSolutionDownvotesCount.toString() : null,
+      color:
+        this.scoredSolutionDownvotesCount !== undefined
+          ? this.calculateColorUsingInverseThresholds(this.scoredSolutionDownvotesCount, downvotesCountThresholds)
+          : 'gray',
+      explanationMarkdown: downvotesCountExplanationMarkdown,
+    };
+  }
+
+  get medianChangedLinesStatistic(): CommunitySolutionsAnalysisStatistic {
+    return {
+      title: 'Median Changed Lines',
+      label: 'lines',
+      value: this.p50 !== undefined ? this.p50.toString() : null,
+      color: 'gray',
+      explanationMarkdown: medianChangedLinesExplanationMarkdown,
+    };
+  }
+
+  get p50(): number {
+    return this.changedLinesCountDistribution?.['p50'] || 0;
+  }
+
+  get solutionsCountStatistic(): CommunitySolutionsAnalysisStatistic {
+    return {
+      title: 'Solutions Count',
+      label: 'solutions',
+      value: this.solutionsCount !== undefined ? this.solutionsCount.toString() : null,
+      color: this.solutionsCount !== undefined ? this.calculateColorUsingThresholds(this.solutionsCount, solutionsCountThresholds) : 'gray',
+      explanationMarkdown: solutionsCountExplanationMarkdown,
+    };
+  }
+
+  get upvotesCountStatistic(): CommunitySolutionsAnalysisStatistic {
+    return {
+      title: 'Upvotes on Scored Solutions',
+      label: 'upvotes',
+      value: this.scoredSolutionUpvotesCount !== undefined ? this.scoredSolutionUpvotesCount.toString() : null,
+      color:
+        this.scoredSolutionUpvotesCount !== undefined
+          ? this.calculateColorUsingThresholds(this.scoredSolutionUpvotesCount, upvotesCountThresholds)
+          : 'gray',
+      explanationMarkdown: upvotesCountExplanationMarkdown,
+    };
+  }
+
+  private calculateColorUsingInverseThresholds(value: number, thresholds: { red: number; yellow: number }): 'red' | 'yellow' | 'green' {
+    if (value >= thresholds.red) {
+      return 'red';
+    } else if (value >= thresholds.yellow) {
+      return 'yellow';
+    } else {
+      return 'green';
+    }
+  }
+
+  private calculateColorUsingThresholds(value: number, thresholds: { green: number; yellow: number }): 'green' | 'yellow' | 'red' {
+    if (value >= thresholds.green) {
+      return 'green';
+    } else if (value >= thresholds.yellow) {
+      return 'yellow';
+    } else {
+      return 'red';
+    }
+  }
+}

app/models/course-stage.ts

@@ -11,10 +11,14 @@ import type RepositoryModel from './repository';
 import Mustache from 'mustache';
 import type CourseStageParticipationAnalysisModel from './course-stage-participation-analysis';
 import type CourseStageParticipationModel from './course-stage-participation';
+import type CommunitySolutionsAnalysisModel from './community-solutions-analysis';
 
 export default class CourseStageModel extends Model {
   @belongsTo('course', { async: false, inverse: 'stages' }) declare course: CourseModel;
 
+  @hasMany('community-solutions-analysis', { async: false, inverse: 'courseStage' })
+  declare communitySolutionsAnalyses: CommunitySolutionsAnalysisModel[];
+
   @hasMany('course-stage-comment', { async: false, inverse: 'target' }) declare comments: CourseStageCommentModel[];
   @hasMany('community-course-stage-solution', { async: false, inverse: 'courseStage' })
   declare communitySolutions: CommunityCourseStageSolutionModel[];

app/router.ts

@@ -27,15 +27,17 @@ Router.map(function () {
   this.route('courses');
 
   this.route('course-admin', { path: '/courses/:course_slug/admin' }, function () {
-    this.route('buildpacks');
     this.route('buildpack', { path: '/buildpacks/:buildpack_id' });
+    this.route('buildpacks');
     this.route('code-example', { path: '/code-examples/:code_example_id' });
-    this.route('code-example-evaluators');
     this.route('code-example-evaluator', { path: '/code-example-evaluators/:evaluator_slug' });
+    this.route('code-example-evaluators');
+    this.route('code-example-insights', { path: '/code-examples/stage/:stage_slug' });
+    this.route('code-example-insights-index', { path: '/code-examples' });
     this.route('feedback');
     this.route('insights');
-    this.route('stage-insights-index', { path: '/stage-insights' });
     this.route('stage-insights', { path: '/stage-insights/:stage_slug' });
+    this.route('stage-insights-index', { path: '/stage-insights' });
     this.route('submissions');
     this.route('tester-version', { path: '/tester-versions/:tester_version_id' });
     this.route('tester-versions');