Resolve deck_name aliases and suppress opm-common family containers

opm-common models families of summary vectors and array variants under a
single schema name (WELL_PROBE, AQUIFER_PROBE_ANALYTIC, MULT_XYZ, …) whose
deck_names are the concrete keywords users actually type (WOPR, AAQP, MULTX).

- Suppress the 31 family/container schema names from the index: they are
  never typed in a deck, but were leaking in as fake keywords with a
  placeholder summary, polluting completions and passing as valid. Real
  keywords that carry deck_names (KRNUM, IMBNUM, DIFF, NEXTSTEP) keep their
  reference-manual entry untouched.
- Tag every expanded mnemonic with alias_of naming its family keyword
  (WOPR -> WELL_PROBE, KRNUMX -> KRNUM), including pre-existing entries from
  the manual SUMMARY table and the directional-variant expansion. Skip the
  self-reference where a keyword lists its own name in deck_names.
- Propagate alias_of into the compact index and surface it in keyword hover.
- Document the alias hover and container suppression in the README.

Adds python tests and a vscode-free data-integrity test over the shipped index.

Author: magnesj

scripts/build_keyword_index.py

@@ -559,6 +559,17 @@ def synthesize_opm_only_entries(index: dict, opm_common_index: dict) -> int:
     for name, opm in opm_common_index.items():
         if name in index:
             continue
+        if opm.get("deck_names"):
+            # Alias/family container: an opm-common schema name (WELL_PROBE,
+            # AQUIFER_PROBE_ANALYTIC, ENDPOINT_SPECIFIERS, MULT_XYZ, …) whose
+            # real deck keywords are listed in ``deck_names`` and are emitted
+            # separately by ``expand_probe_deck_names``. The container name
+            # itself is never typed in a deck, so don't synthesize it as a
+            # keyword (it would otherwise pollute completions and be wrongly
+            # accepted as valid). Real keywords that happen to carry deck_names
+            # (KRNUM, IMBNUM, DIFF, NEXTSTEP) already have a reference-manual
+            # entry, so they were skipped by the ``name in index`` guard above.
+            continue
         sections = list(opm["sections"])
         records = opm.get("records")
         items = opm["items"]
@@ -622,8 +633,15 @@ def expand_probe_deck_names(index: dict, opm_common_index: dict) -> int:
     (WELL_PROBE, FIELD_PROBE, BLOCK_PROBE, …) into individual recognised
     entries. Each is a minimal entry (name, sections, one-line summary) with no
     size shape, so it is recognised by the diagnostics engine without triggering
-    arity or terminator checks. Existing entries (e.g. WOPR from the manual) are
-    left untouched. Returns the number of entries added.
+    arity or terminator checks.
+
+    Every expanded mnemonic is tagged with ``alias_of`` naming the family
+    keyword it belongs to (WOPR -> WELL_PROBE, KRNUMX -> KRNUM), so hover/docs
+    can surface the relationship. A mnemonic that already exists (e.g. WOPR from
+    the manual SUMMARY table, or KRNUMX from the directional-variant expansion)
+    keeps its richer fields and only gains the ``alias_of`` tag. Returns the
+    number of entries added (pre-existing entries that were merely tagged are
+    not counted).
     """
     added = 0
     for probe_name, opm in opm_common_index.items():
@@ -633,7 +651,20 @@ def expand_probe_deck_names(index: dict, opm_common_index: dict) -> int:
         sections = list(opm.get("sections", []))
         summary = _probe_summary(opm.get("comment", ""), probe_name)
         for dn in deck_names:
-            if not dn or dn in index:
+            if not dn or dn == probe_name:
+                # Some real keywords (IMBNUM, NEXTSTEP) list their own name in
+                # deck_names alongside their variants; a keyword is not an alias
+                # of itself, so skip the self-reference.
+                continue
+            existing = index.get(dn)
+            if existing is not None:
+                # Already present from the manual or directional expansion;
+                # record the family it aliases without clobbering its fields.
+                # Index values may be a list (multi-section manual entry) or a
+                # plain dict; tag the primary entry. First family wins, which
+                # is deterministic in opm-common's stable load order.
+                primary = existing[0] if isinstance(existing, list) else existing
+                primary.setdefault("alias_of", probe_name)
                 continue
             index[dn] = {
                 "name":         dn,
@@ -646,6 +677,7 @@ def expand_probe_deck_names(index: dict, opm_common_index: dict) -> int:
                 "examples":     [],
                 "full_text":    "",
                 "source_file":  "",
+                "alias_of":     probe_name,
             }
             added += 1
     print(f"Expanded {added} summary-vector deck names")
@@ -1645,6 +1677,9 @@ def write_compact_json(index: dict, output_path: Path):
         prohibits = primary.get("prohibits")
         if prohibits:
             out_entry["prohibits"] = prohibits
+        alias_of = primary.get("alias_of")
+        if alias_of:
+            out_entry["alias_of"] = alias_of
         compact[name] = out_entry
     with open(output_path, "w", encoding="utf-8") as f:
         json.dump(compact, f, separators=(",", ":"), ensure_ascii=False)

scripts/test_build_keyword_index.py

@@ -1042,6 +1042,28 @@ def test_keywords_only_in_opm_common_get_synthesized(self):
         assert e["parameters"][1]["default"] == "1"
         assert "OPM Flow keyword" in e["summary"]
 
+    def test_alias_family_containers_are_not_synthesized(self):
+        # opm-common schema names that carry deck_names (PROBE families,
+        # ENDPOINT_SPECIFIERS, MULT_XYZ, …) are not deck keywords themselves;
+        # their deck_names are expanded separately. They must not be added as
+        # standalone keywords (else they pollute completions / pass as valid).
+        index: dict = {}
+        opm = {
+            "WELL_PROBE": {
+                "sections": ["SUMMARY"],
+                "items": [],
+                "deck_names": ["WOPR", "WWIP"],
+            },
+            "PYACTION": {  # a normal OPM-only keyword, no deck_names
+                "sections": ["SCHEDULE"],
+                "items": [{"name": "FILE", "value_type": "STRING"}],
+            },
+        }
+        added = synthesize_opm_only_entries(index, opm)
+        assert added == 1
+        assert "WELL_PROBE" not in index
+        assert "PYACTION" in index
+
     def test_already_present_keywords_are_left_alone(self):
         index = {"EXISTING": {"name": "EXISTING", "summary": "kept"}}
         opm = {"EXISTING": {"sections": ["RUNSPEC"], "items": []}}
@@ -1480,6 +1502,8 @@ def test_expands_deck_names_into_minimal_entries(self):
         assert index["WWIP"]["name"] == "WWIP"
         assert index["WWIP"]["sections_opm"] == ["SUMMARY"]
         assert index["WWIP"]["summary"] == "Well summary vectors."
+        # Each expanded mnemonic is tagged with the family it derives from.
+        assert index["WWIP"]["alias_of"] == "WELL_PROBE"
         # No size shape -> no terminator/arity checks downstream.
         assert "size_kind" not in index["WWIP"]
 
@@ -1489,6 +1513,35 @@ def test_does_not_overwrite_existing_entries(self):
         added = expand_probe_deck_names(index, opm)
         assert added == 1
         assert index["WOPR"]["summary"] == "from manual"
+        # A pre-existing mnemonic keeps its richer fields but still gains the
+        # alias tag so hover can show the family relationship.
+        assert index["WOPR"]["alias_of"] == "WELL_PROBE"
+
+    def test_tags_existing_list_valued_entry(self):
+        # Multi-section manual entries are stored as a list of dicts; the
+        # primary (first) entry must receive the alias tag without error.
+        index = {"WOPR": [{"name": "WOPR", "summary": "from manual"}]}
+        opm = {"WELL_PROBE": {"sections": ["SUMMARY"], "deck_names": ["WOPR"]}}
+        added = expand_probe_deck_names(index, opm)
+        assert added == 0
+        assert index["WOPR"][0]["alias_of"] == "WELL_PROBE"
+
+    def test_self_referential_deck_name_is_not_tagged(self):
+        # IMBNUM/NEXTSTEP list their own name in deck_names; a keyword must not
+        # be marked as an alias of itself.
+        index = {"IMBNUM": {"name": "IMBNUM", "summary": "real keyword"}}
+        opm = {"IMBNUM": {"sections": ["REGIONS"],
+                          "deck_names": ["IMBNUM", "IMBNUMX", "IMBNUMY"]}}
+        expand_probe_deck_names(index, opm)
+        assert "alias_of" not in index["IMBNUM"]
+        assert index["IMBNUMX"]["alias_of"] == "IMBNUM"
+
+    def test_existing_alias_tag_is_not_overwritten(self):
+        # First family wins when a mnemonic is claimed by more than one family.
+        index = {"WOPR": {"name": "WOPR", "alias_of": "ALREADY"}}
+        opm = {"WELL_PROBE": {"sections": ["SUMMARY"], "deck_names": ["WOPR"]}}
+        expand_probe_deck_names(index, opm)
+        assert index["WOPR"]["alias_of"] == "ALREADY"
 
     def test_collect_deck_name_regexes_dedupes(self):
         opm = {

vscode-extension/README.md

@@ -69,6 +69,11 @@ Hovering over a **value in a data record** shows the description for that specif
 parameter column. For example, hovering over the group name in a `WELSPECS` record
 shows the `GRPNAME` parameter description, units, and default.
 
+For a summary vector or array variant that derives from an `opm-common` keyword
+family — e.g. `WOPR` (from `WELL_PROBE`) or `KRNUMX` (from `KRNUM`) — the hover
+adds a *Deck-name alias of `<family>`* line, so you can see which keyword family
+the concrete name belongs to.
+
 Keywords on the diagnostics exclusion list (see `opm-flow.diagnostics.excludedKeywords`
 under [Settings](#settings)) carry an extra notice in the hover indicating that
 arity, terminator, and section checks are skipped — useful when squiggles are
@@ -383,6 +388,12 @@ The language is registered as `opm-flow`.
     supply the section header.
   - An indented unknown token under an active keyword is treated as record body
     rather than flagged as an unknown keyword.
+- **Deck-name alias resolution** — concrete summary vectors and directional
+  array variants now record which `opm-common` keyword family they derive from
+  (e.g. `WOPR` → `WELL_PROBE`, `KRNUMX` → `KRNUM`) and surface it in hover. The
+  31 family/container schema names themselves (`WELL_PROBE`,
+  `AQUIFER_PROBE_ANALYTIC`, `MULT_XYZ`, …) are no longer offered as completions
+  or accepted as valid keywords, since they are never typed in a deck.
 
 ### 0.8.0
 

vscode-extension/data/keyword_index_compact.json

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// Deck-name alias coverage on the shipped keyword index.
+//
+// opm-common models families of summary vectors / array variants under a
+// single schema name (WELL_PROBE, AQUIFER_PROBE_ANALYTIC, MULT_XYZ, …) whose
+// `deck_names` are the concrete keywords a user actually types (WOPR, AAQP,
+// MULTX). The build expands those into real index entries tagged with
+// `alias_of`, and suppresses the schema container names (which are never typed
+// in a deck) so they don't pollute completions or pass as valid keywords.
+//
+// These assertions guard the shipped `keyword_index_compact.json` against
+// regressions in that build step.
+// ---------------------------------------------------------------------------
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface CompactEntry {
+  name: string;
+  alias_of?: string;
+  [k: string]: unknown;
+}
+
+function loadIndex(): Record<string, CompactEntry> {
+  const p = path.join(__dirname, '..', 'data', 'keyword_index_compact.json');
+  return JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, CompactEntry>;
+}
+
+describe('deck-name alias coverage', () => {
+  const index = loadIndex();
+
+  it.each([
+    'WELL_PROBE',
+    'FIELD_PROBE',
+    'AQUIFER_PROBE_ANALYTIC',
+    'ENDPOINT_SPECIFIERS',
+    'MULT_XYZ',
+  ])('suppresses the opm-common family/container name %s', (container) => {
+    expect(index[container]).toBeUndefined();
+  });
+
+  it.each([
+    ['WOPR', 'WELL_PROBE'],
+    ['AAQP', 'AQUIFER_PROBE_ANALYTIC'],
+    ['MULTX', 'MULT_XYZ'],
+    ['KRNUMX', 'KRNUM'],
+  ])('tags %s as an alias of %s', (mnemonic, family) => {
+    expect(index[mnemonic]).toBeDefined();
+    expect(index[mnemonic].alias_of).toBe(family);
+  });
+
+  it('keeps real keywords that carry deck_names, untagged', () => {
+    for (const kw of ['KRNUM', 'IMBNUM', 'DIFF', 'NEXTSTEP']) {
+      expect(index[kw]).toBeDefined();
+      expect(index[kw].alias_of).toBeUndefined();
+    }
+  });
+
+  it('never marks a keyword as an alias of itself', () => {
+    for (const [name, entry] of Object.entries(index)) {
+      expect(entry.alias_of).not.toBe(name);
+    }
+  });
+
+  it('every alias target is itself a known keyword family (no dangling tags)', () => {
+    // The alias target is either a real keyword still in the index (KRNUM) or a
+    // suppressed family container — but it must never be the empty string.
+    for (const entry of Object.values(index)) {
+      if (entry.alias_of !== undefined) {
+        expect(typeof entry.alias_of).toBe('string');
+        expect(entry.alias_of.length).toBeGreaterThan(0);
+      }
+    }
+  });
+});

vscode-extension/src/alias.test.ts

@@ -69,6 +69,13 @@ interface KeywordEntry {
    * when the literal token isn't in the index.
    */
   templated?: boolean;
+  /**
+   * Deck-name alias: the opm-common family/keyword this mnemonic belongs to
+   * (WOPR -> WELL_PROBE, KRNUMX -> KRNUM). Surfaced in hover so the user sees
+   * which keyword family a concrete summary vector or directional variant
+   * derives from.
+   */
+  alias_of?: string;
 }
 
 type KeywordIndex = Record<string, KeywordEntry>;
@@ -594,6 +601,9 @@ function buildKeywordHover(
   const sectionLabel = entry.sections.length ? ` — ${entry.sections.join(', ')}` : '';
   md.appendMarkdown(`## \`${entry.name}\`${sectionLabel}\n\n`);
   if (entry.summary) md.appendMarkdown(`${entry.summary}\n\n`);
+  if (entry.alias_of) {
+    md.appendMarkdown(`*Deck-name alias of \`${entry.alias_of}\`.*\n\n`);
+  }
   appendParameterTable(md, entry.parameters, getDocColumns());
   if (entry.example) md.appendMarkdown(`**Example**\n\`\`\`\n${entry.example}\n\`\`\`\n`);
   return md;