Manifest & Index Linting
Relevant source files
The following files were used as context for generating this wiki page:
Manifest and Index Linting refers to the suite of automated checks within the Numan Registry project designed to ensure structural integrity, metadata consistency, and trust invariants across the package catalog. The primary goal is to prevent common intake mistakes, such as malformed version constraints, duplicate digests, or inconsistencies between the CI-built plugin manifest and the public registry index. Sources: scripts/lint_packages.py:8-12, AGENTS.md:32-34
These checks operate as Stage 2 and Stage 5 gates in the project's intake and CI workflows. They ensure that all packages in registry/index.json adhere to the defined schema and that activatable packages have undergone required lifecycle evidence verification before promotion to production. Sources: scripts/validate_candidate.py:16-21, REVIEW.md:5-18
Architecture and Components
The linting system is composed of several specialized scripts that target different layers of the registry's data structures.
Structural Package Linting
The lint_packages.py script performs deterministic checks on the internal structure of the index.json file. It verifies required metadata fields (owner, name, description, repo), validates package types, and ensures that version entries are well-formed. It specifically monitors for duplicate SHA-256 digests across different packages to prevent artifact collisions. Sources: scripts/lint_packages.py:64-98, scripts/lint_packages.py:157-200
Manifest-Index Synchronization Lint
The lint-manifest-index.py script serves as a Stage 2 intake gate. It compares the nu_version constraints in numan-plugins/manifest.json (for CI-built plugins) against the entries in registry/index.json. If a plugin exists in both locations at the same version, their Nushell compatibility strings must match exactly. Sources: scripts/lint-manifest-index.py:8-15, AGENTS.md:32-34
Validation Orchestration
The validate_candidate.py script orchestrates multiple tools to validate a candidate registry spec. It executes the download and hashing process, triggers the structural lint, and performs schema validation before optionally running lifecycle proofs. Sources: scripts/validate_candidate.py:126-167
Linting Logic and Data Flow
The following diagram illustrates how a candidate package spec moves through the validation and linting pipeline:
This flowchart shows the sequential validation steps orchestrated by the candidate validation harness, leading to final lifecycle proof. Sources: scripts/validate_candidate.py:16-21, scripts/lint-manifest-index.py:8-15
Validation Rules and Constraints
The system enforces specific technical constraints on registry entries:
| Component | Rule/Constraint | Description |
|---|---|---|
| SHA-256 | ^[a-fA-F0-9]{64}$ | Must be 64 hex characters; duplicates are forbidden across targets. |
| Package Type | plugin, module, script, completion | Must match one of these four strictly defined categories. |
| Target Triples | x86_64-pc-windows-msvc, etc. | Must be one of the 6 known triples for binary artifacts. |
| Nu Version | MAJOR.MINOR.PATCH | Constraints must use exact versions, comparators, or minor wildcards. |
| Provenance | Immutable rev | Git revisions must be tags or full hashes, not branches like 'main'. |
Sources: scripts/lint_packages.py:27-35, scripts/lint_packages.py:102-125, scripts/lint_packages.py:265-275
Key Functions and Logic
SHA-256 Deduplication
The _record_sha256 function in lint_packages.py maintains a mapping of seen hashes to ensure that no two distinct artifacts share the same digest, which would indicate a trust bypass or administrative error.
Sources: scripts/lint_packages.py:175-200
Nu Version Constraint Parsing
The nu_constraint_error function validates that the Nushell version strings follow the project's supported grammar, allowing for exact matches (e.g., 0.113.1), comparators (e.g., >=0.113.0), or minor wildcards (e.g., 0.113.*).
Sources: scripts/lint_packages.py:102-125
This sequence diagram shows the interaction between the CI environment and the manifest-index linting script to ensure cross-repository compatibility. Sources: scripts/lint-manifest-index.py:86-135
Summary of Intake Gates
The linting process is tiered to provide early feedback before expensive operations:
- Structural Lint: Fast, local checks for missing fields or malformed JSON. Sources: scripts/lint_packages.py:214-250
- Manifest Sync: Remote check against upstream plugin metadata. Sources: scripts/lint-manifest-index.py:145-165
- Candidate Validation: Full orchestration including artifact downloads and digest calculation. Sources: scripts/validate_candidate.py:228-268
Manifest and Index linting ensures that the Numan registry remains a trusted source for Nushell packages by enforcing rigorous metadata standards and cross-component consistency. Through the orchestration of structural, schema, and synchronization checks, the project maintains high reliability in its signed index publication. Sources: REVIEW.md:38-50, SECURITY.md:50-60