create-yss-spec 3.0.0 → 3.0.1

package/template/.hermes/skills/archify/renderers/shared/layout-report.mjs

@@ -1,40 +0,0 @@
-/** 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/template/.hermes/skills/archify/renderers/shared/legend.mjs

@@ -1,217 +0,0 @@
-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/template/.hermes/skills/archify/renderers/shared/output-path.mjs

@@ -1,321 +0,0 @@
-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(),
-}) {
-  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'],
-    });
-  }
-
-  return {
-    outputPath,
-    source,
-  };
-}