@snovon/solast 0.2.0

package/dist/semantic/imports.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * Solidity import resolution.
+ *
+ * Solidity supports three import forms (per the language docs at
+ * https://docs.soliditylang.org/en/latest/layout-of-source-files.html):
+ *
+ *   1. `import "x";`                              — glob; merges all of x's symbols.
+ *   2. `import "x" as X;`                         — namespace; X.Foo references x's Foo.
+ *   3. `import {A, B as C} from "x";`             — named; optionally renamed.
+ *
+ * (ES-style `import * as X from "x";` is NOT valid Solidity — the spec
+ * docstring for SemanticModel calls this out explicitly because external
+ * reviewers commonly conflate them.)
+ *
+ * This module:
+ *   - Parses `ImportDirective` nodes into `ImportInfo` records.
+ *   - Resolves the raw path to an absolute path using the policy from
+ *     the spec: relative paths against importer dir; project paths via
+ *     remappings → node_modules → projectRoot fallback.
+ *   - Builds per-source-unit `visibleSymbols` maps so detector queries
+ *     like `resolveContract(fromPath, "Base")` can find a contract that
+ *     was imported (possibly under an alias) from another file.
+ *
+ * Lenient by design: unresolved imports emit a diagnostic but the rest
+ * of the model continues to work. Per-file detector behaviour falls
+ * back when cross-file lookups return undefined.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readImportDirective = readImportDirective;
+exports.resolveImportPath = resolveImportPath;
+exports.buildVisibleSymbols = buildVisibleSymbols;
+const path = __importStar(require("path"));
+const diagnostics_1 = require("./diagnostics");
+/**
+ * Read the three import forms from a single `ImportDirective` AST node.
+ * Returns `null` if the node doesn't look like a real import (defensive
+ * — the parser shouldn't emit those, but we don't want to crash if it
+ * does).
+ */
+function readImportDirective(node) {
+    if (!node)
+        return null;
+    if (node.type !== 'ImportDirective' && node.type !== 'ImportStatement') {
+        // Some forks of the parser emit `ImportStatement`; handle both.
+        return null;
+    }
+    const rawPath = typeof node.path === 'string'
+        ? node.path
+        : (typeof node.file === 'string' ? node.file : '');
+    if (!rawPath)
+        return null;
+    // `import {A, B as C} from "x";` — symbolAliases is non-empty.
+    // Parser shape varies between releases; handle both `{name, alias}`
+    // and `[name, alias]` tuples.
+    const symbolAliases = node.symbolAliases || [];
+    if (Array.isArray(symbolAliases) && symbolAliases.length > 0) {
+        const named = [];
+        for (const entry of symbolAliases) {
+            if (!entry)
+                continue;
+            if (Array.isArray(entry)) {
+                const imported = String(entry[0] || '');
+                const local = entry[1] != null ? String(entry[1]) : imported;
+                if (imported)
+                    named.push({ imported, local });
+                continue;
+            }
+            const imported = String((typeof entry.name === 'string' && entry.name)
+                || (entry.foreign && typeof entry.foreign.name === 'string' && entry.foreign.name)
+                || '');
+            const local = String((typeof entry.alias === 'string' && entry.alias)
+                || (typeof entry.local === 'string' && entry.local)
+                || imported);
+            if (imported)
+                named.push({ imported, local });
+        }
+        return { rawPath, kind: 'named', named };
+    }
+    // `import "x" as X;` — `unitAlias` is set.
+    if (typeof node.unitAlias === 'string' && node.unitAlias) {
+        return { rawPath, kind: 'namespace', namespace: node.unitAlias };
+    }
+    // Bare `import "x";`.
+    return { rawPath, kind: 'glob' };
+}
+/**
+ * Resolve a raw import path against the importer's directory and the
+ * project root. Returns the absolute path on success or `undefined`.
+ *
+ * Policy:
+ *   - Relative path (starts with `.` or `..`): normalise against
+ *     importer directory.
+ *   - Project path: check `remappings` first (longest-prefix match wins),
+ *     then `node_modules/` under projectRoot, then projectRoot itself.
+ *
+ * The model is lenient: a path that resolves to a non-existent file
+ * still returns the resolved string (so detectors / diagnostics know
+ * what we tried). Callers should check `fileExists` themselves before
+ * treating the path as authoritative.
+ */
+function resolveImportPath(rawPath, importerPath, ctx) {
+    if (!rawPath)
+        return undefined;
+    // Relative.
+    if (rawPath.startsWith('./') || rawPath.startsWith('../')) {
+        const importerDir = path.dirname(importerPath);
+        return path.resolve(importerDir, rawPath);
+    }
+    // Remappings: longest prefix wins to match foundry semantics.
+    const remappings = ctx.remappings || [];
+    let bestPrefix = '';
+    let bestRemap = null;
+    for (const remap of remappings) {
+        if (rawPath.startsWith(remap.from) && remap.from.length > bestPrefix.length) {
+            bestPrefix = remap.from;
+            bestRemap = remap;
+        }
+    }
+    if (bestRemap) {
+        const tail = rawPath.slice(bestPrefix.length);
+        // `remap.to` may be relative to projectRoot or absolute.
+        const target = path.isAbsolute(bestRemap.to)
+            ? path.join(bestRemap.to, tail)
+            : path.resolve(ctx.projectRoot, bestRemap.to, tail);
+        return target;
+    }
+    // node_modules fallback (common for OpenZeppelin et al.).
+    const nodeModules = path.resolve(ctx.projectRoot, 'node_modules', rawPath);
+    if (ctx.fileExists(nodeModules))
+        return nodeModules;
+    // Plain projectRoot-relative.
+    return path.resolve(ctx.projectRoot, rawPath);
+}
+/**
+ * Build the `visibleSymbols` map for a source unit: the set of contract
+ * names a detector working inside this file can reference, mapped to
+ * the actual `ContractInfo` the name resolves to.
+ *
+ * Three rules:
+ *   - Local declarations (contracts/libraries/interfaces in this file)
+ *     are always visible by their own name.
+ *   - `import "x";`            (glob)     → every export of x is visible by its export-name.
+ *   - `import "x" as X;`       (namespace) → `X.Foo` notation; for now we expose `X` as
+ *     a synthetic symbol pointing at the FIRST exported contract; detectors needing
+ *     full member access should consult `imports[i].resolvedPath` and re-resolve.
+ *     This is a known v1 limitation documented in the spec.
+ *   - `import {A, B as C} from "x";` (named) → each local name maps to the export.
+ *
+ * Diagnostics:
+ *   - `unresolved-import`: path didn't resolve to a parsed source unit.
+ *   - `unresolved-symbol`: a `named` import asks for an export the
+ *     source unit doesn't have.
+ */
+function buildVisibleSymbols(sourceUnit, parsedSourceUnits, contractsByExporter, diagnostics) {
+    const visible = new Map();
+    // Local declarations first; they shadow imports per Solidity semantics.
+    for (const contractId of sourceUnit.declaredContracts) {
+        // Extract the name from the contractId (`<path>::<name>`).
+        const dblColon = contractId.lastIndexOf('::');
+        if (dblColon < 0)
+            continue;
+        const name = contractId.slice(dblColon + 2);
+        visible.set(name, { contractId, name });
+    }
+    for (const imp of sourceUnit.imports) {
+        if (!imp.resolvedPath || !parsedSourceUnits.has(imp.resolvedPath)) {
+            diagnostics.push((0, diagnostics_1.makeDiagnostic)('unresolved-import', sourceUnit.path, `Could not resolve import "${imp.rawPath}" (resolvedPath=${imp.resolvedPath || 'undefined'})`));
+            continue;
+        }
+        const exports = contractsByExporter.get(imp.resolvedPath);
+        if (!exports || exports.size === 0)
+            continue;
+        if (imp.kind === 'glob') {
+            for (const [exportName, contractInfo] of exports) {
+                // Local declarations take precedence — don't overwrite.
+                if (!visible.has(exportName)) {
+                    visible.set(exportName, { contractId: contractInfo.id, name: exportName });
+                }
+            }
+            continue;
+        }
+        if (imp.kind === 'namespace' && imp.namespace) {
+            // v1 limitation: namespace member access (`Lib.Base`) is recorded
+            // but not fully expanded into the visibleSymbols map. Detectors
+            // doing inheritance lookups against `Lib.Base` will need to walk
+            // the import resolved path explicitly. We DO record the namespace
+            // alias against the *first* exported contract so simple lookups
+            // (`resolveContract(file, 'Lib.Base')`) can match later.
+            // Spec section "Algorithm choices > Import-alias resolution" notes
+            // this. Slice 2 detector adoption will exercise it.
+            // No-op: nothing to map into `visibleSymbols` for the alias
+            // itself — the `imports[i]` record carries enough info for
+            // member-access resolution at lookup time.
+            continue;
+        }
+        if (imp.kind === 'named' && imp.named) {
+            for (const { imported, local } of imp.named) {
+                const target = exports.get(imported);
+                if (!target) {
+                    diagnostics.push((0, diagnostics_1.makeDiagnostic)('unresolved-symbol', sourceUnit.path, `Named import {${imported}${local !== imported ? ` as ${local}` : ''}} from "${imp.rawPath}": symbol "${imported}" not found in the imported source unit`));
+                    continue;
+                }
+                if (!visible.has(local)) {
+                    visible.set(local, { contractId: target.id, name: imported });
+                }
+            }
+            continue;
+        }
+    }
+    return visible;
+}
+//# sourceMappingURL=imports.js.map

package/dist/semantic/index.d.ts

@@ -0,0 +1,2 @@
+export { buildSemanticModel, type SemanticModel, type BuildSemanticModelInput } from './model';
+export { TaintTracker, type TaintQueryOptions, type TaintSourcePredicate } from './taint-tracker';

package/dist/semantic/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaintTracker = exports.buildSemanticModel = void 0;
+var model_1 = require("./model");
+Object.defineProperty(exports, "buildSemanticModel", { enumerable: true, get: function () { return model_1.buildSemanticModel; } });
+var taint_tracker_1 = require("./taint-tracker");
+Object.defineProperty(exports, "TaintTracker", { enumerable: true, get: function () { return taint_tracker_1.TaintTracker; } });
+//# sourceMappingURL=index.js.map

package/dist/semantic/inheritance.d.ts

@@ -0,0 +1,33 @@
+/**
+ * C3 linearization with **Solidity-specific** base-list precedence.
+ *
+ * Solidity's `contract D is B, C` lists base contracts left-to-right
+ * from "most base-like" to "most derived" (per the official Solidity
+ * docs). That's the opposite of Python's `class D(B, C):` convention,
+ * where `B` is the immediate parent (most-derived base) and is listed
+ * first.
+ *
+ * Concretely:
+ *   - Python:   `class D(B, C): pass; class B(A): pass; class C(A): pass`
+ *               → MRO is `[D, B, C, A]`
+ *   - Solidity: `contract D is B, C; contract B is A; contract C is A;`
+ *               → MRO is `[D, C, B, A]`  (rightmost base = highest precedence)
+ *
+ * Implementation: reverse the base list before feeding standard C3
+ * merge. The reversal converts Solidity ordering into Python ordering
+ * for the purpose of computing the MRO; the result is what Solidity's
+ * own dispatch produces (verified against the diamond example in the
+ * Solidity docs). Note the reversal direction is load-bearing: feeding
+ * the base list in source order yields the Python-style ordering
+ * (`[D, B, C, A]` for the diamond), which is NOT what Solidity does.
+ */
+import type { ContractId, LinearizedContract, ContractInfo } from './types';
+import { SemanticDiagnostic } from './diagnostics';
+/**
+ * Build the MRO for every contract in `contracts`, lazily and with
+ * memoization. Cyclic graphs and impossible merges emit diagnostics
+ * (per the lenient-by-design policy from `diagnostics.ts`) and leave
+ * the affected contract's linearization undefined; other contracts
+ * still linearize.
+ */
+export declare function buildLinearizer(contracts: Map<ContractId, ContractInfo>, diagnostics: SemanticDiagnostic[]): (id: ContractId) => LinearizedContract | undefined;

package/dist/semantic/inheritance.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * C3 linearization with **Solidity-specific** base-list precedence.
+ *
+ * Solidity's `contract D is B, C` lists base contracts left-to-right
+ * from "most base-like" to "most derived" (per the official Solidity
+ * docs). That's the opposite of Python's `class D(B, C):` convention,
+ * where `B` is the immediate parent (most-derived base) and is listed
+ * first.
+ *
+ * Concretely:
+ *   - Python:   `class D(B, C): pass; class B(A): pass; class C(A): pass`
+ *               → MRO is `[D, B, C, A]`
+ *   - Solidity: `contract D is B, C; contract B is A; contract C is A;`
+ *               → MRO is `[D, C, B, A]`  (rightmost base = highest precedence)
+ *
+ * Implementation: reverse the base list before feeding standard C3
+ * merge. The reversal converts Solidity ordering into Python ordering
+ * for the purpose of computing the MRO; the result is what Solidity's
+ * own dispatch produces (verified against the diamond example in the
+ * Solidity docs). Note the reversal direction is load-bearing: feeding
+ * the base list in source order yields the Python-style ordering
+ * (`[D, B, C, A]` for the diamond), which is NOT what Solidity does.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLinearizer = buildLinearizer;
+const diagnostics_1 = require("./diagnostics");
+/**
+ * Build the MRO for every contract in `contracts`, lazily and with
+ * memoization. Cyclic graphs and impossible merges emit diagnostics
+ * (per the lenient-by-design policy from `diagnostics.ts`) and leave
+ * the affected contract's linearization undefined; other contracts
+ * still linearize.
+ */
+function buildLinearizer(contracts, diagnostics) {
+    const cache = new Map();
+    const computing = new Set();
+    function linearize(id) {
+        if (cache.has(id))
+            return cache.get(id);
+        if (computing.has(id)) {
+            // Cycle detected. Bail out for every contract on the stack.
+            // We emit one diagnostic per call into this branch — the cycle
+            // itself is reported below when the outermost caller sees it.
+            return undefined;
+        }
+        const info = contracts.get(id);
+        if (!info) {
+            cache.set(id, undefined);
+            return undefined;
+        }
+        computing.add(id);
+        // Resolve base contracts. `BaseSpecifier.resolved` may be undefined
+        // for bases referenced by an unresolved name (cross-file alias that
+        // didn't resolve, or a name that's literally not in the project).
+        // Those bases are skipped — the MRO is computed over only the
+        // resolved portion of the inheritance graph. Detectors that need to
+        // know "this contract has unresolved bases" can inspect
+        // `info.bases.filter(b => !b.resolved)` themselves.
+        const resolvedBases = [];
+        for (const base of info.bases) {
+            if (base.resolved)
+                resolvedBases.push(base.resolved);
+        }
+        if (resolvedBases.length === 0) {
+            computing.delete(id);
+            cache.set(id, [id]);
+            return [id];
+        }
+        // === Solidity-specific step ===
+        // Solidity lists bases from most-base-like to most-derived; C3
+        // expects them in most-derived-first order (Python convention).
+        // Reverse the list so standard C3 produces Solidity precedence.
+        const parentsForC3 = resolvedBases.slice().reverse();
+        // Compute parent MROs.
+        const parentMros = [];
+        let detectedCycle = false;
+        for (const parentId of parentsForC3) {
+            const parentMro = linearize(parentId);
+            if (parentMro === undefined) {
+                // Either cycle or unknown contract; bail out the whole computation.
+                detectedCycle = true;
+                break;
+            }
+            parentMros.push(parentMro);
+        }
+        if (detectedCycle) {
+            computing.delete(id);
+            cache.set(id, undefined);
+            diagnostics.push((0, diagnostics_1.makeDiagnostic)('inheritance-cycle', info.sourcePath, `Inheritance cycle detected when linearizing ${info.name} (${id})`));
+            return undefined;
+        }
+        // Standard C3 merge: L[D] = D + merge(L[parents[0]], L[parents[1]], ..., parents)
+        // The trailing `parents` itself goes into the merge to preserve the
+        // relative order of direct parents.
+        const lists = parentMros.map(m => m.slice());
+        lists.push(parentsForC3.slice());
+        const mro = [id];
+        while (lists.some(l => l.length > 0)) {
+            let candidate;
+            for (const list of lists) {
+                if (list.length === 0)
+                    continue;
+                const head = list[0];
+                // A head is acceptable iff it doesn't appear in the tail of any list.
+                const inTail = lists.some(other => other.indexOf(head) > 0);
+                if (!inTail) {
+                    candidate = head;
+                    break;
+                }
+            }
+            if (candidate === undefined) {
+                // No acceptable head — linearization is impossible.
+                computing.delete(id);
+                cache.set(id, undefined);
+                diagnostics.push((0, diagnostics_1.makeDiagnostic)('linearization-impossible', info.sourcePath, `C3 linearization is impossible for ${info.name} (${id}) — no acceptable head in the merge step`));
+                return undefined;
+            }
+            mro.push(candidate);
+            // Remove candidate from the heads of all lists.
+            for (const list of lists) {
+                if (list[0] === candidate)
+                    list.shift();
+            }
+        }
+        computing.delete(id);
+        cache.set(id, mro);
+        return mro;
+    }
+    return (id) => {
+        const mro = linearize(id);
+        if (!mro)
+            return undefined;
+        return { contractId: id, mro };
+    };
+}
+//# sourceMappingURL=inheritance.js.map

package/dist/semantic/model.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SemanticModel — cross-file inheritance + import resolution.
+ *
+ * What this module is:
+ *   - A read-only index over parsed Solidity source units.
+ *   - Lets a detector ask "what contracts are in scope here?",
+ *     "what's the inheritance MRO of this contract?", "what modifiers
+ *     can `Derived` see (including inherited from `Base` in another
+ *     file)?", "what's the body of `onlyAdmin` for this contract?".
+ *
+ * What this module is NOT:
+ *   - A type checker.
+ *   - A `solc` shim.
+ *   - A bytecode model.
+ *   - A general dataflow / call-graph layer (the EOG in
+ *     `src/semantic/eog.ts` is separate; SemanticModel does not replace
+ *     or extend it).
+ *   - A detector. Detectors consume `SemanticModel` via `ctx.semantic`
+ *     starting in Slice 2; Slice 1 ships only the infra, no detector
+ *     adoption.
+ *
+ * Lifecycle:
+ *   - Construct once per `scanFiles` invocation from the set of parsed
+ *     source units the scanner is about to walk.
+ *   - Detectors get a reference via the optional `ctx.semantic` field.
+ *   - The model is read-only after construction; subsequent detector
+ *     calls only consult cached lookups.
+ *
+ * Cost:
+ *   - Construction is O(N) over parsed source units (build the contract
+ *     and import indexes) plus O(M) over contracts to populate base
+ *     resolution. Linearization is lazy + memoized — first lookup of a
+ *     contract's MRO pays the C3 merge cost; subsequent lookups are
+ *     O(1). The performance budget from the spec (< 500ms for ~100-file
+ *     project) is comfortable.
+ */
+import type { ContractInfo, ContractId, SourceUnitInfo, SourcePath, SymbolName, FunctionInfo, ModifierInfo, LinearizedContract } from './types';
+import type { SemanticDiagnostic } from './diagnostics';
+export interface BuildSemanticModelInput {
+    /** Parsed source units the model should index. Pre-parsed by the caller. */
+    parsedFiles: Array<{
+        path: SourcePath;
+        ast: any;
+        source?: string;
+    }>;
+    /** Absolute project root for resolving non-relative imports. Optional; pass undefined when not in project-scan mode. */
+    projectRoot?: string;
+    /** Foundry-style remappings. v1 reads these from `foundry.toml` if the caller wants to; this module just consumes the parsed list. */
+    remappings?: Array<{
+        from: string;
+        to: string;
+    }>;
+    /**
+     * Pluggable file-existence check. Defaults to a stub that always
+     * returns false (so the resolver doesn't try to `fs.statSync` unknown
+     * paths). The CLI injects a real check.
+     */
+    fileExists?: (absPath: string) => boolean;
+}
+export interface SemanticModel {
+    contracts: Map<ContractId, ContractInfo>;
+    sourceUnits: Map<SourcePath, SourceUnitInfo>;
+    diagnostics: SemanticDiagnostic[];
+    /**
+     * Resolve a name as visible in the source unit at `fromPath` to its
+     * canonical `ContractInfo`. Returns undefined when the name doesn't
+     * resolve (no local declaration, no matching import).
+     *
+     * The lookup honours import aliases:
+     *   - Glob import:      `import "Base.sol"; contract D is Base` → looks up `Base`.
+     *   - Named alias:      `import {Base as B} from "Base.sol"; contract D is B` → looks up `B`.
+     *   - Namespace alias:  `import "Base.sol" as Lib; contract D is Lib.Base` → looks up `Lib.Base`.
+     */
+    resolveContract(fromPath: SourcePath, visibleName: string): ContractInfo | undefined;
+    /**
+     * Compute the linearized MRO for a contract. Most-derived first, in
+     * Solidity precedence (for `contract D is B, C`, MRO begins `[D, C, B, ...]`).
+     * Returns undefined for contracts with cycles or impossible
+     * linearizations.
+     */
+    linearize(contractId: ContractId): LinearizedContract | undefined;
+    /**
+     * Walk the contract's MRO and collect all inherited externally-callable
+     * functions (public + external). De-duped by function name with most-
+     * derived-wins (matching Solidity's `super.f()` dispatch). The
+     * contract's own functions are included.
+     */
+    inheritedFunctions(contractId: ContractId): FunctionInfo[];
+    /**
+     * Resolve a modifier name to its declaration, walking the contract's
+     * MRO. First match wins (most-derived-first).
+     */
+    resolveModifier(contractId: ContractId, modifierName: SymbolName): ModifierInfo | undefined;
+}
+export declare function buildSemanticModel(input: BuildSemanticModelInput): SemanticModel;