dsh-archify-projects 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,173 @@
+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');
+let recordingSuppressionDepth = 0;
+
+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))]
+      : [],
+    ...(Array.isArray(diagnostic?.suppresses) ? {
+      suppresses: [...new Set(diagnostic.suppresses.map((code) => String(code).trim()).filter(Boolean))],
+    } : {}),
+  };
+}
+
+export function recordDiagnostic(diagnostic) {
+  if (!DIAGNOSTIC_MODE || recordingSuppressionDepth > 0) return;
+  const normalized = normalizedDiagnostic(diagnostic);
+  if (recordedMessages.has(normalized.message)) return;
+  recordedMessages.add(normalized.message);
+  recorded.push(normalized);
+}
+
+export function withDiagnosticRecordingSuppressed(callback) {
+  recordingSuppressionDepth += 1;
+  try {
+    return callback();
+  } finally {
+    recordingSuppressionDepth -= 1;
+  }
+}
+
+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 = {}, diagnostics: details = [] } = {}) {
+  const messages = (problems || []).map((problem) => String(problem));
+  const byMessage = new Map(details.map((entry) => [entry.message, entry]));
+  const diagnostics = messages.map((message) => normalizedDiagnostic(byMessage.get(message) || {
+      code,
+      severity: 'error',
+      message,
+      subject,
+      evidence: {},
+      supportedFixes: [],
+    }));
+  throwDiagnosticError(`${prefix}:\n- ${messages.join('\n- ')}`, diagnostics);
+}
+
+function fallbackDiagnostic(error) {
+  const input = process.argv[2] ? path.resolve(process.argv[2]) : undefined;
+  return normalizedDiagnostic({
+    code: 'internal/unclassified',
+    severity: 'error',
+    message: error?.message || 'Renderer failed without a diagnostic.',
+    subject: { input },
+    evidence: { errorName: error?.name || 'Error' },
+    supportedFixes: [],
+  });
+}
+export function rendererFailure(error) {
+  const attached = Array.isArray(error?.archifyDiagnostics)
+    ? error.archifyDiagnostics.map(normalizedDiagnostic)
+    : [];
+  // Earlier diagnostics do not classify a later, unrelated implementation error.
+  const diagnostics = attached.length
+    ? (recorded.length ? recorded : attached)
+    : [fallbackDiagnostic(error)];
+  return {
+    schemaVersion: 1,
+    ok: false,
+    source: 'renderer',
+    error: error?.message || 'Renderer failed without a diagnostic.',
+    diagnostics,
+  };
+}
+
+// Match the public CLI's text format without making its standalone doctor
+// bootstrap depend on this renderer runtime being present.
+function formatDiagnostics(error, diagnostics = []) {
+  if (!diagnostics.length) return error;
+  return [
+    error,
+    ...diagnostics.map((entry) => {
+      const fix = entry.supportedFixes?.length ? ` Fix: ${entry.supportedFixes.join('; ')}.` : '';
+      return `[${entry.code}] ${entry.message}${fix}`;
+    }),
+  ].join('\n');
+}
+
+const readerSignal = new Int32Array(new SharedArrayBuffer(4));
+
+function waitForReader() {
+  // Sleep instead of spinning on EAGAIN. A retry budget looks like a safeguard
+  // and behaves like a truncation gate: a spinning loop burns thousands of
+  // attempts in a few milliseconds, so a reader that is merely slow to start
+  // exhausts it and loses the tail of the receipt. Waiting costs nothing while
+  // the reader catches up, and a reader that goes away raises EPIPE, which the
+  // caller already treats as a real write failure.
+  Atomics.wait(readerSignal, 0, 0, 1);
+}
+
+export function installRendererDiagnosticBoundary() {
+  if (globalThis[boundaryKey]) return;
+  globalThis[boundaryKey] = true;
+  if (!DIAGNOSTIC_MODE) {
+    process.once('uncaughtException', (error) => {
+      // Only errors classified at their operation boundary are author-facing.
+      // Preserve Node's debugging information for unexpected implementation errors.
+      if (!error?.archifyDiagnostics?.length) {
+        // The once-listener is already removed. Rethrow outside the exception
+        // handler so Node retains its normal stack and exit code (not code 7).
+        process.nextTick(() => { throw error; });
+        return;
+      }
+      const payload = `${formatDiagnostics(error.message, error.archifyDiagnostics)}\n`;
+      process.stderr.once('error', () => process.exit(1));
+      process.stderr.write(payload, () => process.exit(1));
+    });
+    return;
+  }
+  process.on('uncaughtException', (error) => {
+    const payload = `${JSON.stringify(rendererFailure(error))}\n`;
+    try {
+      // stderr may be a pipe. fs.writeSync performs a PARTIAL write once the
+      // payload exceeds the OS pipe buffer (8KB on macOS) and returns the byte
+      // count actually written. Ignoring that return value silently truncated
+      // large diagnostic payloads mid-JSON, so the parent CLI's JSON.parse
+      // failed and the fail-closed boundary reported internal/unclassified
+      // instead of the diagnostics we had already computed. Loop until drained.
+      // A full pipe also makes writeSync throw EAGAIN; wait for the reader
+      // rather than treat it as a stream failure, otherwise the tail is
+      // dropped just the same.
+      const buffer = Buffer.from(payload, 'utf8');
+      let written = 0;
+      while (written < buffer.length) {
+        try {
+          written += fs.writeSync(process.stderr.fd, buffer, written, buffer.length - written);
+        } catch (writeError) {
+          if (writeError?.code === 'EAGAIN') {
+            waitForReader();
+            continue;
+          }
+          throw writeError;
+        }
+      }
+    } 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/skills/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,
+  );
+}