@documentation-robotics/cli 0.1.13 → 0.3.0

package/dist/reports/model-layer-report-generator.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/reports/model-layer-report-generator.ts"],
-  "sourcesContent": ["/**\n * Model Layer Report Generator\n *\n * Generates markdown documentation for a single architecture layer with:\n * - Mermaid intra-layer and inter-layer diagrams\n * - Relationship tables\n * - Element reference documentation\n * - Navigation and metadata\n *\n * Mirrors LayerReportGenerator from spec script but renders element instances\n * instead of type schemas.\n */\n\nimport type { ModelLayerReportData } from './model-report-data.js';\nimport type { Relationship } from '../core/relationships.js';\nimport { formatLayerName } from '../utils/layer-name-formatter.js';\nimport { formatMarkdownTable } from '../utils/markdown-table.js';\nimport { sanitizeMermaidId, escapeMermaidLabel } from '../utils/mermaid-utils.js';\nimport { createAnchor } from '../utils/markdown-anchor.js';\nimport { escapeMarkdown, getLayerDescription, valueToMarkdown } from '../export/markdown-utils.js';\nimport { getLayerOrder, CANONICAL_LAYER_NAMES } from '../core/layers.js';\nimport { getValidRelationships } from '../generated/relationship-index.js';\n\nexport class ModelLayerReportGenerator {\n  constructor(private modelVersion: string, private generatedAt: string) {}\n\n  /**\n   * Generate complete layer report markdown\n   */\n  generate(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n\n    // Document header\n    lines.push(this.generateHeader(data));\n\n    // Report Index (table of contents)\n    lines.push(this.generateTableOfContents(data));\n\n    // Layer Introduction + Statistics\n    lines.push(this.generateLayerIntroduction(data));\n\n    // Intra-Layer Relationships diagram\n    lines.push(this.generateIntraLayerDiagram(data));\n\n    // Inter-Layer Dependencies diagram\n    lines.push(this.generateInterLayerDiagram(data));\n\n    // Inter-Layer Relationships Table\n    lines.push(this.generateInterLayerTable(data));\n\n    // Element Reference section\n    lines.push(this.generateElementReference(data));\n\n    // Footer\n    lines.push(this.generateFooter());\n\n    return lines.join('');\n  }\n\n  private generateHeader(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push(`# ${formatLayerName(data.layerName)}\\n`);\n    lines.push('\\n');\n    lines.push(`${getLayerDescription(data.layerName)}\\n`);\n    lines.push('\\n');\n    return lines.join('');\n  }\n\n  private generateTableOfContents(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push('## Report Index\\n');\n    lines.push('\\n');\n\n    lines.push('- [Layer Introduction](#layer-introduction)\\n');\n    lines.push('- [Intra-Layer Relationships](#intra-layer-relationships)\\n');\n    lines.push('- [Inter-Layer Dependencies](#inter-layer-dependencies)\\n');\n\n    if (data.interRelationships.length > 0) {\n      lines.push('- [Inter-Layer Relationships Table](#inter-layer-relationships-table)\\n');\n    }\n\n    if (data.elements.length > 0) {\n      lines.push('- [Element Reference](#element-reference)\\n');\n    }\n\n    lines.push('\\n');\n    return lines.join('');\n  }\n\n  private generateLayerIntroduction(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push('## Layer Introduction\\n');\n    lines.push('\\n');\n\n    // Statistics table\n    const headers = ['Metric', 'Count'];\n    const rows = [\n      ['Elements', String(data.statistics.elementCount)],\n      ['Intra-Layer Relationships', String(data.statistics.intraRelationshipCount)],\n      ['Inter-Layer Relationships', String(data.statistics.interRelationshipCount)],\n      ['Inbound Relationships', String(data.statistics.inboundRelationshipCount)],\n      ['Outbound Relationships', String(data.statistics.outboundRelationshipCount)],\n    ];\n\n    const table = formatMarkdownTable(headers, rows);\n    lines.push(table);\n    lines.push('\\n');\n\n    // Upstream and downstream layers\n    if (data.upstreamLayers.length > 0 || data.downstreamLayers.length > 0) {\n      lines.push('**Cross-Layer References**:\\n');\n      lines.push('\\n');\n\n      if (data.upstreamLayers.length > 0) {\n        const upstreamLinks = data.upstreamLayers\n          .map((layerName) => this.createLayerLink(layerName))\n          .join(', ');\n        lines.push(`- **Upstream layers**: ${upstreamLinks}\\n`);\n      }\n\n      if (data.downstreamLayers.length > 0) {\n        const downstreamLinks = data.downstreamLayers\n          .map((layerName) => this.createLayerLink(layerName))\n          .join(', ');\n        lines.push(`- **Downstream layers**: ${downstreamLinks}\\n`);\n      }\n\n      lines.push('\\n');\n    }\n\n    return lines.join('');\n  }\n\n  private generateIntraLayerDiagram(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push('## Intra-Layer Relationships\\n');\n    lines.push('\\n');\n\n    // Empty layer handling\n    if (data.elements.length === 0) {\n      lines.push('No elements in this layer.\\n');\n      lines.push('\\n');\n      return lines.join('');\n    }\n\n    // Large layer fallback: For >30 elements, use summary table instead of Mermaid\n    // to prevent rendering failures\n    if (data.elements.length > 30) {\n      lines.push('*This layer has >30 elements. Summary table shown instead of diagram.*\\n');\n      lines.push('\\n');\n\n      const headers = ['Element', 'Type', 'Relationships'];\n      const rows: string[][] = [];\n\n      for (const element of data.elements) {\n        const relCount = data.intraRelationships.filter(\n          (rel) => rel.source === element.path || rel.target === element.path\n        ).length;\n\n        rows.push([\n          `\\`${escapeMarkdown(element.path)}\\``,\n          `\\`${escapeMarkdown(element.type)}\\``,\n          String(relCount),\n        ]);\n      }\n\n      const table = formatMarkdownTable(headers, rows);\n      lines.push(table);\n      lines.push('\\n');\n\n      return lines.join('');\n    }\n\n    // Generate mermaid diagram for layers with \u226430 elements\n    lines.push('```mermaid\\n');\n    lines.push('flowchart LR\\n');\n    lines.push(`  subgraph ${sanitizeMermaidId(data.layerName)}\\n`);\n\n    // Add all elements as nodes (use escapeMermaidLabel for correct Mermaid escaping)\n    for (const element of data.elements) {\n      const nodeId = sanitizeMermaidId(element.path);\n      const label = escapeMermaidLabel(element.name);\n      lines.push(`    ${nodeId}[\"${label}\"]\\n`);\n    }\n\n    // Add intra-layer relationships (sorted for deterministic output)\n    const sortedRelationships = [...data.intraRelationships].sort((a, b) => {\n      const aKey = `${a.source}-${a.predicate}-${a.target}`;\n      const bKey = `${b.source}-${b.predicate}-${b.target}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    for (const rel of sortedRelationships) {\n      const sourceId = sanitizeMermaidId(rel.source);\n      const targetId = sanitizeMermaidId(rel.target);\n      const predicate = escapeMermaidLabel(rel.predicate);\n      lines.push(`    ${sourceId} -->|${predicate}| ${targetId}\\n`);\n    }\n\n    lines.push('  end\\n');\n    lines.push('```\\n');\n    lines.push('\\n');\n\n    return lines.join('');\n  }\n\n  private generateInterLayerDiagram(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push('## Inter-Layer Dependencies\\n');\n    lines.push('\\n');\n\n    // Empty layer handling\n    if (data.elements.length === 0) {\n      lines.push('No elements in this layer.\\n');\n      lines.push('\\n');\n      return lines.join('');\n    }\n\n    lines.push('```mermaid\\n');\n    lines.push('flowchart TB\\n');\n    lines.push('  classDef current fill:#f9f,stroke:#333,stroke-width:2px\\n');\n\n    // Add all layers as nodes\n    for (const layerName of CANONICAL_LAYER_NAMES) {\n      const layerId = sanitizeMermaidId(layerName);\n      const label = formatLayerName(layerName);\n      lines.push(`  ${layerId}[\"${label}\"]\\n`);\n    }\n\n    // Add layer-to-layer relationships for inter-layer dependencies\n    const addedRelationships = new Set<string>();\n    const layerRelationships: Array<{ sourceId: string; destId: string }> = [];\n\n    for (const rel of data.interRelationships) {\n      // Only include inter-layer relationships\n      if (rel.layer !== rel.targetLayer && rel.targetLayer) {\n        const key = `${rel.layer}-${rel.targetLayer}`;\n        if (!addedRelationships.has(key)) {\n          const sourceId = sanitizeMermaidId(rel.layer);\n          const destId = sanitizeMermaidId(rel.targetLayer);\n          layerRelationships.push({ sourceId, destId });\n          addedRelationships.add(key);\n        }\n      }\n    }\n\n    // Sort and output relationships for deterministic ordering\n    const sortedLayerRels = layerRelationships.sort((a, b) => {\n      const aKey = `${a.sourceId}-${a.destId}`;\n      const bKey = `${b.sourceId}-${b.destId}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    for (const { sourceId, destId } of sortedLayerRels) {\n      lines.push(`  ${sourceId} --> ${destId}\\n`);\n    }\n\n    // Highlight current layer\n    const currentLayerId = sanitizeMermaidId(data.layerName);\n    lines.push(`  class ${currentLayerId} current\\n`);\n\n    lines.push('```\\n');\n    lines.push('\\n');\n\n    return lines.join('');\n  }\n\n  private generateInterLayerTable(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n\n    if (data.interRelationships.length === 0) {\n      return '';\n    }\n\n    lines.push('## Inter-Layer Relationships Table\\n');\n    lines.push('\\n');\n\n    // Sort relationships for deterministic output\n    const sortedRels = [...data.interRelationships].sort((a, b) => {\n      const aKey = `${a.source}-${a.predicate}-${a.target}`;\n      const bKey = `${b.source}-${b.predicate}-${b.target}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    const headers = ['Relationship ID', 'Source Node', 'Dest Node', 'Dest Layer', 'Predicate', 'Cardinality', 'Strength'];\n    const rows: string[][] = [];\n\n    for (const rel of sortedRels) {\n      // Extract element types from paths (e.g., \"motivation.goal.customer-satisfaction\" -> \"motivation.goal\")\n      const sourceType = this.extractElementType(rel.source);\n      const targetType = this.extractElementType(rel.target);\n\n      // Look up spec-level relationship properties\n      const specs = getValidRelationships(sourceType, rel.predicate, targetType);\n      const cardinality = specs.length > 0 ? specs[0].cardinality : 'unknown';\n      const strength = specs.length > 0 ? specs[0].strength : 'unknown';\n\n      // Use spec relationship ID when available, fall back to concatenated form\n      const relationshipId = specs.length > 0 ? specs[0].id : `${rel.source}-${rel.predicate}-${rel.target}`;\n\n      rows.push([\n        `\\`${escapeMarkdown(relationshipId)}\\``,\n        `\\`${escapeMarkdown(rel.source)}\\``,\n        `\\`${escapeMarkdown(rel.target)}\\``,\n        rel.targetLayer ? `\\`${escapeMarkdown(rel.targetLayer)}\\`` : '\u2014',\n        `\\`${escapeMarkdown(rel.predicate)}\\``,\n        cardinality,\n        strength,\n      ]);\n    }\n\n    const table = formatMarkdownTable(headers, rows);\n    lines.push(table);\n    lines.push('\\n');\n\n    return lines.join('');\n  }\n\n  private generateElementReference(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n\n    if (data.elements.length === 0) {\n      return '';\n    }\n\n    lines.push('## Element Reference\\n');\n    lines.push('\\n');\n\n    for (const element of data.elements) {\n      const anchor = createAnchor(element.name);\n      lines.push(`### ${escapeMarkdown(element.name)} {#${anchor}}\\n`);\n      lines.push('\\n');\n\n      // ID and type\n      lines.push(`**ID**: \\`${escapeMarkdown(element.path)}\\`\\n\\n`);\n      lines.push(`**Type**: \\`${escapeMarkdown(element.type)}\\`\\n\\n`);\n\n      // Description if available\n      if (element.description) {\n        lines.push(`${escapeMarkdown(element.description)}\\n\\n`);\n      }\n\n      // Attributes if available\n      if (Object.keys(element.attributes).length > 0) {\n        lines.push('#### Attributes\\n\\n');\n        const attrHeaders = ['Name', 'Value'];\n        const attrRows: string[][] = [];\n\n        // Sort attributes for deterministic output\n        const sortedAttrs = Object.entries(element.attributes).sort((a, b) =>\n          a[0].localeCompare(b[0])\n        );\n\n        for (const [name, value] of sortedAttrs) {\n          const valueStr = valueToMarkdown(value);\n          attrRows.push([name, valueStr]);\n        }\n\n        const attrTable = formatMarkdownTable(attrHeaders, attrRows);\n        lines.push(attrTable);\n        lines.push('\\n');\n      }\n\n      // Relationships involving this element\n      const elementRels = this.getElementRelationships(data, element.path);\n      if (elementRels.length > 0) {\n        lines.push('#### Relationships\\n\\n');\n        const relHeaders = ['Type', 'Related Element', 'Predicate', 'Direction'];\n        const relRows: string[][] = [];\n\n        // Sort for deterministic output\n        const sortedElementRels = [...elementRels].sort((a, b) => {\n          const aKey = `${a.relType}-${a.rel.source}-${a.rel.predicate}-${a.rel.target}`;\n          const bKey = `${b.relType}-${b.rel.source}-${b.rel.predicate}-${b.rel.target}`;\n          return aKey.localeCompare(bKey);\n        });\n\n        for (const { rel, relType } of sortedElementRels) {\n          const relatedElement = rel.source === element.path ? rel.target : rel.source;\n          const direction = rel.source === element.path ? 'outbound' : 'inbound';\n\n          relRows.push([\n            relType,\n            `\\`${escapeMarkdown(relatedElement)}\\``,\n            `\\`${escapeMarkdown(rel.predicate)}\\``,\n            direction,\n          ]);\n        }\n\n        const relTable = formatMarkdownTable(relHeaders, relRows);\n        lines.push(relTable);\n        lines.push('\\n');\n      }\n    }\n\n    return lines.join('');\n  }\n\n  private generateFooter(): string {\n    const lines: string[] = [];\n    lines.push('---\\n');\n    lines.push('\\n');\n    lines.push(`Generated: ${this.generatedAt} | Model Version: ${this.modelVersion}\\n`);\n    return lines.join('');\n  }\n\n  /**\n   * Create a markdown link to a layer report\n   */\n  private createLayerLink(layerName: string): string {\n    const layerNumber = getLayerOrder(layerName);\n    if (layerNumber === -1) {\n      return layerName;\n    }\n    const filename = `./${String(layerNumber).padStart(2, '0')}-${layerName}-layer-report.md`;\n    return `[${formatLayerName(layerName)}](${filename})`;\n  }\n\n  /**\n   * Get relationships involving a specific element\n   */\n  private getElementRelationships(\n    data: ModelLayerReportData,\n    elementPath: string\n  ): Array<{ rel: Relationship; relType: 'intra-layer' | 'inter-layer' }> {\n    const rels: Array<{ rel: Relationship; relType: 'intra-layer' | 'inter-layer' }> = [];\n\n    // Intra-layer relationships\n    for (const rel of data.intraRelationships) {\n      if (rel.source === elementPath || rel.target === elementPath) {\n        rels.push({ rel, relType: 'intra-layer' });\n      }\n    }\n\n    // Inter-layer relationships\n    for (const rel of data.interRelationships) {\n      if (rel.source === elementPath || rel.target === elementPath) {\n        rels.push({ rel, relType: 'inter-layer' });\n      }\n    }\n\n    return rels;\n  }\n\n  /**\n   * Extract element type from element path in layer.type format\n   * Example: \"motivation.goal.customer-satisfaction\" -> \"motivation.goal\"\n   * This format matches the keys in RELATIONSHIPS_BY_SOURCE map.\n   */\n  private extractElementType(elementPath: string): string {\n    const parts = elementPath.split('.');\n    if (parts.length >= 2) {\n      return parts.slice(0, 2).join('.');\n    }\n    return elementPath;\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Model Layer Report Generator\n *\n * Generates markdown documentation for a single architecture layer with:\n * - Mermaid intra-layer and inter-layer diagrams\n * - Relationship tables\n * - Element reference documentation\n * - Navigation and metadata\n *\n * Mirrors LayerReportGenerator from spec script but renders element instances\n * instead of type schemas.\n */\n\nimport type { ModelLayerReportData } from './model-report-data.js';\nimport type { Relationship } from '../core/relationships.js';\nimport { formatLayerName } from '../utils/layer-name-formatter.js';\nimport { formatMarkdownTable } from '../utils/markdown-table.js';\nimport { sanitizeMermaidId, escapeMermaidLabel } from '../utils/mermaid-utils.js';\nimport { createAnchor } from '../utils/markdown-anchor.js';\nimport { escapeMarkdown, getLayerDescription, valueToMarkdown } from '../export/markdown-utils.js';\nimport type { CanonicalLayerName } from '../core/layers.js';\nimport { getLayerOrder, CANONICAL_LAYER_NAMES } from '../core/layers.js';\nimport { getValidRelationships } from '../generated/relationship-index.js';\nimport { getLayerReportFileName } from './model-report-utils.js';\n\nexport class ModelLayerReportGenerator {\n  constructor(private modelVersion: string, private generatedAt: string) {}\n\n  /**\n   * Generate complete layer report markdown\n   */\n  generate(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n\n    // Document header\n    lines.push(this.generateHeader(data));\n\n    // Report Index (table of contents)\n    lines.push(this.generateTableOfContents(data));\n\n    // Layer Introduction + Statistics\n    lines.push(this.generateLayerIntroduction(data));\n\n    // Intra-Layer Relationships diagram\n    lines.push(this.generateIntraLayerDiagram(data));\n\n    // Inter-Layer Dependencies diagram\n    lines.push(this.generateInterLayerDiagram(data));\n\n    // Inter-Layer Relationships Table\n    lines.push(this.generateInterLayerTable(data));\n\n    // Element Reference section\n    lines.push(this.generateElementReference(data));\n\n    // Footer\n    lines.push(this.generateFooter());\n\n    return lines.join('');\n  }\n\n  private generateHeader(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push(`# ${formatLayerName(data.layerName)}\\n`);\n    lines.push('\\n');\n    lines.push('[\u2190 Back to README](../README.md)\\n');\n    lines.push('\\n');\n    lines.push(`${getLayerDescription(data.layerName)}\\n`);\n    lines.push('\\n');\n    return lines.join('');\n  }\n\n  private generateTableOfContents(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push('## Report Index\\n');\n    lines.push('\\n');\n\n    lines.push('- [Layer Introduction](#layer-introduction)\\n');\n    lines.push('- [Intra-Layer Relationships](#intra-layer-relationships)\\n');\n    lines.push('- [Inter-Layer Dependencies](#inter-layer-dependencies)\\n');\n\n    if (data.interRelationships.length > 0) {\n      lines.push('- [Inter-Layer Relationships Table](#inter-layer-relationships-table)\\n');\n    }\n\n    if (data.elements.length > 0) {\n      lines.push('- [Element Reference](#element-reference)\\n');\n    }\n\n    lines.push('\\n');\n    return lines.join('');\n  }\n\n  private generateLayerIntroduction(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push('## Layer Introduction\\n');\n    lines.push('\\n');\n\n    // Statistics table\n    const headers = ['Metric', 'Count'];\n    const rows = [\n      ['Elements', String(data.statistics.elementCount)],\n      ['Intra-Layer Relationships', String(data.statistics.intraRelationshipCount)],\n      ['Inter-Layer Relationships', String(data.statistics.interRelationshipCount)],\n      ['Inbound Relationships', String(data.statistics.inboundRelationshipCount)],\n      ['Outbound Relationships', String(data.statistics.outboundRelationshipCount)],\n    ];\n\n    const table = formatMarkdownTable(headers, rows);\n    lines.push(table);\n    lines.push('\\n');\n\n    // Upstream and downstream layers\n    if (data.upstreamLayers.length > 0 || data.downstreamLayers.length > 0) {\n      lines.push('**Cross-Layer References**:\\n');\n      lines.push('\\n');\n\n      if (data.upstreamLayers.length > 0) {\n        const upstreamLinks = data.upstreamLayers\n          .map((layerName) => this.createLayerLink(layerName))\n          .join(', ');\n        lines.push(`- **Upstream layers**: ${upstreamLinks}\\n`);\n      }\n\n      if (data.downstreamLayers.length > 0) {\n        const downstreamLinks = data.downstreamLayers\n          .map((layerName) => this.createLayerLink(layerName))\n          .join(', ');\n        lines.push(`- **Downstream layers**: ${downstreamLinks}\\n`);\n      }\n\n      lines.push('\\n');\n    }\n\n    return lines.join('');\n  }\n\n  private generateIntraLayerDiagram(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push('## Intra-Layer Relationships\\n');\n    lines.push('\\n');\n\n    // Empty layer handling\n    if (data.elements.length === 0) {\n      lines.push('No elements in this layer.\\n');\n      lines.push('\\n');\n      return lines.join('');\n    }\n\n    // Large layer fallback: For >30 elements, use summary table instead of Mermaid\n    // to prevent rendering failures\n    if (data.elements.length > 30) {\n      lines.push('*This layer has >30 elements. Summary table shown instead of diagram.*\\n');\n      lines.push('\\n');\n\n      const headers = ['Element', 'Type', 'Relationships'];\n      const rows: string[][] = [];\n\n      for (const element of data.elements) {\n        const relCount = data.intraRelationships.filter(\n          (rel) => rel.source === element.path || rel.target === element.path\n        ).length;\n\n        rows.push([\n          `\\`${escapeMarkdown(element.path)}\\``,\n          `\\`${escapeMarkdown(element.type)}\\``,\n          String(relCount),\n        ]);\n      }\n\n      const table = formatMarkdownTable(headers, rows);\n      lines.push(table);\n      lines.push('\\n');\n\n      return lines.join('');\n    }\n\n    // Generate mermaid diagram for layers with \u226430 elements\n    lines.push('```mermaid\\n');\n    lines.push('flowchart LR\\n');\n    lines.push(`  subgraph ${sanitizeMermaidId(data.layerName)}\\n`);\n\n    // Add all elements as nodes (use escapeMermaidLabel for correct Mermaid escaping)\n    for (const element of data.elements) {\n      const nodeId = sanitizeMermaidId(element.path);\n      const label = escapeMermaidLabel(element.name);\n      lines.push(`    ${nodeId}[\"${label}\"]\\n`);\n    }\n\n    // Add intra-layer relationships (sorted for deterministic output)\n    const sortedRelationships = [...data.intraRelationships].sort((a, b) => {\n      const aKey = `${a.source}-${a.predicate}-${a.target}`;\n      const bKey = `${b.source}-${b.predicate}-${b.target}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    for (const rel of sortedRelationships) {\n      const sourceId = sanitizeMermaidId(rel.source);\n      const targetId = sanitizeMermaidId(rel.target);\n      const predicate = escapeMermaidLabel(rel.predicate);\n      lines.push(`    ${sourceId} -->|${predicate}| ${targetId}\\n`);\n    }\n\n    lines.push('  end\\n');\n    lines.push('```\\n');\n    lines.push('\\n');\n\n    return lines.join('');\n  }\n\n  private generateInterLayerDiagram(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n    lines.push('## Inter-Layer Dependencies\\n');\n    lines.push('\\n');\n\n    // Empty layer handling\n    if (data.elements.length === 0) {\n      lines.push('No elements in this layer.\\n');\n      lines.push('\\n');\n      return lines.join('');\n    }\n\n    lines.push('```mermaid\\n');\n    lines.push('flowchart TB\\n');\n    lines.push('  classDef current fill:#f9f,stroke:#333,stroke-width:2px\\n');\n\n    // Add all layers as nodes\n    for (const layerName of CANONICAL_LAYER_NAMES) {\n      const layerId = sanitizeMermaidId(layerName);\n      const label = formatLayerName(layerName);\n      lines.push(`  ${layerId}[\"${label}\"]\\n`);\n    }\n\n    // Add layer-to-layer relationships for inter-layer dependencies\n    const addedRelationships = new Set<string>();\n    const layerRelationships: Array<{ sourceId: string; destId: string }> = [];\n\n    for (const rel of data.interRelationships) {\n      // Only include inter-layer relationships\n      if (rel.layer !== rel.targetLayer && rel.targetLayer) {\n        const key = `${rel.layer}-${rel.targetLayer}`;\n        if (!addedRelationships.has(key)) {\n          const sourceId = sanitizeMermaidId(rel.layer);\n          const destId = sanitizeMermaidId(rel.targetLayer);\n          layerRelationships.push({ sourceId, destId });\n          addedRelationships.add(key);\n        }\n      }\n    }\n\n    // Sort and output relationships for deterministic ordering\n    const sortedLayerRels = layerRelationships.sort((a, b) => {\n      const aKey = `${a.sourceId}-${a.destId}`;\n      const bKey = `${b.sourceId}-${b.destId}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    for (const { sourceId, destId } of sortedLayerRels) {\n      lines.push(`  ${sourceId} --> ${destId}\\n`);\n    }\n\n    // Highlight current layer\n    const currentLayerId = sanitizeMermaidId(data.layerName);\n    lines.push(`  class ${currentLayerId} current\\n`);\n\n    lines.push('```\\n');\n    lines.push('\\n');\n\n    return lines.join('');\n  }\n\n  private generateInterLayerTable(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n\n    if (data.interRelationships.length === 0) {\n      return '';\n    }\n\n    lines.push('## Inter-Layer Relationships Table\\n');\n    lines.push('\\n');\n\n    // Sort relationships for deterministic output\n    const sortedRels = [...data.interRelationships].sort((a, b) => {\n      const aKey = `${a.source}-${a.predicate}-${a.target}`;\n      const bKey = `${b.source}-${b.predicate}-${b.target}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    const headers = ['Relationship ID', 'Source Node', 'Dest Node', 'Dest Layer', 'Predicate', 'Cardinality', 'Strength'];\n    const rows: string[][] = [];\n\n    for (const rel of sortedRels) {\n      // Extract element types from paths (e.g., \"motivation.goal.customer-satisfaction\" -> \"motivation.goal\")\n      const sourceType = this.extractElementType(rel.source);\n      const targetType = this.extractElementType(rel.target);\n\n      // Look up spec-level relationship properties\n      const specs = getValidRelationships(sourceType, rel.predicate, targetType);\n      const cardinality = specs.length > 0 ? specs[0].cardinality : 'unknown';\n      const strength = specs.length > 0 ? specs[0].strength : 'unknown';\n\n      // Use spec relationship ID when available, fall back to concatenated form\n      const relationshipId = specs.length > 0 ? specs[0].id : `${rel.source}-${rel.predicate}-${rel.target}`;\n\n      rows.push([\n        `\\`${escapeMarkdown(relationshipId)}\\``,\n        `\\`${escapeMarkdown(rel.source)}\\``,\n        `\\`${escapeMarkdown(rel.target)}\\``,\n        rel.targetLayer ? `\\`${escapeMarkdown(rel.targetLayer)}\\`` : '\u2014',\n        `\\`${escapeMarkdown(rel.predicate)}\\``,\n        cardinality,\n        strength,\n      ]);\n    }\n\n    const table = formatMarkdownTable(headers, rows);\n    lines.push(table);\n    lines.push('\\n');\n\n    return lines.join('');\n  }\n\n  private generateElementReference(data: ModelLayerReportData): string {\n    const lines: string[] = [];\n\n    if (data.elements.length === 0) {\n      return '';\n    }\n\n    lines.push('## Element Reference\\n');\n    lines.push('\\n');\n\n    for (const element of data.elements) {\n      const anchor = createAnchor(element.name);\n      lines.push(`### ${escapeMarkdown(element.name)} {#${anchor}}\\n`);\n      lines.push('\\n');\n\n      // ID and type\n      lines.push(`**ID**: \\`${escapeMarkdown(element.path)}\\`\\n\\n`);\n      lines.push(`**Type**: \\`${escapeMarkdown(element.type)}\\`\\n\\n`);\n\n      // Description if available\n      if (element.description) {\n        lines.push(`${escapeMarkdown(element.description)}\\n\\n`);\n      }\n\n      // Attributes if available\n      if (Object.keys(element.attributes).length > 0) {\n        lines.push('#### Attributes\\n\\n');\n        const attrHeaders = ['Name', 'Value'];\n        const attrRows: string[][] = [];\n\n        // Sort attributes for deterministic output\n        const sortedAttrs = Object.entries(element.attributes).sort((a, b) =>\n          a[0].localeCompare(b[0])\n        );\n\n        for (const [name, value] of sortedAttrs) {\n          const valueStr = valueToMarkdown(value);\n          attrRows.push([name, valueStr]);\n        }\n\n        const attrTable = formatMarkdownTable(attrHeaders, attrRows);\n        lines.push(attrTable);\n        lines.push('\\n');\n      }\n\n      // Relationships involving this element\n      const elementRels = this.getElementRelationships(data, element.path);\n      if (elementRels.length > 0) {\n        lines.push('#### Relationships\\n\\n');\n        const relHeaders = ['Type', 'Related Element', 'Predicate', 'Direction'];\n        const relRows: string[][] = [];\n\n        // Sort for deterministic output\n        const sortedElementRels = [...elementRels].sort((a, b) => {\n          const aKey = `${a.relType}-${a.rel.source}-${a.rel.predicate}-${a.rel.target}`;\n          const bKey = `${b.relType}-${b.rel.source}-${b.rel.predicate}-${b.rel.target}`;\n          return aKey.localeCompare(bKey);\n        });\n\n        for (const { rel, relType } of sortedElementRels) {\n          const relatedElement = rel.source === element.path ? rel.target : rel.source;\n          const direction = rel.source === element.path ? 'outbound' : 'inbound';\n\n          relRows.push([\n            relType,\n            `\\`${escapeMarkdown(relatedElement)}\\``,\n            `\\`${escapeMarkdown(rel.predicate)}\\``,\n            direction,\n          ]);\n        }\n\n        const relTable = formatMarkdownTable(relHeaders, relRows);\n        lines.push(relTable);\n        lines.push('\\n');\n      }\n    }\n\n    return lines.join('');\n  }\n\n  private generateFooter(): string {\n    const lines: string[] = [];\n    lines.push('---\\n');\n    lines.push('\\n');\n    lines.push(`Generated: ${this.generatedAt} | Model Version: ${this.modelVersion}\\n`);\n    return lines.join('');\n  }\n\n  /**\n   * Create a markdown link to a layer report\n   */\n  private createLayerLink(layerName: string): string {\n    const layerNumber = getLayerOrder(layerName);\n    if (layerNumber === -1) {\n      return layerName;\n    }\n    const filename = `./${getLayerReportFileName(layerName as CanonicalLayerName)}`;\n    return `[${formatLayerName(layerName)}](${filename})`;\n  }\n\n  /**\n   * Get relationships involving a specific element\n   */\n  private getElementRelationships(\n    data: ModelLayerReportData,\n    elementPath: string\n  ): Array<{ rel: Relationship; relType: 'intra-layer' | 'inter-layer' }> {\n    const rels: Array<{ rel: Relationship; relType: 'intra-layer' | 'inter-layer' }> = [];\n\n    // Intra-layer relationships\n    for (const rel of data.intraRelationships) {\n      if (rel.source === elementPath || rel.target === elementPath) {\n        rels.push({ rel, relType: 'intra-layer' });\n      }\n    }\n\n    // Inter-layer relationships\n    for (const rel of data.interRelationships) {\n      if (rel.source === elementPath || rel.target === elementPath) {\n        rels.push({ rel, relType: 'inter-layer' });\n      }\n    }\n\n    return rels;\n  }\n\n  /**\n   * Extract element type from element path in layer.type format\n   * Example: \"motivation.goal.customer-satisfaction\" -> \"motivation.goal\"\n   * This format matches the keys in RELATIONSHIPS_BY_SOURCE map.\n   */\n  private extractElementType(elementPath: string): string {\n    const parts = elementPath.split('.');\n    if (parts.length >= 2) {\n      return parts.slice(0, 2).join('.');\n    }\n    return elementPath;\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/reports/model-readme-generator.js

@@ -0,0 +1,116 @@
+import { formatLayerName } from "../utils/layer-name-formatter.js";
+import { formatMarkdownTable } from "../utils/markdown-table.js";
+import { escapeMarkdown } from "../export/markdown-utils.js";
+class ModelReadmeGenerator {
+  generatedAt;
+  constructor(generatedAt) {
+    this.generatedAt = generatedAt;
+  }
+  /**
+   * Generate complete model README markdown
+   */
+  generate(data) {
+    const lines = [];
+    return lines.push(this.generateHeader(data)), lines.push(this.generateStatistics(data)), lines.push(this.generateProjectSummary(data)), lines.push(this.generateIntroduction()), lines.push(this.generateLayerIndex(data)), lines.push(this.generateFooter(data)), lines.join("");
+  }
+  generateHeader(data) {
+    const lines = [];
+    return lines.push(`# ${escapeMarkdown(data.projectName)}
+`), lines.push(`
+`), lines.join("");
+  }
+  generateStatistics(data) {
+    const lines = [];
+    lines.push(`## Model Statistics
+`), lines.push(`
+`);
+    const headers = ["Metric", "Value"], rows = [
+      ["Total Elements", String(data.totalElements)],
+      ["Total Relationships", String(data.totalRelationships)],
+      ["Populated Layers", String(data.populatedLayerCount)],
+      ["Last Updated", data.lastUpdated],
+      ["CLI Version", data.cliVersion]
+    ];
+    data.specVersion && rows.push(["Spec Version", data.specVersion]);
+    const table = formatMarkdownTable(headers, rows);
+    return lines.push(table), lines.push(`
+`), lines.join("");
+  }
+  generateProjectSummary(data) {
+    const lines = [];
+    lines.push(`## Project Summary
+`), lines.push(`
+`), data.projectDescription && lines.push(`${escapeMarkdown(data.projectDescription)}
+
+`);
+    const populatedLayers = data.layers.filter((l) => l.elementCount > 0);
+    if (populatedLayers.length > 0) {
+      lines.push(`**Populated Layers**:
+
+`);
+      const layerNames = populatedLayers.map((l) => `- ${formatLayerName(l.layerName)}`).join(`
+`);
+      lines.push(`${layerNames}
+
+`);
+    }
+    return lines.join("");
+  }
+  generateIntroduction() {
+    const lines = [];
+    lines.push(`## About Documentation Robotics
+`), lines.push(`
+`), lines.push(`Documentation Robotics is a toolkit for managing federated architecture data models across 13 interconnected layers. It provides a structured approach to documenting systems architecture by organizing elements and relationships across distinct layers that represent different concerns: from business motivation and strategy through to technology infrastructure and testing.
+
+`), lines.push(`### The 13-Layer Architecture Model
+
+`);
+    const layerDescriptions = [
+      "1. **Motivation** - Goals, requirements, drivers, and strategic outcomes",
+      "2. **Business** - Business processes, functions, roles, and services",
+      "3. **Product** - Product features, capabilities, personas, and milestones",
+      "4. **Security** - Authentication, authorization, threats, and controls",
+      "5. **Application** - Application components, services, and interactions",
+      "6. **Technology** - Infrastructure, platforms, and technology components",
+      "7. **API** - REST APIs, operations, and endpoints",
+      "8. **Data Model** - Data entities, relationships, and structure definitions",
+      "9. **Data Store** - Databases and persistence mechanisms",
+      "10. **UX** - User interface components and user experience elements",
+      "11. **Navigation** - Application routing and navigation flows",
+      "12. **APM** - Observability, monitoring, metrics, and tracing",
+      "13. **Testing** - Test strategies, test cases, and test coverage"
+    ];
+    return lines.push(layerDescriptions.join(`
+`)), lines.push(`
+
+`), lines.push(`Each layer is independently managed but interconnected, allowing elements in higher layers to reference elements in lower layers, creating a comprehensive dependency graph that ensures architectural coherence and traceability across all concerns.
+
+`), lines.join("");
+  }
+  generateLayerIndex(data) {
+    const lines = [];
+    lines.push(`## Layer Reports
+`), lines.push(`
+`);
+    const headers = ["Layer", "Elements", "Report"], rows = [], sortedLayers = [...data.layers].sort((a, b) => a.layerNumber - b.layerNumber);
+    for (const layer of sortedLayers) {
+      const layerName = formatLayerName(layer.layerName), elementCount = String(layer.elementCount);
+      let report;
+      layer.elementCount > 0 ? report = `[${layer.reportFileName}](./reports/${layer.reportFileName})` : report = "\u2014", rows.push([layerName, elementCount, report]);
+    }
+    const table = formatMarkdownTable(headers, rows);
+    return lines.push(table), lines.push(`
+`), lines.join("");
+  }
+  generateFooter(data) {
+    const lines = [];
+    return lines.push(`---
+`), lines.push(`
+`), lines.push(`Generated: ${this.generatedAt} | Model Version: ${data.modelVersion}
+`), lines.join("");
+  }
+}
+export {
+  ModelReadmeGenerator
+};
+//# sourceMappingURL=model-readme-generator.js.map

package/dist/reports/model-readme-generator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/reports/model-readme-generator.ts"],
+  "sourcesContent": ["/**\n * Model README Generator\n *\n * Generates the main README.md for the model documentation with:\n * - Model statistics (elements, relationships, versions)\n * - Project summary\n * - Introduction to documentation robotics\n * - Per-layer report index table\n */\n\nimport type { ModelReadmeData } from './model-report-data.js';\nimport { formatLayerName } from '../utils/layer-name-formatter.js';\nimport { formatMarkdownTable } from '../utils/markdown-table.js';\nimport { escapeMarkdown } from '../export/markdown-utils.js';\n\nexport class ModelReadmeGenerator {\n  constructor(private generatedAt: string) {}\n\n  /**\n   * Generate complete model README markdown\n   */\n  generate(data: ModelReadmeData): string {\n    const lines: string[] = [];\n\n    // Header with project name\n    lines.push(this.generateHeader(data));\n\n    // Statistics section\n    lines.push(this.generateStatistics(data));\n\n    // Project summary\n    lines.push(this.generateProjectSummary(data));\n\n    // Documentation robotics introduction\n    lines.push(this.generateIntroduction());\n\n    // Layer index table\n    lines.push(this.generateLayerIndex(data));\n\n    // Footer\n    lines.push(this.generateFooter(data));\n\n    return lines.join('');\n  }\n\n  private generateHeader(data: ModelReadmeData): string {\n    const lines: string[] = [];\n    lines.push(`# ${escapeMarkdown(data.projectName)}\\n`);\n    lines.push('\\n');\n    return lines.join('');\n  }\n\n  private generateStatistics(data: ModelReadmeData): string {\n    const lines: string[] = [];\n    lines.push('## Model Statistics\\n');\n    lines.push('\\n');\n\n    const headers = ['Metric', 'Value'];\n    const rows = [\n      ['Total Elements', String(data.totalElements)],\n      ['Total Relationships', String(data.totalRelationships)],\n      ['Populated Layers', String(data.populatedLayerCount)],\n      ['Last Updated', data.lastUpdated],\n      ['CLI Version', data.cliVersion],\n    ];\n\n    // Add spec version if available\n    if (data.specVersion) {\n      rows.push(['Spec Version', data.specVersion]);\n    }\n\n    const table = formatMarkdownTable(headers, rows);\n    lines.push(table);\n    lines.push('\\n');\n\n    return lines.join('');\n  }\n\n  private generateProjectSummary(data: ModelReadmeData): string {\n    const lines: string[] = [];\n    lines.push('## Project Summary\\n');\n    lines.push('\\n');\n\n    // Project description if available\n    if (data.projectDescription) {\n      lines.push(`${escapeMarkdown(data.projectDescription)}\\n\\n`);\n    }\n\n    // Layer population summary\n    const populatedLayers = data.layers.filter(l => l.elementCount > 0);\n    if (populatedLayers.length > 0) {\n      lines.push('**Populated Layers**:\\n\\n');\n      const layerNames = populatedLayers\n        .map(l => `- ${formatLayerName(l.layerName)}`)\n        .join('\\n');\n      lines.push(`${layerNames}\\n\\n`);\n    }\n\n    return lines.join('');\n  }\n\n  private generateIntroduction(): string {\n    const lines: string[] = [];\n    lines.push('## About Documentation Robotics\\n');\n    lines.push('\\n');\n    lines.push(\n      'Documentation Robotics is a toolkit for managing federated architecture data models across 13 interconnected layers. ' +\n      'It provides a structured approach to documenting systems architecture by organizing elements and relationships across ' +\n      'distinct layers that represent different concerns: from business motivation and strategy through to technology infrastructure and testing.\\n\\n'\n    );\n\n    lines.push('### The 13-Layer Architecture Model\\n\\n');\n\n    const layerDescriptions = [\n      '1. **Motivation** - Goals, requirements, drivers, and strategic outcomes',\n      '2. **Business** - Business processes, functions, roles, and services',\n      '3. **Product** - Product features, capabilities, personas, and milestones',\n      '4. **Security** - Authentication, authorization, threats, and controls',\n      '5. **Application** - Application components, services, and interactions',\n      '6. **Technology** - Infrastructure, platforms, and technology components',\n      '7. **API** - REST APIs, operations, and endpoints',\n      '8. **Data Model** - Data entities, relationships, and structure definitions',\n      '9. **Data Store** - Databases and persistence mechanisms',\n      '10. **UX** - User interface components and user experience elements',\n      '11. **Navigation** - Application routing and navigation flows',\n      '12. **APM** - Observability, monitoring, metrics, and tracing',\n      '13. **Testing** - Test strategies, test cases, and test coverage',\n    ];\n\n    lines.push(layerDescriptions.join('\\n'));\n    lines.push('\\n\\n');\n\n    lines.push(\n      'Each layer is independently managed but interconnected, allowing elements in higher layers to reference elements in lower layers, ' +\n      'creating a comprehensive dependency graph that ensures architectural coherence and traceability across all concerns.\\n\\n'\n    );\n\n    return lines.join('');\n  }\n\n  private generateLayerIndex(data: ModelReadmeData): string {\n    const lines: string[] = [];\n    lines.push('## Layer Reports\\n');\n    lines.push('\\n');\n\n    const headers = ['Layer', 'Elements', 'Report'];\n    const rows: string[][] = [];\n\n    // Sort layers by layer number for consistent ordering\n    const sortedLayers = [...data.layers].sort((a, b) => a.layerNumber - b.layerNumber);\n\n    for (const layer of sortedLayers) {\n      const layerName = formatLayerName(layer.layerName);\n      const elementCount = String(layer.elementCount);\n\n      let report: string;\n      if (layer.elementCount > 0) {\n        // Create link to layer report (in reports/ subdirectory)\n        report = `[${layer.reportFileName}](./reports/${layer.reportFileName})`;\n      } else {\n        // No link for empty layers\n        report = '\u2014';\n      }\n\n      rows.push([layerName, elementCount, report]);\n    }\n\n    const table = formatMarkdownTable(headers, rows);\n    lines.push(table);\n    lines.push('\\n');\n\n    return lines.join('');\n  }\n\n  private generateFooter(data: ModelReadmeData): string {\n    const lines: string[] = [];\n    lines.push('---\\n');\n    lines.push('\\n');\n    lines.push(`Generated: ${this.generatedAt} | Model Version: ${data.modelVersion}\\n`);\n    return lines.join('');\n  }\n}\n"],
+  "mappings": "AAWA,SAAS,uBAAuB;AAChC,SAAS,2BAA2B;AACpC,SAAS,sBAAsB;AAEzB,MAAO,qBAAoB;EACX;EAApB,YAAoB,aAAmB;AAAnB,SAAA,cAAA;EAAsB;;;;EAK1C,SAAS,MAAqB;AAC5B,UAAM,QAAkB,CAAA;AAGxB,iBAAM,KAAK,KAAK,eAAe,IAAI,CAAC,GAGpC,MAAM,KAAK,KAAK,mBAAmB,IAAI,CAAC,GAGxC,MAAM,KAAK,KAAK,uBAAuB,IAAI,CAAC,GAG5C,MAAM,KAAK,KAAK,qBAAoB,CAAE,GAGtC,MAAM,KAAK,KAAK,mBAAmB,IAAI,CAAC,GAGxC,MAAM,KAAK,KAAK,eAAe,IAAI,CAAC,GAE7B,MAAM,KAAK,EAAE;EACtB;EAEQ,eAAe,MAAqB;AAC1C,UAAM,QAAkB,CAAA;AACxB,iBAAM,KAAK,KAAK,eAAe,KAAK,WAAW,CAAC;CAAI,GACpD,MAAM,KAAK;CAAI,GACR,MAAM,KAAK,EAAE;EACtB;EAEQ,mBAAmB,MAAqB;AAC9C,UAAM,QAAkB,CAAA;AACxB,UAAM,KAAK;CAAuB,GAClC,MAAM,KAAK;CAAI;AAEf,UAAM,UAAU,CAAC,UAAU,OAAO,GAC5B,OAAO;MACX,CAAC,kBAAkB,OAAO,KAAK,aAAa,CAAC;MAC7C,CAAC,uBAAuB,OAAO,KAAK,kBAAkB,CAAC;MACvD,CAAC,oBAAoB,OAAO,KAAK,mBAAmB,CAAC;MACrD,CAAC,gBAAgB,KAAK,WAAW;MACjC,CAAC,eAAe,KAAK,UAAU;;AAIjC,IAAI,KAAK,eACP,KAAK,KAAK,CAAC,gBAAgB,KAAK,WAAW,CAAC;AAG9C,UAAM,QAAQ,oBAAoB,SAAS,IAAI;AAC/C,iBAAM,KAAK,KAAK,GAChB,MAAM,KAAK;CAAI,GAER,MAAM,KAAK,EAAE;EACtB;EAEQ,uBAAuB,MAAqB;AAClD,UAAM,QAAkB,CAAA;AACxB,UAAM,KAAK;CAAsB,GACjC,MAAM,KAAK;CAAI,GAGX,KAAK,sBACP,MAAM,KAAK,GAAG,eAAe,KAAK,kBAAkB,CAAC;;CAAM;AAI7D,UAAM,kBAAkB,KAAK,OAAO,OAAO,OAAK,EAAE,eAAe,CAAC;AAClE,QAAI,gBAAgB,SAAS,GAAG;AAC9B,YAAM,KAAK;;CAA2B;AACtC,YAAM,aAAa,gBAChB,IAAI,OAAK,KAAK,gBAAgB,EAAE,SAAS,CAAC,EAAE,EAC5C,KAAK;CAAI;AACZ,YAAM,KAAK,GAAG,UAAU;;CAAM;IAChC;AAEA,WAAO,MAAM,KAAK,EAAE;EACtB;EAEQ,uBAAoB;AAC1B,UAAM,QAAkB,CAAA;AACxB,UAAM,KAAK;CAAmC,GAC9C,MAAM,KAAK;CAAI,GACf,MAAM,KACJ;;CAEgJ,GAGlJ,MAAM,KAAK;;CAAyC;AAEpD,UAAM,oBAAoB;MACxB;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;;AAGF,iBAAM,KAAK,kBAAkB,KAAK;CAAI,CAAC,GACvC,MAAM,KAAK;;CAAM,GAEjB,MAAM,KACJ;;CAC0H,GAGrH,MAAM,KAAK,EAAE;EACtB;EAEQ,mBAAmB,MAAqB;AAC9C,UAAM,QAAkB,CAAA;AACxB,UAAM,KAAK;CAAoB,GAC/B,MAAM,KAAK;CAAI;AAEf,UAAM,UAAU,CAAC,SAAS,YAAY,QAAQ,GACxC,OAAmB,CAAA,GAGnB,eAAe,CAAC,GAAG,KAAK,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,cAAc,EAAE,WAAW;AAElF,eAAW,SAAS,cAAc;AAChC,YAAM,YAAY,gBAAgB,MAAM,SAAS,GAC3C,eAAe,OAAO,MAAM,YAAY;AAE9C,UAAI;AACJ,MAAI,MAAM,eAAe,IAEvB,SAAS,IAAI,MAAM,cAAc,eAAe,MAAM,cAAc,MAGpE,SAAS,UAGX,KAAK,KAAK,CAAC,WAAW,cAAc,MAAM,CAAC;IAC7C;AAEA,UAAM,QAAQ,oBAAoB,SAAS,IAAI;AAC/C,iBAAM,KAAK,KAAK,GAChB,MAAM,KAAK;CAAI,GAER,MAAM,KAAK,EAAE;EACtB;EAEQ,eAAe,MAAqB;AAC1C,UAAM,QAAkB,CAAA;AACxB,iBAAM,KAAK;CAAO,GAClB,MAAM,KAAK;CAAI,GACf,MAAM,KAAK,cAAc,KAAK,WAAW,qBAAqB,KAAK,YAAY;CAAI,GAC5E,MAAM,KAAK,EAAE;EACtB;;",
+  "names": []
+}

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

@@ -1,5 +1,7 @@
 import { Element } from "../core/element.js";
-import { getLayerOrder, isValidLayerName } from "../core/layers.js";
+import { getLayerOrder, CANONICAL_LAYER_NAMES, isValidLayerName } from "../core/layers.js";
+import { getCliVersion } from "../utils/spec-version.js";
+import { getLayerReportFileName } from "./model-report-utils.js";
 class ModelReportDataCollector {
   /**
    * Collect report data for a specific layer
@@ -50,6 +52,40 @@ class ModelReportDataCollector {
       statistics
     };
   }
+  /**
+   * Collect aggregated model-wide data for the model README
+   *
+   * @param model - The live Model instance
+   * @returns Aggregated model-wide data including project metadata, per-layer summaries, and statistics
+   */
+  collectModelData(model) {
+    const layers = [];
+    let totalElements = 0;
+    for (const layerName of CANONICAL_LAYER_NAMES) {
+      const elementCount = model.graph.getNodesByLayer(layerName).length;
+      totalElements += elementCount;
+      const layerNumber = getLayerOrder(layerName), reportFileName = getLayerReportFileName(layerName);
+      layers.push({
+        layerName,
+        layerNumber,
+        elementCount,
+        reportFileName
+      });
+    }
+    const totalRelationships = model.relationships.getAll().length, populatedLayerCount = layers.filter((l) => l.elementCount > 0).length;
+    return {
+      projectName: model.manifest.name,
+      projectDescription: model.manifest.description,
+      modelVersion: model.manifest.version,
+      cliVersion: model.manifest.cliVersion || getCliVersion(),
+      specVersion: model.manifest.specVersion,
+      lastUpdated: model.manifest.modified,
+      totalElements,
+      totalRelationships,
+      populatedLayerCount,
+      layers
+    };
+  }
 }
 export {
   ModelReportDataCollector

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/reports/model-report-data.ts"],
-  "sourcesContent": ["import type { Model } from '../core/model.js';\nimport { Element } from '../core/element.js';\nimport type { Relationship } from '../core/relationships.js';\nimport { getLayerOrder, type CanonicalLayerName, isValidLayerName } from '../core/layers.js';\n\n/**\n * Statistics about relationships in a layer\n */\nexport interface ModelLayerStatistics {\n  elementCount: number;\n  intraRelationshipCount: number;\n  interRelationshipCount: number;\n  inboundRelationshipCount: number;   // inter-layer rels targeting this layer\n  outboundRelationshipCount: number;  // inter-layer rels sourced from this layer\n}\n\n/**\n * Report-friendly data structure for a single layer\n * Analogous to ReportDataModel in scripts/generate-layer-reports.ts\n */\nexport interface ModelLayerReportData {\n  layerName: CanonicalLayerName;\n  layerNumber: number;\n  elements: Element[];                        // sorted by element.path\n  intraRelationships: Relationship[];         // both source and target in same layer\n  interRelationships: Relationship[];         // source or target in a different layer\n  upstreamLayers: CanonicalLayerName[];       // canonical layer names referencing INTO this layer\n  downstreamLayers: CanonicalLayerName[];     // canonical layer names this layer references OUT TO\n  statistics: ModelLayerStatistics;\n}\n\n/**\n * Data collector for generating layer report data from a live Model instance\n * Reads from Model/Layer/Relationships and transforms into report-friendly shapes\n */\nexport class ModelReportDataCollector {\n  /**\n   * Collect report data for a specific layer\n   *\n   * @param model - The live Model instance\n   * @param layerName - The canonical layer name (e.g., 'api', 'data-model')\n   * @returns Report-friendly data structure for the layer\n   */\n  collectLayerData(model: Model, layerName: CanonicalLayerName): ModelLayerReportData {\n    // Get the layer number for file naming\n    const layerNumber = getLayerOrder(layerName);\n\n    // Get all elements in this layer using GraphModel's indexed lookup for O(1) layer-scoped access\n    // Convert GraphNodes to Elements for report-friendly shape\n    const graphNodes = model.graph.getNodesByLayer(layerName);\n    const elements: Element[] = graphNodes\n      .map(\n        (node) =>\n          new Element({\n            id: node.uuid || node.id,\n            path: node.id,\n            spec_node_id: node.spec_node_id || '',\n            type: node.type,\n            layer_id: node.layer,\n            name: node.name,\n            description: node.description,\n            attributes: node.attributes,\n            source_reference: node.source_reference,\n            metadata: node.metadata,\n          })\n      )\n      .sort((a, b) => (a.path || a.id).localeCompare(b.path || b.id));\n\n    // Get all relationships and classify them\n    const allRelationships = model.relationships.getAll();\n\n    // Filter relationships involving this layer\n    const allRelatingRelationships = allRelationships.filter(\n      r => r.layer === layerName || r.targetLayer === layerName\n    );\n\n    // Intra-layer relationships: both source and target in same layer\n    // Note: Relationships with missing targetLayer are treated as intra-layer because targetLayer is\n    // typically only populated for inter-layer relationships during persistence and loading.\n    const intraRelationships = allRelatingRelationships.filter(\n      r => r.layer === layerName && (r.targetLayer === layerName || !r.targetLayer)\n    );\n\n    // Inter-layer relationships: source or target in different layer (or other endpoint exists)\n    const interRelationships = allRelatingRelationships.filter(\n      r => !(r.layer === layerName && (r.targetLayer === layerName || !r.targetLayer))\n    );\n\n    // Compute upstream and downstream layers from inter-layer relationships\n    const upstreamLayerSet = new Set<CanonicalLayerName>();\n    const downstreamLayerSet = new Set<CanonicalLayerName>();\n    let inboundRelationshipCount = 0;\n    let outboundRelationshipCount = 0;\n\n    for (const rel of interRelationships) {\n      // Upstream: layers that have relationships targeting THIS layer\n      if (rel.targetLayer === layerName && rel.layer !== layerName) {\n        // Validate layer name before casting (defensive: guards against user-editable YAML with invalid layer names)\n        if (isValidLayerName(rel.layer)) {\n          upstreamLayerSet.add(rel.layer);\n          inboundRelationshipCount++;\n        } else {\n          console.warn(`Skipping invalid layer name in relationship: ${rel.layer}`);\n        }\n      }\n      // Downstream: layers that THIS layer references\n      if (rel.layer === layerName && rel.targetLayer && rel.targetLayer !== layerName) {\n        // Validate layer name before casting (defensive: guards against user-editable YAML with invalid layer names)\n        if (isValidLayerName(rel.targetLayer)) {\n          downstreamLayerSet.add(rel.targetLayer);\n          outboundRelationshipCount++;\n        } else {\n          console.warn(`Skipping invalid layer name in relationship: ${rel.targetLayer}`);\n        }\n      }\n    }\n\n    // Sort upstream and downstream layers\n    const upstreamLayers = Array.from(upstreamLayerSet).sort();\n    const downstreamLayers = Array.from(downstreamLayerSet).sort();\n\n    // Sort relationships deterministically by \"${source}-${predicate}-${target}\"\n    intraRelationships.sort((a, b) => {\n      const aKey = `${a.source}-${a.predicate}-${a.target}`;\n      const bKey = `${b.source}-${b.predicate}-${b.target}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    interRelationships.sort((a, b) => {\n      const aKey = `${a.source}-${a.predicate}-${a.target}`;\n      const bKey = `${b.source}-${b.predicate}-${b.target}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    // Build statistics\n    const statistics: ModelLayerStatistics = {\n      elementCount: elements.length,\n      intraRelationshipCount: intraRelationships.length,\n      interRelationshipCount: interRelationships.length,\n      inboundRelationshipCount,\n      outboundRelationshipCount,\n    };\n\n    return {\n      layerName,\n      layerNumber,\n      elements,\n      intraRelationships,\n      interRelationships,\n      upstreamLayers,\n      downstreamLayers,\n      statistics,\n    };\n  }\n}\n"],
-  "mappings": "AACA,SAAS,eAAe;AAExB,SAAS,eAAwC,wBAAwB;AAgCnE,MAAO,yBAAwB;;;;;;;;EAQnC,iBAAiB,OAAc,WAA6B;AAE1D,UAAM,cAAc,cAAc,SAAS,GAKrC,WADa,MAAM,MAAM,gBAAgB,SAAS,EAErD,IACC,CAAC,SACC,IAAI,QAAQ;MACV,IAAI,KAAK,QAAQ,KAAK;MACtB,MAAM,KAAK;MACX,cAAc,KAAK,gBAAgB;MACnC,MAAM,KAAK;MACX,UAAU,KAAK;MACf,MAAM,KAAK;MACX,aAAa,KAAK;MAClB,YAAY,KAAK;MACjB,kBAAkB,KAAK;MACvB,UAAU,KAAK;KAChB,CAAC,EAEL,KAAK,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAI,cAAc,EAAE,QAAQ,EAAE,EAAE,CAAC,GAM1D,2BAHmB,MAAM,cAAc,OAAM,EAGD,OAChD,OAAK,EAAE,UAAU,aAAa,EAAE,gBAAgB,SAAS,GAMrD,qBAAqB,yBAAyB,OAClD,OAAK,EAAE,UAAU,cAAc,EAAE,gBAAgB,aAAa,CAAC,EAAE,YAAY,GAIzE,qBAAqB,yBAAyB,OAClD,OAAK,EAAE,EAAE,UAAU,cAAc,EAAE,gBAAgB,aAAa,CAAC,EAAE,aAAa,GAI5E,mBAAmB,oBAAI,IAAG,GAC1B,qBAAqB,oBAAI,IAAG;AAClC,QAAI,2BAA2B,GAC3B,4BAA4B;AAEhC,eAAW,OAAO;AAEhB,MAAI,IAAI,gBAAgB,aAAa,IAAI,UAAU,cAE7C,iBAAiB,IAAI,KAAK,KAC5B,iBAAiB,IAAI,IAAI,KAAK,GAC9B,8BAEA,QAAQ,KAAK,gDAAgD,IAAI,KAAK,EAAE,IAIxE,IAAI,UAAU,aAAa,IAAI,eAAe,IAAI,gBAAgB,cAEhE,iBAAiB,IAAI,WAAW,KAClC,mBAAmB,IAAI,IAAI,WAAW,GACtC,+BAEA,QAAQ,KAAK,gDAAgD,IAAI,WAAW,EAAE;AAMpF,UAAM,iBAAiB,MAAM,KAAK,gBAAgB,EAAE,KAAI,GAClD,mBAAmB,MAAM,KAAK,kBAAkB,EAAE,KAAI;AAG5D,uBAAmB,KAAK,CAAC,GAAG,MAAK;AAC/B,YAAM,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,SAAS,IAAI,EAAE,MAAM,IAC7C,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,SAAS,IAAI,EAAE,MAAM;AACnD,aAAO,KAAK,cAAc,IAAI;IAChC,CAAC,GAED,mBAAmB,KAAK,CAAC,GAAG,MAAK;AAC/B,YAAM,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,SAAS,IAAI,EAAE,MAAM,IAC7C,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,SAAS,IAAI,EAAE,MAAM;AACnD,aAAO,KAAK,cAAc,IAAI;IAChC,CAAC;AAGD,UAAM,aAAmC;MACvC,cAAc,SAAS;MACvB,wBAAwB,mBAAmB;MAC3C,wBAAwB,mBAAmB;MAC3C;MACA;;AAGF,WAAO;MACL;MACA;MACA;MACA;MACA;MACA;MACA;MACA;;EAEJ;;",
+  "sourcesContent": ["import type { Model } from '../core/model.js';\nimport { Element } from '../core/element.js';\nimport type { Relationship } from '../core/relationships.js';\nimport { getLayerOrder, CANONICAL_LAYER_NAMES, type CanonicalLayerName, isValidLayerName } from '../core/layers.js';\nimport { getCliVersion } from '../utils/spec-version.js';\nimport { getLayerReportFileName } from './model-report-utils.js';\n\n/**\n * Statistics about relationships in a layer\n */\nexport interface ModelLayerStatistics {\n  elementCount: number;\n  intraRelationshipCount: number;\n  interRelationshipCount: number;\n  inboundRelationshipCount: number;   // inter-layer rels targeting this layer\n  outboundRelationshipCount: number;  // inter-layer rels sourced from this layer\n}\n\n/**\n * Report-friendly data structure for a single layer\n * Analogous to ReportDataModel in scripts/generate-layer-reports.ts\n */\nexport interface ModelLayerReportData {\n  layerName: CanonicalLayerName;\n  layerNumber: number;\n  elements: Element[];                        // sorted by element.path\n  intraRelationships: Relationship[];         // both source and target in same layer\n  interRelationships: Relationship[];         // source or target in a different layer\n  upstreamLayers: CanonicalLayerName[];       // canonical layer names referencing INTO this layer\n  downstreamLayers: CanonicalLayerName[];     // canonical layer names this layer references OUT TO\n  statistics: ModelLayerStatistics;\n}\n\n/**\n * Per-layer summary for the model README\n */\nexport interface ModelReadmeLayerSummary {\n  layerName: CanonicalLayerName;\n  layerNumber: number;\n  elementCount: number;\n  reportFileName: string;\n}\n\n/**\n * Aggregated model-wide data for the model README\n */\nexport interface ModelReadmeData {\n  projectName: string;\n  projectDescription?: string;\n  modelVersion: string;\n  cliVersion: string;\n  specVersion?: string;\n  lastUpdated: string;\n  totalElements: number;\n  totalRelationships: number;\n  populatedLayerCount: number;\n  layers: ModelReadmeLayerSummary[];\n}\n\n/**\n * Data collector for generating layer report data from a live Model instance\n * Reads from Model/Layer/Relationships and transforms into report-friendly shapes\n */\nexport class ModelReportDataCollector {\n  /**\n   * Collect report data for a specific layer\n   *\n   * @param model - The live Model instance\n   * @param layerName - The canonical layer name (e.g., 'api', 'data-model')\n   * @returns Report-friendly data structure for the layer\n   */\n  collectLayerData(model: Model, layerName: CanonicalLayerName): ModelLayerReportData {\n    // Get the layer number for file naming\n    const layerNumber = getLayerOrder(layerName);\n\n    // Get all elements in this layer using GraphModel's indexed lookup for O(1) layer-scoped access\n    // Convert GraphNodes to Elements for report-friendly shape\n    const graphNodes = model.graph.getNodesByLayer(layerName);\n    const elements: Element[] = graphNodes\n      .map(\n        (node) =>\n          new Element({\n            id: node.uuid || node.id,\n            path: node.id,\n            spec_node_id: node.spec_node_id || '',\n            type: node.type,\n            layer_id: node.layer,\n            name: node.name,\n            description: node.description,\n            attributes: node.attributes,\n            source_reference: node.source_reference,\n            metadata: node.metadata,\n          })\n      )\n      .sort((a, b) => (a.path || a.id).localeCompare(b.path || b.id));\n\n    // Get all relationships and classify them\n    const allRelationships = model.relationships.getAll();\n\n    // Filter relationships involving this layer\n    const allRelatingRelationships = allRelationships.filter(\n      r => r.layer === layerName || r.targetLayer === layerName\n    );\n\n    // Intra-layer relationships: both source and target in same layer\n    // Note: Relationships with missing targetLayer are treated as intra-layer because targetLayer is\n    // typically only populated for inter-layer relationships during persistence and loading.\n    const intraRelationships = allRelatingRelationships.filter(\n      r => r.layer === layerName && (r.targetLayer === layerName || !r.targetLayer)\n    );\n\n    // Inter-layer relationships: source or target in different layer (or other endpoint exists)\n    const interRelationships = allRelatingRelationships.filter(\n      r => !(r.layer === layerName && (r.targetLayer === layerName || !r.targetLayer))\n    );\n\n    // Compute upstream and downstream layers from inter-layer relationships\n    const upstreamLayerSet = new Set<CanonicalLayerName>();\n    const downstreamLayerSet = new Set<CanonicalLayerName>();\n    let inboundRelationshipCount = 0;\n    let outboundRelationshipCount = 0;\n\n    for (const rel of interRelationships) {\n      // Upstream: layers that have relationships targeting THIS layer\n      if (rel.targetLayer === layerName && rel.layer !== layerName) {\n        // Validate layer name before casting (defensive: guards against user-editable YAML with invalid layer names)\n        if (isValidLayerName(rel.layer)) {\n          upstreamLayerSet.add(rel.layer);\n          inboundRelationshipCount++;\n        } else {\n          console.warn(`Skipping invalid layer name in relationship: ${rel.layer}`);\n        }\n      }\n      // Downstream: layers that THIS layer references\n      if (rel.layer === layerName && rel.targetLayer && rel.targetLayer !== layerName) {\n        // Validate layer name before casting (defensive: guards against user-editable YAML with invalid layer names)\n        if (isValidLayerName(rel.targetLayer)) {\n          downstreamLayerSet.add(rel.targetLayer);\n          outboundRelationshipCount++;\n        } else {\n          console.warn(`Skipping invalid layer name in relationship: ${rel.targetLayer}`);\n        }\n      }\n    }\n\n    // Sort upstream and downstream layers\n    const upstreamLayers = Array.from(upstreamLayerSet).sort();\n    const downstreamLayers = Array.from(downstreamLayerSet).sort();\n\n    // Sort relationships deterministically by \"${source}-${predicate}-${target}\"\n    intraRelationships.sort((a, b) => {\n      const aKey = `${a.source}-${a.predicate}-${a.target}`;\n      const bKey = `${b.source}-${b.predicate}-${b.target}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    interRelationships.sort((a, b) => {\n      const aKey = `${a.source}-${a.predicate}-${a.target}`;\n      const bKey = `${b.source}-${b.predicate}-${b.target}`;\n      return aKey.localeCompare(bKey);\n    });\n\n    // Build statistics\n    const statistics: ModelLayerStatistics = {\n      elementCount: elements.length,\n      intraRelationshipCount: intraRelationships.length,\n      interRelationshipCount: interRelationships.length,\n      inboundRelationshipCount,\n      outboundRelationshipCount,\n    };\n\n    return {\n      layerName,\n      layerNumber,\n      elements,\n      intraRelationships,\n      interRelationships,\n      upstreamLayers,\n      downstreamLayers,\n      statistics,\n    };\n  }\n\n  /**\n   * Collect aggregated model-wide data for the model README\n   *\n   * @param model - The live Model instance\n   * @returns Aggregated model-wide data including project metadata, per-layer summaries, and statistics\n   */\n  collectModelData(model: Model): ModelReadmeData {\n    // Collect per-layer element counts\n    const layers: ModelReadmeLayerSummary[] = [];\n    let totalElements = 0;\n\n    for (const layerName of CANONICAL_LAYER_NAMES) {\n      const graphNodes = model.graph.getNodesByLayer(layerName);\n      const elementCount = graphNodes.length;\n      totalElements += elementCount;\n\n      const layerNumber = getLayerOrder(layerName);\n      const reportFileName = getLayerReportFileName(layerName);\n\n      layers.push({\n        layerName,\n        layerNumber,\n        elementCount,\n        reportFileName,\n      });\n    }\n\n    // Count total relationships\n    const totalRelationships = model.relationships.getAll().length;\n\n    // Count populated layers (layers with at least one element)\n    const populatedLayerCount = layers.filter(l => l.elementCount > 0).length;\n\n    return {\n      projectName: model.manifest.name,\n      projectDescription: model.manifest.description,\n      modelVersion: model.manifest.version,\n      cliVersion: model.manifest.cliVersion || getCliVersion(),\n      specVersion: model.manifest.specVersion,\n      lastUpdated: model.manifest.modified,\n      totalElements,\n      totalRelationships,\n      populatedLayerCount,\n      layers,\n    };\n  }\n}\n"],
+  "mappings": "AACA,SAAS,eAAe;AAExB,SAAS,eAAe,uBAAgD,wBAAwB;AAChG,SAAS,qBAAqB;AAC9B,SAAS,8BAA8B;AA0DjC,MAAO,yBAAwB;;;;;;;;EAQnC,iBAAiB,OAAc,WAA6B;AAE1D,UAAM,cAAc,cAAc,SAAS,GAKrC,WADa,MAAM,MAAM,gBAAgB,SAAS,EAErD,IACC,CAAC,SACC,IAAI,QAAQ;MACV,IAAI,KAAK,QAAQ,KAAK;MACtB,MAAM,KAAK;MACX,cAAc,KAAK,gBAAgB;MACnC,MAAM,KAAK;MACX,UAAU,KAAK;MACf,MAAM,KAAK;MACX,aAAa,KAAK;MAClB,YAAY,KAAK;MACjB,kBAAkB,KAAK;MACvB,UAAU,KAAK;KAChB,CAAC,EAEL,KAAK,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAI,cAAc,EAAE,QAAQ,EAAE,EAAE,CAAC,GAM1D,2BAHmB,MAAM,cAAc,OAAM,EAGD,OAChD,OAAK,EAAE,UAAU,aAAa,EAAE,gBAAgB,SAAS,GAMrD,qBAAqB,yBAAyB,OAClD,OAAK,EAAE,UAAU,cAAc,EAAE,gBAAgB,aAAa,CAAC,EAAE,YAAY,GAIzE,qBAAqB,yBAAyB,OAClD,OAAK,EAAE,EAAE,UAAU,cAAc,EAAE,gBAAgB,aAAa,CAAC,EAAE,aAAa,GAI5E,mBAAmB,oBAAI,IAAG,GAC1B,qBAAqB,oBAAI,IAAG;AAClC,QAAI,2BAA2B,GAC3B,4BAA4B;AAEhC,eAAW,OAAO;AAEhB,MAAI,IAAI,gBAAgB,aAAa,IAAI,UAAU,cAE7C,iBAAiB,IAAI,KAAK,KAC5B,iBAAiB,IAAI,IAAI,KAAK,GAC9B,8BAEA,QAAQ,KAAK,gDAAgD,IAAI,KAAK,EAAE,IAIxE,IAAI,UAAU,aAAa,IAAI,eAAe,IAAI,gBAAgB,cAEhE,iBAAiB,IAAI,WAAW,KAClC,mBAAmB,IAAI,IAAI,WAAW,GACtC,+BAEA,QAAQ,KAAK,gDAAgD,IAAI,WAAW,EAAE;AAMpF,UAAM,iBAAiB,MAAM,KAAK,gBAAgB,EAAE,KAAI,GAClD,mBAAmB,MAAM,KAAK,kBAAkB,EAAE,KAAI;AAG5D,uBAAmB,KAAK,CAAC,GAAG,MAAK;AAC/B,YAAM,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,SAAS,IAAI,EAAE,MAAM,IAC7C,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,SAAS,IAAI,EAAE,MAAM;AACnD,aAAO,KAAK,cAAc,IAAI;IAChC,CAAC,GAED,mBAAmB,KAAK,CAAC,GAAG,MAAK;AAC/B,YAAM,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,SAAS,IAAI,EAAE,MAAM,IAC7C,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,SAAS,IAAI,EAAE,MAAM;AACnD,aAAO,KAAK,cAAc,IAAI;IAChC,CAAC;AAGD,UAAM,aAAmC;MACvC,cAAc,SAAS;MACvB,wBAAwB,mBAAmB;MAC3C,wBAAwB,mBAAmB;MAC3C;MACA;;AAGF,WAAO;MACL;MACA;MACA;MACA;MACA;MACA;MACA;MACA;;EAEJ;;;;;;;EAQA,iBAAiB,OAAY;AAE3B,UAAM,SAAoC,CAAA;AAC1C,QAAI,gBAAgB;AAEpB,eAAW,aAAa,uBAAuB;AAE7C,YAAM,eADa,MAAM,MAAM,gBAAgB,SAAS,EACxB;AAChC,uBAAiB;AAEjB,YAAM,cAAc,cAAc,SAAS,GACrC,iBAAiB,uBAAuB,SAAS;AAEvD,aAAO,KAAK;QACV;QACA;QACA;QACA;OACD;IACH;AAGA,UAAM,qBAAqB,MAAM,cAAc,OAAM,EAAG,QAGlD,sBAAsB,OAAO,OAAO,OAAK,EAAE,eAAe,CAAC,EAAE;AAEnE,WAAO;MACL,aAAa,MAAM,SAAS;MAC5B,oBAAoB,MAAM,SAAS;MACnC,cAAc,MAAM,SAAS;MAC7B,YAAY,MAAM,SAAS,cAAc,cAAa;MACtD,aAAa,MAAM,SAAS;MAC5B,aAAa,MAAM,SAAS;MAC5B;MACA;MACA;MACA;;EAEJ;;",
   "names": []
 }

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

@@ -1,7 +1,9 @@
 import { ModelReportDataCollector } from "./model-report-data.js";
 import { ModelLayerReportGenerator } from "./model-layer-report-generator.js";
-import { CANONICAL_LAYER_NAMES, getLayerOrder, isValidLayerName } from "../core/layers.js";
+import { ModelReadmeGenerator } from "./model-readme-generator.js";
+import { CANONICAL_LAYER_NAMES, isValidLayerName } from "../core/layers.js";
 import { getErrorMessage } from "../utils/errors.js";
+import { getLayerReportFileName } from "./model-report-utils.js";
 import * as fs from "fs/promises";
 import * as path from "path";
 class ModelReportOrchestrator {
@@ -9,19 +11,23 @@ class ModelReportOrchestrator {
   rootPath;
   collector;
   generator;
+  readmeGenerator;
   constructor(model, rootPath) {
     this.model = model, this.rootPath = rootPath, this.collector = new ModelReportDataCollector();
     const modelVersion = model.manifest.version || "unknown", generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.generator = new ModelLayerReportGenerator(modelVersion, generatedAt);
+    this.generator = new ModelLayerReportGenerator(modelVersion, generatedAt), this.readmeGenerator = new ModelReadmeGenerator(generatedAt);
   }
   /**
    * Regenerate reports for a specific set of affected layers.
    * On first invocation or when reports don't exist, regenerates all 13 reports.
    * 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.
    */
   async regenerate(affectedLayers) {
     if (!await this.isInitialized())
       return this.regenerateAll();
+    await this.generateReadme();
     for (const layerName of affectedLayers) {
       if (!isValidLayerName(layerName)) {
         console.warn(`Skipping invalid layer name: ${layerName}`);
@@ -31,12 +37,13 @@ class ModelReportOrchestrator {
     }
   }
   /**
-   * Regenerate all 13 layer reports.
+   * Regenerate all 13 layer reports and the README.
    * Lets mkdir errors propagate so callers can handle them with proper telemetry.
+   * README is generated first so it exists even if a layer report throws.
    */
   async regenerateAll() {
     const reportDir = this.getReportDir();
-    await fs.mkdir(reportDir, { recursive: !0 });
+    await fs.mkdir(reportDir, { recursive: !0 }), await this.generateReadme();
     for (const layerName of CANONICAL_LAYER_NAMES)
       await this.generateLayerReport(layerName);
   }
@@ -78,7 +85,7 @@ class ModelReportOrchestrator {
    * Get the full file path for a layer report.
    */
   getReportFilePath(layerName) {
-    const layerNumber = getLayerOrder(layerName), filename = `${String(layerNumber).padStart(2, "0")}-${layerName}-layer-report.md`;
+    const filename = getLayerReportFileName(layerName);
     return path.join(this.getReportDir(), filename);
   }
   /**
@@ -91,11 +98,27 @@ class ModelReportOrchestrator {
     try {
       data = this.collector.collectLayerData(this.model, layerName), markdown = this.generator.generate(data);
     } catch (error) {
-      throw new Error(`Failed to generate report content for layer: ${layerName} (programming error or corrupted model) - ${getErrorMessage(error)}`);
+      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");
   }
+  /**
+   * Generate and write the model README.
+   * Separates concerns to distinguish programming bugs from I/O errors.
+   * Lets generation and write errors propagate so callers can handle them with proper telemetry.
+   * README is written to documentation-robotics/README.md (outside reports/ folder).
+   */
+  async generateReadme() {
+    let data, markdown;
+    try {
+      data = this.collector.collectModelData(this.model), markdown = this.readmeGenerator.generate(data);
+    } catch (error) {
+      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");
+  }
 }
 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 { CANONICAL_LAYER_NAMES, type CanonicalLayerName, getLayerOrder, isValidLayerName } from '../core/layers.js';\nimport { getErrorMessage } from '../utils/errors.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\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  }\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   */\n  async regenerate(affectedLayers: Set<string>): Promise<void> {\n    if (!(await this.isInitialized())) {\n      return this.regenerateAll();\n    }\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.\n   * Lets mkdir errors propagate so callers can handle them with proper telemetry.\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 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 layerNumber = getLayerOrder(layerName);\n    const paddedNumber = String(layerNumber).padStart(2, '0');\n    const filename = `${paddedNumber}-${layerName}-layer-report.md`;\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      );\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"],
-  "mappings": "AAQA,SAAS,gCAAgC;AACzC,SAAS,iCAAiC;AAC1C,SAAS,uBAAgD,eAAe,wBAAwB;AAChG,SAAS,uBAAuB;AAChC,YAAY,QAAQ;AACpB,YAAY,UAAU;AAEhB,MAAO,wBAAuB;EAId;EAAsB;EAHlC;EACA;EAER,YAAoB,OAAsB,UAAgB;AAAtC,SAAA,QAAA,OAAsB,KAAA,WAAA,UACxC,KAAK,YAAY,IAAI,yBAAwB;AAC7C,UAAM,eAAe,MAAM,SAAS,WAAW,WACzC,eAAc,oBAAI,KAAI,GAAG,YAAW;AAC1C,SAAK,YAAY,IAAI,0BAA0B,cAAc,WAAW;EAC1E;;;;;;EAOA,MAAM,WAAW,gBAA2B;AAC1C,QAAI,CAAE,MAAM,KAAK,cAAa;AAC5B,aAAO,KAAK,cAAa;AAG3B,eAAW,aAAa,gBAAgB;AAEtC,UAAI,CAAC,iBAAiB,SAAS,GAAG;AAChC,gBAAQ,KAAK,gCAAgC,SAAS,EAAE;AACxD;MACF;AACA,YAAM,KAAK,oBAAoB,SAAS;IAC1C;EACF;;;;;EAMA,MAAM,gBAAa;AAEjB,UAAM,YAAY,KAAK,aAAY;AACnC,UAAM,GAAG,MAAM,WAAW,EAAE,WAAW,GAAI,CAAE;AAG7C,eAAW,aAAa;AACtB,YAAM,KAAK,oBAAoB,SAAS;EAE5C;;;;;;EAOA,sBAAsB,cAAgC;AAEpD,QAAI,CAAC,iBAAiB,YAAY;AAChC,YAAM,IAAI,MACR,gCAAgC,YAAY,4DACvB,sBAAsB,KAAK,IAAI,CAAC,EAAE;AAI3D,UAAM,WAAW,oBAAI,IAAwB,CAAC,YAAY,CAAC;AAE3D,eAAW,OAAO,KAAK,MAAM,cAAc,OAAM;AAE/C,MAAI,IAAI,UAAU,gBAAgB,IAAI,eAEhC,iBAAiB,IAAI,WAAW,KAClC,SAAS,IAAI,IAAI,WAAW,GAI5B,IAAI,gBAAgB,gBAElB,iBAAiB,IAAI,KAAK,KAC5B,SAAS,IAAI,IAAI,KAAK;AAK5B,WAAO;EACT;;;;;EAMQ,MAAM,gBAAa;AACzB,eAAW,aAAa;AACtB,UAAI;AACF,cAAM,GAAG,OAAO,KAAK,kBAAkB,SAAS,CAAC;MACnD,SAAS,OAAgB;AAGvB,YAFY,MAEJ,SAAS;AACf,iBAAO;AAGT,cAAM;MACR;AAEF,WAAO;EACT;;;;EAKQ,eAAY;AAClB,WAAO,KAAK,KAAK,KAAK,UAAU,0BAA0B,SAAS;EACrE;;;;EAKQ,kBAAkB,WAA6B;AACrD,UAAM,cAAc,cAAc,SAAS,GAErC,WAAW,GADI,OAAO,WAAW,EAAE,SAAS,GAAG,GAAG,CACxB,IAAI,SAAS;AAC7C,WAAO,KAAK,KAAK,KAAK,aAAY,GAAI,QAAQ;EAChD;;;;;;EAOQ,MAAM,oBAAoB,WAA6B;AAC7D,QAAI,MACA;AAEJ,QAAI;AAEF,aAAO,KAAK,UAAU,iBAAiB,KAAK,OAAO,SAAS,GAG5D,WAAW,KAAK,UAAU,SAAS,IAAI;IACzC,SAAS,OAAO;AACd,YAAM,IAAI,MACR,gDAAgD,SAAS,6CAA6C,gBAAgB,KAAK,CAAC,EAAE;IAElI;AAIA,UAAM,WAAW,KAAK,kBAAkB,SAAS;AACjD,UAAM,GAAG,UAAU,UAAU,UAAU,OAAO;EAChD;;",
+  "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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",
   "names": []
 }

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

@@ -0,0 +1,9 @@
+import { getLayerOrder } from "../core/layers.js";
+function getLayerReportFileName(layerName) {
+  const layerNumber = getLayerOrder(layerName);
+  return `${String(layerNumber).padStart(2, "0")}-${layerName}-layer-report.md`;
+}
+export {
+  getLayerReportFileName
+};
+//# sourceMappingURL=model-report-utils.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/reports/model-report-utils.ts"],
+  "sourcesContent": ["import type { CanonicalLayerName } from '../core/layers.js';\nimport { getLayerOrder } from '../core/layers.js';\n\n/**\n * Generate the report filename for a layer using the shared pattern: {NN}-{layerName}-layer-report.md\n *\n * @param layerName - The canonical layer name (e.g., 'api', 'data-model')\n * @returns The filename string with zero-padded layer number\n */\nexport function getLayerReportFileName(layerName: CanonicalLayerName): string {\n  const layerNumber = getLayerOrder(layerName);\n  const paddedNumber = String(layerNumber).padStart(2, '0');\n  return `${paddedNumber}-${layerName}-layer-report.md`;\n}\n"],
+  "mappings": "AACA,SAAS,qBAAqB;AAQxB,SAAU,uBAAuB,WAA6B;AAClE,QAAM,cAAc,cAAc,SAAS;AAE3C,SAAO,GADc,OAAO,WAAW,EAAE,SAAS,GAAG,GAAG,CAClC,IAAI,SAAS;AACrC;",
+  "names": []
+}