@documentation-robotics/cli 0.3.0 → 0.4.0

package/dist/reports/model-report-orchestrator.js

@@ -23,6 +23,7 @@ class ModelReportOrchestrator {
    * Invalid layer names in the affected set are skipped with a warning.
    * Also regenerates the README since it contains model-wide stats that may have changed.
    * README is generated first so it exists even if a layer report throws.
+   * A report whose content is unchanged apart from its timestamp is not rewritten.
    */
   async regenerate(affectedLayers) {
     if (!await this.isInitialized())
@@ -60,6 +61,21 @@ class ModelReportOrchestrator {
       rel.layer === primaryLayer && rel.targetLayer && isValidLayerName(rel.targetLayer) && affected.add(rel.targetLayer), rel.targetLayer === primaryLayer && isValidLayerName(rel.layer) && affected.add(rel.layer);
     return affected;
   }
+  /**
+   * The layers whose reports a change to these elements can alter: the elements' own layer, and
+   * the layer at the other end of each of their relationships (that report lists them).
+   * Unlike {@link computeAffectedLayers}, a relationship elsewhere in the layer does not count.
+   */
+  computeElementAffectedLayers(layerName, elementIds) {
+    const affected = /* @__PURE__ */ new Set();
+    isValidLayerName(layerName) && affected.add(layerName);
+    const ids = new Set(elementIds);
+    if (ids.size === 0)
+      return affected;
+    for (const rel of this.model.relationships.getAll())
+      ids.has(rel.source) && rel.targetLayer && isValidLayerName(rel.targetLayer) && affected.add(rel.targetLayer), ids.has(rel.target) && isValidLayerName(rel.layer) && affected.add(rel.layer);
+    return affected;
+  }
   /**
    * Check if all 13 report files exist and are initialized.
    * Returns false only if files don't exist (ENOENT); propagates other errors like EACCES, EMFILE, EIO.
@@ -101,7 +117,7 @@ class ModelReportOrchestrator {
       throw new Error(`Failed to generate report content for layer: ${layerName} (programming error or corrupted model) - ${getErrorMessage(error)}`, { cause: error });
     }
     const filePath = this.getReportFilePath(layerName);
-    await fs.writeFile(filePath, markdown, "utf-8");
+    await writeIfChanged(filePath, markdown);
   }
   /**
    * Generate and write the model README.
@@ -117,8 +133,21 @@ class ModelReportOrchestrator {
       throw new Error(`Failed to generate README content (programming error or corrupted model) - ${getErrorMessage(error)}`, { cause: error });
     }
     const filePath = path.join(this.rootPath, "documentation-robotics", "README.md");
-    await fs.writeFile(filePath, markdown, "utf-8");
+    await writeIfChanged(filePath, markdown);
+  }
+}
+const GENERATED_AT = /^Generated: [^|\n]*\|/m, LAST_UPDATED_ROW = /^\|\s*Last Updated\s*\|[^\n]*$/m;
+function withoutTimestamps(markdown) {
+  return markdown.replace(GENERATED_AT, "Generated: |").replace(LAST_UPDATED_ROW, "| Last Updated |");
+}
+async function writeIfChanged(filePath, markdown) {
+  let current;
+  try {
+    current = await fs.readFile(filePath, "utf-8");
+  } catch {
+    current = void 0;
   }
+  current !== void 0 && withoutTimestamps(current) === withoutTimestamps(markdown) || await fs.writeFile(filePath, markdown, "utf-8");
 }
 export {
   ModelReportOrchestrator

package/dist/reports/model-report-orchestrator.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/reports/model-report-orchestrator.ts"],
-  "sourcesContent": ["/**\n * Model Report Orchestrator\n *\n * Coordinates report generation across all 13 architecture layers.\n * Determines which reports need regeneration and manages the report directory.\n */\n\nimport type { Model } from '../core/model.js';\nimport { ModelReportDataCollector } from './model-report-data.js';\nimport { ModelLayerReportGenerator } from './model-layer-report-generator.js';\nimport { ModelReadmeGenerator } from './model-readme-generator.js';\nimport { CANONICAL_LAYER_NAMES, type CanonicalLayerName, isValidLayerName } from '../core/layers.js';\nimport { getErrorMessage } from '../utils/errors.js';\nimport { getLayerReportFileName } from './model-report-utils.js';\nimport * as fs from 'fs/promises';\nimport * as path from 'path';\n\nexport class ModelReportOrchestrator {\n  private collector: ModelReportDataCollector;\n  private generator: ModelLayerReportGenerator;\n  private readmeGenerator: ModelReadmeGenerator;\n\n  constructor(private model: Model, private rootPath: string) {\n    this.collector = new ModelReportDataCollector();\n    const modelVersion = model.manifest.version || 'unknown';\n    const generatedAt = new Date().toISOString();\n    this.generator = new ModelLayerReportGenerator(modelVersion, generatedAt);\n    this.readmeGenerator = new ModelReadmeGenerator(generatedAt);\n  }\n\n  /**\n   * Regenerate reports for a specific set of affected layers.\n   * On first invocation or when reports don't exist, regenerates all 13 reports.\n   * Invalid layer names in the affected set are skipped with a warning.\n   * Also regenerates the README since it contains model-wide stats that may have changed.\n   * README is generated first so it exists even if a layer report throws.\n   */\n  async regenerate(affectedLayers: Set<string>): Promise<void> {\n    if (!(await this.isInitialized())) {\n      return this.regenerateAll();\n    }\n\n    // Generate README first so it exists even if a layer report throws\n    await this.generateReadme();\n\n    for (const layerName of affectedLayers) {\n      // Type predicate narrows layerName to CanonicalLayerName automatically\n      if (!isValidLayerName(layerName)) {\n        console.warn(`Skipping invalid layer name: ${layerName}`);\n        continue;\n      }\n      await this.generateLayerReport(layerName);\n    }\n  }\n\n  /**\n   * Regenerate all 13 layer reports and the README.\n   * Lets mkdir errors propagate so callers can handle them with proper telemetry.\n   * README is generated first so it exists even if a layer report throws.\n   */\n  async regenerateAll(): Promise<void> {\n    // Ensure report directory exists\n    const reportDir = this.getReportDir();\n    await fs.mkdir(reportDir, { recursive: true });\n\n    // Generate README first so it exists even if a layer report throws\n    await this.generateReadme();\n\n    // Generate all 13 layer reports\n    for (const layerName of CANONICAL_LAYER_NAMES) {\n      await this.generateLayerReport(layerName);\n    }\n  }\n\n  /**\n   * Compute the set of layers affected by a change to a primary layer.\n   * Returns the primary layer plus any layers that have cross-layer relationships with it.\n   * Throws if the primary layer is not a recognized canonical layer name.\n   */\n  computeAffectedLayers(primaryLayer: CanonicalLayerName): Set<CanonicalLayerName> {\n    // Defense-in-depth: validate despite type signature (guards against as casts from callers)\n    if (!isValidLayerName(primaryLayer)) {\n      throw new Error(\n        `Invalid primary layer name: '${primaryLayer}' is not a recognized canonical layer. ` +\n        `Valid layers are: ${CANONICAL_LAYER_NAMES.join(', ')}`\n      );\n    }\n\n    const affected = new Set<CanonicalLayerName>([primaryLayer]);\n\n    for (const rel of this.model.relationships.getAll()) {\n      // Outbound: this layer references another layer\n      if (rel.layer === primaryLayer && rel.targetLayer) {\n        // Validate layer name before casting (defensive: guards against user-editable YAML with invalid layer names)\n        if (isValidLayerName(rel.targetLayer)) {\n          affected.add(rel.targetLayer);\n        }\n      }\n      // Inbound: another layer references this layer\n      if (rel.targetLayer === primaryLayer) {\n        // Validate layer name before casting (defensive: guards against user-editable YAML with invalid layer names)\n        if (isValidLayerName(rel.layer)) {\n          affected.add(rel.layer);\n        }\n      }\n    }\n\n    return affected;\n  }\n\n  /**\n   * Check if all 13 report files exist and are initialized.\n   * Returns false only if files don't exist (ENOENT); propagates other errors like EACCES, EMFILE, EIO.\n   */\n  private async isInitialized(): Promise<boolean> {\n    for (const layerName of CANONICAL_LAYER_NAMES) {\n      try {\n        await fs.access(this.getReportFilePath(layerName));\n      } catch (error: unknown) {\n        const err = error as NodeJS.ErrnoException;\n        // Only ENOENT (file not found) should return false; other errors propagate\n        if (err.code === 'ENOENT') {\n          return false;\n        }\n        // Re-throw permission errors, I/O errors, etc.\n        throw error;\n      }\n    }\n    return true;\n  }\n\n  /**\n   * Get the reports directory path.\n   */\n  private getReportDir(): string {\n    return path.join(this.rootPath, 'documentation-robotics', 'reports');\n  }\n\n  /**\n   * Get the full file path for a layer report.\n   */\n  private getReportFilePath(layerName: CanonicalLayerName): string {\n    const filename = getLayerReportFileName(layerName);\n    return path.join(this.getReportDir(), filename);\n  }\n\n  /**\n   * Generate and write a single layer report.\n   * Separates concerns to distinguish programming bugs from I/O errors.\n   * Lets generation and write errors propagate so callers can handle them with proper telemetry.\n   */\n  private async generateLayerReport(layerName: CanonicalLayerName): Promise<void> {\n    let data;\n    let markdown;\n\n    try {\n      // Collect layer data (may throw if programming bug or model is corrupted)\n      data = this.collector.collectLayerData(this.model, layerName);\n\n      // Generate markdown report (may throw if programming bug)\n      markdown = this.generator.generate(data);\n    } catch (error) {\n      throw new Error(\n        `Failed to generate report content for layer: ${layerName} (programming error or corrupted model) - ${getErrorMessage(error)}`,\n        { cause: error }\n      );\n    }\n\n    // Write to file (may throw for I/O errors like ENOSPC, EACCES, EIO)\n    // Let write errors propagate so callers can handle them with proper telemetry\n    const filePath = this.getReportFilePath(layerName);\n    await fs.writeFile(filePath, markdown, 'utf-8');\n  }\n\n  /**\n   * Generate and write the model README.\n   * Separates concerns to distinguish programming bugs from I/O errors.\n   * Lets generation and write errors propagate so callers can handle them with proper telemetry.\n   * README is written to documentation-robotics/README.md (outside reports/ folder).\n   */\n  private async generateReadme(): Promise<void> {\n    let data;\n    let markdown;\n\n    try {\n      // Collect model-wide data (may throw if programming bug or model is corrupted)\n      data = this.collector.collectModelData(this.model);\n\n      // Generate markdown README (may throw if programming bug)\n      markdown = this.readmeGenerator.generate(data);\n    } catch (error) {\n      throw new Error(\n        `Failed to generate README content (programming error or corrupted model) - ${getErrorMessage(error)}`,\n        { cause: error }\n      );\n    }\n\n    // Write to file (may throw for I/O errors like ENOSPC, EACCES, EIO)\n    // Let write errors propagate so callers can handle them with proper telemetry\n    const filePath = path.join(this.rootPath, 'documentation-robotics', 'README.md');\n    await fs.writeFile(filePath, markdown, 'utf-8');\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Model Report Orchestrator\n *\n * Coordinates report generation across all 13 architecture layers.\n * Determines which reports need regeneration and manages the report directory.\n */\n\nimport type { Model } from '../core/model.js';\nimport { ModelReportDataCollector } from './model-report-data.js';\nimport { ModelLayerReportGenerator } from './model-layer-report-generator.js';\nimport { ModelReadmeGenerator } from './model-readme-generator.js';\nimport { CANONICAL_LAYER_NAMES, type CanonicalLayerName, isValidLayerName } from '../core/layers.js';\nimport { getErrorMessage } from '../utils/errors.js';\nimport { getLayerReportFileName } from './model-report-utils.js';\nimport * as fs from 'fs/promises';\nimport * as path from 'path';\n\nexport class ModelReportOrchestrator {\n  private collector: ModelReportDataCollector;\n  private generator: ModelLayerReportGenerator;\n  private readmeGenerator: ModelReadmeGenerator;\n\n  constructor(private model: Model, private rootPath: string) {\n    this.collector = new ModelReportDataCollector();\n    const modelVersion = model.manifest.version || 'unknown';\n    const generatedAt = new Date().toISOString();\n    this.generator = new ModelLayerReportGenerator(modelVersion, generatedAt);\n    this.readmeGenerator = new ModelReadmeGenerator(generatedAt);\n  }\n\n  /**\n   * Regenerate reports for a specific set of affected layers.\n   * On first invocation or when reports don't exist, regenerates all 13 reports.\n   * Invalid layer names in the affected set are skipped with a warning.\n   * Also regenerates the README since it contains model-wide stats that may have changed.\n   * README is generated first so it exists even if a layer report throws.\n   * A report whose content is unchanged apart from its timestamp is not rewritten.\n   */\n  async regenerate(affectedLayers: Set<string>): Promise<void> {\n    if (!(await this.isInitialized())) {\n      return this.regenerateAll();\n    }\n\n    // Generate README first so it exists even if a layer report throws\n    await this.generateReadme();\n\n    for (const layerName of affectedLayers) {\n      // Type predicate narrows layerName to CanonicalLayerName automatically\n      if (!isValidLayerName(layerName)) {\n        console.warn(`Skipping invalid layer name: ${layerName}`);\n        continue;\n      }\n      await this.generateLayerReport(layerName);\n    }\n  }\n\n  /**\n   * Regenerate all 13 layer reports and the README.\n   * Lets mkdir errors propagate so callers can handle them with proper telemetry.\n   * README is generated first so it exists even if a layer report throws.\n   */\n  async regenerateAll(): Promise<void> {\n    // Ensure report directory exists\n    const reportDir = this.getReportDir();\n    await fs.mkdir(reportDir, { recursive: true });\n\n    // Generate README first so it exists even if a layer report throws\n    await this.generateReadme();\n\n    // Generate all 13 layer reports\n    for (const layerName of CANONICAL_LAYER_NAMES) {\n      await this.generateLayerReport(layerName);\n    }\n  }\n\n  /**\n   * Compute the set of layers affected by a change to a primary layer.\n   * Returns the primary layer plus any layers that have cross-layer relationships with it.\n   * Throws if the primary layer is not a recognized canonical layer name.\n   */\n  computeAffectedLayers(primaryLayer: CanonicalLayerName): Set<CanonicalLayerName> {\n    // Defense-in-depth: validate despite type signature (guards against as casts from callers)\n    if (!isValidLayerName(primaryLayer)) {\n      throw new Error(\n        `Invalid primary layer name: '${primaryLayer}' is not a recognized canonical layer. ` +\n        `Valid layers are: ${CANONICAL_LAYER_NAMES.join(', ')}`\n      );\n    }\n\n    const affected = new Set<CanonicalLayerName>([primaryLayer]);\n\n    for (const rel of this.model.relationships.getAll()) {\n      // Outbound: this layer references another layer\n      if (rel.layer === primaryLayer && rel.targetLayer) {\n        // Validate layer name before casting (defensive: guards against user-editable YAML with invalid layer names)\n        if (isValidLayerName(rel.targetLayer)) {\n          affected.add(rel.targetLayer);\n        }\n      }\n      // Inbound: another layer references this layer\n      if (rel.targetLayer === primaryLayer) {\n        // Validate layer name before casting (defensive: guards against user-editable YAML with invalid layer names)\n        if (isValidLayerName(rel.layer)) {\n          affected.add(rel.layer);\n        }\n      }\n    }\n\n    return affected;\n  }\n\n  /**\n   * The layers whose reports a change to these elements can alter: the elements' own layer, and\n   * the layer at the other end of each of their relationships (that report lists them).\n   * Unlike {@link computeAffectedLayers}, a relationship elsewhere in the layer does not count.\n   */\n  computeElementAffectedLayers(layerName: string, elementIds: Iterable<string>): Set<CanonicalLayerName> {\n    const affected = new Set<CanonicalLayerName>();\n    if (isValidLayerName(layerName)) affected.add(layerName);\n    const ids = new Set(elementIds);\n    if (ids.size === 0) return affected;\n\n    for (const rel of this.model.relationships.getAll()) {\n      if (ids.has(rel.source) && rel.targetLayer && isValidLayerName(rel.targetLayer)) {\n        affected.add(rel.targetLayer);\n      }\n      if (ids.has(rel.target) && isValidLayerName(rel.layer)) {\n        affected.add(rel.layer);\n      }\n    }\n    return affected;\n  }\n\n  /**\n   * Check if all 13 report files exist and are initialized.\n   * Returns false only if files don't exist (ENOENT); propagates other errors like EACCES, EMFILE, EIO.\n   */\n  private async isInitialized(): Promise<boolean> {\n    for (const layerName of CANONICAL_LAYER_NAMES) {\n      try {\n        await fs.access(this.getReportFilePath(layerName));\n      } catch (error: unknown) {\n        const err = error as NodeJS.ErrnoException;\n        // Only ENOENT (file not found) should return false; other errors propagate\n        if (err.code === 'ENOENT') {\n          return false;\n        }\n        // Re-throw permission errors, I/O errors, etc.\n        throw error;\n      }\n    }\n    return true;\n  }\n\n  /**\n   * Get the reports directory path.\n   */\n  private getReportDir(): string {\n    return path.join(this.rootPath, 'documentation-robotics', 'reports');\n  }\n\n  /**\n   * Get the full file path for a layer report.\n   */\n  private getReportFilePath(layerName: CanonicalLayerName): string {\n    const filename = getLayerReportFileName(layerName);\n    return path.join(this.getReportDir(), filename);\n  }\n\n  /**\n   * Generate and write a single layer report.\n   * Separates concerns to distinguish programming bugs from I/O errors.\n   * Lets generation and write errors propagate so callers can handle them with proper telemetry.\n   */\n  private async generateLayerReport(layerName: CanonicalLayerName): Promise<void> {\n    let data;\n    let markdown;\n\n    try {\n      // Collect layer data (may throw if programming bug or model is corrupted)\n      data = this.collector.collectLayerData(this.model, layerName);\n\n      // Generate markdown report (may throw if programming bug)\n      markdown = this.generator.generate(data);\n    } catch (error) {\n      throw new Error(\n        `Failed to generate report content for layer: ${layerName} (programming error or corrupted model) - ${getErrorMessage(error)}`,\n        { cause: error }\n      );\n    }\n\n    // Write to file (may throw for I/O errors like ENOSPC, EACCES, EIO)\n    // Let write errors propagate so callers can handle them with proper telemetry\n    const filePath = this.getReportFilePath(layerName);\n    await writeIfChanged(filePath, markdown);\n  }\n\n  /**\n   * Generate and write the model README.\n   * Separates concerns to distinguish programming bugs from I/O errors.\n   * Lets generation and write errors propagate so callers can handle them with proper telemetry.\n   * README is written to documentation-robotics/README.md (outside reports/ folder).\n   */\n  private async generateReadme(): Promise<void> {\n    let data;\n    let markdown;\n\n    try {\n      // Collect model-wide data (may throw if programming bug or model is corrupted)\n      data = this.collector.collectModelData(this.model);\n\n      // Generate markdown README (may throw if programming bug)\n      markdown = this.readmeGenerator.generate(data);\n    } catch (error) {\n      throw new Error(\n        `Failed to generate README content (programming error or corrupted model) - ${getErrorMessage(error)}`,\n        { cause: error }\n      );\n    }\n\n    // Write to file (may throw for I/O errors like ENOSPC, EACCES, EIO)\n    // Let write errors propagate so callers can handle them with proper telemetry\n    const filePath = path.join(this.rootPath, 'documentation-robotics', 'README.md');\n    await writeIfChanged(filePath, markdown);\n  }\n}\n\n/**\n * The footer's generation time changes on every generation, and the README's \"Last Updated\" row\n * (the manifest's modified time) on every save: neither is a change to the report's content.\n */\nconst GENERATED_AT = /^Generated: [^|\\n]*\\|/m;\nconst LAST_UPDATED_ROW = /^\\|\\s*Last Updated\\s*\\|[^\\n]*$/m;\n\nfunction withoutTimestamps(markdown: string): string {\n  return markdown.replace(GENERATED_AT, 'Generated: |').replace(LAST_UPDATED_ROW, '| Last Updated |');\n}\n\n/**\n * Write a generated report unless the file already holds the same report apart from its\n * timestamps, so regenerating a report nothing changed leaves no diff. A file that cannot be read\n * is written.\n */\nasync function writeIfChanged(filePath: string, markdown: string): Promise<void> {\n  let current: string | undefined;\n  try {\n    current = await fs.readFile(filePath, 'utf-8');\n  } catch {\n    current = undefined;\n  }\n  if (current !== undefined && withoutTimestamps(current) === withoutTimestamps(markdown)) {\n    return;\n  }\n  await fs.writeFile(filePath, markdown, 'utf-8');\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/schemas/bundled/analyzers/cbm.json

@@ -1,7 +1,7 @@
 {
   "name": "cbm",
-  "version": "0.11.0",
-  "source_version": "0.11.0",
+  "version": "0.12.0",
+  "source_version": "0.12.0",
   "analyzer": {
     "name": "cbm",
     "display_name": "codebase-memory-mcp",
@@ -386,9 +386,14 @@
       "dr_scope": "intra-layer",
       "direction": "forward",
       "dr_pattern": "application.applicationfunction → application.applicationfunction",
-      "implementation_note": "Listed first: it is the call-graph default edge type for dr analyzer callers and callees. Creates a relationship only between functions that both survive classification.",
+      "implementation_note": "Listed first: it is the call-graph default edge type for dr analyzer callers and callees. Creates a relationship only between functions that both survive classification. A call from a test case to the code it exercises (a component, function, process, interface, service, operation, object schema or access pattern) is the test testing it (testing.testcasesketch.tests.*); a call to a member with no element of its own counts as a call to its class, and from a test only when the test's file refers to that class (a USAGE or IMPORTS edge), because the index resolves a call by the member's name.",
       "conditions": {
         "predicates": [
+          {
+            "predicate": "tests",
+            "invert": false,
+            "from_types": ["testing.testcasesketch"]
+          },
           {
             "predicate": "depends-on",
             "invert": false
@@ -660,7 +665,7 @@
       "cbm_edge": "TESTS",
       "dr_relationship": "tests",
       "confidence": "high",
-      "description": "A test function exercises a symbol: the test case sketch tests that function, interface, service or operation",
+      "description": "A test function exercises a symbol: the test case sketch tests that component, function, interface, service, operation, object schema or access pattern",
       "usage": "verification_and_mapping",
       "dr_scope": "cross-layer",
       "direction": "forward",
@@ -838,7 +843,7 @@
       "dr_scope": "cross-layer",
       "direction": "caller_to_callee",
       "confidence_from_property": "confidence",
-      "implementation_note": "Creates a relationship only from a test case (a symbol Tier 0 classified as testing.testcasesketch) to an operation: on CBM 0.12.1 almost every observed caller is test code (53 of 55 on fastapi, 81 of 86 on dr-cli). A production caller (application code consuming an operation) still creates none: that triple waits on catalog addition 7 (docs/analyzers/CBM_MAPPING_INVENTORY.md), queued in Context Studio.",
+      "implementation_note": "Creates a relationship only from a test case (a symbol Tier 0 classified as testing.testcasesketch) to an operation: on CBM 0.12.1 almost every observed caller is test code (53 of 55 on fastapi, 81 of 86 on dr-cli). A production caller (application code consuming an operation) still creates none: that triple waits on catalog addition 7 (docs/analyzers/CBM_MAPPING_INVENTORY.md), queued in Context Studio. Extraction also reads this edge from test code that calls a served route by URL (MockMvc get(\"/owners/{ownerId}\"), RestTemplate, supertest), which CBM has no edge for.",
       "dr_pattern": "testing.testcasesketch → api.operation",
       "conditions": {
         "from_types": ["testing.testcasesketch"],
@@ -883,15 +888,22 @@
     },
     "INHERITS": {
       "cbm_edge": "INHERITS",
-      "dr_relationship": null,
+      "dr_relationship": "specializes",
       "confidence": "high",
-      "description": "Class or interface inheritance",
-      "usage": "traversal_only",
+      "description": "Class or interface inheritance: the subclass specializes its parent",
+      "usage": "verification_and_mapping",
       "dr_scope": "intra-layer",
       "direction": "forward",
-      "implementation_note": "specializes between components and between data objects; proposed to Context Studio's review queue as a catalog addition (docs/analyzers/CBM_MAPPING_INVENTORY.md, addition 1); map once accepted.",
+      "dr_pattern": "data-model.objectschema → data-model.objectschema",
+      "implementation_note": "Only between two elements of the same type that the catalog lets specialize (object schemas, data objects, components, functions, ...): an entity class extending a mapped superclass. Inheriting from a class of another type, or from one that is not an element, creates nothing.",
       "conditions": {
-        "usage_detail": "intra-layer structural"
+        "usage_detail": "intra-layer structural",
+        "predicates": [
+          {
+            "predicate": "specializes",
+            "invert": false
+          }
+        ]
       }
     },
     "EXTENDS": {

package/dist/schemas/bundled/analyzers/manifest.json

@@ -1,9 +1,9 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "analyzers": [
     {
       "name": "cbm",
-      "version": "0.11.0"
+      "version": "0.12.0"
     }
   ]
 }

package/dist/schemas/bundled/api.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "api",
     "number": 7,

package/dist/schemas/bundled/apm.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "apm",
     "number": 12,

package/dist/schemas/bundled/application.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "application",
     "number": 5,

package/dist/schemas/bundled/base.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "schemas": {
     "spec-node": {
       "$schema": "http://json-schema.org/draft-07/schema#",

package/dist/schemas/bundled/business.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "business",
     "number": 2,

package/dist/schemas/bundled/data-model.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "data-model",
     "number": 8,

package/dist/schemas/bundled/data-store.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "data-store",
     "number": 9,

package/dist/schemas/bundled/manifest.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layers": [
     {
       "id": "motivation",
@@ -90,11 +90,11 @@
       "number": 13,
       "name": "Testing Layer",
       "nodeTypeCount": 17,
-      "relationshipCount": 89
+      "relationshipCount": 101
     }
   ],
   "totals": {
     "nodeTypes": 193,
-    "relationships": 975
+    "relationships": 987
   }
 }

package/dist/schemas/bundled/motivation.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "motivation",
     "number": 1,

package/dist/schemas/bundled/navigation.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "navigation",
     "number": 11,

package/dist/schemas/bundled/product.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "product",
     "number": 3,

package/dist/schemas/bundled/security.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "security",
     "number": 4,

package/dist/schemas/bundled/technology.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "technology",
     "number": 6,

package/dist/schemas/bundled/testing.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "testing",
     "number": 13,
@@ -1543,6 +1543,18 @@
       "required": false,
       "description": "The test case verifies the requirement, so passing it is evidence that the requirement is met."
     },
+    "testing.testcasesketch.tests.data-store.accesspattern": {
+      "id": "testing.testcasesketch.tests.data-store.accesspattern",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "data-store.accesspattern",
+      "destination_layer": "data-store",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the access pattern."
+    },
     "testing.testcasesketch.tests.ux.actioncomponent": {
       "id": "testing.testcasesketch.tests.ux.actioncomponent",
       "source_spec_node_id": "testing.testcasesketch",
@@ -1555,6 +1567,18 @@
       "required": false,
       "description": "The test case exercises the action component, such as clicking a button."
     },
+    "testing.testcasesketch.tests.application.applicationcomponent": {
+      "id": "testing.testcasesketch.tests.application.applicationcomponent",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "application.applicationcomponent",
+      "destination_layer": "application",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the application component."
+    },
     "testing.testcasesketch.tests.application.applicationfunction": {
       "id": "testing.testcasesketch.tests.application.applicationfunction",
       "source_spec_node_id": "testing.testcasesketch",
@@ -1579,6 +1603,18 @@
       "required": false,
       "description": "The test case exercises the application interface, such as a contract test."
     },
+    "testing.testcasesketch.tests.application.applicationprocess": {
+      "id": "testing.testcasesketch.tests.application.applicationprocess",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "application.applicationprocess",
+      "destination_layer": "application",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the application process."
+    },
     "testing.testcasesketch.tests.application.applicationservice": {
       "id": "testing.testcasesketch.tests.application.applicationservice",
       "source_spec_node_id": "testing.testcasesketch",
@@ -1591,6 +1627,18 @@
       "required": false,
       "description": "The test case exercises the application service."
     },
+    "testing.testcasesketch.tests.security.authenticationconfig": {
+      "id": "testing.testcasesketch.tests.security.authenticationconfig",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "security.authenticationconfig",
+      "destination_layer": "security",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the authentication configuration."
+    },
     "testing.testcasesketch.tests.business.businessprocess": {
       "id": "testing.testcasesketch.tests.business.businessprocess",
       "source_spec_node_id": "testing.testcasesketch",
@@ -1687,6 +1735,30 @@
       "required": false,
       "description": "The test case checks that the guard allows or blocks navigation."
     },
+    "testing.testcasesketch.tests.navigation.navigationtransition": {
+      "id": "testing.testcasesketch.tests.navigation.navigationtransition",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "navigation.navigationtransition",
+      "destination_layer": "navigation",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the navigation transition."
+    },
+    "testing.testcasesketch.tests.data-model.objectschema": {
+      "id": "testing.testcasesketch.tests.data-model.objectschema",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "data-model.objectschema",
+      "destination_layer": "data-model",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the object schema."
+    },
     "testing.testcasesketch.tests.api.operation": {
       "id": "testing.testcasesketch.tests.api.operation",
       "source_spec_node_id": "testing.testcasesketch",
@@ -1735,6 +1807,18 @@
       "required": false,
       "description": "The test case checks values against the schema definition."
     },
+    "testing.testcasesketch.tests.security.secureresource": {
+      "id": "testing.testcasesketch.tests.security.secureresource",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "security.secureresource",
+      "destination_layer": "security",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises access control on the secure resource."
+    },
     "testing.testcasesketch.tests.security.securitypolicy": {
       "id": "testing.testcasesketch.tests.security.securitypolicy",
       "source_spec_node_id": "testing.testcasesketch",
@@ -1747,6 +1831,42 @@
       "required": false,
       "description": "The test case checks that the security policy is enforced."
     },
+    "testing.testcasesketch.tests.apm.span": {
+      "id": "testing.testcasesketch.tests.apm.span",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "apm.span",
+      "destination_layer": "apm",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the span."
+    },
+    "testing.testcasesketch.tests.data-store.storedlogic": {
+      "id": "testing.testcasesketch.tests.data-store.storedlogic",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "data-store.storedlogic",
+      "destination_layer": "data-store",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the stored logic."
+    },
+    "testing.testcasesketch.tests.ux.subview": {
+      "id": "testing.testcasesketch.tests.ux.subview",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "ux.subview",
+      "destination_layer": "ux",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the subview."
+    },
     "testing.testcasesketch.tests.security.threat": {
       "id": "testing.testcasesketch.tests.security.threat",
       "source_spec_node_id": "testing.testcasesketch",
@@ -1759,6 +1879,18 @@
       "required": false,
       "description": "The test case attempts the threat, such as a penetration test."
     },
+    "testing.testcasesketch.tests.product.userworkflow": {
+      "id": "testing.testcasesketch.tests.product.userworkflow",
+      "source_spec_node_id": "testing.testcasesketch",
+      "source_layer": "testing",
+      "destination_spec_node_id": "product.userworkflow",
+      "destination_layer": "product",
+      "predicate": "tests",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The test case exercises the user workflow."
+    },
     "testing.testcasesketch.tests.data-store.validationrule": {
       "id": "testing.testcasesketch.tests.data-store.validationrule",
       "source_spec_node_id": "testing.testcasesketch",
@@ -2071,6 +2203,18 @@
       "required": false,
       "description": "The target puts the feature in test scope."
     },
+    "testing.testcoveragetarget.covers.ux.librarycomponent": {
+      "id": "testing.testcoveragetarget.covers.ux.librarycomponent",
+      "source_spec_node_id": "testing.testcoveragetarget",
+      "source_layer": "testing",
+      "destination_spec_node_id": "ux.librarycomponent",
+      "destination_layer": "ux",
+      "predicate": "covers",
+      "cardinality": "many-to-many",
+      "strength": "medium",
+      "required": false,
+      "description": "The target puts the library component in test scope."
+    },
     "testing.testcoveragetarget.covers.data-model.objectschema": {
       "id": "testing.testcoveragetarget.covers.data-model.objectschema",
       "source_spec_node_id": "testing.testcoveragetarget",

package/dist/schemas/bundled/ux.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "0.11.0",
+  "specVersion": "0.12.0",
   "layer": {
     "id": "ux",
     "number": 10,