@deepseek-ai/dsh-util-code-language 0.1.7-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.i18n.yaml

@@ -0,0 +1,25 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/code-language/README.md
+/:
+  en: cc80317463624b86
+  zh: 5acd6caf91ab26cb
+/dsh-util-code-language:
+  en: 47e8ee84f77661fe
+  zh: 41d4c547ec0d1c07
+/dsh-util-code-language/summary:
+  en: 7691b06d9c0f5939
+  zh: f11d2272efd6afa1
+/dsh-util-code-language/table-of-contents:
+  en: 0af71fd8a7533fed
+  zh: 325e8000300b6f03
+/dsh-util-code-language/language-selection:
+  en: 320253c948359d9d
+  zh: 05e15afc801c0f4a
+/dsh-util-code-language/known-limitations-and-deferred-work:
+  en: 18e4dc8978a0dd29
+  zh: 6f5715ae89229864
+/dsh-util-code-language/known-limitations-and-deferred-work/dev-note:
+  en: cfc7173facebc57c
+  zh: 4ea51377d7c9c147

package/README.md

@@ -0,0 +1,50 @@
+---
+description: "Single file-extension to syntax-highlighting language table shared by the Client code surfaces and the Host read card."
+kind: "package-library"
+---
+
+# dsh-util-code-language
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The repository's one file-extension to syntax-highlighting language table, shared by the Client's document Code preview and diff review, and by the Host read tool's persisted `lang` hint. `languageForPath` maps a path to a canonical grammar id case-insensitively; `CODE_HIGHLIGHT_EXTENSIONS` lists every suffix a preview registry can claim. `readLangHintForPath` projects the read card's short ids over the same table, so a suffix a recorded session already holds keeps its persisted value and every other suffix takes its language's short name. The package is browser-safe, stateless, and leaves tokenization to the Client highlighter.
+
+## Table of Contents
+
+- [Language selection](#language-selection)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="language-selection"></a>
+## Language selection
+
+The table lives in [`src/index.ts`](src/index.ts). Each key is a canonical language id — the grammar id the Client highlighter resolves — and each value is the lowercase extensions without the dot that select it. `languageForPath(path)` takes the text after the last dot of the final path segment, lowercases it, and looks it up in a `Map`; a `Map` keeps a filename such as `foo.constructor` from resolving an `Object.prototype` member. An unlisted dotfile (`.gitignore`), an absent extension, a trailing dot, and an unknown suffix all return `undefined`, which every consumer renders as plain text; a leading dot is still the separator, so `.env` resolves to `dotenv`. Both `/` and `\` separate path segments, so a Windows path resolves like a POSIX one.
+
+The set is curated for common source, config, script, data, and markup extensions rather than mirroring a full language registry. Extensions with no matching grammar map to the nearest one (`properties` to `ini`, whose registration carries the `properties` alias); certificate and lock extensions (`pem`, `crt`, `key`, `cer`, `lock`) stay unlisted. CSV maps to `csv`; preview registries place specialized viewers before Code so Spreadsheet remains its default preview. `readLangHintForPath` is a projection over this table: a suffix whose value a recorded session already holds returns that persisted short id, any other suffix returns its language's short name (`powershell` to `ps1`), and an unrecognized suffix returns `undefined` — so the persisted field holds one style, a short name; for `kotlin`, `swift`, `yaml`, `json`, and similar that name is also the grammar id, and the suffixes whose own name is the better label (`tsx`, `tf`, `tfvars`, `gradle`) keep it. A consumer that needs the Client highlighter to actually tokenize a language still depends on that grammar being registered there — an id without a loaded grammar renders as plain text rather than failing.
+
+-----
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Extension-only matching** — `languageForPath` reads a suffix, so names recognized without one (`Dockerfile`, `Makefile`, `.gitignore`, `.editorconfig`) stay unlisted. Filename rules are deferred.
+- **No content sniffing** — a file with an absent or unknown extension stays plain text even when its bytes are unambiguous; the table never inspects content.
+- **Curated, not exhaustive** — the table is smaller than Shiki's grammar catalog and GitHub linguist; adding a language means adding both the extension entry and the Client grammar registration.
+
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. This utility owns no mutable runtime relationship.

package/README.zh.md

@@ -0,0 +1,50 @@
+---
+description: "Client 代码界面与 Host read 卡片共享的唯一「扩展名 → 语法高亮语言」表。"
+kind: "package-library"
+---
+
+# dsh-util-code-language
+
+[English](README.md) | 中文
+
+## 概述
+
+本仓库唯一的「文件扩展名 → 语法高亮语言」表，供 Client 的文档 Code 预览、diff 审阅与 Host read 工具持久化的 `lang` 提示共同使用。`languageForPath` 以大小写不敏感的方式把文件名或路径映射为规范化 grammar id；`CODE_HIGHLIGHT_EXTENSIONS` 列出预览注册可以声明的全部后缀。`readLangHintForPath` 在同一张表上把 read 卡片的短 id 投影出来：已录制的会话已经持有该后缀的值时保持该持久化值不变，其余后缀取该语言的短名。该包可在浏览器使用，不提供 Cordis service，也不持有运行时状态；真正的分词仍由 Client 高亮器负责。
+
+## 目录
+
+- [语言选择](#language-selection)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="language-selection"></a>
+## 语言选择
+
+表位于 [`src/index.ts`](src/index.ts)。每个键是规范化语言 id——即 Client 高亮器解析的 grammar id；每个值是选中它的、不含点的小写扩展名。`languageForPath(path)` 取路径最后一段的最后一个点之后的文本、转小写后在 `Map` 中查找；使用 `Map` 可避免 `foo.constructor` 这类文件名解析到 `Object.prototype` 成员。未列入表的 dotfile（`.gitignore`）、无扩展名、结尾点、未知后缀都返回 `undefined`，各消费方一律按纯文本渲染；前导点仍算分隔符，因此 `.env` 解析为 `dotenv`。`/` 与 `\` 都算路径分隔符，因此 Windows 路径与 POSIX 路径解析一致。
+
+该集合按常见源码、配置、脚本、数据与标记扩展名精选，并非完整语言登记表。没有对应 grammar 的扩展名映射到最接近的 grammar（`properties` 映射到 `ini`，该 grammar 自带 `properties` alias）；证书与锁文件扩展名（`pem`、`crt`、`key`、`cer`、`lock`）不列入表。CSV 映射为 `csv`；预览注册表将专用查看器排在 Code 之前，因此 Spreadsheet 仍是它的默认预览。`readLangHintForPath` 在同一张表上做投影：已录制的会话已经持有该后缀的值时返回该持久化短 id，其余后缀返回该语言的短名（`powershell`→`ps1`），无法识别的后缀返回 `undefined`——持久化字段因此只有一种风格，即短名；对 `kotlin`、`swift`、`yaml`、`json` 等语言，短名与 grammar id 相同；而 `tsx`、`tf`、`tfvars`、`gradle` 这些后缀本身的名字更准确，保留其自身名字。消费方若希望 Client 高亮器真正分词，仍取决于该 grammar 已在其中注册——没有加载 grammar 的 id 会按纯文本渲染，而不是报错。
+
+-----
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **只匹配扩展名**——`languageForPath` 只看后缀，因此 `Dockerfile`、`Makefile`、`.gitignore`、`.editorconfig` 这类靠文件名识别的名称仍不表。文件名规则暂缓。
+- **不做内容嗅探**——扩展名缺失或未知时，即使字节含义明确也按纯文本处理；本表从不读取内容。
+- **精选而非穷举**——本表小于 Shiki 的 grammar 目录与 GitHub linguist；新增语言意味着同时添加扩展名条目与 Client grammar 注册。
+
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。这个工具不持有可变运行时关系。

package/lib/index.js

@@ -0,0 +1,269 @@
+//#region lib/types/index.js
+/**
+* Lowercase extension to canonical language id. A Map, not an object: a filename
+* whose extension is an `Object.prototype` key (`foo.constructor`,
+* `foo.__proto__`) must miss instead of resolving the inherited member, which
+* would otherwise reach callers as a non-string language value.
+*/
+const LANGUAGES = new Map(Object.entries({
+	typescript: [
+		"ts",
+		"tsx",
+		"mts",
+		"cts"
+	],
+	javascript: [
+		"js",
+		"jsx",
+		"mjs",
+		"cjs"
+	],
+	shellscript: [
+		"sh",
+		"bash",
+		"zsh"
+	],
+	fish: ["fish"],
+	json: [
+		"json",
+		"jsonc",
+		"jsonl",
+		"ndjson",
+		"ipynb"
+	],
+	csv: ["csv"],
+	python: [
+		"py",
+		"pyw",
+		"pyi"
+	],
+	ruby: [
+		"rb",
+		"rake",
+		"gemspec"
+	],
+	go: ["go"],
+	rust: ["rs"],
+	java: ["java"],
+	c: ["c", "h"],
+	cpp: [
+		"cc",
+		"cpp",
+		"cxx",
+		"hh",
+		"hpp",
+		"hxx"
+	],
+	csharp: ["cs"],
+	kotlin: ["kt", "kts"],
+	swift: ["swift"],
+	php: ["php"],
+	yaml: ["yaml", "yml"],
+	toml: ["toml"],
+	ini: [
+		"ini",
+		"conf",
+		"cfg",
+		"properties"
+	],
+	dotenv: ["env"],
+	log: ["log"],
+	diff: ["diff", "patch"],
+	http: ["http"],
+	markdown: ["md", "markdown"],
+	mdx: ["mdx"],
+	rst: ["rst"],
+	latex: [
+		"tex",
+		"sty",
+		"cls"
+	],
+	bibtex: ["bib"],
+	asciidoc: ["adoc"],
+	html: [
+		"html",
+		"htm",
+		"xhtml"
+	],
+	css: ["css"],
+	scss: ["scss"],
+	less: ["less"],
+	sql: ["sql"],
+	xml: [
+		"xml",
+		"xsd",
+		"xsl",
+		"xslt",
+		"plist",
+		"svg"
+	],
+	lua: ["lua"],
+	bat: ["bat", "cmd"],
+	powershell: [
+		"ps1",
+		"psm1",
+		"psd1"
+	],
+	r: ["r"],
+	julia: ["jl"],
+	dart: ["dart"],
+	scala: ["scala"],
+	clojure: [
+		"clj",
+		"cljs",
+		"edn"
+	],
+	erlang: ["erl", "hrl"],
+	elixir: ["ex", "exs"],
+	haskell: ["hs"],
+	fsharp: [
+		"fs",
+		"fsi",
+		"fsx"
+	],
+	vb: ["vb"],
+	perl: ["pl", "pm"],
+	verilog: ["v"],
+	"system-verilog": ["sv", "svh"],
+	graphql: ["graphql", "gql"],
+	proto: ["proto"],
+	hcl: [
+		"tf",
+		"tfvars",
+		"hcl"
+	],
+	nix: ["nix"],
+	vue: ["vue"],
+	svelte: ["svelte"],
+	make: ["makefile", "mk"],
+	cmake: ["cmake"],
+	groovy: ["gradle", "groovy"]
+}).flatMap(([language, extensions]) => extensions.map((extension) => [extension, language])));
+/** Every recognized filename suffix, one entry each; a document-preview registry uses it to claim Code-rendered bodies. */
+const CODE_HIGHLIGHT_EXTENSIONS = [...LANGUAGES.keys()];
+/**
+* Persisted `lang` values a language-level short id cannot express, keyed by the
+* suffix that produced them. Everything else falls back to
+* {@link SHORT_BY_LANGUAGE}, so only a suffix whose own name is the better label
+* appears here. Each value is the exact string recorded sessions already hold
+* and must not change; the byte-level expectation for every suffix lives in the
+* read consumer's test.
+*/
+const READ_LANG_BY_EXTENSION = new Map([
+	["tsx", "tsx"],
+	["jsx", "jsx"],
+	["tf", "tf"],
+	["tfvars", "tfvars"],
+	["gradle", "gradle"]
+]);
+/**
+* The short `lang` id the read card persists, keyed by canonical language id.
+* Keys are exactly the languages in {@link LANGUAGE_EXTENSIONS}: where
+* {@link READ_LANG_BY_EXTENSION} does not already fix a suffix's value, this
+* table supplies the language's short name (`powershell` to `ps1`, `hcl` to
+* `tf`, `system-verilog` to `sv`) rather than the grammar id. Keys are canonical
+* ids, not untrusted extensions, so an object lookup cannot reach an
+* `Object.prototype` member the way the extension tables can.
+*/
+const SHORT_BY_LANGUAGE = {
+	typescript: "ts",
+	javascript: "js",
+	shellscript: "sh",
+	fish: "fish",
+	json: "json",
+	csv: "csv",
+	python: "py",
+	ruby: "rb",
+	go: "go",
+	rust: "rs",
+	java: "java",
+	c: "c",
+	cpp: "cpp",
+	csharp: "cs",
+	kotlin: "kotlin",
+	swift: "swift",
+	php: "php",
+	yaml: "yaml",
+	toml: "toml",
+	ini: "ini",
+	dotenv: "env",
+	log: "log",
+	diff: "diff",
+	http: "http",
+	markdown: "md",
+	mdx: "mdx",
+	rst: "rst",
+	latex: "tex",
+	bibtex: "bib",
+	asciidoc: "adoc",
+	html: "html",
+	css: "css",
+	scss: "scss",
+	less: "less",
+	sql: "sql",
+	xml: "xml",
+	lua: "lua",
+	bat: "bat",
+	powershell: "ps1",
+	r: "r",
+	julia: "jl",
+	dart: "dart",
+	scala: "scala",
+	clojure: "clj",
+	erlang: "erl",
+	elixir: "ex",
+	haskell: "hs",
+	fsharp: "fs",
+	vb: "vb",
+	perl: "pl",
+	verilog: "v",
+	"system-verilog": "sv",
+	graphql: "graphql",
+	proto: "proto",
+	hcl: "hcl",
+	nix: "nix",
+	vue: "vue",
+	svelte: "svelte",
+	make: "make",
+	cmake: "cmake",
+	groovy: "groovy"
+};
+function extensionForPath(path) {
+	const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+	const base = path.slice(slash + 1);
+	const dot = base.lastIndexOf(".");
+	return dot < 0 ? void 0 : base.slice(dot + 1).toLowerCase();
+}
+/**
+* Derive the syntax-highlighting language from a filename or path, case
+* insensitively. The extension is the text after the last dot of the final path
+* segment; a leading dot is still the separator, so `.env` resolves to `dotenv`
+* while an unlisted dotfile (`.gitignore`) and an extensionless name return
+* `undefined`. Both path separators are recognized, so
+* `C:\\dir\\main.PS1` resolves like `dir/main.ps1`.
+* @param path - decoded filename or path.
+* @returns the canonical language id, or `undefined` for an unrecognized or absent suffix.
+*/
+function languageForPath(path) {
+	const extension = extensionForPath(path);
+	return extension === void 0 ? void 0 : LANGUAGES.get(extension);
+}
+/**
+* Derive the Host read card's persisted `lang` hint from a read path's
+* extension. The value is the language's short name; for some languages that name
+* is also the grammar id (`kotlin`, `swift`, `java`, `yaml`, `json`), and
+* {@link READ_LANG_BY_EXTENSION} overrides it where the suffix names itself
+* better (`tsx`, `tf`, `gradle`). A suffix a recorded session already holds keeps
+* its persisted value. An unrecognized suffix stays `undefined`, so the card
+* renders as plain text.
+* @param path - the model-facing path the read reported.
+* @returns the persisted language hint, or `undefined` when the extension maps to none.
+*/
+function readLangHintForPath(path) {
+	const extension = extensionForPath(path);
+	if (extension === void 0) return void 0;
+	const canonical = LANGUAGES.get(extension);
+	return canonical === void 0 ? void 0 : READ_LANG_BY_EXTENSION.get(extension) ?? SHORT_BY_LANGUAGE[canonical];
+}
+//#endregion
+export { CODE_HIGHLIGHT_EXTENSIONS, languageForPath, readLangHintForPath };

package/lib/types/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The single file-extension to syntax-highlighting language table shared by every
+ * code surface: the Client's document Code preview and diff review, and the Host
+ * read tool's persisted `lang` hint. Language ids are the grammar ids the Client
+ * highlighter's alias table resolves, so a language returned here reaches
+ * `highlightLines`/`highlightToHtml` unchanged; a filename outside the table, or
+ * one naming a language the highlighter does not register, renders as plain text.
+ * The read tool persists a short `lang` id, so {@link readLangHintForPath}
+ * projects short ids over this table: a suffix keeps the value a recorded session
+ * already holds, and every other suffix persists the language's short name —
+ * which for `kotlin`, `swift`, `yaml`, `json`, and similar equals that
+ * language's grammar id.
+ * @module @deepseek-ai/dsh-util-code-language
+ */
+/** Every recognized filename suffix, one entry each; a document-preview registry uses it to claim Code-rendered bodies. */
+export declare const CODE_HIGHLIGHT_EXTENSIONS: readonly string[];
+/**
+ * Derive the syntax-highlighting language from a filename or path, case
+ * insensitively. The extension is the text after the last dot of the final path
+ * segment; a leading dot is still the separator, so `.env` resolves to `dotenv`
+ * while an unlisted dotfile (`.gitignore`) and an extensionless name return
+ * `undefined`. Both path separators are recognized, so
+ * `C:\\dir\\main.PS1` resolves like `dir/main.ps1`.
+ * @param path - decoded filename or path.
+ * @returns the canonical language id, or `undefined` for an unrecognized or absent suffix.
+ */
+export declare function languageForPath(path: string): string | undefined;
+/**
+ * Derive the Host read card's persisted `lang` hint from a read path's
+ * extension. The value is the language's short name; for some languages that name
+ * is also the grammar id (`kotlin`, `swift`, `java`, `yaml`, `json`), and
+ * {@link READ_LANG_BY_EXTENSION} overrides it where the suffix names itself
+ * better (`tsx`, `tf`, `gradle`). A suffix a recorded session already holds keeps
+ * its persisted value. An unrecognized suffix stays `undefined`, so the card
+ * renders as plain text.
+ * @param path - the model-facing path the read reported.
+ * @returns the persisted language hint, or `undefined` when the extension maps to none.
+ */
+export declare function readLangHintForPath(path: string): string | undefined;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@deepseek-ai/dsh-util-code-language",
+  "description": "Single file-extension to syntax-highlighting language table shared by Client code surfaces and the Host read card",
+  "version": "0.1.7-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/code-language"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4"
+  }
+}