@rettangoli/check 0.0.1

package/README.md

@@ -0,0 +1,295 @@
+# Rettangoli Check (Brainstorm)
+
+> Working name: `rettangoli-check` (possible package: `@rettangoli/check`)
+
+This package is intended to be a dedicated static analyzer for Rettangoli projects.
+It should validate that component contracts are respected across files before runtime/build errors happen.
+
+Execution plan: see `packages/rettangoli-check/ROADMAP.md`.
+Loop retrospective: see `packages/rettangoli-check/LOOP_LEARNINGS.md`.
+
+## Current Implementation Status
+
+Implemented now:
+
+- package + CLI entrypoint (`@rettangoli/check`, `rtgl check`)
+- discovery and component grouping
+- model building for YAML/JS contracts
+- FE parity checks (schema required, forbidden view keys, legacy `.prop=` binding)
+- schema/constants checks
+- listener config checks
+- strict handler naming checks (`handle*` only)
+- cross-file symbol checks (handler/action/method existence)
+- YAHTML attr/prop validation for template selector bindings
+- semantic scope graph (YAHTML + Jempl + FE binding context)
+- schema-aware expression checks (unresolved roots, invalid schema paths, boolean type mismatch)
+- lifecycle signature checks (`handleBeforeMount`, `handleOnUpdate`)
+- inter-component compatibility checks (required props, events, boolean prop binding type)
+- UI primitive/component registry generation from `rettangoli-ui`
+- reporters: `text`, `json`, `sarif`
+- watch mode with incremental component model cache
+- robustness harnesses: export differential + template pipeline fuzzing
+- CI integration in `.github/workflows/ci-ui.yaml` via `bun run check:contracts`
+
+Template parser architecture:
+- `docs/template-analysis.md` (YAML -> Jempl -> YAHTML pipeline)
+
+Checklist progress is tracked with `[x]/[ ]` in `packages/rettangoli-check/ROADMAP.md`.
+
+## CLI Usage
+
+```bash
+# default (uses rettangoli.config.yaml fe.dirs when available)
+rtgl check
+
+# explicit directory
+rtgl check --dir src/components
+
+# JSON output
+rtgl check --dir src/components --format json
+
+# SARIF output
+rtgl check --dir src/components --format sarif
+
+# enable expression scope/type checks
+rtgl check --dir src/components --expr
+
+# watch mode (incremental)
+rtgl check --watch --watch-interval-ms 500
+
+# treat warnings as errors
+rtgl check --warn-as-error
+
+# run without YAHTML attr checks (contract-only mode)
+rtgl check --dir src/components --no-yahtml
+
+# preview safe autofixes
+rtgl check --dir src/components --autofix-dry-run --format json
+
+# preview safe autofixes with patch output
+rtgl check --dir src/components --autofix-dry-run --autofix-patch --format json
+
+# apply safe autofixes
+rtgl check --dir src/components --autofix --autofix-min-confidence 0.95
+```
+
+`rtgl-check` command surface:
+
+```bash
+# check contracts
+rtgl-check --dir src/components --format json
+```
+
+CLI contract references:
+
+- `packages/rettangoli-check/docs/cli-contract.md`
+- `packages/rettangoli-check/docs/semantic-compatibility-guarantees.md`
+- `packages/rettangoli-check/docs/diagnostics-reporting-contract.md`
+- `packages/rettangoli-check/docs/diagnostics-reference.md`
+- `packages/rettangoli-check/docs/diagnostics-sarif-contract.md`
+- `packages/rettangoli-check/docs/security-parser-attack-surface.md`
+
+## JS Export Parser Backend
+
+`rettangoli-check` now uses Oxc as the single runtime JS export extractor.
+
+Legacy regex extraction is retained only in test parity harnesses:
+
+```bash
+bun run --cwd packages/rettangoli-check test:diff-js-exports
+```
+
+## Known Strict Findings (Current UI Baseline)
+
+Current baseline is clean in strict mode:
+
+- `packages/rettangoli-ui` contract checks pass with YAHTML enabled
+- CI runs strict contract checks (no `--no-yahtml` bypass)
+
+## Why this package
+
+`@rettangoli/fe` already has a contract checker (`rtgl fe check`), but today it focuses on a small set of structural rules:
+
+- required `.schema.yaml` per component
+- forbidden metadata keys inside `.view.yaml`
+- legacy `.prop=` syntax detection
+
+That baseline is good, but many contract violations are still caught late (during build, runtime, or manually).
+
+## What we learned from current codebase
+
+### FE contract sources
+
+Canonical docs are in `packages/rettangoli-fe/docs/`:
+
+- `overview.md`
+- `view.md`
+- `schema.md`
+- `store.md`
+- `handlers.md`
+- `methods.md`
+- `constants.md`
+
+### Existing FE check implementation
+
+Main check path today:
+
+- `packages/rettangoli-fe/src/cli/check.js`
+- `packages/rettangoli-fe/src/cli/contracts.js`
+- `packages/rettangoli-fe/src/core/contracts/componentFiles.js`
+
+### Runtime/build validations that are currently not fully static
+
+Important checks currently happen at build/runtime, not as deep static analysis:
+
+- schema contract and methods mapping:
+  `packages/rettangoli-fe/src/core/schema/validateSchemaContract.js`
+- listener config validation (handler/action exclusivity, modifiers, debounce/throttle):
+  `packages/rettangoli-fe/src/core/view/refs.js`
+- action dispatch to store action name validation:
+  `packages/rettangoli-fe/src/core/runtime/lifecycle.js`
+- build-time parse/compose of component files:
+  `packages/rettangoli-fe/src/cli/build.js`
+
+### UI package shape
+
+`packages/rettangoli-ui/src/components/*` consistently uses the FE multi-file model (`.view.yaml`, `.schema.yaml`, optional `.handlers.js`/`.store.js`/`.methods.js`).
+That makes it a strong first target for static checks.
+
+## Proposed goals for `rettangoli-check`
+
+1. Catch contract violations earlier than runtime.
+2. Give precise file-level diagnostics (and line-level when possible).
+3. Separate rule engine from FE runtime, so checkers can run in CI/editor/pre-commit.
+4. Support both human and machine output (`text`, `json`, later `sarif`).
+
+## Rule ideas
+
+### V1 (high value, low ambiguity)
+
+1. File-set rules
+- `.schema.yaml` required per component
+- no unsupported FE file suffixes in component folders (optional strict mode)
+
+2. Schema rules
+- `componentName` required, non-empty, valid custom element format
+- reject `attrsSchema`
+- `methods` must be object schema with `properties`
+
+3. Cross-file symbol rules
+- `schema.methods.properties.*` must exist in `.methods.js` exports
+- exported methods in `.methods.js` should be documented in `schema.methods` (warn-level first)
+- `refs.*.eventListeners.*.handler` must exist in `.handlers.js`
+- `refs.*.eventListeners.*.action` must exist in `.store.js`
+
+4. Listener config static validation
+- exactly one of `handler` or `action`
+- `debounce` and `throttle` are mutually exclusive
+- modifier types (`boolean`, non-negative number)
+
+5. Component identity rules
+- detect duplicate `componentName` across project
+- optional: enforce expected mapping between folder/file base name and schema component name
+
+6. Constants rules
+- `.constants.yaml` root must be an object
+
+### V2 (medium complexity)
+
+1. Refs and ID contracts
+- if ID refs are used, matched element IDs should satisfy camelCase constraints used by runtime
+
+2. Store/handlers shape checks
+- `handleBeforeMount` should not be async (or return Promise)
+- basic export-order/lint checks for `.store.js` (if still desired as strict rule)
+
+3. API consistency checks for UI libraries
+- event naming conventions (`kebab-case`, suffix consistency)
+- payload contract hints from schema vs emitted event docs (warn-level)
+
+### V3 (advanced / optional)
+
+1. Template expression linting and unresolved symbol checks.
+2. Inter-component prop compatibility checks (requires component registry graph).
+3. Autofix mode for mechanical issues.
+
+## Architecture proposal
+
+## 1. Core flow
+
+1. Discover component files from configured dirs.
+2. Parse YAML files (`js-yaml`) and JS files (AST-based, likely `@babel/parser`).
+3. Build a component model:
+- metadata (`category`, `component`, paths)
+- schema model
+- view refs/listeners model
+- JS export indexes for store/handlers/methods
+4. Run rule engine over model.
+5. Format diagnostics.
+
+## 2. Module boundaries
+
+- `src/discovery/` file walking and grouping
+- `src/parsers/` yaml/js/template helpers
+- `src/model/` normalized IR for rules
+- `src/rules/` one file per rule with code + tests
+- `src/reporters/` text/json/sarif formatters
+- `src/cli/` command wiring
+
+## 3. Integration points
+
+Short-term:
+
+- keep `rtgl fe check` as-is
+- add optional command path that can call new checker
+
+Long-term:
+
+- make `rtgl fe check` delegate to `@rettangoli/check` for FE rules
+- allow package-specific presets (`fe`, `ui`, custom)
+
+## Suggested CLI surface (draft)
+
+```bash
+# full project scan from rettangoli.config.yaml
+rtgl check
+
+# explicit directories
+rtgl check --dirs src/components --dirs src/pages
+
+# output modes
+rtgl check --format text
+rtgl check --format json
+rtgl check --format sarif
+
+# rule controls
+rtgl check --preset fe
+rtgl check --preset ui
+rtgl check --warn-as-error
+```
+
+## Minimal milestone plan
+
+1. Bootstrap package with CLI + discovery + current FE parity rules.
+2. Add cross-file symbol rules (handler/action/method existence).
+3. Add duplicate component name and method-doc coverage diagnostics.
+4. Wire into CI in `rettangoli-ui` and one example app.
+
+## Open design questions
+
+1. Naming: `rettangoli-check` vs `rettangoli-contracts` vs `rettangoli-lint`.
+2. Should `rtgl fe check` remain FE-specific wrapper, or fully replaced by generic `rtgl check`?
+3. Error code strategy:
+- keep existing `RTGL-CONTRACT-xxx`
+- or introduce package-specific namespaces (example: `RTGL-CHECK-FE-xxx`)
+4. Strictness defaults:
+- what is error vs warning in CI by default?
+
+## Immediate next step (implementation)
+
+Create `@rettangoli/check` with:
+
+- package scaffolding
+- parser/model foundation
+- parity checks from existing `@rettangoli/fe` check
+- at least one new high-value cross-file rule (`action` -> `.store.js` export exists)

package/ROADMAP.md

@@ -0,0 +1,175 @@
+# Rettangoli Check Roadmap
+
+This roadmap is intentionally incremental. Each step should be shippable on its own.
+
+## Steps
+
+- [x] 1. Lock baseline and test fixtures.
+Deliverable: maintain scenario-based fixtures under `test/scenarios/` as the baseline contract.
+
+- [x] 2. Scaffold package runtime.
+Deliverable: add `package.json`, `src/index.js`, `src/cli/index.js`, and a runnable `node` CLI entry.
+
+- [x] 3. Implement project discovery.
+Deliverable: collect FE component groups from configured dirs (`.view.yaml`, `.schema.yaml`, `.store.js`, `.handlers.js`, `.methods.js`, `.constants.yaml`).
+
+- [x] 4. Add normalized component model (IR).
+Deliverable: parsed YAML/JS contracts in one in-memory model used by all rules.
+
+- [x] 5. Port existing FE contract rules (parity mode).
+Deliverable: equivalent behavior to current `rtgl fe check` for schema-required and forbidden view keys.
+
+- [x] 6. Implement YAHTML selector/binding parser pass.
+Deliverable: parse selector, attrs, `:prop`, `?bool`, control-flow lines, with stable diagnostics.
+
+- [x] 7. Implement attr allowlist validation by tag.
+Deliverable: unknown attr failure per tag (`rtgl-button banana=ripe` style errors), with file:line output.
+
+- [x] 8. Build canonical UI contract registry.
+Deliverable: registry generated from `rettangoli-ui` + FE schema contracts (tag, attrs/props, events, methods).
+
+- [x] 9. Add cross-file symbol rules.
+Deliverable: verify `refs.*.handler` in `.handlers.js`, `refs.*.action` in `.store.js`, and `schema.methods` vs `.methods.js` exports.
+
+- [x] 10. Add schema and identity hard checks.
+Deliverable: `componentName` format checks, duplicate `componentName` detection, constants root-object validation.
+
+- [x] 11. Add reporting modes and severity controls.
+Deliverable: `text` and `json` reporters, error/warn levels, non-zero exit on errors, optional `--warn-as-error`.
+
+- [x] 12. Integrate with CLI and CI.
+Deliverable: `rtgl check` command, optional `rtgl fe check` delegation path, CI job for `rettangoli-ui`.
+
+- [x] 13. Enforce strict handler naming contract.
+Deliverable: listener `handler` values and `.handlers.js` exports must start with `handle`.
+
+## Exit Criteria for First Release
+
+1. Detects invalid attrs/props in YAHTML views against registry.
+2. Detects missing handler/action/method symbols across files.
+3. Maintains compatibility with current FE contract checks.
+4. Provides stable error codes and machine-readable JSON output.
+
+## Next Phase: Oxc Parser Migration
+
+- [x] A. Add `oxc-parser` as JS parsing backend.
+Deliverable: parser abstraction in `src/core/parsers.js` with Oxc-based extraction.
+
+- [x] B. Implement AST-based export extraction with Oxc.
+Deliverable: robust handling for named exports, aliases, multi-declarator exports, and default-export detection.
+
+- [x] C. Run dual-mode parity checks (`legacy-regex` vs `oxc`) in scenario tests.
+Deliverable: no behavior regressions on existing scenarios; mismatches reported as test failures.
+
+- [x] D. Expand scenario coverage for JS export edge cases before cutover.
+Deliverable: dedicated scenarios for complex export syntaxes and commented/dead code cases.
+
+- [x] E. Switch default extractor to Oxc after parity is proven.
+Deliverable: `oxc` default enabled.
+
+- [x] F. Remove legacy regex extractor once stable.
+Deliverable: single AST-based runtime path with Oxc; legacy regex kept only in test parity harness.
+
+## Mid-Term Priorities (Compiler-Grade)
+
+These are the next large workstreams to move from rule-checker quality to compiler-grade static analysis.
+
+- [ ] 1. Build a typed YAHTML AST + parser pipeline.
+Deliverable: replace line-heuristic parsing with an explicit YAHTML AST, node kinds, and stable source ranges (line+column+offset).
+
+- [x] 2. Build semantic analysis passes (symbol table + scope graph).
+Deliverable: resolve refs, handlers, actions, methods, constants, and template expression symbols across component files.
+
+- [x] 3. Add static lifecycle and handler contract validation.
+Deliverable: enforce lifecycle semantics (`handleBeforeMount` sync-only, known lifecycle names), handler signatures, and payload shape checks.
+
+- [x] 4. Add schema-aware expression/type checking.
+Deliverable: validate `${...}` and listener payload expressions against schema props/method signatures/constants with precise diagnostics.
+
+- [x] 5. Add inter-component contract compatibility checks.
+Deliverable: validate parent-to-child prop/event/method compatibility using a project component graph and merged registry.
+
+- [ ] 6. Add diagnostic quality upgrades.
+Deliverable: attach rule category + machine-safe metadata to every diagnostic and provide consistent codeframes/ranges.
+
+- [x] 7. Add compiler-grade reporter outputs.
+Deliverable: add SARIF output and keep deterministic JSON contracts for CI, code scanning, and editor integrations.
+
+- [x] 8. Add incremental engine + watch mode.
+Deliverable: file graph cache, invalidation model, and fast incremental re-checks for local development.
+
+- [x] 9. Add robustness testing strategy (fuzz + differential).
+Deliverable: fuzz YAHTML/JS inputs and differential tests against FE runtime/build outcomes to detect semantic drift.
+
+- [x] 10. Tighten CI enforcement to strict mode.
+Deliverable: remove temporary `--no-yahtml` path once baseline issues are fixed and enforce strict contracts in all main pipelines.
+
+## Next Execution Order (Recommended)
+
+- [x] A. Implement Oxc parity harness in scenario runner (dual-backend assertion).
+- [x] B. Add 15-20 export-edge scenarios (re-exports, type-only exports, default forms, parse-failure fallback).
+- [x] C. Start YAHTML AST foundation (parser + node model + source ranges).
+- [x] D. Add lifecycle/handler semantic rules on top of the new AST/IR.
+
+## Compiler-Grade Program Roadmap (Phased)
+
+Goal: move from "strong rule checker" to "deterministic compiler-grade analyzer" with precise source mapping, semantic passes, and CI-grade outputs.
+
+### Phase 1: Stabilize strict baseline (high value, low risk)
+
+- [x] P1.1 Remove temporary `--no-yahtml` CI bypass after fixing current strict UI findings.
+Deliverable: strict YAHTML attr/prop checks are always enforced in CI for UI packages.
+
+- [x] P1.2 Complete Oxc migration hardening.
+Deliverable: parity harness (`legacy-regex` vs `oxc`) + export edge-case scenarios + legacy regex runtime path removed.
+
+- [x] P1.3 Add deterministic diagnostics contract tests.
+Deliverable: snapshot-style checks for code/severity/message/file/line stability.
+
+### Phase 2: Parser and semantic foundation (compiler core)
+
+- [x] P2.1 Introduce typed YAHTML AST with source ranges.
+Deliverable: node kinds + stable `line:column:offset` for selector/attr/binding nodes.
+
+- [x] P2.2 Build semantic IR and scope graph across FE + Jempl + template scopes.
+Deliverable: resolvable symbols for refs, handlers, actions, methods, constants, loop variables, and branch scopes.
+
+- [x] P2.3 Add expression analyzer for `${...}` and listener payload expressions.
+Deliverable: unresolved-symbol and invalid-path diagnostics with precise ranges.
+
+### Phase 3: Type and contract reasoning
+
+- [x] P3.1 Schema-aware expression/type checking.
+Deliverable: expression values validated against schema props/method contracts and constants shapes.
+
+- [x] P3.2 Lifecycle and handler semantic checks.
+Deliverable: enforce lifecycle semantics (sync/async constraints, naming contracts, payload shape expectations).
+
+- [x] P3.3 Inter-component compatibility graph checks.
+Deliverable: parent->child prop/event/method compatibility validation using project registry graph.
+
+### Phase 4: Compiler UX and scale
+
+- [x] P4.1 Compiler-grade reporter outputs.
+Deliverable: SARIF + deterministic JSON contracts + improved text codeframes.
+
+- [x] P4.2 Incremental engine and watch mode.
+Deliverable: dependency graph cache + invalidation strategy for fast local re-checks.
+
+- [x] P4.3 Robustness program (fuzz + differential testing).
+Deliverable: fuzz YAHTML/Jempl inputs and compare checker findings against FE runtime/build outcomes.
+
+## Planned 10-Iteration Loop Track (Immediate)
+
+This track is designed for the next Codex loop run (`gpt-5.3-codex`, high reasoning effort).
+
+- [x] I01. Add Oxc parity harness in scenario runner and baseline it on current scenarios.
+- [x] I02. Add first export-edge scenario pack (re-export, alias, default forms).
+- [x] I03. Add second export-edge scenario pack (commented/dead code/type-only-like patterns).
+- [x] I04. Remove one regex-only branch proven redundant by parity + tests.
+- [x] I05. Add YAHTML AST node model draft and fixture tests (no rule migration yet).
+- [x] I06. Add source-range plumbing (`line:column`) for selector/binding diagnostics.
+- [x] I07. Add semantic symbol table pass for handlers/actions/methods/constants.
+- [x] I08. Add first unresolved-symbol rule for template expressions.
+- [x] I09. Add deterministic diagnostics contract/snapshot tests.
+- [x] I10. Add SARIF reporter foundation with one scenario-backed contract.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rettangoli/check",
+  "version": "0.0.1",
+  "description": "Static contract checker for Rettangoli projects",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./cli": "./src/cli/index.js"
+  },
+  "bin": {
+    "rtgl-check": "./src/cli/bin.js"
+  },
+  "scripts": {
+    "test:scenarios": "node ./test/run-scenarios.js",
+    "test:diff-js-exports": "node ./scripts/differential-js-exports.js",
+    "test:fuzz-template-pipeline": "node ./scripts/fuzz-template-pipeline.js",
+    "test:fuzz-jempl-parser": "node ./scripts/fuzz-jempl-parser.js",
+    "test:jempl-parser-contract": "node ./scripts/test-jempl-parser-contract.js",
+    "test:scope-graph-range-contract": "node ./scripts/test-scope-graph-range-contract.js",
+    "test:fe-frontend-component-identity-contract": "node ./scripts/test-fe-frontend-component-identity-contract.js",
+    "test:fe-frontend-handler-contract": "node ./scripts/test-fe-frontend-handler-contract.js",
+    "test:fe-frontend-lifecycle-contract": "node ./scripts/test-fe-frontend-lifecycle-contract.js",
+    "test:fe-frontend-oxc-contract": "node ./scripts/test-fe-frontend-oxc-contract.js",
+    "test:fe-frontend-schema-normalization-contract": "node ./scripts/test-fe-frontend-schema-normalization-contract.js",
+    "test:semantic-engine-contract": "node ./scripts/test-semantic-engine-contract.js",
+    "test:type-system-contract": "node ./scripts/test-type-system-contract.js",
+    "test:yahtml-parser-snapshots": "node ./scripts/test-yahtml-parser-snapshots.js",
+    "test:yahtml-parser-crash": "node ./scripts/test-yahtml-parser-crash-containment.js",
+    "test:fuzz-yahtml-parser": "node ./scripts/fuzz-yahtml-parser.js",
+    "test:fuzz-fe-contract-combinations": "node ./scripts/fuzz-fe-contract-combinations.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "ROADMAP.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@rettangoli/fe": "workspace:1.0.0-rc3",
+    "jempl": "0.3.2-rc2",
+    "js-yaml": "^4.1.0",
+    "oxc-parser": "^0.112.0",
+    "yahtml": "0.0.5"
+  }
+}