@hybridlabor-api/aos 4.6.5 → 4.7.0

package/skills/global_config/archify/renderers/shared/layout-report.mjs

@@ -0,0 +1,40 @@
+/** Serialize computed layout for dry-run / inspect (#9). */
+
+export function componentBox(c) {
+  return {
+    id: c.id,
+    type: c.type,
+    label: c.label,
+    x: Math.round(c.x),
+    y: Math.round(c.y),
+    width: c.width,
+    height: c.height,
+    ...(Number.isInteger(c.row) ? { row: c.row } : {}),
+    ...(Number.isInteger(c.col) ? { col: c.col } : {}),
+    ...(Array.isArray(c.pos) ? { pos: c.pos.map(Math.round) } : {}),
+  };
+}
+
+export function boundaryBox(b) {
+  return {
+    kind: b.kind,
+    label: b.label,
+    x: Math.round(b.x),
+    y: Math.round(b.y),
+    width: Math.round(b.width),
+    height: Math.round(b.height),
+    wraps: b.wraps,
+  };
+}
+
+export function connectionPath(conn, routed, labelAt) {
+  return {
+    from: conn.from,
+    to: conn.to,
+    label: conn.label ?? null,
+    variant: conn.variant ?? 'default',
+    route: conn.route ?? 'auto',
+    points: routed.points.map(([x, y]) => [Math.round(x), Math.round(y)]),
+    ...(labelAt ? { labelAt: labelAt.map(Math.round) } : {}),
+  };
+}

package/skills/global_config/archify/renderers/shared/legend.mjs

@@ -0,0 +1,217 @@
+import { throwDiagnosticError } from './diagnostics.mjs';
+import { rectsOverlap, segmentIntersectsRect } from './geometry.mjs';
+import { esc, textUnits } from './utils.mjs';
+import { translateMessage } from './i18n.mjs';
+
+const DEFAULT_FONT_SIZE = 8;
+const DEFAULT_ITEM_GAP = 22;
+const DEFAULT_LINE_GAP = 22;
+const DEFAULT_SWATCH_GAP = 8;
+const TEXT_ADVANCE_EM = 0.62;
+const INTERACTIVE_BADGE_ALLOWANCE = 21;
+
+export function relationshipLegendObstacles(relations, { pointsFor, labelRectFor } = {}) {
+  const obstacles = [];
+  for (const [index, relation] of (Array.isArray(relations) ? relations : []).entries()) {
+    const points = typeof pointsFor === 'function' ? pointsFor(relation, index) : [];
+    const finitePoints = (Array.isArray(points) ? points : []).filter((point) => (
+      Array.isArray(point) && point.length === 2 && point.every(Number.isFinite)
+    ));
+    for (let pointIndex = 0; pointIndex < finitePoints.length - 1; pointIndex += 1) {
+      obstacles.push({
+        kind: 'relationship-segment',
+        start: finitePoints[pointIndex],
+        end: finitePoints[pointIndex + 1],
+      });
+    }
+    const labelRect = typeof labelRectFor === 'function' ? labelRectFor(relation, index) : null;
+    if (labelRect && [labelRect.x, labelRect.y, labelRect.width, labelRect.height].every(Number.isFinite)) {
+      obstacles.push({ kind: 'relationship-label', ...labelRect });
+    }
+  }
+  return obstacles;
+}
+
+export function resolveLegend(config, catalog, presentKinds) {
+  const mode = config?.mode || 'auto';
+  if (mode === 'hidden') return [];
+  const present = presentKinds instanceof Set ? presentKinds : new Set(presentKinds || []);
+  const overrides = config?.entries || {};
+
+  return catalog.flatMap((catalogEntry) => {
+    const override = overrides[catalogEntry.kind] || {};
+    const selectedByMode = mode === 'all' || present.has(catalogEntry.kind);
+    const visible = override.visible === true || (selectedByMode && override.visible !== false);
+    if (!visible) return [];
+    return [{
+      ...catalogEntry,
+      label: override.label || catalogEntry.label,
+      present: present.has(catalogEntry.kind),
+      interactive: catalogEntry.interactive !== false && present.has(catalogEntry.kind),
+    }];
+  });
+}
+
+function measuredEntryWidth(entry, fontSize, swatchGap) {
+  const swatchWidth = entry.swatchWidth ?? 14;
+  return Math.ceil(
+    swatchWidth
+    + swatchGap
+    + textUnits(entry.label) * fontSize * TEXT_ADVANCE_EM
+    + (entry.interactive ? INTERACTIVE_BADGE_ALLOWANCE : 0),
+  );
+}
+
+// One pure footprint calculation owns both auto-viewBox sizing and final SVG
+// placement. Callers must not maintain a second approximation of legend width
+// or row count; that would make generated geometry disagree with validation.
+export function legendFootprint(entries, {
+  width,
+  fontSize = DEFAULT_FONT_SIZE,
+  itemGap = DEFAULT_ITEM_GAP,
+  lineGap = DEFAULT_LINE_GAP,
+  swatchGap = DEFAULT_SWATCH_GAP,
+} = {}) {
+  if (!entries.length) {
+    return { measured: [], rows: [], rowCount: 0, minWidth: 0, extraHeight: 0 };
+  }
+  const measured = entries.map((entry) => ({
+    ...entry,
+    width: measuredEntryWidth(entry, fontSize, entry.swatchGap ?? swatchGap),
+  }));
+  const rows = [[]];
+  let cursor = 0;
+  for (const entry of measured) {
+    const row = rows.at(-1);
+    const required = (row.length ? itemGap : 0) + entry.width;
+    if (row.length && cursor + required > width) {
+      rows.push([entry]);
+      cursor = entry.width;
+    } else {
+      row.push(entry);
+      cursor += required;
+    }
+  }
+  return {
+    measured,
+    rows,
+    rowCount: rows.length,
+    minWidth: Math.max(...measured.map((entry) => entry.width)),
+    extraHeight: (rows.length - 1) * lineGap,
+  };
+}
+
+export function measureLegend(entries, {
+  x,
+  baselineY,
+  width,
+  fontSize = DEFAULT_FONT_SIZE,
+  itemGap = DEFAULT_ITEM_GAP,
+  lineGap = DEFAULT_LINE_GAP,
+  swatchGap = DEFAULT_SWATCH_GAP,
+  minTitleY = 0,
+  obstacles = [],
+  unfit = 'error',
+  diagramType = 'diagram',
+} = {}) {
+  if (!entries.length) return { entries: [], rowCount: 0, titleY: null };
+  const footprint = legendFootprint(entries, { width, fontSize, itemGap, lineGap, swatchGap });
+  const tooWide = footprint.measured.find((entry) => entry.width > width);
+  if (tooWide) {
+    if (unfit === 'hide') return null;
+    const message = `[legend/label-too-wide] ${diagramType} legend label for "${tooWide.kind}" needs ${tooWide.width}px but only ${width}px is available.`;
+    throwDiagnosticError(message, [{
+      code: 'legend/label-too-wide',
+      severity: 'error',
+      message,
+      subject: { diagramType, path: `/meta/legend/entries/${tooWide.kind}/label` },
+      evidence: { kind: tooWide.kind, measuredWidthPx: tooWide.width, availableWidthPx: width },
+      supportedFixes: ['shorten the legend label or use a wider viewBox'],
+    }]);
+  }
+
+  const titleY = baselineY - footprint.extraHeight - 20;
+  const legendTopY = titleY - 10;
+  if (legendTopY < minTitleY) {
+    if (unfit === 'hide') return null;
+    const message = `[legend/vertical-overflow] ${diagramType} legend needs ${footprint.rowCount} rows, which would start at y=${legendTopY} above the available legend band at y=${minTitleY}.`;
+    throwDiagnosticError(message, [{
+      code: 'legend/vertical-overflow',
+      severity: 'error',
+      message,
+      subject: { diagramType, path: '/meta/legend' },
+      evidence: { rowCount: footprint.rowCount, requiredTopY: legendTopY, availableTopY: minTitleY },
+      supportedFixes: ['shorten legend labels, hide nonessential entries, or use a wider viewBox'],
+    }]);
+  }
+
+  const positioned = [];
+  footprint.rows.forEach((row, rowIndex) => {
+    let entryX = x;
+    const baseline = baselineY - (footprint.rowCount - rowIndex - 1) * lineGap;
+    for (const entry of row) {
+      positioned.push({ ...entry, x: entryX, baseline, row: rowIndex });
+      entryX += entry.width + itemGap;
+    }
+  });
+
+  const legendRects = [
+    { kind: 'title', x, y: legendTopY, width: 48, height: 14 },
+    ...positioned.map((entry) => ({
+      kind: entry.kind,
+      x: entry.x,
+      y: entry.baseline - 10,
+      width: entry.width,
+      height: 14,
+    })),
+  ];
+  const collision = legendRects.find((legendRect) => obstacles.some((obstacle) => (
+    Array.isArray(obstacle.start) && Array.isArray(obstacle.end)
+      ? segmentIntersectsRect({ start: obstacle.start, end: obstacle.end }, legendRect)
+      : rectsOverlap(obstacle, legendRect)
+  )));
+  if (collision) {
+    if (unfit === 'hide') return null;
+    const message = `[legend/content-overlap] ${diagramType} legend entry "${collision.kind}" overlaps authored relationship geometry.`;
+    throwDiagnosticError(message, [{
+      code: 'legend/content-overlap',
+      severity: 'error',
+      message,
+      subject: { diagramType, path: '/meta/legend' },
+      evidence: { legendKind: collision.kind, legendRect: collision },
+      supportedFixes: ['shorten or hide legend entries, use a wider viewBox, or move the authored relationship route/label out of the legend band'],
+    }]);
+  }
+
+  return {
+    entries: positioned,
+    rowCount: footprint.rowCount,
+    titleY,
+    fontSize,
+  };
+}
+
+export function renderLegend({ entries, layout, renderSwatch, locale }) {
+  if (!entries.length) return '';
+  const measured = measureLegend(entries, layout);
+  if (!measured) return '';
+  const hasInteractiveEntries = measured.entries.some((entry) => entry.interactive);
+  const renderedFontSize = measured.fontSize < 8 ? measured.fontSize + 0.5 : measured.fontSize + 2;
+  const rootAttributes = hasInteractiveEntries ? ' data-legend="" data-legend-bridge=""' : ' data-legend=""';
+  const parts = [
+    `        <g${rootAttributes}>`,
+    `          <text x="${layout.x}" y="${measured.titleY}" class="t-primary" font-size="12" font-weight="650">${esc(translateMessage(locale, 'legend.title'))}</text>`,
+  ];
+
+  for (const entry of measured.entries) {
+    const interactive = entry.interactive
+      ? ` data-legend-kind="${esc(entry.kind)}" data-legend-label="${esc(entry.label)}"`
+      : '';
+    parts.push(`          <g data-legend-semantic-kind="${esc(entry.kind)}"${interactive} data-legend-x="${entry.x}" data-legend-baseline="${entry.baseline}" data-legend-width="${entry.width}">`);
+    parts.push(`            ${renderSwatch(entry)}`);
+    parts.push(`            <text x="${entry.x + (entry.swatchWidth ?? 14) + (entry.swatchGap ?? DEFAULT_SWATCH_GAP)}" y="${entry.baseline}" class="t-muted" font-size="${renderedFontSize}" font-weight="500">${esc(entry.label)}</text>`);
+    parts.push('          </g>');
+  }
+  parts.push('        </g>');
+  return parts.join('\n');
+}

package/skills/global_config/archify/renderers/shared/output-path.mjs

@@ -0,0 +1,340 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_SYMLINK_DEPTH = 64;
+const directorySemanticsCache = new Map();
+let semanticsProbeSequence = 0;
+
+function splitAbsolute(absolutePath) {
+  const root = path.parse(absolutePath).root;
+  return {
+    root,
+    segments: absolutePath.slice(root.length).split(path.sep).filter(Boolean),
+  };
+}
+
+function canonicalize(targetPath, depth) {
+  const absolutePath = path.resolve(targetPath);
+  const { root, segments } = splitAbsolute(absolutePath);
+  let current = root;
+
+  for (let index = 0; index < segments.length; index += 1) {
+    const candidate = path.join(current, segments[index]);
+    let stat;
+    try {
+      stat = fs.lstatSync(candidate);
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+        return path.resolve(current, ...segments.slice(index));
+      }
+      throw error;
+    }
+
+    if (stat.isSymbolicLink()) {
+      if (depth >= MAX_SYMLINK_DEPTH) {
+        const error = new Error(`Could not resolve path because a symbolic-link cycle includes "${candidate}".`);
+        error.code = 'ELOOP';
+        error.path = candidate;
+        throw error;
+      }
+      const link = fs.readlinkSync(candidate);
+      const linkTarget = path.isAbsolute(link) ? link : path.resolve(path.dirname(candidate), link);
+      return canonicalize(path.join(linkTarget, ...segments.slice(index + 1)), depth + 1);
+    }
+
+    current = fs.realpathSync.native(candidate);
+  }
+
+  return path.normalize(current);
+}
+
+export function canonicalFuturePath(targetPath) {
+  try {
+    return canonicalize(targetPath, 0);
+  } catch (error) {
+    if (error?.code !== 'ELOOP') throw error;
+    const output = path.resolve(targetPath);
+    throw new OutputPathError(`Output path contains a symbolic-link cycle: "${output}".`, {
+      code: 'output/symlink-cycle',
+      message: 'Output path could not be resolved because it contains a symbolic-link cycle.',
+      subject: { output },
+      evidence: {
+        systemCode: 'ELOOP',
+        ...(error.path ? { cycleAt: path.resolve(error.path) } : {}),
+      },
+      supportedFixes: ['remove the symbolic-link cycle or choose an output path outside it'],
+    });
+  }
+}
+
+function hasFileIdentity(stat) {
+  return stat.ino !== 0 && stat.ino !== 0n;
+}
+
+function sameFileIdentity(left, right) {
+  return hasFileIdentity(left)
+    && hasFileIdentity(right)
+    && left.dev === right.dev
+    && left.ino === right.ino;
+}
+
+function nearestExistingDirectory(targetPath) {
+  let directory = path.dirname(targetPath);
+  while (true) {
+    try {
+      const stat = fs.statSync(directory);
+      if (stat.isDirectory()) {
+        return {
+          path: fs.realpathSync.native(directory),
+          stat,
+        };
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') return null;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+function directoryIdentityKey(directory) {
+  if (!hasFileIdentity(directory.stat)) return null;
+  return `${directory.stat.dev}:${directory.stat.ino}`;
+}
+
+function probeNamesAlias(directoryPath, authoredName, lookupName) {
+  let fileDescriptor;
+  let created = false;
+  let result = null;
+  let cleaned = true;
+  const authoredPath = path.join(directoryPath, authoredName);
+  const lookupPath = path.join(directoryPath, lookupName);
+  try {
+    fileDescriptor = fs.openSync(authoredPath, 'wx', 0o600);
+    created = true;
+    fs.closeSync(fileDescriptor);
+    fileDescriptor = undefined;
+
+    let authored;
+    let lookup;
+    try {
+      authored = fs.statSync(authoredPath);
+      lookup = fs.statSync(lookupPath);
+    } catch (error) {
+      if (error.code === 'ENOENT') result = false;
+    }
+    if (authored && lookup) {
+      if (sameFileIdentity(authored, lookup)) {
+        result = true;
+      } else {
+        try {
+          result = fs.realpathSync.native(authoredPath) === fs.realpathSync.native(lookupPath);
+        } catch {
+          result = null;
+        }
+      }
+    }
+  } catch {
+    result = null;
+  } finally {
+    if (fileDescriptor !== undefined) {
+      try {
+        fs.closeSync(fileDescriptor);
+      } catch {
+        cleaned = false;
+      }
+    }
+    if (created) {
+      try {
+        fs.unlinkSync(authoredPath);
+      } catch {
+        cleaned = false;
+      }
+    }
+  }
+  return cleaned ? result : null;
+}
+
+function probeDirectorySemantics(directory) {
+  const cacheKey = directoryIdentityKey(directory);
+  if (cacheKey && directorySemanticsCache.has(cacheKey)) {
+    return directorySemanticsCache.get(cacheKey);
+  }
+
+  semanticsProbeSequence += 1;
+  const suffix = `${process.pid}-${Date.now().toString(36)}-${semanticsProbeSequence}`;
+  const caseAuthored = `.archify-Case-Probe-${suffix}`;
+  const normalizationAuthored = `.archify-norm-\u00e9-probe-${suffix}`;
+  const semantics = {
+    caseInsensitive: probeNamesAlias(
+      directory.path,
+      caseAuthored,
+      caseAuthored.toLowerCase(),
+    ),
+    normalizationInsensitive: probeNamesAlias(
+      directory.path,
+      normalizationAuthored,
+      normalizationAuthored.normalize('NFD'),
+    ),
+  };
+  if (
+    cacheKey
+    && semantics.caseInsensitive !== null
+    && semantics.normalizationInsensitive !== null
+  ) {
+    directorySemanticsCache.set(cacheKey, semantics);
+  }
+  return semantics;
+}
+
+function sameDirectory(left, right) {
+  return left.path === right.path || sameFileIdentity(left.stat, right.stat);
+}
+
+function futurePathsAlias(leftPath, rightPath) {
+  const left = canonicalFuturePath(leftPath);
+  const right = canonicalFuturePath(rightPath);
+  if (left === right) return true;
+
+  const leftDirectory = nearestExistingDirectory(left);
+  const rightDirectory = nearestExistingDirectory(right);
+  if (!leftDirectory || !rightDirectory || !sameDirectory(leftDirectory, rightDirectory)) {
+    return false;
+  }
+
+  const semantics = probeDirectorySemantics(leftDirectory);
+  let comparableLeft = path.relative(leftDirectory.path, left);
+  let comparableRight = path.relative(rightDirectory.path, right);
+  if (semantics.normalizationInsensitive !== false) {
+    comparableLeft = comparableLeft.normalize('NFC');
+    comparableRight = comparableRight.normalize('NFC');
+  }
+  if (semantics.caseInsensitive !== false) {
+    comparableLeft = comparableLeft.toLowerCase();
+    comparableRight = comparableRight.toLowerCase();
+  }
+  return comparableLeft === comparableRight;
+}
+
+export function pathsAlias(leftPath, rightPath) {
+  if (futurePathsAlias(leftPath, rightPath)) return true;
+  try {
+    const left = fs.statSync(leftPath);
+    const right = fs.statSync(rightPath);
+    return sameFileIdentity(left, right);
+  } catch {
+    return false;
+  }
+}
+
+function pathIsInside(directoryPath, targetPath) {
+  const relative = path.relative(canonicalFuturePath(directoryPath), canonicalFuturePath(targetPath));
+  return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+}
+
+export class OutputPathError extends Error {
+  constructor(message, diagnostic) {
+    super(message);
+    this.name = 'OutputPathError';
+    this.archifyDiagnostics = [{
+      severity: 'error',
+      subject: {},
+      evidence: {},
+      supportedFixes: [],
+      ...diagnostic,
+    }];
+  }
+}
+
+export function resolveOutputPath({
+  requestedOutput,
+  authoredOutput,
+  defaultOutput,
+  inputPaths = [],
+  inputDescription = 'an input',
+  otherOutputPaths = [],
+  cwd = process.cwd(),
+  requiredExtension = '.html',
+}) {
+  const rawOutput = requestedOutput || authoredOutput || defaultOutput;
+  const source = requestedOutput ? 'cli' : (authoredOutput ? 'meta' : 'default');
+  if (
+    source === 'meta'
+    && (path.isAbsolute(rawOutput) || path.posix.isAbsolute(rawOutput) || path.win32.isAbsolute(rawOutput))
+  ) {
+    throw new OutputPathError('meta.output must be a relative path.', {
+      code: 'output/meta-absolute',
+      message: 'meta.output must be a relative path resolved from the current working directory.',
+      subject: { output: rawOutput },
+      supportedFixes: ['set meta.output to a relative .html path inside the current working directory'],
+    });
+  }
+  if (source === 'meta' && path.extname(rawOutput).toLowerCase() !== '.html') {
+    throw new OutputPathError('meta.output must target an .html file.', {
+      code: 'output/meta-extension',
+      message: 'meta.output must target an .html file.',
+      subject: { output: rawOutput },
+      supportedFixes: ['change meta.output to a path ending in .html'],
+    });
+  }
+  const outputPath = path.resolve(cwd, rawOutput);
+  if (source === 'meta' && path.extname(canonicalFuturePath(outputPath)).toLowerCase() !== '.html') {
+    throw new OutputPathError('meta.output must resolve to an .html file.', {
+      code: 'output/meta-resolved-extension',
+      message: 'meta.output must resolve to an .html file after symbolic links are followed.',
+      subject: { output: rawOutput },
+      supportedFixes: ['remove the symbolic-link alias or point it to an .html target inside the current working directory'],
+    });
+  }
+  if (source === 'meta' && !pathIsInside(cwd, outputPath)) {
+    throw new OutputPathError('meta.output must stay inside the current working directory.', {
+      code: 'output/meta-outside-cwd',
+      message: 'meta.output must stay inside the current working directory after symbolic links are resolved.',
+      subject: { output: rawOutput, cwd: path.resolve(cwd) },
+      supportedFixes: ['set meta.output to a relative .html path inside the current working directory'],
+    });
+  }
+
+  for (const inputPath of inputPaths) {
+    if (!pathsAlias(outputPath, inputPath)) continue;
+    throw new OutputPathError(`Output must not replace ${inputDescription}.`, {
+      code: 'output/input-alias',
+      message: `Output must not replace ${inputDescription}, including through a symbolic-link or future-path alias.`,
+      subject: { output: outputPath, input: path.resolve(inputPath) },
+      supportedFixes: ['choose an output path that is distinct from every input path'],
+    });
+  }
+  for (const otherOutputPath of otherOutputPaths) {
+    if (!pathsAlias(outputPath, otherOutputPath)) continue;
+    throw new OutputPathError('Output targets must use distinct paths.', {
+      code: 'output/target-alias',
+      message: 'Output targets must use distinct paths, including symbolic-link and future-path aliases.',
+      subject: { output: outputPath, conflictingOutput: path.resolve(otherOutputPath) },
+      supportedFixes: ['choose distinct paths for every generated output'],
+    });
+  }
+
+  // Keep explicit CLI directories unrestricted, but reject mistaken file types.
+  // Alias checks above retain priority when a target would overwrite an input.
+  if (source === 'cli') {
+    const resolvedOutput = canonicalFuturePath(outputPath);
+    const authoredMatches = path.extname(rawOutput).toLowerCase() === requiredExtension;
+    const resolvedMatches = path.extname(resolvedOutput).toLowerCase() === requiredExtension;
+    if (!authoredMatches || !resolvedMatches) {
+      const message = `CLI output must ${authoredMatches ? 'resolve to' : 'target'} a ${requiredExtension} file.`;
+      throw new OutputPathError(message, {
+        code: authoredMatches ? 'output/cli-resolved-extension' : 'output/cli-extension',
+        message,
+        subject: { output: rawOutput },
+        evidence: { resolvedOutput, requiredExtension },
+        supportedFixes: [`choose a path ending in ${requiredExtension} whose symbolic-link target also ends in ${requiredExtension}`],
+      });
+    }
+  }
+
+  return {
+    outputPath,
+    source,
+  };
+}