📚 docs: Record field declaration design discussion in papers

## Summary
Documented the "init block vs fields-at-top" design discussion as a valuable example of AI-human collaboration in language design.

## Changes

### Paper G (AI Collaboration)
- Added field-declaration-design.md documenting the entire discussion flow
- Showcased how complex init block proposal evolved to simple "fields at top" rule
- Demonstrates AI's tendency toward complexity vs human intuition for simplicity

### Paper H (AI Practical Patterns)
- Added Pattern #17: "Gradual Refinement Pattern" (段階的洗練型)
- Documents the process: Complex AI proposal → Detailed analysis → Human insight → Convergence
- Field declaration design as a typical example

### Paper K (Explosive Incidents)
- Added Incident #046: "init block vs fields-at-top incident"
- Updated total count to 46 incidents
- Shows how a single human comment redirected entire design approach

## Design Decision
After analysis, decided that BoxIndex should remain a compiler-internal structure, not a core Box:
- Core Boxes: User-instantiable runtime values (String, Integer, Array, Map)
- Compiler internals: BoxIndex for name resolution (compile-time only)
- Clear separation of concerns between language features and compiler tools

## Philosophy
This discussion exemplifies key principles:
- The best design needs no explanation
- Constraints provide clarity, not limitation
- "Everything is Box" doesn't mean "compiler internals are Boxes"
- AI tends toward theoretical completeness; humans toward practical simplicity

🐱 Sometimes the simplest answer is right in front of us\!
This commit is contained in:
Selfhosting Dev
2025-09-16 14:57:05 +09:00
parent 6ca56b0652
commit 47f4ca0e44
14 changed files with 804 additions and 96 deletions

View File

@ -17,8 +17,8 @@ Policy
3) Plugins (short name if unique, otherwise qualified `pluginName.BoxName`)
- On ambiguity: error with candidates and remediation (qualify or define alias).
- Modes:
- Relaxed (default): short names allowed when unique.
- Strict: require plugin prefix (env `NYASH_PLUGIN_REQUIRE_PREFIX=1` or nyash.toml `[plugins] require_prefix=true`).
- Relaxed (default): short names allowed when unique
- Strict: plugin短名にprefix必須(env `NYASH_PLUGIN_REQUIRE_PREFIX=1` または nyash.toml `[plugins] require_prefix=true`)。
- Aliases:
- nyash.toml `[imports] HttpClient = "network.HttpClient"`
- needs sugar: `needs plugin.network.HttpClient as HttpClient` (filescoped alias)
@ -27,6 +27,7 @@ Policy
- Unified namespace with Boxes. Prefer short names when unique.
- Qualified form: `network.HttpClient`
- Perplugin control (nyash.toml): `prefix`, `require_prefix`, `expose_short_names`
- 現状は設定の読み取りのみ(導線)。挙動への反映は段階的に実施予定。
## `needs` sugar (optional)
- Treated as a synonym to `using` on the Runner side; registers aliases only.
@ -37,21 +38,11 @@ Policy
- `[plugins.<name>]`: `path`, `prefix`, `require_prefix`, `expose_short_names`
## Index and Cache (Runner)
- Build a Box index once per run to make resolution fast and predictable:
```
struct BoxIndex {
local_boxes: HashMap<String, PathBuf>,
plugin_boxes: HashMap<String, Vec<PluginBox>>,
aliases: HashMap<String, String>,
}
```
- Maintain a small resolve cache per thread:
```
thread_local! {
static RESOLVE_CACHE: RefCell<HashMap<String, ResolvedBox>> = /* ... */;
}
```
- Trace: `NYASH_RESOLVE_TRACE=1` prints resolution steps (for debugging/CI logs).
- BoxIndexグローバルプラグインBox一覧とaliasesを集約し、Runner起動時plugins init後に構築・更新。
- `aliases: HashMap<String,String>`nyash.toml `[aliases]` と env `NYASH_ALIASES`
- `plugin_boxes: HashSet<String>`(読み取り専用)
- 解決キャッシュ:グローバルの小さなキャッシュで同一キーの再解決を回避(キー: `tgt|base|strict|paths`)。
- トレース:`NYASH_RESOLVE_TRACE=1` で解決手順やキャッシュヒット、未解決候補を出力。
Syntax
- Namespace: `using core.std` or `using core.std as Std`
@ -102,9 +93,14 @@ static box Main {
Runner Configuration
- Enable using preprocessing: `NYASH_ENABLE_USING=1`
- CLI from-the-top registration: `--using "ns as Alias"` or `--using '"apps/foo.nyash" as Foo'` (repeatable)
- Strict mode (plugin prefix required): `NYASH_PLUGIN_REQUIRE_PREFIX=1` または `nyash.toml``[plugins] require_prefix=true`
- Aliases from env: `NYASH_ALIASES="Foo=apps/foo/main.nyash,Bar=lib/bar.nyash"`
- Additional search paths: `NYASH_USING_PATH="apps:lib:."`
- Selfhost pipeline keeps child stdout quiet and extracts JSON only: `NYASH_JSON_ONLY=1` (set by Runner automatically for child)
- Selfhost emits `meta.usings` automatically when present; no additional flags required.
Notes
- Phase 15 keeps resolution in the Runner to minimize parser complexity. Future phases may leverage `meta.usings` for compiler decisions.
- Unknown fields in the toplevel JSON (like `meta`) are ignored by the current bridge.
- 未解決時非strictは実行を継続し、`NYASH_RESOLVE_TRACE=1` で候補を提示。strict時はエラーで候補を表示。