API and Programmatic Usage

This reference targets developers embedding design-lint in custom tooling.

Table of contents

• Quick start
• Linter class
• Helper functions
• Types
• Versioning and stability
• See also

Quick start

import {
  loadConfig,
  createLinter,
  getFormatter,
  applyFixes,
  createNodeEnvironment,
} from '@lapidist/design-lint';

async function main() {
  const config = await loadConfig(process.cwd());
  const env = createNodeEnvironment(config);
  const linter = createLinter(config, env);
  const { results } = await linter.lintTargets(['src/**/*.{ts,tsx}'], true);
  const formatter = await getFormatter('stylish');
  console.log(formatter(results));
  const fixed = applyFixes('color: var(--red);', results[0].messages);
  console.log(fixed);
}

main().catch(console.error);

API contract

Stable exports for programmatic integration:

• createLinter(config, env)
• createLintService(config, env)
• setupLinter(config, env)
• loadConfig(cwd, path?)
• defineConfig(config)
• getFormatter(name)
• applyFixes(text, messages)

Stable Linter methods:

• lintTargets(targets, fix?, ignore?)
• lintDocument(document, fix?)
• lintDocuments(documents, fix?, cache?)
• getTokenCompletions()

Linter class

Linter runs rules against provided documents.

import { createLinter, createNodeEnvironment } from '@lapidist/design-lint';

const env = createNodeEnvironment(config);
const linter = createLinter(config, env);
const { results } = await linter.lintTargets(['src/**/*.ts']);

Key methods:

• lintTargets(targets, fix?) – lint files or globs.
• lintDocument(document, fix?) – lint one preloaded document object.
• lintDocuments(documents, fix?, cache?) – lint multiple preloaded document objects.
• getTokenCompletions() – list available token paths grouped by theme.

Helper functions

• loadConfig(cwd, path?) – resolve configuration.
• defineConfig(config) – provide type checking for config files.
• getFormatter(name) – load a formatter by name or path.
• applyFixes(text, messages) – apply non-overlapping fixes.
• parseDtifTokens(input, options?) – run the canonical DTIF parser on a document, URL, or ParseInput record and receive flattened pointer tokens enriched with metadata and resolution snapshots.
• parseInlineDtifTokens(content, options?) – parse an inline DTIF string or buffer with optional virtual URI metadata.
• parseDtifTokenObject(document, options?) – serialise an in-memory token object and validate it through the DTIF parser.
• parseDtifTokensFromFile(path, options?) – parse a DTIF file from disk while capturing diagnostics and resolver output.
• flattenDesignTokens(tokens, options?) – return canonical flattened DTIF entries sourced from the parser cache. Use getTokenPath(token, transform?) to derive normalized paths for these records when emitting path-based identifiers.
• RuleContext#getDtifTokens(type?, theme?) – read the canonical DTIF tokens that back rule contexts without materializing compatibility views.
• RuleContext#getTokenPath(token) – derive the normalized path for a DTIF token using the configured name transform.
• TokenRegistry#getDtifTokenByPointer(pointer, theme?) / TokenRegistry#getDtifTokenByName(name, theme?) / TokenRegistry#getDtifTokens(theme?) – retrieve the cached DTIF entries that power the registry when parsing DTIF documents.
• indexDtifTokens(tokens) / createDtifNameIndex(tokens) – build pointer- based lookup maps for flattened DTIF tokens.
• DtifTokenRegistry(tokensByTheme, options?) – aggregate flattened DTIF tokens by theme with optional name transforms.
• parseDtifTokensFile(path) / readDtifTokensFile(path) – Node-focused helpers that parse DTIF files and either return flattened tokens or the parsed TokenDocument.
• DtifTokenParseError – error type that surfaces canonical DTIF diagnostics with file URIs and source ranges.

DTIF parsing helpers

design-lint embeds the Lapidist DTIF parser to validate documents against the official schema, resolve $ref pointers, and return flattened tokens in declaration order. Use parseDtifTokens for programmatic parsing and parseDtifTokensFromFile or the Node adapter helpers when reading from disk. Each API surfaces the full diagnostic bag from the parser so tooling can present precise feedback to users.

Types

design-lint ships with TypeScript definitions for Config, LintResult, RuleModule, and more:

import type { Config, LintResult, RuleModule } from '@lapidist/design-lint';

Versioning and stability

The project targets semantic versioning for public API changes. Functions documented here are intended as the stable integration surface. Experimental exports are marked with @experimental in the source and may change without notice.

See also

• Plugins
• Architecture overview