agent-cfml-check 0.1.0

package/dist/core/lexer.js

@@ -0,0 +1,388 @@
+import { SourceIndex } from "./source-index.js";
+import { ToolFailure } from "../schema/errors.js";
+export const PAIRED_TAGS = new Set([
+    "cfif",
+    "cfloop",
+    "cfoutput",
+    "cfquery",
+    "cfsavecontent",
+    "cfsilent",
+    "cfcomponent",
+    "cffunction",
+    "cfscript",
+]);
+export const BRANCH_TAGS = new Set(["cfelseif", "cfelse"]);
+export const BODYLESS_TAGS = new Set(["cfset", "cfreturn", "cfinclude", "cfargument", "cfqueryparam"]);
+function isNameCharacter(character) {
+    return character !== undefined && /[A-Za-z0-9_:-]/u.test(character);
+}
+function startsCfTag(source, index) {
+    const afterSlash = source[index + 1] === "/" ? index + 2 : index + 1;
+    return source.slice(afterSlash, afterSlash + 2).toLowerCase() === "cf" && isNameCharacter(source[afterSlash + 2]);
+}
+function consumeCfmlComment(source, start) {
+    let depth = 1;
+    let cursor = start + 5;
+    while (cursor < source.length) {
+        if (source.startsWith("<!---", cursor)) {
+            depth += 1;
+            cursor += 5;
+            continue;
+        }
+        if (source.startsWith("--->", cursor)) {
+            depth -= 1;
+            cursor += 4;
+            if (depth === 0)
+                return cursor;
+            continue;
+        }
+        cursor += 1;
+    }
+    return null;
+}
+function parseTag(source, start) {
+    const closing = source[start + 1] === "/";
+    let cursor = closing ? start + 2 : start + 1;
+    const nameStart = cursor;
+    while (isNameCharacter(source[cursor]))
+        cursor += 1;
+    const name = source.slice(nameStart, cursor).toLowerCase();
+    if (!name.startsWith("cf"))
+        return { error: "NOT_CF_TAG", at: start };
+    let quote = null;
+    while (cursor < source.length) {
+        const character = source[cursor];
+        if (quote !== null) {
+            if (character === "\\") {
+                cursor += 2;
+                continue;
+            }
+            if (character === quote) {
+                if (source[cursor + 1] === quote) {
+                    cursor += 2;
+                    continue;
+                }
+                quote = null;
+            }
+            cursor += 1;
+            continue;
+        }
+        if (character === "\"" || character === "'") {
+            quote = character;
+            cursor += 1;
+            continue;
+        }
+        if (source.startsWith("<!---", cursor)) {
+            const commentEnd = consumeCfmlComment(source, cursor);
+            if (commentEnd === null)
+                return { error: "UNTERMINATED_COMMENT", at: cursor };
+            cursor = commentEnd;
+            continue;
+        }
+        if (character === ">") {
+            let beforeEnd = cursor - 1;
+            while (beforeEnd >= start && /\s/u.test(source[beforeEnd] ?? ""))
+                beforeEnd -= 1;
+            const selfClosing = source[beforeEnd] === "/";
+            const kind = closing
+                ? "close"
+                : BRANCH_TAGS.has(name)
+                    ? "branch"
+                    : BODYLESS_TAGS.has(name)
+                        ? "bodyless"
+                        : PAIRED_TAGS.has(name)
+                            ? "open"
+                            : "unknown";
+            return { token: { kind, name, start, end: cursor + 1, self_closing: selfClosing }, next: cursor + 1 };
+        }
+        cursor += 1;
+    }
+    if (quote !== null)
+        return { error: "UNTERMINATED_STRING", at: cursor };
+    return { error: "UNTERMINATED_TAG", at: start };
+}
+function addFinding(context, findings, finding) {
+    if (findings.length >= context.max_findings) {
+        throw new ToolFailure("LIMIT_EXCEEDED", "The findings limit was reached; no partial success is returned", 3);
+    }
+    findings.push(finding);
+}
+function related(index, tag) {
+    return tag === undefined ? null : index.location(tag.start, tag.end);
+}
+function finding(context, code, message, start, end, open) {
+    return { code, message, location: context.index.location(start, end), related_open: related(context.index, open) };
+}
+function checkDeadline(context, cursor) {
+    if ((cursor & 255) === 0 && Date.now() > context.deadline) {
+        throw new ToolFailure("LIMIT_EXCEEDED", "The processing time limit was reached; no partial success is returned", 3);
+    }
+}
+function scanScriptDelimiters(context, start, end, findings) {
+    const stack = [];
+    let quote = null;
+    let blockCommentStart = null;
+    let cursor = start;
+    while (cursor < end) {
+        checkDeadline(context, cursor);
+        const character = context.source[cursor];
+        if (quote !== null) {
+            if (character === "\\") {
+                cursor += 2;
+                continue;
+            }
+            if (character === quote) {
+                if (context.source[cursor + 1] === quote) {
+                    cursor += 2;
+                    continue;
+                }
+                quote = null;
+            }
+            cursor += 1;
+            continue;
+        }
+        if (blockCommentStart !== null) {
+            if (context.source.startsWith("*/", cursor)) {
+                blockCommentStart = null;
+                cursor += 2;
+            }
+            else
+                cursor += 1;
+            continue;
+        }
+        if (context.source.startsWith("//", cursor)) {
+            cursor += 2;
+            while (cursor < end && context.source[cursor] !== "\n" && context.source[cursor] !== "\r")
+                cursor += 1;
+            continue;
+        }
+        if (context.source.startsWith("/*", cursor)) {
+            blockCommentStart = cursor;
+            cursor += 2;
+            continue;
+        }
+        if (character === "\"" || character === "'") {
+            quote = character;
+            cursor += 1;
+            continue;
+        }
+        if (character === "(" || character === "[" || character === "{") {
+            if (stack.length >= context.max_nesting) {
+                throw new ToolFailure("LIMIT_EXCEEDED", "The nesting limit was reached; no partial success is returned", 3);
+            }
+            stack.push({ character, start: cursor });
+            cursor += 1;
+            continue;
+        }
+        if (character === ")" || character === "]" || character === "}") {
+            const expected = character === ")" ? "(" : character === "]" ? "[" : "{";
+            const open = stack[stack.length - 1];
+            if (open?.character !== expected) {
+                addFinding(context, findings, finding(context, "UNBALANCED_DELIMITER", `Unmatched CFScript delimiter "${character}"`, cursor, cursor + 1));
+            }
+            else {
+                stack.pop();
+            }
+        }
+        cursor += 1;
+    }
+    if (quote !== null) {
+        addFinding(context, findings, finding(context, "UNTERMINATED_STRING", "Unterminated CFScript string", end, end));
+    }
+    if (blockCommentStart !== null) {
+        addFinding(context, findings, finding(context, "UNTERMINATED_COMMENT", "Unterminated CFScript block comment", blockCommentStart, end));
+    }
+    for (const open of stack) {
+        addFinding(context, findings, finding(context, "UNBALANCED_DELIMITER", `Unclosed CFScript delimiter "${open.character}"`, open.start, open.start + 1));
+    }
+}
+function scanScriptRegion(context, start) {
+    let quote = null;
+    let blockCommentStart = null;
+    let cursor = start;
+    while (cursor < context.source.length) {
+        checkDeadline(context, cursor);
+        const character = context.source[cursor];
+        if (quote !== null) {
+            if (character === "\\") {
+                cursor += 2;
+                continue;
+            }
+            if (character === quote) {
+                if (context.source[cursor + 1] === quote)
+                    cursor += 2;
+                else {
+                    quote = null;
+                    cursor += 1;
+                }
+                continue;
+            }
+            cursor += 1;
+            continue;
+        }
+        if (blockCommentStart !== null) {
+            if (context.source.startsWith("*/", cursor)) {
+                blockCommentStart = null;
+                cursor += 2;
+            }
+            else
+                cursor += 1;
+            continue;
+        }
+        if (context.source.startsWith("//", cursor)) {
+            cursor += 2;
+            while (cursor < context.source.length && context.source[cursor] !== "\n" && context.source[cursor] !== "\r")
+                cursor += 1;
+            continue;
+        }
+        if (context.source.startsWith("/*", cursor)) {
+            blockCommentStart = cursor;
+            cursor += 2;
+            continue;
+        }
+        if (character === "\"" || character === "'") {
+            quote = character;
+            cursor += 1;
+            continue;
+        }
+        if (startsCfTag(context.source, cursor)) {
+            const parsed = parseTag(context.source, cursor);
+            if ("error" in parsed)
+                return { close: null, content_end: cursor, incomplete: { code: parsed.error, message: `CFScript region cannot be parsed (${parsed.error})` } };
+            if (parsed.token.name === "cfscript" && parsed.token.kind === "close") {
+                return { close: parsed.token, content_end: cursor };
+            }
+            return { close: null, content_end: cursor, incomplete: { code: "UNSUPPORTED_SYNTAX", message: "CFML tag island inside cfscript is outside the supported profile" } };
+        }
+        cursor += 1;
+    }
+    if (quote !== null)
+        return { close: null, content_end: context.source.length, incomplete: { code: "UNTERMINATED_STRING", message: "Unterminated CFScript string" } };
+    if (blockCommentStart !== null)
+        return { close: null, content_end: context.source.length, incomplete: { code: "UNTERMINATED_COMMENT", message: "Unterminated CFScript block comment" } };
+    return { close: null, content_end: context.source.length, incomplete: { code: "UNTERMINATED_TAG", message: "cfscript has no closing tag" } };
+}
+function processTag(context, token, stack, findings) {
+    if (token.kind === "unknown") {
+        throw new ToolFailure("UNSUPPORTED_SYNTAX", `Unsupported CFML tag "${token.name}"`, 3);
+    }
+    if (token.kind === "bodyless") {
+        return;
+    }
+    if (token.kind === "branch") {
+        const current = stack[stack.length - 1];
+        if (current?.name !== "cfif") {
+            addFinding(context, findings, finding(context, "INVALID_BRANCH", `${token.name} must belong to the directly open cfif`, token.start, token.end));
+            return;
+        }
+        if (token.name === "cfelse") {
+            if (current.branch_else_seen) {
+                addFinding(context, findings, finding(context, "INVALID_BRANCH", "cfif cannot contain more than one cfelse", token.start, token.end, current));
+            }
+            current.branch_else_seen = true;
+        }
+        else if (current.branch_else_seen) {
+            addFinding(context, findings, finding(context, "INVALID_BRANCH", "cfelseif cannot appear after cfelse", token.start, token.end, current));
+        }
+        return;
+    }
+    if (token.kind === "open") {
+        if (token.self_closing)
+            throw new ToolFailure("UNSUPPORTED_SYNTAX", `Paired tag "${token.name}" cannot be self-closing`, 3);
+        if (stack.length >= context.max_nesting)
+            throw new ToolFailure("LIMIT_EXCEEDED", "The tag nesting limit was reached; no partial success is returned", 3);
+        stack.push({ name: token.name, start: token.start, end: token.end, branch_else_seen: false });
+        return;
+    }
+    if (token.name === "cfscript" && stack[stack.length - 1]?.name !== "cfscript") {
+        addFinding(context, findings, finding(context, "UNEXPECTED_CLOSE", "Closing cfscript has no directly open cfscript", token.start, token.end));
+        return;
+    }
+    if (BODYLESS_TAGS.has(token.name)) {
+        throw new ToolFailure("UNSUPPORTED_SYNTAX", `Bodyless tag "${token.name}" cannot have a closing tag`, 3);
+    }
+    const current = stack[stack.length - 1];
+    if (current === undefined) {
+        addFinding(context, findings, finding(context, "UNEXPECTED_CLOSE", `Unexpected closing tag "${token.name}"`, token.start, token.end));
+        return;
+    }
+    if (current.name !== token.name) {
+        addFinding(context, findings, finding(context, "MISMATCHED_CLOSE", `Closing tag "${token.name}" does not match open "${current.name}"`, token.start, token.end, current));
+        return;
+    }
+    stack.pop();
+}
+export function scanCfml(source, limits) {
+    const index = new SourceIndex(source);
+    const context = { source, index, deadline: Date.now() + limits.time_limit_ms, max_nesting: limits.max_nesting, max_findings: limits.max_findings };
+    const findings = [];
+    const incomplete = [];
+    const script_regions = [];
+    const stack = [];
+    let saw_cfml_tag = false;
+    let cursor = 0;
+    while (cursor < source.length) {
+        checkDeadline(context, cursor);
+        if (source.startsWith("<!---", cursor)) {
+            const end = consumeCfmlComment(source, cursor);
+            if (end === null) {
+                incomplete.push({ code: "UNTERMINATED_COMMENT", message: `Unterminated CFML comment at line ${index.position(cursor).line}, column ${index.position(cursor).column}` });
+                break;
+            }
+            cursor = end;
+            continue;
+        }
+        if (source[cursor] !== "<" || !startsCfTag(source, cursor)) {
+            cursor += 1;
+            continue;
+        }
+        saw_cfml_tag = true;
+        const parsed = parseTag(source, cursor);
+        if ("error" in parsed) {
+            incomplete.push({ code: parsed.error, message: `CFML tag cannot be parsed (${parsed.error}) at line ${index.position(parsed.at).line}, column ${index.position(parsed.at).column}` });
+            break;
+        }
+        const token = parsed.token;
+        if (token.kind === "open" && token.name === "cfscript") {
+            processTag(context, token, stack, findings);
+            const script = scanScriptRegion(context, token.end);
+            scanScriptDelimiters(context, token.end, script.content_end, findings);
+            script_regions.push({ content_start: token.end, content_end: script.content_end });
+            if (script.incomplete !== undefined) {
+                incomplete.push({ code: script.incomplete.code, message: `${script.incomplete.message} at line ${index.position(script.content_end).line}, column ${index.position(script.content_end).column}` });
+                break;
+            }
+            if (script.close !== null) {
+                processTag(context, script.close, stack, findings);
+                cursor = script.close.end;
+                continue;
+            }
+        }
+        processTag(context, token, stack, findings);
+        cursor = parsed.next;
+    }
+    for (const open of stack.reverse()) {
+        addFinding(context, findings, finding(context, "UNCLOSED_TAG", `Unclosed CFML tag "${open.name}"`, open.start, open.end, open));
+    }
+    findings.sort((left, right) => left.location.start_byte - right.location.start_byte || left.code.localeCompare(right.code));
+    return { findings, incomplete, script_regions, saw_cfml_tag };
+}
+export function checkPureScriptCfc(source, extension, limits) {
+    const leading = source.replace(/^\uFEFF/u, "").trimStart();
+    const pureScript = extension.toLowerCase() === ".cfc" && /^(?:component|interface)\b/iu.test(leading);
+    if (pureScript) {
+        const result = { findings: [], incomplete: [], script_regions: [], saw_cfml_tag: false };
+        const index = new SourceIndex(source);
+        const context = { source, index, deadline: Date.now() + limits.time_limit_ms, max_nesting: limits.max_nesting, max_findings: limits.max_findings };
+        scanScriptDelimiters(context, 0, source.length, result.findings);
+        result.findings.sort((left, right) => left.location.start_byte - right.location.start_byte || left.code.localeCompare(right.code));
+        return result;
+    }
+    const result = scanCfml(source, limits);
+    if (extension.toLowerCase() !== ".cfc" || result.saw_cfml_tag)
+        return result;
+    if (!pureScript) {
+        result.incomplete.push({ code: "UNSUPPORTED_SYNTAX", message: "The .cfc source does not use a recognized pure-script component entry mode" });
+    }
+    return result;
+}

package/dist/core/limits.d.ts

@@ -0,0 +1,4 @@
+import type { CheckLimits } from "../schema/types.js";
+export declare const DEFAULT_LIMITS: CheckLimits;
+export declare const HARD_LIMITS: CheckLimits;
+export declare function normalizeLimits(requested: Partial<CheckLimits> | undefined): CheckLimits;

package/dist/core/limits.js

@@ -0,0 +1,32 @@
+import { ToolFailure } from "../schema/errors.js";
+export const DEFAULT_LIMITS = {
+    max_source_bytes: 2 * 1024 * 1024,
+    max_nesting: 256,
+    max_findings: 100,
+    max_output_bytes: 64 * 1024,
+    time_limit_ms: 5_000,
+};
+export const HARD_LIMITS = {
+    max_source_bytes: 16 * 1024 * 1024,
+    max_nesting: 1_024,
+    max_findings: 1_000,
+    max_output_bytes: 1024 * 1024,
+    time_limit_ms: 30_000,
+};
+function positiveInteger(value, name) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new ToolFailure("INVALID_LIMIT", `${name} must be a positive integer`, 2);
+    }
+    return value;
+}
+export function normalizeLimits(requested) {
+    const values = { ...DEFAULT_LIMITS, ...(requested ?? {}) };
+    for (const key of Object.keys(DEFAULT_LIMITS)) {
+        const value = positiveInteger(values[key], key);
+        if (value > HARD_LIMITS[key]) {
+            throw new ToolFailure("INVALID_LIMIT", `${key} exceeds the hard cap of ${HARD_LIMITS[key]}`, 2);
+        }
+        values[key] = value;
+    }
+    return values;
+}

package/dist/core/source-index.d.ts

@@ -0,0 +1,10 @@
+import type { Position, SourceLocation } from "../schema/types.js";
+export declare class SourceIndex {
+    readonly source: string;
+    private readonly byteOffsets;
+    private readonly lineStarts;
+    constructor(source: string);
+    byteOffset(index: number): number;
+    position(index: number): Position;
+    location(start: number, end: number): SourceLocation;
+}

package/dist/core/source-index.js

@@ -0,0 +1,63 @@
+import { TextEncoder } from "node:util";
+export class SourceIndex {
+    source;
+    byteOffsets;
+    lineStarts = [0];
+    constructor(source) {
+        this.source = source;
+        this.byteOffsets = new Uint32Array(source.length + 1);
+        const encoder = new TextEncoder();
+        let byteOffset = 0;
+        for (let index = 0; index < source.length;) {
+            this.byteOffsets[index] = byteOffset;
+            const codePoint = source.codePointAt(index);
+            if (codePoint === undefined)
+                break;
+            const width = codePoint > 0xffff ? 2 : 1;
+            const character = source.slice(index, index + width);
+            const byteLength = encoder.encode(character).byteLength;
+            if (width === 2)
+                this.byteOffsets[index + 1] = byteOffset;
+            byteOffset += byteLength;
+            index += width;
+            this.byteOffsets[index] = byteOffset;
+            if (character === "\n")
+                this.lineStarts.push(index);
+        }
+    }
+    byteOffset(index) {
+        const safe = Math.max(0, Math.min(index, this.source.length));
+        return this.byteOffsets[safe] ?? 0;
+    }
+    position(index) {
+        const safe = Math.max(0, Math.min(index, this.source.length));
+        let low = 0;
+        let high = this.lineStarts.length - 1;
+        while (low <= high) {
+            const middle = Math.floor((low + high) / 2);
+            const start = this.lineStarts[middle] ?? 0;
+            if (start <= safe)
+                low = middle + 1;
+            else
+                high = middle - 1;
+        }
+        const lineStart = this.lineStarts[Math.max(0, high)] ?? 0;
+        let column = 1;
+        for (let cursor = lineStart; cursor < safe;) {
+            const codePoint = this.source.codePointAt(cursor);
+            if (codePoint === undefined)
+                break;
+            cursor += codePoint > 0xffff ? 2 : 1;
+            column += 1;
+        }
+        return { line: Math.max(1, high + 1), column };
+    }
+    location(start, end) {
+        return {
+            start: this.position(start),
+            end: this.position(end),
+            start_byte: this.byteOffset(start),
+            end_byte: this.byteOffset(end),
+        };
+    }
+}

package/dist/core/source-reader.d.ts

@@ -0,0 +1,6 @@
+import type { CheckLimits, LoadedSource } from "../schema/types.js";
+export declare function loadSource(options: {
+    root: string;
+    file: string;
+    limits: CheckLimits;
+}): LoadedSource;

package/dist/core/source-reader.js

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+import { ToolFailure } from "../schema/errors.js";
+function escapesRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative.startsWith("..") || path.isAbsolute(relative);
+}
+export function loadSource(options) {
+    if (!/\.(?:cfm|cfc)$/iu.test(options.file)) {
+        throw new ToolFailure("UNSUPPORTED_EXTENSION", "Only .cfm and .cfc files are supported", 2);
+    }
+    const cwd = process.cwd();
+    const rootPath = path.isAbsolute(options.root) ? options.root : path.resolve(cwd, options.root);
+    const requestedPath = path.isAbsolute(options.file) ? options.file : path.resolve(cwd, options.file);
+    if (escapesRoot(rootPath, requestedPath)) {
+        throw new ToolFailure("FILE_OUTSIDE_ROOT", "The selected file resolves outside the explicit root", 4);
+    }
+    if (!existsSync(rootPath))
+        throw new ToolFailure("ROOT_NOT_FOUND", "The explicit root does not exist", 4);
+    if (!existsSync(requestedPath))
+        throw new ToolFailure("FILE_NOT_FOUND", "The selected file does not exist", 2);
+    let realRoot;
+    let resolvedPath;
+    try {
+        realRoot = realpathSync(rootPath);
+        resolvedPath = realpathSync(requestedPath);
+    }
+    catch {
+        throw new ToolFailure("PATH_UNRESOLVED", "The root or file could not be resolved", 4);
+    }
+    if (escapesRoot(realRoot, resolvedPath)) {
+        throw new ToolFailure("FILE_OUTSIDE_ROOT", "The selected file resolves outside the explicit root", 4);
+    }
+    const before = statSync(resolvedPath);
+    if (!before.isFile())
+        throw new ToolFailure("FILE_NOT_FOUND", "The selected path is not a regular file", 2);
+    if (before.size > options.limits.max_source_bytes) {
+        throw new ToolFailure("LIMIT_EXCEEDED", `Source exceeds the ${options.limits.max_source_bytes}-byte limit`, 3);
+    }
+    const bytes = readFileSync(resolvedPath);
+    const after = statSync(resolvedPath);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+        throw new ToolFailure("SOURCE_CHANGED", "The source changed while it was being read", 3);
+    }
+    if (bytes.byteLength > options.limits.max_source_bytes) {
+        throw new ToolFailure("LIMIT_EXCEEDED", `Source exceeds the ${options.limits.max_source_bytes}-byte limit`, 3);
+    }
+    if (bytes.includes(0))
+        throw new ToolFailure("BINARY_INPUT", "Binary or NUL-containing input is not supported", 2);
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new ToolFailure("ENCODING_UNSUPPORTED", "Source must be valid UTF-8", 2);
+    }
+    const relativePath = path.relative(realRoot, resolvedPath).split(path.sep).join("/");
+    return {
+        requested_path: options.file,
+        resolved_path: resolvedPath,
+        relative_path: relativePath,
+        source,
+        bytes,
+        bom: source.startsWith("\uFEFF"),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { capabilities, checkFile } from "./core/checker.js";
+export { DEFAULT_LIMITS, HARD_LIMITS, normalizeLimits } from "./core/limits.js";
+export type * from "./schema/types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { capabilities, checkFile } from "./core/checker.js";
+export { DEFAULT_LIMITS, HARD_LIMITS, normalizeLimits } from "./core/limits.js";

package/dist/schema/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class ToolFailure extends Error {
+    readonly code: string;
+    readonly exitCode: 1 | 2 | 3 | 4;
+    constructor(code: string, message: string, exitCode: 1 | 2 | 3 | 4);
+}

package/dist/schema/errors.js

@@ -0,0 +1,10 @@
+export class ToolFailure extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.name = "ToolFailure";
+    }
+}