feat(norms): add TypeScript support and update documentation

[aditisingh02]

What this PR does

Adds a from-scratch TypeScript port of the Phase 1 · Lesson 14 (Norms & Distances) code, mirroring every function and demo in the existing Python implementation.

Kind of change

• New lesson
• Fix to an existing lesson
• Translation
• New output (prompt, skill, agent, MCP server)
• Docs / website / tooling

Checklist

• Code runs without errors with the listed dependencies
• No comments in code files (docs explain, code is self-explanatory)
• Built from scratch first, then shown with a framework (for new lessons)
• Lesson folder matches LESSON_TEMPLATE.md structure
• ROADMAP.md row for the lesson is a markdown link ([Name](phases/...)), not bare text
• One lesson per commit (atomic per-lesson rule)
• Tested locally / code output matches what docs/en.md claims

Phase / lesson

Phase 1 · 14-norms-and-distances

Notes for reviewer

• New file: phases/01-math-foundations/14-norms-and-distances/code/distances.ts — a from-scratch port (no framework, no package.json), beside the existing distances.py. Follows the repo's established port pattern (cf. 00-setup-and-tooling/01-dev-environment/, where verify.py / verify.ts / main.rs coexist). Run with npx tsx distances.ts.
• Ports all functions (norms, distances, cosine, dot, Mahalanobis with from-scratch matrix inversion, Jaccard, Levenshtein, KL divergence, Wasserstein, covariance) and all 13 demos.
• Randomness: the Python demos use Python's random (Mersenne Twister), which can't be reproduced exactly in JS. I added a small seeded PRNG (mulberry32 + Box–Muller) so the randomized demos are deterministic. Fixed-input demos (norms, distances, cosine, KL, Wasserstein) match the Python output exactly; the randomized demos produce different numbers but preserve every narrative conclusion the docs claim (e.g. Mahalanobis flagging the off-axis point that L2 misses, L1 driving weights to exact zero).
• Verified: npx tsx distances.ts → exit 0; tsc --strict --types node → exit 0.
• Docs/metadata updated to reflect the second language: docs/en.md **Language:** line + a note on the TS port; README.md Lang column; site/data.js rebuilt via node site/build.js (diff is only the timestamp + the changed lang field).

Note: the "Built from scratch first, then shown with a framework" box is unchecked because this is a port of an existing lesson, not a new lesson — the lesson already has its from-scratch/framework split.

Resolves Issue #311

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the Norms & Distances lesson metadata to include TypeScript and added a new TypeScript lesson module with distance, similarity, statistical, and distribution metrics plus console demos and entrypoint wiring.

Changes

Norms & Distances TypeScript lesson

Layer / File(s)	Summary
Lesson metadata and language listing README.md, phases/01-math-foundations/14-norms-and-distances/docs/en.md, site/data.js	The lesson is listed with Python and TypeScript in the curriculum table, lesson docs, and generated site data; the docs also reference code/distances.ts and its tsx run command.
Core distances and Mahalanobis phases/01-math-foundations/14-norms-and-distances/code/distances.ts	The TypeScript lesson file adds a seeded PRNG, vector norms, distance and similarity functions, matrix inversion, and Mahalanobis distance.
Set, string, and distribution measures phases/01-math-foundations/14-norms-and-distances/code/distances.ts	The lesson file also adds covariance estimation plus Jaccard similarity, Levenshtein distance, KL divergence, and 1D Wasserstein distance.
Introductory demos phases/01-math-foundations/14-norms-and-distances/code/distances.ts	The lesson file adds console demos for norms, point-to-point distances, cosine-versus-dot-product comparisons, and Mahalanobis distance.
Remaining demos and entrypoint phases/01-math-foundations/14-norms-and-distances/code/distances.ts	The lesson file adds demos for Jaccard, edit distance, KL divergence, Wasserstein distance, norm ordering, k-NN, nearest-neighbor comparison, embedding ranking, and L1/L2-style regularization, then runs them from main() on load.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.94% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding TypeScript support and updating docs for the norms lesson.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description directly matches the changeset by describing a new TypeScript port and documentation updates for the Norms & Distances lesson.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

phases/01-math-foundations/14-norms-and-distances/code/distances.ts (1)

4-4: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Prefer canonical sources over Wikipedia in citations.

The header cites Wikipedia for norms and Levenshtein distance. Per the repo guideline, code comments should cite RFCs, official specs, or academic papers as the canonical source (e.g., Levenshtein, V. I. (1966), Soviet Physics Doklady) rather than Wikipedia.

As per coding guidelines: "Cite RFCs, official specs, and academic papers when they are the canonical source."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@phases/01-math-foundations/14-norms-and-distances/code/distances.ts` at line
4, Replace the Wikipedia references in the top-of-file citation comment in
distances.ts with canonical sources: use an academic paper or other primary
source for the norm definition and Levenshtein distance instead of Wikipedia.
Update the comment near the file header so it points to the authoritative
references for the concepts mentioned, keeping the rest of the file unchanged.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@phases/01-math-foundations/14-norms-and-distances/docs/en.md`:
- Line 434: The docs in the norms-and-distances section reference `distances.ts`
directly, which conflicts with the `main.*` naming convention. Update the run
command in the same place as the `code/distances.ts` mention so it uses
`main.ts` if the file is renamed, and make sure both the filename and command
stay aligned together.

---

Nitpick comments:
In `@phases/01-math-foundations/14-norms-and-distances/code/distances.ts`:
- Line 4: Replace the Wikipedia references in the top-of-file citation comment
in distances.ts with canonical sources: use an academic paper or other primary
source for the norm definition and Levenshtein distance instead of Wikipedia.
Update the comment near the file header so it points to the authoritative
references for the concepts mentioned, keeping the rest of the file unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fa4d106b-15fb-4a86-8c02-1a251432b013

📥 Commits

Reviewing files that changed from the base of the PR and between c8b9b92 and a5984c1.

📒 Files selected for processing (4)

• README.md
• phases/01-math-foundations/14-norms-and-distances/code/distances.ts
• phases/01-math-foundations/14-norms-and-distances/docs/en.md
• site/data.js

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Run command references distances.ts directly — inconsistent with the main.* convention.

The instruction npx tsx distances.ts implies readers run the file directly by name. If the file is renamed to main.ts (to satisfy the frontmatter guideline above), this command should become npx tsx main.ts. Both changes should land together to stay consistent.

✏️ Proposed update (conditional on renaming the file)

-See `code/distances.py` for the complete implementation. Every function is built from scratch using only basic Python math. `code/distances.ts` is a from-scratch TypeScript port of the same functions and demos — run it with `npx tsx distances.ts`.
+See `code/distances.py` for the complete implementation. Every function is built from scratch using only basic Python math. `code/main.ts` is a from-scratch TypeScript port of the same functions and demos — run it with `npx tsx main.ts`.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	See `code/distances.py` for the complete implementation. Every function is built from scratch using only basic Python math. `code/distances.ts` is a from-scratch TypeScript port of the same functions and demos — run it with `npx tsx distances.ts`.
	See `code/distances.py` for the complete implementation. Every function is built from scratch using only basic Python math. `code/main.ts` is a from-scratch TypeScript port of the same functions and demos — run it with `npx tsx main.ts`.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@phases/01-math-foundations/14-norms-and-distances/docs/en.md` at line 434,
The docs in the norms-and-distances section reference `distances.ts` directly,
which conflicts with the `main.*` naming convention. Update the run command in
the same place as the `code/distances.ts` mention so it uses `main.ts` if the
file is renamed, and make sure both the filename and command stay aligned
together.

Source: Coding guidelines