agent-cfml-check 0.1.0

package/dist/schema/types.d.ts

@@ -0,0 +1,93 @@
+export declare const TOOL_ID: "agent-cfml-check";
+export declare const TOOL_VERSION: "0.1.0";
+export declare const PROFILE_ID: "cfml-structure-v1";
+export interface Position {
+    line: number;
+    column: number;
+}
+export interface SourceLocation {
+    start: Position;
+    end: Position;
+    start_byte: number;
+    end_byte: number;
+}
+export interface Finding {
+    code: "UNEXPECTED_CLOSE" | "MISMATCHED_CLOSE" | "UNCLOSED_TAG" | "INVALID_BRANCH" | "UNTERMINATED_STRING" | "UNTERMINATED_COMMENT" | "UNBALANCED_DELIMITER";
+    message: string;
+    location: SourceLocation;
+    related_open: SourceLocation | null;
+}
+export interface SourceInfo {
+    path: string;
+    sha256: string;
+    byte_size: number;
+    encoding: "utf-8";
+    bom: boolean;
+}
+export interface CheckData {
+    profile: typeof PROFILE_ID;
+    source: SourceInfo;
+    verdict: "pass" | "violations";
+    checks: string[];
+    exclusions: string[];
+    findings: Finding[];
+}
+export interface EnvelopeError {
+    code: string;
+    message: string;
+}
+export interface EnvelopeMeta {
+    scope: string;
+    limits: {
+        max_source_bytes: number;
+        max_nesting: number;
+        max_findings: number;
+        max_output_bytes: number;
+        time_limit_ms: number;
+    };
+}
+export interface Envelope<T> {
+    schema_version: "1.0.0";
+    tool: {
+        id: typeof TOOL_ID;
+        version: typeof TOOL_VERSION;
+    };
+    status: "ok" | "incomplete" | "error";
+    complete: boolean;
+    data: T | null;
+    errors: EnvelopeError[];
+    warnings: EnvelopeError[];
+    meta: EnvelopeMeta;
+}
+export interface CheckLimits {
+    max_source_bytes: number;
+    max_nesting: number;
+    max_findings: number;
+    max_output_bytes: number;
+    time_limit_ms: number;
+}
+export interface CheckOptions {
+    root: string;
+    file: string;
+    limits?: Partial<CheckLimits>;
+}
+export interface LoadedSource {
+    requested_path: string;
+    resolved_path: string;
+    relative_path: string;
+    source: string;
+    bytes: Buffer;
+    bom: boolean;
+}
+export interface CapabilitiesData {
+    profile: typeof PROFILE_ID;
+    operations: string[];
+    extensions: string[];
+    supported_tags: {
+        paired_bodies: string[];
+        branches: string[];
+        bodyless: string[];
+    };
+    limits: CheckLimits;
+    exclusions: string[];
+}

package/dist/schema/types.js

@@ -0,0 +1,3 @@
+export const TOOL_ID = "agent-cfml-check";
+export const TOOL_VERSION = "0.1.0";
+export const PROFILE_ID = "cfml-structure-v1";

package/fixtures/misnested.cfm

@@ -0,0 +1,4 @@
+<cfif enabled>
+  <cfloop array="#items#">
+</cfif>
+</cfloop>

package/fixtures/valid.cfm

@@ -0,0 +1,3 @@
+<cfif enabled>
+  <cfoutput>#message#</cfoutput>
+</cfif>

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agent-cfml-check",
+  "version": "0.1.0",
+  "description": "Deterministic, read-only structural checks for a bounded CFML subset.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "bin": {
+    "agent-cfml-check": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SPEC.md",
+    "schema",
+    "fixtures"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test .test-dist/test/check.test.js .test-dist/test/cli.test.js",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}

package/schema/agent-cfml-check-result-v1.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:agent-cfml-check:result-v1",
+  "title": "Agent CFML Check Result",
+  "type": "object",
+  "required": ["schema_version", "tool", "status", "complete", "data", "errors", "warnings", "meta"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "tool": {
+      "type": "object",
+      "required": ["id", "version"],
+      "properties": {
+        "id": { "const": "agent-cfml-check" },
+        "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" }
+      },
+      "additionalProperties": false
+    },
+    "status": { "enum": ["ok", "incomplete", "error"] },
+    "complete": { "type": "boolean" },
+    "data": {
+      "anyOf": [
+        { "$ref": "#/$defs/check_data" },
+        { "$ref": "#/$defs/capabilities_data" },
+        { "type": "null" }
+      ]
+    },
+    "errors": { "type": "array", "items": { "$ref": "#/$defs/message" } },
+    "warnings": { "type": "array", "items": { "$ref": "#/$defs/message" } },
+    "meta": { "$ref": "#/$defs/meta" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "ok" } } },
+      "then": { "properties": { "complete": { "const": true }, "errors": { "maxItems": 0 }, "data": { "not": { "type": "null" } } } }
+    },
+    {
+      "if": { "properties": { "status": { "enum": ["incomplete", "error"] } } },
+      "then": { "properties": { "complete": { "const": false }, "data": { "type": "null" }, "errors": { "minItems": 1 } } }
+    }
+  ],
+  "$defs": {
+    "message": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": { "code": { "type": "string" }, "message": { "type": "string" } },
+      "additionalProperties": false
+    },
+    "position": {
+      "type": "object",
+      "required": ["line", "column"],
+      "properties": { "line": { "type": "integer", "minimum": 1 }, "column": { "type": "integer", "minimum": 1 } },
+      "additionalProperties": false
+    },
+    "location": {
+      "type": "object",
+      "required": ["start", "end", "start_byte", "end_byte"],
+      "properties": {
+        "start": { "$ref": "#/$defs/position" },
+        "end": { "$ref": "#/$defs/position" },
+        "start_byte": { "type": "integer", "minimum": 0 },
+        "end_byte": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "finding": {
+      "type": "object",
+      "required": ["code", "message", "location", "related_open"],
+      "properties": {
+        "code": { "type": "string" },
+        "message": { "type": "string" },
+        "location": { "$ref": "#/$defs/location" },
+        "related_open": { "anyOf": [{ "$ref": "#/$defs/location" }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "source": {
+      "type": "object",
+      "required": ["path", "sha256", "byte_size", "encoding", "bom"],
+      "properties": {
+        "path": { "type": "string" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "byte_size": { "type": "integer", "minimum": 0 },
+        "encoding": { "const": "utf-8" },
+        "bom": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "check_data": {
+      "type": "object",
+      "required": ["profile", "source", "verdict", "checks", "exclusions", "findings"],
+      "properties": {
+        "profile": { "const": "cfml-structure-v1" },
+        "source": { "$ref": "#/$defs/source" },
+        "verdict": { "enum": ["pass", "violations"] },
+        "checks": { "type": "array", "items": { "type": "string" } },
+        "exclusions": { "type": "array", "items": { "type": "string" } },
+        "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } }
+      },
+      "additionalProperties": false
+    },
+    "capabilities_data": {
+      "type": "object",
+      "required": ["profile", "operations", "extensions", "supported_tags", "limits", "exclusions"],
+      "properties": {
+        "profile": { "const": "cfml-structure-v1" },
+        "operations": { "type": "array", "items": { "type": "string" } },
+        "extensions": { "type": "array", "items": { "type": "string" } },
+        "supported_tags": { "type": "object" },
+        "limits": { "$ref": "#/$defs/limits" },
+        "exclusions": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "limits": {
+      "type": "object",
+      "required": ["max_source_bytes", "max_nesting", "max_findings", "max_output_bytes", "time_limit_ms"],
+      "properties": {
+        "max_source_bytes": { "type": "integer", "minimum": 1 },
+        "max_nesting": { "type": "integer", "minimum": 1 },
+        "max_findings": { "type": "integer", "minimum": 1 },
+        "max_output_bytes": { "type": "integer", "minimum": 1 },
+        "time_limit_ms": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "meta": {
+      "type": "object",
+      "required": ["scope", "limits"],
+      "properties": { "scope": { "type": "string" }, "limits": { "$ref": "#/$defs/limits" } },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}