provenant/parsers/metadata.rs
1// SPDX-FileCopyrightText: Provenant contributors
2// SPDX-License-Identifier: Apache-2.0
3
4/// Registered detection-surface metadata for auto-generating documentation.
5///
6/// This module provides the `ParserMetadata` type used by parser `metadata()`
7/// trait methods and by `bin/generate_supported_formats.rs` to automatically
8/// generate `docs/SUPPORTED_FORMATS.md`.
9///
10/// Fields are used by the xtask but not in library code,
11/// so we allow dead_code warnings for library builds.
12#[derive(Debug, Clone)]
13#[allow(dead_code)]
14pub struct ParserMetadata {
15 /// Human-readable description (e.g., "npm package.json manifest")
16 pub description: &'static str,
17 /// File patterns this parser matches (e.g., `["**/package.json"]`).
18 ///
19 /// Documentation of the intended surface, not an executable contract, and
20 /// deliberately not asserted against `is_match`. The two cannot be held
21 /// equal: many parsers gate on content or path context rather than the
22 /// filename alone — an `.apk` is claimed only if its magic bytes match, a
23 /// `METADATA` only inside a wheel's dist-info — so a pattern describes what
24 /// a user should expect to be recognised, while `is_match` decides whether a
25 /// specific file on disk actually is.
26 ///
27 /// Two consequences worth knowing when editing these:
28 ///
29 /// - A pattern here can be *broader* than `is_match`, and legitimately so.
30 /// Keep it recognisable to a user reading `docs/SUPPORTED_FORMATS.md`
31 /// rather than mechanically exact.
32 /// - A surface that is not expressible as a glob at all — detector-driven,
33 /// scanner-gated, or resolved relative to the scan root — uses the
34 /// `<...>` convention instead (e.g.
35 /// `"<compiled Go binaries with Go build info>"`), which the generated
36 /// table renders as prose. Prefer that over a glob that would advertise
37 /// files the parser declines.
38 pub file_patterns: &'static [&'static str],
39 /// Package type identifier (e.g., "npm", "pypi", "maven")
40 pub package_type: &'static str,
41 /// Primary programming language (e.g., "JavaScript", "Python")
42 pub primary_language: &'static str,
43 /// Optional documentation URL
44 pub documentation_url: Option<&'static str>,
45}