docs-coderef 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+# [0.4.0](https://github.com/cawpea/docs-coderef/compare/v0.3.0...v0.4.0) (2026-01-02)
+
+
+### Bug Fixes
+
+* correct diff display for UPDATE_LINE_NUMBERS from CODE_CONTENT_MISMATCH ([1984d23](https://github.com/cawpea/docs-coderef/commit/1984d238e2e176980cfde79fe2dd296ee7a16be6))
+* show actual vs kept code diff for UPDATE_LINE_NUMBERS in CODE_CONTENT_MISMATCH ([44c34cb](https://github.com/cawpea/docs-coderef/commit/44c34cb097d3e431eb10d90802e80666680f2d27))
+
+
+### Features
+
+* add color highlighting to CODE_REF preview in fix options ([11e8e84](https://github.com/cawpea/docs-coderef/commit/11e8e848126e3731dd015b84c7bb891ba70b7cc3))
+* add syntax highlighting to code blocks in fix preview ([37bbebe](https://github.com/cawpea/docs-coderef/commit/37bbebe7b9c9bb1ada72874de9fbc22d9139a983))
+* group diff display by change type for better readability ([3f891eb](https://github.com/cawpea/docs-coderef/commit/3f891eb5bf5a460a6eed5cbcdec2b57c80fda835))
+* simplify Option 2 preview to show only CODE_REF change ([294e2e4](https://github.com/cawpea/docs-coderef/commit/294e2e424b00f51caf9aa7580d3f2e7eca0a6ecf))
+* unify error message styling with centralized formatter ([4735c23](https://github.com/cawpea/docs-coderef/commit/4735c2392ae2b57154d0ddfea91c139634f3648a))
+
+# [0.3.0](https://github.com/cawpea/docs-coderef/compare/v0.2.0...v0.3.0) (2026-01-01)
+
+
+### Bug Fixes
+
+* update demo valid docs to pass all validations ([2caab53](https://github.com/cawpea/docs-coderef/commit/2caab535a936d118efff7bedfadbd4a5b8d85c19))
+
+
+### Features
+
+* add demo environment for local CODE_REF testing ([b845f99](https://github.com/cawpea/docs-coderef/commit/b845f997368ef898ad315f3dfdd43506cfdb5679))
+* add demo:reset npm script for quick demo restoration ([3bceb6e](https://github.com/cawpea/docs-coderef/commit/3bceb6e00b72421c193495f506a6a1428123978a))
+
 # [0.2.0](https://github.com/cawpea/docs-coderef/compare/v0.1.0...v0.2.0) (2026-01-01)
 
 

package/README.md

@@ -159,6 +159,33 @@ This references lines 15-35 of the file. If the code changes, `coderef` will det
 
 For more examples and usage patterns, see [docs/user-guide/](docs/user-guide/).
 
+## Demo Environment
+
+Try out `docs-coderef` with the included demo environment:
+
+```bash
+# Clone the repository
+git clone https://github.com/cawpea/docs-coderef.git
+cd docs-coderef
+
+# Install dependencies and build
+npm install
+npm run build
+
+# Try the demo
+npm run demo:validate:valid    # See valid CODE_REF examples
+npm run demo:validate:invalid  # See error detection
+npm run demo:fix:dry           # Preview auto-fix
+```
+
+The `demo/` directory includes:
+
+- Sample TypeScript files with various code patterns
+- Documentation with valid and invalid CODE_REF examples
+- Scripts for testing validation and fixing
+
+See [demo/README.md](demo/README.md) for detailed instructions.
+
 ## Configuration
 
 Create `.docs-coderefrc.json` in your project root:

package/dist/chunk-U3LM2QL7.mjs

@@ -0,0 +1,268 @@
+// src/utils/message-formatter.ts
+import chalk from "chalk";
+var COLOR_SCHEMES = {
+  error: chalk.redBright,
+  warning: chalk.yellow,
+  info: chalk.cyan,
+  success: chalk.green,
+  debug: chalk.gray,
+  neutral: chalk.white,
+  // Accent colors
+  highlight: chalk.cyan.bold,
+  dim: chalk.dim,
+  code: chalk.yellow
+};
+var EMOJIS = {
+  error: "\u274C",
+  warning: "\u26A0\uFE0F",
+  success: "\u2705",
+  info: "\u2139\uFE0F",
+  search: "\u{1F50D}",
+  fix: "\u{1F527}",
+  file: "\u{1F4C4}",
+  stats: "\u{1F4CA}",
+  backup: "\u{1F4BE}",
+  skip: "\u23ED\uFE0F"
+};
+var MessageFormatter = class {
+  /**
+   * Set verbose mode
+   * @param enabled Whether verbose mode is enabled
+   */
+  static setVerbose(enabled) {
+    this.verboseMode = enabled;
+  }
+  /**
+   * Format error message
+   * @param text Error message text
+   * @returns Formatted error message with emoji and color
+   */
+  static error(text) {
+    return `${COLOR_SCHEMES.error(`${EMOJIS.error} ${text}`)}`;
+  }
+  /**
+   * Format warning message
+   * @param text Warning message text
+   * @returns Formatted warning message with emoji and color
+   */
+  static warning(text) {
+    return `${COLOR_SCHEMES.warning(`${EMOJIS.warning} ${text}`)}`;
+  }
+  /**
+   * Format info message
+   * @param text Info message text
+   * @returns Formatted info message with emoji and color
+   */
+  static info(text) {
+    return `${COLOR_SCHEMES.info(`${EMOJIS.info} ${text}`)}`;
+  }
+  /**
+   * Format success message
+   * @param text Success message text
+   * @returns Formatted success message with emoji and color
+   */
+  static success(text) {
+    return `${COLOR_SCHEMES.success(`${EMOJIS.success} ${text}`)}`;
+  }
+  /**
+   * Format debug message (only shown in verbose mode)
+   * @param text Debug message text
+   * @returns Formatted debug message if verbose mode is enabled, empty string otherwise
+   */
+  static debug(text) {
+    if (!this.verboseMode) {
+      return "";
+    }
+    return COLOR_SCHEMES.debug(text);
+  }
+  /**
+   * Format neutral message (no emoji, white color)
+   * @param text Neutral message text
+   * @returns Formatted neutral message
+   */
+  static neutral(text) {
+    return COLOR_SCHEMES.neutral(text);
+  }
+  /**
+   * Format error detail with type, message, and optional location
+   * @param type Error type (e.g., 'CODE_CONTENT_MISMATCH')
+   * @param message Error message
+   * @param location Optional file location
+   * @returns Formatted error detail
+   */
+  static errorDetail(type, message, location) {
+    const lines = [];
+    lines.push(this.error(`${type}: ${message}`));
+    if (location) {
+      lines.push(`   ${COLOR_SCHEMES.dim(`Reference: ${location}`)}`);
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Format summary section
+   * @param successful Number of successful operations
+   * @param failed Number of failed operations
+   * @param backupPaths Array of backup file paths
+   * @returns Formatted summary section
+   */
+  static summary(successful, failed, backupPaths) {
+    const lines = [];
+    const separator = COLOR_SCHEMES.dim("\u2501".repeat(60));
+    lines.push("");
+    lines.push(separator);
+    lines.push(`${EMOJIS.stats} Fix Results Summary`);
+    lines.push("");
+    lines.push(COLOR_SCHEMES.success(`${EMOJIS.success} Successful: ${successful}`));
+    lines.push(COLOR_SCHEMES.error(`${EMOJIS.error} Failed: ${failed}`));
+    if (backupPaths.length > 0) {
+      lines.push("");
+      lines.push(`${EMOJIS.backup} Backup files: ${backupPaths.length}`);
+      backupPaths.forEach((path) => {
+        lines.push(`   ${COLOR_SCHEMES.dim(path)}`);
+      });
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Format start message for fix operation
+   * @param text Start message text
+   * @returns Formatted start message with fix emoji
+   */
+  static startFix(text) {
+    return `${COLOR_SCHEMES.info(`${EMOJIS.fix} ${text}`)}`;
+  }
+  /**
+   * Format start message for validation operation
+   * @param text Start message text
+   * @returns Formatted start message with search emoji
+   */
+  static startValidation(text) {
+    return `${COLOR_SCHEMES.info(`${EMOJIS.search} ${text}`)}`;
+  }
+  /**
+   * Format file reference
+   * @param text File path or reference
+   * @returns Formatted file reference with emoji
+   */
+  static file(text) {
+    return `${EMOJIS.file} ${COLOR_SCHEMES.neutral(text)}`;
+  }
+  /**
+   * Format backup notification
+   * @param text Backup message text
+   * @returns Formatted backup message with emoji
+   */
+  static backup(text) {
+    return `${COLOR_SCHEMES.info(`${EMOJIS.backup} ${text}`)}`;
+  }
+  /**
+   * Format skip notification
+   * @param text Skip message text
+   * @returns Formatted skip message with emoji
+   */
+  static skip(text) {
+    return `${COLOR_SCHEMES.neutral(`${EMOJIS.skip} ${text}`)}`;
+  }
+  /**
+   * Format context line (indented with dim color)
+   * @param text Context text
+   * @returns Formatted context line with 3 spaces indentation
+   */
+  static context(text) {
+    return `   ${COLOR_SCHEMES.dim(text)}`;
+  }
+};
+MessageFormatter.verboseMode = false;
+var msg = {
+  error: (text) => MessageFormatter.error(text),
+  warning: (text) => MessageFormatter.warning(text),
+  info: (text) => MessageFormatter.info(text),
+  success: (text) => MessageFormatter.success(text),
+  debug: (text) => MessageFormatter.debug(text),
+  neutral: (text) => MessageFormatter.neutral(text),
+  errorDetail: (type, message, location) => MessageFormatter.errorDetail(type, message, location),
+  summary: (successful, failed, backupPaths) => MessageFormatter.summary(successful, failed, backupPaths),
+  startFix: (text) => MessageFormatter.startFix(text),
+  startValidation: (text) => MessageFormatter.startValidation(text),
+  file: (text) => MessageFormatter.file(text),
+  backup: (text) => MessageFormatter.backup(text),
+  skip: (text) => MessageFormatter.skip(text),
+  context: (text) => MessageFormatter.context(text),
+  setVerbose: (enabled) => MessageFormatter.setVerbose(enabled)
+};
+
+// src/utils/diff-display.ts
+function displayCodeDiff(expected, actual) {
+  const expectedLines = expected.split("\n");
+  const actualLines = actual.split("\n");
+  const output = [];
+  const maxLines = Math.max(expectedLines.length, actualLines.length);
+  output.push(COLOR_SCHEMES.dim("\u2501".repeat(64)));
+  output.push(COLOR_SCHEMES.error("- Expected code (in document)"));
+  output.push(COLOR_SCHEMES.success("+ Actual code (in file)"));
+  output.push(COLOR_SCHEMES.dim("\u2501".repeat(64)));
+  const removedLines = [];
+  const addedLines = [];
+  const flushChanges = () => {
+    removedLines.forEach((line) => {
+      output.push(COLOR_SCHEMES.error(`- ${line}`));
+    });
+    addedLines.forEach((line) => {
+      output.push(COLOR_SCHEMES.success(`+ ${line}`));
+    });
+    removedLines.length = 0;
+    addedLines.length = 0;
+  };
+  for (let i = 0; i < maxLines; i++) {
+    const expectedLine = expectedLines[i];
+    const actualLine = actualLines[i];
+    if (expectedLine === actualLine) {
+      if (removedLines.length > 0 || addedLines.length > 0) {
+        flushChanges();
+      }
+      if (expectedLine !== void 0) {
+        output.push(`  ${expectedLine}`);
+      }
+    } else {
+      if (expectedLine !== void 0) {
+        removedLines.push(expectedLine);
+      }
+      if (actualLine !== void 0) {
+        addedLines.push(actualLine);
+      }
+    }
+  }
+  if (removedLines.length > 0 || addedLines.length > 0) {
+    flushChanges();
+  }
+  output.push(COLOR_SCHEMES.dim("\u2501".repeat(64)));
+  return output.join("\n");
+}
+function displayLineRangeDiff(code, expectedRange, actualRange) {
+  const output = [];
+  output.push(COLOR_SCHEMES.dim("\u2501".repeat(64)));
+  output.push(
+    COLOR_SCHEMES.error(`- Expected line range: ${expectedRange.start}-${expectedRange.end}`)
+  );
+  output.push(
+    COLOR_SCHEMES.success(`+ Actual line range: ${actualRange.start}-${actualRange.end}`)
+  );
+  output.push(COLOR_SCHEMES.dim("\u2501".repeat(64)));
+  const codeLines = code.split("\n");
+  codeLines.forEach((line, index) => {
+    const expectedLineNum = expectedRange.start + index;
+    const actualLineNum = actualRange.start + index;
+    output.push(
+      `${COLOR_SCHEMES.error(expectedLineNum.toString().padStart(4))} | ${COLOR_SCHEMES.success(actualLineNum.toString().padStart(4))} | ${line}`
+    );
+  });
+  output.push(COLOR_SCHEMES.dim("\u2501".repeat(64)));
+  return output.join("\n");
+}
+
+export {
+  COLOR_SCHEMES,
+  msg,
+  displayCodeDiff,
+  displayLineRangeDiff
+};