@sap/cds-compiler 6.5.2 → 6.6.0

package/CHANGELOG.md

@@ -13,6 +13,32 @@ we might not list every change in its behavior here.
 Productive code should never require a `beta` flag to be set, and
 might use a deprecated flag only for a limited period of time.
 
+## Version 6.6.0 - 2025-12-12
+
+### Added
+
+- compiler:
+  + Support for upcoming ESlint rules (by other team) for Fiori elements annotations.
+  + Namespace `cds.dataproducts` is no longer reserved by the cds-compiler. It is used by the CAP @sap/cds-data-products plugin.
+- for.odata/to.edm(x):
+  + Enumeration symbols are now supported in annotation expression syntax.
+  + For projections and views, the `@hierarchy` annotation now triggers generation of
+    additional Fiori Tree View relevant annotations and fields.
+- for.effective: First non-beta release.
+
+### Changed
+
+- `to.sql`: Annotating a foreign key of an association in a view with a sql-snippet annotation (e.g. `@sql.append`)
+            now results in an error. This is the default behaviour for any element in a view.
+
+### Fixed
+
+- compiler:
+  + Minor fixes for auto-redirections and recompilation with localized data
+    in very rare situations when an aspect definition uses an entity as include.
+  + Don't let “namespaces” prevent the compiler to generate texts/target entities.
+- to.sql: Improve foreign key flattening for various edge cases.
+
 ## Version 6.5.2 - 2025-12-02
 
 ### Fixed

package/lib/api/main.js

@@ -321,9 +321,6 @@ function forSeal( csn, options, messageFunctions ) {
 function forEffective( csn, options, messageFunctions ) {
   const internalOptions = prepareOptions.for.effective(options);
   internalOptions.transformation = 'effective';
-  // for.effective is still beta mode
-  if (!baseModel.isBetaEnabled(options, 'effectiveCsn'))
-    throw new baseError.CompilerAssertion('effective CSN is only supported with beta flag `effectiveCsn`!');
 
   return forEffectiveInternal(csn, options, internalOptions, messageFunctions);
 }

package/lib/base/builtins.js

@@ -50,7 +50,8 @@ function isInReservedNamespace( absolute ) {
     !absolute.match( /^cds\.foundation(\.|$)/ ) &&
     !absolute.match( /^cds\.outbox(\.|$)/ ) && // Requested by Node runtime
     !absolute.match( /^cds\.core(\.|$)/ ) && // Requested by Node runtime
-    !absolute.match( /^cds\.xt(\.|$)/ ); // Requested by Mtx
+    !absolute.match( /^cds\.xt(\.|$)/ ) && // Requested by Mtx
+    !absolute.match( /^cds\.dataproducts(\.|$)/ ); // Requested by @sap/cds-data-products
 }
 
 /**

package/lib/base/message-registry.js

@@ -735,7 +735,6 @@ const centralMessageTexts = {
   },
   'ref-undefined-art': {
     std: 'No artifact has been found with name $(ART)',
-    namespace: 'No artifact has been found with name $(ART) which can be extended with annotations',
     localized: 'Can\'t extend localized definitions, only annotate them using an $(KEYWORD) statement',
   },
   // TODO: proposal 'No definition found for $(NAME)',

package/lib/base/model.js

@@ -24,7 +24,6 @@ const availableBetaFlags = {
   mapAssocToJoinCardinality: true, // only SAP HANA HEX engine supports it
   enableUniversalCsn: true,
   odataTerms: true,
-  effectiveCsn: true,
   tenantVariable: true,
   calcAssoc: true,
   temporalRawProjection: true,

package/lib/checks/sql-snippets.js

@@ -38,6 +38,14 @@ function checkSqlAnnotationOnElement( member, memberName, prop, path ) {
       checkValidAnnoValue(member, '@sql.append', path, this.error, this.options);
     }
   }
+
+  // recursive check for keys
+  if (member.keys) {
+    for (const keyName of Object.keys(member.keys)) {
+      const key = member.keys[keyName];
+      checkSqlAnnotationOnElement.call(this, key, keyName, prop, path.concat([ 'keys', keyName ]));
+    }
+  }
 }
 
 /**

package/lib/checks/validator.js

@@ -93,7 +93,6 @@ const forRelationalDBCsnValidators = [
   navigationIntoMany,
   checkPathsInStoredCalcElement,
   featureFlags,
-  checkAndRemoveEnums,
 ];
 /**
  * @type {Array<(query: CSN.Query, path: CSN.Path) => void>}
@@ -200,8 +199,11 @@ function _validate( csn, that,
 function getDBCsnValidators( options ) {
   const validations = [ ...forRelationalDBCsnValidators ];
 
-  if (options.transformation !== 'effective')
+  if (options.transformation !== 'effective') {
+    validations.push(checkAndRemoveEnums);
     validations.push(checkForParams.csnValidator);
+  }
+
   if (options.sqlDialect === 'h2' || options.sqlDialect === 'postgres')
     validations.push(checkForHanaTypes);
 

package/lib/compiler/define.js

@@ -528,7 +528,7 @@ function define( model ) {
     if (!reInit)                // not for auto-exposed entity
       initArtifactParentLink( art, model.definitions );
     checkRedefinition( art );
-    initDollarSelf( art );      // $self
+    initDollarSelf( art );      // $self, TODO: also for 'namespace'?
     initMembers( art );
     if (art.params)
       initDollarParameters( art ); // $parameters

package/lib/compiler/extend.js

@@ -78,6 +78,7 @@ function extend( model ) {
     extendArtifactBefore,
     extendArtifactAfter,
     extendForeignKeys,
+    withLocalizedData,
     applyIncludes,              // TODO: re-check
   } );
 
@@ -940,32 +941,28 @@ function extend( model ) {
   }
 
   function checkRemainingMainExtensions( art, ext ) {
-    const refCtx = ext.kind === 'annotate' && hasSecurityAnno( ext )
-      ? 'annotate-sec'
-      : ext.kind;
+    const refCtx = extensionRefContext( ext );
     if (!resolvePath( ext.name, refCtx, ext )) // error for extend, info for annotate
       return;
 
-    if (art?.builtin) {
+    if (art?.builtin) {                                       // TODO: do via accept
       info( 'anno-builtin', [ ext.name.location, ext ], {} ); // TODO: better location?
     }
-    else if (ext.kind === 'extend' && art?.kind === 'namespace') {
-      // `annotate` on namespaces already handled before
-      const hasAnnotations = Object.keys(ext).find(a => a.charAt(0) === '@');
-      const firstAnno = ext[hasAnnotations];
-      // In v5, extending namespaces is only allowed for `extend with definitions`.
-      // Neither annotations nor other extensions are allowed.
-      // Non-artifact extensions are reported in resolvePath() already (for v5).
-      // Because "namespaces" are the same as "unknown" artifacts in CSN, we don't report
-      // an error for `annotate`s.
-      // FIXME: The compiler generates empty `annotate` statements for
-      //        `extend ns with definitions {…}`. That's why we check the frontend.
-      if (hasAnnotations || (!ext.artifacts && ext._block.$frontend !== 'json')) {
-        error( 'ref-undefined-art', [ (firstAnno?.name || ext.name).location, ext ], {
-          '#': 'namespace', art: ext,
-        } );
-      }
+  }
+
+  function extensionRefContext( ext ) {
+    if (ext.kind === 'annotate') {
+      if (hasSecurityAnno( ext ))
+        return 'annotate-sec';
     }
+    else if (ext.artifacts ||   // extend … with definitions
+             ext._block.$frontend === 'json' && !ext.elements && !ext.actions) {
+      // TODO: not for `extend context` and `extend service` → !ext.expectedKind
+      // TODO v7: also fully with CSN input
+      if (!ext.doc && !Object.keys( ext ).some( a => a.charAt(0) === '@') )
+        return 'annotate';      // TODO: or an extra refCtx ?
+    }
+    return ext.kind;
   }
 
   // Issue messages for annotations on namespaces and builtins
@@ -1530,10 +1527,11 @@ function extend( model ) {
 
     if (!art._ancestors && !art.query)
       setLink( art, '_ancestors', [] ); // recursive array of includes
+    const shouldSetAncestors = art.kind === 'entity' && !art.query;
     for (const ref of ext.includes) {
       const template = resolvePath( ref, 'include', art );
       // !template -> non-includable, e.g. scalar type, or cyclic
-      if (template && !art.query) {
+      if (template?.kind === 'entity' && shouldSetAncestors) {
         if (template._ancestors)
           art._ancestors.push( ...template._ancestors );
         art._ancestors.push( template );
@@ -1581,8 +1579,17 @@ function extend( model ) {
         if (template[prop] && !ext[prop])
           ext[prop] = Object.create( null );
         const location = weakRefLocation( ref );
+
+        // prevent recompilation issue when localized entity is included in aspect or
+        // entity without keys (via shadowing):
+        const checkForLocalized = prop === 'elements' &&
+          template.kind === 'entity' && !template.query &&
+          withLocalizedData( template, ext );
+
         // eslint-disable-next-line no-loop-func
         forEachInOrder( template, prop, ( origin, name ) => {
+          if (checkForLocalized && (name === 'texts' || name === 'localized'))
+            return;
           if (members && members[name]) {
             if (!includesNonShadowedFirst && !ext[prop][name])
               dictAdd( ext[prop], name, members[name] ); // to keep order
@@ -1601,7 +1608,7 @@ function extend( model ) {
           if (origin.value && origin.$syntax === 'calc') {
             // TODO: If paths become invalid in the new artifact, should we mark
             //       all usages in the expressions? Possibly just the first one?
-            // TODO: Unify with coding in extend.js
+            // TODO: Unify with other code in extend.js
             elem.value = Object.assign( { $inferred: 'include' }, copyExpr( origin.value ));
             elem.$syntax = 'calc';
             createAndLinkCalcDepElement( elem );
@@ -1628,6 +1635,31 @@ function extend( model ) {
     }
   }
 
+  /**
+   * Return true if include (with `name` and `elements`) in `ext` highly likely
+   * contain elements `texts` and `localized` which are compiler-generated for
+   * localized data.  Due to recompilation, we cannot just check the `$inferred`
+   * property in the XSN, but need to apply an heuristics.
+   *
+   * It is as follows: the elements `texts` and `localized` in entity `‹E›` and
+   * the entity `‹E›.texts` are considered compiler-generated for Localized Data if
+   *
+   *  - `‹E›.texts` has a key element `locale`
+   *  - `texts` of `‹E›` is an unmanaged composition to `‹E›.texts`
+   *  - `localized` of `‹E›` is an unmanaged association to `‹E›.texts`
+   */
+  function withLocalizedData( { name, elements }, ext ) {
+    const textsEntityName = `${ name.id }.texts`;
+    if (!model.definitions[textsEntityName]?.elements?.locale?.key?.val)
+      return false;
+    const { texts, localized } = elements ?? {};
+    return texts?.target && localized?.target && texts.on && localized.on &&
+      resolveUncheckedPath( texts.target, 'target', ext ) === textsEntityName &&
+      resolveUncheckedPath( localized.target, 'target', ext ) === textsEntityName &&
+      resolveUncheckedPath( texts.type, 'type', ext ) === 'cds.Composition' &&
+      resolveUncheckedPath( localized.type, 'type', ext ) === 'cds.Association';
+  }
+
   /**
    * Report duplicates in parent[prop] that happen due to multiple includes having the
    * same member.  Covers `entity G : E, G {};` but not `entity G : E {};  extend G with F;`.

package/lib/compiler/generate.js

@@ -173,8 +173,8 @@ function generate( model ) {
     const localized = localizedData( art, textsEntity, fioriEnabled );
     if (!localized)
       return;
-    if (textsEntity)            // expanded localized data in source
-      return;                   // -> make it idempotent
+    if (textsEntity && textsEntity.kind !== 'namespace')
+      return;                 //  expanded texts entity in source -> nothing to do
     createTextsEntity( art, textsName, localized, fioriEnabled );
     addTextsAssociations( art, textsName, localized );
   }
@@ -236,7 +236,10 @@ function generate( model ) {
       return false;
     }
 
-    if (textsEntity) {
+    if (textsEntity?.kind === 'namespace') { // namespace Base.texts
+      textsEntity = null;
+    }
+    else if (textsEntity) {
       if (textsEntity.$duplicates)
         return false;
       if (textsEntity.kind !== 'entity' || textsEntity.query ||
@@ -283,15 +286,19 @@ function generate( model ) {
    */
   function createTextsEntity( base, absolute, textElems, fioriEnabled ) {
     const location = weakLocation( base.elements[$location] || base.location );
-    const art = {
+    let art = {
       kind: 'entity',
       name: { id: absolute, location },
       location,
       elements: Object.create( null ),
       $inferred: 'localized-entity',
     };
+    const gap = model.definitions[absolute];
+    if (gap)
+      art = Object.assign( gap, art );
+    else
+      model.definitions[absolute] = art;
     setLink( art, '_block', model.$internal );
-    model.definitions[absolute] = art;
     extendArtifactBefore( art ); // having extensions here would be wrong
 
     if (!fioriEnabled) {
@@ -341,6 +348,11 @@ function generate( model ) {
       addElementToTextsEntity( orig, art, fioriEnabled, assertUniqueValue );
 
     initMainArtifact( art );
+    // do the kick-start relevant stuff: _service, there are no _ancestors,
+    // _descendants would have been set already for a gap artifact
+    setLink( art, '_service', art._parent._service );
+    model.$compositionTargets[absolute] = true;
+
     if (art.includes) {
       // add elements `locale`, etc. which are required below.
       applyIncludes( art, art ); // TODO: rethink - can we avoid this if only new extend?
@@ -641,7 +653,8 @@ function generate( model ) {
              'An aspect $(TARGET) with an element named $(NAME) can\'t be used as target' );
       return false;
     }
-    if (model.definitions[entityName]) { // TODO: allow a gap (namespace)?
+    const place = model.definitions[entityName];
+    if (place && place.kind !== 'namespace') {
       error( null, [ location, elem ], { art: entityName },
              // eslint-disable-next-line @stylistic/max-len
              'Target entity $(ART) can\'t be created as there is another definition with this name' );
@@ -687,7 +700,7 @@ function generate( model ) {
       $inferred: 'aspect-composition',
     };
 
-    const art = {
+    let art = {
       kind: 'entity',
       name: {
         id: entityName,
@@ -698,6 +711,12 @@ function generate( model ) {
       elements: Object.create( null ),
       $inferred: 'composition-entity',
     };
+    const gap = model.definitions[entityName];
+    if (gap)
+      art = Object.assign( gap, art );
+    else
+      model.definitions[entityName] = art;
+
     if (target.name) {          // named target aspect
       if (!isDeprecatedEnabled( options, 'noCompositionIncludes' )) {
         art.includes = [ createInclude( target.name.id, location ) ];
@@ -741,9 +760,13 @@ function generate( model ) {
     addProxyElements( art, target.elements, 'aspect-composition', enforceLocation && location );
 
     setLink( art, '_block', model.$internal );
-    model.definitions[entityName] = art;
     initMainArtifact( art );
 
+    // do the kick-start relevant stuff: _service, there are no _ancestors,
+    // _descendants would have been set already for a gap artifact
+    setLink( art, '_service', art._parent._service );
+    model.$compositionTargets[entityName] = true;
+
     // Apply annotations to generated artifact, prepare (not apply!) element
     // annotations (remark: adding elements is not allowed for generated artifacts):
     extendArtifactBefore( art );

package/lib/compiler/index.js

@@ -495,8 +495,8 @@ function compileDoXSync( model ) {
     return model;
   }
   extend( model );
-  generate( model );
   kickStart( model );
+  generate( model );
   populate( model );
 
   model.definitions = model.$functions.shuffleDict( model.definitions );
@@ -546,7 +546,7 @@ async function compileDoX( model ) {
     return model;
   }
 
-  for (const phase of [ extend, generate, kickStart, populate ]) {
+  for (const phase of [ extend, kickStart, generate, populate ]) {
     phase( model );
     // eslint-disable-next-line no-await-in-loop
     await checkAsyncAbortFlag( options.abortSignal );

package/lib/compiler/kick-start.js

@@ -2,6 +2,7 @@
 
 'use strict';
 
+const { builtinLocation } = require('../base/location');
 const { isBetaEnabled, forEachGeneric } = require('../base/model');
 const {
   setLink,
@@ -14,14 +15,12 @@ function kickStart( model ) {
   const { options } = model;
   const { message } = model.$messageFunctions;
 
-  const { resolveUncheckedPath, resolvePath } = model.$functions;
+  const { resolveUncheckedPath, initMainArtifact } = model.$functions;
 
   // Set _service link (sorted to set it on parent first).  Could be set
   // directly, but beware a namespace becoming a service later.
   Object.keys( model.definitions ).sort().forEach( setAncestorsAndService );
   forEachGeneric( model, 'definitions', postProcessArtifact );
-
-  forEachGeneric( model, 'sources', resolveUsings );
   return;
 
 
@@ -85,7 +84,7 @@ function kickStart( model ) {
       chain.push( art );
       setLink( art, '_ancestors', 0 ); // avoid infloop with cyclic from
       const name = resolveUncheckedPath( art.query.from, 'from', art );
-      art = name && model.definitions[name];
+      art = name && (model.definitions[name] || createGapArtifact( name ));
       if (autoexposed)
         break;                  // only direct projection for auto-exposed
     }
@@ -98,6 +97,18 @@ function kickStart( model ) {
     }
   }
 
+  function createGapArtifact( name, location = builtinLocation() ) {
+    // TODO: make it probably part of define.js
+    // TODO: make it work without location (or value undefined/null)
+    // TODO: change the location later if overwritten
+    const art = {
+      kind: 'namespace', name: { id: name, location }, location,
+    };
+    model.definitions[name] = art;
+    initMainArtifact( art );
+    return art;
+  }
+
   function postProcessArtifact( art ) {
     tagCompositionTargets( art );
     if (art.$queries) {
@@ -128,40 +139,19 @@ function kickStart( model ) {
   }
 
   function tagCompositionTargets( elem ) {
+    // TODO: together with test for targetIsTargetAspect()
     if (elem.target && isDirectComposition( elem )) {
       // A target aspect would have already moved to property `targetAspect` in
       // define.js (hm... more something for kick-start.js...)
       // TODO: for safety, just use resolveUncheckedPath()
-      const target = resolvePath( elem.target, 'target', elem );
+      const target = resolveUncheckedPath( elem.target, 'target', elem );
       if (target)
-        model.$compositionTargets[target.name.id] = true;
+        model.$compositionTargets[target] = true;
     }
     if (elem.targetAspect?.elements)
       elem = elem.targetAspect;
     forEachGeneric( elem, 'elements', tagCompositionTargets );
   }
-
-  // Resolve the using declarations in `using`.  Issue
-  // error message if the referenced artifact does not exist.
-  // TODO: think of moving this to resolve.js
-  function resolveUsings( src, topLevel ) {
-    if (!src.usings)
-      return;
-    for (const def of src.usings) {
-      if (def.usings)           // using {...}
-        resolveUsings( def );
-      if (!def.name || !def.name.id)
-        continue;               // using {...}, parse error
-      const art = model.definitions[def.name.absolute];
-      if (art && art.$duplicates)
-        continue;
-      const ref = def.extern;
-      const user = (topLevel ? def : src);
-      const from = user.fileDep;
-      if (art || !from || from.realname)   // no error for non-existing ref with non-existing module
-        resolvePath( ref, 'using', def ); // TODO: consider FROM for validNames
-    }
-  }
 }
 
 module.exports = kickStart;

package/lib/compiler/propagator.js

@@ -47,7 +47,7 @@ function propagate( model ) {
     precision: always,
     scale: always,
     srid: always,
-    localized: withKind,
+    localized,
     target: notWithExpand,
     targetAspect,
     cardinality: notWithExpand,
@@ -78,6 +78,7 @@ function propagate( model ) {
   const { rewriteAnnotationsRefs, rewriteRefsInExpression } = xprRewriteFns( model );
 
   const { message, throwWithError } = model.$messageFunctions;
+  const { withLocalizedData } = model.$functions;
 
   forEachDefinition( model, run );
   forEachGeneric( model, 'vocabularies', run );
@@ -336,6 +337,24 @@ function propagate( model ) {
       annotation( prop, target, source );
   }
 
+  /**
+   * Propagate `localized`, but not for a texts entity
+   * (as `null` in an Universal CSN).
+   */
+  function localized( prop, target, source ) {
+    const main = target._main;
+    if (target.kind === 'element' && main.kind === 'entity' && !main.query) {
+      const { id } = main.name;
+      const base = id.endsWith( '.texts' ) &&
+        model.definitions[id.slice( 0, -'.texts'.length )];
+      if (base && withLocalizedData( base, main )) {
+        target.localized = { $inferred: 'NULL', val: undefined }; // null in UCSN
+        return;
+      }
+    }
+    withKind( prop, target, source );
+  }
+
   function withKind( prop, target, source ) {
     if (target.kind === 'param' && source.kind === 'entity')
       return; // Don't propagate from entity types to parameters (+ return type).

package/lib/compiler/resolve.js

@@ -108,8 +108,32 @@ function resolve( model ) {
   const ignoreSpecifiedElements
     = isDeprecatedEnabled( options, 'ignoreSpecifiedQueryElements' );
 
+  forEachGeneric( model, 'sources', resolveUsings );
   return doResolve();
 
+  /**
+   * Resolve the using declarations in `using`.
+   * Issue error message if the referenced artifact does not exist.
+   */
+  function resolveUsings( src, topLevel ) {
+    if (!src.usings)
+      return;
+    for (const def of src.usings) {
+      if (def.usings)           // using {...}
+        resolveUsings( def );
+      if (!def.name || !def.name.id)
+        continue;               // using {...}, parse error
+      const art = model.definitions[def.name.absolute];
+      if (art && art.$duplicates)
+        continue;
+      const ref = def.extern;
+      const user = (topLevel ? def : src);
+      const from = user.fileDep;
+      if (art || !from || from.realname)   // no error for non-existing ref with non-existing module
+        resolvePath( ref, 'using', def ); // TODO: consider FROM for validNames
+    }
+  }
+
   function doResolve() {
     // Phase 1: check paths in `usings` has been moved to kick-start.js Phase 2:
     // calculate/init view elements & collect views in order:

package/lib/compiler/shared.js

@@ -846,6 +846,8 @@ function fns( model ) {
 
     if (!semantics.dollar) {
       valid.push( dynamicDict );
+      if (isMainRef)            // eslint-disable-next-line no-return-assign
+        valid.forEach( ( d, idx ) => (valid[idx] = removeGapArtifact( d )) );
     }
     else {
       const filterFn = semantics.variableFilter || removeRestrictedVariables;
@@ -908,14 +910,22 @@ function fns( model ) {
       }
       // need to do that here, because we also need to disallow Service.AutoExposed:elem
       // TODO: but Service.AutoExposed.NotAuto should be fine
-      if (isMainRef !== 'all' && artItemsCount === 0 &&
-          art.$inferred === 'autoexposed' && !user.$inferred) {
-        // Depending on the processing sequence, the following could be a
-        // simple 'ref-undefined-art'/'ref-undefined-def' - TODO: which we
-        // could "change" to this message at the end of compile():
-        error( 'ref-unexpected-autoexposed', [ item.location, user ], { art },
-               'An auto-exposed entity can\'t be referred to - expose entity $(ART) explicitly' );
-        return null;            // continuation semantics: like “not found”
+      if (isMainRef && isMainRef !== 'all' && artItemsCount === 0) {
+        if (art.kind === 'namespace') {
+          if (env !== false) {
+            semantics.notFound( user, item, [ removeGapArtifact( env ) ],
+                                null, prev, path, semantics );
+          }
+          return null;
+        }
+        else if (art.$inferred === 'autoexposed' && !user.$inferred) {
+          // Depending on the processing sequence, the following could be a
+          // simple 'ref-undefined-art'/'ref-undefined-def' - TODO: which we
+          // could "change" to this message at the end of compile():
+          error( 'ref-unexpected-autoexposed', [ item.location, user ], { art },
+                 'An auto-exposed entity can\'t be referred to - expose entity $(ART) explicitly' );
+          return null;            // continuation semantics: like “not found”
+        }
       }
     }
     return art;
@@ -978,7 +988,25 @@ function fns( model ) {
           return def;
         if (def.$duplicates)
           return false;
-        return setArtifactLink( head, def ); // we do not want to see the using
+        art = setArtifactLink( head, def ); // we do not want to see the using
+        if (art.kind !== 'namespace')
+          return art;
+      }
+      /* FALLTHROUGH */
+      case 'namespace': {
+        if (semantics.isMainRef === 'all' || path.length !== 1 && ref.scope !== 1)
+          return art;
+        const valid = [];
+        const lexical = userBlock( user );
+        if (lexical) {
+          for (let env = lexical; env; env = env._block)
+            valid.push( removeGapArtifact( env.artifacts || Object.create( null ) ) );
+        }
+        valid.push( removeGapArtifact( model.definitions ) );
+        semantics.notFound?.( user._user || user, head, valid, model.definitions,
+                              null, path, semantics );
+
+        return null;
       }
       case 'mixin': {
         // use a source element having that name if in `extend … with columns`:
@@ -2153,6 +2181,18 @@ function removeDollarNames( dict ) {
   return r;
 }
 
+function removeGapArtifact( dict ) {
+  const r = Object.create( null );
+  for (const name in dict) {
+    const art = dict[name];
+    // TODO: for gaps with sub artifacts, we use use `${name}.` as name
+    // TODO: clarify with LSP
+    if (art.kind !== 'namespace' || art._subArtifacts)
+      r[name] = dict[name];
+  }
+  return r;
+}
+
 module.exports = {
   fns,
 };

package/lib/compiler/utils.js

@@ -206,6 +206,7 @@ function initExprAnnoBlock( art, block ) {
 
 function initDollarSelf( art ) {
   // TODO: use setMemberParent() ?
+  // TODO: also on 'namespace's?  (test with annotation with checked ref on them)
   const self = {
     name: { id: '$self', location: art.location },
     kind: '$self',