madr-lint 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,370 @@
+import { AnySchemaObject } from 'ajv';
+import { Root, Nodes } from 'mdast';
+
+type MdastNodeType = Root['type'] | Nodes['type'];
+type MdastNode = Root | Nodes;
+/** Severity levels supported by every rule. */
+type Severity = 'error' | 'warn';
+/**
+ * User-facing severity declaration in config files.
+ * - bare string: enable/disable with default options
+ * - tuple: enable with explicit options
+ */
+type RuleSeverity = Severity | 'off' | readonly [Severity, Record<string, unknown>];
+type MadrVersion = 'v2' | 'v3' | 'v4';
+interface RuleMeta<TOptions = Record<string, unknown>> {
+    /** Rule identifier, e.g. 'madr/filename-format'. */
+    name: string;
+    /** Whether the rule operates per-file or across the project. */
+    type: 'perFile' | 'project';
+    /** Which MADR versions this rule applies to. */
+    versionCompat: readonly MadrVersion[];
+    docs: {
+        description: string;
+        url?: string;
+        recommended: boolean;
+    };
+    /** messageId -> template string with {{placeholders}}. */
+    messages: Record<string, string>;
+    /** Default options merged with user config. */
+    defaultOptions: TOptions;
+    /** AJV JSON Schema for options. Validated at runRule time. */
+    schema?: AnySchemaObject;
+}
+interface FileContext {
+    /** File path (typically basename or repo-relative). */
+    path: string;
+    /** Raw file content. */
+    content: string;
+}
+interface Diagnostic {
+    /** Rule that emitted this diagnostic. */
+    ruleName: string;
+    /** messageId from rule.meta.messages. */
+    messageId: string;
+    /** Severity resolved against the user config. */
+    severity: Severity;
+    /** Path of the offending file. */
+    path: string;
+    /** Optional source range. Filename rules omit this. */
+    loc?: {
+        line: number;
+        column: number;
+    };
+    /** Data for placeholder interpolation in messages[messageId]. */
+    data?: Record<string, unknown>;
+}
+interface RuleContext<TOptions = Record<string, unknown>> {
+    /** The file being linted. */
+    file: FileContext;
+    /**
+     * Parsed YAML frontmatter (v3/v4 only), or null if absent.
+     * Use this when the rule must validate strict YAML frontmatter shape.
+     */
+    frontmatter: Record<string, unknown> | null;
+    /**
+     * Combined metadata: YAML frontmatter merged with v2 bold-list extracted
+     * from the body. Frontmatter wins on key conflict. null only when both
+     * are absent. See ADR-0006. Use this for format-agnostic field reads.
+     */
+    metadata: Record<string, unknown> | null;
+    /** User-merged options for this rule (validated against rule.meta.schema). */
+    options: TOptions;
+    /** Emit a diagnostic. */
+    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity' | 'path'>): void;
+}
+/**
+ * Visitor map dispatched during single-pass mdast traversal.
+ * Rules subscribe to specific node types; the runner walks the tree once
+ * and calls the matching enter/exit handler for each node.
+ */
+interface RuleListeners {
+    enter?: Partial<Record<MdastNodeType, (node: MdastNode) => void>>;
+    exit?: Partial<Record<MdastNodeType, (node: MdastNode) => void>>;
+}
+/**
+ * A lint rule.
+ *
+ * - Filename / metadata-only rules: `create` reports diagnostics directly,
+ *   then returns void.
+ * - AST-based rules: `create` returns RuleListeners; the runner invokes
+ *   them during single-pass traversal of the file's mdast tree.
+ */
+interface Rule<TOptions = Record<string, unknown>> {
+    meta: RuleMeta<TOptions>;
+    create(context: RuleContext<TOptions>): RuleListeners | void;
+}
+/**
+ * A pre-parsed file passed to project rules. Built once per
+ * `runRulesOnProject` invocation.
+ */
+interface ProjectFile {
+    /** File path relative to the project root. */
+    path: string;
+    /** Raw file content (unparsed). */
+    content: string;
+    /** Parsed YAML frontmatter (v3/v4 only), or null if absent. */
+    frontmatter: Record<string, unknown> | null;
+    /**
+     * Combined metadata: frontmatter merged with v2 bold-list extracted
+     * from the body. Frontmatter wins on key conflict. See ADR-0006.
+     */
+    metadata: Record<string, unknown> | null;
+    /** mdast root of the body (frontmatter stripped). */
+    ast: Root;
+}
+interface ProjectRuleContext<TOptions = Record<string, unknown>> {
+    /** All files in the project (eager-parsed). */
+    files: readonly ProjectFile[];
+    /** User-merged options for this rule. */
+    options: TOptions;
+    /**
+     * Predicate: does a project-root-relative POSIX path exist as a regular
+     * file WITHIN the project root? Injected by the orchestrator so rules (e.g.
+     * no-broken-links) can verify link targets that are NOT in the linted `.md`
+     * set — non-Markdown assets or files outside the scanned paths. Returns
+     * false for directories and for any target that resolves at or above the
+     * project root (i.e. escapes it). Undefined when no filesystem is available
+     * (e.g. in-memory unit tests), in which case rules fall back to the `files`
+     * set alone.
+     */
+    fileExists?: (resolvedPath: string) => boolean;
+    /**
+     * Emit a diagnostic. Unlike per-file rules, project rules MUST set
+     * `path` explicitly — the runner cannot infer which file the
+     * diagnostic relates to.
+     */
+    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity'>): void;
+}
+/**
+ * A cross-file rule. Receives all parsed files at once and reports
+ * diagnostics with explicit `path` per file.
+ *
+ * Project rules use a different runner function (`runRulesOnProject`)
+ * and a distinct context shape from per-file rules. See ADR-0005 for
+ * the rationale behind keeping the two APIs separate.
+ */
+interface ProjectRule<TOptions = Record<string, unknown>> {
+    meta: RuleMeta<TOptions>;
+    check(context: ProjectRuleContext<TOptions>): void;
+}
+/** Either a per-file or a project rule. */
+type AnyRule<TOptions = Record<string, unknown>> = Rule<TOptions> | ProjectRule<TOptions>;
+/** Type guard distinguishing project rules from per-file rules. */
+declare function isProjectRule(rule: AnyRule): rule is ProjectRule;
+
+/**
+ * The reserved rule name used for internal-error diagnostics. A real rule
+ * cannot register with this name (the registry should reject collisions).
+ */
+declare const INTERNAL_ERROR_RULE_NAME = "core/internal-error";
+/**
+ * Thrown when a rule's merged options fail AJV validation against
+ * `rule.meta.schema`. Distinct from generic `Error` so callers can
+ * `instanceof` to skip rules with bad config and continue.
+ */
+declare class RuleOptionsError extends Error {
+    readonly ruleName: string;
+    readonly ajvErrors: string;
+    constructor(ruleName: string, ajvErrors: string);
+}
+interface RunRuleOptions {
+    /** Per-rule options to merge over rule.meta.defaultOptions. */
+    options?: Record<string, unknown>;
+    /**
+     * Options keyed by rule name, for multi-rule calls where each rule needs
+     * its own options (e.g. config tuples `['error', {...}]`). For a given rule,
+     * an entry here takes precedence over `options`; rules absent from the map
+     * fall back to `options` (if any), then `meta.defaultOptions`.
+     */
+    optionsByRule?: Record<string, Record<string, unknown>>;
+    /** Severity to attach to emitted diagnostics. Defaults to 'error'. */
+    severity?: Severity;
+    /** Skip AJV options validation. Default false. */
+    skipValidation?: boolean;
+    /**
+     * Filesystem-existence predicate exposed to project rules as
+     * `context.fileExists`. Per-file runs ignore this. See
+     * ProjectRuleContext.fileExists.
+     */
+    fileExists?: (resolvedPath: string) => boolean;
+}
+/**
+ * Run a single rule against a single file. Sugar over runRulesOnFile
+ * for the common one-rule case (used heavily by tests).
+ */
+declare function runRule<TOptions extends Record<string, unknown>>(rule: Rule<TOptions>, file: FileContext, runtime?: RunRuleOptions): Diagnostic[];
+/**
+ * Run multiple rules against a single file with a single mdast traversal.
+ *
+ * Steps:
+ *   1. Validate each rule's merged options against its schema (AJV).
+ *      Throws RuleOptionsError on failure (caller decides whether to skip).
+ *   2. Call each rule's create(). If a rule throws, the error is caught
+ *      and reported as a `core/internal-error` diagnostic — other rules
+ *      continue. The same isolation wraps every enter/exit handler so a
+ *      single buggy rule cannot abort the whole lint run.
+ *   3. If at least one rule returned RuleListeners, call parseFile()
+ *      ONCE (gray-matter + mdast-util-from-markdown together; there is
+ *      no separate cheap "frontmatter only" path) and walk the tree,
+ *      dispatching enter/exit handlers per node type.
+ *
+ * Frontmatter is exposed lazily via context.frontmatter — the getter
+ * triggers parseFile() on first access. Filename-style rules that never
+ * touch frontmatter and return void from create() pay zero parse cost.
+ */
+declare function runRulesOnFile(rules: readonly Rule[], file: FileContext, runtime?: RunRuleOptions): Diagnostic[];
+/**
+ * Build a `ProjectFile` (path + content + parsed frontmatter + AST) from
+ * a raw file. Used by `runRulesOnProject` and by the lint orchestrator
+ * to share parsing between per-file and project passes when needed.
+ */
+declare function buildProjectFile(file: FileContext): ProjectFile;
+/**
+ * Run multiple project rules across all parsed files. Each rule's
+ * `check()` is called once with the full file array. Throws are
+ * captured as `core/internal-error` diagnostics (attached to the
+ * first file's path, since project rules have no file context).
+ *
+ * See ADR-0005 for the API rationale.
+ */
+declare function runRulesOnProject(rules: readonly ProjectRule[], files: readonly ProjectFile[], runtime?: RunRuleOptions): Diagnostic[];
+
+interface ParsedFile {
+    /** Parsed YAML frontmatter (v3/v4), or null if absent. */
+    frontmatter: Record<string, unknown> | null;
+    /**
+     * v2 body-list metadata extracted from the leading list, or null if absent.
+     * Covers both the bold-key (`- **Status**:`) and the canonical MADR v2.1.2
+     * plain-key (`* Status:`) shapes. See ADR-0006.
+     */
+    listMetadata: Record<string, unknown> | null;
+    /**
+     * Combined metadata: frontmatter merged with bold-list. Frontmatter wins
+     * on key conflict. null only when both are absent. See ADR-0006.
+     */
+    metadata: Record<string, unknown> | null;
+    /** mdast root of the body (frontmatter stripped). */
+    ast: Root;
+    /** Body content with frontmatter stripped. */
+    body: string;
+}
+/**
+ * Parse a Markdown file: extract YAML frontmatter via gray-matter, then
+ * feed the body into mdast-util-from-markdown directly (per ADR-0002,
+ * we skip the unified+remark pipeline overhead). Additionally, extract
+ * v2-style list metadata from the body's first list — both bold-key and
+ * canonical plain-key shapes (see ADR-0006).
+ */
+declare function parseFile(content: string): ParsedFile;
+/**
+ * Extract v2-style list metadata from an mdast Root. The metadata block is
+ * the leading list — the first block after the H1 title (only headings may
+ * precede it; an intervening paragraph means the list is body content, not
+ * metadata). Each `listItem` is read as one `Key: value` pair in either of
+ * two shapes:
+ *
+ *   - Bold key:  `- **Status**: accepted`  (some MADR v2 authors)
+ *   - Plain key: `* Status: accepted`      (official MADR v2.1.2 template)
+ *
+ * Key normalization: trim → lowercase → spaces become hyphens
+ * (matches v4 frontmatter convention, e.g. "Decision Makers" →
+ * "decision-makers"). On duplicate keys, first occurrence wins.
+ *
+ * Returns null unless the list carries a recognized MADR key, so ordinary
+ * leading prose lists are not mistaken for metadata. (A leading list keyed by
+ * a recognized field is still treated as metadata even if its value reads
+ * prose-like, e.g. `Status: under discussion` — that position + key is
+ * overwhelmingly metadata; this is an intentional, bounded tradeoff.)
+ *
+ * Because the result is gated on MADR field names, callers using this as a
+ * generic list reader will get null for purely non-MADR lists.
+ */
+declare function extractListMetadata(ast: Root): Record<string, unknown> | null;
+
+interface DateIso8601Options extends Record<string, unknown> {
+    field: string;
+}
+declare const rule$7: Rule<DateIso8601Options>;
+
+interface FilenameFormatOptions extends Record<string, unknown> {
+    pattern: string;
+}
+declare const rule$6: Rule<FilenameFormatOptions>;
+
+interface NoBrokenLinksOptions extends Record<string, unknown> {
+}
+declare const rule$5: ProjectRule<NoBrokenLinksOptions>;
+
+interface NoDuplicateNumberingOptions extends Record<string, unknown> {
+}
+declare const rule$4: ProjectRule<NoDuplicateNumberingOptions>;
+
+interface NoNumberingGapOptions extends Record<string, unknown> {
+}
+declare const rule$3: ProjectRule<NoNumberingGapOptions>;
+
+interface RequiredSectionsOptions extends Record<string, unknown> {
+    sections: string[];
+    matchMode: 'exact' | 'startsWith';
+}
+declare const rule$2: Rule<RequiredSectionsOptions>;
+
+interface StatusEnumOptions extends Record<string, unknown> {
+    values: string[];
+    prefixValues: string[];
+    caseSensitive: boolean;
+}
+declare const rule$1: Rule<StatusEnumOptions>;
+
+interface SupersedesBidirectionalOptions extends Record<string, unknown> {
+}
+declare const rule: ProjectRule<SupersedesBidirectionalOptions>;
+
+declare namespace index {
+  export { rule$7 as dateIso8601, rule$6 as filenameFormat, rule$5 as noBrokenLinks, rule$4 as noDuplicateNumbering, rule$3 as noNumberingGap, rule$2 as requiredSections, rule$1 as statusEnum, rule as supersedesBidirectional };
+}
+
+declare const recommended: Record<string, RuleSeverity>;
+
+interface MadrLintConfig {
+    /** Preset configurations to extend (e.g. 'madr-lint:recommended'). */
+    extends?: string[];
+    /** MADR format version target. 'auto' = detect per-file. */
+    madrVersion?: MadrVersion | 'auto';
+    /** Directory containing ADR files. */
+    adrDir?: string;
+    /** Per-rule severity / options overrides. */
+    rules?: Record<string, RuleSeverity>;
+    /**
+     * Filename / path patterns to skip. Phase 1 supports exact basename,
+     * full relative path, path suffix, and trailing wildcard (e.g.
+     * `9999-*`). Full glob support is on the roadmap.
+     */
+    ignorePatterns?: string[];
+    /** Enable per-file content-hash cache. Default: true. */
+    cache?: boolean;
+    /** Cache directory. Default: '.madr-lint/cache'. */
+    cacheLocation?: string;
+}
+/**
+ * Helper for type-safe config files. Identity at runtime.
+ *
+ * Usage:
+ * ```typescript
+ * // madr-lint.config.ts
+ * import { defineConfig } from 'madr-lint';
+ * export default defineConfig({
+ *   extends: ['madr-lint:recommended'],
+ *   madrVersion: 'auto',
+ *   adrDir: 'docs/adr',
+ *   ignorePatterns: ['README.md', 'template.md'],
+ *   rules: {
+ *     'madr/filename-format': ['error', { pattern: '^[0-9]{4}-.+\\.md$' }],
+ *   },
+ * });
+ * ```
+ */
+declare function defineConfig(config: MadrLintConfig): MadrLintConfig;
+
+export { type AnyRule, type Diagnostic, type FileContext, INTERNAL_ERROR_RULE_NAME, type MadrLintConfig, type MadrVersion, type MdastNode, type MdastNodeType, type ParsedFile, type ProjectFile, type ProjectRule, type ProjectRuleContext, type Rule, type RuleContext, type RuleListeners, type RuleMeta, RuleOptionsError, type RuleSeverity, type RunRuleOptions, type Severity, buildProjectFile, defineConfig, extractListMetadata, isProjectRule, parseFile, recommended, index as rules, runRule, runRulesOnFile, runRulesOnProject };