expressir 2.4.41-x86_64-linux → 2.4.42-x86_64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/performance-release.yml +124 -0
  3. data/TODO.compat/00-overview.md +35 -0
  4. data/TODO.compat/01-interchange-cli.md +34 -0
  5. data/TODO.compat/02-compat-guide.md +21 -0
  6. data/TODO.compat/03-scoreboard.md +24 -0
  7. data/TODO.compat/04-unified-receipt.md +26 -0
  8. data/TODO.compat/05-p28-configured.md +26 -0
  9. data/TODO.compat/06-change-classification.md +26 -0
  10. data/TODO.compat/07-evaluator-matrix.md +22 -0
  11. data/TODO.compat/08-wasm.md +24 -0
  12. data/docs/_guides/compat/eval-builtin-matrix.adoc +42 -0
  13. data/docs/_guides/compat/index.adoc +16 -0
  14. data/docs/_guides/compat/interchange.adoc +79 -0
  15. data/docs/_guides/compat/toolchain.adoc +57 -0
  16. data/docs/_guides/reference/grammar-crosswalk.adoc +1 -0
  17. data/lib/expressir/3.2/expressir_core.so +0 -0
  18. data/lib/expressir/3.3/expressir_core.so +0 -0
  19. data/lib/expressir/3.4/expressir_core.so +0 -0
  20. data/lib/expressir/4.0/expressir_core.so +0 -0
  21. data/lib/expressir/cli.rb +22 -0
  22. data/lib/expressir/commands/compare.rb +177 -0
  23. data/lib/expressir/commands/doctor.rb +81 -0
  24. data/lib/expressir/commands/receipt.rb +30 -0
  25. data/lib/expressir/commands/validate.rb +7 -0
  26. data/lib/expressir/commands/validate_remarks.rb +283 -0
  27. data/lib/expressir/commands.rb +4 -0
  28. data/lib/expressir/eengine/modified_object.rb +6 -0
  29. data/lib/expressir/eval/builtin_matrix.rb +83 -0
  30. data/lib/expressir/eval/interpreter.rb +13 -0
  31. data/lib/expressir/eval.rb +1 -0
  32. data/lib/expressir/express/builders/expression_builder.rb +4 -3
  33. data/lib/expressir/express/change_classification.rb +75 -0
  34. data/lib/expressir/express/formatters/declarations_formatter.rb +11 -10
  35. data/lib/expressir/express/grammar/parser.rb +15 -2
  36. data/lib/expressir/express/parser.rb +16 -0
  37. data/lib/expressir/express/schema_compare.rb +2 -1
  38. data/lib/expressir/express.rb +2 -0
  39. data/lib/expressir/p28/configuration.rb +124 -0
  40. data/lib/expressir/p28/xsd.rb +73 -32
  41. data/lib/expressir/p28.rb +1 -0
  42. data/lib/expressir/receipt.rb +237 -0
  43. data/lib/expressir/reference/grammar_crosswalk.yml +4 -0
  44. data/lib/expressir/scoreboard.rb +151 -0
  45. data/lib/expressir/version.rb +1 -1
  46. data/lib/expressir.rb +2 -0
  47. data/lib/tasks/scoreboard.rake +59 -0
  48. data/scoreboard-baseline.json +7 -0
  49. metadata +27 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a98fb97c25c89a9a5e4b827d4f55b753e0e8212d2e3bd4fc58dbece4301246e4
4
- data.tar.gz: f2dde5ede1c5b0b7a2ebd0c2738459c199bb7fe3d6e463a12d8d180456b2af5c
3
+ metadata.gz: ed6d84a6cc471ddd5557339a21b166fc49e1dfb496dc3fc91597647dbf1565cf
4
+ data.tar.gz: 130e9298873c14a46197c775497f061429f51d66c62d8a687929444ee37bcf04
5
5
  SHA512:
6
- metadata.gz: 73bab2ea26dab3f4adc6292deff88e7d073dc54e4c13d9fdd73f9591cb52a677b5d3e125c54d5399e01b39833a08f1230f07f1eabd8830411933920aef137ede
7
- data.tar.gz: f70e298de2a767b17c9b545ebb8f1dfd442f17a343725be6471d9c0fa8eeb7795af8685f4d66bf4f12771c98a6bf9262cfb655dc11474e83e5c40caa4f6e1a45
6
+ metadata.gz: 8c028aaabb961b2e7b2a9897ad307b1556ca74b32443e7a53ae4ee43205247c77bd0b43c3ba8a70781adb00d99ebf57cae3027a41de9e0edd08aeeb949738fcd
7
+ data.tar.gz: 00bb5a9ecc6f2a3bcabd8df1b7e31e8a403b65f05441ff131353ccc2ca02b8808c0484ca87e9390101e7dc445cfbaeb480c46799593d4da277e0d08b6694c109
@@ -0,0 +1,124 @@
1
+ name: performance-release
2
+
3
+ # Every release re-measures the per-command scoreboard (TODO.compat/03)
4
+ # and appends the table to the release notes; the gate fails the run on
5
+ # a regression against the committed CI baseline. Idempotent — the
6
+ # marked notes section is replaced, not stacked.
7
+ on:
8
+ workflow_run:
9
+ workflows: ["release"]
10
+ types: [completed]
11
+ workflow_dispatch:
12
+ inputs:
13
+ seed_baseline:
14
+ description: "Measure only and print the baseline JSON for committing"
15
+ type: boolean
16
+ default: false
17
+
18
+ concurrency:
19
+ group: ${{ github.workflow }}
20
+ cancel-in-progress: true
21
+
22
+ permissions:
23
+ contents: write
24
+
25
+ jobs:
26
+ report:
27
+ if: >-
28
+ github.event_name == 'workflow_dispatch' ||
29
+ github.event.workflow_run.conclusion == 'success'
30
+ # Pinned: runner-image and vCPU drift move the medians; the gate
31
+ # compares like against like.
32
+ runs-on: ubuntu-24.04
33
+ steps:
34
+ - uses: actions/checkout@v6
35
+ with:
36
+ # Pin to the exact tree the release run published, so the
37
+ # measured scoreboard describes the released code even when
38
+ # main moves between the release and this report.
39
+ ref: ${{ github.event.workflow_run.head_sha || 'main' }}
40
+
41
+ - name: Set up Ruby
42
+ uses: ruby/setup-ruby@v1
43
+ with:
44
+ ruby-version: "3.3"
45
+ bundler-cache: false
46
+
47
+ - name: Install dependencies
48
+ run: bundle install
49
+
50
+ - name: Let the runner settle after the build
51
+ run: |
52
+ # The install burst pushes the 1-minute load past the gate's
53
+ # budget (half the vCPUs); wait (bounded) for it to decay so
54
+ # the measurement judges steady-state load.
55
+ for i in $(seq 1 60); do
56
+ load=$(awk '{print $1}' /proc/loadavg)
57
+ ncpu=$(nproc)
58
+ awk -v l="$load" -v n="$ncpu" 'BEGIN { exit !(l <= n * 0.5) }' && break
59
+ sleep 5
60
+ done
61
+ echo "1-minute load at measure time: $(awk '{print $1}' /proc/loadavg)"
62
+
63
+ - name: Measure the scoreboard
64
+ run: |
65
+ SCOREBOARD_JSON=/tmp/scoreboard.json \
66
+ bundle exec rake scoreboard:print
67
+
68
+ - name: Gate against the committed CI baseline
69
+ if: ${{ inputs.seed_baseline != true }}
70
+ run: |
71
+ if [ ! -f scoreboard-ci-baseline.json ]; then
72
+ echo "::notice::no scoreboard-ci-baseline.json — gate skipped; seed it from this run's artifact"
73
+ else
74
+ SCOREBOARD_BASELINE=scoreboard-ci-baseline.json \
75
+ bundle exec rake scoreboard:gate
76
+ fi
77
+
78
+ - name: Seed mode — publish the baseline JSON for committing
79
+ if: ${{ inputs.seed_baseline == true }}
80
+ run: |
81
+ cp /tmp/scoreboard.json scoreboard-ci-baseline.json
82
+ echo '## CI scoreboard baseline' >> "$GITHUB_STEP_SUMMARY"
83
+ echo 'Commit `scoreboard-ci-baseline.json` from this run to arm the gate.' >> "$GITHUB_STEP_SUMMARY"
84
+ echo '```json' >> "$GITHUB_STEP_SUMMARY"
85
+ cat /tmp/scoreboard.json >> "$GITHUB_STEP_SUMMARY"
86
+ echo '```' >> "$GITHUB_STEP_SUMMARY"
87
+
88
+ - name: Upload the measurement
89
+ uses: actions/upload-artifact@v4
90
+ with:
91
+ name: scoreboard
92
+ path: /tmp/scoreboard.json
93
+ if-no-files-found: error
94
+
95
+ - name: Append the scoreboard to the release notes of the measured version
96
+ if: ${{ github.event_name == 'workflow_run' }}
97
+ env:
98
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
99
+ run: |
100
+ # The notes target is the release created by the triggering
101
+ # run — NOT "latest" (a rerun of an old run would mis-aim).
102
+ TRIGGERED_AT="${{ github.event.workflow_run.created_at }}"
103
+ TAG=$(gh api "repos/${GITHUB_REPOSITORY}/releases" \
104
+ --jq "map(select(.created_at >= \"${TRIGGERED_AT}\")) | sort_by(.created_at) | last | .tag_name")
105
+ TAG=${TAG:-$(gh release view --json tagName --jq .tagName)}
106
+ echo "Reporting against $TAG"
107
+ gh release view "$TAG" --json body --jq .body > /tmp/body.md
108
+ ruby -e '
109
+ require "json"
110
+ require "expressir"
111
+ require "expressir/scoreboard"
112
+ rows = JSON.parse(File.read("/tmp/scoreboard.json"))
113
+ File.write("/tmp/section.md", Expressir::Scoreboard.table(rows) + "\n")
114
+ body = File.read("/tmp/body.md")
115
+ section = File.read("/tmp/section.md")
116
+ block = "<!-- SCOREBOARD:BEGIN -->\n#{section}<!-- SCOREBOARD:END -->"
117
+ if body.include?("<!-- SCOREBOARD:BEGIN -->")
118
+ body = body.sub(/<!-- SCOREBOARD:BEGIN -->.*<!-- SCOREBOARD:END -->/m, block)
119
+ else
120
+ body = body.chomp + "\n\n" + block
121
+ end
122
+ File.write("/tmp/new_body.md", body)
123
+ '
124
+ gh release edit "$TAG" --notes-file /tmp/new_body.md
@@ -0,0 +1,35 @@
1
+ # 00 — Compatibility & capability program overview
2
+
3
+ Expressir operates alongside established EXPRESS tooling in the same
4
+ ecosystem. This program has two goals: (1) compatibility faces for
5
+ existing toolchain invocations and interchange formats, so pipelines
6
+ can adopt expressir incrementally without rewrites; and (2) capability
7
+ expansion beyond what current implementations offer.
8
+
9
+ Interchange formats we already read (e.g. the `schema.changes`
10
+ comparison report) gain matching writers, so data flows both ways
11
+ across toolchains.
12
+
13
+ ## Ladder
14
+
15
+ | n | task | tier | status |
16
+ |---|------|------|--------|
17
+ | 01 | comparison interchange: `expressir compare` emitting the `schema.changes` report, round-tripping with the existing importer | compat | done (#536) |
18
+ | 02 | compatibility guide + divergence register + `expressir doctor` workspace assessment | compat | done (#543) |
19
+ | 03 | cross-implementation scoreboard: interleaved CPU medians per command (`rake scoreboard`), baseline gate (`scoreboard:gate`) | compat | done (#545) |
20
+ | 04 | unified repository receipt: schemas + instance datasets + mapping tables in one deterministic, signing-ready artifact | capability | done (#548) |
21
+ | 05 | P28 configured binding (clauses 8/10) — the TODO.p28/05 promotion | capability | done (#549) |
22
+ | 06 | semantic change classification: breaking vs additive through the subtype graph (ISO 10303-11 Annex K policy) | capability | done (#550) |
23
+ | 07 | evaluator conformance matrix: ISO 10303-11 Annex B built-in coverage, mutation-tested | capability | done (#552) |
24
+ | 08 | WASM expressir-rs: schema + instance validation in browser/Node | capability | done (#551; expressir-rs#14) |
25
+
26
+ ## Standing rules
27
+
28
+ - Compatibility faces mirror observable contracts (invocation shape,
29
+ output format, exit codes) — never the internals of other tools.
30
+ - Every output format gets a round-trip or cross-read spec against the
31
+ corresponding reader we already ship.
32
+ - Capability tasks cite the clause/annex they implement where
33
+ applicable; no spec-invented behaviour.
34
+ - Divergences are registered (D-NN, the moxml register pattern), not
35
+ silently blessed.
@@ -0,0 +1,34 @@
1
+ # 01 — Comparison interchange: `expressir compare`
2
+
3
+ `expressir compare BASE.exp REVISED.exp [-o report.xml]` runs
4
+ `Expressir::Express::SchemaCompare` across the two files' schemas and
5
+ emits the `schema.changes` interchange report (the format the existing
6
+ `changes` importer reads). Pipelines gain a two-way street: reports we
7
+ emit, our importer consumes.
8
+
9
+ ## Mapping
10
+
11
+ - schemas are paired by downcased id across the two repositories; a
12
+ schema present on only one side contributes all its declarations to
13
+ additions / deletions respectively.
14
+ - deltas come from `SchemaCompare.collection_deltas` per collection
15
+ (constants, types, entities, subtype_constraints, functions, rules,
16
+ procedures), so removed declarations carry their kind even though
17
+ the delta's node is nil.
18
+ - op :added → `schema.additions`, op :removed → `schema.deletions`,
19
+ op :changed → `schema.modifications`; attribute-level deltas
20
+ (paths deeper than `schema.item`) always land in modifications —
21
+ an added attribute modifies its entity — with the qualified
22
+ attribute path as the name.
23
+ - Emission goes through Moxml: lutaml-model's leptris-backed
24
+ serializer mis-parses the interchange's dotted element names as
25
+ namespace prefixes (upstream family of lutaml-model#997); the
26
+ model layer stays lutaml-model (from_xml is unaffected).
27
+
28
+ ## Acceptance
29
+
30
+ - Round trip: emit a report for a seeded old/new schema pair; the
31
+ existing importer parses it and the additions/modifications carry
32
+ exactly the seeded differences.
33
+ - Exit code 0 on success; a missing input file is a command error.
34
+ - Deterministic output: same inputs, same bytes.
@@ -0,0 +1,21 @@
1
+ # 02-compat-guide — Compatibility guide, divergence register (D-NN) and the expressir doctor workspace assessment
2
+
3
+ docs/_guides/compat/ gets the per-command Rosetta table and exit-code contracts; doctor reads an existing toolchain workspace (corpus paths, batch scripts, configs) and emits a readiness report plus a starter manifest. Acceptance: doctor on the shipped corpus fixtures reports every fixture as ready; the register cites every known divergence.
4
+
5
+ ## Status: done
6
+
7
+ - Divergence register: `docs/_guides/compat/interchange.adoc`
8
+ (D-01 corpus header tolerance, D-02 remark-only files, D-03
9
+ schema.changes Moxml emission) with the linkage guard
10
+ `spec/expressir/compat/divergence_register_spec.rb` — entries must
11
+ cite existing specs, ids contiguous.
12
+ - Compatibility guide: `docs/_guides/compat/toolchain.adoc` — the
13
+ per-command Rosetta table (invocation, output, pinning spec) and
14
+ exit-code contract.
15
+ - `expressir doctor DIR [-o MANIFEST]`
16
+ (`lib/expressir/commands/doctor.rb`): scans a workspace for
17
+ schemas (.exp), instance datasets (.p21) and mapping files
18
+ (mapping*.yaml), probes each with the shipped parsers, prints the
19
+ readiness report (ready/UNREADABLE per file), and optionally writes
20
+ a starter schema manifest. Spec:
21
+ `spec/expressir/commands/doctor_spec.rb`.
@@ -0,0 +1,24 @@
1
+ # 03-scoreboard — Cross-implementation scoreboard
2
+
3
+ interleaved A/B CPU-time medians per command (parse, compare, validate, flatten) against a pinned reference implementation, published per release and gating regressions (the moxml scoreboard pattern). Acceptance: the scoreboard rides the release workflow; a regression fails the gate.
4
+
5
+ ## Status: done
6
+
7
+ - Harness: `Expressir::Scoreboard`
8
+ (`lib/expressir/scoreboard.rb`, #545) — interleaved CPU-time
9
+ medians over deterministic synthetic fixtures: parse on both shipped
10
+ lanes (native core vs Ruby grammar), compare, population validate,
11
+ flatten.
12
+ - Gate: `rake scoreboard:gate` — fails on a >2x regression against the
13
+ committed baseline (medians swing ~2x on loaded boxes); the baseline
14
+ path is `SCOREBOARD_BASELINE`-overridable, so CI and local
15
+ toolchains gate against their own like-for-like measurement.
16
+ - Release riding: `.github/workflows/performance-release.yml` — on
17
+ every completed `release` run (pinned `ubuntu-24.04`, load-settled,
18
+ tree pinned to the released SHA) the scoreboard re-measures, gates
19
+ against the committed CI baseline `scoreboard-ci-baseline.json`,
20
+ and appends the table to the release notes (marked, idempotent
21
+ section). `workflow_dispatch` with `seed_baseline` measures and
22
+ publishes the JSON for committing.
23
+ - Specs: `spec/expressir/scoreboard_spec.rb` (harness rows, table
24
+ rendering, gate logic).
@@ -0,0 +1,26 @@
1
+ # 04-unified-receipt — Unified repository receipt
2
+
3
+ one deterministic artifact binding schema validation, instance dataset validation and mapping validation (the three shipped validators) with digests, versions and per-rule verdicts; structured for signing. Acceptance: one manifest drives one receipt; byte-identical reruns; signing-ready canonical JSON.
4
+
5
+ ## Status: done
6
+
7
+ - `Expressir::Receipt`
8
+ (`lib/expressir/receipt.rb`): one workspace manifest
9
+ (`Expressir::Receipt::WorkspaceManifest`, lutaml-model key-value
10
+ mapping) drives one receipt binding the three shipped validators —
11
+ schema (`Expressir::Express::Checker`), instance datasets
12
+ (`Expressir::P21::Validator` over `DatasetManifest`s) and module
13
+ mappings (`Expressir::Mapping` links/refpaths/rules) — with SHA-256
14
+ digests of every consumed input, the generator version, and per-rule
15
+ verdicts.
16
+ - Canonical, signing-ready bytes: recursively sorted object keys, no
17
+ insignificant whitespace, no timestamps, manifest-relative paths —
18
+ `Receipt.generate` output is byte-identical across reruns and
19
+ checkouts; signatures cover the canonical serialization (declared in
20
+ the receipt's `canonicalization` field).
21
+ - CLI: `expressir receipt MANIFEST [-o FILE]` — exits 1 when the
22
+ receipt reports errors.
23
+ - Specs: `spec/expressir/commands/receipt_spec.rb` — one manifest →
24
+ one receipt covering all three validators; byte-identical reruns;
25
+ canonical byte form (regenerated == stored); error path exits with
26
+ the receipt still written.
@@ -0,0 +1,26 @@
1
+ # 05-p28-configured — P28 configured binding (ISO 10303-28 clauses 8/10) — the TODO.p28/05 promotion
2
+
3
+ configuration directives over the default binding. Acceptance: the TODO.p28/01-04 corpus validates through a configured derivation; clause-cited rules.
4
+
5
+ ## Status: done
6
+
7
+ - `Expressir::P28::Configuration`
8
+ (`lib/expressir/p28/configuration.rb`): parses the clause 8
9
+ configuration document (annex D `configuration.xsd` shape,
10
+ namespace `urn:iso10303-28:ex`) — options, type/entity/attribute
11
+ directives, nested scopes.
12
+ - Applied over the clause 7 default derivation
13
+ (`P28::Xsd.format(schema, configuration:)`): the configuration-
14
+ chosen target namespace (7.7.2 via clause 8), the naming
15
+ convention (7.1.2 via clause 8: initial-upper default,
16
+ camel-case, preserve-case), and explicit type/entity/attribute
17
+ renames — followed through every type reference.
18
+ - Default invariant (acceptance): a configuration with no directives
19
+ derives byte-identically to the unconfigured default binding, so
20
+ the TODO.p28/01-04 corpus validates through the configured
21
+ derivation unchanged. Pinned in
22
+ `spec/expressir/p28/configuration_spec.rb` together with the
23
+ rename/naming/namespace rules and the unknown-convention rejection.
24
+ - Directives outside the applied subset are registered as divergence
25
+ D-04 in `docs/_guides/compat/interchange.adoc` (clause-cited) and
26
+ pinned by the same spec.
@@ -0,0 +1,26 @@
1
+ # 06-change-classification — Semantic change classification
2
+
3
+ SchemaCompare deltas classified breaking vs additive through the subtype graph and the ISO 10303-11 Annex K deprecation policy. Acceptance: a seeded breaking change (supertype attribute removal) classifies breaking; an additive one (new subtype) classifies additive; classification rides the report.
4
+
5
+ ## Status: done
6
+
7
+ - `Expressir::Express::ChangeClassification`
8
+ (`lib/expressir/express/change_classification.rb`): classifies
9
+ SchemaCompare deltas through the base schema's subtype graph —
10
+ `:added` is additive; removals and signature changes are breaking,
11
+ carrying the affected direct subtypes of the owning entity.
12
+ - ISO 10303-11 Annex K deprecation policy: paths the schema edition
13
+ already announced for removal are flagged `deprecated` on the
14
+ verdict (the removal stays classified breaking — the flag carries
15
+ the policy).
16
+ - Rides the report: the `schema.changes` emission's
17
+ `modified.object` elements carry `classif="breaking|additive"`
18
+ (`Commands::Compare` classifies every delta before emission);
19
+ readers ignoring unknown attributes are unaffected — registered as
20
+ divergence D-05.
21
+ - Specs: `spec/expressir/express/change_classification_spec.rb`
22
+ (acceptance cases: supertype attribute removal → breaking with
23
+ affected subtypes; new subtype → additive; declaration removal;
24
+ signature change; deprecation flag; unclassified-until-applied);
25
+ report emission pinned in
26
+ `spec/expressir/commands/compare_spec.rb`.
@@ -0,0 +1,22 @@
1
+ # 07-evaluator-matrix — Evaluator conformance matrix
2
+
3
+ ISO 10303-11 Annex B built-in function coverage of Expressir::Eval, mutation-tested per function. Acceptance: the matrix is generated, cited per clause, and mutation failures fail the suite.
4
+
5
+ ## Status: done
6
+
7
+ - `Expressir::Eval::BuiltinMatrix`
8
+ (`lib/expressir/eval/builtin_matrix.rb`): the clause 15 standard
9
+ function inventory, every row cited per clause (15.1–15.29) with
10
+ its coverage status. New this task: `BOUNDS`, `ROLESOF` and
11
+ `VALUE_IN` join the dispatch; `FORMAT` and `VALUE_UA` are
12
+ registered divergent (D-06), `ROLESOF` documented as degenerate.
13
+ - Generated matrix:
14
+ `docs/_guides/compat/eval-builtin-matrix.adoc` — produced by
15
+ `BuiltinMatrix.to_adoc`, deterministic (spec-asserted byte-equal
16
+ across generations), every row present with its clause.
17
+ - Mutation-tested per function:
18
+ `spec/expressir/eval/builtin_matrix_spec.rb` holds, for every
19
+ implemented function, a clause example [arguments, expected,
20
+ mutation]; the suite fails when a function drifts from its example
21
+ OR when the example stops distinguishing the mutation (a surviving
22
+ mutant fails the suite).
@@ -0,0 +1,24 @@
1
+ # 08-wasm — WASM expressir-rs
2
+
3
+ the Rust core compiled to WebAssembly for schema + instance validation in browser/Node. Acceptance: a wasm package validates a schema and a P21 population with parity to the native path on the conformance corpus.
4
+
5
+ ## Status: done
6
+
7
+ - Rust surface (lutaml/expressir-rs#14): `src/p21.rs` parses the
8
+ ISO-10303-21 exchange structure (header/FILE_SCHEMA, named data
9
+ sections, entity/complex/typed records, anchors and external
10
+ references, EXPRESS constant references) and validates record
11
+ keywords against a schema inventory (clause 12); `src/wasm.rs`
12
+ exposes `parse_schema` (declaration inventory through the full
13
+ grammar engine), `parse_population` and `validate_population` over
14
+ wasm-bindgen, wasm32-only.
15
+ - Package: `wasm-pack build --target nodejs --release` produces the
16
+ browser/Node package.
17
+ - Parity harness:
18
+ `spec/expressir/wasm_parity_spec.rb` — on the P21 conformance
19
+ corpus (annexes E/H/I/J) the wasm schema parse returns the same
20
+ entity inventory as the native path, every population parses with
21
+ the same FILE_SCHEMA/instance/anchor/reference inventories, and the
22
+ schema inventory validates the annex H population while a bogus
23
+ inventory rejects it. Skipped when the package or node is absent;
24
+ parity asserted whenever present.
@@ -0,0 +1,42 @@
1
+ = Eval built-in function matrix
2
+
3
+ Coverage of the ISO 10303-11 clause 15 standard functions in
4
+ `Expressir::Eval`, generated from `Expressir::Eval::BuiltinMatrix`.
5
+ Divergent rows are registered in
6
+ xref:interchange[the interchange and divergences page].
7
+
8
+ [cols="1,1,1,2"]
9
+ |===
10
+ | Function | Clause | Status | Note
11
+ | `ABS` | 15.1 | implemented | |
12
+ | `ACOS` | 15.2 | implemented | |
13
+ | `ASIN` | 15.3 | implemented | |
14
+ | `ATAN` | 15.4 | implemented | |
15
+ | `ATAN2` | 15.4 | implemented | two-argument arctangent |
16
+ | `BLENGTH` | 15.5 | implemented | |
17
+ | `BOUNDS` | 15.6 | implemented | evaluated aggregates: [1, size] |
18
+ | `COS` | 15.7 | implemented | |
19
+ | `EXISTS` | 15.8 | implemented | |
20
+ | `EXP` | 15.9 | implemented | |
21
+ | `FORMAT` | 15.10 | divergent | not evaluated (D-06) |
22
+ | `HIBOUND` | 15.11 | implemented | evaluated aggregates: size |
23
+ | `HIINDEX` | 15.12 | implemented | evaluated aggregates: size |
24
+ | `LENGTH` | 15.13 | implemented | |
25
+ | `LOBOUND` | 15.14 | implemented | evaluated aggregates: 1 |
26
+ | `LOINDEX` | 15.15 | implemented | evaluated aggregates: 1 |
27
+ | `LOG` | 15.16 | implemented | |
28
+ | `LOG2` | 15.16 | implemented | |
29
+ | `LOG10` | 15.16 | implemented | |
30
+ | `NVL` | 15.19 | implemented | |
31
+ | `ODD` | 15.20 | implemented | |
32
+ | `ROLESOF` | 15.21 | implemented | degenerate: no role metadata — empty set (D-06) |
33
+ | `SIN` | 15.22 | implemented | |
34
+ | `SIZEOF` | 15.23 | implemented | |
35
+ | `SQRT` | 15.24 | implemented | |
36
+ | `TAN` | 15.25 | implemented | |
37
+ | `TYPEOF` | 15.26 | implemented | |
38
+ | `USEDIN` | 15.27 | implemented | |
39
+ | `VALUE` | 15.28 | implemented | |
40
+ | `VALUE_IN` | 15.29 | implemented | |
41
+ | `VALUE_UA` | 15.29 | divergent | not evaluated (D-06) |
42
+ |===
@@ -0,0 +1,16 @@
1
+ ---
2
+ title: Compatibility
3
+ has_children: true
4
+ nav_order: 9
5
+ ---
6
+
7
+ = Compatibility
8
+
9
+ Expressir interoperates with established EXPRESS toolchains: it reads
10
+ and writes the interchange formats they produce, and its commands map
11
+ onto familiar invocations. This section documents the compatibility
12
+ surface and its registered divergences.
13
+
14
+ * *Interchange formats* — the schema.changes comparison report,
15
+ corpus tolerances, and the divergence register
16
+ * *Workspace readiness* — `expressir doctor`
@@ -0,0 +1,79 @@
1
+ ---
2
+ title: Interchange formats and divergences
3
+ nav_order: 1
4
+ parent: Compatibility
5
+ ---
6
+
7
+ = Interchange formats and divergences
8
+
9
+ Expressir reads and writes the interchange formats the EXPRESS
10
+ ecosystem already uses, and runs against real-world corpora that
11
+ predate strict readings of the standard. Where expressir's behaviour
12
+ diverges from a strict standard reading — by tolerance or by
13
+ enhancement — the divergence is registered here with an ID, and a
14
+ spec pins it.
15
+
16
+ == Comparison reports (schema.changes)
17
+
18
+ `expressir compare BASE REVISED` emits the `schema.changes` XML
19
+ report (additions, deletions, modifications per declaration), and
20
+ `expressir changes` imports the same format. The round trip is
21
+ pinned in `spec/expressir/commands/compare_spec.rb`.
22
+
23
+ == Registered divergences
24
+
25
+ | ID | Facet | Divergence
26
+ |===
27
+ | D-01
28
+ | entity header
29
+ | Real-world corpora omit the entity header delimiter
30
+ (`ENTITY qus -- remark` with no `;` — STEPmod resources,
31
+ quantities_and_units_schema.exp:170). ISO 10303-11 requires it;
32
+ expressir makes the delimiter optional. Pinned in
33
+ `spec/expressir/express/parser_537_parser_gaps_corpus_gate_spec.rb`.
34
+
35
+ | D-02
36
+ | remark-only files
37
+ | Files with no SCHEMA wrapper (conversion artifacts) raise the clean
38
+ `SchemaNotFoundError` ("no schema found") on both parse paths
39
+ instead of a grammar dump. Pinned in
40
+ `spec/expressir/express/parser_537_parser_gaps_corpus_gate_spec.rb`.
41
+
42
+ | D-03
43
+ | schema.changes emission
44
+ | The report is emitted through Moxml: lutaml-model's leptris-backed
45
+ serializer mis-parses the interchange's dotted element names as
46
+ namespace prefixes (lutaml-model#997 family). The model layer stays
47
+ lutaml-model; `from_xml` is unaffected. Pinned in
48
+ `spec/expressir/commands/compare_spec.rb`.
49
+
50
+ | D-04
51
+ | P28 binding configuration
52
+ | The clause 8 configuration document is parsed in full, but the
53
+ derived XML schema applies only the naming-convention, target
54
+ namespace and explicit renames; the remaining directives (exp-type,
55
+ exp-attribute, content, flatten, sparse, tagless, keep, use-id,
56
+ invert, tag-source/tag-values, notation, map, inheritance) are
57
+ preserved without effect (ISO 10303-28 clause 8). Pinned in
58
+ `spec/expressir/p28/configuration_spec.rb`.
59
+
60
+ | D-05
61
+ | schema.changes classification
62
+ | The comparison report's `modified.object` elements carry a
63
+ `classif` attribute — breaking vs additive per the subtype graph
64
+ and the ISO 10303-11 Annex K deprecation policy — beyond the
65
+ interchange minimum. Readers that ignore unknown attributes are
66
+ unaffected (the importer round trip is pinned in
67
+ `spec/expressir/commands/compare_spec.rb`; the classification in
68
+ `spec/expressir/express/change_classification_spec.rb`).
69
+
70
+ | D-06
71
+ | Eval built-in coverage
72
+ | Of the ISO 10303-11 clause 15 standard functions, `FORMAT` and
73
+ `VALUE_UA` are not evaluated, and `ROLESOF` returns the empty set
74
+ (the evaluated population carries no role metadata); aggregate
75
+ bounds functions answer for evaluated aggregates only. The
76
+ generated matrix is
77
+ xref:eval-builtin-matrix[the eval built-in function matrix], pinned
78
+ in `spec/expressir/eval/builtin_matrix_spec.rb`.
79
+ |===
@@ -0,0 +1,57 @@
1
+ ---
2
+ title: Toolchain mapping
3
+ nav_order: 2
4
+ parent: Compatibility
5
+ ---
6
+
7
+ = Toolchain mapping
8
+
9
+ Expressir's commands cover the core EXPRESS toolchain surface. This
10
+ table maps each capability to its expressir invocation, the format it
11
+ produces, and where the behaviour is pinned.
12
+
13
+ [cols="1,1,1,2"]
14
+ |===
15
+ | Capability | Command | Output | Pinned by
16
+
17
+ | Comparison report | `expressir compare BASE REVISED -o report.xml`
18
+ | `schema.changes` XML | Round trip through the importer:
19
+ `spec/expressir/commands/compare_spec.rb`
20
+
21
+ | Comparison import | `expressir changes` family
22
+ | EXPRESS Changes YAML | `spec/expressir/commands/changes_import_eengine_spec.rb`
23
+
24
+ | Instance + schema validation | `expressir population validate MANIFEST`
25
+ | Deterministic receipt JSON (exit 1 on errors) |
26
+ `spec/expressir/commands/population_spec.rb`
27
+
28
+ | Longform flatten | `expressir flatten PATH`
29
+ | Single longform schema | Annex G audit suite
30
+ (`spec/fixtures/shtolo/annex-g-rules.md`)
31
+
32
+ | XML Schema rendering | `expressir xsd PATH`
33
+ | XSD | `spec/expressir/commands/xsd_spec.rb`
34
+
35
+ | Corpus index | `expressir xml-index DIR`
36
+ | Index XML | `spec/expressir/commands/smrl_xml_index_spec.rb`
37
+
38
+ | Workspace assessment | `expressir doctor DIR [-o manifest]`
39
+ | Readiness report + starter manifest |
40
+ `spec/expressir/commands/doctor_spec.rb`
41
+
42
+ |===
43
+
44
+ == Exit codes
45
+
46
+ * `0` — success (validation runs report their verdicts in the output
47
+ or receipt)
48
+ * `1` — the command completed but its findings include errors
49
+ (e.g. `population validate`)
50
+ * command failures (unreadable input, missing files) raise and exit
51
+ non-zero
52
+
53
+ == Divergences
54
+
55
+ Tolerances and enhancements relative to strict standard readings are
56
+ registered with IDs in xref:interchange[the interchange and
57
+ divergences page] — every entry cites the spec that pins it.
@@ -78,6 +78,7 @@ grammar are classified with one of these statuses:
78
78
  | `entityConstructor` | entity_constructor | aligned |
79
79
  | `entityDecl` | entity_decl | aligned |
80
80
  | `entityHead` | entity_head | aligned |
81
+ | `entityHeaderTail` | | internal | trivia and the optional delimiter after the entity name, split out of entityHead so the header tail is atomic (issue
81
82
  | `entityId` | entity_id | aligned |
82
83
  | `entityRef` | entity_ref | aligned |
83
84
  | `enumerationExtension` | enumeration_extension | aligned |
Binary file
Binary file
Binary file
Binary file
data/lib/expressir/cli.rb CHANGED
@@ -129,6 +129,19 @@ module Expressir
129
129
  Expressir::Commands::ExportOwl.new(options).run(path)
130
130
  end
131
131
 
132
+ desc "compare BASE REVISED", "Compare two EXPRESS files; write the schema.changes interchange report"
133
+ option :output, type: :string, aliases: "-o",
134
+ desc: "Report path (defaults to stdout)"
135
+ def compare(base_path, revised_path)
136
+ Expressir::Commands::Compare.new(options).run(base_path, revised_path)
137
+ end
138
+
139
+ desc "doctor DIR", "Assess a workspace for expressir readiness"
140
+ option :emit_manifest, type: :string, desc: "Write a starter schema manifest listing the ready schemas"
141
+ def doctor(path)
142
+ Expressir::Commands::Doctor.new(options).run(path)
143
+ end
144
+
132
145
  desc "xml-index DIR", "Write the SMRL index XML for every EXPRESS schema under DIR"
133
146
  method_option :output, type: :string, aliases: "-o",
134
147
  desc: "Output file path (defaults to stdout)"
@@ -142,6 +155,15 @@ module Expressir
142
155
  desc "population SUBCOMMAND", "Part 21 dataset validation commands"
143
156
  subcommand "population", Expressir::Commands::Population
144
157
 
158
+ desc "receipt MANIFEST",
159
+ "Run schema, dataset and mapping validation over one workspace " \
160
+ "manifest; emit the unified canonical-JSON receipt"
161
+ method_option :output, type: :string, aliases: "-o",
162
+ desc: "Receipt path (defaults to stdout)"
163
+ def receipt(manifest_path)
164
+ Expressir::Commands::Receipt.new(options).run(manifest_path)
165
+ end
166
+
145
167
  desc "coverage *PATH",
146
168
  "List EXPRESS entities and check documentation coverage"
147
169
  method_option :format, type: :string,