@iris-code/core

The analysis engine behind Iris Code. It scores source files for health, finds hardcoded secrets, security problems, duplicate code and maintainability issues, evaluates a quality gate, and maps how files import each other.

The same package runs inside the Iris Code extension for VS Code and its forks, the JetBrains plugin, the @iris-code/cli command line, cloud scans, and the Playground in the browser. The same file gets the same score and findings wherever it is analysed.

npm install @iris-code/core

Local refactor APIs (unpublished)

The local branch adds fileStructure, projectConventions, planRefactor and verifyRefactor. They consume source/config data and return native ranges, conventions, ranked suggestions and verification results without filesystem, network, parser dependencies or model calls. planSafeFix remains the single mechanical planner, including multiline edits; console.error is deliberately ineligible.

Plans and findings are separate contracts. Verification checks code-line improvement, packing, comment-only changes, imports, cycles, imported exports, public API changes and new findings across every changed source. Hosts own in-memory session baselines and git HEAD disclosure. The real-source suggestion review remains in progress, and reviewed omissions are explicit in coverage. Versions are unchanged; these APIs are not published or added to the Playground.

What it does

• Ten languages: TypeScript, JavaScript, Vue, Svelte, Go, Python, Ruby, C#, Java and Rust. Vue and Svelte components are analysed through their <script> blocks, with findings on the component's own line numbers.
• Health score and findings per file: function length, complexity, nesting, parameters, file size, debug prints, TODOs, any usage, unused code where it can be stated safely, file naming, and language-specific rules.
• Hardcoded secrets by variable name and by known token format, and security smells such as eval, SQL built by concatenation, disabled TLS verification and weak hashing.
• Duplicate code within and across files, with normalised token matching.
• Quality gate evaluation: a minimum health score plus optional caps on secrets, complexity, file length, security smells, suppressions, duplicate blocks and naming violations.
• Inline suppressions (// iris-ignore: rule -- reason), where a suppression without a reason is ignored and reported.
• Import graph for TypeScript, JavaScript, Vue, Svelte, Go, Python, Java, C# and Rust: which files import which, cycles, and imports that cannot be resolved, listed with a reason rather than guessed.

Design

• No I/O. Every function takes source text and configuration and returns data. Reading files, watching them and showing results is the host's job, which is why the same code runs in an editor, a terminal, a server and a browser.
• No AI model. Every result is deterministic: the same input always gives the same output.
• Honest about gaps. A file that cannot be parsed is marked parseFailed rather than scored as zero, and an import that cannot be resolved is listed with its reason.

Examples

Analyse one file:

const { analyseFile, DEFAULT_IRIS_CONFIG } = require('@iris-code/core')

const analysis = analyseFile(source, DEFAULT_IRIS_CONFIG, 'src/orders.ts')
console.log(analysis.healthScore)                    // 0-100
console.log(analysis.codeSmells.hardcodedSecrets)    // [{ line, message, ... }]

Evaluate a gate over several files:

const { analyseFile, evaluateGate, DEFAULT_IRIS_CONFIG } = require('@iris-code/core')

const files = paths.map(path => ({ path, analysis: analyseFile(read(path), DEFAULT_IRIS_CONFIG, path) }))
const gate = evaluateGate({ minScore: 70, maxSecrets: 0 }, files)
console.log(gate.passed, gate.failures)

Build an import graph and ask what a change reaches:

const { createModuleGraphIndex, graphImpact, describeGraphImpact } = require('@iris-code/core')

const graph = createModuleGraphIndex({
  knownFiles: ['app/page.tsx', 'lib/api.ts'],
  configFiles: [],
  sources: new Map([
    ['app/page.tsx', "import { request } from '../lib/api'"],
    ['lib/api.ts', 'export const request = () => {}'],
  ]),
}).graph()

const impact = graphImpact(graph, ['lib/api.ts'])
console.log(describeGraphImpact(impact.files['lib/api.ts']))   // "1 file imports this"

createModuleGraphIndex also accepts incremental updates (index.update([{ path, source }])), so a host can keep the graph current as files change.

Versioning

The package is at 0.x: minor versions can change the API, so pin a range such as ~0.4.0 if you depend on it outside Iris Code. Scores and findings follow the Iris Code release they ship with, and the changelog describes what changed.

Links

• Iris Code: iriscode.co
• Documentation: docs.iriscode.co
• Command line: @iris-code/cli

MIT licensed.

Local refactor prerequisites

On the local v1.36 branch, fileStructure(source, language) returns declaration and nested-block evidence for the ten supported languages. analyseFile adds optional inclusive { startLine, endLine } ranges to existing findings. Unproved boundaries are omitted, with structure refusals reported explicitly. This does not change existing metrics or scores. The rest of the refactor playbook remains in progress.