nginx-lint-plugin 0.0.1 → 0.8.2

package/README.md

@@ -1,45 +1,256 @@
 # nginx-lint-plugin
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+TypeScript SDK for writing [nginx-lint](https://github.com/walf443/nginx-lint) plugins.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+Plugins are compiled to WebAssembly Component Model modules and loaded by the nginx-lint CLI at runtime.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Install
 
-## Purpose
+```bash
+npm install nginx-lint-plugin
+```
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `nginx-lint-plugin`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Quick Start
 
-## What is OIDC Trusted Publishing?
+A plugin exports two functions: `spec` (metadata) and `check` (lint logic).
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+```typescript
+// src/plugin.ts
+import type { Config, LintError, PluginSpec } from "nginx-lint-plugin";
 
-## Setup Instructions
+export function spec(): PluginSpec {
+  return {
+    name: "my-rule",
+    category: "best-practices",
+    description: "Describe what this rule checks",
+    apiVersion: "1.0",
+    severity: "warning",
+  };
+}
 
-To properly configure OIDC trusted publishing for this package:
+export function check(cfg: Config, path: string): LintError[] {
+  const errors: LintError[] = [];
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+  for (const ctx of cfg.allDirectivesWithContext()) {
+    const directive = ctx.directive;
 
-## DO NOT USE THIS PACKAGE
+    if (directive.is("proxy_pass") && !directive.hasBlock()) {
+      errors.push({
+        rule: "my-rule",
+        category: "best-practices",
+        message: "proxy_pass should ...",
+        severity: "warning",
+        line: directive.line(),
+        column: directive.column(),
+        fixes: [directive.replaceWith("proxy_pass http://upstream;")],
+      });
+    }
+  }
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+  return errors;
+}
+```
 
-## More Information
+## Testing
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+The `nginx-lint-plugin/testing` entry provides parser-based testing utilities. Tests parse real nginx configuration strings using the same Rust parser that powers the production linter.
 
----
+```typescript
+import { describe, it } from "node:test";
+import { spec, check } from "./plugin.js";
+import { parseConfig, PluginTestRunner } from "nginx-lint-plugin/testing";
 
-**Maintained for OIDC setup purposes only**
+describe("my-rule", () => {
+  const runner = new PluginTestRunner(spec, check);
+
+  it("detects the issue", () => {
+    runner.assertErrors("http {\n    proxy_pass http://bad;\n}", 1);
+  });
+
+  it("passes valid config", () => {
+    runner.assertErrors("http {\n    proxy_pass http://good;\n}", 0);
+  });
+
+  it("checks error on specific line", () => {
+    runner.assertErrorOnLine("http {\n    proxy_pass http://bad;\n}", 2);
+  });
+
+  it("validates bad/good examples", () => {
+    runner.testExamples(
+      "http {\n    proxy_pass http://bad;\n}",
+      "http {\n    proxy_pass http://good;\n}",
+    );
+  });
+});
+```
+
+### Testing with include context
+
+Use `parseConfig` directly to simulate files included from specific blocks:
+
+```typescript
+it("handles included files", () => {
+  const cfg = parseConfig("server_tokens off;", {
+    includeContext: ["http", "server"],
+  });
+  const errors = check(cfg, "test.conf");
+  assert.equal(errors.length, 0);
+});
+```
+
+### PluginTestRunner
+
+| Method | Description |
+|--------|-------------|
+| `checkString(content, opts?)` | Parse and check, returning errors from this rule |
+| `assertErrors(content, count)` | Assert exactly N errors |
+| `assertErrorOnLine(content, line)` | Assert error on a specific line |
+| `testExamples(badConf, goodConf)` | Validate bad config produces errors, good config does not |
+
+## Building a Plugin
+
+### package.json
+
+The WIT definition file is bundled with this package, so `jco componentize` can reference it directly from `node_modules`.
+
+```json
+{
+  "name": "my-plugin",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && jco componentize dist/plugin.js -w node_modules/nginx-lint-plugin/wit -n plugin --disable all -o dist/my-plugin.wasm",
+    "test": "tsc && node --test dist/plugin.test.js"
+  },
+  "dependencies": {
+    "nginx-lint-plugin": "^0.8.2"
+  },
+  "devDependencies": {
+    "@bytecodealliance/componentize-js": "^0.19",
+    "@bytecodealliance/jco": "^1",
+    "typescript": "^5"
+  }
+}
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}
+```
+
+### Build and run
+
+```bash
+npm run build
+nginx-lint --plugins ./dist path/to/nginx.conf
+```
+
+The `--plugins` option takes a directory path. nginx-lint automatically loads all `.wasm` files found in that directory.
+
+## API Reference
+
+### Types
+
+```typescript
+import type {
+  // Core types
+  Severity,        // "error" | "warning"
+  Fix,             // Autofix descriptor
+  LintError,       // Lint error with rule, message, line, column, fixes
+  PluginSpec,      // Plugin metadata
+
+  // Directive data
+  ArgumentType,    // "literal" | "quoted-string" | "single-quoted-string" | "variable"
+  ArgumentInfo,    // Argument with value, raw text, type, position
+  DirectiveData,   // Flat directive properties
+
+  // Config tree
+  Config,          // Parsed nginx configuration
+  Directive,       // A single directive with methods
+  DirectiveContext,// Directive with parent stack and depth
+  ConfigItem,      // Directive | Comment | BlankLine
+} from "nginx-lint-plugin";
+```
+
+### Config
+
+| Method | Description |
+|--------|-------------|
+| `allDirectivesWithContext()` | All directives with parent context (DFS order) |
+| `allDirectives()` | All directives without context |
+| `items()` | Top-level config items (directives, comments, blank lines) |
+| `includeContext()` | Parent block names from `include` directives |
+| `isIncludedFrom(context)` | Check if included from a specific block |
+| `isIncludedFromHttp()` | Check if included from `http` block |
+| `isIncludedFromHttpServer()` | Check if included from `http > server` |
+| `isIncludedFromHttpLocation()` | Check if included from `http > ... > location` |
+| `isIncludedFromStream()` | Check if included from `stream` block |
+| `immediateParentContext()` | Immediate parent block name |
+
+### Directive
+
+| Method | Description |
+|--------|-------------|
+| `name()` | Directive name (e.g. `"server_tokens"`) |
+| `is(name)` | Check directive name |
+| `firstArg()` | First argument value |
+| `firstArgIs(value)` | Check first argument |
+| `argAt(index)` | Argument at index |
+| `lastArg()` | Last argument value |
+| `hasArg(value)` | Check if argument exists |
+| `argCount()` | Number of arguments |
+| `args()` | All arguments as `ArgumentInfo[]` |
+| `line()` / `column()` | Source position |
+| `hasBlock()` | Whether directive has a `{ }` block |
+| `blockItems()` | Child items inside the block |
+| `blockIsRaw()` | Whether block content is raw (e.g. `map`) |
+
+### Directive Fix Builders
+
+| Method | Description |
+|--------|-------------|
+| `replaceWith(newText)` | Replace the entire directive |
+| `deleteLineFix()` | Delete the directive's line |
+| `insertAfter(newText)` | Insert text after the directive |
+| `insertBefore(newText)` | Insert text before the directive |
+| `insertAfterMany(lines)` | Insert multiple lines after |
+| `insertBeforeMany(lines)` | Insert multiple lines before |
+
+### DirectiveContext
+
+| Field | Description |
+|-------|-------------|
+| `directive` | The directive |
+| `parentStack` | Parent block names (e.g. `["http", "server"]`) |
+| `depth` | Nesting depth |
+
+### PluginSpec
+
+```typescript
+{
+  name: string;         // Rule identifier (e.g. "my-rule")
+  category: string;     // Category (e.g. "security", "best-practices", "style", "syntax")
+  description: string;  // Human-readable description
+  apiVersion: string;   // API version ("1.0")
+  severity?: string;    // Default: "warning". Also accepts "error"
+  why?: string;         // Explanation of why this rule matters
+  badExample?: string;  // Config that triggers the rule
+  goodExample?: string; // Config that passes the rule
+  references?: string[];// Links to relevant documentation
+}
+```
+
+## License
+
+MIT

package/dist/config-builder.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Builds WIT-compatible Config/Directive objects from parser component output.
+ *
+ * The parser WASM component returns a ParseOutput with an index-based tree
+ * representation (to avoid recursive types in WIT). This module reconstructs
+ * the method-based Directive/Config interfaces from that flat representation.
+ */
+import type { Config } from "./generated/interfaces/nginx-lint-plugin-config-api.js";
+import type { ParseOutput } from "../wasm/parser/interfaces/nginx-lint-plugin-parser-types.js";
+export declare function buildConfigFromParseOutput(output: ParseOutput): Config;

package/dist/config-builder.js

@@ -0,0 +1,109 @@
+/**
+ * Builds WIT-compatible Config/Directive objects from parser component output.
+ *
+ * The parser WASM component returns a ParseOutput with an index-based tree
+ * representation (to avoid recursive types in WIT). This module reconstructs
+ * the method-based Directive/Config interfaces from that flat representation.
+ */
+import { makeIncludeContextMethods } from "./include-context.js";
+// ── Wrap DirectiveData with Directive interface ─────────────────────
+function wrapDirective(data, resolveBlockItems) {
+    const argValues = data.args.map((a) => a.value);
+    return {
+        data() { return data; },
+        name() { return data.name; },
+        is(name) { return data.name === name; },
+        firstArg() { return argValues[0] ?? undefined; },
+        firstArgIs(value) { return argValues[0] === value; },
+        argAt(index) { return argValues[index] ?? undefined; },
+        lastArg() { return argValues.length > 0 ? argValues[argValues.length - 1] : undefined; },
+        hasArg(value) { return argValues.includes(value); },
+        argCount() { return argValues.length; },
+        args() { return data.args; },
+        line() { return data.line; },
+        column() { return data.column; },
+        startOffset() { return data.startOffset; },
+        endOffset() { return data.endOffset; },
+        leadingWhitespace() { return data.leadingWhitespace; },
+        trailingWhitespace() { return data.trailingWhitespace; },
+        spaceBeforeTerminator() { return data.spaceBeforeTerminator; },
+        hasBlock() { return data.hasBlock; },
+        blockItems() { return resolveBlockItems(); },
+        blockIsRaw() { return data.blockIsRaw; },
+        replaceWith(newText) {
+            return {
+                line: data.line, oldText: undefined, newText,
+                deleteLine: false, insertAfter: false,
+                startOffset: data.startOffset, endOffset: data.endOffset,
+            };
+        },
+        deleteLineFix() {
+            return {
+                line: data.line, oldText: undefined, newText: "",
+                deleteLine: true, insertAfter: false,
+                startOffset: undefined, endOffset: undefined,
+            };
+        },
+        insertAfter(newText) {
+            return {
+                line: data.line, oldText: undefined, newText,
+                deleteLine: false, insertAfter: true,
+                startOffset: undefined, endOffset: undefined,
+            };
+        },
+        insertBefore(newText) {
+            return {
+                line: data.line, oldText: undefined, newText,
+                deleteLine: false, insertAfter: false,
+                startOffset: undefined, endOffset: undefined,
+            };
+        },
+        insertAfterMany(lines) {
+            return {
+                line: data.line, oldText: undefined, newText: lines.join("\n"),
+                deleteLine: false, insertAfter: true,
+                startOffset: undefined, endOffset: undefined,
+            };
+        },
+        insertBeforeMany(lines) {
+            return {
+                line: data.line, oldText: undefined, newText: lines.join("\n"),
+                deleteLine: false, insertAfter: false,
+                startOffset: undefined, endOffset: undefined,
+            };
+        },
+    };
+}
+// ── Resolve index-based items to ConfigItem tree ────────────────────
+function resolveConfigItem(allItems, index) {
+    const item = allItems[index];
+    if (item.value.tag === "directive-item") {
+        const data = item.value.val;
+        const childIndices = item.childIndices;
+        return {
+            tag: "directive-item",
+            val: wrapDirective(data, () => Array.from(childIndices).map((i) => resolveConfigItem(allItems, i))),
+        };
+    }
+    if (item.value.tag === "comment-item") {
+        return { tag: "comment-item", val: item.value.val };
+    }
+    return { tag: "blank-line-item", val: item.value.val };
+}
+// ── Build Config from ParseOutput ───────────────────────────────────
+export function buildConfigFromParseOutput(output) {
+    const inclCtx = output.includeContext;
+    const allItems = output.allItems;
+    const directiveContexts = output.directivesWithContext.map((ctx) => ({
+        directive: wrapDirective(ctx.data, () => Array.from(ctx.blockItemIndices).map((i) => resolveConfigItem(allItems, i))),
+        parentStack: ctx.parentStack,
+        depth: ctx.depth,
+    }));
+    const topLevelItems = Array.from(output.topLevelIndices).map((i) => resolveConfigItem(allItems, i));
+    return {
+        allDirectivesWithContext() { return directiveContexts; },
+        allDirectives() { return directiveContexts.map((c) => c.directive); },
+        items() { return topLevelItems; },
+        ...makeIncludeContextMethods(inclCtx),
+    };
+}

package/dist/include-context.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared include-context helpers for Config implementations.
+ *
+ * Provides the include-context portion of the Config interface so that
+ * config-builder.ts can reuse a single, tested implementation.
+ */
+export interface IncludeContextMethods {
+    includeContext(): string[];
+    isIncludedFrom(context: string): boolean;
+    isIncludedFromHttp(): boolean;
+    isIncludedFromHttpServer(): boolean;
+    isIncludedFromHttpLocation(): boolean;
+    isIncludedFromStream(): boolean;
+    immediateParentContext(): string | undefined;
+}
+export declare function makeIncludeContextMethods(inclCtx: string[]): IncludeContextMethods;

package/dist/include-context.js

@@ -0,0 +1,25 @@
+/**
+ * Shared include-context helpers for Config implementations.
+ *
+ * Provides the include-context portion of the Config interface so that
+ * config-builder.ts can reuse a single, tested implementation.
+ */
+export function makeIncludeContextMethods(inclCtx) {
+    return {
+        includeContext() { return inclCtx; },
+        isIncludedFrom(context) { return inclCtx.includes(context); },
+        isIncludedFromHttp() { return inclCtx.includes("http"); },
+        isIncludedFromHttpServer() {
+            const httpIndex = inclCtx.indexOf("http");
+            const serverIndex = inclCtx.indexOf("server");
+            return httpIndex !== -1 && serverIndex !== -1 && httpIndex < serverIndex;
+        },
+        isIncludedFromHttpLocation() {
+            const httpIndex = inclCtx.indexOf("http");
+            const locationIndex = inclCtx.indexOf("location");
+            return httpIndex !== -1 && locationIndex !== -1 && httpIndex < locationIndex;
+        },
+        isIncludedFromStream() { return inclCtx.includes("stream"); },
+        immediateParentContext() { return inclCtx.length > 0 ? inclCtx[inclCtx.length - 1] : undefined; },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * nginx-lint-plugin — shared TypeScript library for nginx-lint WASM plugins.
+ *
+ * Types are auto-generated from the WIT definition (wit/nginx-lint-plugin.wit)
+ * by `jco types` during the build step.
+ *
+ * Usage:
+ *   import type { Config, LintError, PluginSpec } from "nginx-lint-plugin";
+ */
+export type { Severity, Fix, LintError, PluginSpec, } from "./generated/interfaces/nginx-lint-plugin-types.js";
+export type { ArgumentType, ArgumentInfo, CommentInfo, BlankLineInfo, DirectiveData, } from "./generated/interfaces/nginx-lint-plugin-data-types.js";
+export type { ConfigItem, ConfigItemDirectiveItem, ConfigItemCommentItem, ConfigItemBlankLineItem, DirectiveContext, Directive, Config, } from "./generated/interfaces/nginx-lint-plugin-config-api.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * nginx-lint-plugin — shared TypeScript library for nginx-lint WASM plugins.
+ *
+ * Types are auto-generated from the WIT definition (wit/nginx-lint-plugin.wit)
+ * by `jco types` during the build step.
+ *
+ * Usage:
+ *   import type { Config, LintError, PluginSpec } from "nginx-lint-plugin";
+ */
+export {};

package/dist/plugin-test-runner.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Parser-based testing utilities for TypeScript nginx-lint plugins.
+ *
+ * Provides `parseConfig()` to parse real nginx configuration strings
+ * into WIT-compatible Config objects, and `PluginTestRunner` for
+ * assertion-based testing.
+ *
+ * Usage:
+ *   import { parseConfig, PluginTestRunner } from "nginx-lint-plugin/testing";
+ */
+import type { Config } from "./generated/interfaces/nginx-lint-plugin-config-api.js";
+import type { LintError, PluginSpec } from "./generated/interfaces/nginx-lint-plugin-types.js";
+/**
+ * Parse an nginx configuration string into a WIT-compatible Config object.
+ *
+ * Uses the nginx-lint-parser WASM component for accurate parsing identical
+ * to the production Rust parser. The DFS traversal (allDirectivesWithContext)
+ * is computed on the Rust side.
+ */
+export declare function parseConfig(source: string, opts?: {
+    includeContext?: string[];
+}): Config;
+type SpecFn = () => PluginSpec;
+type CheckFn = (cfg: Config, path: string) => LintError[];
+/**
+ * Test runner for TypeScript nginx-lint plugins.
+ *
+ * Mirrors the Rust `PluginTestRunner` API from `nginx-lint-plugin/testing`.
+ *
+ * Example:
+ * ```typescript
+ * import { spec, check } from "./plugin.js";
+ * import { PluginTestRunner } from "nginx-lint-plugin/testing";
+ *
+ * const runner = new PluginTestRunner(spec, check);
+ * runner.assertErrors("http { server_tokens on; }", 1);
+ * runner.assertErrors("http { server_tokens off; }", 0);
+ * ```
+ */
+export declare class PluginTestRunner {
+    private specFn;
+    private checkFn;
+    constructor(spec: SpecFn, check: CheckFn);
+    /**
+     * Parse and check a config string, returning only errors from this plugin's rule.
+     */
+    checkString(content: string, opts?: {
+        includeContext?: string[];
+    }): LintError[];
+    /**
+     * Assert that parsing and checking a config produces exactly `count` errors
+     * from this plugin's rule.
+     */
+    assertErrors(content: string, count: number): void;
+    /**
+     * Assert that a config produces at least one error on the given line.
+     */
+    assertErrorOnLine(content: string, line: number): void;
+    /**
+     * Test bad/good config content.
+     * - `badConf` must produce at least one error.
+     * - `goodConf` must produce zero errors.
+     */
+    testExamples(badConf: string, goodConf: string): void;
+}
+export {};

package/dist/plugin-test-runner.js

@@ -0,0 +1,92 @@
+/**
+ * Parser-based testing utilities for TypeScript nginx-lint plugins.
+ *
+ * Provides `parseConfig()` to parse real nginx configuration strings
+ * into WIT-compatible Config objects, and `PluginTestRunner` for
+ * assertion-based testing.
+ *
+ * Usage:
+ *   import { parseConfig, PluginTestRunner } from "nginx-lint-plugin/testing";
+ */
+import { parseConfig as parseConfigWasm } from "../wasm/parser/parser.js";
+import { buildConfigFromParseOutput } from "./config-builder.js";
+/**
+ * Parse an nginx configuration string into a WIT-compatible Config object.
+ *
+ * Uses the nginx-lint-parser WASM component for accurate parsing identical
+ * to the production Rust parser. The DFS traversal (allDirectivesWithContext)
+ * is computed on the Rust side.
+ */
+export function parseConfig(source, opts) {
+    const output = parseConfigWasm(source, opts?.includeContext ?? []);
+    return buildConfigFromParseOutput(output);
+}
+/**
+ * Test runner for TypeScript nginx-lint plugins.
+ *
+ * Mirrors the Rust `PluginTestRunner` API from `nginx-lint-plugin/testing`.
+ *
+ * Example:
+ * ```typescript
+ * import { spec, check } from "./plugin.js";
+ * import { PluginTestRunner } from "nginx-lint-plugin/testing";
+ *
+ * const runner = new PluginTestRunner(spec, check);
+ * runner.assertErrors("http { server_tokens on; }", 1);
+ * runner.assertErrors("http { server_tokens off; }", 0);
+ * ```
+ */
+export class PluginTestRunner {
+    specFn;
+    checkFn;
+    constructor(spec, check) {
+        this.specFn = spec;
+        this.checkFn = check;
+    }
+    /**
+     * Parse and check a config string, returning only errors from this plugin's rule.
+     */
+    checkString(content, opts) {
+        const cfg = parseConfig(content, opts);
+        const errors = this.checkFn(cfg, "test.conf");
+        const ruleName = this.specFn().name;
+        return errors.filter((e) => e.rule === ruleName);
+    }
+    /**
+     * Assert that parsing and checking a config produces exactly `count` errors
+     * from this plugin's rule.
+     */
+    assertErrors(content, count) {
+        const errors = this.checkString(content);
+        if (errors.length !== count) {
+            throw new Error(`Expected ${count} error(s) from "${this.specFn().name}", got ${errors.length}: ${JSON.stringify(errors, null, 2)}`);
+        }
+    }
+    /**
+     * Assert that a config produces at least one error on the given line.
+     */
+    assertErrorOnLine(content, line) {
+        const errors = this.checkString(content);
+        const hasLine = errors.some((e) => e.line === line);
+        if (!hasLine) {
+            const lines = errors.map((e) => e.line);
+            throw new Error(`Expected error on line ${line} from "${this.specFn().name}", got errors on lines: ${JSON.stringify(lines)}`);
+        }
+    }
+    /**
+     * Test bad/good config content.
+     * - `badConf` must produce at least one error.
+     * - `goodConf` must produce zero errors.
+     */
+    testExamples(badConf, goodConf) {
+        const ruleName = this.specFn().name;
+        const badErrors = this.checkString(badConf);
+        if (badErrors.length === 0) {
+            throw new Error(`bad.conf should produce at least one "${ruleName}" error, got none`);
+        }
+        const goodErrors = this.checkString(goodConf);
+        if (goodErrors.length > 0) {
+            throw new Error(`good.conf should produce no "${ruleName}" errors, got: ${JSON.stringify(goodErrors, null, 2)}`);
+        }
+    }
+}

package/package.json

@@ -1,10 +1,31 @@
 {
   "name": "nginx-lint-plugin",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for nginx-lint-plugin",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "version": "0.8.2",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/walf443/nginx-lint",
+    "directory": "plugins/typescript/nginx-lint-plugin"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./testing": "./dist/plugin-test-runner.js"
+  },
+  "files": [
+    "dist",
+    "wit"
+  ],
+  "scripts": {
+    "copy-wit": "mkdir -p wit && cp ../../../wit/nginx-lint-plugin.wit wit/",
+    "generate": "jco types wit -n plugin -o src/generated",
+    "build": "npm run copy-wit && npm run generate && tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@bytecodealliance/jco": "^1",
+    "typescript": "^5"
+  }
 }

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>;
+}