Scala files fall back to generic review rules despite being supported

[Qiyuanqiii]

Problem statement

Scala source files are already accepted by open-code-review, but they do not receive Scala-specific review guidance.

The built-in allowlist contains .scala, so Scala files pass file selection and enter review. However, internal/config/rules/system_rules.json has no **/*.scala mapping and internal/config/rules/rule_docs/ has no Scala rule document. The system resolver therefore behaves as designed and falls back to the generic default.md rule for every Scala source file that does not have a higher-priority user rule.

This makes Scala support incomplete: the files are reviewable, but the reviewer receives no built-in guidance for Scala-specific correctness risks.

Current routing behavior

For a path such as:

src/main/scala/com/example/Service.scala

the current routing chain is:

1. The extension filter accepts the file because .scala is already listed in internal/config/allowlist/supported_file_types.json.
2. Custom, project, and global rules are evaluated using the existing precedence.
3. The embedded system resolver evaluates internal/config/rules/system_rules.json.
4. No Scala pattern matches.
5. The resolver returns the generic embedded default rule.

The gap is therefore in built-in rule registration and content, not in file eligibility or resolver implementation.

Actual behavior

• .scala files are selected for review.
• They receive only default.md when no user-defined rule overrides the system layer.
• The prompt lacks guidance for common Scala failure modes, including:
  • Java nullability boundaries and unsafe Option extraction;
  • partial collections, single-use iterators, lazy views, and potentially infinite collections;
  • Future, Promise, ExecutionContext, blocking, and failure observation;
  • pattern-match exhaustivity, refutable bindings, and erased generic type tests;
  • superclass/subclass initialization order and cyclic lazy values;
  • equality, hashing, ordering, and mutable collection keys;
  • narrowing conversions, overflow, integer division, and floating-point edge cases;
  • exception classification and resource lifetime;
  • JVM, Scala.js, and Scala Native interoperability boundaries;
  • published-library compatibility and Scala-specific test behavior.

Expected behavior

When no higher-priority custom, project, or global rule applies, a Scala source path should resolve through the built-in mapping:

src/main/scala/com/example/Service.scala
    -> **/*.scala
    -> scala.md

The Scala rules should favor precision over recall. Version-, platform-, framework-, and runtime-dependent findings must be grounded in repository evidence rather than assuming that every Scala project uses the same compiler flags, effect system, actor framework, collection library, or target platform.

Root cause

File eligibility and language-specific rule routing are configured independently.

Scala was added to the supported-extension allowlist, which makes .scala files reviewable, but the corresponding system-rule mapping and embedded rule document were never added. No new resolver mechanism is required.

Proposed solution

Keep the implementation within the existing configuration and documentation mechanism:

• Add internal/config/rules/rule_docs/scala.md.

• Register:

  "**/*.scala": "scala.md"

  in internal/config/rules/system_rules.json.

• Add a deterministic resolver regression case for a representative nested Scala path.

• Verify the resolved content contains a stable Scala-only heading, proving that the path did not fall back to default.md.

• Synchronize the built-in mapping table across all maintained documentation locales:

  • English
  • Chinese
  • Japanese
  • Korean
  • Russian

The rule document should describe concrete failure mechanisms and observable consequences, with explicit false-positive controls for Scala 2 versus Scala 3, optional compiler features, JVM/JavaScript/native targets, and ecosystem-owned concurrency or lifecycle semantics.

Acceptance criteria

• .scala remains an accepted review extension.
• LoadDefault() loads the embedded configuration and Scala rule document.
• src/main/scala/com/example/Service.scala resolves to scala.md.
• The resolver regression test proves the result contains Scala-specific content that is absent from default.md.
• Custom, project, and global rule precedence remains unchanged.
• Existing mappings and fallback behavior for other files remain unchanged.
• Integrity tests confirm that scala.md exists, is embedded, is referenced, and is not orphaned.
• Extension consistency checks confirm that .scala is already allowlisted.
• The rule mapping tables are synchronized across en, zh, ja, ko, and ru.
• make check, make test, and make coverage pass.

Non-goals

This issue does not include:

• adding any new supported extension;
• adding rules for .sbt, .sc, or other Scala-adjacent file types;
• changing scan, preview, exclusion, or resolver logic;
• changing rule precedence;
• changing public APIs, CLI flags, or configuration schemas;
• adding a Scala parser, compiler, linter, or build-tool integration;
• enforcing formatting or subjective Scala style;
• requiring Cats, Cats Effect, ZIO, Akka, Pekko, Spark, Play, or another ecosystem library;
• treating Scala 2 and Scala 3 as semantically identical;
• modifying production Go code.

Compatibility and risk

This is an additive built-in rule update.

File selection does not change because .scala is already allowlisted. User-provided custom, project, and global rules continue to outrank the embedded system rule. There is no API, CLI, or persisted-data migration.

The intentional observable change is limited to Scala files that currently depend on the built-in fallback: their review prompts will contain Scala-specific guidance instead of only default.md. This can change the findings produced for those files, which is the purpose of the feature.

Implementation risk is low because the change uses the existing embedded document and path-matching mechanisms and introduces no new runtime branch.

Validation approach

Automated validation should include:

make check
make test
make coverage
git diff --check

The resolver regression test should prove both that scala.md is available through the embedded loader and that **/*.scala routes a nested Scala path to that document.

Manual validation can use:

ocr rules check src/main/scala/com/example/Service.scala

The command should report System built-in, pattern **/*.scala, and the Scala rule content. A path without a dedicated mapping should continue to use default.md, while .sbt and .sc remain outside this issue's scope.