Support top-level custom linter rules

[jviotti]

No description provided.

[augmentcode]

🤖 Augment PR Summary

Summary: This PR adds support for registering custom linter rules that run only at the document root (top-level).

Changes:

• Introduced a new CLI option --top-level-rule/-t alongside existing --rule/-a to scope custom rules to the root schema only.
• Extended jsonschema.json configuration so lint.rules can contain either strings or objects ({ path, topLevel }) to declare rule scope.
• Refactored lint rule loading to share logic between option-based rule registration paths.
• Updated bash/zsh completions and CLI help text to document the new option.
• Added a comprehensive set of shell-based tests covering top-level rules (pass/fail, YAML, exclude/only, duplicate names, fix behavior) and new config entry validation.
• Vendor update to Blaze adding rule scoping support, improving annotation-collection decision logic, and registering the Sourcemeta Extension vocabulary/dialects with better evaluator descriptions for new annotation keywords.

Technical Notes: Top-level scoping is implemented in Blaze’s SchemaRule by skipping evaluation for non-root schema locations, and config parsing now validates mixed (string/object) rule entries with clear error locations.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/configuration.markdown">

<violation number="1" location="docs/configuration.markdown:65">
P2: The new type notation `String[] / Object[]` incorrectly suggests `lint.rules` must be homogeneous (all strings **or** all objects), but the implementation allows mixing both types in the same array — each entry can independently be a string or an object with a `path`/`topLevel` shape. Consider reverting to the previous `(String / Object)[]` notation, which more accurately describes `(String | Object)[]` — an array whose individual elements can be either type.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The new type notation String[] / Object[] incorrectly suggests lint.rules must be homogeneous (all strings or all objects), but the implementation allows mixing both types in the same array — each entry can independently be a string or an object with a path/topLevel shape. Consider reverting to the previous (String / Object)[] notation, which more accurately describes (String | Object)[] — an array whose individual elements can be either type.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/configuration.markdown, line 65:

<comment>The new type notation `String[] / Object[]` incorrectly suggests `lint.rules` must be homogeneous (all strings **or** all objects), but the implementation allows mixing both types in the same array — each entry can independently be a string or an object with a `path`/`topLevel` shape. Consider reverting to the previous `(String / Object)[]` notation, which more accurately describes `(String | Object)[]` — an array whose individual elements can be either type.</comment>

<file context>
@@ -62,7 +62,7 @@ describes the available configuration options:
 | `dependencies` | Object | A mapping of URIs to relative file paths for external schema dependencies to install (see [`jsonschema install`](./install.markdown)) | `{}` |
 | `lint` | Object | Lint configuration | `{}` |
-| `lint.rules` | (String / Object)[] | Paths to custom lint rule schemas relative to `jsonschema.json` (see [lint](./lint.markdown)). An entry may also be an object with a required `path` string property and an optional `topLevel` boolean property (defaults to `false`) that makes the rule only run against the document root | `[]` |
+| `lint.rules` | String[] / Object[] | Paths to custom lint rule schemas relative to `jsonschema.json` (see [lint](./lint.markdown)). An entry may also be an object with a required `path` string property and an optional `topLevel` boolean property (defaults to `false`) that makes the rule only run against the document root | `[]` |
 
 Lookup Algorithm
</file context>

Suggested change

	| `lint.rules` | String[] / Object[] | Paths to custom lint rule schemas relative to `jsonschema.json` (see [lint](./lint.markdown)). An entry may also be an object with a required `path` string property and an optional `topLevel` boolean property (defaults to `false`) that makes the rule only run against the document root | `[]` |
	| `lint.rules` | (String / Object)[] | Paths to custom lint rule schemas relative to `jsonschema.json` (see [lint](./lint.markdown)). An entry may also be an object with a required `path` string property and an optional `topLevel` boolean property (defaults to `false`) that makes the rule only run against the document root | `[]` |

[cubic-dev-ai]

1 issue found and verified against the latest diff

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="completion/jsonschema.bash">

<violation number="1" location="completion/jsonschema.bash:145">
P3: After `jsonschema lint -t `, Bash completion offers `typescript`, which is not a valid top-level rule argument. The new alias needs a `lint`-specific `-t` argument completion before the existing codegen/upgrade handling.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: After jsonschema lint -t , Bash completion offers typescript, which is not a valid top-level rule argument. The new alias needs a lint-specific -t argument completion before the existing codegen/upgrade handling.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At completion/jsonschema.bash, line 145:

<comment>After `jsonschema lint -t `, Bash completion offers `typescript`, which is not a valid top-level rule argument. The new alias needs a `lint`-specific `-t` argument completion before the existing codegen/upgrade handling.</comment>

<file context>
@@ -142,7 +142,7 @@ _jsonschema() {
       ;;
     lint)
-      local options="--fix -f --extension -e --ignore -i --exclude -x --only -o --list -l --indentation -n"
+      local options="--fix -f --extension -e --ignore -i --exclude -x --only -o --list -l --indentation -n --rule -a --top-level-rule -t"
       if [[ ${current} == -* ]]
       then
</file context>