@ijonis/geo-lint 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,267 @@
+/**
+ * @ijonis/geo-lint Configuration Types
+ */
+/** Content directory configuration */
+interface ContentPathConfig {
+    /** Relative path from project root, e.g. 'content/blog' */
+    dir: string;
+    /** Content type identifier */
+    type: 'blog' | 'page' | 'project';
+    /** URL prefix for permalink derivation, e.g. '/blog/' */
+    urlPrefix?: string;
+    /** Default locale when frontmatter has no locale field */
+    defaultLocale?: string;
+}
+/** GEO-specific configuration */
+interface GeoConfig {
+    /** Brand name for entity density rule, e.g. 'ACME Corp'. Empty = skip check */
+    brandName: string;
+    /** Primary city/location for entity density rule, e.g. 'Berlin'. Empty = skip check */
+    brandCity: string;
+    /** Path to geo-keywords markdown file, relative to project root. Empty = skip */
+    keywordsPath: string;
+}
+/** User-facing configuration (partial, with defaults applied) */
+interface GeoLintUserConfig {
+    /** Canonical site URL, e.g. 'https://example.com' (required) */
+    siteUrl: string;
+    /** Content directory configurations */
+    contentPaths?: ContentPathConfig[];
+    /** Static routes valid for link validation (e.g. ['/about', '/contact']) */
+    staticRoutes?: string[];
+    /** Image directories to scan, relative to project root */
+    imageDirectories?: string[];
+    /** Valid blog categories (empty = skip category-invalid rule) */
+    categories?: string[];
+    /** Slugs to fully exclude from linting */
+    excludeSlugs?: string[];
+    /** Content categories to fully exclude (e.g. 'legal') */
+    excludeCategories?: string[];
+    /** GEO-specific configuration */
+    geo?: Partial<GeoConfig>;
+    /** Rule severity overrides: 'off' disables a rule */
+    rules?: Record<string, 'error' | 'warning' | 'off'>;
+    /** Threshold overrides */
+    thresholds?: Partial<ThresholdConfig>;
+}
+/** Threshold configuration for validation rules */
+interface ThresholdConfig {
+    title: {
+        minLength: number;
+        maxLength: number;
+        warnLength: number;
+    };
+    description: {
+        minLength: number;
+        maxLength: number;
+        warnLength: number;
+    };
+    slug: {
+        maxLength: number;
+    };
+    content: {
+        minWordCount: number;
+        minReadabilityScore: number;
+    };
+}
+/** Fully resolved configuration with all defaults applied */
+interface GeoLintConfig {
+    siteUrl: string;
+    contentPaths: ContentPathConfig[];
+    staticRoutes: string[];
+    imageDirectories: string[];
+    categories: string[];
+    excludeSlugs: string[];
+    excludeCategories: string[];
+    geo: GeoConfig;
+    rules: Record<string, 'error' | 'warning' | 'off'>;
+    thresholds: ThresholdConfig;
+}
+
+/**
+ * @ijonis/geo-lint Core Types
+ * Shared interfaces for the SEO/GEO validation system
+ */
+type Severity = 'error' | 'warning';
+type ContentType = 'blog' | 'page' | 'project';
+/**
+ * Result of a single lint check
+ */
+interface LintResult {
+    /** Relative path: blog/my-post-slug */
+    file: string;
+    /** Field or area checked (e.g., 'title', 'body', 'links') */
+    field: string;
+    /** Rule identifier (e.g., 'title-too-long', 'geo-no-question-headings') */
+    rule: string;
+    /** Whether this blocks the build */
+    severity: Severity;
+    /** Human-readable error message */
+    message: string;
+    /** Optional actionable fix suggestion */
+    suggestion?: string;
+    /** Line number in MDX file if applicable */
+    line?: number;
+}
+/**
+ * Parsed content item combining frontmatter metadata and raw MDX body
+ */
+interface ContentItem {
+    title: string;
+    slug: string;
+    description: string;
+    permalink: string;
+    image?: string;
+    imageAlt?: string;
+    categories?: string[];
+    date?: string;
+    category?: string;
+    locale?: string;
+    translationKey?: string;
+    updatedAt?: string;
+    noindex?: boolean;
+    draft?: boolean;
+    /** Content type: blog, page, or project */
+    contentType: ContentType;
+    /** Full path to source file */
+    filePath: string;
+    /** Raw file content (frontmatter + body) */
+    rawContent: string;
+    /** Body content without frontmatter */
+    body: string;
+}
+/**
+ * Context passed to rules for cross-content validation
+ */
+interface RuleContext {
+    /** All content items (including excluded) for link/duplicate detection */
+    allContent: ContentItem[];
+    /** Set of all valid internal URL paths */
+    validSlugs: Set<string>;
+    /** Set of all valid image paths */
+    validImages: Set<string>;
+}
+/**
+ * A lint rule definition
+ */
+interface Rule {
+    /** Unique rule identifier */
+    name: string;
+    /** Whether violations block the build */
+    severity: Severity;
+    /** Rule implementation */
+    run: (item: ContentItem, context: RuleContext) => LintResult[];
+    /** Machine-readable fix strategy for AI coding agents */
+    fixStrategy?: string;
+    /** Rule category for grouping (seo, geo, content, technical, i18n) */
+    category?: string;
+}
+/**
+ * A global rule that validates project-wide concerns (not per-item)
+ */
+interface GlobalRule {
+    /** Unique rule identifier */
+    name: string;
+    /** Whether violations block the build */
+    severity: Severity;
+    /** Rule implementation (no item — validates global state) */
+    run: () => LintResult[];
+}
+/**
+ * Extracted heading from MDX content
+ */
+interface Heading {
+    level: number;
+    text: string;
+    line: number;
+}
+/**
+ * Extracted link from MDX content
+ */
+interface ExtractedLink {
+    url: string;
+    text: string;
+    line: number;
+    isInternal: boolean;
+    originalUrl: string;
+}
+/**
+ * Extracted image from MDX content
+ */
+interface ExtractedImage {
+    src: string;
+    alt: string;
+    line: number;
+    hasAlt: boolean;
+    source: 'frontmatter' | 'inline';
+}
+
+/**
+ * @ijonis/geo-lint Content Adapter Types
+ */
+
+/**
+ * Adapter interface for custom content sources.
+ * Implement this to integrate geo-lint with any CMS or content pipeline.
+ */
+interface ContentAdapter {
+    /** Load all content items from the source */
+    loadItems(projectRoot: string): ContentItem[] | Promise<ContentItem[]>;
+}
+/**
+ * Create an adapter from a simple function
+ */
+declare function createAdapter(fn: (projectRoot: string) => ContentItem[] | Promise<ContentItem[]>): ContentAdapter;
+
+/**
+ * @ijonis/geo-lint Configuration Loader
+ */
+
+/**
+ * Helper for TypeScript-aware config files. Provides autocomplete in user configs.
+ */
+declare function defineConfig(config: GeoLintUserConfig): GeoLintUserConfig;
+
+/**
+ * @ijonis/geo-lint MDX Content Adapter
+ * Scans directories for MDX/Markdown files and parses them with gray-matter
+ */
+
+/**
+ * Load all content items from configured content paths.
+ * Uses gray-matter for robust YAML frontmatter parsing.
+ */
+declare function loadContentItems(contentPaths: ContentPathConfig[], projectRoot: string): ContentItem[];
+
+/**
+ * @ijonis/geo-lint
+ * SEO and GEO (Generative Engine Optimization) linter for Markdown/MDX content
+ *
+ * The first open-source linter that checks your content for AI search visibility.
+ */
+
+/** Options for the lint() function */
+interface LintOptions {
+    /** Project root directory (defaults to cwd) */
+    projectRoot?: string;
+    /** Explicit config (skips file loading) */
+    config?: GeoLintUserConfig;
+    /** Custom content adapter (skips default MDX scanning) */
+    adapter?: ContentAdapter;
+    /** Global rules to run after per-item rules */
+    globalRules?: GlobalRule[];
+    /** Output format: 'pretty' for terminal, 'json' for machine consumption */
+    format?: 'pretty' | 'json';
+}
+/**
+ * Run the complete GEO lint process.
+ * Returns exit code: 0 for success (no errors), 1 for errors found.
+ */
+declare function lint(options?: LintOptions): Promise<number>;
+/**
+ * Run the linter and return raw results (no console output).
+ * Useful for programmatic integration.
+ */
+declare function lintQuiet(options?: LintOptions): Promise<LintResult[]>;
+
+export { type ContentAdapter, type ContentItem, type ContentPathConfig, type ContentType, type ExtractedImage, type ExtractedLink, type GeoConfig, type GeoLintConfig, type GeoLintUserConfig, type GlobalRule, type Heading, type LintOptions, type LintResult, type Rule, type RuleContext, type Severity, type ThresholdConfig, createAdapter, defineConfig, lint, lintQuiet, loadContentItems };

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @ijonis/geo-lint Configuration Types
+ */
+/** Content directory configuration */
+interface ContentPathConfig {
+    /** Relative path from project root, e.g. 'content/blog' */
+    dir: string;
+    /** Content type identifier */
+    type: 'blog' | 'page' | 'project';
+    /** URL prefix for permalink derivation, e.g. '/blog/' */
+    urlPrefix?: string;
+    /** Default locale when frontmatter has no locale field */
+    defaultLocale?: string;
+}
+/** GEO-specific configuration */
+interface GeoConfig {
+    /** Brand name for entity density rule, e.g. 'ACME Corp'. Empty = skip check */
+    brandName: string;
+    /** Primary city/location for entity density rule, e.g. 'Berlin'. Empty = skip check */
+    brandCity: string;
+    /** Path to geo-keywords markdown file, relative to project root. Empty = skip */
+    keywordsPath: string;
+}
+/** User-facing configuration (partial, with defaults applied) */
+interface GeoLintUserConfig {
+    /** Canonical site URL, e.g. 'https://example.com' (required) */
+    siteUrl: string;
+    /** Content directory configurations */
+    contentPaths?: ContentPathConfig[];
+    /** Static routes valid for link validation (e.g. ['/about', '/contact']) */
+    staticRoutes?: string[];
+    /** Image directories to scan, relative to project root */
+    imageDirectories?: string[];
+    /** Valid blog categories (empty = skip category-invalid rule) */
+    categories?: string[];
+    /** Slugs to fully exclude from linting */
+    excludeSlugs?: string[];
+    /** Content categories to fully exclude (e.g. 'legal') */
+    excludeCategories?: string[];
+    /** GEO-specific configuration */
+    geo?: Partial<GeoConfig>;
+    /** Rule severity overrides: 'off' disables a rule */
+    rules?: Record<string, 'error' | 'warning' | 'off'>;
+    /** Threshold overrides */
+    thresholds?: Partial<ThresholdConfig>;
+}
+/** Threshold configuration for validation rules */
+interface ThresholdConfig {
+    title: {
+        minLength: number;
+        maxLength: number;
+        warnLength: number;
+    };
+    description: {
+        minLength: number;
+        maxLength: number;
+        warnLength: number;
+    };
+    slug: {
+        maxLength: number;
+    };
+    content: {
+        minWordCount: number;
+        minReadabilityScore: number;
+    };
+}
+/** Fully resolved configuration with all defaults applied */
+interface GeoLintConfig {
+    siteUrl: string;
+    contentPaths: ContentPathConfig[];
+    staticRoutes: string[];
+    imageDirectories: string[];
+    categories: string[];
+    excludeSlugs: string[];
+    excludeCategories: string[];
+    geo: GeoConfig;
+    rules: Record<string, 'error' | 'warning' | 'off'>;
+    thresholds: ThresholdConfig;
+}
+
+/**
+ * @ijonis/geo-lint Core Types
+ * Shared interfaces for the SEO/GEO validation system
+ */
+type Severity = 'error' | 'warning';
+type ContentType = 'blog' | 'page' | 'project';
+/**
+ * Result of a single lint check
+ */
+interface LintResult {
+    /** Relative path: blog/my-post-slug */
+    file: string;
+    /** Field or area checked (e.g., 'title', 'body', 'links') */
+    field: string;
+    /** Rule identifier (e.g., 'title-too-long', 'geo-no-question-headings') */
+    rule: string;
+    /** Whether this blocks the build */
+    severity: Severity;
+    /** Human-readable error message */
+    message: string;
+    /** Optional actionable fix suggestion */
+    suggestion?: string;
+    /** Line number in MDX file if applicable */
+    line?: number;
+}
+/**
+ * Parsed content item combining frontmatter metadata and raw MDX body
+ */
+interface ContentItem {
+    title: string;
+    slug: string;
+    description: string;
+    permalink: string;
+    image?: string;
+    imageAlt?: string;
+    categories?: string[];
+    date?: string;
+    category?: string;
+    locale?: string;
+    translationKey?: string;
+    updatedAt?: string;
+    noindex?: boolean;
+    draft?: boolean;
+    /** Content type: blog, page, or project */
+    contentType: ContentType;
+    /** Full path to source file */
+    filePath: string;
+    /** Raw file content (frontmatter + body) */
+    rawContent: string;
+    /** Body content without frontmatter */
+    body: string;
+}
+/**
+ * Context passed to rules for cross-content validation
+ */
+interface RuleContext {
+    /** All content items (including excluded) for link/duplicate detection */
+    allContent: ContentItem[];
+    /** Set of all valid internal URL paths */
+    validSlugs: Set<string>;
+    /** Set of all valid image paths */
+    validImages: Set<string>;
+}
+/**
+ * A lint rule definition
+ */
+interface Rule {
+    /** Unique rule identifier */
+    name: string;
+    /** Whether violations block the build */
+    severity: Severity;
+    /** Rule implementation */
+    run: (item: ContentItem, context: RuleContext) => LintResult[];
+    /** Machine-readable fix strategy for AI coding agents */
+    fixStrategy?: string;
+    /** Rule category for grouping (seo, geo, content, technical, i18n) */
+    category?: string;
+}
+/**
+ * A global rule that validates project-wide concerns (not per-item)
+ */
+interface GlobalRule {
+    /** Unique rule identifier */
+    name: string;
+    /** Whether violations block the build */
+    severity: Severity;
+    /** Rule implementation (no item — validates global state) */
+    run: () => LintResult[];
+}
+/**
+ * Extracted heading from MDX content
+ */
+interface Heading {
+    level: number;
+    text: string;
+    line: number;
+}
+/**
+ * Extracted link from MDX content
+ */
+interface ExtractedLink {
+    url: string;
+    text: string;
+    line: number;
+    isInternal: boolean;
+    originalUrl: string;
+}
+/**
+ * Extracted image from MDX content
+ */
+interface ExtractedImage {
+    src: string;
+    alt: string;
+    line: number;
+    hasAlt: boolean;
+    source: 'frontmatter' | 'inline';
+}
+
+/**
+ * @ijonis/geo-lint Content Adapter Types
+ */
+
+/**
+ * Adapter interface for custom content sources.
+ * Implement this to integrate geo-lint with any CMS or content pipeline.
+ */
+interface ContentAdapter {
+    /** Load all content items from the source */
+    loadItems(projectRoot: string): ContentItem[] | Promise<ContentItem[]>;
+}
+/**
+ * Create an adapter from a simple function
+ */
+declare function createAdapter(fn: (projectRoot: string) => ContentItem[] | Promise<ContentItem[]>): ContentAdapter;
+
+/**
+ * @ijonis/geo-lint Configuration Loader
+ */
+
+/**
+ * Helper for TypeScript-aware config files. Provides autocomplete in user configs.
+ */
+declare function defineConfig(config: GeoLintUserConfig): GeoLintUserConfig;
+
+/**
+ * @ijonis/geo-lint MDX Content Adapter
+ * Scans directories for MDX/Markdown files and parses them with gray-matter
+ */
+
+/**
+ * Load all content items from configured content paths.
+ * Uses gray-matter for robust YAML frontmatter parsing.
+ */
+declare function loadContentItems(contentPaths: ContentPathConfig[], projectRoot: string): ContentItem[];
+
+/**
+ * @ijonis/geo-lint
+ * SEO and GEO (Generative Engine Optimization) linter for Markdown/MDX content
+ *
+ * The first open-source linter that checks your content for AI search visibility.
+ */
+
+/** Options for the lint() function */
+interface LintOptions {
+    /** Project root directory (defaults to cwd) */
+    projectRoot?: string;
+    /** Explicit config (skips file loading) */
+    config?: GeoLintUserConfig;
+    /** Custom content adapter (skips default MDX scanning) */
+    adapter?: ContentAdapter;
+    /** Global rules to run after per-item rules */
+    globalRules?: GlobalRule[];
+    /** Output format: 'pretty' for terminal, 'json' for machine consumption */
+    format?: 'pretty' | 'json';
+}
+/**
+ * Run the complete GEO lint process.
+ * Returns exit code: 0 for success (no errors), 1 for errors found.
+ */
+declare function lint(options?: LintOptions): Promise<number>;
+/**
+ * Run the linter and return raw results (no console output).
+ * Useful for programmatic integration.
+ */
+declare function lintQuiet(options?: LintOptions): Promise<LintResult[]>;
+
+export { type ContentAdapter, type ContentItem, type ContentPathConfig, type ContentType, type ExtractedImage, type ExtractedLink, type GeoConfig, type GeoLintConfig, type GeoLintUserConfig, type GlobalRule, type Heading, type LintOptions, type LintResult, type Rule, type RuleContext, type Severity, type ThresholdConfig, createAdapter, defineConfig, lint, lintQuiet, loadContentItems };