Skip to content

Commit c09f21a

Browse files
committed
[docs] Reconcile GitHub import boundaries
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent badae48 commit c09f21a

3 files changed

Lines changed: 143 additions & 80 deletions

File tree

‎app/DEPENDENCIES.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ Toolchain pin: **Flutter 3.44.1 (stable)** / Dart SDK `^3.12.1` (see
3636
| `flutter_blue_plus` | runtime | `^1.35.0` | 1.36.8 | BSD-3-Clause | The BLE transport (A-02; FR-BLE-1/2/3/5). The **sole** importer lives under `lib/ble/`; no other layer may import it (enforced by `tools/ci/import_boundary.sh`, CON-8). Min 1.35.0 is the floor carrying the GATT service-filtered scan + `requestMtu(247)` + write-without-response API the `lib/ble` adapter binds to. It is a **federated** plugin: it hard-depends on all platform backends (`_android`/`_darwin`/`_linux`/`_web`); only the Android + iOS (`_darwin`) backends compile into PyBLE's shipped targets — see the **copyleft carve-out** under the transitive table. |
3737
| `intl` | runtime | `^0.20.2` | 0.20.2 | BSD-3-Clause | The ARB message runtime consumed by the generated `AppLocalizations` (X-12). The constraint is reconciled to the exact `intl` the pinned `flutter_localizations` (Flutter 3.44.1) admits — 0.20.2. |
3838
| `package_info_plus` | runtime | `^10.2.1` | 10.2.1 | BSD-3-Clause | The sole `lib/app/app_build_info.dart` adapter reads the actual installed iOS/Android version and build number for the X-11 About page (FR-ABOUT-3). It is never imported by `lib/pble`; static ASCII `kAppVersion` remains the PBLE/1 HELLO identity. Min 10.2.1 supports PyBLE's pinned Flutter 3.44.1, Dart 3.12.1, iOS 13, Java 17, AGP 9.0.1, and Gradle 9.1 toolchain. |
39+
| `http` | runtime | `^1.6.0` | 1.6.0 | BSD-3-Clause | The bounded public GitHub REST client for the connected A-33 subset ([ADR-0040](../docs/decisions/0040-sha-pinned-connected-github-import.md)). The direct dependency is confined to `lib/github_import/`'s production composition point and `GithubRepositoryClient`; all feature consumers bind to the neutral `GithubApi` seam. The adapter accepts only canonical public repository input, sends no credential or user source, permits requests only to exact HTTPS host `api.github.com`, disables redirects, pins every browse to a full commit SHA, and bounds time and response bodies. Min 1.6.0 supplies the abortable request surface used by the cancellation contract on the pinned Dart/Flutter toolchain. |
3940
| `webview_flutter` | runtime | `^4.14.1` | 4.14.1 | BSD-3-Clause | The offline platform-WebView host for the pinned Blockly runtime (A-31, ADR-0013). Min 4.14.1 matches PyBLE's Android 24 / iOS 13 platform floors and supplies `loadFlutterAsset`, JavaScript channels, and navigation delegates. Its sole importer is `lib/blocks/`; generated source and board actions stay in Dart behind the neutral `Connection` seam. |
4041
| `flutter_test` | dev (SDK) | Flutter SDK | 3.44.1 | BSD-3-Clause | Widget/unit/golden test harness; the substrate for the G1 suites (NFR-MAINT-4). |
4142
| `integration_test` | dev (SDK) | Flutter SDK | 3.44.1 | BSD-3-Clause | On-device Android/iPadOS parity coverage for the real Blockly platform WebView, local asset load, JavaScript bridge, generated Python, and file-backed actions (A-31). Ships with the Flutter SDK and is never part of a release build. |
@@ -70,7 +71,6 @@ directly. Every one is permissive and MIT-compatible (verified against the
7071
| `flutter_driver` | (Flutter SDK) | BSD-3-Clause |
7172
| `flutter_web_plugins` | (Flutter SDK) | BSD-3-Clause |
7273
| `fuchsia_remote_debug_protocol` | (Flutter SDK) | BSD-3-Clause |
73-
| `http` | 1.6.0 | BSD-3-Clause |
7474
| `http_parser` | 4.1.2 | BSD-3-Clause |
7575
| `leak_tracker` | 11.0.2 | BSD-3-Clause |
7676
| `leak_tracker_flutter_testing` | 3.0.10 | BSD-3-Clause |
@@ -151,5 +151,4 @@ rationale when added:
151151
|---|---|---|
152152
| `drift`, `sqlite3` | S5 / A-24 | Local persistence. |
153153
| `fl_chart` | later | Plotting surface. |
154-
| direct `http` / `dio` client | later | Network fetch for the import flow. (`http` is currently transitive through `package_info_plus`, but PyBLE imports no network client for About and performs no metadata network request.) |
155154
| `go_router` | — | Not planned for S1; navigation is index-based via a Riverpod `StateProvider` + `IndexedStack`. |

‎docs/decisions/0012-flutter-code-editor-behind-editorsurface.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR 0012 — Adopt `flutter_code_editor` behind an `EditorSurface` interface (closes App OI-1; bounds R1 instead of clearing it)
22

3-
**Status:** Accepted (2026-07-25). **Closes App [OI-1](../specifications/App/specs.md) — the Flutter Python-editor widget choice.** Does **not** clear [R1](../specifications/App/TDD.md#17-risks--open-questions): R1 is re-scoped from "maturity unproven" to a **measured, bounded residual risk** with explicit fallback triggers. Re-freezes the rich-editor half of FR-EDIT-1/2/3/4 that [ADR-0010](0010-working-loop-in-memory-document.md) deferred. Honors [ADR-0003](0003-license-mit.md) (MIT), [ADR-0007](0007-riverpod-state-management.md) (Riverpod) and [ADR-0008](0008-signal-design-system.md) (Signal tokens). Preserves, without weakening, the hardware-verified typographic-substitution guarantee shipped in `lib/editor/smart_punctuation.dart`.
3+
**Status:** Accepted (2026-07-25). **Closes App [OI-1](../specifications/App/specs.md) — the Flutter Python-editor widget choice.** Does **not** clear [R1](../specifications/App/TDD.md#17-risks--open-questions): R1 is re-scoped from "maturity unproven" to a **measured, bounded residual risk** with explicit fallback triggers. Re-freezes the rich-editor half of FR-EDIT-1/2/3/4 that [ADR-0010](0010-working-loop-in-memory-document.md) deferred. Honors [ADR-0003](0003-license-mit.md) (MIT), [ADR-0007](0007-riverpod-state-management.md) (Riverpod) and [ADR-0008](0008-signal-design-system.md) (Signal tokens). Preserves, without weakening, the hardware-verified typographic-substitution guarantee shipped in `lib/editor/smart_punctuation.dart`. [ADR-0040](0040-sha-pinned-connected-github-import.md) narrowly supersedes this decision's original app-wide `package:http` prohibition only for the bounded public-GitHub adapter under `lib/github_import/`; the editor sandbox and every prohibition on sending editor/user source remain unchanged.
44

55
## Context
66

@@ -43,7 +43,7 @@ The question OI-1 actually poses, then, is not "is this package good?" but **"wh
4343

4444
2. **The smart-punctuation invariant is preserved and re-pinned by test.** Because `CodeField` has no `inputFormatters`, the guard moves to a `CodeController` subclass overriding its `value` setter — the same interception point, one layer lower. The `save()`/`run()` normalizers stay exactly as they are and remain the unconditional guarantee: whatever any widget does, the bytes that reach the board tokenize. A test asserts the invariant **through whichever `EditorSurface` is active**, so it cannot regress silently during or after the swap.
4545

46-
3. **Every optional package surface is off by default.** No `DartPadAnalyzer` (local analyzer only), no error gutter, no package find UI (its strings are unlocalizable English, which would breach FR-I18N), and the `wip/`-quality autocomplete popup is enabled only behind an explicit, tested opt-in. A CI grep gate forbids `DartPadAnalyzer` and `package:http` in `app/lib/`, in the same spirit as the existing no-leak and import-boundary gates — so the dormant network capability stays dormant by construction, not by intention.
46+
3. **Every optional editor-package surface is off by default.** No `DartPadAnalyzer` (local analyzer only), no error gutter, no package find UI (its strings are unlocalizable English, which would breach FR-I18N), and the `wip/`-quality autocomplete popup is enabled only behind an explicit, tested opt-in. The network boundary forbids `DartPadAnalyzer` throughout `app/lib/` and forbids `package:http` outside the exact `lib/github_import/` production composition/client boundary authorized later by [ADR-0040](0040-sha-pinned-connected-github-import.md). In particular, `lib/editor/`, the editor adapter, analyzers, and every code path that can observe editor/user source remain unable to import or call the HTTP client. The GitHub exception sends no editor/user source and is consumed elsewhere through the neutral `GithubApi` seam, so the dormant editor-package network capability stays dormant by construction rather than intention.
4747

4848
4. **The Tab defect is fixed at the adapter, not worked around in docs.** PyBLE installs its own Tab handling above the package's `Shortcuts` so Tab with a multi-line selection indents and never replaces. This is a `[red]`-first item: the failing test comes before the fix, and it pins the exact reproduction (`a = 1\nb = 2\nc = 3\n`, lines 1–2 selected, Tab).
4949

@@ -75,7 +75,7 @@ Unchanged: the `Connection` seam (D1), neutral types (D2), `UI → lib/pble →
7575
**Costs / mitigations**
7676
- **+24 packages**, including a native plugin family and an embedded database we will never use. *Mitigation:* recorded in the ledger; footprint measured before/after and reported, not estimated; optional surfaces off.
7777
- **MPL-2.0 in the closure via `autotrie`, unavoidable.** *Mitigation:* we modify none of it, so no source-disclosure duty attaches to PyBLE's own files; it is disclosed in `THIRD_PARTY_LICENSES` and the notices screen — but it requires the owner ratification named above.
78-
- **Dormant `DartPadAnalyzer` network path.** *Mitigation:* default local analyzer, plus a CI gate forbidding it and `package:http` in `app/lib/`.
78+
- **Dormant `DartPadAnalyzer` network path.** *Mitigation:* default local analyzer, plus a boundary that forbids `DartPadAnalyzer` everywhere and permits `package:http` only inside ADR-0040's exact bounded `lib/github_import/` production adapter. No editor or analyzer receives that exception.
7979
- **Superlinear typing cost with no soft wrap.** *Mitigation:* fallback trigger (b) makes this a measured, actionable condition on real hardware rather than a vague worry.
8080
- **Dormant upstream.** *Mitigation:* exact version pin, adapter-level fixes, retained second implementation, fallback trigger (c).
8181
- **Golden churn.** The editor surface changes appearance, so the shell goldens must be regenerated deliberately and reviewed as an intended visual change.
@@ -90,4 +90,5 @@ Unchanged: the `Connection` seam (D1), neutral types (D2), `UI → lib/pble →
9090
- Closes App **OI-1**; re-scopes **R1** ([TDD.md §17](../specifications/App/TDD.md#17-risks--open-questions)).
9191
- Supersedes the rich-editor deferral in [ADR-0010](0010-working-loop-in-memory-document.md); leaves ADR-0010's volatile-document decision and its FR-EDIT-7 deviation untouched.
9292
- Honors [ADR-0003](0003-license-mit.md) (MIT — see the MPL-2.0 carve-out), [ADR-0007](0007-riverpod-state-management.md), [ADR-0008](0008-signal-design-system.md).
93+
- Narrowly superseded for one network boundary by [ADR-0040](0040-sha-pinned-connected-github-import.md); its public GitHub client does not weaken this ADR's editor isolation or source-exfiltration prohibition.
9394
- Preserves the A-25 typographic-substitution guarantee (`app/lib/editor/smart_punctuation.dart`), which was established from a hardware-verified failure and is re-pinned by test as part of this work.

0 commit comments

Comments
 (0)