feat: Publish @chainproof/core as a fully documented public API with versioned changelog

[Nanle-code]

Overview

@chainproof/core is the engine that powers all of ChainProof's interfaces. As the plugin API and third-party integrations are added, the public API surface of this package becomes critical infrastructure. Currently there is no formal API documentation, no explicit public/private boundary, and no changelog. This issue tracks the work to make the core package production-ready as a public library.

Current State

• All exports from index.ts are public by default, but no contract exists about which are stable vs internal
• No JSDoc on any exported function or type
• No CHANGELOG.md
• No semantic versioning discipline (the package is at 1.0.0 but has never had a documented breaking change policy)
• TypeScript types are exported but not documented

Proposed Work

1. API Surface Audit

Categorize all current exports:

Export	Status	Notes
scan()	Public stable	Primary entry point
generateMarkdownReport()	Public stable
generateJSONReport()	Public stable
generateTableReport()	Public stable
isSlitherAvailable()	Public stable
parseSolidity()	Internal	Used by rules only
visit()	Internal	AST traversal utility
runSlither()	Internal

Mark internal exports with an @internal JSDoc tag and move to a separate internal/ directory.

2. JSDoc on All Public Exports

/**
 * Scans one or more Solidity files or directories for security vulnerabilities,
 * gas inefficiencies, and bad patterns.
 *
 * @param config - Scan configuration specifying targets, feature flags, and output options
 * @returns A ScanResult containing per-file findings and an aggregate summary
 *
 * @example
 * const result = await scan({ targets: ['contracts/'], useLLM: false });
 * console.log(result.summary.critical); // number of critical findings
 */
export async function scan(config: ScanConfig): Promise<ScanResult>

3. TypeDoc API Reference

Configure TypeDoc to generate an API reference site from JSDoc comments:

• Published to GitHub Pages at https://stellarchainproof.github.io/StellarChainproofs/api/
• Auto-built on every release via GitHub Actions

4. CHANGELOG.md

Adopt Keep a Changelog format. Backfill entries for existing functionality. Commit to Semantic Versioning: breaking changes bump major, new features bump minor, bug fixes bump patch.

5. Deprecation Policy

Document how deprecated APIs will be handled: deprecated in minor, removed in next major.

Acceptance Criteria

• All public exports identified and documented with JSDoc
• Internal exports moved to internal/ or marked @internal
• TypeDoc configured and generating output
• GitHub Actions workflow publishes docs to GitHub Pages on release
• CHANGELOG.md created with backfilled history
• package.json exports field set to only expose the public API
• README updated with full API reference link and quick-start examples

[ZuLu0890]

I would like to work on this issue

[madisonsc52-del]

Hi maintainer i can work on this, I'll make sure to work on the issue asap

[Chigybillionz]

Hello Maintainer!

I would like to work on this issue.Hello Maintainer!

I would like to work on this issue.

[Ebenezer199914]

i will like to work on this