@fuzdev/fuz_ui 0.206.7 → 0.206.9

package/src/lib/module.svelte.ts

@@ -1,12 +1,13 @@
 import type {
 	ModuleJsonInput,
 	ReExportJsonInput,
-	ExternalReExportJsonInput,
+	ExternalReExportJsonInput
 } from 'svelte-docinfo/types.js';
+import { EMPTY_ARRAY } from '@fuzdev/fuz_util/array.ts';
 
-import {Declaration} from './declaration.svelte.ts';
-import type {Library} from './library.svelte.ts';
-import {url_github_file} from '@fuzdev/fuz_util/package_helpers.ts';
+import { Declaration } from './declaration.svelte.ts';
+import type { Library } from './library.svelte.ts';
+import { url_github_file } from '@fuzdev/fuz_util/package_helpers.ts';
 
 /**
  * Groups entries by a string key, with groups sorted by key. Entries within
@@ -14,7 +15,7 @@ import {url_github_file} from '@fuzdev/fuz_util/package_helpers.ts';
  */
 const group_sorted = <T>(
 	entries: Array<T>,
-	get_key: (entry: T) => string,
+	get_key: (entry: T) => string
 ): Map<string, Array<T>> => {
 	const by_key: Map<string, Array<T>> = new Map();
 	for (const entry of entries) {
@@ -32,8 +33,11 @@ const group_sorted = <T>(
 /**
  * Rich runtime representation of a module with computed properties.
  *
- * Wraps svelte-docinfo's `ModuleJson` with reactive derivations,
- * URL generation, and `Declaration` instances.
+ * Wraps svelte-docinfo's `ModuleJson` with computed properties, URL
+ * generation, and `Declaration` instances.
+ *
+ * Computed properties are plain getters rather than `$derived` — see
+ * `Library` for why.
  *
  * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
  * @see `declaration.svelte.ts` for the `Declaration` wrapper class
@@ -57,28 +61,38 @@ export class Module {
 	 * A leading `./` or a `.js` runtime extension will not match. Top-level
 	 * files match by bare filename; nested files require the full sub-path.
 	 */
-	path = $derived(this.module_json.path);
+	get path(): string {
+		return this.module_json.path;
+	}
 
 	/**
 	 * Import-style path with ./ prefix.
 	 */
-	path_import = $derived('./' + this.path);
+	get path_import(): string {
+		return './' + this.path;
+	}
 
-	module_comment = $derived(this.module_json.moduleComment);
+	get module_comment(): string | undefined {
+		return this.module_json.moduleComment;
+	}
+
+	#declarations: Array<Declaration> | undefined;
 
 	/**
 	 * Array of `Declaration` instances. Filters out default exports.
 	 */
-	declarations = $derived(
-		(this.module_json.declarations ?? [])
+	get declarations(): Array<Declaration> {
+		return (this.#declarations ??= (this.module_json.declarations ?? [])
 			.filter((declaration_json) => declaration_json.name !== 'default')
-			.map((declaration_json) => new Declaration(this, declaration_json)),
-	);
+			.map((declaration_json) => new Declaration(this, declaration_json)));
+	}
 
 	/**
 	 * API documentation URL for this module.
 	 */
-	url_api = $derived(`/docs/api${this.library.url_prefix}/${this.path}`);
+	get url_api(): string {
+		return `/docs/api${this.library.url_prefix}/${this.path}`;
+	}
 
 	/**
 	 * Public documentation link (if `homepage_url` is available).
@@ -86,42 +100,52 @@ export class Module {
 	 * Absolute URL into the library's own deployed docs, for rendering a
 	 * foreign library's modules on a different site (e.g. an aggregator).
 	 */
-	url_api_full = $derived(
-		this.library.homepage_url
-			? `${this.library.homepage_url.replace(/\/$/, '')}/docs/api/${this.path}`
-			: undefined,
-	);
+	get url_api_full(): string | undefined {
+		const { homepage_url } = this.library;
+		return homepage_url ? `${homepage_url.replace(/\/$/, '')}/docs/api/${this.path}` : undefined;
+	}
 
 	/**
 	 * GitHub source URL.
 	 */
-	url_github = $derived(
-		this.library.repo_url
-			? url_github_file(this.library.repo_url, `src/lib/${this.path}`)
-			: undefined,
-	);
+	get url_github(): string | undefined {
+		const { repo_url } = this.library;
+		return repo_url ? url_github_file(repo_url, `src/lib/${this.path}`) : undefined;
+	}
 
 	/**
 	 * Whether the module has renderable declarations (after the default-export
 	 * filter in `declarations`).
 	 */
-	has_declarations: boolean = $derived(this.declarations.length > 0);
+	get has_declarations(): boolean {
+		return this.declarations.length > 0;
+	}
 
-	has_module_comment: boolean = $derived(!!this.module_comment);
+	get has_module_comment(): boolean {
+		return !!this.module_comment;
+	}
 
 	/**
 	 * Modules this imports (paths relative to src/lib).
 	 */
-	dependencies = $derived(this.module_json.dependencies ?? []);
+	get dependencies(): NonNullable<ModuleJsonInput['dependencies']> {
+		return this.module_json.dependencies ?? EMPTY_ARRAY;
+	}
 
 	/**
 	 * Modules that import this (paths relative to src/lib).
 	 */
-	dependents = $derived(this.module_json.dependents ?? []);
+	get dependents(): NonNullable<ModuleJsonInput['dependents']> {
+		return this.module_json.dependents ?? EMPTY_ARRAY;
+	}
 
-	has_dependencies: boolean = $derived(this.dependencies.length > 0);
+	get has_dependencies(): boolean {
+		return this.dependencies.length > 0;
+	}
 
-	has_dependents: boolean = $derived(this.dependents.length > 0);
+	get has_dependents(): boolean {
+		return this.dependents.length > 0;
+	}
 
 	/**
 	 * Same-name re-export edges in this module's source (`ModuleJson.reExports`)
@@ -129,9 +153,13 @@ export class Module {
 	 * then module. Renamed re-exports appear as declarations with `aliasOf`
 	 * instead, and star exports in `star_exports`.
 	 */
-	re_exports = $derived(this.module_json.reExports ?? []);
+	get re_exports(): NonNullable<ModuleJsonInput['reExports']> {
+		return this.module_json.reExports ?? EMPTY_ARRAY;
+	}
 
-	has_re_exports: boolean = $derived(this.re_exports.length > 0);
+	get has_re_exports(): boolean {
+		return this.re_exports.length > 0;
+	}
 
 	/**
 	 * Modules fully re-exported via `export * from './module'`
@@ -139,55 +167,76 @@ export class Module {
 	 * not materialized as declarations or `re_exports` edges — this is their
 	 * sole encoding.
 	 */
-	star_exports = $derived(this.module_json.starExports ?? []);
+	get star_exports(): NonNullable<ModuleJsonInput['starExports']> {
+		return this.module_json.starExports ?? EMPTY_ARRAY;
+	}
 
-	has_star_exports: boolean = $derived(this.star_exports.length > 0);
+	get has_star_exports(): boolean {
+		return this.star_exports.length > 0;
+	}
+
+	#re_exports_by_module: Map<string, Array<ReExportJsonInput>> | undefined;
 
 	/**
 	 * Re-export edges grouped by canonical module path, groups sorted by path.
 	 * Entries within each group keep their name-sorted serialized order.
 	 */
-	re_exports_by_module: Map<string, Array<ReExportJsonInput>> = $derived(
-		group_sorted(this.re_exports, (entry) => entry.module),
-	);
+	get re_exports_by_module(): Map<string, Array<ReExportJsonInput>> {
+		return (this.#re_exports_by_module ??= group_sorted(this.re_exports, (entry) => entry.module));
+	}
 
 	/**
 	 * Re-exports whose immediate target is an external package
 	 * (`ModuleJson.externalReExports`) — `export {x} from 'pkg'` and
 	 * `export * as ns from 'pkg'` forms, sorted by name then specifier.
 	 */
-	external_re_exports = $derived(this.module_json.externalReExports ?? []);
+	get external_re_exports(): NonNullable<ModuleJsonInput['externalReExports']> {
+		return this.module_json.externalReExports ?? EMPTY_ARRAY;
+	}
+
+	get has_external_re_exports(): boolean {
+		return this.external_re_exports.length > 0;
+	}
 
-	has_external_re_exports: boolean = $derived(this.external_re_exports.length > 0);
+	#external_re_exports_by_specifier: Map<string, Array<ExternalReExportJsonInput>> | undefined;
 
 	/**
 	 * External re-exports grouped by package specifier, groups sorted by
 	 * specifier. Entries within each group keep their name-sorted serialized
 	 * order.
 	 */
-	external_re_exports_by_specifier: Map<string, Array<ExternalReExportJsonInput>> = $derived(
-		group_sorted(this.external_re_exports, (entry) => entry.specifier),
-	);
+	get external_re_exports_by_specifier(): Map<string, Array<ExternalReExportJsonInput>> {
+		return (this.#external_re_exports_by_specifier ??= group_sorted(
+			this.external_re_exports,
+			(entry) => entry.specifier
+		));
+	}
 
 	/**
 	 * External packages fully re-exported via `export * from 'pkg'`
 	 * (`ModuleJson.externalStarExports`), in source order. The projected
 	 * names are unknown — the package isn't analyzed.
 	 */
-	external_star_exports = $derived(this.module_json.externalStarExports ?? []);
+	get external_star_exports(): NonNullable<ModuleJsonInput['externalStarExports']> {
+		return this.module_json.externalStarExports ?? EMPTY_ARRAY;
+	}
 
-	has_external_star_exports: boolean = $derived(this.external_star_exports.length > 0);
+	get has_external_star_exports(): boolean {
+		return this.external_star_exports.length > 0;
+	}
 
 	/**
 	 * Whether the module re-exports anything in any form — same-name edges,
 	 * star exports, or the external variants of both.
 	 */
-	has_any_re_exports: boolean = $derived(
-		this.has_re_exports ||
+	get has_any_re_exports(): boolean {
+		return (
+			this.has_re_exports ||
 			this.has_star_exports ||
 			this.has_external_re_exports ||
-			this.has_external_star_exports,
-	);
+			this.has_external_star_exports
+		);
+	}
 
 	constructor(library: Library, module_json: ModuleJsonInput) {
 		this.library = library;

package/src/lib/module_contextmenu.ts

@@ -1,5 +1,5 @@
-import type {Module} from './module.svelte.ts';
-import type {ContextmenuParams} from './contextmenu_state.svelte.ts';
+import type { Module } from './module.svelte.ts';
+import type { ContextmenuParams } from './contextmenu_state.svelte.ts';
 
 // TODO @many expand contextmenus for docs
 
@@ -11,8 +11,8 @@ export const create_module_contextmenu = (module: Module): Array<ContextmenuPara
 		entries.push({
 			snippet: 'link',
 			props: {
-				href: module.url_github,
-			},
+				href: module.url_github
+			}
 		});
 	}
 

package/src/lib/project_stats.ts

@@ -0,0 +1,220 @@
+/**
+ * Types and pure helpers for project commit-activity stats.
+ *
+ * The committed dataset (`project_stats_data.ts`, written by the
+ * `project_stats_update` task) stores daily commit counts per project as the
+ * master granularity; coarser scopes like monthly are derived at runtime by
+ * rebucketing. All date handling is UTC — `YYYY-MM-DD` strings and "epoch
+ * days" (days since the Unix epoch) — so results are deterministic across
+ * machines.
+ *
+ * @module
+ */
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Daily commit counts for one project.
+ */
+export interface ProjectCommitStats {
+	/**
+	 * Project name, matching `project_items`.
+	 */
+	name: string;
+	/**
+	 * UTC date (`YYYY-MM-DD`) of the first day bucket, the day of the first commit.
+	 */
+	start_date: string;
+	/**
+	 * Commits per UTC day from `start_date` through the snapshot's `end_date`, inclusive.
+	 */
+	daily_counts: Array<number>;
+}
+
+/**
+ * A snapshot of commit stats across projects, sharing a single `end_date`.
+ */
+export interface ProjectStatsSnapshot {
+	/**
+	 * ISO datetime when the snapshot was collected.
+	 */
+	generated_at: string;
+	/**
+	 * UTC date (`YYYY-MM-DD`) of the final day bucket, shared by every project.
+	 */
+	end_date: string;
+	projects: Array<ProjectCommitStats>;
+}
+
+/**
+ * A derived series of bucketed counts for one project.
+ */
+export interface ProjectStatsSeries {
+	name: string;
+	counts: Array<number>;
+}
+
+/**
+ * Converts a UTC `YYYY-MM-DD` date to days since the Unix epoch.
+ */
+export const epoch_day_from_date = (date: string): number => {
+	const [year, month, day] = date.split('-').map(Number);
+	return Date.UTC(year!, month! - 1, day) / DAY_MS;
+};
+
+/**
+ * Converts days since the Unix epoch to a UTC `YYYY-MM-DD` date.
+ */
+export const date_from_epoch_day = (epoch_day: number): string =>
+	new Date(epoch_day * DAY_MS).toISOString().slice(0, 10);
+
+/**
+ * Buckets commit timestamps into daily counts from the earliest commit's UTC
+ * day through `end_date`, inclusive.
+ *
+ * @param timestamps - commit times as Unix epoch seconds
+ * @param end_date - UTC date (`YYYY-MM-DD`) of the final bucket; later timestamps clamp into it
+ * @returns the start date and daily counts, or `null` if `timestamps` is empty
+ */
+export const daily_counts_from_timestamps = (
+	timestamps: Array<number>,
+	end_date: string
+): { start_date: string; daily_counts: Array<number> } | null => {
+	if (timestamps.length === 0) return null;
+	const days = timestamps.map((t) => Math.floor((t * 1000) / DAY_MS));
+	const end_day = epoch_day_from_date(end_date);
+	let start_day = end_day;
+	for (const day of days) {
+		if (day < start_day) start_day = day;
+	}
+	const daily_counts: Array<number> = new Array(end_day - start_day + 1).fill(0);
+	for (const day of days) {
+		daily_counts[Math.min(day, end_day) - start_day]! += 1;
+	}
+	return { start_date: date_from_epoch_day(start_day), daily_counts };
+};
+
+/**
+ * Pads `daily_counts` with leading zeros so the series starts at
+ * `padded_start_date` instead of `start_date`.
+ *
+ * Returns the input array unchanged when `padded_start_date` is not earlier
+ * than `start_date`.
+ */
+export const daily_counts_pad_start = (
+	daily_counts: Array<number>,
+	start_date: string,
+	padded_start_date: string
+): Array<number> => {
+	const pad = epoch_day_from_date(start_date) - epoch_day_from_date(padded_start_date);
+	if (pad <= 0) return daily_counts;
+	return (new Array(pad).fill(0) as Array<number>).concat(daily_counts);
+};
+
+/**
+ * Rebuckets daily counts into calendar-month (UTC) counts.
+ *
+ * The first and last buckets may cover partial months.
+ */
+export const monthly_counts_from_daily = (
+	daily_counts: Array<number>,
+	start_date: string
+): Array<number> => {
+	const start_day = epoch_day_from_date(start_date);
+	const counts: Array<number> = [];
+	let current_month_key: number | null = null;
+	for (let i = 0; i < daily_counts.length; i++) {
+		const date = new Date((start_day + i) * DAY_MS);
+		const month_key = date.getUTCFullYear() * 12 + date.getUTCMonth();
+		if (month_key !== current_month_key) {
+			current_month_key = month_key;
+			counts.push(0);
+		}
+		counts[counts.length - 1]! += daily_counts[i]!;
+	}
+	return counts;
+};
+
+/**
+ * Rebuckets daily counts into 7-day counts, anchored at the end of the series
+ * so the newest bucket always covers a full 7 days.
+ *
+ * The first bucket may cover fewer days when the length isn't a multiple of 7.
+ */
+export const weekly_counts_from_daily = (daily_counts: Array<number>): Array<number> => {
+	const counts: Array<number> = [];
+	for (let end = daily_counts.length; end > 0; end -= 7) {
+		let sum = 0;
+		for (let i = Math.max(0, end - 7); i < end; i++) {
+			sum += daily_counts[i]!;
+		}
+		counts.push(sum);
+	}
+	return counts.reverse();
+};
+
+const to_aligned_series = (
+	snapshot: ProjectStatsSnapshot,
+	rebucket: (daily_counts: Array<number>, start_date: string) => Array<number>
+): { series: Array<ProjectStatsSeries>; max: number } => {
+	if (snapshot.projects.length === 0) return { series: [], max: 0 };
+	let shared_start = snapshot.projects[0]!.start_date;
+	for (const project of snapshot.projects) {
+		if (project.start_date < shared_start) shared_start = project.start_date;
+	}
+	let max = 0;
+	const series = snapshot.projects.map((project) => {
+		const daily = daily_counts_pad_start(project.daily_counts, project.start_date, shared_start);
+		const counts = rebucket(daily, shared_start);
+		for (const count of counts) {
+			if (count > max) max = count;
+		}
+		return { name: project.name, counts };
+	});
+	return { series, max };
+};
+
+/**
+ * Derives aligned monthly series for every project in `snapshot`, sharing one
+ * time window and one scale.
+ *
+ * Each series spans from the earliest project's `start_date` through the
+ * snapshot's `end_date` (younger projects are zero-padded at the front), so
+ * all series have the same length and bucket boundaries. `max` is the largest
+ * monthly count across all projects, for rendering every series at the same
+ * vertical scale.
+ */
+export const project_stats_to_monthly_series = (
+	snapshot: ProjectStatsSnapshot
+): { series: Array<ProjectStatsSeries>; max: number } =>
+	to_aligned_series(snapshot, monthly_counts_from_daily);
+
+/**
+ * Derives aligned weekly series for every project in `snapshot`, sharing one
+ * time window and one scale — the weekly sibling of
+ * `project_stats_to_monthly_series`.
+ */
+export const project_stats_to_weekly_series = (
+	snapshot: ProjectStatsSnapshot
+): { series: Array<ProjectStatsSeries>; max: number } =>
+	to_aligned_series(snapshot, weekly_counts_from_daily);
+
+const start_date_formatter = new Intl.DateTimeFormat('en-US', {
+	month: 'long',
+	day: 'numeric',
+	year: 'numeric',
+	timeZone: 'UTC'
+});
+
+/**
+ * Formats a one-line human-readable summary of a project's commit stats,
+ * e.g. `"gro — 2,386 commits since August 7, 2019"`. Used for accessible
+ * labels and tooltips.
+ */
+export const project_stats_label = (project: ProjectCommitStats): string => {
+	let total = 0;
+	for (const count of project.daily_counts) {
+		total += count;
+	}
+	return `${project.name} — ${total.toLocaleString('en-US')} commits since ${start_date_formatter.format(new Date(project.start_date))}`;
+};