astro-archify 0.3.4

package/vendor/archify/renderers/shared/cli.mjs

@@ -0,0 +1,220 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { applyTemplate, renderCards, esc } from './utils.mjs';
+import { validateSchema } from './validator.mjs';
+import { verifyRepositoryEvidence } from './repository-evidence.mjs';
+import { installRendererDiagnosticBoundary, throwDiagnosticProblems } from './diagnostics.mjs';
+import { validateEngineeringProfile } from './engineering-profiles.mjs';
+import { resolveOutputPath } from './output-path.mjs';
+import { prepareDiagramBrandMarks } from './brand-marks.mjs';
+import { resolveLocale, translateMessage } from './i18n.mjs';
+
+installRendererDiagnosticBoundary();
+
+const outputPathGuards = new Map();
+
+// Common CLI head: node render-<type>.mjs [input.json] [output.html]
+// Keep this synchronous because callers also use it to establish the guarded
+// output path before testing a last-moment filesystem alias change.
+export function loadDiagram({ rendererDir, diagramType, defaultExample, argv = process.argv }) {
+  const skillRoot = path.resolve(rendererDir, '../..');
+  const inputPath = path.resolve(argv[2] || path.join(skillRoot, 'examples', defaultExample));
+  const diagram = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+  validateSchema(diagramType, diagram);
+  validateGuidedViews(diagramType, diagram);
+  validateRelationshipIds(diagramType, diagram);
+  validateEngineeringProfile(diagramType, diagram);
+  const sourceEvidence = verifyRepositoryEvidence(diagramType, diagram, process.env.ARCHIFY_REPO_ROOT);
+  const template = fs.readFileSync(path.join(skillRoot, 'assets/template.html'), 'utf8');
+  // Optional chaining: in degraded mode (no ajv) malformed input must still
+  // reach the renderer's friendly layout checks instead of crashing here.
+  const outputRequest = {
+    requestedOutput: argv[3],
+    authoredOutput: diagram.meta?.output,
+    defaultOutput: `${diagramType}.html`,
+    inputPaths: [inputPath],
+    cwd: process.cwd(),
+  };
+  const { outputPath: outPath } = resolveOutputPath(outputRequest);
+  outputPathGuards.set(outPath, outputRequest);
+  return { diagram, template, outPath, sourceEvidence };
+}
+
+// Brand URL capture is the only asynchronous authoring step. Typed renderers
+// opt into it through this wrapper without changing loadDiagram's long-lived
+// synchronous safety contract.
+export async function loadDiagramWithBrandMarks(options) {
+  const loaded = loadDiagram(options);
+  await prepareDiagramBrandMarks(options.diagramType, loaded.diagram);
+  return loaded;
+}
+
+const START_TYPES = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle']);
+
+// Common CLI tail: fill the template and write the standalone HTML file.
+export function writeDiagram({ outPath, template, diagramType, meta, svg, cards, sourceEvidence = null }) {
+  if (!START_TYPES.has(diagramType)) throw new Error(`writeDiagram: unknown diagram type ${JSON.stringify(diagramType)}`);
+  const outputGuard = outputPathGuards.get(outPath);
+  if (outputGuard) resolveOutputPath(outputGuard);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, applyTemplate(template, {
+    title: meta.title,
+    subtitle: meta.subtitle,
+    svg,
+    cards: renderCards(cards),
+    locale: meta.locale,
+    visualPreset: meta.visual_preset || 'classic',
+    guidedViews: meta.views || [],
+    sourceEvidence,
+  }));
+  outputPathGuards.delete(outPath);
+  console.log(outPath);
+}
+
+const SEMANTIC_COLLECTIONS = {
+  architecture: 'components',
+  workflow: 'nodes',
+  sequence: 'participants',
+  dataflow: 'nodes',
+  lifecycle: 'states',
+};
+
+const RELATIONSHIP_COLLECTIONS = {
+  architecture: 'connections',
+  workflow: 'edges',
+  sequence: 'messages',
+  dataflow: 'flows',
+  lifecycle: 'transitions',
+};
+
+// Relationship IDs are optional for backwards compatibility, but once an
+// author supplies one it becomes the durable identity used by viewer links.
+// Keep uniqueness enforcement in the shared zero-install path so every typed
+// renderer fails the same way even when development dependencies are absent.
+export function validateRelationshipIds(diagramType, diagram) {
+  const collection = RELATIONSHIP_COLLECTIONS[diagramType];
+  const relationships = collection && Array.isArray(diagram[collection]) ? diagram[collection] : [];
+  const seen = new Set();
+  const problems = [];
+
+  relationships.forEach((relationship, index) => {
+    if (relationship.id === undefined || relationship.id === null || relationship.id === '') return;
+    if (seen.has(relationship.id)) {
+      problems.push(`/${collection}/${index}/id duplicates relationship id ${JSON.stringify(relationship.id)}`);
+    }
+    seen.add(relationship.id);
+  });
+
+  if (problems.length) {
+    throwDiagnosticProblems('Relationship identity validation failed', problems, {
+      code: 'relationship/duplicate-id',
+      subject: { diagramType, collection },
+    });
+  }
+}
+
+// JSON Schema keeps the view object bounded; this pass checks facts that span
+// collections. Keeping it here makes the same contract apply to all five
+// renderers, including the zero-install standalone-validator path.
+export function validateGuidedViews(diagramType, diagram) {
+  const views = diagram.meta?.views;
+  if (!Array.isArray(views) || views.length === 0) return;
+  const collection = SEMANTIC_COLLECTIONS[diagramType];
+  const semanticIds = new Set((diagram[collection] || []).map((item) => item.id));
+  const seen = new Set();
+  const problems = [];
+
+  views.forEach((view, index) => {
+    if (seen.has(view.id)) problems.push(`/meta/views/${index}/id duplicates view id ${JSON.stringify(view.id)}`);
+    seen.add(view.id);
+    const seenFocus = new Set();
+    (view.focus || []).forEach((id, focusIndex) => {
+      if (seenFocus.has(id)) {
+        problems.push(`/meta/views/${index}/focus/${focusIndex} duplicates semantic id ${JSON.stringify(id)}`);
+      }
+      seenFocus.add(id);
+      if (!semanticIds.has(id)) {
+        problems.push(`/meta/views/${index}/focus/${focusIndex} references unknown semantic id ${JSON.stringify(id)}`);
+      }
+    });
+  });
+
+  if (problems.length) {
+    throwDiagnosticProblems('Guided view validation failed', problems, {
+      code: 'guided-view/invalid',
+      subject: { diagramType, collection: 'meta.views' },
+    });
+  }
+}
+
+// Accessible name for the generated diagram SVG.
+export function svgRootAttrs(meta, kind) {
+  const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';
+  const preset = ` data-preset="${esc(meta.visual_preset || 'classic')}"`;
+  const engineeringProfile = meta.engineering_profile
+    ? ` data-engineering-profile="${esc(meta.engineering_profile)}"`
+    : '';
+  const requestedProfile = process.env.ARCHIFY_QUALITY_PROFILE || meta.quality_profile;
+  const qualityProfile = requestedProfile === 'showcase' ? 'showcase' : 'standard';
+  const advisory = requestedProfile ? '' : ' data-quality-gates="advisory"';
+  return `role="img" lang="${esc(resolveLocale(meta.locale))}" aria-labelledby="archify-diagram-title archify-diagram-description"${animation}${preset}${engineeringProfile} data-quality-profile="${esc(qualityProfile)}"${advisory}`;
+}
+
+// Keep the accessible name inside the SVG so it survives standalone SVG
+// export and embedding. The fixed IDs are deterministic because an Archify
+// artifact intentionally contains one primary diagram SVG.
+export function svgAccessibleText(meta, kind) {
+  const description = meta.subtitle || translateMessage(meta.locale, `diagram.description.${kind}`);
+  return `        <title id="archify-diagram-title">${esc(meta.title)}</title>\n        <desc id="archify-diagram-description">${esc(description)}</desc>`;
+}
+
+export function animateAttr(meta, kind, step) {
+  if (meta.animation !== 'trace') return '';
+  // Ambient trace must finish inside the fixed six-second WebM capture. The
+  // cap affects visual delay only; authored order and semantic identity stay
+  // untouched in the JSON, DOM, Story, and relationship contracts.
+  const safeStep = Number.isFinite(step) && step >= 0 ? Math.min(12, Math.floor(step)) : 0;
+  return ` data-animate="${kind}" style="--step:${safeStep}"`;
+}
+
+// Stable semantic hooks for the standalone HTML explorer. IDs already pass
+// the schema's conservative identifier pattern; escape again at the markup
+// boundary so these helpers remain safe if that contract expands later.
+export function focusNodeAttrs(id, label, metadata = {}, locale) {
+  const optional = [
+    ['data-node-kind', metadata.kind],
+    ['data-node-sublabel', metadata.sublabel],
+    ['data-node-tag', metadata.tag],
+    ['data-node-context', metadata.context],
+    ['data-node-brand', metadata.brand],
+    ['data-node-brand-id', metadata.brandId],
+    ['data-node-brand-status', metadata.brandStatus],
+    ['data-node-brand-source', metadata.brandSource],
+  ].filter(([, value]) => value !== undefined && value !== null && String(value).trim() !== '')
+    .map(([name, value]) => ` ${name}="${esc(String(value))}"`)
+    .join('');
+  const detail = [metadata.sublabel, metadata.context, metadata.brand]
+    .filter((value) => value !== undefined && value !== null && String(value).trim() !== '')
+    .join(', ');
+  const aria = detail
+    ? translateMessage(locale, 'node.focus.detail', { label, detail })
+    : translateMessage(locale, 'node.focus', { label });
+  return `id="node-${esc(id)}" data-node-id="${esc(id)}" data-node-label="${esc(label)}" tabindex="0" role="button" aria-label="${esc(aria)}" aria-pressed="false"${optional}`;
+}
+
+// Native SVG titles preserve a compact details-on-demand fallback when the
+// canonical SVG is embedded inline outside the full Archify viewer.
+export function focusNodeTitle(label, metadata = {}) {
+  const parts = [label, metadata.sublabel, metadata.context, metadata.tag, metadata.brand]
+    .filter((value) => value !== undefined && value !== null && String(value).trim() !== '');
+  return `<title>${esc(parts.join(' · '))}</title>`;
+}
+
+export function focusEdgeAttrs(from, to, label, key, id) {
+  const named = label ? ` data-edge-label="${esc(label)}"` : '';
+  const keyed = key !== undefined && key !== null ? ` data-edge-key="${esc(String(key))}"` : '';
+  const identified = id !== undefined && id !== null && String(id).trim() !== ''
+    ? ` data-edge-id="${esc(String(id))}"`
+    : '';
+  return `data-edge-from="${esc(from)}" data-edge-to="${esc(to)}"${named}${keyed}${identified}`;
+}

package/vendor/archify/renderers/shared/desktop-readability.mjs

@@ -0,0 +1,26 @@
+export const DESKTOP_READABILITY_VIEWPORT = Object.freeze({ width: 1440, height: 900 });
+export const DESKTOP_READER_MIN_WIDTH = 960;
+export const DESKTOP_READER_HORIZONTAL_CHROME = 30;
+export const DESKTOP_READER_DIAGRAM_WIDTH = DESKTOP_READER_MIN_WIDTH - DESKTOP_READER_HORIZONTAL_CHROME;
+export const MIN_PROJECTED_NODE_TEXT_PX = 6;
+
+export function projectedNodeTextPx(sourceFontPx, viewBoxWidth, diagramWidth = DESKTOP_READER_DIAGRAM_WIDTH) {
+  if (![sourceFontPx, viewBoxWidth, diagramWidth].every(Number.isFinite) || viewBoxWidth <= 0 || diagramWidth <= 0) {
+    return Number.NaN;
+  }
+  return sourceFontPx * Math.min(1, diagramWidth / viewBoxWidth);
+}
+
+export function minimumReadableSourceTextPx(
+  viewBoxWidth,
+  diagramWidth = DESKTOP_READER_DIAGRAM_WIDTH,
+  minimumProjectedPx = MIN_PROJECTED_NODE_TEXT_PX,
+) {
+  if (![viewBoxWidth, diagramWidth, minimumProjectedPx].every(Number.isFinite)
+    || viewBoxWidth <= 0
+    || diagramWidth <= 0
+    || minimumProjectedPx <= 0) {
+    return Number.NaN;
+  }
+  return minimumProjectedPx / Math.min(1, diagramWidth / viewBoxWidth);
+}

package/vendor/archify/renderers/shared/diagnostics.mjs

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DIAGNOSTIC_MODE = process.env.ARCHIFY_DIAGNOSTIC_FORMAT === 'json';
+const recorded = [];
+const recordedMessages = new Set();
+const boundaryKey = Symbol.for('archify.renderer-diagnostic-boundary');
+
+function plainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+
+function normalizedDiagnostic(diagnostic) {
+  const message = String(diagnostic?.message || 'Archify could not classify this failure.').trim();
+  return {
+    code: String(diagnostic?.code || 'internal/unclassified'),
+    severity: diagnostic?.severity === 'warning' ? 'warning' : 'error',
+    message,
+    subject: plainObject(diagnostic?.subject),
+    evidence: plainObject(diagnostic?.evidence),
+    supportedFixes: Array.isArray(diagnostic?.supportedFixes)
+      ? [...new Set(diagnostic.supportedFixes.map((fix) => String(fix).trim()).filter(Boolean))]
+      : [],
+  };
+}
+
+export function recordDiagnostic(diagnostic) {
+  if (!DIAGNOSTIC_MODE) return;
+  const normalized = normalizedDiagnostic(diagnostic);
+  if (recordedMessages.has(normalized.message)) return;
+  recordedMessages.add(normalized.message);
+  recorded.push(normalized);
+}
+
+export function throwDiagnosticError(message, diagnostics) {
+  for (const diagnostic of diagnostics || []) recordDiagnostic(diagnostic);
+  const error = new Error(message);
+  error.archifyDiagnostics = (diagnostics || []).map(normalizedDiagnostic);
+  throw error;
+}
+
+export function throwDiagnosticProblems(prefix, problems, { code = 'layout/constraint', subject = {} } = {}) {
+  const messages = (problems || []).map((problem) => String(problem));
+  for (const message of messages) {
+    recordDiagnostic({
+      code,
+      severity: 'error',
+      message,
+      subject,
+      evidence: {},
+      supportedFixes: [],
+    });
+  }
+  throw new Error(`${prefix}:\n- ${messages.join('\n- ')}`);
+}
+
+function fallbackDiagnostic(error) {
+  const input = process.argv[2] ? path.resolve(process.argv[2]) : undefined;
+  if (error instanceof SyntaxError) {
+    return normalizedDiagnostic({
+      code: 'input/json-parse',
+      severity: 'error',
+      message: `Input JSON could not be parsed: ${error.message}`,
+      subject: { input },
+      evidence: { reason: error.message },
+      supportedFixes: ['repair the JSON syntax and run validation again'],
+    });
+  }
+  if (error?.code === 'ENOENT' || error?.code === 'EACCES' || error?.code === 'EISDIR') {
+    return normalizedDiagnostic({
+      code: 'input/read',
+      severity: 'error',
+      message: `Input could not be read: ${error.message}`,
+      subject: { input },
+      evidence: { systemCode: error.code, reason: error.message },
+      supportedFixes: ['provide one readable JSON input file'],
+    });
+  }
+  return normalizedDiagnostic({
+    code: 'internal/unclassified',
+    severity: 'error',
+    message: error?.message || 'Renderer failed without a diagnostic.',
+    subject: { input },
+    evidence: { errorName: error?.name || 'Error' },
+    supportedFixes: [],
+  });
+}
+function rendererFailure(error) {
+  const attached = Array.isArray(error?.archifyDiagnostics)
+    ? error.archifyDiagnostics.map(normalizedDiagnostic)
+    : [];
+  const diagnostics = recorded.length ? recorded : (attached.length ? attached : [fallbackDiagnostic(error)]);
+  return {
+    schemaVersion: 1,
+    ok: false,
+    source: 'renderer',
+    error: error?.message || 'Renderer failed without a diagnostic.',
+    diagnostics,
+  };
+}
+
+export function installRendererDiagnosticBoundary() {
+  if (!DIAGNOSTIC_MODE || globalThis[boundaryKey]) return;
+  globalThis[boundaryKey] = true;
+  process.on('uncaughtException', (error) => {
+    const payload = `${JSON.stringify(rendererFailure(error))}\n`;
+    try {
+      fs.writeSync(process.stderr.fd, payload);
+    } catch {
+      // The renderer is already failing. Avoid replacing its real error with a
+      // secondary stream failure; the parent CLI still has the exit status.
+    }
+    process.exit(1);
+  });
+}

package/vendor/archify/renderers/shared/engineering-profiles.mjs

@@ -0,0 +1,157 @@
+import { throwDiagnosticError } from './diagnostics.mjs';
+
+const DEPLOYMENT_PROFILE = 'deployment-ownership';
+const DEPLOYMENT_BOUNDARY_KINDS = new Set(['region', 'security-group']);
+const PRIVATE_STATE_TYPES = new Set(['database']);
+
+function subject(collection, index, item = {}) {
+  return {
+    diagramType: 'architecture',
+    profile: DEPLOYMENT_PROFILE,
+    collection,
+    index,
+    ...(item.id ? { id: item.id } : {}),
+  };
+}
+
+function membership(boundaries, componentId, kind) {
+  return boundaries
+    .map((boundary, index) => ({ boundary, index }))
+    .filter(({ boundary }) => boundary.kind === kind && boundary.wraps.includes(componentId));
+}
+
+export function deploymentOwnershipDiagnostics(diagram) {
+  const components = Array.isArray(diagram.components) ? diagram.components : [];
+  const boundaries = (Array.isArray(diagram.boundaries) ? diagram.boundaries : [])
+    .map((boundary) => ({ ...boundary, wraps: Array.isArray(boundary.wraps) ? boundary.wraps : [] }));
+  const connections = Array.isArray(diagram.connections) ? diagram.connections : [];
+  const diagnostics = [];
+
+  for (const kind of DEPLOYMENT_BOUNDARY_KINDS) {
+    const count = boundaries.filter((boundary) => boundary.kind === kind).length;
+    if (count > 0) continue;
+    diagnostics.push({
+      code: 'engineering/deployment-boundary-kind',
+      severity: 'error',
+      message: `Deployment ownership requires at least one ${kind} boundary.`,
+      subject: subject('boundaries', -1),
+      evidence: { requiredKind: kind, found: count },
+      supportedFixes: [`add one ${kind} boundary with an explicit wraps list`],
+    });
+  }
+
+  components.forEach((component, index) => {
+    if (component.type === 'external') return;
+    if (typeof component.tag !== 'string' || component.tag.trim() === '') {
+      diagnostics.push({
+        code: 'engineering/deployment-owner-missing',
+        severity: 'error',
+        message: `Deployment component ${JSON.stringify(component.id)} does not name its owner in tag.`,
+        subject: subject('components', index, component),
+        evidence: { componentType: component.type, ownerField: 'tag' },
+        supportedFixes: [`set /components/${index}/tag to the responsible team or owner`],
+      });
+    }
+
+    const regions = membership(boundaries, component.id, 'region');
+    if (regions.length === 0) {
+      diagnostics.push({
+        code: 'engineering/deployment-region-scope',
+        severity: 'error',
+        message: `Deployment component ${JSON.stringify(component.id)} is not assigned to a region boundary.`,
+        subject: subject('components', index, component),
+        evidence: { componentType: component.type, regionMemberships: 0 },
+        supportedFixes: ['add the component id to the real region boundary wraps list'],
+      });
+    } else if (regions.length > 1) {
+      diagnostics.push({
+        code: 'engineering/deployment-region-ambiguous',
+        severity: 'error',
+        message: `Deployment component ${JSON.stringify(component.id)} belongs to more than one region boundary.`,
+        subject: subject('components', index, component),
+        evidence: {
+          componentType: component.type,
+          regions: regions.map(({ boundary, index: boundaryIndex }) => ({ boundaryIndex, label: boundary.label })),
+        },
+        supportedFixes: ['keep the component id in exactly one real region boundary wraps list'],
+      });
+    }
+
+    if (PRIVATE_STATE_TYPES.has(component.type)) {
+      const privateScopes = membership(boundaries, component.id, 'security-group');
+      if (privateScopes.length === 0) {
+        diagnostics.push({
+          code: 'engineering/deployment-private-state',
+          severity: 'error',
+          message: `Stateful component ${JSON.stringify(component.id)} is not assigned to a private security-group boundary.`,
+          subject: subject('components', index, component),
+          evidence: { componentType: component.type, privateMemberships: 0 },
+          supportedFixes: ['add the component id to the real private security-group boundary wraps list'],
+        });
+      }
+    }
+  });
+
+  boundaries.forEach((boundary, index) => {
+    if (boundary.kind !== 'security-group') return;
+    const members = boundary.wraps.map((id) => ({
+      id,
+      regions: membership(boundaries, id, 'region').map(({ boundary: region, index: boundaryIndex }) => ({
+        boundaryIndex,
+        label: region.label,
+      })),
+    }));
+    const regionIndexes = new Set(members.flatMap((member) => member.regions.map((region) => region.boundaryIndex)));
+    const consistent = members.length > 0
+      && members.every((member) => member.regions.length === 1)
+      && regionIndexes.size === 1;
+    if (consistent) return;
+    diagnostics.push({
+      code: 'engineering/deployment-private-region-consistency',
+      severity: 'error',
+      message: `Private boundary ${JSON.stringify(boundary.label)} must contain components from exactly one shared region.`,
+      subject: subject('boundaries', index, boundary),
+      evidence: { boundaryKind: boundary.kind, members },
+      supportedFixes: ['assign every private-boundary component to exactly one shared region boundary'],
+    });
+  });
+
+  connections.forEach((connection, index) => {
+    const crossedBoundaries = boundaries
+      .map((boundary, boundaryIndex) => ({
+        boundaryIndex,
+        kind: boundary.kind,
+        label: boundary.label,
+        fromInside: boundary.wraps.includes(connection.from),
+        toInside: boundary.wraps.includes(connection.to),
+      }))
+      .filter((boundary) => DEPLOYMENT_BOUNDARY_KINDS.has(boundary.kind) && boundary.fromInside !== boundary.toInside);
+    if (crossedBoundaries.length === 0 || (typeof connection.label === 'string' && connection.label.trim() !== '')) return;
+    diagnostics.push({
+      code: 'engineering/deployment-crossing-mechanism',
+      severity: 'error',
+      message: `Cross-boundary connection ${JSON.stringify(connection.id || `${connection.from}->${connection.to}`)} does not name its mechanism.`,
+      subject: subject('connections', index, connection),
+      evidence: {
+        from: connection.from,
+        to: connection.to,
+        crossedBoundaries: crossedBoundaries.map(({ boundaryIndex, kind, label }) => ({ boundaryIndex, kind, label })),
+      },
+      supportedFixes: [`set /connections/${index}/label to the real cross-boundary mechanism`],
+    });
+  });
+
+  return diagnostics;
+}
+
+export function validateEngineeringProfile(diagramType, diagram) {
+  const profile = diagram.meta?.engineering_profile;
+  if (!profile) return;
+  if (diagramType !== 'architecture' || profile !== DEPLOYMENT_PROFILE) return;
+  const diagnostics = deploymentOwnershipDiagnostics(diagram);
+  if (!diagnostics.length) return;
+  throwDiagnosticError(
+    `Engineering profile ${JSON.stringify(profile)} failed:\n${diagnostics.map((entry) => `- ${entry.message}`).join('\n')}`,
+    diagnostics,
+  );
+}