nginx-lint-plugin 0.0.1 → 0.8.3

package/wit/nginx-lint-plugin.wit

@@ -0,0 +1,281 @@
+package nginx-lint:plugin@3.0.0;
+
+interface types {
+    enum severity {
+        error,
+        warning,
+    }
+
+    record fix {
+        line: u32,
+        old-text: option<string>,
+        new-text: string,
+        delete-line: bool,
+        insert-after: bool,
+        start-offset: option<u32>,
+        end-offset: option<u32>,
+    }
+
+    record lint-error {
+        rule: string,
+        category: string,
+        message: string,
+        severity: severity,
+        line: option<u32>,
+        column: option<u32>,
+        fixes: list<fix>,
+    }
+
+    record plugin-spec {
+        name: string,
+        category: string,
+        description: string,
+        api-version: string,
+        severity: option<string>,
+        why: option<string>,
+        bad-example: option<string>,
+        good-example: option<string>,
+        references: option<list<string>>,
+    }
+}
+
+/// Shared data types used by both the plugin config-api (resource-based)
+/// and the parser output (record-based).
+interface data-types {
+    /// Argument value type
+    enum argument-type {
+        literal,
+        quoted-string,
+        single-quoted-string,
+        variable,
+    }
+
+    /// Argument data (returned as a record since it's small)
+    record argument-info {
+        value: string,
+        raw: string,
+        arg-type: argument-type,
+        line: u32,
+        column: u32,
+        start-offset: u32,
+        end-offset: u32,
+    }
+
+    /// Comment data
+    record comment-info {
+        text: string,
+        line: u32,
+        column: u32,
+        leading-whitespace: string,
+        trailing-whitespace: string,
+        start-offset: u32,
+        end-offset: u32,
+    }
+
+    /// Blank line data
+    record blank-line-info {
+        line: u32,
+        content: string,
+        start-offset: u32,
+    }
+
+    /// All flat properties of a directive (for bulk retrieval)
+    record directive-data {
+        name: string,
+        args: list<argument-info>,
+        line: u32,
+        column: u32,
+        start-offset: u32,
+        end-offset: u32,
+        end-line: u32,
+        end-column: u32,
+        leading-whitespace: string,
+        trailing-whitespace: string,
+        space-before-terminator: string,
+        has-block: bool,
+        block-is-raw: bool,
+        /// Actual raw content for raw blocks (e.g., lua code); none if not a raw block
+        block-raw-content: option<string>,
+        /// Leading whitespace before the closing brace; none if no block
+        closing-brace-leading-whitespace: option<string>,
+        /// Trailing whitespace after the closing brace; none if no block
+        block-trailing-whitespace: option<string>,
+        /// Text of the trailing comment on the directive line; none if no comment
+        trailing-comment-text: option<string>,
+        /// End column of the name token (1-based)
+        name-end-column: u32,
+        /// End byte offset of the name token (0-based)
+        name-end-offset: u32,
+        /// Start line of the block's opening brace (1-based); none if no block
+        block-start-line: option<u32>,
+        /// Start column of the block's opening brace (1-based); none if no block
+        block-start-column: option<u32>,
+        /// Start byte offset of the block's opening brace (0-based); none if no block
+        block-start-offset: option<u32>,
+    }
+}
+
+interface config-api {
+    use types.{fix};
+    use data-types.{argument-type, argument-info, comment-info, blank-line-info, directive-data};
+
+    /// A config item (directive, comment, or blank line)
+    variant config-item {
+        directive-item(directive),
+        comment-item(comment-info),
+        blank-line-item(blank-line-info),
+    }
+
+    /// A directive paired with its parent block context
+    record directive-context {
+        directive: directive,
+        parent-stack: list<string>,
+        depth: u32,
+    }
+
+    /// An nginx directive (resource backed by host data)
+    resource directive {
+        /// Get all flat properties in a single call (optimized for reconstruction)
+        data: func() -> directive-data;
+        /// Get the directive name
+        name: func() -> string;
+        /// Check if the directive has the given name
+        is: func(name: string) -> bool;
+
+        /// Get the first argument value
+        first-arg: func() -> option<string>;
+        /// Check if the first argument equals the given value
+        first-arg-is: func(value: string) -> bool;
+        /// Get the argument at the given index
+        arg-at: func(index: u32) -> option<string>;
+        /// Get the last argument value
+        last-arg: func() -> option<string>;
+        /// Check if any argument equals the given value
+        has-arg: func(value: string) -> bool;
+        /// Return the number of arguments
+        arg-count: func() -> u32;
+        /// Get all arguments as records
+        args: func() -> list<argument-info>;
+
+        /// Get the start line number (1-based)
+        line: func() -> u32;
+        /// Get the start column number (1-based)
+        column: func() -> u32;
+        /// Get the start byte offset (0-based)
+        start-offset: func() -> u32;
+        /// Get the end byte offset (0-based)
+        end-offset: func() -> u32;
+        /// Get the leading whitespace before the directive
+        leading-whitespace: func() -> string;
+        /// Get the trailing whitespace after the directive
+        trailing-whitespace: func() -> string;
+        /// Get the space before the terminator (; or {)
+        space-before-terminator: func() -> string;
+
+        /// Check if the directive has a block
+        has-block: func() -> bool;
+        /// Get the items inside the directive's block
+        block-items: func() -> list<config-item>;
+        /// Check if the block contains raw content (e.g., lua blocks)
+        block-is-raw: func() -> bool;
+
+        /// Create a fix that replaces this directive with new text
+        replace-with: func(new-text: string) -> fix;
+        /// Create a fix that deletes this directive's line
+        delete-line-fix: func() -> fix;
+        /// Create a fix that inserts a new line after this directive
+        insert-after: func(new-text: string) -> fix;
+        /// Create a fix that inserts a new line before this directive
+        insert-before: func(new-text: string) -> fix;
+        /// Create a fix that inserts multiple lines after this directive
+        insert-after-many: func(lines: list<string>) -> fix;
+        /// Create a fix that inserts multiple lines before this directive
+        insert-before-many: func(lines: list<string>) -> fix;
+    }
+
+    /// The parsed nginx configuration (resource backed by host data)
+    resource config {
+        /// Iterate over all directives recursively with parent context
+        all-directives-with-context: func() -> list<directive-context>;
+        /// Iterate over all directives recursively
+        all-directives: func() -> list<directive>;
+        /// Get the top-level config items
+        items: func() -> list<config-item>;
+
+        /// Get the include context (parent block names from include directive)
+        include-context: func() -> list<string>;
+        /// Check if this config is included from within a specific context
+        is-included-from: func(context: string) -> bool;
+        /// Check if included from http context
+        is-included-from-http: func() -> bool;
+        /// Check if included from http > server context
+        is-included-from-http-server: func() -> bool;
+        /// Check if included from http > ... > location context
+        is-included-from-http-location: func() -> bool;
+        /// Check if included from stream context
+        is-included-from-stream: func() -> bool;
+        /// Get the immediate parent context
+        immediate-parent-context: func() -> option<string>;
+    }
+}
+
+/// Record-based types for parser output (no resources, no recursion).
+/// Uses index-based references to represent the tree structure:
+/// all config items are stored in a flat array, with child-indices
+/// pointing to children within that array.
+interface parser-types {
+    use data-types.{comment-info, blank-line-info, directive-data};
+
+    /// The kind of a config item (non-recursive)
+    variant config-item-value {
+        directive-item(directive-data),
+        comment-item(comment-info),
+        blank-line-item(blank-line-info),
+    }
+
+    /// A config item in the flat all-items array.
+    /// For directive items with blocks, child-indices contains the indices
+    /// of child items within the all-items array.
+    record config-item {
+        value: config-item-value,
+        child-indices: list<u32>,
+    }
+
+    /// A directive paired with its parent block context
+    record directive-context {
+        data: directive-data,
+        /// Indices of block items in the all-items array
+        block-item-indices: list<u32>,
+        parent-stack: list<string>,
+        depth: u32,
+    }
+
+    /// Complete parser output
+    record parse-output {
+        directives-with-context: list<directive-context>,
+        include-context: list<string>,
+        /// Flat array of all config items (DFS order)
+        all-items: list<config-item>,
+        /// Indices of top-level items in all-items
+        top-level-indices: list<u32>,
+    }
+}
+
+world plugin {
+    use types.{plugin-spec, lint-error};
+    use config-api.{config};
+    import config-api;
+
+    /// Return plugin metadata
+    export spec: func() -> plugin-spec;
+
+    /// Check config and return lint errors
+    export check: func(cfg: borrow<config>, path: string) -> list<lint-error>;
+}
+
+world parser {
+    use parser-types.{parse-output};
+
+    /// Parse nginx config source and return structured output
+    export parse-config: func(source: string, include-context: list<string>) -> result<parse-output, string>;
+}