Skip to content

Commit 1c67b6e

Browse files
Nikhita-14Nikhita-14
authored
Merge branch 'sugarlabs:master' into master
2 parents b850a2e + 48e71e9 commit 1c67b6e

31 files changed

+10019
-2581
lines changed

‎.eslintignore‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎.eslintrc.json‎

Lines changed: 0 additions & 41 deletions
This file was deleted.

‎.gitattributes‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,6 @@
66
*.md text eol=lf
77
*.yml text eol=lf
88
*.yaml text eol=lf
9+
# Mark locale files as generated - hides them from PR diffs by default
10+
# These files are auto-generated from PO files via convert_po_to_json.py
11+
locales/*.json linguist-generated=true

‎.github/workflows/linter.yml‎

Lines changed: 43 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,48 @@
11
name: ESLint
22

33
on:
4-
pull_request:
5-
branches: [master]
4+
pull_request:
5+
branches: [master]
66

77
jobs:
8-
lint:
9-
name: Lint updated JavaScript files with ESLint
10-
11-
runs-on: ubuntu-latest
12-
13-
steps:
14-
- name: Checkout code
15-
uses: actions/checkout@v4
16-
with:
17-
fetch-depth: 0
18-
ref: ${{ github.event.pull_request.head.sha }}
19-
20-
- name: Set up Node.js
21-
uses: actions/setup-node@v4
22-
with:
23-
node-version: 20.x
24-
25-
- name: Get changed JavaScript files
26-
id: get_files
27-
run: |
28-
CHANGED_FILES=$(git diff --diff-filter=ACMRT --name-only ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }} -- '*.js')
29-
echo "files<<EOF" >> $GITHUB_ENV
30-
echo "$CHANGED_FILES" >> $GITHUB_ENV
31-
echo "EOF" >> $GITHUB_ENV
32-
33-
- name: Install dependencies
34-
run: npm ci
35-
36-
- name: Run ESLint on changed files
37-
if: env.files != ''
38-
run: |
39-
echo "Linting the following files:"
40-
echo "$files"
41-
echo "$files" | xargs npx eslint
42-
- name: Run Prettier check on changed files
43-
if: env.files != ''
44-
run: |
45-
echo "Checking formatting for the following files:"
46-
echo "$files"
47-
echo "$files" | xargs npx prettier --check
8+
lint:
9+
name: Lint updated JavaScript files with ESLint
10+
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v4
16+
with:
17+
fetch-depth: 0
18+
ref: ${{ github.event.pull_request.head.sha }}
19+
20+
- name: Set up Node.js
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: 20.x
24+
cache: "npm"
25+
26+
- name: Get changed JavaScript files
27+
id: get_files
28+
run: |
29+
CHANGED_FILES=$(git diff --diff-filter=ACMRT --name-only ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }} -- '*.js')
30+
echo "files<<EOF" >> $GITHUB_ENV
31+
echo "$CHANGED_FILES" >> $GITHUB_ENV
32+
echo "EOF" >> $GITHUB_ENV
33+
34+
- name: Install dependencies
35+
run: npm ci
36+
37+
- name: Run ESLint on changed files
38+
if: env.files != ''
39+
run: |
40+
echo "Linting the following files:"
41+
echo "$files"
42+
echo "$files" | xargs npx eslint
43+
- name: Run Prettier check on changed files
44+
if: env.files != ''
45+
run: |
46+
echo "Checking formatting for the following files:"
47+
echo "$files"
48+
echo "$files" | xargs npx prettier --check

‎.github/workflows/node.js.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ jobs:
1515

1616
strategy:
1717
matrix:
18-
node-version: [18.x, 20.x]
18+
node-version: [20.x, 22.x]
1919

2020
steps:
2121
- name: Checkout code

‎.github/workflows/po-to-json-autocommit.yml‎

Lines changed: 56 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,56 @@
1-
name: Auto-convert PO to JSON and commit
2-
3-
on:
4-
push:
5-
paths:
6-
- 'po/**/*.po'
7-
8-
jobs:
9-
convert-and-commit:
10-
runs-on: ubuntu-latest
11-
12-
steps:
13-
- name: Checkout code
14-
uses: actions/checkout@v4
15-
with:
16-
persist-credentials: true
17-
fetch-depth: 0
18-
19-
- name: Set up Python
20-
uses: actions/setup-python@v5
21-
with:
22-
python-version: '3.x'
23-
24-
- name: Find changed .po files
25-
id: find_po
26-
run: |
27-
git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep '^po/.*\.po$' > changed_po_files.txt || true
28-
cat changed_po_files.txt
29-
echo "po_files<<EOF" >> $GITHUB_OUTPUT
30-
echo "$(cat changed_po_files.txt)" >> $GITHUB_OUTPUT
31-
echo "EOF" >> $GITHUB_OUTPUT
32-
33-
- name: Run conversion script
34-
if: steps.find_po.outputs.po_files != ''
35-
run: |
36-
mkdir -p locales
37-
while IFS= read -r po_file; do
38-
echo "▶ Converting $po_file"
39-
python3 convert_po_to_json.py "$po_file" "locales"
40-
done < changed_po_files.txt
41-
42-
- name: Commit and push updated JSON
43-
if: steps.find_po.outputs.po_files != ''
44-
run: |
45-
git config --global user.name "github-actions[bot]"
46-
git config --global user.email "github-actions[bot]@users.noreply.github.com"
47-
48-
git add locales/*.json
49-
50-
if git diff --cached --quiet; then
51-
echo "✅ No JSON changes to commit."
52-
else
53-
git commit -m "chore(i18n): auto-update JSON files from updated PO files"
54-
git push origin ${{ github.ref }}
55-
echo "🚀 Pushed updated JSON files."
56-
fi
1+
name: Auto-convert PO to JSON and commit
2+
3+
on:
4+
push:
5+
paths:
6+
- 'po/**/*.po'
7+
8+
jobs:
9+
convert-and-commit:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v4
15+
with:
16+
persist-credentials: true
17+
fetch-depth: 0
18+
19+
- name: Set up Python
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: '3.x'
23+
24+
- name: Find changed .po files
25+
id: find_po
26+
run: |
27+
git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep '^po/.*\.po$' > changed_po_files.txt || true
28+
cat changed_po_files.txt
29+
echo "po_files<<EOF" >> $GITHUB_OUTPUT
30+
echo "$(cat changed_po_files.txt)" >> $GITHUB_OUTPUT
31+
echo "EOF" >> $GITHUB_OUTPUT
32+
33+
- name: Run conversion script
34+
if: steps.find_po.outputs.po_files != ''
35+
run: |
36+
mkdir -p locales
37+
while IFS= read -r po_file; do
38+
echo "▶ Converting $po_file"
39+
python3 convert_po_to_json.py "$po_file" "locales"
40+
done < changed_po_files.txt
41+
42+
- name: Commit and push updated JSON
43+
if: steps.find_po.outputs.po_files != ''
44+
run: |
45+
git config --global user.name "github-actions[bot]"
46+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
47+
48+
git add locales/*.json
49+
50+
if git diff --cached --quiet; then
51+
echo "✅ No JSON changes to commit."
52+
else
53+
git commit -m "chore(i18n): auto-update JSON files from updated PO files"
54+
git push origin ${{ github.ref }}
55+
echo "🚀 Pushed updated JSON files."
56+
fi

‎.github/workflows/security_scan.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
- name: Setup Node.js
1919
uses: actions/setup-node@v4
2020
with:
21-
node-version: '18'
21+
node-version: '20'
2222

2323
- name: Install Dependencies
2424
run: npm install

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ node_modules/
33
coverage/
44
.DS_Store
55
**/.DS_Store
6+
Docs/architecture/dependency-analysis-report.json
7+
Docs/architecture/dev_architecture.html
8+
!Docs/architecture/*.svg
69

710
# Lighthouse CI
8-
.lighthouseci/
11+
.lighthouseci/

‎DOCS_MODULE_ARCHITECTURE.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Music Blocks Module Architecture & Dependency Analysis
2+
3+
## Overview
4+
This document outlines the current state of the Music Blocks module system as of January 2026. The architecture is currently in a transition phase between global-scope scripts and an asynchronous module definition (AMD) system using RequireJS.
5+
6+
## 1. Core Bootstrap Sequence
7+
The application initialization follows a multi-phase approach:
8+
1. **Phase 0 (HTML/Splash)**: `index.html` loads early scripts and CSS.
9+
2. **Phase 1 (Loader)**: `js/loader.js` configures RequireJS and initializes `i18next`.
10+
3. **Phase 2 (Core Load)**: RequireJS loads `activity/activity` and `utils/utils`.
11+
4. **Phase 3 (App Initialization)**: The `Activity` class initializes the UI, Canvas, and secondary modules.
12+
13+
## 2. Dependency Management Strategy
14+
Music Blocks primarily uses two methods for dependency management:
15+
- **RequireJS (AMD)**: Used for external libraries (Tone.js, p5.js, i18next) and some internal utilities.
16+
- **Global Namespace**: Most internal modules (`Logo`, `Blocks`, `Turtles`) are loaded via RequireJS but register themselves on the `window` object or rely on other globals being present.
17+
18+
### Key Module Manifests
19+
Internal dependencies are manually managed in `js/activity.js` via the `MYDEFINES` array. Analysis shows **97 modules** are orchestrated this way.
20+
21+
## 3. High-Risk Dependency Chains (Data-Driven)
22+
Based on automated analysis of 123 modules and **792 implicit dependencies** via globals, the following "Bottleneck Modules" have been identified:
23+
24+
| Module | Incoming Dependencies | Role |
25+
| :--- | :--- | :--- |
26+
| `js/utils/musicutils.js` | 177 | Core music logic, pitch/frequency conversions. |
27+
| `js/artwork.js` | 118 | Visual assets and block icons. |
28+
| `js/logo.js` | 99 | Execution engine and core state. |
29+
| `js/utils/utils.js` | 97 | General-purpose helpers (DOM, math, browser). |
30+
| `js/protoblocks.js` | 56 | Block definitions and structure. |
31+
32+
### Interpretation
33+
A change in `musicutils.js` potentially affects 177 other modules. This is the highest-risk area for regressions.
34+
35+
## 4. Identified Architectural Risks
36+
1. **Implicit Globals (792 instances)**: Most module "dependencies" are not managed by RequireJS but are instead implicit. If `musicutils.js` fails to load or registers its globals late, 177 other modules may crash.
37+
2. **Circular Dependencies**: Since variables are registered globally, it is easy to create cycles where `logo.js` uses `musicutils.js` which in turn might use a constant from `logo.js`.
38+
3. **Global Namespace Overcrowding**: There are over 468 unique symbols exported to the global namespace, increasing the likelihood of name collisions.
39+
40+
## 5. Visual Dependency Graph (High Level)
41+
```mermaid
42+
graph TD
43+
index.html --> loader.js
44+
loader.js --> lib/require.js
45+
loader.js --> i18next
46+
loader.js --> activity.js
47+
loader.js --> utils.js
48+
49+
subgraph "Core Cluster"
50+
activity.js --> logo.js
51+
activity.js --> blocks.js
52+
activity.js --> turtles.js
53+
activity.js --> palette.js
54+
end
55+
56+
logo.js --> synthutils.js
57+
logo.js --> musicutils.js
58+
blocks.js --> logo.js
59+
turtles.js --> logo.js
60+
61+
subgraph "External Libraries"
62+
tone.js
63+
p5.js
64+
createjs
65+
end
66+
```
67+
68+
## 6. Tooling & Maintenance
69+
70+
### Source Control Policy
71+
To maintain a clean repository and avoid merge conflicts on binary/large generated files:
72+
1. **Source Files (Committed)**: The Python analysis script (`scripts/analyze-dependencies.py`), the Graphviz source (`Docs/architecture/dependency-graph.dot`), and the rendered SVG (`Docs/architecture/dependency-graph.svg`) are versioned for easier review.
73+
2. **Generated Data (Ignored)**: Output reports (`.json`) are excluded from Git to prevent merge conflicts.
74+
75+
### Regeneration Instructions
76+
To update the dependency analysis data after making module changes, run:
77+
```bash
78+
python3 scripts/analyze-dependencies.py
79+
```
80+
This script will automatically update the `.dot`, `.json`, and `.svg` files (if Graphviz is installed).
81+
82+
### Visual Audit Tool
83+
A local visualizer is provided for deep-dive architecture audits:
84+
- **Location**: `Docs/architecture/dev_architecture.html`
85+
- **Regeneration**: This file can be updated to point to the latest `dependency-graph.dot` for interactive exploration.
86+
- **Audience**: This is an internal tool for maintainers and contributors during the refactoring of #2632.
87+
88+

0 commit comments

Comments
 (0)