create-yss-spec 2.1.4 → 2.1.6

package/template/.codex/skills/drawio/scripts/postprocess/mutate.test.js

@@ -1,193 +0,0 @@
-import assert from 'node:assert/strict'
-import { readFileSync } from 'node:fs'
-import test from 'node:test'
-
-import { normalizePostprocessInput } from './input.js'
-import { serializeDocumentSpecYaml } from '../runtime/artifacts.js'
-import { specToDrawioXml, validateXml } from '../dsl/spec-to-drawio.js'
-import { drawioToDocumentSpec, renderDocumentFile, validateDrawioDocument } from '../dsl/multi-page.js'
-import { applyHeatmap, applyRelabel, applyRestyle, parseHeatmapMetrics } from './mutate.js'
-
-const fixture = normalizePostprocessInput(
-  readFileSync(new URL('./fixtures/bundle.yaml', import.meta.url), 'utf8')
-)
-
-test('relabels bundle objects by stable page/object address without mutating identity, geometry, links, or source', () => {
-  const original = structuredClone(fixture)
-  const result = applyRelabel(fixture, {
-    'context/gateway': 'Gateway renamed',
-    'detail/gateway': 'Detail renamed'
-  })
-
-  assert.equal(result.pages[0].nodes[0].label, 'Gateway renamed')
-  assert.equal(result.pages[1].nodes[0].label, 'Detail renamed')
-  assert.equal(result.pages[0].nodes[0].id, 'gateway')
-  assert.deepEqual(result.pages[0].nodes[0].bounds, original.pages[0].nodes[0].bounds)
-  assert.deepEqual(result.pages[0].edges, original.pages[0].edges)
-  assert.deepEqual(result.links, original.links)
-  assert.deepEqual(fixture, original)
-})
-
-test('supports legacy object-id maps and returns deterministic match diagnostics', () => {
-  const legacy = normalizePostprocessInput('nodes:\n  - id: api\n    label: API\nedges: []\nmodules: []\n')
-  const result = applyRelabel(legacy, { api: 'HTTP API' }, { returnDiagnostics: true })
-
-  assert.equal(result.value.nodes[0].label, 'HTTP API')
-  assert.deepEqual(result.diagnostics, { matched: ['page-1/api'], missing: [], changed: ['page-1/api'] })
-})
-
-test('rejects duplicate and missing map addresses unless explicitly allowed', () => {
-  assert.throws(
-    () => applyRelabel(fixture, [
-      { pageId: 'context', objectId: 'gateway', label: 'A' },
-      { pageId: 'context', objectId: 'gateway', label: 'B' }
-    ]),
-    /duplicate relabel map key.*context\/gateway/i
-  )
-  assert.throws(() => applyRelabel(fixture, { 'context/missing': 'Nope' }), /relabel map key.*not found/i)
-  const allowed = applyRelabel(fixture, { 'context/missing': 'Nope' }, { allowMissing: true, returnDiagnostics: true })
-  assert.deepEqual(allowed.diagnostics.missing, ['context/missing'])
-})
-
-test('page selection limits relabeling to the selected page', () => {
-  const result = applyRelabel(fixture, { 'detail/gateway': 'Only detail' }, { page: 'detail' })
-
-  assert.equal(result.pages[0].nodes[0].label, 'Gateway')
-  assert.equal(result.pages[1].nodes[0].label, 'Only detail')
-})
-
-test('restyles through a bundled preset while preserving protected canonical fields', () => {
-  const original = structuredClone(fixture)
-  const result = applyRestyle(fixture, 'corporate')
-
-  assert.equal(result.pages[0].nodes[0].style.fillColor, '#e3f2fd')
-  assert.equal(result.pages[0].nodes[0].style.strokeColor, '#1565c0')
-  assert.equal(result.pages[0].nodes[1].style.fillColor, '#e8f5e9')
-  assert.equal(result.pages[0].nodes[0].icon, 'lucide.server-cog')
-  assert.equal(result.pages[0].nodes[1].icon, 'redis.server')
-  assert.equal(result.pages[0].nodes[2].icon, 'lobe.openai')
-  assert.equal(result.pages[0].nodes[3].icon, 'aws.lambda')
-  assert.deepEqual(result.pages[0].nodes[0].identity, original.pages[0].nodes[0].identity)
-  assert.deepEqual(result.pages[0].nodes[0].bounds, original.pages[0].nodes[0].bounds)
-  assert.deepEqual(result.pages[0].meta, original.pages[0].meta)
-  assert.deepEqual(result.pages[1].meta, original.pages[1].meta)
-  assert.deepEqual(result.links, original.links)
-  assert.deepEqual(fixture, original)
-  assert.equal(serializeDocumentSpecYaml(result), serializeDocumentSpecYaml(applyRestyle(fixture, 'corporate')))
-})
-
-test('accepts bounded user style tokens and rejects shape, icon, and unsafe preset text', () => {
-  const legacy = normalizePostprocessInput('nodes:\n  - id: api\n    label: API\nedges: []\nmodules: []\n')
-  const result = applyRestyle(legacy, {
-    node: { fillColor: '#112233', strokeColor: '#445566', fontSize: 14 },
-    edge: { strokeWidth: 2 },
-    module: { fontColor: '#000000' }
-  })
-
-  assert.equal(result.nodes[0].style.fillColor, '#112233')
-  assert.throws(() => applyRestyle(legacy, { node: { shape: 'image' } }), /unsupported restyle token.*shape/i)
-  assert.throws(() => applyRestyle(legacy, { node: { icon: 'lobe.openai' } }), /unsupported restyle token.*icon/i)
-  assert.throws(
-    () => applyRestyle(legacy, { node: { fontFamily: 'Arial;html=1' } }),
-    /restyle.*fontFamily.*safe/i
-  )
-})
-
-test('restyled legacy output renders and validates through the existing XML path', () => {
-  const legacy = normalizePostprocessInput(readFileSync(new URL('./fixtures/legacy.yaml', import.meta.url), 'utf8'))
-  const result = applyRestyle(legacy, 'corporate')
-  const xml = specToDrawioXml(result, { silent: true })
-
-  assert.match(xml, /fillColor=#e3f2fd/)
-  assert.equal(validateXml(xml).valid, true)
-})
-
-test('applies heatmap metrics by identity, address, then explicit label fallback', () => {
-  const original = structuredClone(fixture)
-  const result = applyHeatmap(
-    fixture,
-    {
-      'fixture:context/gateway': 0,
-      'context/cache': 50,
-      'Detail gateway': 100,
-      unmatched: 25
-    },
-    { palette: 'heat', labelFallback: true, returnDiagnostics: true }
-  )
-
-  assert.equal(result.value.pages[0].nodes[0].style.fillColor, '#FFF7EC')
-  assert.equal(result.value.pages[0].nodes[1].style.fillColor, '#FC8D59')
-  assert.equal(result.value.pages[1].nodes[0].style.fillColor, '#7F0000')
-  assert.deepEqual(result.value.links, original.links)
-  assert.equal(result.value.pages[0].nodes[0].icon, original.pages[0].nodes[0].icon)
-  assert.deepEqual(result.value.pages[0].nodes[0].identity, original.pages[0].nodes[0].identity)
-  assert.deepEqual(result.diagnostics.unmatched, ['unmatched'])
-  assert.deepEqual(result.diagnostics.range, { min: 0, max: 100 })
-  assert.deepEqual(fixture, original)
-})
-
-test('parses bounded JSON and CSV heatmap metrics deterministically', () => {
-  assert.deepEqual(parseHeatmapMetrics('{"context/gateway": 5}'), [{ key: 'context/gateway', value: 5 }])
-  assert.deepEqual(parseHeatmapMetrics('pageId,objectId,value\ncontext,gateway,5\ndetail,gateway,9\n'), [
-    { key: 'context/gateway', value: 5 },
-    { key: 'detail/gateway', value: 9 }
-  ])
-  assert.throws(() => parseHeatmapMetrics('key,value\na,NaN\n'), /finite numeric value/i)
-  assert.throws(() => parseHeatmapMetrics([{ key: 'a', value: 1 }, { key: 'a', value: 2 }]), /duplicate heatmap metric key.*a/i)
-})
-
-test('rejects unknown palettes and ambiguous label fallback', () => {
-  assert.throws(() => applyHeatmap(fixture, { 'context/gateway': 1 }, { palette: 'unknown' }), /unknown heatmap palette/i)
-  const duplicateLabels = normalizePostprocessInput({
-    meta: {},
-    nodes: [
-      { id: 'a', label: 'Same' },
-      { id: 'b', label: 'Same' }
-    ],
-    edges: [],
-    modules: []
-  })
-  assert.throws(
-    () => applyHeatmap(duplicateLabels, { Same: 1 }, { labelFallback: true }),
-    /heatmap label.*ambiguous/i
-  )
-})
-
-test('bounds optional heatmap geometry scaling and keeps center stable', () => {
-  const result = applyHeatmap(
-    fixture,
-    { 'context/gateway': 0, 'context/cache': 10 },
-    { sizeScale: { min: 0.5, max: 1.5 }, page: 'context' }
-  )
-  const originalBounds = fixture.pages[0].nodes[0].bounds
-  const scaledBounds = result.pages[0].nodes[0].bounds
-
-  assert.equal(scaledBounds.width, originalBounds.width * 0.5)
-  assert.equal(scaledBounds.x + scaledBounds.width / 2, originalBounds.x + originalBounds.width / 2)
-  assert.throws(
-    () => applyHeatmap(fixture, { 'context/gateway': 1 }, { sizeScale: { min: 0.1, max: 3 } }),
-    /sizeScale.*bounded/i
-  )
-})
-
-test('canonical mutators round-trip through validated multi-page Draw.io and restore stable links', async () => {
-  const roundTripFixture = structuredClone(fixture)
-  delete roundTripFixture.pages[0].meta.adapter
-  for (const object of roundTripFixture.pages[0].nodes) delete object.identity
-  for (const object of roundTripFixture.pages[0].edges) delete object.identity
-  const outputs = [
-    applyRelabel(roundTripFixture, { 'context/gateway': 'Gateway round-trip', 'detail/gateway': 'Detail round-trip' }),
-    applyRestyle(roundTripFixture, 'corporate'),
-    applyHeatmap(roundTripFixture, { 'context/gateway': 1, 'detail/gateway': 2 }, { palette: 'heat' })
-  ]
-
-  for (const output of outputs) {
-    const drawio = await renderDocumentFile(output, { silent: true })
-    assert.equal(validateDrawioDocument(drawio).valid, true)
-    const imported = drawioToDocumentSpec(drawio)
-    assert.deepEqual(imported.pages.map((page) => page.id), ['context', 'detail'])
-    assert.deepEqual(imported.pages.map((page) => page.nodes[0].id), ['gateway', 'gateway'])
-    assert.deepEqual(imported.links, roundTripFixture.links)
-    assert.equal(serializeDocumentSpecYaml(imported).includes('schemaVersion: 1'), true)
-  }
-})

package/template/.codex/skills/drawio/scripts/postprocess/projection.js

@@ -1,178 +0,0 @@
-import { normalizePostprocessInput, selectPostprocessPages } from './input.js'
-
-const MERMAID_DIRECTIONS = new Set(['LR', 'RL', 'TB', 'BT'])
-const MERMAID_TYPES = new Map([
-  ['database', ['[("', '")]']],
-  ['decision', ['{ "', '" }']],
-  ['terminal', ['(["', '"])']],
-  ['queue', ['[/"', '"/]']],
-  ['cloud', ['(("', '"))']],
-  ['text', ['["', '"]']],
-  ['service', ['["', '"]']],
-  ['user', ['(("', '"))']],
-  ['operator', ['{{"', '"}}']]
-])
-
-function asText(value, fallback = '') {
-  return typeof value === 'string' ? value : value == null ? fallback : String(value)
-}
-
-function escapeMermaidLabel(value) {
-  return asText(value)
-    .replaceAll('\\', '\\\\')
-    .replaceAll('"', '\\"')
-    .replaceAll('`', '\\`')
-    .replaceAll('|', '|')
-    .replace(/\r?\n/g, '<br>')
-    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, ' ')
-}
-
-function escapeHeading(value) {
-  return asText(value, 'Untitled')
-    .replace(/[\r\n]+/g, ' ')
-    .replace(/([\\`*_{}\[\]()#+.!<>|])/g, '\\$1')
-}
-
-function inlineCode(value) {
-  const text = asText(value).replace(/[\r\n]+/g, ' ')
-  const runs = text.match(/`+/g)
-  if (!runs) return `\`${text}\``
-  const fence = '`'.repeat(Math.max(...runs.map((run) => run.length)) + 1)
-  return `${fence} ${text} ${fence}`
-}
-
-function mermaidId(pageId, objectId) {
-  return `${pageId}_${objectId}`
-}
-
-function objectLabel(object, fallback = object?.id || 'object') {
-  return object?.label || fallback
-}
-
-function pageTitle(page) {
-  return page.meta?.title || page.name || page.id
-}
-
-function edgeOperator(edge) {
-  if (edge.type === 'dependency') return '==>'
-  if (edge.type === 'optional' || edge.type === 'data') return '-.->'
-  return '-->'
-}
-
-function buildMermaidNode(pageId, object, type, warnings) {
-  const shape = MERMAID_TYPES.get(type || 'service')
-  if (!shape) {
-    warnings.push(`page ${pageId} object ${object.id} uses unsupported Mermaid type "${type}"; rendered as a neutral node`)
-  }
-  const [start, end] = shape || MERMAID_TYPES.get('service')
-  return `    ${mermaidId(pageId, object.id)}${start}${escapeMermaidLabel(objectLabel(object))}${end}`
-}
-
-function projectionPages(value, options) {
-  const normalized = normalizePostprocessInput(value)
-  const selected = selectPostprocessPages(normalized, {
-    page: options.page,
-    allPages: options.page == null ? options.allPages !== false : false
-  })
-  return selected
-}
-
-export function renderMermaidProjection(value, options = {}) {
-  const direction = options.direction || 'LR'
-  if (!MERMAID_DIRECTIONS.has(direction)) {
-    throw new Error(`Mermaid direction must be one of ${[...MERMAID_DIRECTIONS].join(', ')}`)
-  }
-  const { document, pages } = projectionPages(value, options)
-  const warnings = []
-  const lines = [`flowchart ${direction}`]
-  const pageIds = new Set(pages.map((page) => page.id))
-
-  for (const page of pages) {
-    lines.push(`  subgraph ${page.id}["${escapeMermaidLabel(pageTitle(page))}"]`)
-    for (const module of page.modules || []) lines.push(buildMermaidNode(page.id, module, 'service', warnings))
-    for (const node of page.nodes || []) lines.push(buildMermaidNode(page.id, node, node.type || 'service', warnings))
-    for (const edge of page.edges || []) {
-      lines.push(
-        `    ${mermaidId(page.id, edge.from)} ${edgeOperator(edge)}|${escapeMermaidLabel(edge.label || edge.type || '')}| ${mermaidId(page.id, edge.to)}`
-      )
-    }
-    lines.push('  end')
-  }
-
-  for (const link of document.links || []) {
-    if (!pageIds.has(link.from.pageId) || !pageIds.has(link.to.pageId)) continue
-    const from = mermaidId(link.from.pageId, link.from.objectId)
-    const to = mermaidId(link.to.pageId, link.to.objectId)
-    lines.push(`  ${from} -.-> ${to}`)
-    lines.push(`  %% structured-link ${link.from.pageId}/${link.from.objectId} -> ${link.to.pageId}/${link.to.objectId}`)
-  }
-
-  return { text: lines.join('\n') + '\n', warnings }
-}
-
-export function renderMermaid(value, options = {}) {
-  const result = renderMermaidProjection(value, options)
-  const output = options.fenced ? `\`\`\`mermaid\n${result.text}\`\`\`\n` : result.text
-  return options.returnWarnings ? { text: output, warnings: result.warnings } : output
-}
-
-function metadataLine(meta) {
-  const fields = ['source', 'profile', 'theme', 'layout']
-    .filter((field) => meta?.[field] != null)
-    .map((field) => `${field} ${inlineCode(meta[field])}`)
-  return fields.length ? `\nMetadata: ${fields.join('; ')}` : ''
-}
-
-function identityText(object) {
-  if (!object?.identity) return ''
-  return `; identity ${inlineCode(`${object.identity.scheme}:${object.identity.key}`)}`
-}
-
-function explainObject(object, kind) {
-  const type = object.type || (kind === 'module' ? 'module' : kind)
-  const icon = object.icon ? `; icon ${inlineCode(object.icon)}` : ''
-  return `- ${inlineCode(object.id)}: ${inlineCode(objectLabel(object))} (${type})${icon}${identityText(object)}`
-}
-
-export function explainDocument(value, options = {}) {
-  const { document, pages } = projectionPages(value, options)
-  const title = options.page != null ? pageTitle(pages[0]) : document.meta?.title || pageTitle(pages[0])
-  const lines = [`# ${escapeHeading(title)}`]
-  if (options.page == null) lines.push(metadataLine(document.meta || {}))
-
-  for (const page of pages) {
-    lines.push(`## Page: ${escapeHeading(page.name)} (${inlineCode(page.id)})`)
-    lines.push(metadataLine(page.meta || {}))
-    if (page.modules?.length) {
-      lines.push('### Modules')
-      for (const module of page.modules) lines.push(explainObject(module, 'module'))
-    }
-    if (page.nodes?.length) {
-      lines.push('### Nodes')
-      for (const node of page.nodes) lines.push(explainObject(node, 'node'))
-    }
-    if (page.edges?.length) {
-      lines.push('### Edges')
-      for (const edge of page.edges) {
-        const label = edge.label ? `: ${inlineCode(edge.label)}` : ''
-        lines.push(`- ${inlineCode(edge.from)} -> ${inlineCode(edge.to)}${label}${identityText(edge)}`)
-      }
-    }
-  }
-
-  const selectedIds = new Set(pages.map((page) => page.id))
-  const links = (document.links || []).filter(
-    (link) => selectedIds.has(link.from.pageId) && selectedIds.has(link.to.pageId)
-  )
-  if (links.length) {
-    lines.push('### Structured links')
-    for (const link of links) {
-      lines.push(
-        `- ${inlineCode(`${link.from.pageId}/${link.from.objectId}`)} -> ${inlineCode(`${link.to.pageId}/${link.to.objectId}`)}`
-      )
-    }
-  }
-  return lines.join('\n').replace(/\n{3,}/g, '\n\n') + '\n'
-}
-
-export const renderExplain = explainDocument

package/template/.codex/skills/drawio/scripts/postprocess/projection.test.js

@@ -1,67 +0,0 @@
-import assert from 'node:assert/strict'
-import { readFileSync } from 'node:fs'
-import test from 'node:test'
-
-import { normalizePostprocessInput } from './input.js'
-import { explainDocument, renderMermaid, renderMermaidProjection } from './projection.js'
-
-const bundle = normalizePostprocessInput(
-  readFileSync(new URL('./fixtures/bundle.yaml', import.meta.url), 'utf8')
-)
-
-test('renders deterministic Mermaid subgraphs in page and object order with structured links', () => {
-  const first = renderMermaid(bundle, { direction: 'TB' })
-  const second = renderMermaid(bundle, { direction: 'TB' })
-
-  assert.equal(first, second)
-  assert.match(first, /^flowchart TB\n/)
-  assert.ok(first.indexOf('subgraph context') < first.indexOf('subgraph detail'))
-  assert.ok(first.indexOf('context_gateway["Gateway"]') < first.indexOf('context_cache[("Redis")]'))
-  assert.match(first, /context_gateway -->\|query\| context_cache/)
-  assert.match(first, /context_gateway -.-> detail_gateway/)
-  assert.match(first, /structured-link context\/gateway -> detail\/gateway/)
-})
-
-test('escapes Mermaid labels and reports bounded semantic downgrade warnings', () => {
-  const value = {
-    meta: {},
-    nodes: [{ id: 'unsafe', label: 'A"\\B\nC|D', type: 'document' }],
-    edges: [],
-    modules: []
-  }
-  const { text, warnings } = renderMermaidProjection(value)
-
-  assert.match(text, /A\\"\\\\B<br>C&#124;D/)
-  assert.equal(text.includes('C|D'), false)
-  assert.equal(warnings.length, 1)
-  assert.match(warnings[0], /document/)
-})
-
-test('explains only observable canonical fields and keeps author order', () => {
-  const text = explainDocument(bundle)
-
-  assert.match(text, /^# Postprocess bundle fixture\n/)
-  assert.ok(text.indexOf('## Page: Context') < text.indexOf('## Page: Detail'))
-  assert.match(text, /- `gateway`: `Gateway` \(service\); icon `lucide\.server-cog`; identity `fixture:context\/gateway`/)
-  assert.match(text, /- `context\/gateway` -> `detail\/gateway`/)
-  assert.doesNotMatch(text, /should|intended|risk|owner|executive|architecture intent/i)
-})
-
-test('uses a safe Markdown code-span fence for labels containing backticks', () => {
-  const text = explainDocument({
-    meta: { title: 'Backtick fixture' },
-    nodes: [{ id: 'code', label: 'A`B', type: 'service' }],
-    edges: [],
-    modules: []
-  })
-
-  assert.match(text, /`` A`B ``/)
-  assert.equal(text.includes('`A\\`B`'), false)
-})
-
-test('supports deterministic selected-page Mermaid and Markdown projections', () => {
-  assert.equal(renderMermaid(bundle, { page: 'detail' }), renderMermaid(bundle, { page: 1 }))
-  const text = explainDocument(bundle, { page: 'detail' })
-  assert.match(text, /^# Detail\n/)
-  assert.doesNotMatch(text, /## Page: Context/)
-})