@typecad/cuttlefish 0.1.0-alpha.1

package/dist/orchestrator/semantic-facts-verifier.js

@@ -0,0 +1,121 @@
+import ts from "typescript";
+import { canonicalize, cppTypeFromCanonicalType, TYPED_ARRAY_NAMES } from "./semantic-facts.js";
+import { makeDiagnostic } from "../ir/ast-node-utils.js";
+/** Names of nodes that are not "expressions" we want to type-check — they're
+ *  type-only or structural and would produce noise. */
+function isSkippableForTyping(node) {
+    // Type-only constructs (isTypeNode covers TypeReference, TypeLiteral, etc.).
+    return (ts.isTypeNode(node) ||
+        ts.isTypeAliasDeclaration(node) ||
+        ts.isInterfaceDeclaration(node) ||
+        ts.isHeritageClause(node) ||
+        ts.isTypeParameterDeclaration(node) ||
+        // Statements themselves aren't typed; their expressions are visited.
+        ts.isStatement(node));
+}
+/** A blank identifier (`_`) used as a deliberate discard isn't a value use. */
+function isVoidOrNeverExpression(node) {
+    return (node.kind === ts.SyntaxKind.VoidExpression ||
+        node.kind === ts.SyntaxKind.DeleteExpression);
+}
+/**
+ * Verify semantic-fact completeness across user files.
+ *
+ * Walks every expression, computes its CanonicalType, and emits a diagnostic
+ * for each one that resolves to "unknown" (at the configured severity).
+ *
+ * If `facts` is passed, the walk also POPULATES the store with the computed
+ * `type` (CanonicalType) and `cppType` for each expression. This is the single
+ * place concrete per-expression type facts are recorded — Phase 3 of the type-
+ * resolution consolidation — so gate rules can read them without re-deriving
+ * from the ts.TypeChecker, and so a future pipeline reorder can populate the
+ * same fields from the ProgramIR SymbolTable instead. See SemanticFacts.cppType.
+ */
+export function verifyFacts(program, userFiles, options = {}) {
+    const unknownSeverity = options.unknownTypeSeverity ?? "warning";
+    const facts = options.facts;
+    const checker = program.getTypeChecker();
+    const userFileSet = new Set(userFiles.map((f) => f.replace(/\\/g, "/")));
+    const diagnostics = [];
+    let expressionsVisited = 0;
+    let unknownTypeExpressions = 0;
+    for (const sourceFile of program.getSourceFiles()) {
+        const filePath = sourceFile.fileName.replace(/\\/g, "/");
+        if (!userFileSet.has(filePath))
+            continue;
+        if (filePath.includes("/node_modules/") || filePath.includes("/packages/"))
+            continue;
+        const sourceText = sourceFile.getFullText();
+        const visit = (node) => {
+            if (isSkippableForTyping(node)) {
+                // Still recurse so nested expressions in non-skippable children are
+                // visited, but don't type-check the skippable node itself.
+                ts.forEachChild(node, visit);
+                return;
+            }
+            if (ts.isExpression(node) && !isVoidOrNeverExpression(node)) {
+                expressionsVisited++;
+                const type = checker.getTypeAtLocation(node);
+                const category = canonicalize(checker, type);
+                // Record the concrete type facts on this expression node. `type` makes
+                // the SemanticFacts.type field actually populated (it was previously
+                // declared but only computed ephemerally here); `cppType` is the
+                // Phase 3 addition. Both are no-ops when no store is passed.
+                if (facts) {
+                    facts.merge(node, {
+                        type: category,
+                        ...(category !== "unknown"
+                            ? { cppType: cppTypeFromCanonicalType(checker, type, category) }
+                            : {}),
+                    });
+                }
+                if (category === "unknown") {
+                    unknownTypeExpressions++;
+                    if (unknownSeverity !== "off") {
+                        diagnostics.push(makeUnknownTypeDiagnostic(sourceText, node, checker, type));
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+    }
+    // Apply severity to the collected unknown-type diagnostics.
+    if (unknownSeverity === "warning") {
+        for (const d of diagnostics)
+            d.severity = "warning";
+    }
+    else if (unknownSeverity === "error") {
+        for (const d of diagnostics)
+            d.severity = "error";
+    }
+    return {
+        diagnostics,
+        counts: { expressionsVisited, unknownTypeExpressions },
+    };
+}
+function makeUnknownTypeDiagnostic(sourceText, node, checker, type) {
+    const message = describeUnknownType(type, checker, node);
+    const diag = makeDiagnostic(sourceText, node.getStart(), message, "warning", "TS2CPP_UNCLASSIFIABLE_TYPE");
+    diag.source = "semantic-facts-verifier";
+    return diag;
+}
+/**
+ * Produce a human-readable reason for why a type canonicalized to "unknown".
+ * By the time this runs, `any` has already been classified to its own category
+ * (not "unknown"), so the only remaining causes are `unknown`/`never` types
+ * (which the lowering can't target) or a type canonicalize() doesn't yet
+ * recognize (a classifier gap to report).
+ */
+function describeUnknownType(type, checker, node) {
+    const flags = type.flags;
+    const typeStr = checker.typeToString(type);
+    const exprText = node.getText().slice(0, 40);
+    if (flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Never)) {
+        return `Expression '${exprText}' has type '${typeStr}', which has no safe C++ target. Use an explicit type annotation.`;
+    }
+    // Not unknown/never but still unclassified — canonicalize() has a gap.
+    return `Expression '${exprText}' has type '${typeStr}', which the type classifier does not yet recognize. This is a cuttlefish gap — please report it.`;
+}
+/** Re-export so callers can introspect the typed-array name set if needed. */
+export { TYPED_ARRAY_NAMES };

package/dist/orchestrator/semantic-facts.d.ts

@@ -0,0 +1,141 @@
+import ts from "typescript";
+import type { Diagnostic } from "../types.js";
+/**
+ * Canonical type category. Deliberately small — this is NOT a full SType
+ * algebra. It exists to stop the six boolean predicates from each calling
+ * typeToString() in disguise.
+ *
+ * Field names are chosen to be SIR-compatible: a future promotion to a full
+ * SType algebra should be able to widen `category` without renaming consumers.
+ */
+export type CanonicalType = "primitive" | "struct" | "array" | "typed-array" | "map" | "set" | "function" | "any" | "unknown";
+/**
+ * How an expression's value reaches its use. The categories the current gates
+ * care about are: copy (map/record value lookup, by-value param) and reference.
+ * temporary/rvalue are reserved for future promotion; not all are populated in
+ * Phase 1.
+ */
+export type ValueCategory = "lvalue" | "rvalue" | "copy" | "reference" | "temporary";
+export type Lifetime = "local" | "param" | "param-by-ref" | "field" | "global" | "temporary" | "unknown";
+/**
+ * Nullability as the lowering sees it. `erased` = TS optional (`x?: T`) or
+ * nullable union flattened to a value type in C++ (the case
+ * TS2CPP_OPTIONAL_FIELD_NULLISH catches). `none` = definitively not null.
+ */
+export type Nullable = "none" | "erased" | "unknown";
+/**
+ * Provenance of a value, used by the mutation gates to decide whether a write
+ * reaches the caller/container.
+ *
+ * Only the origins the current gates consume are defined here. Add new origins
+ * as new gates migrate — do not pre-declare a large set.
+ */
+export type SemanticOrigin = "map-value-lookup" | "array-param" | "typed-array-param" | "local-binding" | "field-access" | "other";
+export interface SemanticFacts {
+    /** Canonical type category. The verifier requires this to be non-"unknown"
+     *  for every expression in user code, else a fatal diagnostic is emitted. */
+    type: CanonicalType;
+    valueCategory?: ValueCategory;
+    lifetime?: Lifetime;
+    nullable?: Nullable;
+    origin?: SemanticOrigin;
+    /**
+     * The concrete C++ type this node lowers to, when it is determinable from
+     * the TS type alone (e.g. `number` → "double", `string` → "std::string",
+     * `Uint8Array` → "uint8_t*"). Undefined when the cppType depends on IR-build
+     * context the type-checker does not have (user class field resolution,
+     * cross-module types, `auto` deduction from a complex initializer).
+     *
+     * Phase 3 of the type-resolution consolidation. This is populated from the
+     * ts.TypeChecker (which buildSemanticFacts already holds) as
+     * forward-compatible infrastructure: it lets gate rules read a concrete
+     * cppType without re-deriving it, and — if the pipeline is later reordered
+     * to build ProgramIR before the gates — the SymbolTable can populate this
+     * field directly and the ts.TypeChecker derivation removed. The direction is
+     * strictly one-way: gates read facts.cppType, they never feed it back into
+     * the IR/emit SymbolTable. See docs/design-semantic-facts.md.
+     */
+    cppType?: string;
+}
+/**
+ * Read-only view exposed to gate rules.
+ *
+ * `get` returns undefined for nodes outside user files or nodes the pipeline
+ * did not visit. Gate rules treat undefined as "no fact, skip" — they never
+ * throw. The verifier (Phase 3) is the only place that asserts presence.
+ */
+export interface FactStore {
+    /** Facts for a node, or undefined if not in a user file / not visited. */
+    get(node: ts.Node): Readonly<SemanticFacts> | undefined;
+    /** True iff node is in a user file and was visited by the pipeline. */
+    has(node: ts.Node): boolean;
+    /** Set a fact. Only called by analysis passes, before gate rules run. */
+    set(node: ts.Node, facts: SemanticFacts): void;
+    /**
+     * Merge a partial fact into an existing entry, creating one if absent.
+     * Used when multiple passes contribute to the same node. The `type` field
+     * defaults to "unknown" if a new entry is created — callers that know the
+     * type should set it explicitly first.
+     */
+    merge(node: ts.Node, partial: Partial<SemanticFacts>): void;
+}
+/**
+ * Result of building semantic facts for a program.
+ */
+export interface AnalysisResult {
+    facts: FactStore;
+    /** Fatal analysis diagnostics — appended before gate diagnostics. */
+    diagnostics: Diagnostic[];
+    /** Identifier-to-origin resolver consumed by mutation gates. */
+    resolver: BindingResolver;
+}
+/** Names recognized as typed arrays (Int8Array .. Float64Array, etc.). */
+export declare const TYPED_ARRAY_NAMES: Set<string>;
+/**
+ * Classify a resolved TS type into a canonical category. This is the single
+ * source of truth for "what kind of C++ concept does this type lower to?"
+ *
+ * Categories and their verifier meaning:
+ *  - concrete categories (primitive, struct, array, ...) — fine.
+ *  - "any" — the transpiler handles `any` via inference; the verifier treats
+ *    this as a NON-hazard (it is not `unknown`).
+ *  - "unknown" — genuinely unclassifiable; the verifier flags this.
+ *
+ * Unions with a null/undefined constituent (e.g. `Account | null`) are
+ * classified by their non-null constituent, because the transpiler erases
+ * optionality to the value type. `this` types resolve to the enclosing
+ * class/interface, so they classify as struct.
+ */
+export declare function canonicalize(checker: ts.TypeChecker, type: ts.Type): CanonicalType;
+/**
+ * Map a canonicalized type to the concrete C++ type the lowering emits, for
+ * the categories where the cppType is deterministic from the TS type alone.
+ * Returns undefined when the cppType depends on IR-build context the
+ * type-checker does not have (user-defined class/interface names resolve to
+ * themselves as struct names but their field layout is a SymbolTable concern;
+ * `auto` deduction from complex initializers is an IR-build concern).
+ *
+ * This populates SemanticFacts.cppType so gate rules can read a concrete type
+ * without re-deriving it. Phase 3 of the type-resolution consolidation — see
+ * the doc comment on SemanticFacts.cppType for the one-way direction.
+ */
+export declare function cppTypeFromCanonicalType(checker: ts.TypeChecker, type: ts.Type, category: CanonicalType): string | undefined;
+/**
+ * A name->facts binding resolver. Gate rules call `resolveOrigin(identifier)`
+ * to ask "what is the origin of the value this identifier refers to?", which
+ * resolves the identifier to its declaration and looks up the declaration's
+ * origin fact. This replaces the name-based scope-chain lookup in the old
+ * GateScope machinery: it is shadowing-proof because the checker resolves the
+ * identifier to the exact declaration, regardless of scope.
+ */
+export interface BindingResolver {
+    /**
+     * Resolve an identifier's value origin. Returns undefined if the identifier
+     * is not a value reference or has no recorded origin.
+     */
+    resolveOrigin(identifier: ts.Identifier): SemanticOrigin | undefined;
+}
+/**
+ * Build the SemanticFacts store for a program by running the analysis passes.
+ */
+export declare function buildSemanticFacts(program: ts.Program, userFiles: string[]): AnalysisResult;