@org-press/lint 0.9.12

package/LICENSE

@@ -0,0 +1,29 @@
+GNU GENERAL PUBLIC LICENSE
+Version 2, June 1991
+
+Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+For the full license text, see: https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
+
+---
+
+Org-Press - Static site generator for org-mode files
+Copyright (C) 2024-2026
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

package/dist/index.js

@@ -0,0 +1,344 @@
+// src/plugin.ts
+import { CreateCommand } from "org-press";
+
+// src/utils.ts
+import * as fs from "fs";
+import * as path from "path";
+import { parse } from "uniorg-parse/lib/parser.js";
+function findOrgFiles(dir) {
+  const files = [];
+  if (!fs.existsSync(dir)) {
+    return files;
+  }
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== "node_modules" && !entry.name.startsWith(".")) {
+        files.push(...findOrgFiles(fullPath));
+      }
+    } else if (entry.name.endsWith(".org")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function extractBlocksFromFile(orgFilePath, projectRoot, options) {
+  const absolutePath = path.isAbsolute(orgFilePath) ? orgFilePath : path.join(projectRoot, orgFilePath);
+  const relativePath = path.relative(projectRoot, absolutePath);
+  const content = fs.readFileSync(absolutePath, "utf-8");
+  const lines = content.split("\n");
+  const ast = parse(content);
+  const blocks = [];
+  let blockIndex = 0;
+  const blockPositions = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const beginMatch = line.match(/^\s*#\+begin_src\s+(\w+)(.*)$/i);
+    if (beginMatch) {
+      const language = beginMatch[1].toLowerCase();
+      let name;
+      for (let j = i - 1; j >= 0; j--) {
+        const prevLine = lines[j].trim();
+        const nameMatch = prevLine.match(/^#\+name:\s*(.+)$/i);
+        if (nameMatch) {
+          name = nameMatch[1].trim();
+          break;
+        }
+        if (prevLine && !prevLine.startsWith("#")) break;
+      }
+      let endLine = i;
+      for (let k = i + 1; k < lines.length; k++) {
+        if (lines[k].match(/^\s*#\+end_src\s*$/i)) {
+          endLine = k;
+          break;
+        }
+      }
+      blockPositions.push({
+        startLine: i + 1,
+        // 1-based
+        endLine: endLine + 1,
+        // 1-based
+        name,
+        language
+      });
+    }
+  }
+  function walk(node) {
+    if (!node || typeof node !== "object") return;
+    const nodeObj = node;
+    if (nodeObj.type === "src-block") {
+      const position = blockPositions[blockIndex];
+      if (!position) {
+        blockIndex++;
+        return;
+      }
+      const language = nodeObj.language?.toLowerCase() || "";
+      if (options?.languages && options.languages.length > 0 && !options.languages.includes(language)) {
+        blockIndex++;
+        return;
+      }
+      blocks.push({
+        orgFilePath: relativePath,
+        blockIndex,
+        blockName: position.name,
+        code: nodeObj.value || "",
+        language,
+        startLine: position.startLine,
+        endLine: position.endLine
+      });
+      blockIndex++;
+    }
+    if (nodeObj.children && Array.isArray(nodeObj.children)) {
+      for (const child of nodeObj.children) {
+        walk(child);
+      }
+    }
+  }
+  walk(ast);
+  return blocks;
+}
+async function collectCodeBlocks(contentDir, projectRoot = process.cwd(), options) {
+  const absoluteContentDir = path.isAbsolute(contentDir) ? contentDir : path.join(projectRoot, contentDir);
+  let orgFiles = findOrgFiles(absoluteContentDir);
+  if (options?.files && options.files.length > 0) {
+    const patterns = options.files.map(
+      (f) => path.isAbsolute(f) ? f : path.join(projectRoot, f)
+    );
+    orgFiles = orgFiles.filter(
+      (file) => patterns.some((pattern) => {
+        if (pattern.endsWith(".org")) {
+          return file === pattern || file.endsWith(pattern);
+        }
+        return file.includes(pattern);
+      })
+    );
+  }
+  const allBlocks = [];
+  for (const orgFile of orgFiles) {
+    try {
+      const blocks = extractBlocksFromFile(orgFile, projectRoot, options);
+      allBlocks.push(...blocks);
+    } catch (error) {
+      console.warn(
+        `[lint] Warning: Failed to parse ${orgFile}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  return allBlocks;
+}
+function writeBlockContentBatch(updates, projectRoot = process.cwd()) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const update of updates) {
+    const filePath = update.block.orgFilePath;
+    if (!byFile.has(filePath)) {
+      byFile.set(filePath, []);
+    }
+    byFile.get(filePath).push(update);
+  }
+  for (const [filePath, fileUpdates] of byFile) {
+    fileUpdates.sort((a, b) => b.block.blockIndex - a.block.blockIndex);
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+    let fileContent = fs.readFileSync(absolutePath, "utf-8");
+    let lines = fileContent.split("\n");
+    for (const { block, newContent } of fileUpdates) {
+      const beginLineIndex = block.startLine - 1;
+      const endLineIndex = block.endLine - 1;
+      if (beginLineIndex < 0 || endLineIndex >= lines.length || beginLineIndex >= endLineIndex) {
+        console.warn(
+          `[lint] Warning: Invalid block position in ${filePath}: lines ${block.startLine}-${block.endLine}`
+        );
+        continue;
+      }
+      const beginLine = lines[beginLineIndex];
+      const endLine = lines[endLineIndex];
+      if (!beginLine.match(/^\s*#\+begin_src\s+\w+/i)) {
+        console.warn(
+          `[lint] Warning: Expected #+begin_src at line ${block.startLine} in ${filePath}`
+        );
+        continue;
+      }
+      if (!endLine.match(/^\s*#\+end_src\s*$/i)) {
+        console.warn(
+          `[lint] Warning: Expected #+end_src at line ${block.endLine} in ${filePath}`
+        );
+        continue;
+      }
+      const trimmedContent = newContent.replace(/\n$/, "");
+      const beforeBlock = lines.slice(0, beginLineIndex + 1);
+      const afterBlock = lines.slice(endLineIndex);
+      lines = [...beforeBlock, trimmedContent, ...afterBlock];
+    }
+    fs.writeFileSync(absolutePath, lines.join("\n"), "utf-8");
+  }
+}
+function findEslintConfig(projectRoot) {
+  const configFiles = [
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs",
+    // Legacy configs
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    ".eslintrc.json",
+    ".eslintrc"
+  ];
+  for (const configFile of configFiles) {
+    const configPath = path.join(projectRoot, configFile);
+    if (fs.existsSync(configPath)) {
+      return configPath;
+    }
+  }
+  return null;
+}
+
+// src/types.ts
+var LANGUAGE_EXTENSIONS = {
+  typescript: "ts",
+  ts: "ts",
+  tsx: "tsx",
+  javascript: "js",
+  js: "js",
+  jsx: "jsx",
+  json: "json",
+  css: "css",
+  scss: "scss",
+  less: "less",
+  html: "html",
+  yaml: "yaml",
+  yml: "yml",
+  markdown: "md",
+  md: "md",
+  graphql: "graphql",
+  gql: "graphql"
+};
+var LINT_LANGUAGES = [
+  "typescript",
+  "ts",
+  "tsx",
+  "javascript",
+  "js",
+  "jsx"
+];
+
+// src/command.ts
+function parseLintArgs(args) {
+  const options = {
+    fix: false,
+    languages: [],
+    files: []
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--fix" || arg === "-f") {
+      options.fix = true;
+    } else if (arg === "--languages" || arg === "-l") {
+      const next = args[++i];
+      if (next) {
+        options.languages = next.split(",").map((l) => l.trim().toLowerCase());
+      }
+    } else if (!arg.startsWith("-")) {
+      options.files.push(arg);
+    }
+  }
+  return options;
+}
+function getExtension(language) {
+  return LANGUAGE_EXTENSIONS[language.toLowerCase()] || "js";
+}
+async function runLint(args, ctx) {
+  const options = parseLintArgs(args);
+  let ESLint;
+  try {
+    const eslintModule = await import("eslint");
+    ESLint = eslintModule.ESLint;
+  } catch {
+    console.error("[lint] ESLint is not installed. Please install eslint:");
+    console.error("  npm install -D eslint");
+    return 1;
+  }
+  const configPath = findEslintConfig(ctx.projectRoot);
+  if (!configPath) {
+    console.warn("[lint] No ESLint configuration found. Using default settings.");
+  }
+  const languages = options.languages?.length ? options.languages : LINT_LANGUAGES;
+  const blocks = await collectCodeBlocks(ctx.contentDir, ctx.projectRoot, {
+    files: options.files?.length ? options.files : void 0,
+    languages
+  });
+  if (blocks.length === 0) {
+    console.log("[lint] No code blocks found to lint");
+    return 0;
+  }
+  const eslint = new ESLint({
+    cwd: ctx.projectRoot,
+    fix: options.fix
+  });
+  let errorCount = 0;
+  let warningCount = 0;
+  const updates = [];
+  for (const block of blocks) {
+    const ext = getExtension(block.language);
+    const virtualPath = block.blockName ? `${block.orgFilePath}#${block.blockName}.${ext}` : `${block.orgFilePath}#block-${block.blockIndex}.${ext}`;
+    try {
+      const results = await eslint.lintText(block.code, {
+        filePath: virtualPath
+      });
+      for (const result of results) {
+        for (const msg of result.messages) {
+          const orgLine = block.startLine + msg.line;
+          const severity = msg.severity === 2 ? "error" : "warning";
+          const ruleId = msg.ruleId ? ` (${msg.ruleId})` : "";
+          console.log(
+            `${block.orgFilePath}:${orgLine}:${msg.column} ${severity}: ${msg.message}${ruleId}`
+          );
+          if (msg.severity === 2) {
+            errorCount++;
+          } else {
+            warningCount++;
+          }
+        }
+        if (options.fix && result.output && result.output !== block.code) {
+          updates.push({ block, newContent: result.output.replace(/\n$/, "") });
+        }
+      }
+    } catch (error) {
+      const location = block.blockName ? `${block.orgFilePath}:${block.startLine} (${block.blockName})` : `${block.orgFilePath}:${block.startLine}`;
+      console.warn(
+        `[lint] Warning: Failed to lint ${location}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  if (updates.length > 0) {
+    writeBlockContentBatch(updates, ctx.projectRoot);
+    console.log(`[lint] Fixed ${updates.length} block(s)`);
+  }
+  if (errorCount > 0 || warningCount > 0) {
+    console.log(
+      `[lint] Found ${errorCount} error(s) and ${warningCount} warning(s) in ${blocks.length} block(s)`
+    );
+  } else {
+    console.log(`[lint] No issues found in ${blocks.length} block(s)`);
+  }
+  return errorCount > 0 ? 1 : 0;
+}
+
+// src/plugin.ts
+var lintPlugin = CreateCommand("lint", {
+  description: "Lint code blocks in org files using ESLint",
+  args: [
+    { name: "fix", type: "boolean", description: "Auto-fix problems" },
+    { name: "languages", type: "string", description: "Comma-separated list of languages" }
+  ],
+  execute: (args, ctx) => runLint(args._, ctx)
+});
+export {
+  LANGUAGE_EXTENSIONS,
+  LINT_LANGUAGES,
+  collectCodeBlocks,
+  findEslintConfig,
+  lintPlugin,
+  parseLintArgs,
+  runLint,
+  writeBlockContentBatch
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@org-press/lint",
+  "version": "0.9.12",
+  "description": "Lint code blocks in org files using ESLint",
+  "license": "GPL-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "org-press": ">=0.9.0"
+  },
+  "optionalDependencies": {
+    "eslint": "^8.0.0 || ^9.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "~5.7.3",
+    "uniorg": "^1.3.0",
+    "uniorg-parse": "^3.2.0",
+    "eslint": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "org-press": "0.9.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://orgp.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/org-press/org-press.git"
+  },
+  "bugs": {
+    "url": "https://github.com/org-press/org-press/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist"
+  }
+}

package/src/command.ts

@@ -0,0 +1,166 @@
+/**
+ * Lint Command Implementation
+ *
+ * Lints code blocks in org files using ESLint.
+ */
+
+import type { CommandContext } from "org-press";
+import { collectCodeBlocks, writeBlockContentBatch, findEslintConfig } from "./utils.js";
+import { LINT_LANGUAGES, LANGUAGE_EXTENSIONS, type LintOptions } from "./types.js";
+
+/**
+ * Parse command line arguments for lint command
+ */
+export function parseLintArgs(args: string[]): LintOptions {
+  const options: LintOptions = {
+    fix: false,
+    languages: [],
+    files: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--fix" || arg === "-f") {
+      options.fix = true;
+    } else if (arg === "--languages" || arg === "-l") {
+      const next = args[++i];
+      if (next) {
+        options.languages = next.split(",").map((l) => l.trim().toLowerCase());
+      }
+    } else if (!arg.startsWith("-")) {
+      // Positional argument - file pattern
+      options.files!.push(arg);
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Get file extension for a language
+ */
+function getExtension(language: string): string {
+  return LANGUAGE_EXTENSIONS[language.toLowerCase()] || "js";
+}
+
+/**
+ * Run the lint command
+ *
+ * @param args - Command line arguments
+ * @param ctx - CLI context
+ * @returns Exit code (0 for success, 1 if errors found)
+ */
+export async function runLint(
+  args: string[],
+  ctx: CommandContext
+): Promise<number> {
+  const options = parseLintArgs(args);
+
+  // Check if ESLint is available
+  let ESLint: typeof import("eslint").ESLint;
+  try {
+    const eslintModule = await import("eslint");
+    ESLint = eslintModule.ESLint;
+  } catch {
+    console.error("[lint] ESLint is not installed. Please install eslint:");
+    console.error("  npm install -D eslint");
+    return 1;
+  }
+
+  // Check for ESLint config
+  const configPath = findEslintConfig(ctx.projectRoot);
+  if (!configPath) {
+    console.warn("[lint] No ESLint configuration found. Using default settings.");
+  }
+
+  // Determine which languages to lint
+  const languages =
+    options.languages?.length ? options.languages : LINT_LANGUAGES;
+
+  // Collect blocks
+  const blocks = await collectCodeBlocks(ctx.contentDir, ctx.projectRoot, {
+    files: options.files?.length ? options.files : undefined,
+    languages,
+  });
+
+  if (blocks.length === 0) {
+    console.log("[lint] No code blocks found to lint");
+    return 0;
+  }
+
+  // Create ESLint instance
+  const eslint = new ESLint({
+    cwd: ctx.projectRoot,
+    fix: options.fix,
+  });
+
+  let errorCount = 0;
+  let warningCount = 0;
+  const updates: Array<{ block: (typeof blocks)[0]; newContent: string }> = [];
+
+  for (const block of blocks) {
+    const ext = getExtension(block.language);
+    // Use virtual filename for ESLint to apply correct rules
+    const virtualPath = block.blockName
+      ? `${block.orgFilePath}#${block.blockName}.${ext}`
+      : `${block.orgFilePath}#block-${block.blockIndex}.${ext}`;
+
+    try {
+      const results = await eslint.lintText(block.code, {
+        filePath: virtualPath,
+      });
+
+      for (const result of results) {
+        // Print messages
+        for (const msg of result.messages) {
+          // Map line number back to org file
+          const orgLine = block.startLine + msg.line;
+          const severity = msg.severity === 2 ? "error" : "warning";
+          const ruleId = msg.ruleId ? ` (${msg.ruleId})` : "";
+
+          console.log(
+            `${block.orgFilePath}:${orgLine}:${msg.column} ${severity}: ${msg.message}${ruleId}`
+          );
+
+          if (msg.severity === 2) {
+            errorCount++;
+          } else {
+            warningCount++;
+          }
+        }
+
+        // Collect fixes if --fix and there's output
+        if (options.fix && result.output && result.output !== block.code) {
+          updates.push({ block, newContent: result.output.replace(/\n$/, "") });
+        }
+      }
+    } catch (error) {
+      const location = block.blockName
+        ? `${block.orgFilePath}:${block.startLine} (${block.blockName})`
+        : `${block.orgFilePath}:${block.startLine}`;
+      console.warn(
+        `[lint] Warning: Failed to lint ${location}: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
+  // Write fixes
+  if (updates.length > 0) {
+    writeBlockContentBatch(updates, ctx.projectRoot);
+    console.log(`[lint] Fixed ${updates.length} block(s)`);
+  }
+
+  // Summary
+  if (errorCount > 0 || warningCount > 0) {
+    console.log(
+      `[lint] Found ${errorCount} error(s) and ${warningCount} warning(s) in ${blocks.length} block(s)`
+    );
+  } else {
+    console.log(`[lint] No issues found in ${blocks.length} block(s)`);
+  }
+
+  return errorCount > 0 ? 1 : 0;
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @org-press/lint
+ *
+ * Lint code blocks in org files using ESLint.
+ *
+ * This package provides the `orgp lint` CLI command plugin.
+ *
+ * @example
+ * ```typescript
+ * // .org-press/config.ts
+ * import { lintPlugin } from '@org-press/lint';
+ *
+ * export default {
+ *   contentDir: 'content',
+ *   plugins: [lintPlugin],
+ * };
+ * ```
+ */
+
+// Plugin export
+export { lintPlugin } from "./plugin.js";
+
+// Command export (for programmatic use)
+export { runLint, parseLintArgs } from "./command.js";
+
+// Type exports
+export type { CollectedBlock, CollectOptions, LintOptions } from "./types.js";
+
+// Constant exports
+export { LANGUAGE_EXTENSIONS, LINT_LANGUAGES } from "./types.js";
+
+// Utility exports (for advanced use cases)
+export { collectCodeBlocks, writeBlockContentBatch, findEslintConfig } from "./utils.js";

package/src/plugin.ts

@@ -0,0 +1,30 @@
+/**
+ * Lint Plugin
+ *
+ * Provides the `orgp lint` command for linting code blocks with ESLint.
+ */
+
+import { CreateCommand } from "org-press";
+import type { ParsedArgs, CommandContext } from "org-press";
+import { runLint } from "./command.js";
+
+/**
+ * Lint plugin
+ *
+ * Registers the `lint` CLI command for linting JavaScript/TypeScript
+ * code blocks in org files using ESLint.
+ *
+ * Usage:
+ *   orgp lint                     # Lint all JS/TS blocks
+ *   orgp lint --fix               # Auto-fix problems
+ *   orgp lint --languages ts,tsx  # Lint only TypeScript blocks
+ *   orgp lint content/utils.org   # Lint specific file
+ */
+export const lintPlugin = CreateCommand("lint", {
+  description: "Lint code blocks in org files using ESLint",
+  args: [
+    { name: "fix", type: "boolean", description: "Auto-fix problems" },
+    { name: "languages", type: "string", description: "Comma-separated list of languages" },
+  ],
+  execute: (args: ParsedArgs, ctx: CommandContext) => runLint(args._, ctx),
+});

package/src/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Types for @org-press/lint
+ */
+
+/**
+ * A collected code block from an org file
+ */
+export interface CollectedBlock {
+  /** Relative path to the org file */
+  orgFilePath: string;
+  /** 0-based index of the block in the file */
+  blockIndex: number;
+  /** Block name from #+NAME: directive */
+  blockName?: string;
+  /** The source code content */
+  code: string;
+  /** Block language (e.g., "typescript", "javascript") */
+  language: string;
+  /** 1-based line number where the block starts (#+begin_src line) */
+  startLine: number;
+  /** 1-based line number where the block ends (#+end_src line) */
+  endLine: number;
+}
+
+/**
+ * Options for collecting code blocks
+ */
+export interface CollectOptions {
+  /** Filter by file path patterns */
+  files?: string[];
+  /** Filter by languages */
+  languages?: string[];
+}
+
+/**
+ * Options for the lint command
+ */
+export interface LintOptions {
+  /** Auto-fix problems */
+  fix?: boolean;
+  /** Filter by languages */
+  languages?: string[];
+  /** Filter by file patterns */
+  files?: string[];
+}
+
+/**
+ * Language to file extension mapping
+ */
+export const LANGUAGE_EXTENSIONS: Record<string, string> = {
+  typescript: "ts",
+  ts: "ts",
+  tsx: "tsx",
+  javascript: "js",
+  js: "js",
+  jsx: "jsx",
+  json: "json",
+  css: "css",
+  scss: "scss",
+  less: "less",
+  html: "html",
+  yaml: "yaml",
+  yml: "yml",
+  markdown: "md",
+  md: "md",
+  graphql: "graphql",
+  gql: "graphql",
+};
+
+/**
+ * Languages that can be linted with ESLint
+ */
+export const LINT_LANGUAGES = [
+  "typescript",
+  "ts",
+  "tsx",
+  "javascript",
+  "js",
+  "jsx",
+];

package/src/utils.ts

@@ -0,0 +1,319 @@
+/**
+ * Utilities for @org-press/lint
+ *
+ * Block collection, writing, and config loading functions.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse } from "uniorg-parse/lib/parser.js";
+import type { OrgData } from "uniorg";
+import type { CollectedBlock, CollectOptions } from "./types.js";
+
+/**
+ * Find all org files recursively in a directory
+ */
+function findOrgFiles(dir: string): string[] {
+  const files: string[] = [];
+
+  if (!fs.existsSync(dir)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      // Skip node_modules and hidden directories
+      if (entry.name !== "node_modules" && !entry.name.startsWith(".")) {
+        files.push(...findOrgFiles(fullPath));
+      }
+    } else if (entry.name.endsWith(".org")) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Extract code blocks from a single org file
+ */
+function extractBlocksFromFile(
+  orgFilePath: string,
+  projectRoot: string,
+  options?: CollectOptions
+): CollectedBlock[] {
+  const absolutePath = path.isAbsolute(orgFilePath)
+    ? orgFilePath
+    : path.join(projectRoot, orgFilePath);
+  const relativePath = path.relative(projectRoot, absolutePath);
+  const content = fs.readFileSync(absolutePath, "utf-8");
+  const lines = content.split("\n");
+  const ast = parse(content) as OrgData;
+
+  const blocks: CollectedBlock[] = [];
+  let blockIndex = 0;
+
+  // Find block positions and names by scanning raw content
+  const blockPositions: Array<{
+    startLine: number;
+    endLine: number;
+    name?: string;
+    language: string;
+  }> = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const beginMatch = line.match(/^\s*#\+begin_src\s+(\w+)(.*)$/i);
+
+    if (beginMatch) {
+      const language = beginMatch[1].toLowerCase();
+
+      // Look backwards for #+NAME: directive
+      let name: string | undefined;
+      for (let j = i - 1; j >= 0; j--) {
+        const prevLine = lines[j].trim();
+        const nameMatch = prevLine.match(/^#\+name:\s*(.+)$/i);
+        if (nameMatch) {
+          name = nameMatch[1].trim();
+          break;
+        }
+        // Stop looking if we hit a non-comment, non-empty line
+        if (prevLine && !prevLine.startsWith("#")) break;
+      }
+
+      // Find matching #+end_src
+      let endLine = i;
+      for (let k = i + 1; k < lines.length; k++) {
+        if (lines[k].match(/^\s*#\+end_src\s*$/i)) {
+          endLine = k;
+          break;
+        }
+      }
+
+      blockPositions.push({
+        startLine: i + 1, // 1-based
+        endLine: endLine + 1, // 1-based
+        name,
+        language,
+      });
+    }
+  }
+
+  // Walk AST and match blocks with their positions
+  function walk(node: unknown): void {
+    if (!node || typeof node !== "object") return;
+
+    const nodeObj = node as Record<string, unknown>;
+
+    if (nodeObj.type === "src-block") {
+      const position = blockPositions[blockIndex];
+      if (!position) {
+        blockIndex++;
+        return;
+      }
+
+      const language = (nodeObj.language as string)?.toLowerCase() || "";
+
+      // Filter by language if specified
+      if (
+        options?.languages &&
+        options.languages.length > 0 &&
+        !options.languages.includes(language)
+      ) {
+        blockIndex++;
+        return;
+      }
+
+      blocks.push({
+        orgFilePath: relativePath,
+        blockIndex,
+        blockName: position.name,
+        code: (nodeObj.value as string) || "",
+        language,
+        startLine: position.startLine,
+        endLine: position.endLine,
+      });
+
+      blockIndex++;
+    }
+
+    // Recurse into children
+    if (nodeObj.children && Array.isArray(nodeObj.children)) {
+      for (const child of nodeObj.children) {
+        walk(child);
+      }
+    }
+  }
+
+  walk(ast);
+  return blocks;
+}
+
+/**
+ * Collect all code blocks from a content directory
+ *
+ * @param contentDir - Content directory to scan
+ * @param projectRoot - Project root directory
+ * @param options - Collection options
+ * @returns Array of collected code blocks
+ */
+export async function collectCodeBlocks(
+  contentDir: string,
+  projectRoot: string = process.cwd(),
+  options?: CollectOptions
+): Promise<CollectedBlock[]> {
+  const absoluteContentDir = path.isAbsolute(contentDir)
+    ? contentDir
+    : path.join(projectRoot, contentDir);
+
+  // Find all org files
+  let orgFiles = findOrgFiles(absoluteContentDir);
+
+  // Filter by file patterns if specified
+  if (options?.files && options.files.length > 0) {
+    const patterns = options.files.map((f) =>
+      path.isAbsolute(f) ? f : path.join(projectRoot, f)
+    );
+
+    orgFiles = orgFiles.filter((file) =>
+      patterns.some((pattern) => {
+        // Support both exact match and contains match
+        if (pattern.endsWith(".org")) {
+          return file === pattern || file.endsWith(pattern);
+        }
+        return file.includes(pattern);
+      })
+    );
+  }
+
+  const allBlocks: CollectedBlock[] = [];
+
+  // Process each file
+  for (const orgFile of orgFiles) {
+    try {
+      const blocks = extractBlocksFromFile(orgFile, projectRoot, options);
+      allBlocks.push(...blocks);
+    } catch (error) {
+      console.warn(
+        `[lint] Warning: Failed to parse ${orgFile}: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
+  return allBlocks;
+}
+
+/**
+ * Batch write multiple block updates to minimize file I/O
+ *
+ * Updates are grouped by file and applied in reverse order
+ * (to preserve line numbers for earlier blocks in the same file)
+ *
+ * @param updates - Array of {block, newContent} pairs
+ * @param projectRoot - Project root directory
+ */
+export function writeBlockContentBatch(
+  updates: Array<{ block: CollectedBlock; newContent: string }>,
+  projectRoot: string = process.cwd()
+): void {
+  // Group updates by file
+  const byFile = new Map<string, Array<{ block: CollectedBlock; newContent: string }>>();
+
+  for (const update of updates) {
+    const filePath = update.block.orgFilePath;
+    if (!byFile.has(filePath)) {
+      byFile.set(filePath, []);
+    }
+    byFile.get(filePath)!.push(update);
+  }
+
+  // Process each file
+  for (const [filePath, fileUpdates] of byFile) {
+    // Sort by blockIndex in reverse order so we can apply changes
+    // from the end of the file backwards (preserving line numbers)
+    fileUpdates.sort((a, b) => b.block.blockIndex - a.block.blockIndex);
+
+    const absolutePath = path.isAbsolute(filePath)
+      ? filePath
+      : path.join(projectRoot, filePath);
+
+    let fileContent = fs.readFileSync(absolutePath, "utf-8");
+    let lines = fileContent.split("\n");
+
+    for (const { block, newContent } of fileUpdates) {
+      const beginLineIndex = block.startLine - 1;
+      const endLineIndex = block.endLine - 1;
+
+      // Validate
+      if (
+        beginLineIndex < 0 ||
+        endLineIndex >= lines.length ||
+        beginLineIndex >= endLineIndex
+      ) {
+        console.warn(
+          `[lint] Warning: Invalid block position in ${filePath}: lines ${block.startLine}-${block.endLine}`
+        );
+        continue;
+      }
+
+      const beginLine = lines[beginLineIndex];
+      const endLine = lines[endLineIndex];
+
+      if (!beginLine.match(/^\s*#\+begin_src\s+\w+/i)) {
+        console.warn(
+          `[lint] Warning: Expected #+begin_src at line ${block.startLine} in ${filePath}`
+        );
+        continue;
+      }
+
+      if (!endLine.match(/^\s*#\+end_src\s*$/i)) {
+        console.warn(
+          `[lint] Warning: Expected #+end_src at line ${block.endLine} in ${filePath}`
+        );
+        continue;
+      }
+
+      // Replace content
+      const trimmedContent = newContent.replace(/\n$/, "");
+      const beforeBlock = lines.slice(0, beginLineIndex + 1);
+      const afterBlock = lines.slice(endLineIndex);
+      lines = [...beforeBlock, trimmedContent, ...afterBlock];
+    }
+
+    fs.writeFileSync(absolutePath, lines.join("\n"), "utf-8");
+  }
+}
+
+/**
+ * Check if ESLint flat config exists
+ *
+ * @param projectRoot - Project root directory
+ * @returns Path to ESLint config if found, null otherwise
+ */
+export function findEslintConfig(projectRoot: string): string | null {
+  const configFiles = [
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs",
+    // Legacy configs
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    ".eslintrc.json",
+    ".eslintrc",
+  ];
+
+  for (const configFile of configFiles) {
+    const configPath = path.join(projectRoot, configFile);
+    if (fs.existsSync(configPath)) {
+      return configPath;
+    }
+  }
+
+  return null;
+}