@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/identifier-collector.js

@@ -0,0 +1,439 @@
+/**
+ * Shared utility for collecting identifiers from IR nodes.
+ * This consolidates duplicate logic that was previously in:
+ * - transpile.ts (collectExpressionIdentifiers, collectStatementIdentifiers)
+ * - call-graph.ts (collectExpressionIdentifiers, collectStatementIdentifiers)
+ * - build-ir.ts (similar traversal logic)
+ */
+/**
+ * Collect all identifiers from an expression IR node.
+ * Returns a Set of identifier names found.
+ */
+export function collectExpressionIdentifiers(expr) {
+    const identifiers = new Set();
+    // Safety check
+    if (!expr || typeof expr !== "object" || !expr.kind) {
+        return identifiers;
+    }
+    switch (expr.kind) {
+        case "identifier":
+            identifiers.add(expr.value);
+            break;
+        case "raw": {
+            // Extract identifiers from raw expressions
+            const matches = expr.value.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+            if (matches) {
+                for (const match of matches) {
+                    identifiers.add(match);
+                }
+            }
+            break;
+        }
+        case "await":
+            for (const id of collectExpressionIdentifiers(expr.value)) {
+                identifiers.add(id);
+            }
+            break;
+        case "ternary":
+            for (const id of collectExpressionIdentifiers(expr.condition)) {
+                identifiers.add(id);
+            }
+            for (const id of collectExpressionIdentifiers(expr.whenTrue)) {
+                identifiers.add(id);
+            }
+            for (const id of collectExpressionIdentifiers(expr.whenFalse)) {
+                identifiers.add(id);
+            }
+            break;
+        case "array":
+            for (const element of expr.elements) {
+                for (const id of collectExpressionIdentifiers(element)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "object":
+            for (const field of expr.fields) {
+                for (const id of collectExpressionIdentifiers(field.value)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "instanceof":
+            for (const id of collectExpressionIdentifiers(expr.object)) {
+                identifiers.add(id);
+            }
+            identifiers.add(expr.className);
+            break;
+        case "spread_array":
+            for (const id of collectExpressionIdentifiers(expr.spreadExpr)) {
+                identifiers.add(id);
+            }
+            for (const element of expr.additionalElements) {
+                for (const id of collectExpressionIdentifiers(element)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "binary":
+            for (const id of collectExpressionIdentifiers(expr.left)) {
+                identifiers.add(id);
+            }
+            for (const id of collectExpressionIdentifiers(expr.right)) {
+                identifiers.add(id);
+            }
+            break;
+        case "unary":
+            for (const id of collectExpressionIdentifiers(expr.operand)) {
+                identifiers.add(id);
+            }
+            break;
+        case "property-access":
+            for (const id of collectExpressionIdentifiers(expr.object)) {
+                identifiers.add(id);
+            }
+            break;
+        case "element-access":
+            for (const id of collectExpressionIdentifiers(expr.object)) {
+                identifiers.add(id);
+            }
+            for (const id of collectExpressionIdentifiers(expr.index)) {
+                identifiers.add(id);
+            }
+            break;
+        case "template_string":
+            for (const id of collectExpressionIdentifiers(expr.expression)) {
+                identifiers.add(id);
+            }
+            break;
+        case "string_concat":
+            for (const part of expr.parts) {
+                for (const id of collectExpressionIdentifiers(part)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "callback":
+            // Callbacks have nested statements
+            for (const stmt of expr.statements) {
+                for (const id of collectStatementIdentifiers(stmt)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "method-call": {
+            const calleeParts = expr.callee.split(/->|::|\./);
+            for (const part of calleeParts) {
+                if (part.length > 0) {
+                    identifiers.add(part);
+                }
+            }
+            for (const arg of expr.args) {
+                for (const id of collectExpressionIdentifiers(arg)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        }
+        // Parenthesized expression — recurse into the inner expression. The `paren`
+        // IR node exists to preserve explicit TS grouping (e.g. `(a + b) * c`), and
+        // any free-function call nested inside parens (such as `!fn(x)` inside an
+        // `(cond && !fn(x))` clause) MUST be visible to the call-graph/reachability
+        // pass, or the function is tree-shaken and g++ reports "not declared in
+        // this scope". Demo #22 Finding B — the root cause was the absence of this
+        // case, not a forward-declaration or return-type gap.
+        case "paren":
+            for (const id of collectExpressionIdentifiers(expr.inner)) {
+                identifiers.add(id);
+            }
+            break;
+        // Tuple element access `std::get<N>(object)` — the object may reference a
+        // reachable symbol.
+        case "tuple-access":
+            for (const id of collectExpressionIdentifiers(expr.object)) {
+                identifiers.add(id);
+            }
+            break;
+        // Arrow/lambda expression used as a value — walk its body for captured
+        // identifiers (the call graph must see free functions/vars a lambda uses).
+        case "lambda":
+            for (const param of expr.params) {
+                identifiers.add(param.name);
+            }
+            for (const stmt of expr.body) {
+                for (const id of collectStatementIdentifiers(stmt)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        // HAL operation used as an expression — delegate to the HAL identifier
+        // collector (same logic as the hal-op statement case).
+        case "hal-expr":
+            for (const id of collectHALOpIdentifiers(expr.operation)) {
+                identifiers.add(id);
+            }
+            break;
+        // number, string, boolean have no identifiers
+    }
+    return identifiers;
+}
+/**
+ * Collect all identifiers from a statement IR node.
+ * Returns a Set of identifier names found.
+ */
+export function collectStatementIdentifiers(statement) {
+    const identifiers = new Set();
+    // Safety check
+    if (!statement || typeof statement !== "object" || !statement.kind) {
+        return identifiers;
+    }
+    switch (statement.kind) {
+        case "call":
+            // Extract function/method name from callee
+            const calleeParts = statement.callee.split(/->|::|[.(]/);
+            identifiers.add(calleeParts[0]);
+            // Add EVERY callee part, not just the first. A `call` statement's callee
+            // can be a lowered raw wrapper (`__RAW_STMT__out.push_back(glyphFor(op))`,
+            // produced by ir/transformers/call-statement.ts when an outer call wraps
+            // an inner free-function call). Only adding `calleeParts[0]` left the
+            // inner callee (`glyphFor`) invisible to the call graph, so a free
+            // function called only as a nested argument was tree-shaken and g++
+            // reported it "not declared in this scope". Demo #28 Finding C.
+            for (const part of calleeParts) {
+                if (part.length > 0) {
+                    identifiers.add(part);
+                }
+            }
+            // Also add the full callee (e.g. "Serial.begin") for polyfill detection
+            identifiers.add(statement.callee);
+            // Demo #31 Finding A — a `__RAW_STMT__` callee carries a fully-formed
+            // C++ expression in its raw text (e.g. `parts.push_back(ONES_TEENS[i])`
+            // or `__tc_pop(map[k])`), and the split on `/->|::|[.(]/` does NOT fully
+            // tokenize it: it stops splitting once it hits `]` or `)`, so an indexed
+            // identifier like `ONES_TEENS` survives glued to its suffix
+            // (`"ONES_TEENS[i])"`) and is never added. The result: a top-level
+            // variable referenced ONLY through `arr.push(globalArr[i])` from a class
+            // method is tree-shaken, then g++ reports it "not declared in this
+            // scope" from the inline method body. Same blind-spot family as demo
+            // #22 B / demo #28 C, but in a DIFFERENT shape: those missed a free
+            // FUNCTION buried in raw/paren text; this misses a free VARIABLE buried
+            // in raw text behind an index. Fix: when the callee is a raw wrapper,
+            // scan its raw text with the SAME identifier regex the `raw` expression
+            // case uses (`case "raw"` above), so EVERY identifier in the embedded
+            // expression is collected regardless of bracket/paren structure.
+            if (statement.callee.startsWith("__RAW_STMT__")) {
+                const matches = statement.callee.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+                if (matches) {
+                    for (const match of matches) {
+                        identifiers.add(match);
+                    }
+                }
+            }
+            for (const arg of statement.args) {
+                // Special case: if this is an __EMIT__ call, scan string literals for identifiers
+                if (statement.callee === "__EMIT__" && arg.kind === "string") {
+                    const matches = arg.value.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+                    if (matches) {
+                        for (const match of matches) {
+                            identifiers.add(match);
+                        }
+                    }
+                }
+                for (const id of collectExpressionIdentifiers(arg)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "var_decl":
+            identifiers.add(statement.name);
+            if (statement.initializer) {
+                for (const id of collectExpressionIdentifiers(statement.initializer)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "assign":
+            identifiers.add(statement.target);
+            for (const id of collectExpressionIdentifiers(statement.value)) {
+                identifiers.add(id);
+            }
+            break;
+        case "update":
+            identifiers.add(statement.target);
+            break;
+        case "return":
+            if (statement.value) {
+                for (const id of collectExpressionIdentifiers(statement.value)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "while":
+        case "do_while":
+            for (const id of collectExpressionIdentifiers(statement.condition)) {
+                identifiers.add(id);
+            }
+            for (const nested of statement.body) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "if":
+            for (const id of collectExpressionIdentifiers(statement.condition)) {
+                identifiers.add(id);
+            }
+            for (const nested of statement.thenBranch) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            for (const nested of statement.elseBranch ?? []) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "for":
+            if (statement.initializer) {
+                for (const id of collectStatementIdentifiers(statement.initializer)) {
+                    identifiers.add(id);
+                }
+            }
+            if (statement.condition) {
+                for (const id of collectExpressionIdentifiers(statement.condition)) {
+                    identifiers.add(id);
+                }
+            }
+            if (statement.increment) {
+                for (const id of collectStatementIdentifiers(statement.increment)) {
+                    identifiers.add(id);
+                }
+            }
+            for (const nested of statement.body) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "for_of":
+            for (const id of collectStatementIdentifiers(statement.variable)) {
+                identifiers.add(id);
+            }
+            for (const id of collectExpressionIdentifiers(statement.iterable)) {
+                identifiers.add(id);
+            }
+            for (const nested of statement.body) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "for_in":
+            for (const id of collectStatementIdentifiers(statement.variable)) {
+                identifiers.add(id);
+            }
+            for (const id of collectExpressionIdentifiers(statement.object)) {
+                identifiers.add(id);
+            }
+            for (const nested of statement.body) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "switch":
+            for (const id of collectExpressionIdentifiers(statement.expression)) {
+                identifiers.add(id);
+            }
+            for (const caseClause of statement.cases) {
+                if (caseClause.value) {
+                    for (const id of collectExpressionIdentifiers(caseClause.value)) {
+                        identifiers.add(id);
+                    }
+                }
+                for (const nested of caseClause.body) {
+                    for (const id of collectStatementIdentifiers(nested)) {
+                        identifiers.add(id);
+                    }
+                }
+            }
+            break;
+        case "try":
+            if (statement.catchParam) {
+                identifiers.add(statement.catchParam);
+            }
+            for (const nested of statement.tryBlock) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            for (const nested of statement.catchBlock ?? []) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            if (statement.finallyBlock) {
+                for (const nested of statement.finallyBlock) {
+                    for (const id of collectStatementIdentifiers(nested)) {
+                        identifiers.add(id);
+                    }
+                }
+            }
+            break;
+        case "throw":
+            for (const id of collectExpressionIdentifiers(statement.value)) {
+                identifiers.add(id);
+            }
+            break;
+        case "labeled":
+            identifiers.add(statement.label);
+            for (const nested of statement.body) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        case "block":
+            for (const nested of statement.body) {
+                for (const id of collectStatementIdentifiers(nested)) {
+                    identifiers.add(id);
+                }
+            }
+            break;
+        // break, continue have no identifiers
+        case "hal-op":
+            for (const id of collectHALOpIdentifiers(statement.operation)) {
+                identifiers.add(id);
+            }
+            break;
+        // break, continue have no identifiers
+    }
+    return identifiers;
+}
+/**
+ * Extract identifier names from a HAL operation's string fields.
+ * This ensures the call graph tracks function references embedded in
+ * semantic HAL ops (e.g. the handler name in interrupt.attach).
+ */
+function collectHALOpIdentifiers(op) {
+    const identifiers = new Set();
+    switch (op.operation) {
+        case "interrupt.attach":
+            // handler is a resolved C++ function name (e.g. "myIsr" or a placeholder)
+            identifiers.add(op.handler);
+            break;
+        case "raw": {
+            // Raw C++ code may reference user-defined identifiers
+            const matches = op.code.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+            if (matches) {
+                for (const match of matches) {
+                    identifiers.add(match);
+                }
+            }
+            break;
+        }
+        // Other HAL ops have only numeric/literal fields — no identifier references
+    }
+    return identifiers;
+}

package/dist/ir/interrupt-analysis.d.ts

@@ -0,0 +1,39 @@
+import type { ProgramIR } from '../api/index.js';
+import type { PeripheralUsage } from './peripheral-usage.js';
+import type { Diagnostic } from '../types.js';
+export { walkNestedStatements as scanNestedStatements } from './utils/walk-ir.js';
+/** ISR-unsafe operation entry. */
+export interface IsrUnsafeOp {
+    reason: string;
+    severity: 'warning' | 'info';
+}
+/**
+ * Track interrupt handlers attached to pins.
+ * Maps pin name to the number of handlers attached.
+ */
+export interface InterruptHandlerInfo {
+    pinName: string;
+    attachCount: number;
+}
+/**
+ * Analyze a program for interrupt handler issues.
+ *
+ * @param program - The program IR to analyze
+ * @param usage - Peripheral usage information
+ * @param isrUnsafeOps - Platform-specific ISR-unsafe operations map (from strategy)
+ * @returns Array of diagnostics for interrupt-related issues
+ */
+export declare function analyzeInterruptSafety(program: ProgramIR, usage: PeripheralUsage, isrUnsafeOps?: Map<string, IsrUnsafeOp>): Diagnostic[];
+/**
+ * Infer `volatile` for global variables shared between ISR callbacks and main
+ * code. Mutates the IR (sets isVolatile=true on qualifying var_decls) and
+ * emits an info diagnostic for each promotion. A variable qualifies when it is
+ * a global (top-level) that is assigned inside an isInterruptHandler callback
+ * AND read from non-ISR code (setup/loop/main/functions).
+ */
+export declare function inferVolatileForIsrSharedVars(program: ProgramIR, diagnostics: Diagnostic[]): void;
+/**
+ * Detect functions called from both ISR callbacks and main-thread code.
+ * Emits a warning for each reentrancy-risk function.
+ */
+export declare function detectReentrancyRisk(program: ProgramIR, diagnostics: Diagnostic[]): void;