Add File Extensions or New Languages to a Language-Detection Repo

## Find Which Files and Tools Own Each Part of Detection Before editing, identify which files and tools own each part of language detection: - the language registry for names, extensions, filenames, and language properties; - the heuristic rules and their implementation for ambiguous files; - the statistical classifier and its real-world sample corpus; - the grammar registry used for syntax highlighting; - vendored grammar sources and cached license data; - maintenance scripts, tests, and continuous-integration entry points. Treat these as coordinated contracts. A metadata change may require samples, heuristics, generated identifiers, grammar data, tests, and evidence rather than a single isolated edit. ## Set Up in the Repo's Dev Container and Use Its Scripts Prefer the repository's maintained development container or hosted environment when available. It should provide the declared language runtime, package tools, container runtime, native libraries, and all project dependencies. When working locally: 1. Run the canonical bootstrap command. 2. Invoke the library or command-line tool through the repository's dependency runner. 3. Use the documented maintenance scripts instead of reproducing their effects by hand. 4. Confirm that native dependencies required for encoding detection, repository access, or grammar work are present. Do not treat a locally successful ad hoc invocation as proof that the supported environment will pass. ## Add an Extension in Alphabetical Order with Real Code Samples When adding a filename extension to an existing language: 1. Update the authoritative language entry. 2. Keep extension lists in the required case-sensitive alphabetical order, with uppercase before lowercase and the primary extension first. 3. Add representative real-world sample files under the owning language. 4. If another language shares the extension, provide at least two samples and add a disambiguation heuristic. 5. Add or update tests for the metadata and heuristic behavior. Do not use tutorial staples such as trivial greeting programs as classifier evidence. Samples must reflect real code that the detector should recognize. ## Add a New Language with a Grammar and a Script-Generated ID A new language requires more than a registry label: 1. Add the language entry but leave its generated identifier unset. 2. Register an approved, compatible syntax-highlighting grammar through the canonical grammar tool. 3. Add representative sample files from verifiable original sources. 4. Run the identifier-generation script rather than assigning an identifier manually. 5. If any extension is shared, provide at least two samples and add tested disambiguation rules. 6. Verify metadata, grammar registration, classification, and generated changes together. Keep the registry's header guidance, field requirements, and case-sensitive ordering intact. ## Write Tested Regex Rules to Tell Apart Languages Sharing an Extension Heuristics should resolve genuine ambiguity without creating broad false positives. - Match the smallest distinctive evidence that separates the competing languages. - Keep every pattern linear in input size. - Avoid constructs vulnerable to regular-expression denial of service. - Use only syntax supported by the repository's required regular-expression engine. - Test positive cases, competing-language cases, and near misses. - Run classifier cross-validation when a heuristic or sample change can shift detection behavior. Every heuristic must have tests. A rule that recognizes the target but captures unrelated files is not acceptable. ## Regenerate Files with Maintenance Commands Instead of Editing Them by Hand Do not edit generated registries, module declarations, vendored grammar content, or cached grammar-license files by hand. Use the owning maintenance command to add or replace a grammar and review all generated changes it produces. Before accepting a grammar: - confirm compatibility with the syntax-highlighting format used by the project; - verify that its license is on the approved list; - preserve the canonical source URL and license record; - run grammar-specific validation in the supported container environment. If the generated result is wrong, fix the source input or generator workflow rather than patching the output. ## Run Classifier Cross-Validation and the Full Test Suite Run the narrowest relevant checks first, then the repository's full required validation: 1. Validate changed metadata and ordering. 2. Run tests for new samples and heuristics. 3. Run classifier cross-validation when detection boundaries may move. 4. Run the complete test suite through the canonical dependency runner. 5. Confirm that continuous integration passes the same required stages. Review failures for false positives, generated-file drift, missing native dependencies, invalid grammar data, and unintended changes to unrelated languages. ## Show Usage Evidence and Sample Licenses Before Submitting Before opening a contribution request: - use the provided request template and remove only irrelevant sections; - link to public search evidence for each added extension, excluding forks; - show at least 2000 indexed files for common extensions, or 200 files for names that normally occur once per repository; - check reasonable distribution across distinct user and repository combinations, accounting for unusually dominant users; - link every sample to its original source, not to the contribution fork; - state the license of each sample individually; - pass all required tests and continuous-integration checks; - keep the change focused and do not combine it with unrelated refactoring. If any requirement is unmet, do not open the request. Explain which evidence, license, test, or scope condition is missing and what must be completed first.