@codeconscience/core

Convention and constraint discovery engine for CodeConscience.

The library that powers the codeconscience CLI. Use it directly when you need programmatic access to convention/constraint discovery without going through the CLI surface.

Install

npm install @codeconscience/core
# or
pnpm add @codeconscience/core

Requires Node.js ≥ 18. Native dependency: better-sqlite3.

Quick example

import {
  Store,
  incrementalIndex,
  detectConventions,
  detectConstraints,
  detectRationale,
  buildProjectContract,
  exportToClaudeMd,
} from '@codeconscience/core';

const projectRoot = '/path/to/your/project';

const storeResult = Store.open(projectRoot);
if (!storeResult.success) throw storeResult.error;
const store = storeResult.value;

// 1. Index source files (incremental — only re-parses changed files)
const indexResult = incrementalIndex(projectRoot, store);
if (!indexResult.success) throw indexResult.error;

// 2. Run analyzers
detectConventions(store);
detectConstraints(store, projectRoot);
detectRationale(store, projectRoot);

// 3. Build a portable contract and export
const contract = buildProjectContract(store, 'my-project');
exportToClaudeMd(contract, projectRoot);

store.close();

What's exported

• Store — SQLite-backed persistence layer (Store.open, Store.openMemory)
• Indexing — incrementalIndex, scanProject, indexFile, indexAbsolutePath
• Analyzers — detectConventions, detectConstraints, detectRationale
• Contract + export — buildProjectContract, exportToYaml, exportToClaudeMd, exportToCursorRules, exportToCopilotInstructions, exportToHumanReadable, exportToDashboard
• Violation checking — checkViolations, checkFile
• Utilities — classifyName, matchesNamingPattern, convertToPattern, discoverFiles, Result/ok/err/CodeConscienceError, logger
• Types — ConventionRule, ConstraintRule, DesignRationale, Violation, ProjectContract, SymbolInfo, ImportInfo, etc.

See the main repo README for design principles and a feature overview.

License

Released under the PolyForm Noncommercial License 1.0.0. Free for personal, hobby, research, educational, and non-profit use. Commercial use requires a separate license.