c-next 0.1.0

package/src/codegen/CommentExtractor.ts

@@ -0,0 +1,240 @@
+import { CommonTokenStream, Token } from "antlr4ng";
+import { CNextLexer } from "../parser/grammar/CNextLexer";
+import ECommentType from "./types/ECommentType";
+import IComment from "./types/IComment";
+import ICommentError from "./types/ICommentError";
+
+/**
+ * Extracts and validates comments from the HIDDEN channel (ADR-043)
+ *
+ * - Extracts LINE_COMMENT, BLOCK_COMMENT, DOC_COMMENT tokens
+ * - Validates MISRA C:2012 Rule 3.1 (no nested comment markers)
+ * - Validates MISRA C:2012 Rule 3.2 (no line-splice in line comments)
+ */
+class CommentExtractor {
+  private tokenStream: CommonTokenStream;
+
+  private comments: IComment[] | null = null;
+
+  private errors: ICommentError[] = [];
+
+  constructor(tokenStream: CommonTokenStream) {
+    this.tokenStream = tokenStream;
+  }
+
+  /**
+   * Extract all comments from the token stream
+   */
+  extractAll(): IComment[] {
+    if (this.comments !== null) {
+      return this.comments;
+    }
+
+    this.tokenStream.fill();
+    this.comments = [];
+
+    // Get all tokens and filter for comments on HIDDEN channel
+    const size = this.tokenStream.size;
+    for (let i = 0; i < size; i++) {
+      const token = this.tokenStream.get(i);
+      if (token.channel === Token.HIDDEN_CHANNEL) {
+        const comment = this.tokenToComment(token);
+        if (comment) {
+          this.comments.push(comment);
+        }
+      }
+    }
+
+    return this.comments;
+  }
+
+  /**
+   * Get comments that appear before a given token index
+   */
+  getCommentsBefore(tokenIndex: number): IComment[] {
+    const hiddenTokens = this.tokenStream.getHiddenTokensToLeft(
+      tokenIndex,
+      Token.HIDDEN_CHANNEL,
+    );
+    if (!hiddenTokens) return [];
+
+    const comments: IComment[] = [];
+    for (const token of hiddenTokens) {
+      const comment = this.tokenToComment(token);
+      if (comment) {
+        comments.push(comment);
+      }
+    }
+    return comments;
+  }
+
+  /**
+   * Get inline comments that appear after a given token index (same line)
+   */
+  getCommentsAfter(tokenIndex: number): IComment[] {
+    const hiddenTokens = this.tokenStream.getHiddenTokensToRight(
+      tokenIndex,
+      Token.HIDDEN_CHANNEL,
+    );
+    if (!hiddenTokens) return [];
+
+    const comments: IComment[] = [];
+    const sourceToken = this.tokenStream.get(tokenIndex);
+    const sourceLine = sourceToken.line;
+
+    for (const token of hiddenTokens) {
+      // Only include comments on the same line (inline comments)
+      if (token.line !== sourceLine) break;
+
+      const comment = this.tokenToComment(token);
+      if (comment) {
+        comments.push(comment);
+      }
+    }
+    return comments;
+  }
+
+  /**
+   * Validate all comments against MISRA C:2012 Rules 3.1 and 3.2
+   */
+  validate(): ICommentError[] {
+    this.errors = [];
+    const comments = this.extractAll();
+
+    for (const comment of comments) {
+      this.validateMisra31(comment);
+      this.validateMisra32(comment);
+    }
+
+    return this.errors;
+  }
+
+  /**
+   * Get validation errors
+   */
+  getErrors(): ICommentError[] {
+    return this.errors;
+  }
+
+  /**
+   * Convert a token to an IComment, or null if not a comment token
+   */
+  private tokenToComment(token: Token): IComment | null {
+    const text = token.text;
+    if (!text) return null;
+
+    let type: ECommentType;
+    let content: string;
+
+    switch (token.type) {
+      case CNextLexer.DOC_COMMENT:
+        type = ECommentType.Doc;
+        content = text.slice(3).trim(); // Remove ///
+        break;
+      case CNextLexer.LINE_COMMENT:
+        type = ECommentType.Line;
+        content = text.slice(2); // Remove //
+        break;
+      case CNextLexer.BLOCK_COMMENT:
+        type = ECommentType.Block;
+        content = text.slice(2, -2); // Remove /* and */
+        break;
+      default:
+        return null; // Not a comment token (e.g., whitespace)
+    }
+
+    return {
+      type,
+      raw: text,
+      content,
+      line: token.line,
+      column: token.column,
+      tokenIndex: token.tokenIndex,
+    };
+  }
+
+  /**
+   * MISRA C:2012 Rule 3.1: No nested comment markers
+   * The character sequences /* and // shall not appear within a comment.
+   * Exception: :// (URI pattern) is allowed per Amendment 4
+   */
+  private validateMisra31(comment: IComment): void {
+    const content = comment.content;
+
+    // Check for nested /* (not part of a URI)
+    const nestedBlockStart = content.indexOf("/*");
+    if (nestedBlockStart !== -1) {
+      this.errors.push({
+        rule: "3.1",
+        message:
+          "Nested comment marker '/*' found inside comment (MISRA C:2012 Rule 3.1)",
+        line: comment.line,
+        column:
+          comment.column +
+          this.getMarkerLength(comment.type) +
+          nestedBlockStart,
+      });
+    }
+
+    // Check for nested // (not part of a URI like ://)
+    // Find all // occurrences and check if preceded by :
+    let searchStart = 0;
+    while (true) {
+      const slashSlash = content.indexOf("//", searchStart);
+      if (slashSlash === -1) break;
+
+      // Check if this is part of a URI (preceded by :)
+      const isUri = slashSlash > 0 && content[slashSlash - 1] === ":";
+
+      if (!isUri) {
+        this.errors.push({
+          rule: "3.1",
+          message:
+            "Nested comment marker '//' found inside comment (MISRA C:2012 Rule 3.1)",
+          line: comment.line,
+          column:
+            comment.column + this.getMarkerLength(comment.type) + slashSlash,
+        });
+        break; // Only report first occurrence
+      }
+
+      searchStart = slashSlash + 2;
+    }
+  }
+
+  /**
+   * MISRA C:2012 Rule 3.2: No line-splice in line comments
+   * Line comments ending with \ cause undefined behavior
+   */
+  private validateMisra32(comment: IComment): void {
+    // Only applies to line comments (// and ///)
+    if (comment.type === ECommentType.Block) return;
+
+    const content = comment.content;
+    if (content.endsWith("\\")) {
+      this.errors.push({
+        rule: "3.2",
+        message:
+          "Line comment ends with '\\' which causes line-splice (MISRA C:2012 Rule 3.2)",
+        line: comment.line,
+        column: comment.column,
+      });
+    }
+  }
+
+  /**
+   * Get the length of the comment marker for column calculation
+   */
+  private getMarkerLength(type: ECommentType): number {
+    switch (type) {
+      case ECommentType.Doc:
+        return 3; // ///
+      case ECommentType.Line:
+        return 2; // //
+      case ECommentType.Block:
+        return 2; // /*
+    }
+  }
+}
+
+export default CommentExtractor;

package/src/codegen/CommentFormatter.ts

@@ -0,0 +1,155 @@
+import ECommentType from "./types/ECommentType";
+import IComment from "./types/IComment";
+
+/**
+ * Formats comments for C output (ADR-043)
+ *
+ * - Line comments: Keep as // (C99+ mode)
+ * - Block comments: Keep as block comments
+ * - Doc comments: Convert /// to Doxygen format
+ */
+class CommentFormatter {
+  /**
+   * Format a single comment for C output
+   * @param comment The comment to format
+   * @param indent Indentation string (spaces)
+   * @returns Formatted comment string
+   */
+  format(comment: IComment, indent: string = ""): string {
+    switch (comment.type) {
+      case ECommentType.Line:
+        return `${indent}//${comment.content}`;
+
+      case ECommentType.Block:
+        return this.formatBlockComment(comment, indent);
+
+      case ECommentType.Doc:
+        return this.formatDocComment(comment, indent);
+    }
+  }
+
+  /**
+   * Format consecutive doc comments as a single Doxygen block
+   * @param comments Array of consecutive doc comments
+   * @param indent Indentation string
+   * @returns Formatted Doxygen comment block
+   */
+  formatDocCommentGroup(comments: IComment[], indent: string = ""): string {
+    if (comments.length === 0) return "";
+
+    if (comments.length === 1) {
+      return this.formatDocComment(comments[0], indent);
+    }
+
+    // Multiple doc comments -> single /** ... */ block
+    const lines: string[] = [];
+    lines.push(`${indent}/**`);
+
+    for (const comment of comments) {
+      const content = comment.content.trim();
+      if (content) {
+        lines.push(`${indent} * ${content}`);
+      } else {
+        lines.push(`${indent} *`);
+      }
+    }
+
+    lines.push(`${indent} */`);
+    return lines.join("\n");
+  }
+
+  /**
+   * Format leading comments (comments that appear before code)
+   * Groups consecutive doc comments into Doxygen blocks
+   * @param comments Array of comments
+   * @param indent Indentation string
+   * @returns Array of formatted comment strings
+   */
+  formatLeadingComments(comments: IComment[], indent: string = ""): string[] {
+    if (comments.length === 0) return [];
+
+    const result: string[] = [];
+    let docGroup: IComment[] = [];
+
+    for (const comment of comments) {
+      if (comment.type === ECommentType.Doc) {
+        docGroup.push(comment);
+      } else {
+        // Flush any accumulated doc comments
+        if (docGroup.length > 0) {
+          result.push(this.formatDocCommentGroup(docGroup, indent));
+          docGroup = [];
+        }
+        result.push(this.format(comment, indent));
+      }
+    }
+
+    // Flush remaining doc comments
+    if (docGroup.length > 0) {
+      result.push(this.formatDocCommentGroup(docGroup, indent));
+    }
+
+    return result;
+  }
+
+  /**
+   * Format a trailing/inline comment
+   * @param comment The comment
+   * @returns Formatted inline comment (with leading spaces)
+   */
+  formatTrailingComment(comment: IComment): string {
+    switch (comment.type) {
+      case ECommentType.Line:
+      case ECommentType.Doc:
+        return `  //${comment.content}`;
+
+      case ECommentType.Block:
+        // For inline block comments, keep on single line if possible
+        if (!comment.content.includes("\n")) {
+          return `  /*${comment.content}*/`;
+        }
+        // Multi-line block comment shouldn't be inline
+        return `  /*${comment.content}*/`;
+    }
+  }
+
+  /**
+   * Format a block comment preserving internal structure
+   */
+  private formatBlockComment(comment: IComment, indent: string): string {
+    const content = comment.content;
+
+    // Single-line block comment
+    if (!content.includes("\n")) {
+      return `${indent}/*${content}*/`;
+    }
+
+    // Multi-line block comment - preserve structure
+    const lines = content.split("\n");
+    const result: string[] = [];
+    result.push(`${indent}/*${lines[0]}`);
+
+    for (let i = 1; i < lines.length - 1; i++) {
+      result.push(`${indent}${lines[i]}`);
+    }
+
+    if (lines.length > 1) {
+      result.push(`${indent}${lines[lines.length - 1]}*/`);
+    }
+
+    return result.join("\n");
+  }
+
+  /**
+   * Format a single doc comment as Doxygen
+   */
+  private formatDocComment(comment: IComment, indent: string): string {
+    const content = comment.content.trim();
+    if (!content) {
+      return `${indent}/** */`;
+    }
+    return `${indent}/** ${content} */`;
+  }
+}
+
+export default CommentFormatter;

package/src/codegen/HeaderGenerator.ts

@@ -0,0 +1,265 @@
+/**
+ * Header Generator
+ * Generates C header (.h) files from C-Next source
+ */
+
+import ISymbol from "../types/ISymbol";
+import ESymbolKind from "../types/ESymbolKind";
+import ESourceLanguage from "../types/ESourceLanguage";
+import SymbolTable from "../symbols/SymbolTable";
+
+/**
+ * Maps C-Next types to C types
+ */
+const TYPE_MAP: Record<string, string> = {
+  u8: "uint8_t",
+  u16: "uint16_t",
+  u32: "uint32_t",
+  u64: "uint64_t",
+  i8: "int8_t",
+  i16: "int16_t",
+  i32: "int32_t",
+  i64: "int64_t",
+  f32: "float",
+  f64: "double",
+  bool: "bool",
+  void: "void",
+  ISR: "ISR", // ADR-040: Interrupt Service Routine function pointer
+};
+
+/**
+ * Options for header generation
+ */
+interface IHeaderOptions {
+  /** Guard prefix (default: derived from filename) */
+  guardPrefix?: string;
+
+  /** Include system headers in the output */
+  includeSystemHeaders?: boolean;
+
+  /** Only generate declarations for exported symbols */
+  exportedOnly?: boolean;
+}
+
+/**
+ * Generates C header files from symbol information
+ */
+class HeaderGenerator {
+  /**
+   * Generate a header file from symbols
+   */
+  generate(
+    symbols: ISymbol[],
+    filename: string,
+    options: IHeaderOptions = {},
+  ): string {
+    const lines: string[] = [];
+    const guard = this.makeGuard(filename, options.guardPrefix);
+
+    // Header guard
+    lines.push(`#ifndef ${guard}`);
+    lines.push(`#define ${guard}`);
+    lines.push("");
+
+    // Header comment
+    lines.push("/**");
+    lines.push(" * Generated by C-Next Transpiler");
+    lines.push(" * Header file for cross-language interoperability");
+    lines.push(" */");
+    lines.push("");
+
+    // System includes
+    if (options.includeSystemHeaders !== false) {
+      lines.push("#include <stdint.h>");
+      lines.push("#include <stdbool.h>");
+      lines.push("");
+    }
+
+    // C++ compatibility
+    lines.push("#ifdef __cplusplus");
+    lines.push('extern "C" {');
+    lines.push("#endif");
+    lines.push("");
+
+    // Filter symbols
+    const exportedSymbols = options.exportedOnly
+      ? symbols.filter((s) => s.isExported)
+      : symbols;
+
+    // Group symbols by kind
+    const structs = exportedSymbols.filter(
+      (s) => s.kind === ESymbolKind.Struct,
+    );
+    const classes = exportedSymbols.filter((s) => s.kind === ESymbolKind.Class);
+    const functions = exportedSymbols.filter(
+      (s) => s.kind === ESymbolKind.Function,
+    );
+    const variables = exportedSymbols.filter(
+      (s) => s.kind === ESymbolKind.Variable,
+    );
+    const enums = exportedSymbols.filter((s) => s.kind === ESymbolKind.Enum);
+    const types = exportedSymbols.filter((s) => s.kind === ESymbolKind.Type);
+
+    // Forward declarations for structs
+    if (structs.length > 0 || classes.length > 0) {
+      lines.push("/* Forward declarations */");
+      for (const sym of structs) {
+        lines.push(`typedef struct ${sym.name} ${sym.name};`);
+      }
+      for (const sym of classes) {
+        // Classes become typedefs to structs
+        lines.push(`typedef struct ${sym.name} ${sym.name};`);
+      }
+      lines.push("");
+    }
+
+    // Enum declarations
+    if (enums.length > 0) {
+      lines.push("/* Enumerations */");
+      for (const sym of enums) {
+        // For now, just forward declare - full definition would require enum values
+        lines.push(`/* Enum: ${sym.name} (see implementation for values) */`);
+      }
+      lines.push("");
+    }
+
+    // Type aliases
+    if (types.length > 0) {
+      lines.push("/* Type aliases */");
+      for (const sym of types) {
+        if (sym.type) {
+          const cType = this.mapType(sym.type);
+          lines.push(`typedef ${cType} ${sym.name};`);
+        }
+      }
+      lines.push("");
+    }
+
+    // Extern variable declarations
+    if (variables.length > 0) {
+      lines.push("/* External variables */");
+      for (const sym of variables) {
+        const cType = sym.type ? this.mapType(sym.type) : "int";
+        lines.push(`extern ${cType} ${sym.name};`);
+      }
+      lines.push("");
+    }
+
+    // Function prototypes
+    if (functions.length > 0) {
+      lines.push("/* Function prototypes */");
+      for (const sym of functions) {
+        const proto = this.generateFunctionPrototype(sym);
+        if (proto) {
+          lines.push(proto);
+        }
+      }
+      lines.push("");
+    }
+
+    // C++ compatibility end
+    lines.push("#ifdef __cplusplus");
+    lines.push("}");
+    lines.push("#endif");
+    lines.push("");
+
+    // End header guard
+    lines.push(`#endif /* ${guard} */`);
+    lines.push("");
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Generate header from a symbol table, filtering by source file
+   */
+  generateFromSymbolTable(
+    symbolTable: SymbolTable,
+    sourceFile: string,
+    options: IHeaderOptions = {},
+  ): string {
+    const symbols = symbolTable.getSymbolsByFile(sourceFile);
+    const basename = sourceFile.replace(/\.[^.]+$/, "");
+    const headerName = `${basename}.h`;
+
+    return this.generate(symbols, headerName, options);
+  }
+
+  /**
+   * Generate header for all C-Next symbols in the symbol table
+   */
+  generateCNextHeader(
+    symbolTable: SymbolTable,
+    filename: string,
+    options: IHeaderOptions = {},
+  ): string {
+    const symbols = symbolTable.getSymbolsByLanguage(ESourceLanguage.CNext);
+    return this.generate(symbols, filename, options);
+  }
+
+  /**
+   * Create an include guard macro from filename
+   */
+  private makeGuard(filename: string, prefix?: string): string {
+    // Remove path and extension
+    const base = filename.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, "");
+
+    // Convert to uppercase and replace non-alphanumeric with underscore
+    const sanitized = base.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+
+    if (prefix) {
+      return `${prefix.toUpperCase()}_${sanitized}_H`;
+    }
+
+    return `${sanitized}_H`;
+  }
+
+  /**
+   * Map a C-Next type to C type
+   */
+  private mapType(type: string): string {
+    // Check direct mapping first
+    if (TYPE_MAP[type]) {
+      return TYPE_MAP[type];
+    }
+
+    // Handle pointer types
+    if (type.endsWith("*")) {
+      const baseType = type.slice(0, -1).trim();
+      return `${this.mapType(baseType)}*`;
+    }
+
+    // Handle array types (simplified)
+    const arrayMatch = type.match(/^(\w+)\[(\d*)\]$/);
+    if (arrayMatch) {
+      const baseType = this.mapType(arrayMatch[1]);
+      const size = arrayMatch[2] || "";
+      return `${baseType}[${size}]`;
+    }
+
+    // User-defined types pass through
+    return type;
+  }
+
+  /**
+   * Generate a function prototype from symbol info
+   */
+  private generateFunctionPrototype(sym: ISymbol): string | null {
+    // Use signature if available
+    if (sym.signature) {
+      // Parse signature to extract return type and params
+      // Signature format is typically: "return_type(param1_type, param2_type, ...)"
+      return `${sym.signature};`;
+    }
+
+    // Generate from type info
+    const returnType = sym.type ? this.mapType(sym.type) : "void";
+
+    // For C-Next functions, all non-array parameters become pointers
+    // This is a simplified version - full implementation would need param info
+    return `${returnType} ${sym.name}(void);`;
+  }
+}
+
+export default HeaderGenerator;
+export type { IHeaderOptions };