ZemDomu Core

https://github.com/zemdomu/zemdomu-core
Admin
ZemDomu Core is a static analysis engine for semantic accessibility and HTML structure across HTML,...
Tokens:11,656
Snippets:109
Trust Score:4.1
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install and build ZemDomu Core

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Run these commands from the core package directory to install dependencies and build the project.

```bash
cd packages/ZemDomu-Core
npm install
npm run build
```

--------------------------------

### Install ZemDomu with npm or yarn

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Install the library using either npm or yarn. The commands are shown as alternatives in the same installation block.

```bash
npm install zemdomu
# or
yarn add zemdomu
```

--------------------------------

### Custom rule example (noFooDiv)

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Example custom rule that flags <foo> elements. Export an object with name, test, and message properties.

```JavaScript
// my-rule.js
module.exports = {
  name: "noFooDiv",
  test: node => node.type === "element" && node.tagName === "foo",
  message: "<foo> is not allowed"
};
```

--------------------------------

### Example enabling rule severities

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Shows how to configure rule severities in the lint() options. Here, requireAltText is set to 'warning' and uniqueIds to 'error'.

```ts
const results = lint(html, {
  rules: { requireAltText: "warning", uniqueIds: "error" }
});
```

--------------------------------

### Example diagnostic output

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Shows the pretty output format: file path, line and column, rule code, and message. The rule code ZMD004 indicates a missing alt attribute on an img tag.

```text
Card.tsx:3:5 ZMD004: <img> tag missing alt attribute
```

--------------------------------

### Import and use lint and ProjectLinter

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Shows the primary entry point for the zemdomu package. Use lint() for a single in-memory source and ProjectLinter for file or project analysis. Subpath imports like 'zemdomu/linter' are deprecated.

```ts
import { lint, ProjectLinter } from "zemdomu";

const inMemoryResults = lint(source, { filePath: "src/Card.tsx" });
const project = new ProjectLinter({ crossComponentAnalysis: true });
const projectResults = await project.lintFiles(["src/Card.tsx"]);
const semanticGraph = await project.buildSemanticGraph(["src/Card.tsx"]);
const pageModel = await project.buildPageModel(["src/AppLayout.tsx"]);
const pageDiagnostics = await project.lintPageDiagnostics(["src/AppLayout.tsx"]);
```

--------------------------------

### CLI custom rules and performance commands

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Commands to set up a custom rules directory, copy a rule file, and run the CLI with custom rules or performance diagnostics.

```Bash
mkdir -p custom-rules
cp my-rule.js custom-rules/my-rule.js
npx zemdomu file.html --custom custom-rules/my-rule.js
npx zemdomu "src/**/*.{html,jsx,tsx,vue}" --perf --perf-slowest
```

--------------------------------

### new ProjectLinter(options?: ProjectLinterOptions)

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Creates a project linter instance for file or project analysis.

```APIDOC
## new ProjectLinter(options?: ProjectLinterOptions)

### Description
Creates a project linter for file or project analysis. Supports cross-component analysis and semantic graph building.

### Method
Constructor

### Endpoint
`new ProjectLinter(options?)`

### Parameters
- `options.crossComponentAnalysis` (boolean) - Optional - Enable cross-component analysis.

### Request Example
```ts
const project = new ProjectLinter({ crossComponentAnalysis: true });
```
```

--------------------------------

### createVueFileRouteAdapter()

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Creates a route adapter for Vue filesystem conventions.

```APIDOC
## createVueFileRouteAdapter()

### Description
Creates a route adapter for Vue filesystem conventions to infer route identity for page models.

### Method
Function call

### Endpoint
`createVueFileRouteAdapter()`

### Request Example
```ts
const adapter = createVueFileRouteAdapter();
```
```

--------------------------------

### project.lintFiles(files: string[]): Promise<LintResult[]>

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Lints a list of files in the project and returns lint results.

```APIDOC
## project.lintFiles(files: string[]): Promise<LintResult[]>

### Description
Lints a list of files in the project and returns lint results.

### Method
Async method

### Endpoint
`project.lintFiles(files)`

### Parameters
- `files` (string[]) - Required - Array of file paths to lint.

### Request Example
```ts
const projectResults = await project.lintFiles(["src/Card.tsx"]);
```
```

--------------------------------

### createReactFileRouteAdapter()

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Creates a route adapter for React filesystem conventions.

```APIDOC
## createReactFileRouteAdapter()

### Description
Creates a route adapter for React filesystem conventions to infer route identity for page models.

### Method
Function call

### Endpoint
`createReactFileRouteAdapter()`

### Request Example
```ts
const adapter = createReactFileRouteAdapter();
```
```

--------------------------------

### Run zemdomu check with pretty, json, and sarif formats

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Use these CLI commands to lint files matching the given glob patterns and output diagnostics in one of three formats. 'pretty' is the default and writes readable diagnostics to stderr; 'json' and 'sarif' write only machine-readable JSON to stdout, with operational and invocation errors always going to stderr. The CLI exits with 0 when no diagnostics are emitted, 1 when diagnostics are emitted, and 2 for invalid CLI usage.

```bash
zemdomu check "src/**/*.{html,jsx,tsx,vue}" --format pretty
zemdomu check "src/**/*.{html,jsx,tsx,vue}" --format json
zemdomu check "src/**/*.{html,jsx,tsx,vue}" --format sarif
```

--------------------------------

### Adapt and serialize diagnostics with toZemDomuDiagnostic and serializeZemDomuDiagnostics

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Use toZemDomuDiagnostic to convert legacy LintResult objects into canonical ZemDomuDiagnostic objects, then serializeZemDomuDiagnostics to output them as JSON. The adapter requires result.filePath or context.sourceFile and throws if neither is available; it does not mutate the legacy result. Lines and columns are zero-based, and missing legacy severity defaults to 'error' unless defaultSeverity is provided.

```typescript
import {
  lint,
  serializeZemDomuDiagnostics,
  toZemDomuDiagnostic,
} from "zemdomu";

const results = lint(source, { filePath: "src/Card.tsx" });
const diagnostics = results.map((result) =>
  toZemDomuDiagnostic(result, { sourceFile: "src/Card.tsx" })
);
console.log(serializeZemDomuDiagnostics(diagnostics, 2));
```

--------------------------------

### project.buildPageModel(files: string[]): Promise<PageModel>

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Builds a page model from the given files, composing graph output into page-scoped facts.

```APIDOC
## project.buildPageModel(files: string[]): Promise<PageModel>

### Description
Composes graph output into page-scoped component trees and ordered heading, landmark, section, navigation, and document-ID facts. Requires `pages` option for certain route identity or a route adapter.

### Method
Async method

### Endpoint
`project.buildPageModel(files)`

### Parameters
- `files` (string[]) - Required - Array of file paths to analyze.

### Request Example
```ts
const pageModel = await project.buildPageModel(["src/AppLayout.tsx"]);
```

### Response
#### Success Response
- Returns a page model with page-scoped component trees and ordered facts. Route identity may be unknown if no adapter is provided.
```

--------------------------------

### Run ZemDomu check with npx

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Scans source files matching the glob pattern for semantic accessibility issues. Exits with code 1 when diagnostics are found, making it suitable for CI. Output is pretty-printed and includes rule codes.

```bash
npx zemdomu check "src/**/*.{html,jsx,tsx,vue}" --format pretty
```

--------------------------------

### project.buildSemanticGraph(files: string[]): Promise<SemanticGraph>

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Builds a semantic graph from the given files, following supported imports and returning a deterministic graph.

```APIDOC
## project.buildSemanticGraph(files: string[]): Promise<SemanticGraph>

### Description
Builds a semantic graph from the given files. Follows supported local React/JSX/TSX and Vue imports and returns a public schema 1.0 graph with deterministic IDs and array order.

### Method
Async method

### Endpoint
`project.buildSemanticGraph(files)`

### Parameters
- `files` (string[]) - Required - Array of file paths to analyze.

### Request Example
```ts
const semanticGraph = await project.buildSemanticGraph(["src/Card.tsx"]);
```

### Response
#### Success Response
- Returns a semantic graph object with schema version 1.0. Contains source-backed files, components, imports, composition usages, headings, navigation landmarks, list items, sections, and static document IDs with zero-based locations. Each component exposes a `semanticOutput` with an inferred native root and evidence path.
```

--------------------------------

### Inspect a single route with zemdomu inspect

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Use the inspect command to compose one route from an explicit entry file. Requiring the route-to-entry mapping keeps router conventions outside Core and makes the result reproducible. Page inspection prints the nested component path, ordered semantic facts, source locations, and any unresolved or traversal-boundary unknowns.

```bash
zemdomu inspect "/products/[id]" --entry "src/AppLayout.tsx"
```

--------------------------------

### Lint HTML with lint() and requireAltText rule

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Imports the lint function, lints an HTML string with the requireAltText rule enabled, and logs the results. The output shows a diagnostic for the missing alt attribute.

```ts
import { lint } from "zemdomu";

const html = "<img>";
const results = lint(html, { rules: { requireAltText: true } });

console.log(results);
// [
//   {
//     line: 0,
//     column: 0,
//     message: "<img> tag missing alt attribute",
//     rule: "requireAltText"
//   }
// ]
```

--------------------------------

### Check public repository safety

Source: https://github.com/zemdomu/zemdomu-core/blob/main/PUBLIC_REPOSITORY_POLICY.md

Run this command from the canonical ZemDomu monorepo root to check that the repository contains no sensitive information before publishing.

```sh
node scripts/check-public-repo-safety.mjs --package core
```

--------------------------------

### Inspect semantic graph with zemdomu graph

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Use the graph command to inspect the deterministic semantic graph for one or more entry files. It follows supported local React, JSX, TSX, and Vue imports and groups source files, components, rendered semantic nodes, and explicit unknown analysis boundaries in readable sections.

```bash
zemdomu graph "src/AppLayout.tsx"
zemdomu graph "src/pages/**/*.{tsx,vue}" --cross-depth 4
```

--------------------------------

### CLI cross-component analysis command

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Runs the ZemDomu CLI with cross-component analysis enabled and a depth of 2 on JSX, TSX, and Vue files. Use --cross to enable and --cross-depth to limit traversal depth.

```Bash
npx zemdomu "src/**/*.{jsx,tsx,vue}" --cross --cross-depth 2
```

--------------------------------

### Helper utilities import

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Imports helper functions and types for advanced rule development, including HTML parsing, AST visiting, and attribute inspection.

```TypeScript
import {
  parseHtml,
  visitHtml,
  getAttr,
  getJsxAttr,
  getJsxAttribute,
  getJsxAttributeState,
  getJsxExpressionState,
  getTag,
  isJsxExpressionPossiblyEmpty,
  ElementNode,
  HtmlVisitor,
} from "zemdomu";
```

--------------------------------

### lint(content: string, options?: LinterOptions): LintResult[]

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Lints a single in-memory source string and returns an array of lint results.

```APIDOC
## lint(content: string, options?: LinterOptions): LintResult[]

### Description
Lints a single in-memory source string (HTML, JSX, TSX, or Vue template) and returns an array of lint results.

### Method
Function call

### Endpoint
`lint(content, options?)`

### Parameters
- `content` (string) - Required - HTML, JSX, TSX, or Vue template string input.
- `options.rules` (Record<string, "error" | "warning" | "off">) - Optional - Severity settings for built-in rules.
- `options.customRules` (Rule[]) - Optional - Array of additional rules.
- `options.filePath` (string) - Optional - Source file path.
- `options.forceHtml` (boolean) - Optional - Treat input as HTML.
- `options.perf` (PerformanceRecorder) - Optional - Attach a PerformanceRecorder instance.

### Request Example
```ts
const results = lint(html, {
  rules: { requireAltText: "warning", uniqueIds: "error" }
});
```

### Response
#### Success Response
- `line` (number) - Line number of the diagnostic.
- `column` (number) - Column number of the diagnostic.
- `message` (string) - Diagnostic message.
- `rule` (string) - Rule identifier.

#### Response Example
```ts
interface LintResult {
  line: number;
  column: number;
  message: string;
  rule: string;
}
```
```

--------------------------------

### ProjectLinter with crossComponentAnalysis

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Instantiates ProjectLinter with crossComponentAnalysis enabled and a depth of 2, then lints App.jsx. Use this to track semantic issues across component boundaries in JSX or Vue projects.

```TypeScript
import { ProjectLinter } from "zemdomu";

const linter = new ProjectLinter({
  crossComponentAnalysis: true,
  crossComponentDepth: 2,
});

await linter.lintFile("App.jsx");
```

--------------------------------

### formatZemDomuDiagnosticPretty(diagnostic: PageDiagnostic): string

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Formats a page diagnostic for terminal output.

```APIDOC
## formatZemDomuDiagnosticPretty(diagnostic: PageDiagnostic): string

### Description
Renders optional context from page diagnostics for terminal output.

### Method
Function call

### Endpoint
`formatZemDomuDiagnosticPretty(diagnostic)`

### Parameters
- `diagnostic` (PageDiagnostic) - Required - The page diagnostic to format.

### Request Example
```ts
const pretty = formatZemDomuDiagnosticPretty(diagnostic);
```
```

--------------------------------

### LinterOptions interface

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Defines the options object for the lint() function. The rules property maps rule names to severity levels, customRules accepts additional rules, filePath is optional, forceHtml treats input as HTML, and perf attaches a PerformanceRecorder.

```ts
interface LinterOptions {
  rules?: Record<string, "error" | "warning" | "off">;
  customRules?: Rule[];
  filePath?: string;
  forceHtml?: boolean;
  perf?: PerformanceRecorder;
}
```

--------------------------------

### project.lintPageDiagnostics(files: string[]): Promise<PageDiagnostic[]>

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Returns canonical diagnostics with page-level context for the given files.

```APIDOC
## project.lintPageDiagnostics(files: string[]): Promise<PageDiagnostic[]>

### Description
Returns canonical diagnostics with additional page context, including affected page, readable component path, composition-instance source locations, and preferred edit location when statically resolved.

### Method
Async method

### Endpoint
`project.lintPageDiagnostics(files)`

### Parameters
- `files` (string[]) - Required - Array of file paths to analyze.

### Request Example
```ts
const pageDiagnostics = await project.lintPageDiagnostics(["src/AppLayout.tsx"]);
```

### Response
#### Success Response
- Returns an array of page diagnostics with additional context fields. The `singleH1` rule remains at-most-one. The `requirePageH1` rule (ZMD022) is advisory and only active when explicitly enabled.
```

--------------------------------

### Using custom rules programmatically

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Passes a custom rule to the lint function via the customRules option. The rule is required from a local file.

```TypeScript
import { lint } from "zemdomu";

const results = lint("<foo></foo>", { customRules: [require("./my-rule")] });
```

--------------------------------

### LintResult interface

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Defines the structure of a lint result, containing line, column, message, and rule fields.

```ts
interface LintResult {
  line: number;
  column: number;
  message: string;
  rule: string;
}
```

--------------------------------

### PerformanceDiagnostics recorder

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Attaches a PerformanceDiagnostics recorder to gather timing information for each file and rule. Use getAsJSON() to retrieve the collected data.

```TypeScript
import { lint, PerformanceDiagnostics } from "zemdomu";

const perf = new PerformanceDiagnostics();
lint(code, { perf });
console.log(perf.getAsJSON());
```

--------------------------------

### Rule interface definition

Source: https://github.com/zemdomu/zemdomu-core/blob/main/README.md

Defines the Rule interface that custom rules must implement. Provide a name, a test function returning true when a node violates the rule, and a message describing the problem.

```TypeScript
interface Rule {
  name: string;
  test(node: any): boolean;
  message: string;
}
```
Tokens:
Raw