@sap/cds-compiler 3.0.0 → 3.0.2

package/lib/optionProcessor.js

@@ -19,10 +19,7 @@ optionProcessor
   .option('    --color <mode>', ['auto', 'always', 'never'])
   .option('-o, --out <dir>')
   .option('    --cds-home <dir>')
-  .option('    --lint-mode')
   .option('    --fuzzy-csn-error')
-  .option('    --trace-parser')
-  .option('    --trace-parser-amb')
   .option('    --trace-fs')
   .option('    --error <id-list>')
   .option('    --warn <id-list>')
@@ -35,7 +32,6 @@ optionProcessor
   .option('    --beta <list>')
   .option('    --deprecated <list>')
   .option('    --direct-backend')
-  .option('    --parse-only')
   .option('    --fallback-parser <type>', ['cdl', 'csn', 'csn!'])
   .option('    --test-mode')
   .option('    --test-sort-csn')
@@ -78,7 +74,6 @@ optionProcessor
                               never:
    -o, --out <dir>          Place generated files in directory <dir>, default is "-" for <stdout>
        --cds-home <dir>     When set, modules starting with '@sap/cds/' are searched in <dir>
-       --lint-mode          Generate nothing, just produce messages if any (for use by editors)
        --fuzzy-csn-error    Report free-style CSN properties as errors
        --                   Indicate the end of options (helpful if source names start with "-")
 
@@ -87,8 +82,6 @@ optionProcessor
        --default-string-length <length> Default 'length' for 'cds.String'
 
   Diagnostic options
-       --trace-parser       Trace parser
-       --trace-parser-amb   Trace parser ambiguities
        --trace-fs           Trace file system access caused by "using from"
 
   Severity options
@@ -112,7 +105,6 @@ optionProcessor
        --deprecated <list>  Comma separated list of deprecated options.
                             Valid values are:
                               eagerPersistenceForGeneratedEntities
-       --parse-only         Stop compilation after parsing and write result to <stdout>
        --fallback-parser <type>  If the language cannot be deduced by the file's extensions, use this
                                  parser as a fallback. Valid values are:
                                    cdl  : Use CDL parser
@@ -141,6 +133,8 @@ optionProcessor
        toCsn [options] <files...>               (default) Generate original model as CSN
        parseCdl [options] <file>                Generate a CSN that is close to the CDL source.
        explain <message-id>                     Explain a compiler message.
+       parseOnly [options] <files...>           (internal)  Stop compilation after parsing, write messages to <stderr>,
+                                                per default no output.
        toRename [options] <files...>            (internal) Generate SQL DDL rename statements
        manageConstraints [options] <files...>   (internal) Generate ALTER TABLE statements to
                                                            add / modify referential constraints.
@@ -149,7 +143,7 @@ optionProcessor
 // ----------- toHana -----------
 optionProcessor.command('H, toHana')
   .option('-h, --help')
-  .option('-n, --names <style>', ['plain', 'quoted', 'hdbcds'])
+  .option('-n, --sql-mapping <style>', ['plain', 'quoted', 'hdbcds'], { aliases: ['--names'] })
   .option('    --render-virtual')
   .option('    --joinfk')
   .option('-u, --user <user>')
@@ -166,7 +160,7 @@ optionProcessor.command('H, toHana')
 
   Options
    -h, --help                 Show this help text
-   -n, --names <style>        Naming style for generated entity and element names:
+   -n, --sql-mapping <style>  Naming style for generated entity and element names:
                                 plain  : (default) Produce HANA entity and element names in
                                          uppercase and flattened with underscores. Do not generate
                                          structured types.
@@ -197,7 +191,7 @@ optionProcessor.command('H, toHana')
 
 optionProcessor.command('O, toOdata')
   .option('-h, --help')
-  .option('-v, --odata-version <version>', ['v2', 'v4', 'v4x'])
+  .option('-v, --odata-version <version>', ['v2', 'v4', 'v4x'], { aliases: ['--version'] })
   .option('-x, --xml')
   .option('-j, --json')
   .option('    --odata-containment')
@@ -207,7 +201,7 @@ optionProcessor.command('O, toOdata')
   .option('    --odata-v2-partial-constr')
   .option('-c, --csn')
   .option('-f, --odata-format <format>', ['flat', 'structured'])
-  .option('-n, --names <style>', ['plain', 'quoted', 'hdbcds'])
+  .option('-n, --sql-mapping <style>', ['plain', 'quoted', 'hdbcds'], { aliases: [ '--names' ] })
   .option('-s, --service-names <list>')
   .help(`
   Usage: cdsc toOdata [options] <files...>
@@ -232,13 +226,13 @@ optionProcessor.command('O, toOdata')
        --odata-foreign-keys        Render foreign keys in structured format (V4 only)
        --odata-v2-partial-constr   Render referential constraints also for partial principal key tuple
                                    (Not spec compliant and V2 only)
-   -n, --names <style>      Annotate artifacts and elements with "@cds.persistence.name", which is
-                            the corresponding database name (see "--names" for "toHana or "toSql")
-                              plain   : (default) Names in uppercase and flattened with underscores
-                              quoted  : Names in original case as in CDL. Entity names with dots,
-                                        but element names flattened with underscores
-                              hdbcds  : Names as HANA CDS would generate them from the same CDS
-                                        source (like "quoted", but using element names with dots)
+   -n, --sql-mapping <style> Annotate artifacts and elements with "@cds.persistence.name", which is
+                             the corresponding database name (see "--sql-mapping" for "toHana or "toSql")
+                               plain   : (default) Names in uppercase and flattened with underscores
+                               quoted  : Names in original case as in CDL. Entity names with dots,
+                                         but element names flattened with underscores
+                               hdbcds  : Names as HANA CDS would generate them from the same CDS
+                                         source (like "quoted", but using element names with dots)
     -s, --service-names <list>    List of comma-separated service names to be rendered
                                   (default) empty, all services are rendered
 `);
@@ -256,10 +250,10 @@ optionProcessor.command('C, toCdl')
 
 optionProcessor.command('Q, toSql')
   .option('-h, --help')
-  .option('-n, --names <style>', ['plain', 'quoted', 'hdbcds'])
+  .option('-n, --sql-mapping <style>', ['plain', 'quoted', 'hdbcds'], { aliases: [ '--names' ] })
+  .option('-d, --sql-dialect <dialect>',  ['hana', 'sqlite', 'plain', 'postgres'], { aliases: [ '--dialect' ] })
   .option('    --render-virtual')
   .option('    --joinfk')
-  .option('-d, --dialect <dialect>', ['hana', 'sqlite', 'plain', 'postgres'])
   .option('-u, --user <user>')
   .option('-l, --locale <locale>')
   .option('-s, --src <style>', ['sql', 'hdi'])
@@ -276,7 +270,7 @@ optionProcessor.command('Q, toSql')
 
   Options
    -h, --help                 Show this help text
-   -n, --names <style>        Naming style for generated entity and element names:
+   -n, --sql-mapping <style>  Naming style for generated entity and element names:
                                 plain  : (default) Produce SQL table and view names in
                                          flattened with underscores format (no quotes required)
                                 quoted : Produce SQL table and view names in original case as in
@@ -289,7 +283,7 @@ optionProcessor.command('Q, toSql')
                                          combination with "hana" dialect.
        --render-virtual       Render virtual elements in views and draft tables
        --joinfk               Create JOINs for foreign key accesses
-   -d, --dialect <dialect>    SQL dialect to be generated:
+   -d, --sql-dialect <dialect>  SQL dialect to be generated:
                                 plain    : (default) Common SQL - no assumptions about DB restrictions
                                 hana     : SQL with HANA specific language features
                                 sqlite   : Common SQL for sqlite
@@ -320,28 +314,29 @@ optionProcessor.command('Q, toSql')
 
 optionProcessor.command('toRename')
   .option('-h, --help')
-  .option('-n, --names <style>', ['quoted', 'hdbcds'])
+  .option('-n, --sql-mapping <style>', ['quoted', 'hdbcds'], { aliases: ['--names'] })
   .help(`
   Usage: cdsc toRename [options] <files...>
 
   (internal, subject to change): Generate SQL stored procedure containing DDL statements to
   "storedProcedure.sql" that allows to rename existing tables and their columns so that they
-  match the result of "toHana" or "toSql" with the "--names plain" option.
+  match the result of "toHana" or "toSql" with the "--sql-mapping plain" option.
 
   Options
    -h, --help           Display this help text
-   -n, --names <style>  Assume existing tables were generated with "--names <style>":
+   -n, --sql-mapping <style>
+                        Assume existing tables were generated with "--sql-mapping <style>":
                           quoted   : Assume existing SQL tables and views were named in original
                                      case as in CDL (with dots), but column names were flattened
-                                     with underscores (e.g. resulting from "toHana --names quoted")
+                                     with underscores (e.g. resulting from "toHana --sql-mapping quoted")
                           hdbcds   : (default) Assume existing SQL tables, views and columns were
                                      generated by HANA CDS from the same CDS source (or resulting
-                                     from "toHana --names hdbcds")
+                                     from "toHana --sql-mapping hdbcds")
 `);
 
 optionProcessor.command('manageConstraints')
   .option('-h, --help')
-  .option('-n, --names <style>', ['plain', 'quoted', 'hdbcds'])
+  .option('-n, --sql-mapping <style>', ['plain', 'quoted', 'hdbcds'], { aliases: ['--names'] })
   .option('-s, --src <style>', ['sql', 'hdi'])
   .option('    --drop')
   .option('    --alter')
@@ -357,7 +352,8 @@ optionProcessor.command('manageConstraints')
 
   Options
    -h, --help             Display this help text
-   -n, --names <style>    Assume existing tables were generated with "--names <style>":
+   -n, --sql-mapping <style>
+                          Assume existing tables were generated with "--sql-mapping <style>":
                             plain    : (default) Assume SQL tables were flattened and dots were
                                         replaced by underscores
                             quoted   : Assume existing SQL tables and views were named in original
@@ -379,7 +375,7 @@ optionProcessor.command('manageConstraints')
 
 optionProcessor.command('toCsn')
   .option('-h, --help')
-  .option('-f, --flavor <flavor>', ['client', 'gensrc', 'universal'])
+  .option('-f, --csn-flavor <flavor>', ['client', 'gensrc', 'universal'], { aliases: ['--flavor'] })
   .option('    --with-localized')
   .help(`
   Usage: cdsc toCsn [options] <files...>
@@ -388,13 +384,13 @@ optionProcessor.command('toCsn')
 
   Options
    -h, --help             Show this help text
-   -f, --flavor <flavor>  Generate CSN in one of two flavors:
-                            client  : (default) Standard CSN consumable by clients and backends
-                            gensrc  : CSN specifically for use as a source, e.g. for
-                                      combination with additional "extend" or "annotate"
-                                      statements, but not suitable for consumption by clients or
-                                      backends
-                            universal: in development (BETA)
+   -f, --csn-flavor <flavor>  Generate CSN in one of two flavors:
+                                client  : (default) Standard CSN consumable by clients and backends
+                                gensrc  : CSN specifically for use as a source, e.g. for
+                                          combination with additional "extend" or "annotate"
+                                          statements, but not suitable for consumption by clients or
+                                          backends
+                                universal: in development (BETA)
 
   Internal options (for testing only, may be changed/removed at any time)
        --with-localized   Add localized convenience views to the CSN output.
@@ -413,6 +409,26 @@ optionProcessor.command('parseCdl')
    -h, --help             Show this help text
 `);
 
+optionProcessor.command('parseOnly')
+  .option('-h, --help')
+  .option('    --trace-parser')
+  .option('    --trace-parser-amb')
+  .positionalArgument('<file>')
+  .help(`
+  Usage: cdsc parseOnly [options] <files...>
+
+  (internal): Stop compilation after parsing and write messages to <stderr>.
+  Per default, nothing is printed.  With \`--raw-output +\`, XSN is printed
+  to <stdout>.
+
+  Options
+   -h, --help               Show this help text
+
+  Diagnostic options
+       --trace-parser       Trace parser
+       --trace-parser-amb   Trace parser ambiguities
+`);
+
 optionProcessor.command('explain')
   .option('-h, --help')
   .positionalArgument('<message-id>')

package/lib/render/toHdbcds.js

@@ -839,7 +839,7 @@ function toHdbcdsSource(csn, options) {
    * @param {object} [elements] For leading query, the elements of the artifact
    * @returns {string} The rendered query
    */
-  function renderQuery(query, isLeadingQuery, env, path = [], elements) {
+  function renderQuery(query, isLeadingQuery, env, path = [], elements = null) {
     let result = '';
     env.skipKeys = !isLeadingQuery;
     // Set operator, like UNION, INTERSECT, ...

package/lib/render/toSql.js

@@ -117,6 +117,9 @@ function toSqlDdl(csn, options) {
      */
     addColumns: {
       fromElementStrings(tableName, eltStrings) {
+        if (options.sqlDialect === 'sqlite') // SQLite can only alter one column at a time
+          return eltStrings.map(eltString => `ALTER TABLE ${tableName} ADD ${eltString};`);
+
         const elts = options.sqlDialect === 'hana' ? `(${eltStrings.join(', ')})` : `${eltStrings.join(', ')}`;
         return [ `ALTER TABLE ${tableName} ADD ${elts};` ];
       },
@@ -138,10 +141,10 @@ function toSqlDdl(csn, options) {
       TODO duplicity check
      */
     addAssociations(artifactName, tableName, elementsObj, env) {
-      return Object.entries(elementsObj)
+      return options.sqlDialect === 'hana' ? Object.entries(elementsObj)
         .map(([ name, elt ]) => renderAssociationElement(name, elt, env))
         .filter(s => s !== '')
-        .map(eltStr => `ALTER TABLE ${tableName} ADD ASSOCIATION (${eltStr});`);
+        .map(eltStr => `ALTER TABLE ${tableName} ADD ASSOCIATION (${eltStr});`) : [];
     },
     /*
       Render key addition as HANA SQL.
@@ -159,7 +162,7 @@ function toSqlDdl(csn, options) {
       Render association removals as HANA SQL.
      */
     dropAssociation(tableName, sqlId) {
-      return [ `ALTER TABLE ${tableName} DROP ASSOCIATION ${sqlId};` ];
+      return options.sqlDialect === 'hana' ? [ `ALTER TABLE ${tableName} DROP ASSOCIATION ${sqlId};` ] : [];
     },
     /*
       Render primary-key removals as HANA SQL.
@@ -1492,6 +1495,7 @@ function toSqlDdl(csn, options) {
       }
       else if (x.ref[0] === '$now') { // TODO: Can there be cases where $now is followed by something?
         switch (options.sqlDialect) {
+          case 'plain':
           case 'sqlite':
           case 'hana':
             return 'CURRENT_TIMESTAMP';

package/lib/transform/forOdataNew.js

@@ -120,7 +120,7 @@ function transform4odataWithCsn(inputModel, options) {
     return keepLocalizedViews && !isExternalServiceMember(undefined, parent);
   }
 
-  addLocalizationViews(csn, options, acceptLocalizedView);
+  addLocalizationViews(csn, options, { acceptLocalizedView, ignoreUnknownExtensions: true });
 
   const cleanup = validate.forOdata(csn, {
     message, error, warning, info, inspectRef, effectiveType, artifactRef, csn, options, csnUtils, services, isAspect, isExternalServiceMember
@@ -324,7 +324,7 @@ function transform4odataWithCsn(inputModel, options) {
       // but '@Core.Immutable' for everything else.
       if (!(node['@readonly'] && node['@insertonly'])) {
         if (name === '@readonly' && node[name] !== null) {
-          if (node.kind === 'entity') {
+          if (node.kind === 'entity' || node.kind === 'aspect') {
             setAnnotation(node, '@Capabilities.DeleteRestrictions.Deletable', false);
             setAnnotation(node, '@Capabilities.InsertRestrictions.Insertable', false);
             setAnnotation(node, '@Capabilities.UpdateRestrictions.Updatable', false);
@@ -334,7 +334,7 @@ function transform4odataWithCsn(inputModel, options) {
         }
         // @insertonly is effective on entities/queries only
         else if (name === '@insertonly' && node[name] !== null) {
-          if (node.kind === 'entity') {
+          if (node.kind === 'entity' || node.kind === 'aspect') {
             setAnnotation(node, '@Capabilities.DeleteRestrictions.Deletable', false);
             setAnnotation(node, '@Capabilities.ReadRestrictions.Readable', false);
             setAnnotation(node, '@Capabilities.UpdateRestrictions.Updatable', false);

package/lib/transform/localized.js

@@ -69,10 +69,9 @@ const _targetFor = Symbol('_targetFor');
  * @param {CSN.Options} options
  * @param {boolean} useJoins If true, rewrite the "localized" association to a
  *                           join in direct convenience views.
- * @param {acceptLocalizedView} [acceptLocalizedView] optional callback function returning true if the localized view
- *                                                    name and its parent name provided as parameter should be created
+ * @param {object} config
  */
-function _addLocalizationViews(csn, options, useJoins, acceptLocalizedView = null) {
+function _addLocalizationViews(csn, options, useJoins, config) {
   // Don't try to create convenience views with errors.
   if (hasErrors(options.messages))
     return csn;
@@ -81,6 +80,7 @@ function _addLocalizationViews(csn, options, useJoins, acceptLocalizedView = nul
   if (hasExistingLocalizationViews(csn, options, messageFunctions))
     return csn;
 
+  const { acceptLocalizedView, ignoreUnknownExtensions } = config;
   const noCoalesce = (options.localizedLanguageFallback === 'none' ||
                       options.localizedWithoutCoalesce);
 
@@ -91,8 +91,12 @@ function _addLocalizationViews(csn, options, useJoins, acceptLocalizedView = nul
 
   // In case that the user tried to annotate `localized.*` artifacts, apply them.
   applyAnnotationsFromExtensions(csn, {
-    overwrite: true,
-    filter: (name) => name.startsWith('localized.')
+    override: true,
+    filter: (name) => name.startsWith('localized.'),
+    notFound(name, index) {
+      if (!ignoreUnknownExtensions)
+        messageFunctions.message('anno-undefined-art', [ 'extensions', index ], { name })
+    },
   });
 
   sortCsnDefinitionsForTests(csn, options);
@@ -608,10 +612,10 @@ function _addLocalizationViews(csn, options, useJoins, acceptLocalizedView = nul
  *
  * @param {CSN.Model} csn
  * @param {CSN.Options} options
- * @param [acceptLocalizedView] optional callback function returning true if the localized view name and its parent name provided as parameter should be created
+ * @param [config] config.acceptLocalizedView: optional callback function returning true if the localized view name and its parent name provided as parameter should be created
  */
-function addLocalizationViews(csn, options, acceptLocalizedView = null) {
-  return _addLocalizationViews(csn, options, false, acceptLocalizedView);
+function addLocalizationViews(csn, options, config = {}) {
+  return _addLocalizationViews(csn, options, false, config);
 }
 
 /**
@@ -621,10 +625,10 @@ function addLocalizationViews(csn, options, acceptLocalizedView = null) {
  *
  * @param {CSN.Model} csn
  * @param {CSN.Options} options
- * @param [acceptLocalizedView] optional callback function returning true if the localized view name and its parent name provided as parameter should be created
+ * @param [config] config.acceptLocalizedView: optional callback function returning true if the localized view name and its parent name provided as parameter should be created
  */
-function addLocalizationViewsWithJoins(csn, options, acceptLocalizedView = null) {
-  return _addLocalizationViews(csn, options, true, acceptLocalizedView);
+function addLocalizationViewsWithJoins(csn, options, config = {}) {
+  return _addLocalizationViews(csn, options, true, config);
 }
 
 /**

package/lib/utils/file.js

@@ -113,11 +113,16 @@ function cdsFs(fileCache, enableTrace) {
         traceFS( 'READFILE:start:', filename );
         // TODO: set cache directly to some "delay" - store error differently?
         // e.g. an error of callback functions!
-        reader(filename, enc, ( err, data ) => {
-          fileCache[filename] = err || data;
-          traceFS( 'READFILE:data:', filename, err || data );
-          cb( err, data );
-        });
+        try {
+          reader(filename, enc, (err, data) => {
+            fileCache[filename] = err || data;
+            traceFS('READFILE:data:', filename, err || data);
+            cb(err, data);
+          });
+        }
+        catch (err) {
+          cb(err); // if filename is not a valid (e.g. contains NUL byte), readFile() may throw
+        }
       }
     };
   }
@@ -143,19 +148,24 @@ function cdsFs(fileCache, enableTrace) {
         // in the future (if we do module resolve ourself with just readFile),
         // we avoid parallel readFile by storing having an array of `cb`s in
         // fileCache[ filename ] before starting fs.readFile().
-        fsStat( filename, ( err, stat ) => {
-          if (err)
-            body = (err.code === 'ENOENT' || err.code === 'ENOTDIR') ? false : err;
-          else
-            body = !!(stat.isFile() || stat.isFIFO());
-          if (fileCache[filename] === undefined) // parallel readFile() has been processed
-            fileCache[filename] = body;
-          traceFS( 'ISFILE:data:', filename, body );
-          if (body instanceof Error)
-            cb( err );
-          else
-            cb( null, body );
-        });
+        try {
+          fsStat(filename, (err, stat) => {
+            if (err)
+              body = (err.code === 'ENOENT' || err.code === 'ENOTDIR') ? false : err;
+            else
+              body = !!(stat.isFile() || stat.isFIFO());
+            if (fileCache[filename] === undefined) // parallel readFile() has been processed
+              fileCache[filename] = body;
+            traceFS('ISFILE:data:', filename, body);
+            if (body instanceof Error)
+              cb(err);
+            else
+              cb(null, body);
+          });
+        }
+        catch (err) {
+          cb(err); // if filename is not a valid (e.g. contains NUL byte), fsStat() may throw
+        }
       }
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sap/cds-compiler",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "CDS (Core Data Services) compiler and backends",
   "homepage": "https://cap.cloud.sap/",
   "author": "SAP SE (https://www.sap.com)",
@@ -19,9 +19,8 @@
     "xmakeBeforeInstall": "echo \"Due to binary mirror, use sqlite 5.0.8 explicitly\" && npm install --save --save-exact --no-package-lock sqlite3@5.0.8",
     "xmakeAfterInstall": "npm run gen",
     "xmakePrepareRelease": "echo \"$(node scripts/stripReadme.js README.md)\" > README.md && node scripts/assertSnapshotVersioning.js && node scripts/assertChangelog.js && node scripts/cleanup.js --remove-dev",
-    "test": "node scripts/verifyGrammarChecksum.js && mocha --parallel --reporter min --reporter-option maxDiffSize=0 test/ test3/ && mocha scripts/testLazyLoading.js",
+    "test": "node scripts/verifyGrammarChecksum.js && mocha --reporter min --reporter-option maxDiffSize=0 scripts/testLazyLoading.js && mocha --parallel --reporter min --reporter-option maxDiffSize=0 test/ test3/",
     "testverbose": "node scripts/verifyGrammarChecksum.js && mocha --parallel test/ test3/",
-    "testdot": "node scripts/verifyGrammarChecksum.js && mocha --parallel --reporter dot --reporter-option maxDiffSize=0 --full-trace scripts/linter/lintMessages.js test/ test3/",
     "test3": "node scripts/verifyGrammarChecksum.js && node scripts/linter/lintTests.js test3/ && mocha --reporter-option maxDiffSize=0 scripts/linter/lintMessages.js test3/",
     "deployTest3SQL": "deployRefs=true mocha --reporter-option maxDiffSize=0 test3/testHANASQLDeployment.js",
     "deployTest3": "deployRefs=true mocha --reporter-option maxDiffSize=0 test3/testDeployment.js",

package/share/messages/syntax-expected-integer.md

@@ -1,12 +1,12 @@
 # syntax-expected-integer
 
 The compiler expects a safe integer here.
-The last safe Integer is `2^53 - 1` or `9007199254740991`.
+The last safe integer is `2^53 - 1` or `9007199254740991`.
 
-A safe integer is an integer that
+A safe integer is an integer that fulfills all of the following:
 
-- can be exactly represented as an IEEE-754 double precision number, and
-- whose IEEE-754 representation cannot be the result of rounding any
+- Can be exactly represented as an IEEE-754 double precision number.
+- The IEEE-754 representation cannot be the result of rounding any
   other integer to fit the IEEE-754 representation.
 
 The message's severity is `Error`.
@@ -15,13 +15,14 @@ The message's severity is `Error`.
 
 Erroneous code example:
 
+<!-- cds-mode: ignore -->
 ```cdl
 type LengthIsUnsafe : String(9007199254740992);
 type NotAnInteger : String(42.1);
 ```
 
-In the above example, the string length for the type `LengthIsUnsafe` is not a
-safe Integer. It is too large.
+In the erroneous example, the string length for the type `LengthIsUnsafe` is
+not a safe integer. It is too large.
 Likewise, the string length for the type `NotAnInteger` is a decimal.
 
 ## How to Fix
@@ -33,5 +34,5 @@ type LengthIsSafe : String(9007199254740991);
 type AnInteger : String(42);
 ```
 
-If not feasible, a string representation of the number needs to be used,
-e.g. in annotation values.
+If it's not feasible to use a safe integer, a string representation of the
+number needs to be used, for example, in annotation values.