From 5d5bc65035531d0eddc2315757f4fe4cee6e4c79 Mon Sep 17 00:00:00 2001 From: Matt Stavola Date: Thu, 9 Oct 2025 00:19:23 -0400 Subject: [PATCH] Docs cleanup --- website/content/docs/cli/07-fetch.md | 10 - website/content/docs/cli/08-errors.md | 335 -------------------------- 2 files changed, 345 deletions(-) delete mode 100644 website/content/docs/cli/08-errors.md diff --git a/website/content/docs/cli/07-fetch.md b/website/content/docs/cli/07-fetch.md index 71000e7..e81547d 100644 --- a/website/content/docs/cli/07-fetch.md +++ b/website/content/docs/cli/07-fetch.md @@ -295,13 +295,3 @@ Make sure you're using the correct namespace format: ### Permission Errors Ensure you have write permissions for the project directory to create `.mlf/`. - -## Future Features - -Planned enhancements: - -- `--force` flag to re-fetch cached lexicons -- Version pinning (fetch specific lexicon versions) -- Private/authenticated repositories -- Offline mode with local cache -- Fetch from local directories diff --git a/website/content/docs/cli/08-errors.md b/website/content/docs/cli/08-errors.md deleted file mode 100644 index f4b1cdc..0000000 --- a/website/content/docs/cli/08-errors.md +++ /dev/null @@ -1,335 +0,0 @@ -+++ -title = "Error Messages" -description = "Understanding MLF error diagnostics" -weight = 8 -+++ - -MLF provides rich, helpful error messages with source code context and suggestions for fixing issues. - -## Error Format - -All MLF errors follow this format: - -``` - × Error title - ╭─[file.mlf:5:12] - 5 │ author: ProfileView, - · ^^^^^^^^^^^ error message - ╰──── - help: Suggestion for fixing the issue -``` - -**Components:** -- **× Error title** - Brief description of the error -- **Source location** - File name, line, and column -- **Source context** - The relevant code snippet -- **Error span** - Highlighted location with `^^^` -- **help:** - Actionable suggestion for fixing - -## Common Errors - -### Parse Errors - -#### Expected Token - -``` - × Expected '}', found ',' - ╭─[thread.mlf:10:5] -10 │ title: string, - · ^ expected '}' - ╰──── - help: Check for missing closing braces or extra commas -``` - -**Cause:** Syntax error in MLF code - -**Fix:** Correct the syntax according to MLF grammar - -#### Invalid Identifier - -``` - × Invalid identifier: '123invalid' - ╭─[thread.mlf:5:5] - 5 │ 123invalid: string, - · ^^^^^^^^^^ identifiers cannot start with numbers - ╰──── - help: Identifiers must start with a letter or underscore -``` - -**Cause:** Identifier doesn't follow naming rules - -**Fix:** Start identifiers with letters or underscores - -### Type Errors - -#### Undefined Reference - -``` - × Undefined reference to 'ProfileView' - ╭─[thread.mlf:8:12] - 8 │ author: ProfileView, - · ^^^^^^^^^^^ 'ProfileView' is not defined - ╰──── - help: Make sure this type is defined in the same file or imported via 'use'. -``` - -**Causes:** -- Type is not defined -- Type is in another file and not imported -- Typo in type name - -**Fixes:** -- Define the type in the same file -- Use `mlf fetch` to download external lexicons -- Add a `use` statement (if MLF supports imports) -- Check spelling - -#### Type Mismatch - -``` - × Type mismatch: expected integer, found string - ╭─[thread.mlf:12:15] -12 │ count: string, - · ^^^^^^ expected integer type - ╰──── - help: Change this to 'integer' or update the constraint -``` - -**Cause:** Field type doesn't match its definition - -**Fix:** Update the type to match the schema - -### Constraint Errors - -#### Invalid Constraint - -``` - × Invalid constraint for type 'integer': 'maxLength' - ╭─[thread.mlf:15:9] -15 │ maxLength: 100, - · ^^^^^^^^^ 'maxLength' is only valid for string types - ╰──── - help: Use 'maximum' for integer constraints -``` - -**Cause:** Constraint doesn't apply to the type - -**Fix:** Use the correct constraint for the type: -- String: `maxLength`, `minLength`, `maxGraphemes`, `minGraphemes` -- Integer: `minimum`, `maximum` -- Array: `maxLength`, `minLength` - -#### Constraint Value Error - -``` - × Constraint value must be positive - ╭─[thread.mlf:18:20] -18 │ maxLength: -10, - · ^^^ negative value not allowed - ╰──── - help: Use a positive integer value -``` - -**Cause:** Constraint value is invalid - -**Fix:** Use a valid value according to the constraint rules - -### Record Errors - -#### Missing Record Key - -``` - × Record definition must specify a key type - ╭─[thread.mlf:3:1] - 3 │ record main { - · ^^^^^^^^^^^ missing key specification - ╰──── - help: Add 'key: "tid"' or another valid key type to the record -``` - -**Cause:** Record doesn't specify how records are keyed - -**Fix:** Add a key specification to the record definition - -### XRPC Errors - -#### Invalid Response Code - -``` - × Invalid HTTP response code: 999 - ╭─[api.mlf:25:5] -25 │ 999: error, - · ^^^ response code must be between 200-599 - ╰──── - help: Use a valid HTTP status code -``` - -**Cause:** Invalid HTTP status code in query/procedure - -**Fix:** Use standard HTTP status codes (200, 400, 401, 404, 500, etc.) - -#### Missing Required Response - -``` - × Query/procedure must define at least one success response - ╭─[api.mlf:20:1] -20 │ query getProfile(...) { - · ^^^^^^^^^^^^^^^^^^^^^ no 200-level responses defined - ╰──── - help: Add at least one 2xx response (typically 200) -``` - -**Cause:** XRPC method has no success responses - -**Fix:** Add a 200-level response - -### Union Errors - -#### Empty Union - -``` - × Union must have at least one type - ╭─[thread.mlf:30:15] -30 │ data: unit | , - · ^ empty union - ╰──── - help: Add at least one type to the union -``` - -**Cause:** Union has no types - -**Fix:** Add types to the union: `string | integer` - -#### Duplicate Union Types - -``` - × Duplicate type in union: 'string' - ╭─[thread.mlf:32:20] -32 │ data: string | string, - · ^^^^^^ duplicate type - ╰──── - help: Remove duplicate types from the union -``` - -**Cause:** Same type appears multiple times in union - -**Fix:** Remove duplicates - -## Validation Errors - -### Record Validation - -``` -✗ Record validation failed with 2 error(s): - • Field 'title' is required but missing - • Field 'count': expected integer, found "123" -``` - -**Cause:** JSON record doesn't match lexicon schema - -**Fix:** Update the JSON to match the schema - -## Generation Errors - -### File Read Error - -``` -Failed to read file: permission denied -``` - -**Cause:** Cannot read input file - -**Fix:** Check file permissions and path - -### Type Resolution Error - -``` -Type resolution error: circular reference detected -``` - -**Cause:** Types reference each other in a cycle - -**Fix:** Break the circular dependency - -### Code Generation Error - -``` -Generator 'typescript' not found -``` - -**Cause:** Generator feature not enabled - -**Fix:** Install with `--features typescript` or use `--all-features` - -## Fetch Errors - -### DNS Error - -``` -✗ DNS lookup failed: No TXT record found for _lexicon.place.stream -``` - -**Cause:** Domain has no lexicon TXT record - -**Fix:** Verify the namespace is correct and has published lexicons - -### Network Error - -``` -✗ Failed to fetch lexicon records: connection timeout -``` - -**Cause:** Network connectivity issues - -**Fix:** Check internet connection and try again - -### Parse Error - -``` -✗ Failed to parse lexicon JSON: unexpected end of input -``` - -**Cause:** Malformed JSON from remote repository - -**Fix:** Report issue to namespace maintainer - -## Exit Codes - -All MLF commands use standard exit codes: - -- `0` - Success -- `1` - Error occurred - -Use in scripts: - -```bash -if mlf check; then - echo "✓ Valid" -else - echo "✗ Invalid" - exit 1 -fi -``` - -## Tips for Reading Errors - -1. **Read the title** - Gives you the high-level issue -2. **Check the location** - Find the exact line and column -3. **Examine the span** - See what code is problematic -4. **Follow the help** - Actionable suggestions for fixes -5. **Look for patterns** - Similar errors often have similar fixes - -## Reporting Bugs - -If you encounter an error that seems like a bug: - -1. Note the exact error message -2. Create a minimal reproduction case -3. Check if it's a known issue -4. Report at: https://github.com/anthropics/claude-code/issues - -Include: -- MLF version (`mlf --version`) -- Complete error message -- Minimal MLF code that reproduces the issue -- Expected behavior vs actual behavior -- 2.51.2