codeguard-detect

codeguard detect

Capability Boundaries

✅ Strengths

1. Recognition of 55 languages/file types (triple: extensions + filenames + project marker files)
2. Project root codeguard.json Custom extension mappings (drawing on codegraph's zero-config + overridable design)
3. Outputs JSON for other tools/skills to consume

⚠️ Prerequisites

1. None (pure Python standard library)

❌ Out of Scope

1. Framework-level recognition (framework detection for Spring/React etc. is on the roadmap)
2. Language version detection (.nvmrc / pom java.version parsing)

Command

bin/codeguard detect              # 当前目录
bin/codeguard detect path/to/pkg  # 指定目录
# 等价：python3 scripts/detect_lang.py path/

Example output

["java"]
["typescript", "vue"]
["go", "markdown"]

Custom extension mappings

Project root codeguard.json：

{
  "extensions": {
    ".dota_lua": "lua",
    ".tpl": "php"
  },
  "exclude": ["vendor/**", "generated/**"]
}

• extensions: merge/override the built-in default mappings
• exclude: file patterns to exclude when scanning (glob/regex strings)

Out of scope (when not to use it)

• Requires precise determination of language or framework version: the detector only identifies types, it does not parse a full dependency graph.
• Requires running lint or fixes: hand off to codeguard-check or codeguard-fix。
• Wants to prove a repository is buildable based on extensions alone: detection results are not build evidence.

Data and security

Detection should be done locally, without collecting, uploading, or storing source code and credentials. Only relative paths, filenames, and necessary marker files are read; reports redact user directories and internal module names as needed.

Standard Workflow

Step 1: Determine the root directory

First find the Git root or the monorepo module specified by the user; do not scan the entire parent workspace.

Step 2: Read exclusion rules

Merge the repository's existing ignore strategy with codeguard.json 's exclude, and clarify the boundaries of generated code, vendor, caches, and sub-repositories.

Step 3: Run detection

Run bin/codeguard detect <path>, and save the actual command, scope, exit code, and structured output.

Step 4: Cross-validate

Recheck the results against marker files and primary source files. When extensions conflict, report the ambiguity rather than silently guessing.

Step 5: Routing gate

For stable languages, enter the corresponding check skill; for planned languages, state clearly that they can only be recognized and cannot yet run the gate.

Rules

1. A language being "recognized" does not equal "linter integrated".
2. Custom mappings must be based on repository facts or user confirmation; do not falsify types to pass the gate.
3. Do not follow symlinks that extend beyond the repository root.
4. For large repositories, prefer specifying a module scope instead of an unrestricted full scan.

Output template

Codeguard detect 结果
- 根目录：<path>
- 排除：<patterns>
- 识别：<language -> evidence>
- 状态：<stable/planned>
- 歧义：<conflicting extensions or markers>
- 下一步：<matching check skill or missing gate>

Gotchas

1. .h and other extensions are ambiguous: need to be judged together with build files for C/C++/Objective-C.
2. Template files may mix languages：.vue、.astro etc. cannot have their main language guessed from the number of embedded snippets.
3. vendor pollutes the results: when third-party code is not excluded, the recognized language may not be maintained by the project.
4. Marker files can be leftovers: need cross-validation with real source files and CI.
5. Sub-repositories and worktrees: do not mistakenly apply the outer workspace's config to an inner repository.
6. planned capability: Can only route to instructions, must not output PASS.

Load resources on demand

• Read when explanation of recognition priority is needed references/rules/detection-precedence.md。
• When configuration is needed codeguard.json read references/operations/configuration-guide.md。
• Only open examples/ the examples in that match the current scenario.