How the Unknown-Key Rule Detects Potential Typos in YAML Files

The unknown-key rule detects potential typos in YAML by comparing unrecognized keys against valid schema keys using Levenshtein distance, flagging matches within a distance threshold of 2 as likely misspellings.

The DESIGN-MD specification uses YAML for configuration, and the google-labs-code/design.md CLI includes a linter to validate these files. The unknown-key rule is a critical validation mechanism that identifies unrecognized keys and suggests corrections when they appear to be misspelled versions of valid schema properties. This rule prevents configuration errors by catching typos early in the development process.

How the Unknown-Key Rule Detects Typos

The detection logic operates in three distinct phases, traversing from raw YAML parsing to actionable developer feedback.

Step 1: Collecting Unknown Keys

During the parsing phase, the linter extracts keys that appear in the YAML but lack definitions in the schema. In packages/cli/src/linter/model/handler.ts, the parser populates state.unknownKeys with these unrecognized key names and stores their corresponding raw values in state.unknownKeyValues. This collection phase isolates potential typos from the set of valid configuration properties.

Step 2: Computing String Similarity

For each unknown key, the rule retrieves the complete set of valid schema keys. It then executes a Levenshtein distance algorithm (implemented in packages/cli/src/linter/linter/rules/levenshtein.test.ts) to calculate the edit distance between the unknown key and every valid key. When the minimum distance is less than or equal to 2, the rule identifies the closest-matching schema key as a probable correction.

Step 3: Generating Typo Suggestions

When a candidate typo is identified, the rule constructs a RuleFinding object containing the unknown key name, the suggested correction, and the precise location in the source file. The finding includes a diagnostic message formatted as: "<unknown-key> is not a known key. Did you mean <suggested-key>?" This implementation resides in packages/cli/src/linter/linter/rules/unknown-key.ts.

Implementation Details

The rule is registered in the linter pipeline through packages/cli/src/linter/linter/rules/index.ts, which imports and exposes the unknownKey function. The core logic accepts a DesignSystemState object containing the accumulated parsing state and returns an array of findings.

// Example invocation from the linter pipeline
import { unknownKey } from './unknown-key.js';

function runLinter(state: DesignSystemState) {
  const findings = unknownKey(state);
  // findings contains suggestions when typos are detected
  console.log(findings);
}

A typical finding returned for a typo like colr instead of color:

{
  "message": "`colr` is not a known key. Did you mean `color`?",
  "location": { "line": 12, "column": 3 },
  "severity": "error"
}

The test suite in packages/cli/src/linter/linter/rules/unknown-key.test.ts validates this behavior, demonstrating how the rule handles various misspelling scenarios against the DESIGN-MD schema.

Summary

• The unknown-key rule validates YAML by identifying keys that do not exist in the schema.
• It uses Levenshtein distance with a threshold of 2 to find similar valid keys.
• Findings are generated in packages/cli/src/linter/linter/rules/unknown-key.ts and include specific line and column locations.
• The rule integrates into the CLI via packages/cli/src/linter/linter/rules/index.ts.
• This approach catches configuration errors early by suggesting corrections for misspelled properties.

Frequently Asked Questions

What is the Levenshtein distance threshold for typo detection?

The rule uses a threshold of 2 for the Levenshtein distance calculation. If an unknown key requires two or fewer character insertions, deletions, or substitutions to match a valid schema key, the rule flags it as a potential typo and suggests the valid key.

Where does the unknown-key rule source its list of valid keys?

The rule derives valid keys from the DESIGN-MD schema definition. During the parsing phase in packages/cli/src/linter/model/handler.ts, the linter distinguishes between defined schema properties and unrecognized keys, storing the latter in state.unknownKeys for subsequent analysis.

How does the rule handle cases where multiple valid keys are similar?

The rule calculates the Levenshtein distance against every valid schema key and selects the candidate with the smallest distance. If multiple keys share the same minimum distance (≤ 2), the implementation typically suggests the first closest match found, though the specific tie-breaking logic is defined in packages/cli/src/linter/linter/rules/unknown-key.ts.

Can I adjust the typo detection sensitivity in the configuration?

The threshold of 2 is hardcoded in the rule implementation within packages/cli/src/linter/linter/rules/unknown-key.ts. To adjust the sensitivity, you would need to modify the source code and rebuild the CLI, as the current version does not expose this parameter through external configuration files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}