@snovon/solast 0.2.0

package/dist/scan.js

@@ -0,0 +1,558 @@
+"use strict";
+/**
+ * Scan orchestration. Extracted from `src/index.ts` per roadmap item
+ * 1.1 slice 6/N. Public API surface is unchanged — `src/index.ts`
+ * re-exports `scanFiles`, `scanAst`, and `discoverFiles` so external
+ * consumers (the CLI, downstream packages) continue to see them at
+ * the same path.
+ *
+ * `scanFiles` orchestrates the per-file scan loop: read source, parse
+ * AST, run the registry, stamp finding metadata via the hashing
+ * primitives, optionally dedup. `scanAst` is the AST-already-parsed
+ * entry point on the programmatic API. `discoverFiles`
+ * walks an input path or list and produces a sorted, deduplicated
+ * list of `.sol` files.
+ */
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SolidityParseError = void 0;
+exports.discoverFiles = discoverFiles;
+exports.scanFiles = scanFiles;
+exports.parseSolidityContent = parseSolidityContent;
+exports.validateSolidityParseResult = validateSolidityParseResult;
+exports.scanAst = scanAst;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const parser_1 = __importDefault(require("@solidity-parser/parser"));
+const findings_1 = require("./dedup/findings");
+const registry_1 = require("./registry");
+const hashing_1 = require("./identity/hashing");
+const files_1 = require("./dedup/files");
+const model_1 = require("./semantic/model");
+const taint_tracker_1 = require("./semantic/taint-tracker");
+const imports_1 = require("./semantic/imports");
+const suppressions_1 = require("./rules/suppressions");
+class SolidityParseError extends Error {
+    unsupportedVersionHint;
+    constructor(message, unsupportedVersionHint = false) {
+        super(message);
+        this.unsupportedVersionHint = unsupportedVersionHint;
+        this.name = 'SolidityParseError';
+    }
+}
+exports.SolidityParseError = SolidityParseError;
+function walkDirectory(dir) {
+    const files = [];
+    const entries = fs.readdirSync(dir).sort((a, b) => a.localeCompare(b));
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry);
+        let stat;
+        try {
+            stat = fs.statSync(fullPath);
+        }
+        catch {
+            // Broken symlink or unreadable entry — skip it instead of aborting
+            // the whole discovery walk.
+            continue;
+        }
+        if (stat.isDirectory()) {
+            files.push(...walkDirectory(fullPath));
+        }
+        else if (entry.endsWith('.sol')) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function discoverFiles(inputPaths) {
+    const paths = Array.isArray(inputPaths) ? inputPaths : [inputPaths];
+    const discovered = new Map();
+    for (const inputPath of paths) {
+        let stat;
+        try {
+            stat = fs.statSync(inputPath);
+        }
+        catch (e) {
+            throw new Error(`Path not found: ${inputPath}`);
+        }
+        if (stat.isDirectory()) {
+            for (const file of walkDirectory(inputPath)) {
+                discovered.set(path.resolve(file), file);
+            }
+        }
+        else if (stat.isFile() && inputPath.endsWith('.sol')) {
+            discovered.set(path.resolve(inputPath), inputPath);
+        }
+    }
+    return [...discovered.values()].sort((a, b) => a.localeCompare(b));
+}
+function scanFiles(files, options = {}) {
+    files = (0, files_1.deduplicateFilesByContent)(files);
+    let results = [];
+    const sourceSuppressionDiagnostics = [];
+    // The registry is reused across files: each detector resets its own
+    // state in setFile(), and DetectorRegistry caches the fan-out visitor
+    // so we only pay for prototype-walk + bind work on the first file.
+    // Constructing a new registry per file (the previous behaviour) made
+    // every cache miss and re-bound every method.
+    const registry = (0, registry_1.createDefaultDetectorRegistry)({ profile: options.profile, detectorOptions: options.detectorOptions });
+    const ignoredDetectorIds = registry.ignoredDetectorIds(options.rules, options.enabledRules, options.ignorePatterns);
+    const validRuleIds = new Set(registry.ids());
+    if (!needsProjectSemanticModel(options)) {
+        for (const file of files) {
+            let content = '';
+            let contractHash = '';
+            try {
+                content = fs.readFileSync(file, 'utf-8');
+                contractHash = (0, hashing_1.computeContractHash)(content);
+                const ast = parseSolidityContent(content);
+                try {
+                    const findings = registry.runAll(ast, path.resolve(file), content, options.rules, options.enabledRules, options.ignorePatterns, undefined, undefined, undefined, ignoredDetectorIds, options.tier);
+                    const filtered = (0, suppressions_1.applySourceSuppressions)(findings, file, content, validRuleIds);
+                    sourceSuppressionDiagnostics.push(...filtered.diagnostics);
+                    for (const finding of filtered.findings) {
+                        finding.file = file;
+                        finding.contractHash = contractHash;
+                        finding.findingId = (0, hashing_1.computeFindingId)(finding.file, finding.line, finding.ruleId, contractHash, finding.instance_key);
+                        finding.snippetHash = (0, hashing_1.computeSnippetHash)(content, finding.line, finding.endLine ?? finding.line);
+                        if (finding.source === undefined)
+                            finding.source = content;
+                        results.push(finding);
+                    }
+                }
+                catch (e) {
+                    results.push({
+                        file: file,
+                        line: 0,
+                        ruleId: 'scan-error',
+                        severity: 'error',
+                        message: `Detector run failed: ${e.message}`,
+                        findingId: '',
+                        contractHash: contractHash
+                    });
+                }
+            }
+            catch (e) {
+                results.push({
+                    file: file,
+                    line: 0,
+                    ruleId: 'parse-error',
+                    severity: 'error',
+                    message: formatParseErrorMessage(e, content),
+                    findingId: '',
+                    contractHash: contractHash
+                });
+            }
+        }
+        if (options.dedup && results.length > 0) {
+            const { findings: deduped, rawCount, uniqueCount } = (0, findings_1.dedupFindings)(results);
+            results = deduped;
+            results._dedup = { rawCount, uniqueCount };
+        }
+        attachIgnoreSuppressionMetadata(results, options, ignoredDetectorIds);
+        attachSourceSuppressionDiagnostics(results, sourceSuppressionDiagnostics);
+        attachProfileStats(results, options, registry.getProfileStats());
+        const profileSummary = options.profile ? '' : registry.formatProfileSummary();
+        if (profileSummary) {
+            process.stderr.write(profileSummary + '\n');
+        }
+        return results;
+    }
+    const parsed = [];
+    for (const file of files) {
+        let content = '';
+        let contractHash = '';
+        try {
+            content = fs.readFileSync(file, 'utf-8');
+            contractHash = (0, hashing_1.computeContractHash)(content);
+            const ast = parseSolidityContent(content);
+            parsed.push({ file, canonicalPath: path.resolve(file), content, contractHash, ast });
+        }
+        catch (e) {
+            results.push({
+                file: file,
+                line: 0,
+                ruleId: 'parse-error',
+                severity: 'error',
+                message: formatParseErrorMessage(e, content),
+                findingId: '',
+                contractHash: contractHash
+            });
+        }
+    }
+    // Pass 2: build SemanticModel across all successfully-parsed files.
+    // Canonical (absolute) paths are used for semantic identity so that
+    // relative parsed paths and absolute resolved import paths match.
+    // The original display path is preserved for user-facing findings.
+    const semanticParsedFiles = parsed.map(p => ({ path: p.canonicalPath, ast: p.ast, source: p.content }));
+    const semanticPaths = new Set(semanticParsedFiles.map(p => p.path));
+    for (const p of parsed) {
+        for (const imported of lazyLoadTransitiveImports(p.canonicalPath, p.ast)) {
+            if (semanticPaths.has(imported.path))
+                continue;
+            semanticPaths.add(imported.path);
+            semanticParsedFiles.push(imported);
+        }
+    }
+    const projectRoot = computeProjectRootFromFiles(files);
+    const semantic = (0, model_1.buildSemanticModel)({
+        parsedFiles: semanticParsedFiles,
+        projectRoot,
+        fileExists: (absPath) => {
+            try {
+                return fs.existsSync(absPath);
+            }
+            catch (_e) {
+                return false;
+            }
+        },
+    });
+    const taint = new taint_tracker_1.TaintTracker(semantic);
+    // Pass 3: per-file detector run, sharing the same SemanticModel.
+    // Detectors receive the canonical path so semantic-model contract IDs
+    // match; findings are patched back to the original display path.
+    for (const { file, canonicalPath, content, contractHash, ast } of parsed) {
+        try {
+            const findings = registry.runAll(ast, canonicalPath, content, options.rules, options.enabledRules, options.ignorePatterns, semantic, taint, options.solcVersion, ignoredDetectorIds, options.tier);
+            const filtered = (0, suppressions_1.applySourceSuppressions)(findings, file, content, validRuleIds);
+            sourceSuppressionDiagnostics.push(...filtered.diagnostics);
+            for (const finding of filtered.findings) {
+                finding.file = file;
+                finding.contractHash = contractHash;
+                // `instance_key` is the detector-supplied discriminator that keeps
+                // findingId distinct when multiple findings share (file, line, ruleId).
+                // Used by missing-access-control's inherited-walk to disambiguate
+                // multiple inherited critical functions on a single derived contract.
+                finding.findingId = (0, hashing_1.computeFindingId)(finding.file, finding.line, finding.ruleId, contractHash, finding.instance_key);
+                finding.snippetHash = (0, hashing_1.computeSnippetHash)(content, finding.line, finding.endLine ?? finding.line);
+                // source holds provenance for SDK findings; set to source
+                // content only when the detector has not already set it (so
+                // the text formatter can extract snippets for built-in rules).
+                if (finding.source === undefined)
+                    finding.source = content;
+                results.push(finding);
+            }
+        }
+        catch (e) {
+            results.push({
+                file: file,
+                line: 0,
+                ruleId: 'scan-error',
+                severity: 'error',
+                message: `Detector run failed: ${e.message}`,
+                findingId: '',
+                contractHash: contractHash
+            });
+        }
+    }
+    if (options.dedup && results.length > 0) {
+        const { findings: deduped, rawCount, uniqueCount } = (0, findings_1.dedupFindings)(results);
+        results = deduped;
+        results._dedup = { rawCount, uniqueCount };
+    }
+    attachIgnoreSuppressionMetadata(results, options, ignoredDetectorIds);
+    attachSourceSuppressionDiagnostics(results, sourceSuppressionDiagnostics);
+    // P.2: emit per-detector profile summary to stderr after the full
+    // scan completes when `SOLAST_PROFILE=1` was set. stderr is the
+    // convention so the NDJSON / SARIF stdout pipeline stays clean. The
+    // summary is empty / skipped when profiling is disabled.
+    attachProfileStats(results, options, registry.getProfileStats());
+    const profileSummary = options.profile ? '' : registry.formatProfileSummary();
+    if (profileSummary) {
+        process.stderr.write(profileSummary + '\n');
+    }
+    return results;
+}
+function attachProfileStats(results, options, profileStats) {
+    if (!options.profile)
+        return;
+    results._profileStats = profileStats;
+}
+function attachIgnoreSuppressionMetadata(results, options, suppressedDetectorIds) {
+    if (!options.ignorePatterns || options.ignorePatterns.length === 0)
+        return;
+    results._ignoreSuppression = {
+        patterns: options.ignorePatterns.slice(),
+        suppressedDetectorIds: suppressedDetectorIds.slice(),
+        suppressedFindingCount: 0,
+    };
+}
+function attachSourceSuppressionDiagnostics(results, diagnostics) {
+    if (diagnostics.length === 0)
+        return;
+    results._sourceSuppressionDiagnostics = diagnostics.slice();
+}
+function needsProjectSemanticModel(options) {
+    if (!options.rules || options.rules.length === 0)
+        return true;
+    // Every rule id whose detector consumes ctx.semantic / ctx.taint /
+    // setSemanticModel. A rule missing from this list silently loses
+    // cross-file context under `--rule <id>` and produces different findings
+    // than an unfiltered scan. Keep in sync with:
+    //   grep -rlE 'ctx\??\.(taint|semantic)|setSemanticModel' src/detectors
+    const semanticRuleIds = new Set([
+        'access-control',
+        'check-effects-interactions',
+        'classic-reentrancy',
+        'cross-chain-arbitrary-call',
+        'cross-contract-integer-overflow',
+        'cross-function-reentrancy',
+        'delegatecall-init',
+        'delegatecall-untrusted-implementation',
+        'erc20-safe-wrapper-return-unchecked',
+        'erc777-tokens-to-send-reentrancy',
+        'governance-flash-loan',
+        'initialization-access-control',
+        'inheritance-override',
+        'missing-access-control',
+        'oracle-manipulation',
+        'sky-oft-governance-payload',
+        'uninitialized-implementation',
+    ]);
+    return options.rules.some(ruleId => semanticRuleIds.has(ruleId));
+}
+function parseSolidityContent(content) {
+    try {
+        return validateSolidityParseResult(parser_1.default.parse(content, { loc: true, range: true }));
+    }
+    catch (e) {
+        if (!shouldRetryWithPartialIdentifierWorkaround(e, content))
+            throw toSolidityParseError(e, content);
+        const normalized = content.replace(/\bpartial\b/g, 'partial_');
+        try {
+            return validateSolidityParseResult(parser_1.default.parse(normalized, { loc: true, range: true }));
+        }
+        catch (retryError) {
+            throw toSolidityParseError(retryError, normalized);
+        }
+    }
+}
+function validateSolidityParseResult(ast) {
+    if (!ast || typeof ast !== 'object') {
+        throw new SolidityParseError('parser returned no AST');
+    }
+    if (ast.type !== 'SourceUnit') {
+        throw new SolidityParseError("parser returned an invalid AST root (expected SourceUnit)");
+    }
+    if (Array.isArray(ast.errors) && ast.errors.length > 0) {
+        const first = ast.errors[0] || {};
+        const location = Number.isFinite(first.line)
+            ? ` (${first.line}:${Number.isFinite(first.column) ? first.column : 0})`
+            : '';
+        throw new SolidityParseError(`${first.message || 'parser reported errors'}${location}`);
+    }
+    return ast;
+}
+function formatParseErrorMessage(e, content) {
+    if (e instanceof SolidityParseError && e.unsupportedVersionHint || isUnsupportedSolidityParseFailure(e, content)) {
+        return 'could not parse (unsupported Solidity version - SolAST supports 0.4+)';
+    }
+    const detail = sanitizeParseErrorDetail(e);
+    return detail ? `could not parse: ${detail}` : 'could not parse';
+}
+function toSolidityParseError(e, content) {
+    if (e instanceof SolidityParseError)
+        return e;
+    const unsupportedVersionHint = isUnsupportedSolidityParseFailure(e, content);
+    const message = unsupportedVersionHint
+        ? 'unsupported Solidity version - SolAST supports 0.4+'
+        : sanitizeParseErrorDetail(e);
+    return new SolidityParseError(message || 'parser failed', unsupportedVersionHint);
+}
+function isUnsupportedSolidityParseFailure(e, content) {
+    const message = String(e?.message || '');
+    return message.includes("Cannot read properties of null (reading 'accept')") ||
+        (!/\bpragma\s+solidity\b/.test(content) && /\bmodifier\b[\s\S]*\bthrow\b[\s\S]*_\s*(?:;|\})/.test(content));
+}
+function sanitizeParseErrorDetail(e) {
+    const message = e instanceof Error ? e.message : String(e || '');
+    return message.split(/\r?\n/)[0].replace(/^Error:\s*/, '').trim();
+}
+function shouldRetryWithPartialIdentifierWorkaround(e, content) {
+    const message = String(e?.message || '');
+    return /\bpartial\b/.test(content) &&
+        message.includes('primary expression should exist when children length is 1');
+}
+function scanAst(ast, file = '<ast>', sourceText, options = {}) {
+    if (ast == null)
+        return [];
+    if (typeof ast !== 'object') {
+        throw new Error('scanAst: AST must be an object');
+    }
+    if (Object.keys(ast).length === 0)
+        return [];
+    // Build a single-source-unit SemanticModel using a canonical absolute
+    // path so contract IDs are consistent with scanFiles. The original
+    // display path is restored in findings below.
+    const canonicalFile = path.resolve(file);
+    const projectRoot = path.dirname(canonicalFile);
+    // Lazy import-load: when the single-file AST input references local
+    // imports that exist on disk, read+parse them and feed them to
+    // SemanticModel so cross-file inheritance resolves (roadmap 3.3 /
+    // H.3 follow-up to Slice 2a). Files not on disk silently skip,
+    // preserving prior pure-in-memory behaviour for callers that drive
+    // scanAst with synthetic ASTs (the in-process tests
+    // that pass `file='<ast>'`). Only the canonical file is detector-
+    // walked; imported files just populate the model.
+    const extraParsed = lazyLoadTransitiveImports(canonicalFile, ast);
+    const parsedFiles = [
+        { path: canonicalFile, ast, source: sourceText },
+        ...extraParsed,
+    ];
+    const semantic = (0, model_1.buildSemanticModel)({
+        parsedFiles,
+        projectRoot,
+        fileExists: (absPath) => {
+            try {
+                return fs.existsSync(absPath);
+            }
+            catch (_e) {
+                return false;
+            }
+        },
+    });
+    const taint = new taint_tracker_1.TaintTracker(semantic);
+    const registry = (0, registry_1.createDefaultDetectorRegistry)({ profile: options.profile, detectorOptions: options.detectorOptions });
+    const ignoredDetectorIds = registry.ignoredDetectorIds(options.rules, options.enabledRules, options.ignorePatterns);
+    const validRuleIds = new Set(registry.ids());
+    const findings = registry.runAll(ast, canonicalFile, sourceText, options.rules, options.enabledRules, options.ignorePatterns, semantic, taint, options.solcVersion, ignoredDetectorIds, options.tier);
+    const filtered = (0, suppressions_1.applySourceSuppressions)(findings, file, sourceText, validRuleIds);
+    for (const f of filtered.findings) {
+        f.file = file;
+    }
+    const results = [...filtered.findings];
+    attachIgnoreSuppressionMetadata(results, options, ignoredDetectorIds);
+    attachSourceSuppressionDiagnostics(results, filtered.diagnostics);
+    attachProfileStats(results, options, registry.getProfileStats());
+    return results;
+}
+/**
+ * Read + parse transitive on-disk imports starting from a single
+ * already-parsed file. Returns the additional parsed source units so
+ * the caller can pass them to SemanticModel.
+ *
+ * - Only imports that exist on disk are loaded; missing files skip
+ *   silently (matches scanAst's "lenient single-file mode" semantics).
+ * - Parse errors on imported files also skip silently — the primary
+ *   file's findings stay correct; the model just lacks one base.
+ * - Recursion is breadth-first; cycles are prevented by the `seen` set.
+ * - Remappings are not consulted (scanAst has no project config); only
+ *   relative imports and bare-name imports rooted at `path.dirname(file)`
+ *   resolve. This is enough for the H.3 fixture shape
+ *   (Derived.sol imports "./Base.sol"); richer config-driven discovery
+ *   stays in scanFiles' project-scan path.
+ */
+function lazyLoadTransitiveImports(startCanonicalFile, startAst) {
+    const out = [];
+    const seen = new Set([startCanonicalFile]);
+    const queue = [
+        { canonical: startCanonicalFile, ast: startAst },
+    ];
+    const fileExists = (p) => {
+        try {
+            return fs.existsSync(p);
+        }
+        catch (_e) {
+            return false;
+        }
+    };
+    while (queue.length > 0) {
+        const { canonical, ast } = queue.shift();
+        const children = Array.isArray(ast?.children) ? ast.children
+            : Array.isArray(ast?.subNodes) ? ast.subNodes
+                : [];
+        for (const child of children) {
+            if (!child || typeof child !== 'object')
+                continue;
+            if (child.type !== 'ImportDirective' && child.type !== 'ImportStatement')
+                continue;
+            const imp = (0, imports_1.readImportDirective)(child);
+            if (!imp)
+                continue;
+            const resolved = (0, imports_1.resolveImportPath)(imp.rawPath, canonical, {
+                projectRoot: path.dirname(canonical),
+                remappings: [],
+                fileExists,
+            });
+            if (!resolved || seen.has(resolved))
+                continue;
+            if (!fileExists(resolved))
+                continue;
+            let content;
+            let importedAst;
+            try {
+                content = fs.readFileSync(resolved, 'utf-8');
+                importedAst = parseSolidityContent(content);
+            }
+            catch (_e) {
+                continue;
+            }
+            seen.add(resolved);
+            out.push({ path: resolved, ast: importedAst, source: content });
+            queue.push({ canonical: resolved, ast: importedAst });
+        }
+    }
+    return out;
+}
+/**
+ * Compute a project root for SemanticModel from the input file list.
+ * Spec proposes nearest-ancestor-with-.git common ancestor;
+ * for Slice 2a we use the common-ancestor directory of the input files,
+ * which works for the typical scanFiles(['/proj/A.sol', '/proj/B.sol'])
+ * shape used by tests and CLI. The richer policy (config-file probing)
+ * is a Slice 2b CLI-side concern -- see the spec's open question 1.
+ */
+function computeProjectRootFromFiles(files) {
+    if (!files || files.length === 0)
+        return process.cwd();
+    if (files.length === 1)
+        return path.dirname(path.resolve(files[0]));
+    const absDirs = files.map(f => path.dirname(path.resolve(f)));
+    // Common-prefix of paths.
+    let common = absDirs[0];
+    for (const d of absDirs.slice(1)) {
+        while (!d.startsWith(common + path.sep) && d !== common) {
+            const parent = path.dirname(common);
+            if (parent === common)
+                return common; // reached root
+            common = parent;
+        }
+    }
+    return common;
+}
+//# sourceMappingURL=scan.js.map

package/dist/semantic/contracts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build a ContractInfo from a `ContractDefinition` AST node. Pure
+ * AST inspection — no symbol resolution, no inheritance graph, no
+ * cross-file work. `imports.ts` handles cross-file symbol mapping;
+ * `inheritance.ts` handles MRO computation; this file is the seam
+ * between `@solidity-parser/parser` and the rest of SemanticModel.
+ */
+import type { ContractInfo, ContractId, SourcePath } from './types';
+export declare function makeContractId(sourcePath: SourcePath, name: string): ContractId;
+export declare function buildContractInfo(sourcePath: SourcePath, contractNode: any): ContractInfo;