expressir 2.4.40 → 2.4.42
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.
- checksums.yaml +4 -4
- data/.github/workflows/performance-release.yml +124 -0
- data/TODO.compat/00-overview.md +35 -0
- data/TODO.compat/01-interchange-cli.md +34 -0
- data/TODO.compat/02-compat-guide.md +21 -0
- data/TODO.compat/03-scoreboard.md +24 -0
- data/TODO.compat/04-unified-receipt.md +26 -0
- data/TODO.compat/05-p28-configured.md +26 -0
- data/TODO.compat/06-change-classification.md +26 -0
- data/TODO.compat/07-evaluator-matrix.md +22 -0
- data/TODO.compat/08-wasm.md +24 -0
- data/docs/_guides/compat/eval-builtin-matrix.adoc +42 -0
- data/docs/_guides/compat/index.adoc +16 -0
- data/docs/_guides/compat/interchange.adoc +79 -0
- data/docs/_guides/compat/toolchain.adoc +57 -0
- data/docs/_guides/reference/grammar-crosswalk.adoc +1 -0
- data/expressir.gemspec +1 -2
- data/ext/expressir_core/Cargo.toml +1 -1
- data/lib/expressir/cli.rb +22 -0
- data/lib/expressir/commands/changes_import_eengine.rb +18 -13
- data/lib/expressir/commands/compare.rb +177 -0
- data/lib/expressir/commands/doctor.rb +81 -0
- data/lib/expressir/commands/receipt.rb +30 -0
- data/lib/expressir/commands/validate.rb +7 -0
- data/lib/expressir/commands/validate_remarks.rb +283 -0
- data/lib/expressir/commands.rb +4 -0
- data/lib/expressir/eengine/modified_object.rb +6 -0
- data/lib/expressir/eval/builtin_matrix.rb +83 -0
- data/lib/expressir/eval/interpreter.rb +13 -0
- data/lib/expressir/eval.rb +1 -0
- data/lib/expressir/express/builders/expression_builder.rb +4 -3
- data/lib/expressir/express/change_classification.rb +75 -0
- data/lib/expressir/express/formatters/declarations_formatter.rb +11 -10
- data/lib/expressir/express/grammar/parser.rb +15 -2
- data/lib/expressir/express/parser.rb +16 -0
- data/lib/expressir/express/schema_compare.rb +2 -1
- data/lib/expressir/express.rb +2 -0
- data/lib/expressir/p28/configuration.rb +124 -0
- data/lib/expressir/p28/xsd.rb +73 -32
- data/lib/expressir/p28.rb +1 -0
- data/lib/expressir/receipt.rb +237 -0
- data/lib/expressir/reference/grammar_crosswalk.yml +4 -0
- data/lib/expressir/scoreboard.rb +151 -0
- data/lib/expressir/version.rb +1 -1
- data/lib/expressir.rb +2 -0
- data/lib/tasks/scoreboard.rake +59 -0
- data/scoreboard-baseline.json +7 -0
- metadata +29 -18
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 570004764a276c54f963e6db2ab5d43230afd0d9d28e15eed298c67a11f64ee4
|
|
4
|
+
data.tar.gz: d80a1e7c3e8f434bb7d468d09919528c7674e9a321cbdf424e6838e85453a7a6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 5408c2662b08ba2a0602bac3b663c8cc72bbae66dc335f34006f2542652c6ea55acfd675e61b3515d68508fe02b3a08fb84e4195ae14656664e0ac4697971d1c
|
|
7
|
+
data.tar.gz: 7f9dc94925ac59bf4625fa04f59d32891c299896f953ad3b6171e1da3f369dcd92acbfc904193ac5b9ec858d05cb0f8a814911ba22c55909d09efaf79fd410f8
|
|
@@ -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 |
|
data/expressir.gemspec
CHANGED
|
@@ -48,8 +48,7 @@ Gem::Specification.new do |spec|
|
|
|
48
48
|
spec.add_dependency "csv"
|
|
49
49
|
spec.add_dependency "liquid", "~> 5"
|
|
50
50
|
spec.add_dependency "lutaml-model", "~> 0.8.114"
|
|
51
|
-
spec.add_dependency "moxml"
|
|
52
|
-
spec.add_dependency "nokogiri", "~> 1.19"
|
|
51
|
+
spec.add_dependency "moxml", ">= 0.5.154"
|
|
53
52
|
spec.add_dependency "paint"
|
|
54
53
|
spec.add_dependency "parsanol", "~> 1.3.9", ">= 1.3.89"
|
|
55
54
|
spec.add_dependency "ruby-progressbar", "~> 1.11"
|
|
@@ -13,7 +13,7 @@ magnus = { version = "0.9" }
|
|
|
13
13
|
# Pinned core release (M1, TODO.parity-ee/19): the ext never floats
|
|
14
14
|
# main — bump the tag per expressir release, alongside the validation
|
|
15
15
|
# run that pins it.
|
|
16
|
-
expressir-rs = { git = "https://github.com/lutaml/expressir-rs", tag = "v0.1.
|
|
16
|
+
expressir-rs = { git = "https://github.com/lutaml/expressir-rs", tag = "v0.1.8" }
|
|
17
17
|
serde_json = "1.0"
|
|
18
18
|
|
|
19
19
|
|
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,
|