@faircopy/core

Core engine for faircopy. Provides types, config loading, file resolution, and the rule runner. This package is for adapter and rule authors — most users should install faircopy instead.

Install

npm i @faircopy/core

Public API

loadConfig(cwd?)

Finds and loads faircopy.config.ts (or .js, .mjs, .cjs) via jiti. Throws ConfigError if no config is found.

import { loadConfig } from '@faircopy/core'
const { config, configPath } = await loadConfig(process.cwd())

loadConfigFile(filename) loads an exact config path with imports resolved relative to that file.

resolveFiles(config, cwd?)

Resolves file globs from config.files, respecting config.ignore and .gitignore.

Ignore comments

Suppress every rule for one source line with either directive:

// faircopy-ignore-next-line
<p>Intentional copy that would otherwise be reported.</p>

<p>Intentional copy.</p> {/* faircopy-ignore-line */}

Add comma-separated rule IDs to suppress only those rules:

// faircopy-ignore-next-line no-em-dash, no-weasel-words
<p>Intentional rule exceptions.</p>

The directives work with line, block, JSX, and HTML comment markers.

import { resolveFiles } from '@faircopy/core'
const files = await resolveFiles(config, cwd)

lintFile(filePath, source, adapters, rules)

Runs a set of resolved rules against a single file using the appropriate adapter.

import { lintFile } from '@faircopy/core'
const diagnostics = await lintFile(filePath, source, adapters, resolvedRules)

lintFileWithCoverage(filePath, source, adapters, rules)

Returns { diagnostics, coverage: { adapter, segments, characters } } from one extraction pass. adapter: null means the extension is unsupported. Zero segments/characters means no nonblank prose was extracted. Character counts use UTF-16 code units and include retained whitespace. lintFile() remains the diagnostics-only API for existing callers; use the coverage API when a clean result must also prove extraction scope.

parseSeverity(ruleConfig)

Parses a RuleConfig value into { severity, options }.

Key types

interface FaircopyConfig { files, ignore?, adapters?, rules, noGitignore?, concurrency? }
interface Adapter { name, extensions, extract(filePath, source) }
interface Rule<Opts> { id, description, check(input) }
interface Diagnostic { ruleId, severity, message, range, help?, suggest? }
interface ExtractedText { text, sourceMap, meta? }

See types.ts for the full schema.

Agent Output

@faircopy/core/reporting exposes reusable formatters for CLI, docs, and integrations:

import { formatAgentCompact, buildAgentJsonPayload } from '@faircopy/core/reporting'

formatAgentCompact() prints grouped diagnostics for coding agents. Snippets are enabled by default, character byte ranges are disabled by default, and both can be configured globally or per rule through output.agentCompact.

export default defineConfig({
  output: {
    agentCompact: {
      snippets: 'all',
      snippetChars: 140,
      chars: false,
      rules: {
        'no-em-dash': { snippets: 'first' },
      },
    },
  },
})