Skip to content

README.md

Latest commit

 

History

History
119 lines (82 loc) · 3.37 KB

README.md

File metadata and controls

119 lines (82 loc) · 3.37 KB

Documentation Validation Tool

A documentation validation tool that supports Dead Link checking, SQL syntax validation, and SQL execution validation.

Commands

🔗 Dead Link Checking

# Single file
pnpm run check:links:file docs/MatrixOne/Test/test-pass.md

# Multiple files
pnpm run check:links:files docs/MatrixOne/Test/test-pass.md docs/MatrixOne/Test/test-fail.md

# Changed files
pnpm run check:links:changed

🧾 SQL Syntax Validation

Validates the syntactic correctness of SQL statements in documentation without executing them against a database.

# Single file
pnpm run check:sql-syntax:file docs/MatrixOne/Test/test-pass.md

# Multiple files
pnpm run check:sql-syntax:files docs/MatrixOne/Test/test-pass.md docs/MatrixOne/Test/test-fail.md

# Changed files
pnpm run check:sql-syntax:changed

Skipping Syntax Templates

The validator automatically detects and skips common syntax template patterns:

  • Angle bracket placeholders: <table_name>, <column_name>, <index_name>
  • Ellipsis patterns: col1, col2, ... or (expr1, expr2, ...)
  • Optional syntax markers: [WITH PARSER ...], [ASC | DESC]
  • Curly brace placeholders: {expr}, {value}

For code blocks that cannot be auto-detected, use the validator-ignore comment:

<!-- validator-ignore -->
```sql
CREATE FULLTEXT INDEX <index_name>
ON <table_name> (col1, col2, ...)
[WITH PARSER (default | ngram | json)];
```

Or inline:

```sql <!-- validator-ignore -->
MATCH (col1, col2, ...) AGAINST (expr [search_modifier]);
```

Skipping Execution Only (Keep Syntax Check)

Use validator-ignore-exec when a SQL example is syntactically valid MatrixOne SQL but cannot reliably run in the generic execution test environment. Typical cases:

  • Examples that depend on external files (LOAD DATA INFILE, SOURCE, LOAD_FILE(), CREATE STAGE url='file:///...')
  • DDL that must run outside the test's implicit transaction (CREATE SNAPSHOT, CREATE PUBLICATION, CREATE SUBSCRIPTION, some CREATE STAGE)
  • Examples that rely on specific data / instance state (existing rows, existing accounts/roles/users, foreign-key data, cluster/HA state)
  • Version-specific output differences (SHOW CREATE TABLE formatting, column counts, time-sensitive values)

With this directive the block is still validated by the syntax checker but skipped by the execution checker:

<!-- validator-ignore-exec -->
```sql
LOAD DATA INFILE '/tmp/demo.csv' INTO TABLE t1;
```

Inline form is also supported:

```sql <!-- validator-ignore-exec -->
CREATE SNAPSHOT s1 FOR DATABASE db1;
```

Prefer validator-ignore-exec over validator-ignore whenever the SQL itself is correct — this keeps syntax coverage as high as possible.

▶️ SQL Execution Validation

Verifies the executability and execution results of SQL statements against a real database environment.

# Start database (latest nightly)
pnpm run db:start

# Start a specific version (prefer release, fallback to nightly)
pnpm run db:start 3.0.4

# Single file
pnpm run check:sql-exec:file docs/MatrixOne/Test/test-pass.md

# Multiple files
pnpm run check:sql-exec:files docs/MatrixOne/Test/test-pass.md docs/MatrixOne/Test/test-fail.md

# Changed files
pnpm run check:sql-exec:changed

# Stop database
pnpm run db:stop