@cofferdam/check-sdk 0.2.2

package/README.md

@@ -0,0 +1,120 @@
+# @cofferdam/check-sdk
+
+Author [cofferdam](https://github.com/TAJD/cofferdam) plugin checks in TypeScript.
+
+`cofferdam` is a code-quality analyzer for TypeScript with a Rust core. The built-in checks cover the common ground (complexity, dead exports, triple-equals, etc); this SDK lets you express **project-specific architectural rules** as checks the same engine runs alongside the built-ins.
+
+## Install
+
+```sh
+pnpm add -D @cofferdam/check-sdk     # pnpm
+npm install -D @cofferdam/check-sdk  # npm
+yarn add -D @cofferdam/check-sdk     # yarn
+```
+
+The SDK ships compiled JS + types; no runtime dependencies. Node 16+.
+
+## Hello check
+
+```ts
+// my-checks/no-rovikore.ts
+import { Category, defineCheck, Severity } from "@cofferdam/check-sdk";
+
+export default defineCheck({
+  id: "BrandCasing",
+  category: Category.Warning,
+  basePriority: 15,
+  defaultSeverity: Severity.High,
+  explanation: "Brand must be spelled ROVIKORE.",
+  files: { extensions: ["ts", "tsx"] },
+  options: {
+    brand: { default: "ROVIKORE", type: "string" },
+  },
+  run(file, ctx, opts) {
+    for (const line of file.lines()) {
+      // Pattern A — line walk. Skip comments and skip non-string content
+      // so we don't false-positive on identifiers / JSX text.
+      if (line.isComment || line.isJsxText) continue;
+      if (!line.isStringLiteral) continue;
+      const m = /\bRovikore\b/.exec(line.text);
+      if (!m) continue;
+      ctx.report({
+        message: `Brand must be ${opts.brand}, not ${m[0]}.`,
+        span: line.spanFor(m.index, m.index + m[0].length),
+      });
+    }
+  },
+});
+```
+
+Wire it into `cofferdam.toml`:
+
+```toml
+plugins = ["./my-checks/no-rovikore.ts"]
+
+[checks."BrandCasing"]
+brand = "ROVIKORE"
+```
+
+Then `cofferdam check src/` runs your plugin alongside every built-in check. Findings flow through the same priority computation, suppression directives, baseline diffing, and output formats.
+
+## Three patterns
+
+The SDK supports three check shapes, each suited to a different rule class:
+
+- **Pattern A — line walk.** `for (const line of file.lines()) { … }`. Best for content checks against string literals or comments (brand spelling, banned words, license headers). The fastest path; no AST parse needed.
+- **Pattern B — AST findAll.** `file.ast.findAll("CallExpression")`, `findAll("ImportDeclaration")`. Best when the rule is a tag-and-match against specific node kinds (banned imports, forbidden API calls).
+- **Pattern C — stateful walk.** `file.ast.walk(visitor)` with accumulator state, decided per-file. Best when the rule depends on inter-statement context (tenant scoping across queries, accumulator-vs-mutator analysis).
+
+`AstView` exposes 9 node kinds today: `Program`, `CallExpression`, `ImportDeclaration`, `Function`, `ArrowFunctionExpression`, `Class`, `ObjectExpression`, `MemberExpression`, `IdentifierReference`. The set is additive — new kinds can land in minor releases without breaking existing plugins.
+
+## API surface
+
+```ts
+import {
+  defineCheck,           // factory — returns a Check
+  Category,              // Consistency | Design | Readability | Refactor | Warning
+  Severity,              // Info | Low | Medium | High | Critical
+  Walk,                  // visitor return: Continue | Skip
+} from "@cofferdam/check-sdk";
+
+import type {
+  Check, CheckContext, ReportArgs, Fix,
+  SourceFile, LineView, Span, RelatedSpan,
+  AstView, AstVisitor, AstNode, NodeKind,
+  // Per-kind typed nodes:
+  ProgramNode, CallExpressionNode, ImportDeclarationNode,
+  FunctionNode, ArrowFunctionExpressionNode, ClassNode,
+  ObjectExpressionNode, MemberExpressionNode, IdentifierReferenceNode,
+  // Options schema helpers:
+  OptionKind, OptionSpec, OptionsSchema, ResolvedOptions,
+} from "@cofferdam/check-sdk";
+```
+
+Everything in this list is part of the stability contract; new exports are additive. Removing or renaming an export is a breaking change.
+
+## Versioning
+
+The SDK ships in lockstep with the cofferdam binary. `@cofferdam/check-sdk@X.Y.Z` is built and tested against `cofferdam@X.Y.Z`; the cofferdam plugin host enforces a major-version compatibility check at load time and refuses to run plugins whose vendored SDK is from a different major.
+
+For 0.x: minor bumps may be breaking. Pin both packages to the same exact version until 1.0:
+
+```jsonc
+{
+  "devDependencies": {
+    "cofferdam": "0.2.2",
+    "@cofferdam/check-sdk": "0.2.2"
+  }
+}
+```
+
+## Documentation
+
+- Full plugin authoring guide (with worked examples for all three patterns): <https://tajd.github.io/cofferdam>
+- AST surface reference: [`design/sdk-ast-surface.md`](https://github.com/TAJD/cofferdam/blob/main/design/sdk-ast-surface.md)
+- AST wire format (Rust ↔ Node host): [`design/sdk-ast-wire.md`](https://github.com/TAJD/cofferdam/blob/main/design/sdk-ast-wire.md)
+- Three end-to-end fixtures (working plugins): [`examples-plugins/`](https://github.com/TAJD/cofferdam/tree/main/examples-plugins)
+
+## License
+
+MIT.

package/dist/ast.d.ts

@@ -0,0 +1,120 @@
+import type { Span } from "./span.js";
+/** Outcome of an AstVisitor visit. Controls per-node descent. */
+export declare const Walk: {
+    readonly Continue: "continue";
+    readonly Skip: "skip";
+};
+export type Walk = (typeof Walk)[keyof typeof Walk];
+/**
+ * Kinds exposed via {@link AstView.findAll} and the {@link AstNode}
+ * union. Deliberately a small set covering the rovikore-host plugin
+ * patterns; grows as plugin needs surface.
+ *
+ * v0 freeze: cd-717 (`design/sdk-ast-surface.md`). 5 strict +
+ * 4 borderline kinds. `NewExpression`, `BinaryExpression`,
+ * `StringLiteral`, `NumericLiteral` are deferred until a fixture
+ * justifies them — adding kinds is non-breaking, removing isn't.
+ */
+export type NodeKind = "Program" | "CallExpression" | "ImportDeclaration" | "Function" | "ArrowFunctionExpression" | "Class" | "ObjectExpression" | "MemberExpression" | "IdentifierReference";
+/**
+ * Common base for every AST node exposed across the FFI. Concrete
+ * kinds extend this with their own typed properties.
+ */
+export interface AstNodeBase<K extends NodeKind> {
+    readonly kind: K;
+    readonly span: Span;
+}
+/**
+ * The Program root — entry point for `view.root`. Body holds top-level
+ * statements; iterate it for declarations / imports / exports without
+ * walking the rest of the tree.
+ *
+ * Added in cd-svf to make `view.root: AstNode` typeable. Without
+ * Program in the union, root narrows to `never` on any TS switch.
+ */
+export interface ProgramNode extends AstNodeBase<"Program"> {
+    readonly body: readonly AstNode[];
+}
+export interface CallExpressionNode extends AstNodeBase<"CallExpression"> {
+    /** The callee expression — typically an `IdentifierReference` or `MemberExpression`. */
+    readonly callee: AstNode;
+    readonly arguments: readonly AstNode[];
+}
+export interface ImportDeclarationNode extends AstNodeBase<"ImportDeclaration"> {
+    /** The module specifier, e.g. `"axios"`. */
+    readonly source: string;
+    /** Each specifier's local name. */
+    readonly specifiers: readonly {
+        readonly localName: string;
+        readonly imported?: string;
+    }[];
+}
+export interface FunctionNode extends AstNodeBase<"Function"> {
+    readonly name: string | undefined;
+    readonly params: readonly AstNode[];
+    readonly async: boolean;
+    readonly generator: boolean;
+}
+export interface ArrowFunctionExpressionNode extends AstNodeBase<"ArrowFunctionExpression"> {
+    readonly params: readonly AstNode[];
+    readonly async: boolean;
+    readonly expression: boolean;
+}
+export interface ClassNode extends AstNodeBase<"Class"> {
+    readonly name: string | undefined;
+}
+export interface ObjectExpressionNode extends AstNodeBase<"ObjectExpression"> {
+    readonly properties: readonly AstNode[];
+}
+export interface MemberExpressionNode extends AstNodeBase<"MemberExpression"> {
+    readonly object: AstNode;
+    /** For `.foo` / `["foo"]`, the resolved property name when statically determinable. */
+    readonly property: string | undefined;
+    readonly computed: boolean;
+}
+export interface IdentifierReferenceNode extends AstNodeBase<"IdentifierReference"> {
+    readonly name: string;
+}
+/** Discriminated union of every node kind {@link AstView} surfaces. */
+export type AstNode = ProgramNode | CallExpressionNode | ImportDeclarationNode | FunctionNode | ArrowFunctionExpressionNode | ClassNode | ObjectExpressionNode | MemberExpressionNode | IdentifierReferenceNode;
+/** Map from kind string to typed node — drives `findAll`'s return type. */
+export type NodeOfKind<K extends NodeKind> = Extract<AstNode, {
+    kind: K;
+}>;
+/**
+ * Visitor passed to {@link AstView.walk}. Override only the kinds you
+ * care about; defaults are `Walk.Continue` no-ops. Returning
+ * `Walk.Skip` stops descent into that node only — sibling nodes still
+ * visit.
+ */
+export interface AstVisitor {
+    visitProgram?(node: ProgramNode): Walk;
+    visitCallExpression?(node: CallExpressionNode): Walk;
+    visitImportDeclaration?(node: ImportDeclarationNode): Walk;
+    visitFunction?(node: FunctionNode): Walk;
+    visitArrowFunctionExpression?(node: ArrowFunctionExpressionNode): Walk;
+    visitClass?(node: ClassNode): Walk;
+    visitObjectExpression?(node: ObjectExpressionNode): Walk;
+    visitMemberExpression?(node: MemberExpressionNode): Walk;
+    visitIdentifierReference?(node: IdentifierReferenceNode): Walk;
+}
+/**
+ * Borrowed view of a parsed file's AST. Cheap to construct; cofferdam's
+ * napi loader builds one per file per check invocation.
+ */
+export interface AstView {
+    /** Direct access to the program root for surgical inspection. */
+    readonly root: AstNode;
+    /**
+     * Eagerly collect every node of `kind` in document order. O(N) over
+     * the AST. Allocates an array. For multi-kind queries prefer a single
+     * {@link walk} pass.
+     */
+    findAll<K extends NodeKind>(kind: K): readonly NodeOfKind<K>[];
+    /**
+     * Run a stateful visitor over the tree. See {@link AstVisitor} for
+     * the per-kind callbacks.
+     */
+    walk(visitor: AstVisitor): void;
+}
+//# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"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"}

package/dist/ast.js

@@ -0,0 +1,21 @@
+"use strict";
+// AST surface for plugins (cd-81a.2). Mirrors cofferdam_core::ast — a
+// thin TS proxy over oxc's parsed tree. The napi loader serializes the
+// shape across the FFI boundary so plugins program against this.
+//
+// Three access patterns:
+//
+// 1. Eager filter — `view.findAll("CallExpression")` returns every node
+//    of the given kind in document order.
+// 2. Stateful walk — `view.walk(visitor)`. Each visit method returns
+//    `Walk.Continue` or `Walk.Skip` to control descent.
+// 3. Direct rooted access — `view.root` for surgical inspection. Escape
+//    hatch when the kinds we expose don't cover the case yet.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Walk = void 0;
+/** Outcome of an AstVisitor visit. Controls per-node descent. */
+exports.Walk = {
+    Continue: "continue",
+    Skip: "skip",
+};
+//# sourceMappingURL=ast.js.map

package/dist/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":";AAAA,sEAAsE;AACtE,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,yBAAyB;AACzB,EAAE;AACF,wEAAwE;AACxE,0CAA0C;AAC1C,qEAAqE;AACrE,wDAAwD;AACxD,wEAAwE;AACxE,8DAA8D;;;AAI9D,iEAAiE;AACpD,QAAA,IAAI,GAAG;IAClB,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,MAAM;CACJ,CAAC"}

package/dist/category.d.ts

@@ -0,0 +1,9 @@
+export declare const Category: {
+    readonly Consistency: "consistency";
+    readonly Design: "design";
+    readonly Readability: "readability";
+    readonly Refactor: "refactor";
+    readonly Warning: "warning";
+};
+export type Category = (typeof Category)[keyof typeof Category];
+//# sourceMappingURL=category.d.ts.map

package/dist/category.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"category.d.ts","sourceRoot":"","sources":["../src/category.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,QAAQ;;;;;;CAMX,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC"}

package/dist/category.js

@@ -0,0 +1,15 @@
+"use strict";
+// Mirror of cofferdam_core::Category. The Rust enum serializes as the
+// lowercase variant ("warning", "design", ...); we hold both shapes so
+// authors can write `Category.Warning` for ergonomics and the engine
+// always reads the wire form.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Category = void 0;
+exports.Category = {
+    Consistency: "consistency",
+    Design: "design",
+    Readability: "readability",
+    Refactor: "refactor",
+    Warning: "warning",
+};
+//# sourceMappingURL=category.js.map

package/dist/category.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"category.js","sourceRoot":"","sources":["../src/category.ts"],"names":[],"mappings":";AAAA,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,8BAA8B;;;AAEjB,QAAA,QAAQ,GAAG;IACtB,WAAW,EAAE,aAAa;IAC1B,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;CACV,CAAC"}

package/dist/check-context.d.ts

@@ -0,0 +1,73 @@
+import type { AstView } from "./ast.js";
+import type { Severity } from "./severity.js";
+import type { LineView } from "./line-view.js";
+import type { Span } from "./span.js";
+/** A source file passed to a check's `run` callback. */
+export interface SourceFile {
+    /** Absolute path as cofferdam discovered it. Forward-slashed on every host. */
+    readonly path: string;
+    /** Full text of the file, UTF-8. Byte offsets in spans index into this. */
+    readonly text: string;
+    /**
+     * Iterate every line in the file with classification flags drawn
+     * from the comment table + an AST walk over string/template/JSX.
+     * See {@link LineView} for flag semantics.
+     */
+    lines(): IterableIterator<LineView>;
+    /**
+     * Plugin-facing AST view. `null` only when parsing produced no
+     * usable program (the engine emitted `Warning.ParseError` for those
+     * files — your check is not invoked again on the failed file).
+     */
+    readonly ast: AstView | null;
+}
+/**
+ * A single mechanical fix: replace the bytes in `span` with `replacement`.
+ * Mirrors `cofferdam_core::TextEdit`. Plugin authors attach this at
+ * report time; the cofferdam fix engine prefers it over the built-in
+ * `Check::autofix` trait method (cd-81a.6).
+ *
+ * Edits must be non-overlapping; the fix engine applies them in reverse
+ * byte-offset order so earlier replacements don't invalidate later spans.
+ */
+export interface Fix {
+    readonly span: Span;
+    readonly replacement: string;
+}
+/** Per-issue payload passed to {@link CheckContext.report}. */
+export interface ReportArgs {
+    /** Required. Human-readable problem description. */
+    readonly message: string;
+    /** Required. Where the issue lives. Build via `LineView.spanFor` or
+     *  `SourceFile.ast` node spans. */
+    readonly span: Span;
+    /**
+     * Optional severity override for this specific finding. Defaults to
+     * the check's `defaultSeverity` declared on `defineCheck`.
+     */
+    readonly severity?: Severity;
+    /**
+     * Optional secondary locations participating in the same finding —
+     * e.g. the duplicate of a duplicate-block, the other declarer of a
+     * duplicate-export. Omitted from JSON when empty.
+     */
+    readonly related?: readonly {
+        readonly file: string;
+        readonly span: Span;
+    }[];
+    /**
+     * Optional autofix payload. When present, `cofferdam fix` applies it
+     * in place of any built-in autofix logic for this check.
+     */
+    readonly fix?: Fix;
+}
+/**
+ * Mutable per-file scratch passed to `Check.run`. The check emits
+ * findings via `ctx.report(...)`; the engine collects, suppresses,
+ * baselines, and renders.
+ */
+export interface CheckContext {
+    /** Emit a finding. Calls accumulate; order is preserved. */
+    report(args: ReportArgs): void;
+}
+//# sourceMappingURL=check-context.d.ts.map

package/dist/check-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-context.d.ts","sourceRoot":"","sources":["../src/check-context.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,wDAAwD;AACxD,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,KAAK,IAAI,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;uCACmC;IACnC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;KAAE,EAAE,CAAC;IAC7E;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CAChC"}

package/dist/check-context.js

@@ -0,0 +1,7 @@
+"use strict";
+// SourceFile + CheckContext — the per-file scratch passed to a check's
+// `run(file, ctx, opts)` callback. Mirrors cofferdam_core::CheckContext
+// minus the bits that are only meaningful in the Rust pipeline (corpus,
+// FinalizeContext — those land in their own beads).
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=check-context.js.map

package/dist/check-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-context.js","sourceRoot":"","sources":["../src/check-context.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,wEAAwE;AACxE,wEAAwE;AACxE,oDAAoD"}

package/dist/define-check.d.ts

@@ -0,0 +1,105 @@
+import type { Category } from "./category.js";
+import type { CheckContext, SourceFile } from "./check-context.js";
+import type { OptionsSchema, ResolvedOptions } from "./options.js";
+import type { Severity } from "./severity.js";
+/**
+ * Declarative file-scope filter (cd-81a.5). When set, the engine
+ * pre-filters discovered files against this scope before invoking
+ * `run()`. Replaces the `scannable?` boilerplate that rovikore-host
+ * checks ship today.
+ */
+export interface FileScope {
+    /** File extensions (without leading dot). Empty/omitted = any. */
+    readonly extensions?: readonly string[];
+    /**
+     * Optional include glob (gitignore syntax via globset). When set,
+     * the file path must match.
+     */
+    readonly pathPattern?: string;
+    /**
+     * Exclude globs. Paths matching any of these are skipped, even if
+     * `pathPattern` matched.
+     */
+    readonly excludePatterns?: readonly string[];
+}
+/**
+ * The shape `defineCheck` returns — what the napi loader picks up
+ * from the plugin module's default export. Holds the static metadata
+ * + the `run` callback.
+ *
+ * The `_optionsKeyType` field is a phantom (never set at runtime); it
+ * pins the schema shape into the type so the loader can pass typed
+ * `opts` without TS losing inference.
+ */
+export interface Check<S extends OptionsSchema = OptionsSchema> {
+    readonly id: string;
+    readonly category: Category;
+    readonly basePriority: number;
+    readonly defaultSeverity: Severity;
+    readonly explanation: string;
+    /** Optional long-form catalog body used by `cofferdam explain --full`. */
+    readonly body: string | undefined;
+    /** Whether the check needs full type-aware analysis (routes through ts-morph). */
+    readonly requiresTypes: boolean;
+    /** Two-pass consistency mode. */
+    readonly consistency: boolean;
+    readonly options: S;
+    /** File-scope filter. `undefined` = applies to every file. */
+    readonly files: FileScope | undefined;
+    run(file: SourceFile, ctx: CheckContext, opts: ResolvedOptions<S>): void;
+}
+/**
+ * Input to `defineCheck`. Same shape as {@link Check} but the schema
+ * generic is inferred at the call site. Optional fields may be omitted
+ * (TS picks the conservative default).
+ */
+export interface DefineCheckInput<S extends OptionsSchema> {
+    readonly id: string;
+    readonly category: Category;
+    readonly basePriority: number;
+    /** Defaults to `Severity.Medium` if omitted. */
+    readonly defaultSeverity?: Severity;
+    readonly explanation: string;
+    readonly body?: string;
+    readonly requiresTypes?: boolean;
+    readonly consistency?: boolean;
+    /** Schema; defaults to `{}`. Inferred at the call site. */
+    readonly options?: S;
+    /** File-scope filter; defaults to "every file". */
+    readonly files?: FileScope;
+    run(file: SourceFile, ctx: CheckContext, opts: ResolvedOptions<S>): void;
+}
+/**
+ * Author a cofferdam plugin check. The call site is the contract: the
+ * value passed in is the value the napi loader receives, with TS
+ * inference flowing from `options` into `run`'s third argument.
+ *
+ * @example
+ *   import { defineCheck, Category, Severity } from "@cofferdam/check-sdk";
+ *
+ *   export default defineCheck({
+ *     id: "BrandCasing",
+ *     category: Category.Warning,
+ *     basePriority: 15,
+ *     explanation: "Brand name must be all-caps in user-facing copy.",
+ *     options: {
+ *       brand: { default: "ROVIKORE", type: "string" },
+ *       allowedAliases: { default: [] as string[], type: "string[]" },
+ *     },
+ *     run(file, ctx, opts) {
+ *       for (const ln of file.lines()) {
+ *         if (ln.isComment) continue;
+ *         if (!ln.isStringLiteral) continue;
+ *         const m = /\bRovikore\b/.exec(ln.text);
+ *         if (!m) continue;
+ *         if (opts.allowedAliases.some((a) => ln.text.includes(a))) continue;
+ *         ctx.report({
+ *           message: `Brand name must be "${opts.brand}", not "${m[0]}".`,
+ *           span: ln.spanFor(m.index, m.index + m[0].length),
+ *         });
+ *       }
+ *     },
+ *   });
+ */
+export declare function defineCheck<const S extends OptionsSchema = {}>(input: DefineCheckInput<S>): Check<S>;
+//# sourceMappingURL=define-check.d.ts.map

package/dist/define-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-check.d.ts","sourceRoot":"","sources":["../src/define-check.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAC1E;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,aAAa;IACvD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACrB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAC1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,CAAC,SAAS,aAAa,GAAG,EAAE,EAC5D,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,GACzB,KAAK,CAAC,CAAC,CAAC,CAcV"}

package/dist/define-check.js

@@ -0,0 +1,57 @@
+"use strict";
+// defineCheck — the factory plugin authors call to declare a check.
+//
+// Type inference flows from the `options` schema declared on the input
+// to the `opts` argument of `run`. This is the surface that earns the
+// SDK its right to exist — without it, plugin authors hand-write
+// matching types twice.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineCheck = defineCheck;
+/**
+ * Author a cofferdam plugin check. The call site is the contract: the
+ * value passed in is the value the napi loader receives, with TS
+ * inference flowing from `options` into `run`'s third argument.
+ *
+ * @example
+ *   import { defineCheck, Category, Severity } from "@cofferdam/check-sdk";
+ *
+ *   export default defineCheck({
+ *     id: "BrandCasing",
+ *     category: Category.Warning,
+ *     basePriority: 15,
+ *     explanation: "Brand name must be all-caps in user-facing copy.",
+ *     options: {
+ *       brand: { default: "ROVIKORE", type: "string" },
+ *       allowedAliases: { default: [] as string[], type: "string[]" },
+ *     },
+ *     run(file, ctx, opts) {
+ *       for (const ln of file.lines()) {
+ *         if (ln.isComment) continue;
+ *         if (!ln.isStringLiteral) continue;
+ *         const m = /\bRovikore\b/.exec(ln.text);
+ *         if (!m) continue;
+ *         if (opts.allowedAliases.some((a) => ln.text.includes(a))) continue;
+ *         ctx.report({
+ *           message: `Brand name must be "${opts.brand}", not "${m[0]}".`,
+ *           span: ln.spanFor(m.index, m.index + m[0].length),
+ *         });
+ *       }
+ *     },
+ *   });
+ */
+function defineCheck(input) {
+    return {
+        id: input.id,
+        category: input.category,
+        basePriority: input.basePriority,
+        defaultSeverity: input.defaultSeverity ?? "medium",
+        explanation: input.explanation,
+        body: input.body,
+        requiresTypes: input.requiresTypes ?? false,
+        consistency: input.consistency ?? false,
+        options: input.options ?? {},
+        files: input.files,
+        run: input.run,
+    };
+}
+//# sourceMappingURL=define-check.js.map

package/dist/define-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-check.js","sourceRoot":"","sources":["../src/define-check.ts"],"names":[],"mappings":";AAAA,oEAAoE;AACpE,EAAE;AACF,uEAAuE;AACvE,sEAAsE;AACtE,iEAAiE;AACjE,wBAAwB;;AA6GxB,kCAgBC;AAhDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,WAAW,CACzB,KAA0B;IAE1B,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,QAAQ;QAClD,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,KAAK;QAC3C,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,KAAK;QACvC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAK,EAAQ;QACnC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,EAAE,KAAK,CAAC,GAAG;KACf,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { Category } from "./category.js";
+export { Severity } from "./severity.js";
+export { Walk } from "./ast.js";
+export { defineCheck } from "./define-check.js";
+export { runPlugin, buildSourceFile } from "./plugin-host.js";
+export { loadPlugins, runPlugins } from "./loader.js";
+export type { PluginReport, PluginRunInput, NativeLineView, } from "./plugin-host.js";
+export type { LoadedPlugin, RunPluginsOptions } from "./loader.js";
+export type { Check, DefineCheckInput, FileScope } from "./define-check.js";
+export type { CheckContext, Fix, ReportArgs, SourceFile } from "./check-context.js";
+export type { LineView } from "./line-view.js";
+export type { Span, RelatedSpan } from "./span.js";
+export type { AstView, AstVisitor, AstNode, AstNodeBase, ProgramNode, CallExpressionNode, ImportDeclarationNode, FunctionNode, ArrowFunctionExpressionNode, ClassNode, ObjectExpressionNode, MemberExpressionNode, IdentifierReferenceNode, NodeKind, NodeOfKind, } from "./ast.js";
+export type { OptionKind, OptionSpec, OptionsSchema, ResolvedOptions, NoOptions, } from "./options.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EACV,YAAY,EACZ,cAAc,EACd,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEnE,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EACV,OAAO,EACP,UAAU,EACV,OAAO,EACP,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,2BAA2B,EAC3B,SAAS,EACT,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,QAAQ,EACR,UAAU,GACX,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,UAAU,EACV,UAAU,EACV,aAAa,EACb,eAAe,EACf,SAAS,GACV,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+// @cofferdam/check-sdk — author cofferdam plugin checks in TypeScript.
+//
+// Plugin authors install this package, write a check with `defineCheck`,
+// and `default export` it. The cofferdam napi loader (cd-81a.7) picks
+// the module up via `cofferdam.toml`'s `plugins = [...]` array and runs
+// it in a worker_thread per source file.
+//
+// This is the public surface. Everything exported here is part of the
+// stability contract; everything kept internal is not. New exports are
+// additive — removing or renaming an export is a breaking change.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPlugins = exports.loadPlugins = exports.buildSourceFile = exports.runPlugin = exports.defineCheck = exports.Walk = exports.Severity = exports.Category = void 0;
+var category_js_1 = require("./category.js");
+Object.defineProperty(exports, "Category", { enumerable: true, get: function () { return category_js_1.Category; } });
+var severity_js_1 = require("./severity.js");
+Object.defineProperty(exports, "Severity", { enumerable: true, get: function () { return severity_js_1.Severity; } });
+var ast_js_1 = require("./ast.js");
+Object.defineProperty(exports, "Walk", { enumerable: true, get: function () { return ast_js_1.Walk; } });
+var define_check_js_1 = require("./define-check.js");
+Object.defineProperty(exports, "defineCheck", { enumerable: true, get: function () { return define_check_js_1.defineCheck; } });
+// Loader runtime (cd-81a.7). Plugin authors import only the surfaces
+// above; cofferdam's own JS wrapper is the consumer of these.
+var plugin_host_js_1 = require("./plugin-host.js");
+Object.defineProperty(exports, "runPlugin", { enumerable: true, get: function () { return plugin_host_js_1.runPlugin; } });
+Object.defineProperty(exports, "buildSourceFile", { enumerable: true, get: function () { return plugin_host_js_1.buildSourceFile; } });
+var loader_js_1 = require("./loader.js");
+Object.defineProperty(exports, "loadPlugins", { enumerable: true, get: function () { return loader_js_1.loadPlugins; } });
+Object.defineProperty(exports, "runPlugins", { enumerable: true, get: function () { return loader_js_1.runPlugins; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,EAAE;AACF,yEAAyE;AACzE,sEAAsE;AACtE,wEAAwE;AACxE,yCAAyC;AACzC,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,kEAAkE;;;AAElE,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,mCAAgC;AAAvB,8FAAA,IAAI,OAAA;AACb,qDAAgD;AAAvC,8GAAA,WAAW,OAAA;AAEpB,qEAAqE;AACrE,8DAA8D;AAC9D,mDAA8D;AAArD,2GAAA,SAAS,OAAA;AAAE,iHAAA,eAAe,OAAA;AACnC,yCAAsD;AAA7C,wGAAA,WAAW,OAAA;AAAE,uGAAA,UAAU,OAAA"}

package/dist/line-view.d.ts

@@ -0,0 +1,25 @@
+import type { Span } from "./span.js";
+export interface LineView {
+    /** 1-based line number. */
+    readonly lineNo: number;
+    /** Line text with the trailing `\r` (CRLF) stripped, no `\n`. */
+    readonly text: string;
+    readonly isComment: boolean;
+    readonly isDocComment: boolean;
+    readonly isStringLiteral: boolean;
+    readonly isJsxText: boolean;
+    readonly isPragma: boolean;
+    /**
+     * Build a `Span` covering bytes `[charStart, charEnd)` *within this
+     * line*. `charStart`/`charEnd` are byte offsets relative to the start
+     * of `text` (after CRLF stripping). The returned span carries
+     * file-absolute `start_byte`/`end_byte` for direct use in
+     * `ctx.report({ span })`.
+     *
+     * Filed as cd-cgd to keep authoring concise — without this the check
+     * has to reconstruct the file-absolute offset by hand from the line's
+     * own start.
+     */
+    spanFor(charStart: number, charEnd: number): Span;
+}
+//# sourceMappingURL=line-view.d.ts.map

package/dist/line-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-view.d.ts","sourceRoot":"","sources":["../src/line-view.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,WAAW,QAAQ;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACnD"}

package/dist/line-view.js

@@ -0,0 +1,21 @@
+"use strict";
+// LineView — plugin-facing view of a source line with classification
+// flags populated by the engine from the parsed comment list and an AST
+// walk over string/template literals. Mirrors
+// cofferdam_core::lines::LineView.
+//
+// Flag semantics (kept in sync with cofferdam-core/src/lines.rs):
+//
+// - `isComment` — any comment (line `//`, single-line block, or
+//   multi-line block) overlaps this line.
+// - `isDocComment` — a JSDoc-style block (`/** ... */`) overlaps. Implies
+//   `isComment`.
+// - `isStringLiteral` — a `StringLiteral` or `TemplateLiteral` span
+//   overlaps this line.
+// - `isJsxText` — JSX text content overlaps this line. Filed as cd-0ne;
+//   present in the SDK so plugins can target it as soon as the engine
+//   ships the flag.
+// - `isPragma` — an annotation-style comment (`/* #__PURE__ */`,
+//   `/* @vite-ignore */`, etc.) overlaps. *Not* JSDoc.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=line-view.js.map

package/dist/line-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-view.js","sourceRoot":"","sources":["../src/line-view.ts"],"names":[],"mappings":";AAAA,qEAAqE;AACrE,wEAAwE;AACxE,8CAA8C;AAC9C,mCAAmC;AACnC,EAAE;AACF,kEAAkE;AAClE,EAAE;AACF,gEAAgE;AAChE,0CAA0C;AAC1C,0EAA0E;AAC1E,iBAAiB;AACjB,oEAAoE;AACpE,wBAAwB;AACxB,wEAAwE;AACxE,sEAAsE;AACtE,oBAAoB;AACpB,iEAAiE;AACjE,uDAAuD"}

package/dist/loader.d.ts

@@ -0,0 +1,32 @@
+import type { Check } from "./define-check.js";
+import type { PluginReport, PluginRunInput } from "./plugin-host.js";
+export interface LoadedPlugin {
+    /** Module path the plugin was loaded from. */
+    readonly path: string;
+    readonly check: Check;
+}
+export interface RunPluginsOptions {
+    /** Per-file timeout. Defaults to 5000ms. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Resolve and load a list of plugin module paths. Each path is
+ * `import()`'d; the module's default export must be the `Check` object
+ * returned from `defineCheck`.
+ *
+ * Throws on shape errors so the cofferdam binary fails loudly with a
+ * clear message — better than a runtime crash deep inside the loader.
+ */
+export declare function loadPlugins(paths: readonly string[]): Promise<LoadedPlugin[]>;
+/**
+ * Run every loaded plugin against every file. Collects `PluginReport[]`
+ * for the cofferdam binary to hand to native `mergePluginFindings`.
+ *
+ * In-process implementation: invokes plugins synchronously on the main
+ * thread. Worker-thread isolation lands in a follow-up bead — keeping
+ * the surface stable matters more than crash containment for the first
+ * milestone, since the SDK's e2e fixture (cd-7e4) is the immediate
+ * consumer and runs trusted code.
+ */
+export declare function runPlugins(plugins: readonly LoadedPlugin[], files: readonly PluginRunInput[], _options?: RunPluginsOptions): Promise<PluginReport[]>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAiBnF;AAaD;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,QAAQ,GAAE,iBAAsB,GAC/B,OAAO,CAAC,YAAY,EAAE,CAAC,CASzB"}

package/dist/loader.js

@@ -0,0 +1,74 @@
+"use strict";
+// Loader — orchestrates plugin discovery, worker_thread execution, and
+// timeout enforcement. Used by the cofferdam binary's JS wrapper after
+// it has the native `lineViews` helper available.
+//
+// API:
+//   const plugins = await loadPlugins(["./examples-plugins/brand-casing"]);
+//   const reports = await runPlugins(plugins, files, { timeoutMs: 5000 });
+//
+// `loadPlugins` resolves each path to its module's default export
+// (expected to be a `Check` returned from `defineCheck`) and verifies
+// shape. `runPlugins` spawns one worker_thread per plugin (NOT per
+// file — workers are reused) and pushes file inputs through them.
+//
+// Crash containment + timeout: a plugin throwing or hanging on one
+// file produces a `Warning.PluginCrashed` issue and the worker is
+// recycled; analysis continues for remaining files.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPlugins = loadPlugins;
+exports.runPlugins = runPlugins;
+/**
+ * Resolve and load a list of plugin module paths. Each path is
+ * `import()`'d; the module's default export must be the `Check` object
+ * returned from `defineCheck`.
+ *
+ * Throws on shape errors so the cofferdam binary fails loudly with a
+ * clear message — better than a runtime crash deep inside the loader.
+ */
+async function loadPlugins(paths) {
+    const { pathToFileURL } = await import("node:url");
+    const out = [];
+    for (const path of paths) {
+        // Convert OS paths to file:// URLs so dynamic import works on Windows
+        // (where C:\foo isn't a valid ESM specifier).
+        const specifier = /^([a-zA-Z]:|\/)/.test(path) ? pathToFileURL(path).href : path;
+        const mod = (await import(specifier));
+        const check = mod.default;
+        if (!isCheckShape(check)) {
+            throw new Error(`plugin at ${path} did not default-export a Check. Expected the value returned from defineCheck(...).`);
+        }
+        out.push({ path, check });
+    }
+    return out;
+}
+function isCheckShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.id === "string" &&
+        typeof v.category === "string" &&
+        typeof v.basePriority === "number" &&
+        typeof v.run === "function");
+}
+/**
+ * Run every loaded plugin against every file. Collects `PluginReport[]`
+ * for the cofferdam binary to hand to native `mergePluginFindings`.
+ *
+ * In-process implementation: invokes plugins synchronously on the main
+ * thread. Worker-thread isolation lands in a follow-up bead — keeping
+ * the surface stable matters more than crash containment for the first
+ * milestone, since the SDK's e2e fixture (cd-7e4) is the immediate
+ * consumer and runs trusted code.
+ */
+async function runPlugins(plugins, files, _options = {}) {
+    const { runPlugin } = await import("./plugin-host.js");
+    const out = [];
+    for (const plugin of plugins) {
+        for (const file of files) {
+            out.push(...runPlugin(plugin.check, file));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,uEAAuE;AACvE,kDAAkD;AAClD,EAAE;AACF,OAAO;AACP,4EAA4E;AAC5E,2EAA2E;AAC3E,EAAE;AACF,kEAAkE;AAClE,sEAAsE;AACtE,mEAAmE;AACnE,kEAAkE;AAClE,EAAE;AACF,mEAAmE;AACnE,kEAAkE;AAClE,oDAAoD;;AAwBpD,kCAiBC;AAuBD,gCAaC;AA7DD;;;;;;;GAOG;AACI,KAAK,UAAU,WAAW,CAAC,KAAwB;IACxD,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;IACnD,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,sEAAsE;QACtE,8CAA8C;QAC9C,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACjF,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAA0B,CAAC;QAC/D,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC;QAC1B,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,qFAAqF,CACvG,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ;QACxB,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ;QAClC,OAAO,CAAC,CAAC,GAAG,KAAK,UAAU,CAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,UAAU,CAC9B,OAAgC,EAChC,KAAgC,EAChC,WAA8B,EAAE;IAEhC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACvD,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/options.d.ts

@@ -0,0 +1,37 @@
+export type OptionKind = "string" | "number" | "boolean" | "string[]" | "number[]";
+export interface OptionSpec<K extends OptionKind, D> {
+    readonly type: K;
+    readonly default: D;
+    /** Optional human-readable description, surfaced by `cofferdam explain`. */
+    readonly description?: string;
+}
+type ResolvedFromKind<K extends OptionKind> = K extends "string" ? string : K extends "number" ? number : K extends "boolean" ? boolean : K extends "string[]" ? readonly string[] : K extends "number[]" ? readonly number[] : never;
+/**
+ * The shape of `opts` inside a check's `run(file, ctx, opts)` callback —
+ * derived from the schema declared on `defineCheck.options`.
+ *
+ * @example
+ *   const sdk = defineCheck({
+ *     options: {
+ *       brand: { default: "ROVIKORE", type: "string" },
+ *       allowedAliases: { default: [] as string[], type: "string[]" },
+ *     },
+ *     run(file, ctx, opts) {
+ *       opts.brand;          // string
+ *       opts.allowedAliases; // readonly string[]
+ *     },
+ *   });
+ */
+export type ResolvedOptions<S> = {
+    readonly [K in keyof S]: S[K] extends OptionSpec<infer Kind, infer _D> ? ResolvedFromKind<Kind> : never;
+};
+/** A bare schema record — `Record<string, OptionSpec<...>>`. Constrained
+ *  generics on `defineCheck` use this as the `extends` upper bound. */
+export type OptionsSchema = Record<string, OptionSpec<OptionKind, unknown>>;
+/** Empty schema — used as the default in `defineCheck` so the
+ *  third `opts` argument is `Record<string, never>` for option-less
+ *  checks rather than `undefined`. */
+export declare const NO_OPTIONS: {};
+export type NoOptions = typeof NO_OPTIONS;
+export {};
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAEnF,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID,KAAK,gBAAgB,CAAC,CAAC,SAAS,UAAU,IAAI,CAAC,SAAS,QAAQ,GAC5D,MAAM,GACN,CAAC,SAAS,QAAQ,GAChB,MAAM,GACN,CAAC,SAAS,SAAS,GACjB,OAAO,GACP,CAAC,SAAS,UAAU,GAClB,SAAS,MAAM,EAAE,GACjB,CAAC,SAAS,UAAU,GAClB,SAAS,MAAM,EAAE,GACjB,KAAK,CAAC;AAElB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC,GAClE,gBAAgB,CAAC,IAAI,CAAC,GACtB,KAAK;CACV,CAAC;AAEF;uEACuE;AACvE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AAE5E;;sCAEsC;AACtC,eAAO,MAAM,UAAU,IAAc,CAAC;AACtC,MAAM,MAAM,SAAS,GAAG,OAAO,UAAU,CAAC"}

package/dist/options.js

@@ -0,0 +1,16 @@
+"use strict";
+// Per-check options schema (cd-81a.3). Plugin authors declare an
+// `options` block on their `defineCheck(...)` call; the engine validates
+// user `cofferdam.toml` overrides against it at startup, and the resolved
+// values are passed to `run(file, ctx, opts)` typed correctly.
+//
+// The schema is a record of name → { default, type }. The `type` field is
+// the discriminator that drives both runtime validation and the type
+// inference below.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_OPTIONS = void 0;
+/** Empty schema — used as the default in `defineCheck` so the
+ *  third `opts` argument is `Record<string, never>` for option-less
+ *  checks rather than `undefined`. */
+exports.NO_OPTIONS = {};
+//# sourceMappingURL=options.js.map

package/dist/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":";AAAA,iEAAiE;AACjE,yEAAyE;AACzE,0EAA0E;AAC1E,+DAA+D;AAC/D,EAAE;AACF,0EAA0E;AAC1E,qEAAqE;AACrE,mBAAmB;;;AAmDnB;;sCAEsC;AACzB,QAAA,UAAU,GAAG,EAAW,CAAC"}

package/dist/plugin-host.d.ts

@@ -0,0 +1,64 @@
+import type { Check } from "./define-check.js";
+import type { Fix } from "./check-context.js";
+import type { LineView } from "./line-view.js";
+import type { Span } from "./span.js";
+export interface NativeLineView {
+    readonly lineNo: number;
+    readonly text: string;
+    readonly isComment: boolean;
+    readonly isDocComment: boolean;
+    readonly isStringLiteral: boolean;
+    readonly isJsxText: boolean;
+    readonly isPragma: boolean;
+    readonly lineStart: number;
+}
+/**
+ * One report that crosses the worker_thread boundary back to the
+ * loader. Mirrors the napi `JsReport` struct in cofferdam-napi.
+ */
+export interface PluginReport {
+    readonly checkId: string;
+    readonly message: string;
+    readonly file: string;
+    readonly startByte: number;
+    readonly endByte: number;
+    readonly severity: string;
+    readonly fix?: Fix;
+    readonly related?: readonly {
+        readonly file: string;
+        readonly span: Span;
+    }[];
+}
+/**
+ * Runtime input passed from the loader to a plugin's `run()` callback.
+ * Built from native `lineViews()` + the file path/text. Cheap to
+ * serialise (no AST handles cross the boundary).
+ */
+export interface PluginRunInput {
+    readonly path: string;
+    readonly text: string;
+    readonly lineViews: readonly NativeLineView[];
+}
+/**
+ * Build the `SourceFile` shape a plugin's `run()` callback expects.
+ * `ast` is `null` here — AST access lives behind a separate napi call
+ * the loader can route through worker_threads in a follow-up bead. The
+ * line-walk Pattern A checks (BrandCasing) work today.
+ */
+export declare function buildSourceFile(input: PluginRunInput): {
+    path: string;
+    text: string;
+    lines(): IterableIterator<LineView>;
+    ast: null;
+};
+/**
+ * Execute a single plugin against a single file. Collects `ctx.report`
+ * calls into a `PluginReport[]` the loader can hand to native
+ * `mergePluginFindings`.
+ *
+ * This is the function a worker_thread invokes. The host process never
+ * touches plugin code directly — crash containment is the worker's
+ * boundary.
+ */
+export declare function runPlugin(check: Check, input: PluginRunInput): PluginReport[];
+//# sourceMappingURL=plugin-host.d.ts.map

package/dist/plugin-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-host.d.ts","sourceRoot":"","sources":["../src/plugin-host.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAgB,GAAG,EAAc,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAItC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IACnB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;KAAE,EAAE,CAAC;CAC9E;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CAC/C;AAwBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc;;;aAKxC,gBAAgB,CAAC,QAAQ,CAAC;;EAqBtC;AAID;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,GAAG,YAAY,EAAE,CA0C7E"}

package/dist/plugin-host.js

@@ -0,0 +1,129 @@
+"use strict";
+// Plugin host runtime — the JS side of cd-81a.7.
+//
+// Lives in @cofferdam/check-sdk so the loader and the authoring SDK
+// share one published surface. The cofferdam binary's JS wrapper (in
+// packages/cofferdam) imports `loadPlugin` and `runPlugin` from here
+// after it has obtained the native addon's `lineViews` /
+// `mergePluginFindings` helpers.
+//
+// Why worker_threads: a plugin throwing on one file must not crash the
+// engine driver, and unbounded plugin runs must be timeout-able.
+// worker_threads gives crash containment + per-message timeout for free,
+// at the cost of postMessage serialisation per file (cheap relative to
+// parsing).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSourceFile = buildSourceFile;
+exports.runPlugin = runPlugin;
+// ---- runtime construction --------------------------------------------
+function buildLineView(native) {
+    return {
+        lineNo: native.lineNo,
+        text: native.text,
+        isComment: native.isComment,
+        isDocComment: native.isDocComment,
+        isStringLiteral: native.isStringLiteral,
+        isJsxText: native.isJsxText,
+        isPragma: native.isPragma,
+        spanFor(charStart, charEnd) {
+            return {
+                line: native.lineNo,
+                column: charStart + 1,
+                start_byte: native.lineStart + charStart,
+                end_byte: native.lineStart + charEnd,
+            };
+        },
+    };
+}
+/**
+ * Build the `SourceFile` shape a plugin's `run()` callback expects.
+ * `ast` is `null` here — AST access lives behind a separate napi call
+ * the loader can route through worker_threads in a follow-up bead. The
+ * line-walk Pattern A checks (BrandCasing) work today.
+ */
+function buildSourceFile(input) {
+    const lineViews = input.lineViews.map(buildLineView);
+    return {
+        path: input.path,
+        text: input.text,
+        lines() {
+            let i = 0;
+            const it = {
+                next() {
+                    if (i < lineViews.length) {
+                        return { value: lineViews[i++], done: false };
+                    }
+                    return { value: undefined, done: true };
+                },
+                [Symbol.iterator]() {
+                    return it;
+                },
+                return(value) {
+                    i = lineViews.length;
+                    return { value: value, done: true };
+                },
+            };
+            return it;
+        },
+        ast: null,
+    };
+}
+// ---- runPlugin -------------------------------------------------------
+/**
+ * Execute a single plugin against a single file. Collects `ctx.report`
+ * calls into a `PluginReport[]` the loader can hand to native
+ * `mergePluginFindings`.
+ *
+ * This is the function a worker_thread invokes. The host process never
+ * touches plugin code directly — crash containment is the worker's
+ * boundary.
+ */
+function runPlugin(check, input) {
+    const reports = [];
+    const ctx = {
+        report(args) {
+            const { span, severity, related, fix } = args;
+            const report = {
+                checkId: check.id,
+                message: args.message,
+                file: input.path,
+                startByte: span.start_byte,
+                endByte: span.end_byte,
+                severity: severity ?? check.defaultSeverity,
+                ...(fix !== undefined ? { fix } : {}),
+                ...(related !== undefined ? { related } : {}),
+            };
+            reports.push(report);
+        },
+    };
+    // Resolve options — currently use the schema defaults; the loader can
+    // pass user-supplied overrides through cofferdam.toml in a follow-up.
+    // The cast is sound because the schema's defaults already satisfy
+    // ResolvedOptions<S>'s mapped types by construction.
+    const opts = resolveDefaults(check.options);
+    try {
+        check.run(buildSourceFile(input), ctx, opts);
+    }
+    catch (err) {
+        // Don't swallow the plugin error — push a synthetic report so the
+        // engine surfaces it as `Warning.PluginCrashed` and analysis
+        // continues for the rest of the corpus.
+        reports.push({
+            checkId: "Warning.PluginCrashed",
+            message: `plugin '${check.id}' threw: ${err instanceof Error ? err.message : String(err)}`,
+            file: input.path,
+            startByte: 0,
+            endByte: 0,
+            severity: "high",
+        });
+    }
+    return reports;
+}
+function resolveDefaults(schema) {
+    const out = {};
+    for (const key of Object.keys(schema)) {
+        out[key] = schema[key].default;
+    }
+    return out;
+}
+//# sourceMappingURL=plugin-host.js.map

package/dist/plugin-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-host.js","sourceRoot":"","sources":["../src/plugin-host.ts"],"names":[],"mappings":"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"}

package/dist/severity.d.ts

@@ -0,0 +1,9 @@
+export declare const Severity: {
+    readonly Info: "info";
+    readonly Low: "low";
+    readonly Medium: "medium";
+    readonly High: "high";
+    readonly Critical: "critical";
+};
+export type Severity = (typeof Severity)[keyof typeof Severity];
+//# sourceMappingURL=severity.d.ts.map

package/dist/severity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.d.ts","sourceRoot":"","sources":["../src/severity.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,QAAQ;;;;;;CAMX,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC"}

package/dist/severity.js

@@ -0,0 +1,14 @@
+"use strict";
+// Mirror of cofferdam_core::Severity. Wire form is the lowercase string;
+// the const-as-namespace pattern keeps `Severity.Warning` ergonomic
+// without spinning up an enum (which TS enums emit runtime code for).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Severity = void 0;
+exports.Severity = {
+    Info: "info",
+    Low: "low",
+    Medium: "medium",
+    High: "high",
+    Critical: "critical",
+};
+//# sourceMappingURL=severity.js.map

package/dist/severity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.js","sourceRoot":"","sources":["../src/severity.ts"],"names":[],"mappings":";AAAA,yEAAyE;AACzE,oEAAoE;AACpE,sEAAsE;;;AAEzD,QAAA,QAAQ,GAAG;IACtB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;CACZ,CAAC"}

package/dist/span.d.ts

@@ -0,0 +1,15 @@
+export interface Span {
+    /** 1-based line number. */
+    readonly line: number;
+    /** 1-based column number, in UTF-8 bytes from the start of the line. */
+    readonly column: number;
+    /** 0-based byte offset from the start of the file (inclusive). */
+    readonly start_byte: number;
+    /** 0-based byte offset from the start of the file (exclusive). */
+    readonly end_byte: number;
+}
+export interface RelatedSpan {
+    readonly file: string;
+    readonly span: Span;
+}
+//# sourceMappingURL=span.d.ts.map

package/dist/span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.d.ts","sourceRoot":"","sources":["../src/span.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,IAAI;IACnB,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB"}

package/dist/span.js

@@ -0,0 +1,9 @@
+"use strict";
+// Mirror of cofferdam_core::Span. Carries both human (line/column) and
+// machine (byte offsets) coordinates so `ctx.report` consumers can do
+// either without re-parsing.
+//
+// All coordinates are 1-based for line, 1-based for column, 0-based for
+// bytes — matching the Rust struct and the JSON formatter contract.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=span.js.map

package/dist/span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.js","sourceRoot":"","sources":["../src/span.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,sEAAsE;AACtE,6BAA6B;AAC7B,EAAE;AACF,wEAAwE;AACxE,oEAAoE"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@cofferdam/check-sdk",
+  "version": "0.2.2",
+  "description": "Author cofferdam plugin checks in TypeScript. defineCheck factory + types.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TAJD/cofferdam.git",
+    "directory": "packages/check-sdk"
+  },
+  "homepage": "https://tajd.github.io/cofferdam",
+  "bugs": "https://github.com/TAJD/cofferdam/issues",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cofferdam",
+    "linter",
+    "static-analysis",
+    "plugin-sdk",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p . --noEmit",
+    "test:types": "tsc -p tests"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.6.0"
+  }
+}