Repository navigation
docs(gh): canonical SAM-BIM Grasshopper component engineering standard - #204
Merged
Merged
Conversation
Add `docs/GH_COMPONENT_STANDARDS.md` as the single SAM-BIM standard for Grasshopper component naming, descriptions, Diagnostics, versioning and published-parameter migration. Every rule carries a status (validated, enforced, proposed, open, frozen legacy) so a proposal is never mistaken for a validated fact. Add `design/grasshopper-icons/tools/param_contract.py` as the canonical shared metadata validator, with `--repo`/`--output` so one copy serves every SAM-BIM repository instead of one copy each. It is the validated pilot validator with the scanner inlined (the repository-local `inventory.py` copies have diverged) and a parameter-class discriminator so it is usable on a repository the size of SAM. Require reading the standard in `AGENTS.md` before changing any Grasshopper component. Documentation, tooling and agent instructions only: no component, GUID, parameter, default, geometry or updater behaviour is modified.
Resolve the four Major and three Minor findings from the review of the canonical standard in #204. The governing change is fail-closed extraction: a component whose published contract was not completely read is reported `partial`/`unresolved` and blocks a compatibility PASS, instead of being silently reported as verified. Extraction (Major): a statement-level walker replaces the single-call-site regex. Now supported and regression-tested: target-typed `new()`, variable reuse and reassignment, object initializers without constructor parentheses, declarations without an initializer, collection expressions and AddRange, verbatim identifiers, declarations inside foreach/if blocks, expression-bodied properties, local parameter factories, parameter-manager registration with typed helpers, attributed `Optional`, inherited registration from an abstract base, generic base type-argument substitution, and compile-removed files. The reported CreatePanelsBySolids case now extracts all 7 inputs and 4 outputs (it previously produced 7 unnamed inputs and no outputs). Type (Major): the runtime parameter type is part of the frozen contract and is compared exactly; custom and third-party types are recorded as `goo`/`external` and reported, and a type that cannot be identified blocks the check. Discovery (Major): classification is by source ancestry, not by name, so a component called NewComputeParam is a component and Goo*Param is a parameter. Ancestry resolves across the repository, unknown ancestry is reported rather than silently excluded, project discovery follows indirect project references and parses csproj with ElementTree (either quoting style), and an unparsable project is reported. Compatibility vs conventions (Major): compatibility compares published metadata against the approved baseline only; naming conventions are a separate finding with an approved-exception list; legitimate List/Tree access and existing nicknames are valid; a code-side default does not require SetPersistentData. Minor: a version-only change is a manifest refresh, not a compatibility violation; SAM's AGENTS.md no longer asks for a baseline-dependent check it cannot satisfy; and the standard no longer labels grammar, SI units or engineering semantics as automatically enforced. Adds design/grasshopper-icons/tools/tests/test_param_contract.py (42 stdlib tests). No component, GUID, parameter, default, updater algorithm or unrelated repository is modified.
michaldengusiak
marked this pull request as ready for review
October 15, 2026 19:26
michaldengusiak
added a commit
that referenced
this pull request
Oct 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem and resulting behavior
The metadata validator previously printed
OK compatibilityfor incomplete contracts, including a real Revit component with four inputs and one output recorded as empty. This revision narrows certification to supported source declarations and refuses uncertain extraction/discovery instead of maximizing the verified count.Tested repair content:
692f35f642db4838c29cda8e820101e2fc90401c.Final PR head:
4a8afbebb186ace81eb5d49aed32deb502120781(record-only docs commit).Base:
sow/2026-Q4at6b12e2a65817556693ba408674211610f4a20dda.Status: merged as
a99083a73b107609d1fbc3b4a39266a9a05686f9after owner-authorized final acceptance; post-merge validation and closeout complete.Scope and corrections
ParamDefinition[]is explicitly unresolved.Four files changed in this repair: shared validator, its tests, canonical standard and PR record. No production component, GUID, parameter, updater/migration infrastructure, workflow, other repository source or PROJECT_PROGRESS change.
Validation
Local Windows / RhinoCode Python 3.13.13 (
-B; TEMP/TMP set to a writable directory):python -B design/grasshopper-icons/tools/tests/test_param_contract.pypython -B design/grasshopper-icons/tools/param_contract.py --repo ../SAM_Psychrometrics --checkgit diff --checkFinal-head hosted checks, all
workflow_dispatchat exact head4a8afbebb186ace81eb5d49aed32deb502120781:These workflows build/test C# and check headers; none executes the Python validator or Rhino migration acceptance. The Python evidence above is local. Historical green runs at c2067f9 are not evidence for this repair.
Corrected coverage and architectural limit
Across the 22 named checkouts in Appendix 2: 826 discovered / 73 verified / 709 partial / 44 unresolved, with 0 unclassified objects / 0 unparseable projects. SAM: 460 / 37 / 423 / 0. Revit: 55 / 9 / 13 / 33. Psychrometrics: 3 / 3 / 0 / 0. Full table and reasons are documented.
The earlier 823/817 claim omitted the pilot's three components; the previous table actually summed to 826/820. That verified label was unsound. The six original partials remain gaps and are a subset of the corrected limitations. CreatePanelsBySolids still extracts 7 inputs/4 outputs, but is partial because custom Goo constructor effects are unproven.
Chosen approach: a strict bounded Python source subset. Roslyn semantic/MSBuild analysis and host-based runtime metadata inspection are separately reviewed follow-ups. Factories, symbolic defaults, nontrivial Goo/third-party constructors, external registration and unsupported returned expressions block certification. No general C# completeness claim; no migration redesign or fleet CI redesign.
Final acceptance and integration — 2026-10-15
Fresh acceptance at exact approved head
4a8afbebb186ace81eb5d49aed32deb502120781: 69 regression tests pass, no skips; 20 independent cases match expected exits, zero unexpected acceptances. Qualified/generic identity, uncertain extraction, unknown ancestry, discovery errors and incomplete baselines behave as required. Psychrometrics approved baseline passes 3 verified/3 compared. Fresh SAM inventory: 460 discovered / 37 verified / 423 partial / 0 unresolved, 0 unclassified / 0 unparseable projects; inventory only, no SAM baseline or compatibility PASS claimed.Final-head Build/Test/SPDX dispatches above are verified successful at the exact SHA; Test log reports 3683/3683 passing. No PR comments, reviews or review threads; Q4 is unprotected with no required reviews. The five-file total PR diff contains only AGENTS guidance, canonical standard, shared validator, regression tests and record. No production component/workflow/Auto-fix changes. Tested repair content differs from final head only in the PR record.
The earlier BuildAll blocker was separately proven to originate in SAM#201 and corrected by merged SAM_Multitasker#12, merge
e58b00ba999a993fe86ebeadd7a30b40100dc9e8. It does not implicate #204. Latest fullBuildAlls_v5.bat nopausePASS, exit 0,00:07:41.6286121, 2026-10-15 21:07:51–21:15:36 Europe/Warsaw: all 26 active repositories, Revit 2025/2026/2027, final OCCT checks. This build used SAM at the exact #204 head plus Multitasker's validated alias-fix contentcfe9d116c1d9837e23ada308d535029eaf6de773, unchanged by its merge. Verified raw-log SHA256 matches the committed Multitasker evidence:889e6260a8b59bef0d24bc8506b8734beb06eab1e745fe601335d259ace536bc. No new build failures. No unrelated repository source changed during final acceptance.Remaining limits: bounded Python source subset; 709 partial / 44 unresolved fleet components remain intentionally uncertified, only Psychrometrics has an approved baseline, schema-2 manifests need reviewed refresh, and unsupported constructors/factories/control flow/Revit declarations require separate semantic/runtime work. No new canvas or saved-definition runtime acceptance is claimed.
Machine-local fresh logs and independent harness/results:
C:/Users/michal/.codex/visualizations/2026/10/15/01a140c3-07d7-7db2-83db-a3f98397ac92/pr204-final-acceptance. Critical cases are also in the committed regression suite. Original PR record is historical pre-acceptance evidence; the post-merge PROJECT_PROGRESS closeout at6167d474703d79f38795b1cc26430a7f4a1e8bbarecords final CI and merge SHA.Completed: merge-commit pinned to approved head; post-merge Build 38793868502, Test 38793868569 (3683 passed), and SPDX 38793919140 all SUCCESS at merge SHA. Policy-compliant docs-only Q4 closeout
6167d474703d79f38795b1cc26430a7f4a1e8bbapushed with [skip ci]. Fully merged feature branch deleted remotely with an expected-SHA lease and locally without force after no-open-PR/no-worktree/protection checks. Clean checkout on sow/2026-Q4. No additional rollout or Diagnostics implementation started; this task is complete.Record:
documentation/GH-Component-Standards-Q4.md.