feat: add issues module with an early implementation for the filename validator

[karellopez]

Closes #85

What this adds

Two modules that turn filename validation into structured findings.

Module	Role
bids_validator/issues.py	The container: what a finding is. Pure data, no I/O.
bids_validator/filename_checks.py	The logic: schema-driven filename and path checks.

Validation currently answers a yes/no question. BIDSValidator.is_bids() returns a
boolean and the CLI prints one line per bad file, which carries no severity, no stable
code, and no structure a program can consume. context.py already anticipates this:
ValidationError is a stub whose body is """TODO: Add issue structure.""".

A problem is now a typed record:

[error] DATATYPE_MISMATCH
    file   : sub-01/func/sub-01_T1w.nii.gz
    detail : the file is in 'func' but its suffix belongs in: anat
    rule   : rules.files.raw.anat.nonparametric

Scope is names and paths only. Nothing here opens a file or reads its contents.
BIDSValidator.is_bids() is untouched, since pybids and mne-bids depend on it.

This PR adds 6 files and modifies none.

Design notes

• attrs, not pydantic or msgspec, matching context.py and types/files.py.
• The two modules are separate so issues.py imports nothing from the package and can
  never take part in an import cycle. Any future check module can depend on it.
• filename_checks.py reads rules.files from the schema and identifies which rule(s) a
  path matches, then reports one specific code per kind of failure. Nothing about BIDS is
  hardcoded; only the ten issue code strings are constants, because the schema does not
  define them. They come from the TypeScript validator's catalog (src/issues/list.ts),
  mirrored in FILENAME_ISSUES so the provenance is explicit and the output stays
  interchangeable.
• The walk applies the TypeScript validator's default ignores (.git**, .*,
  sourcedata/, code/, stimuli/, log/) in addition to .bidsignore. Without them,
  dotfiles such as .DS_Store are reported, which the TypeScript validator never does.
• Directory recordings (CTF .ds, MEF .mefd, OME-Zarr) are treated as single units: the
  walk does not descend into them.
• Schema lookups are memoised per schema object, so the rule tree is flattened once rather
  than once per file (measured: 0.8 ms first call, 0.0005 ms thereafter, 179 rules). The
  walk is a generator, so a large dataset holds one context at a time.

Field naming and JSON output

Following your note in #85: the model uses snake_case internally, and reporting output
should follow the TypeScript validator's camelCase interface. Four of the six fields
already match; the mapping for a future reporter is:

this model	TypeScript validator
code	code
severity	severity
location	location
rule	rule
sub_code	subCode
message	issueMessage

No JSON reporter is included in this PR, so nothing emits either form yet.
attrs.asdict(issue) produces the internal names and is only a convenience for
inspection, not a reporting format. I will add the camelCase mapping when the reporter
lands, or I can add a small to_reporting_dict() here if you would rather the convention
were in place from the start.

One deliberate difference from the TypeScript validator

A data file outside any recognised datatype directory is reported as INVALID_LOCATION:

sub-01/foo/sub-01_T1w.nii.gz     "foo" is not a datatype
sub-01/sub-01_T1w.nii.gz         no datatype folder at all

The TypeScript validator misses this. findDatatype returns an empty string when the
parent folder is not a known datatype (src/schema/datatypes.ts), and DATATYPE_MISMATCH
is gated on that value being truthy (src/validators/filenameValidate.ts). Meanwhile
suffix-based rule matching ignores the datatype entirely
(src/validators/filenameIdentify.ts), so the file still matches a rule and is not
NOT_INCLUDED either.

The legacy is_bids regexes do catch it, because they cover the whole path. Since
this module is the schema-driven successor to that check, dropping the case would lose
coverage users already have:

Path	is_bids	TypeScript validator	this PR
/sub-01/anat/sub-01_T1w.nii.gz	True	clean	clean
/sub-01/foo/sub-01_T1w.nii.gz	False	clean	INVALID_LOCATION
/sub-01/sub-01_T1w.nii.gz	False	clean	INVALID_LOCATION
/sub-01/func/sub-01_T1w.nii.gz	False	DATATYPE_MISMATCH	DATATYPE_MISMATCH

Metadata files are exempt: the inheritance principle lets a .json or .tsv sit higher
in the tree than the data it describes, so sub-01/sub-01_T1w.json and
task-rest_bold.json at the dataset root are correct and are not flagged.

Happy to put this behind a flag if you would rather keep strict parity with the
TypeScript validator by default. I think it is also worth reporting upstream to
bids-standard/bids-validator as a genuine miss.

Tests

Following the existing conventions: plain pytest, the session-scoped schema fixture
from tests/conftest.py, @pytest.mark.parametrize, no new fixture machinery and no new
dependency. No datalad usage added (per #10).

• tests/test_issues.py covers the model: defaults, both severities, the collection
  helpers, and an attrs.asdict round trip.
• tests/test_filename_checks.py is table driven with one case per issue code, plus
  the default ignores, .bidsignore, the rule field, catalog completeness, and the
  datatype-directory cases cross-checked against is_bids to pin the intent.

28 tests, all passing.

CI status

build-test-deploy passes on the full Python 3.10 to 3.14 matrix:

The style job fails, for reasons that predate this PR. ruff check src/ reports 8
findings, none of them in the files this PR adds:

File	Findings
src/bids_validator/context.py	6
src/bids_validator/bids_validator.py	1
src/bids_validator/types/_typings.py	1
src/bids_validator/issues.py (added here)	0
src/bids_validator/filename_checks.py (added here)	0

Rules: PIE790 x2, PLW0120, PYI036, RUF022, SIM102, SIM118, TRY004.

I verified this is not caused by the PR by checking out main at 5a361c4 in a clean
worktree, where neither added module exists, and running the same command. It produces
the identical Found 8 errors with the same rules in the same three files. The cause is
that tox.ini declares deps = ruff unpinned, so CI installs the newest ruff (0.16.2 in
this run) and recently added rules flag existing code, the same situation as the earlier
chore: Resolve ruff complaints commit.

For the two modules and two test files added here, ruff check, ruff format --diff,
codespell and mypy are all clean.

I have deliberately not fixed those 8 findings in this PR, to keep the diff to the
feature. Happy to send them as a separate chore PR if useful. One caveat if I do:
TRY004 asks to change a ValueError to a TypeError in context.py, which is a
behaviour change, so I would rather you decide that one than have me slip it into a
cleanup.

Coverage

Measured locally on the added modules with the same invocation CI uses:

Name                                    Stmts   Miss Branch BrPart  Cover
-------------------------------------------------------------------------
src/bids_validator/filename_checks.py     279     14    130     18    92%
src/bids_validator/issues.py               32      0      0      0   100%
-------------------------------------------------------------------------
TOTAL                                     311     14    130     18    93%

93% on the added code, above the 80% project and patch targets in codecov.yml.

Docs

• docs/filename_issues_module.md: what the modules add, architecture with flowcharts,
  the ten codes, usage, how content validation extends the same layer, and a technical
  reference covering every type and function with the reasoning behind each decision.
• docs/example_filename_issues.py: runs two ways. With no argument it generates a
  dataset containing one deliberately broken file per issue code; with a path it
  validates your own dataset.

Not included, on purpose

• Reading file contents. Sidecar fields, NIfTI headers and tabular columns produce the
  same Issue type into the same DatasetIssues, so they extend this without changing
  the output contract.
• Wiring into the CLI. Since there are no backwards-compatibility commitments for it
  (per Add a structured issues model and emit findings from the filename validator #85), this can simply replace the current printed output rather than sit behind a
  compatibility flag. Happy to do it in this PR or the next, whichever you prefer.
• The TypeScript validator's richer Issue fields (rule provenance, fixes, ignore
  severity, line spans). Left out to keep this PR reviewable, and easy to expand as
  necessary per Add a structured issues model and emit findings from the filename validator #85.

[codecov]

Codecov Report

❌ Patch coverage is 92.45283% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.29%. Comparing base (5a361c4) to head (6955a54).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #86      +/-   ##
==========================================
+ Coverage   90.56%   91.29%   +0.73%     
==========================================
  Files          13       17       +4     
  Lines         890     1310     +420     
  Branches      130      219      +89     
==========================================
+ Hits          806     1196     +390     
- Misses         50       62      +12     
- Partials       34       52      +18     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.