@diagrammo/dgmo 0.34.0 → 0.36.0

package/src/migrate/embedded.ts

@@ -1,238 +0,0 @@
-// Markdown / mdx fenced-block handler for `dgmo migrate --embedded`.
-//
-// Walks ```dgmo (and ```diagrammo) fenced blocks inside `.md` / `.mdx`
-// files, migrates each block, and re-assembles the document. Atomic
-// per file: if any block fails to parse under the legacy parser, the
-// entire file is skipped — no writes, no partial migrations, no `.bak`.
-//
-// Why atomic? Half-new-half-legacy markdown files are unreachable —
-// a re-run on a partially-migrated file would produce inconsistent
-// behavior and a corrupted `.bak`. Per spec "Migration Tool Contract".
-
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-
-import { parseDgmo } from '../dgmo-router';
-import { METADATA_DIAGNOSTIC_CODES } from '../diagnostics';
-import { migrateContent } from './index';
-
-// Diagnostic codes the migration tool itself is repairing — these
-// MUST NOT count as "block fails to parse" reasons, otherwise every
-// legacy block would be skipped. Derived from the canonical registry
-// so a code rename can't silently desync the migrator.
-const MIGRATION_TARGET_CODES = new Set<string>([
-  METADATA_DIAGNOSTIC_CODES.PIPE_OPERATOR_REMOVED,
-  METADATA_DIAGNOSTIC_CODES.GANTT_BARE_PERCENT_REMOVED,
-  METADATA_DIAGNOSTIC_CODES.JOURNEY_BARE_SCORE_REMOVED,
-  METADATA_DIAGNOSTIC_CODES.PYRAMID_BARE_DESCRIPTION_REMOVED,
-  METADATA_DIAGNOSTIC_CODES.RING_BARE_DESCRIPTION_REMOVED,
-]);
-
-const FENCE_RE = /^(\s*)(```+|~~~+)\s*(dgmo|diagrammo)\b([^\n]*)$/i;
-
-interface FencedBlock {
-  /** Index in the line array where the opening fence sits. */
-  readonly fenceStartLine: number;
-  /** Index of the closing fence line. */
-  readonly fenceEndLine: number;
-  /** The fence sequence (e.g. ` ``` ` or ` ~~~ `), used to find the close. */
-  readonly fenceSeq: string;
-  /** 0-based indices [start, end) of the body lines (between fences, exclusive). */
-  readonly bodyStart: number;
-  readonly bodyEnd: number;
-  /** Joined body source. */
-  readonly body: string;
-}
-
-/**
- * Locate every fenced ```dgmo / ```diagrammo block in `source`.
- * Returns empty array when no blocks exist (caller treats as no-op).
- */
-function findFencedBlocks(source: string): FencedBlock[] {
-  const lines = source.split('\n');
-  const blocks: FencedBlock[] = [];
-
-  let i = 0;
-  while (i < lines.length) {
-    const open = lines[i]!.match(FENCE_RE);
-    if (!open) {
-      i++;
-      continue;
-    }
-    const fenceSeq = open[2]!;
-    const indent = open[1] ?? '';
-    // Find matching closer — a fence line whose sequence is `fenceSeq`
-    // (or longer of the same char) at the same or lower indent.
-    const closeRe = new RegExp(
-      `^${escapeRegex(indent)}${escapeRegex(fenceSeq[0]!)}{${fenceSeq.length},}\\s*$`
-    );
-    let j = i + 1;
-    while (j < lines.length) {
-      if (closeRe.test(lines[j]!)) break;
-      j++;
-    }
-    if (j >= lines.length) {
-      // Unclosed fence — bail; don't treat as a block.
-      break;
-    }
-    const body = lines.slice(i + 1, j).join('\n');
-    blocks.push({
-      fenceStartLine: i,
-      fenceEndLine: j,
-      fenceSeq,
-      bodyStart: i + 1,
-      bodyEnd: j,
-      body,
-    });
-    i = j + 1;
-  }
-
-  return blocks;
-}
-
-function escapeRegex(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-export interface EmbeddedMigrationResult {
-  readonly path: string;
-  readonly original: string;
-  readonly migrated: string;
-  readonly changed: boolean;
-  /** True when the file was skipped due to a parse-error block. */
-  readonly skipped: boolean;
-  /** Reason for skip — `null` when not skipped. */
-  readonly skipReason: string | null;
-  /** Number of dgmo blocks found in the file. */
-  readonly blockCount: number;
-  /** Number of blocks that actually changed. */
-  readonly changedBlocks: number;
-  readonly backupWritten: boolean;
-  readonly written: boolean;
-}
-
-export interface MigrateEmbeddedOptions {
-  /** When false, write changes to disk. Default: true (dry-run). */
-  readonly dryRun?: boolean;
-  /** When true and dryRun is false, skip writing the `.bak` sidecar. */
-  readonly noBackup?: boolean;
-}
-
-/**
- * Migrate every ```dgmo block in an `.md` / `.mdx` file. All-or-nothing
- * per file — a single parse-error block aborts the whole file.
- */
-export function migrateEmbedded(
-  path: string,
-  opts: MigrateEmbeddedOptions = {}
-): EmbeddedMigrationResult {
-  const dryRun = opts.dryRun ?? true;
-  const original = readFileSync(path, 'utf-8');
-  const blocks = findFencedBlocks(original);
-
-  if (blocks.length === 0) {
-    return {
-      path,
-      original,
-      migrated: original,
-      changed: false,
-      skipped: false,
-      skipReason: null,
-      blockCount: 0,
-      changedBlocks: 0,
-      backupWritten: false,
-      written: false,
-    };
-  }
-
-  // Pre-flight: every block must parse cleanly under the legacy
-  // parser modulo the migration-target diagnostics (those are what
-  // we're rewriting). Any other severity:error or a null chart-type
-  // detection aborts the whole file (atomicity contract).
-  for (const block of blocks) {
-    const parsed = parseDgmo(block.body);
-    if (parsed.chartType === null) {
-      return {
-        path,
-        original,
-        migrated: original,
-        changed: false,
-        skipped: true,
-        skipReason: `block at line ${block.fenceStartLine + 1} has no recognized chart type`,
-        blockCount: blocks.length,
-        changedBlocks: 0,
-        backupWritten: false,
-        written: false,
-      };
-    }
-    const blockingErrors = parsed.diagnostics.filter(
-      (d) =>
-        d.severity === 'error' &&
-        (d.code === undefined || !MIGRATION_TARGET_CODES.has(d.code))
-    );
-    if (blockingErrors.length > 0) {
-      return {
-        path,
-        original,
-        migrated: original,
-        changed: false,
-        skipped: true,
-        skipReason: `block at line ${block.fenceStartLine + 1} failed to parse: ${blockingErrors[0]!.message}`,
-        blockCount: blocks.length,
-        changedBlocks: 0,
-        backupWritten: false,
-        written: false,
-      };
-    }
-  }
-
-  // Migrate each block and rebuild the document.
-  const lines = original.split('\n');
-  const out: string[] = [];
-  let cursor = 0;
-  let changedBlocks = 0;
-  let anyChange = false;
-
-  for (const block of blocks) {
-    for (let k = cursor; k <= block.bodyStart - 1; k++) {
-      out.push(lines[k]!);
-    }
-    const blockResult = migrateContent(block.body);
-    out.push(blockResult.migrated);
-    if (blockResult.changed) {
-      anyChange = true;
-      changedBlocks++;
-    }
-    cursor = block.bodyEnd;
-  }
-  for (let k = cursor; k < lines.length; k++) {
-    out.push(lines[k]!);
-  }
-  const migrated = out.join('\n');
-
-  let backupWritten = false;
-  let written = false;
-  if (anyChange && !dryRun) {
-    if (!opts.noBackup) {
-      const bakPath = `${path}.bak`;
-      if (!existsSync(bakPath)) {
-        writeFileSync(bakPath, original, 'utf-8');
-        backupWritten = true;
-      }
-    }
-    writeFileSync(path, migrated, 'utf-8');
-    written = true;
-  }
-
-  return {
-    path,
-    original,
-    migrated,
-    changed: anyChange,
-    skipped: false,
-    skipReason: null,
-    blockCount: blocks.length,
-    changedBlocks,
-    backupWritten,
-    written,
-  };
-}

package/src/migrate/index.ts

@@ -1,295 +0,0 @@
-// Orchestration for the `dgmo migrate` tool.
-//
-// `migrateContent(source)` is the chart-type-aware whole-document
-// transform: detects chart type from the first non-empty line, walks
-// lines through the classifier + transformer, returns the new source
-// plus a per-line change report. Pure — no I/O.
-//
-// `migrateFile(path, opts)` is the on-disk wrapper: reads, calls
-// `migrateContent`, optionally writes back with `.bak` semantics.
-// `migrateEmbedded(path, opts)` handles markdown / mdx files with
-// fenced ```dgmo blocks (atomic per file — see `embedded.ts`).
-
-import {
-  readFileSync,
-  writeFileSync,
-  existsSync,
-  statSync,
-  readdirSync,
-} from 'node:fs';
-import { join, extname } from 'node:path';
-
-import { parseDgmoChartType } from '../dgmo-router';
-import { isLegacyMetadataLine } from './line-classifier';
-import { transformLine } from './line-transformer';
-import { DATA_COMMA_CHART_TYPES, migrateDataRowCommaLine } from './data-comma';
-
-export interface ContentMigration {
-  /** Updated source — equal to the input when `changed: false`. */
-  readonly migrated: string;
-  /** True iff at least one line changed. */
-  readonly changed: boolean;
-  /** Detected chart type (from line 1), or `null` if unrecognized. */
-  readonly chartType: string | null;
-  /** 1-based line numbers that were rewritten. */
-  readonly changedLines: readonly number[];
-}
-
-/**
- * Whole-document migration. Pure transform: takes legacy source,
- * returns new-grammar source plus a change report. Idempotent —
- * running on already-migrated content produces zero changes.
- */
-export function migrateContent(source: string): ContentMigration {
-  const chartType = parseDgmoChartType(source);
-  const lines = source.split('\n');
-  const out: string[] = [];
-  const changedLines: number[] = [];
-  let changed = false;
-
-  const migrateDataCommas =
-    chartType !== null && DATA_COMMA_CHART_TYPES.has(chartType);
-
-  let firstContentSeen = false;
-  for (let i = 0; i < lines.length; i++) {
-    let line = lines[i]!;
-    const trimmed = line.trim();
-
-    // Data-row comma migration (1.0): rewrite value-separator + thousands
-    // commas to space-separated, byte-preserving everything else. Skip the
-    // chart-type declaration line and blank/comment lines.
-    if (
-      migrateDataCommas &&
-      firstContentSeen &&
-      trimmed &&
-      !trimmed.startsWith('//')
-    ) {
-      const dc = migrateDataRowCommaLine(line);
-      if (dc.changed) {
-        line = dc.line;
-        changed = true;
-        changedLines.push(i + 1);
-      }
-    }
-    if (trimmed && !trimmed.startsWith('//')) firstContentSeen = true;
-
-    if (!isLegacyMetadataLine(line)) {
-      out.push(line);
-      continue;
-    }
-    const result = transformLine(line, chartType);
-    if (result.changed) {
-      changed = true;
-      if (!changedLines.includes(i + 1)) changedLines.push(i + 1);
-    }
-    out.push(result.line);
-  }
-
-  return {
-    migrated: out.join('\n'),
-    changed,
-    chartType,
-    changedLines,
-  };
-}
-
-// ============================================================
-// File-level operations
-// ============================================================
-
-export interface MigrateFileOptions {
-  /** When false, write changes to disk. Default: true (dry-run). */
-  readonly dryRun?: boolean;
-  /** When true and dryRun is false, skip writing the `.bak` sidecar. */
-  readonly noBackup?: boolean;
-}
-
-export interface FileMigrationResult {
-  readonly path: string;
-  /** Original content. */
-  readonly original: string;
-  /** Migrated content (equal to original when `changed: false`). */
-  readonly migrated: string;
-  /** True iff content differs. */
-  readonly changed: boolean;
-  /** Detected chart type. */
-  readonly chartType: string | null;
-  /** 1-based line numbers changed. */
-  readonly changedLines: readonly number[];
-  /** True iff a `.bak` file was written (only when applying). */
-  readonly backupWritten: boolean;
-  /** True iff the migrated content was written to `path`. */
-  readonly written: boolean;
-}
-
-/**
- * Migrate a single `.dgmo` file. Defaults to dry-run — no writes
- * happen unless `dryRun: false` is passed explicitly.
- *
- * On apply: writes the migrated content to `path`. Also writes the
- * original to `<path>.bak` unless `noBackup` is set, and unless a
- * `.bak` already exists (preserves the original `.bak` across re-runs
- * — re-migrating an already-migrated file is a no-op anyway).
- */
-export function migrateFile(
-  path: string,
-  opts: MigrateFileOptions = {}
-): FileMigrationResult {
-  const dryRun = opts.dryRun ?? true;
-  const original = readFileSync(path, 'utf-8');
-  const { migrated, changed, chartType, changedLines } =
-    migrateContent(original);
-
-  let backupWritten = false;
-  let written = false;
-
-  if (changed && !dryRun) {
-    if (!opts.noBackup) {
-      const bakPath = `${path}.bak`;
-      if (!existsSync(bakPath)) {
-        writeFileSync(bakPath, original, 'utf-8');
-        backupWritten = true;
-      }
-    }
-    writeFileSync(path, migrated, 'utf-8');
-    written = true;
-  }
-
-  return {
-    path,
-    original,
-    migrated,
-    changed,
-    chartType,
-    changedLines,
-    backupWritten,
-    written,
-  };
-}
-
-// ============================================================
-// Directory walking
-// ============================================================
-
-const DGMO_EXTENSION = '.dgmo';
-const EMBEDDED_EXTENSIONS = new Set(['.md', '.mdx']);
-
-/**
- * Recursively collect `.dgmo` files under `root`, skipping common
- * noise (`node_modules`, `.git`, `dist`, `.bak` sidecars).
- */
-export function collectDgmoFiles(root: string): string[] {
-  const stat = statSync(root);
-  if (stat.isFile()) {
-    return root.endsWith(DGMO_EXTENSION) ? [root] : [];
-  }
-  const out: string[] = [];
-  walk(root, out, DGMO_EXTENSION);
-  return out;
-}
-
-/**
- * Recursively collect `.md` / `.mdx` files under `root`. Used in
- * `--embedded` mode.
- */
-export function collectEmbeddedFiles(root: string): string[] {
-  const stat = statSync(root);
-  if (stat.isFile()) {
-    return EMBEDDED_EXTENSIONS.has(extname(root)) ? [root] : [];
-  }
-  const out: string[] = [];
-  walkEmbedded(root, out);
-  return out;
-}
-
-function walk(dir: string, out: string[], ext: string): void {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const name = entry.name;
-    if (
-      name === 'node_modules' ||
-      name === '.git' ||
-      name === 'dist' ||
-      name === '.next' ||
-      name.endsWith('.bak')
-    ) {
-      continue;
-    }
-    const full = join(dir, name);
-    if (entry.isDirectory()) {
-      walk(full, out, ext);
-    } else if (entry.isFile() && name.endsWith(ext)) {
-      out.push(full);
-    }
-  }
-}
-
-function walkEmbedded(dir: string, out: string[]): void {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const name = entry.name;
-    if (
-      name === 'node_modules' ||
-      name === '.git' ||
-      name === 'dist' ||
-      name === '.next' ||
-      name.endsWith('.bak')
-    ) {
-      continue;
-    }
-    const full = join(dir, name);
-    if (entry.isDirectory()) {
-      walkEmbedded(full, out);
-    } else if (entry.isFile() && EMBEDDED_EXTENSIONS.has(extname(name))) {
-      out.push(full);
-    }
-  }
-}
-
-// ============================================================
-// Diff helper (used by --diff)
-// ============================================================
-
-/**
- * Minimal unified-style diff for printing changed lines.
- * Not a full unified-diff: only outputs the touched lines with
- * `- old` / `+ new` markers and a leading file header. Adequate
- * for the `--diff` flag on the migration CLI; no patch consumer.
- */
-export function formatLineDiff(
-  path: string,
-  original: string,
-  migrated: string
-): string {
-  const origLines = original.split('\n');
-  const newLines = migrated.split('\n');
-  const lines: string[] = [`--- ${path}`, `+++ ${path}`];
-  const max = Math.max(origLines.length, newLines.length);
-  for (let i = 0; i < max; i++) {
-    const a = origLines[i];
-    const b = newLines[i];
-    if (a === b) continue;
-    if (a !== undefined) lines.push(`@@ line ${i + 1}\n- ${a}`);
-    if (b !== undefined) lines.push(`+ ${b}`);
-  }
-  return lines.join('\n');
-}
-
-// Re-exports so consumers (cli.ts, dgmo-mcp) can import everything
-// they need from this entrypoint.
-export {
-  isLegacyMetadataLine,
-  findUnsafePipePositions,
-} from './line-classifier';
-export { transformLine } from './line-transformer';
-export type { TransformResult } from './line-transformer';

package/src/migrate/line-classifier.ts

@@ -1,128 +0,0 @@
-// Single-line classifier for the `dgmo migrate` tool.
-//
-// `isLegacyMetadataLine(line)` returns true iff `line` contains a `|`
-// in a position that the unified §1.4 grammar treats as the legacy
-// metadata delimiter — i.e. NOT inside one of these surviving regions:
-//
-//   * Wireframe option braces `{A | B}`         (brace-depth tracked)
-//   * Quoted strings `"..."` / `'...'`          (quote-state tracked)
-//   * In-arrow labels `A -text|more-> B`        (§1.10, arrow regions)
-//
-// The classifier is intentionally pure and chart-type agnostic — every
-// chart type whose legacy syntax used `|` for metadata gets the same
-// treatment. Chart-type-specific bare-positional shapes (gantt `| 80%`,
-// journey-map `| 4 Delighted`, pyramid/ring `| description text`) all
-// start with `|` so the classifier flags them; the transformer is
-// where chart-type awareness lives.
-
-/**
- * Returns the byte offsets of every `|` on `line` that is OUTSIDE the
- * surviving non-metadata regions enumerated above. Empty array means
- * "no legacy metadata pipe on this line."
- */
-export function findUnsafePipePositions(line: string): number[] {
-  const positions: number[] = [];
-  let i = 0;
-  let inDouble = false;
-  let inSingle = false;
-  let braceDepth = 0;
-  let inArrow = false;
-  let arrowOpenChar: '-' | '~' | null = null;
-
-  while (i < line.length) {
-    const ch = line[i]!;
-    const ch2 = i + 1 < line.length ? line[i + 1]! : '';
-
-    if (inDouble) {
-      if (ch === '"') inDouble = false;
-      i++;
-      continue;
-    }
-    if (inSingle) {
-      if (ch === "'") inSingle = false;
-      i++;
-      continue;
-    }
-    if (inArrow) {
-      if (
-        (arrowOpenChar === '-' && ch === '-' && ch2 === '>') ||
-        (arrowOpenChar === '~' && ch === '~' && ch2 === '>')
-      ) {
-        inArrow = false;
-        arrowOpenChar = null;
-        i += 2;
-        continue;
-      }
-      i++;
-      continue;
-    }
-
-    if (ch === '"') {
-      inDouble = true;
-      i++;
-      continue;
-    }
-    if (ch === "'") {
-      inSingle = true;
-      i++;
-      continue;
-    }
-    if (ch === '{') {
-      braceDepth++;
-      i++;
-      continue;
-    }
-    if (ch === '}') {
-      if (braceDepth > 0) braceDepth--;
-      i++;
-      continue;
-    }
-
-    // Arrow start: an opening `-` or `~` that is preceded by whitespace
-    // (token boundary) and followed by a non-arrow, non-space char,
-    // with a matching `->` (or `~>`) closer further along the line and
-    // no embedded `->`/`~>` substring inside the candidate label.
-    // Conservative — false negatives leave the `|` flagged as metadata
-    // (worst case: the migration tool tries to migrate the line and
-    // the legacy parser rejects it, which is a surfaced skip, not a
-    // silent corruption).
-    if ((ch === '-' || ch === '~') && i > 0) {
-      const prev = line[i - 1];
-      const onBoundary = prev === ' ' || prev === '\t';
-      const nextIsLabelChar =
-        ch2 !== '' && ch2 !== ch && ch2 !== '>' && ch2 !== ' ' && ch2 !== '\t';
-      if (onBoundary && nextIsLabelChar) {
-        const closer = ch + '>';
-        const closeIdx = line.indexOf(closer, i + 1);
-        if (closeIdx > i) {
-          const labelRegion = line.substring(i + 1, closeIdx);
-          // Spec §1.10: `->` and `~>` substrings are forbidden inside
-          // an arrow label. If they appear, this isn't a well-formed
-          // arrow — bail and treat the `-`/`~` as ordinary text.
-          if (!labelRegion.includes('->') && !labelRegion.includes('~>')) {
-            inArrow = true;
-            arrowOpenChar = ch as '-' | '~';
-            i++;
-            continue;
-          }
-        }
-      }
-    }
-
-    if (ch === '|' && braceDepth === 0) {
-      positions.push(i);
-    }
-
-    i++;
-  }
-
-  return positions;
-}
-
-/**
- * True iff `line` carries at least one legacy metadata `|` (outside
- * the surviving non-metadata regions). Pure, chart-type agnostic.
- */
-export function isLegacyMetadataLine(line: string): boolean {
-  return findUnsafePipePositions(line).length > 0;
-}