file-lang 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roshan Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# file-lang
+
+> Deterministically detect a programming language from a file path, file name, or extension.
+
+`file-lang` is a tiny utility that maps file extensions and well-known filenames to **human‑readable language names**.
+
+No heuristics. No content parsing. No guessing.
+
+---
+
+<br />
+
+## Why
+
+When building tools that analyze files, repositories, you end up rewriting the same logic again and again:
+
+- Extract extension from paths
+- Normalize weird inputs
+- Map extensions to language names
+- Handle unknowns safely
+
+`file-lang` exists so you never have to think about this again.
+
+---
+
+<br />
+
+## Install
+
+```bash
+npm install file-lang
+```
+
+---
+
+<br />
+
+## Usage
+
+```ts
+import { detectLanguage } from "file-lang";
+
+detectLanguage("ts"); // "TypeScript"
+detectLanguage(".ts"); // "TypeScript"
+detectLanguage("index.ts"); // "TypeScript"
+detectLanguage("/src/utils/file.ts"); // "TypeScript"
+detectLanguage("Dockerfile"); // "Docker"
+detectLanguage("unknown.ext"); // "Unknown"
+```
+
+---
+
+<br />
+
+## Accepted Input
+
+`detectLanguage` accepts **any string** representing:
+
+- A file extension (`ts`, `.ts`)
+- A file name (`index.ts`)
+- A file path (`/path/to/file.ts`)
+- Well-known filenames (`Dockerfile`, `Makefile`)
+
+Invalid, empty, or unsupported inputs safely return:
+
+```ts
+"Unknown";
+```
+
+The function **never throws**.
+
+---
+
+<br />
+
+## Output
+
+- Returns a **human-readable language name** (Title Case)
+- Returns `"Unknown"` if no mapping exists
+
+Examples:
+
+- `"TypeScript"`
+- `"JavaScript"`
+- `"Markdown"`
+- `"Docker"`
+
+---
+
+<br />
+
+## Design Principles
+
+- Deterministic output
+- Extension-based only
+- Zero dependencies
+- Minimal public API
+- Predictable behavior
+
+If an extension is ambiguous or unclear, `file-lang` **does not guess**.
+
+Ambiguity resolves to `"Unknown"`.
+
+---
+
+<br />
+
+## Contributing
+
+Contributions are welcome, especially:
+
+- Adding support for additional languages
+- Improving test coverage
+
+Guidelines:
+
+- Keep changes minimal
+- Follow existing naming conventions
+- Do not introduce heuristics or content-based detection

package/dist/detectLanguage.d.ts

@@ -0,0 +1 @@
+export declare function detectLanguage(input: string): string;

package/dist/detectLanguage.js

@@ -0,0 +1,14 @@
+import { languageMap } from "./language.js";
+import { normalize } from "./normalize.js";
+export function detectLanguage(input) {
+    // Return Unknown input is not typeof string
+    if (typeof input !== "string")
+        return "Unknown";
+    // Check for empty string
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return "Unknown";
+    const normalized = normalize(trimmed);
+    const language = languageMap[normalized];
+    return language || "Unknown";
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { detectLanguage } from "./detectLanguage.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { detectLanguage } from "./detectLanguage.js";

package/dist/language.d.ts

@@ -0,0 +1 @@
+export declare const languageMap: Record<string, string>;

package/dist/language.js

@@ -0,0 +1,74 @@
+export const languageMap = {
+    // --- Bash ---
+    bash: "Bash",
+    // --- C ---
+    c: "C",
+    // --- C++ ---
+    cpp: "C++",
+    hpp: "C++",
+    // --- C# ---
+    cs: "C#",
+    // --- CSS ---
+    css: "CSS",
+    // --- Elixir ---
+    ex: "Elixir",
+    exs: "Elixir",
+    // --- Dart ---
+    dart: "Dart",
+    // --- Docker ---
+    dockerfile: "Docker",
+    // --- Go ---
+    go: "Go",
+    // --- Haskell ---
+    hs: "Haskell",
+    lhs: "Haskell",
+    // --- Less ---
+    less: "Less",
+    // --- JavaScript ---
+    js: "JavaScript",
+    jsx: "JavaScript",
+    mjs: "JavaScript",
+    // --- JSON ---
+    json: "JSON",
+    // --- Java ---
+    java: "Java",
+    // --- Kotlin ---
+    kt: "Kotlin",
+    kts: "Kotlin",
+    // --- Lua ---
+    lua: "Lua",
+    // --- Makefile ---
+    makefile: "Makefile",
+    // --- Markdown ---
+    md: "Markdown",
+    // --- Objective-C ---
+    m: "Objective-C",
+    // --- Python ---
+    py: "Python",
+    pyw: "Python",
+    // --- PHP ---
+    php: "PHP",
+    php3: "PHP",
+    phtml: "PHP",
+    // --- Perl ---
+    pl: "Perl",
+    pm: "Perl",
+    pod: "Perl",
+    // --- R ---
+    r: "R",
+    // --- Rust ---
+    rs: "Rust",
+    // --- Ruby ---
+    rb: "Ruby",
+    rhtml: "Ruby",
+    erb: "Ruby",
+    // --- Shell ---
+    sh: "Shell",
+    // --- SCSS ---
+    scss: "SCSS",
+    // --- TypeScript ---
+    ts: "TypeScript",
+    tsx: "TypeScript",
+    // --- Text ---
+    txt: "Text",
+};

package/dist/normalize.d.ts

@@ -0,0 +1 @@
+export declare function normalize(input: string): string;

package/dist/normalize.js

@@ -0,0 +1,11 @@
+import { extname } from "node:path";
+export function normalize(input) {
+    // Special case: ".ts" → "ts"
+    if (input.startsWith(".") && !input.includes("/") && !input.includes("\\")) {
+        return input.slice(1).toLowerCase();
+    }
+    const ext = extname(input);
+    if (!ext)
+        return input.toLowerCase();
+    return ext.slice(1).toLowerCase();
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "file-lang",
+  "version": "0.1.0",
+  "description": "Deterministically detect a programming language from a file path, name, or extension.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "language-detection",
+    "file-language",
+    "file-extension",
+    "developer-tools",
+    "static-analysis",
+    "repository-analysis",
+    "cli",
+    "tooling"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alcanivorax/file-lang.git"
+  },
+  "author": "alcanivorax",
+  "license": "MIT",
+  "packageManager": "pnpm@10.27.0",
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  }
+}