codeguard-check

codeguard check

Read-only quality gate: identify the real scope, invoke the inspectors already configured in the repository, and preserve reproducible failure evidence.

Start in 30 seconds

First determine the engine (codeguard --version --format json), then choose the command surface. See the full comparison in codeguard skill's references/operations/engine-contract.md。

Legacy Python engine:

bin/codeguard detect .
bin/codeguard check .
bin/codeguard check --lang java,python --timeout 60 .

Rust component (currently always returns incomplete for quality paths):

codeguard detect . --format json
codeguard plan check all .
codeguard check all . --format json

The Rust-side check only accepts the positional argument all|java, there is no --lang；--timeout accepts a duration (e.g. 30m) rather than bare seconds. The Rust component returns exit code 3, which can only be expressed as a partial native observation or incomplete,cannot be used as a gate-pass conclusion。

Before execution, record the working directory, current branch, target module, and tool version, and state which engine issued the result. If bin/codeguard does not exist, do not guess a command or claim it passed; instead use the repository's authoritative CI/lint command or report UNVERIFIED。

Capability boundaries

✅ Strengths

1. Automatically detect project languages and run multilingual lint in one go.
2. Report each language's command, exit code, elapsed time, and status in a table.
3. Under Legacy, use --lang and --timeout to narrow down the failure scope; under Rust, first use plan to view the read-only plan.
4. Distinguish code violations, configuration errors, missing tools, incomplete execution, and executor errors.
5. Produce structured evidence for fixes and CI reproduction.

⚠️ Prerequisites

1. The Codeguard CLI or the corresponding source script is available.
2. The corresponding language toolchain and repository configuration are ready.
3. The execution directory is the real repository or module root, not an arbitrary parent directory.
4. Checks that require network or private servers have been explicitly authorized.

❌ Out of Scope

1. Leave auto-fixing to the codeguard-fix skill. Install:npx skills add full-stack-skills/codeguard-skills --skill codeguard-fix。
2. Leave CVE scanning to the codeguard-cve skill. Install:npx skills add full-stack-skills/codeguard-skills --skill codeguard-cve。
3. Do not expand a lint pass into a compile, test, security, or release pass.
4. Do not modify ignore, suppression, or rule thresholds during a check task.

When to use

• The user asks to "run lint", "check code style", or self-check before committing.
• CI reports a Codeguard/linter failure and it needs to be reproduced locally.
• A cross-language repository needs a unified result summary.
• It is necessary to determine whether the current state is FAIL or UNVERIFIED.

Out of scope (when not to use)

• The user is only asking about syntax or framework design; use language/framework professional skills instead.
• The main issue is dependency vulnerabilities, credential leaks, or data compliance.
• There is no repository context but a request is made to prove "the entire repository is all green".

Data and security

This skill does not collect, upload, send, or store user source code or credentials. By default it runs local tools in read-only mode; if a command may access the network, a private server, or a cache, this must be stated first. Reports should redact tokens, usernames in paths, and business data as necessary.

Command contract

Legacy Python engine:

bin/codeguard check                        # 全量
bin/codeguard check --lang java,python     # 限定语言
bin/codeguard check --timeout 60 path/     # 指定项目与超时（裸秒数）

Rust engine (--lang does not exist,--timeout Use duration; exit code 3 indicates incomplete):

codeguard check all path/ --timeout 30m --format json
codeguard check java path/ --format json

The actual CLI parameters are subject to bin/codeguard check --help(Legacy) or codeguard --help(Rust). The skill package only provides operational knowledge and does not pretend to contain the Codeguard runtime.

Status Semantics

Status	Evidence	Follow-up Action
PASS	The authoritative check command exits 0 within a clearly defined scope	This lint gate can be reported as passed
FAIL	The tool runs successfully and finds violations	Fix by category: formatting/rules/configuration
UNVERIFIED	Tool, configuration, permissions, version, timeout, or insufficient environment	Fill in the prerequisites; do not write passed
INCOMPLETE	The check did not run to completion per the contract (Rust engine exit code 3, required checks missing, some modules not covered)	List the incomplete items,do not write passed, and do not state it as zero violations
PLANNED	The registry has only identification capability, with no executable gate	List the tools pending integration and the acceptance conditions

Standard Workflow

Step 1: Determine Scope

Read the repository instructions, check Git status, and confirm monorepo modules, generated directories, vendor, and submodules.

Step 2: Identify Languages

Run bin/codeguard detect <path>, and cross-validate the detection results with the project marker files.

Step 3: Verify Authoritative Commands

Read the repository configuration and CI; if the commands used by CI are stricter than Codeguard's default commands, CI takes precedence.

Step 4: Probe Tools

Record the Codeguard and language tool versions.command not found, inability to load configuration, or incompatible versions are all UNVERIFIED。

Step 5: Execute Read-Only Checks

Save the full command, working directory, language scope, exit code, and the first actionable error.

Step 6: Classify Failures

Type	Signal	Handling
Formatting	Indentation, whitespace, import order	Can be delegated to a controlled formatter
Static Rules	unused, naming, complexity, dangerous APIs	Minimal semantic fix
Configuration	schema/parser/config errors	Fix the integration first; do not pad the numbers by changing code
Environment	Missing tools, version conflicts, timeouts	Report the prerequisites
Tool Crash	traceback, panic, parser exception	Narrow down the reproduction and preserve the original evidence

Step 7: Output Results

List PASS/FAIL/UNVERIFIED/INCOMPLETE/PLANNED by language, and keep lint, test, build, and security evidence separate.

Rules

1. Missing tools, timeouts, and configuration errors do not equal passing.
2. Do not use --no-verify, ignore, or lowering thresholds to fake a green light.
3. The same conclusion must come with the command, scope, and exit code.
4. Do not modify user files during the check phase.
5. Do not use passing in one language to mask failure in another language.

Output Template

Codeguard check 结果
- 引擎：<legacy | rust>
- 范围：<repo/module/path>
- 检测语言：<list>
- 命令：<actual command>
- 工具：<versions>
- 结果：<language -> PASS/FAIL/UNVERIFIED/INCOMPLETE/PLANNED>
- 发现：<categorized findings>
- 未验证：<test/build/security/platform gaps>
- 未完成：<required checks not run>

Gotchas

1. Wrong root directory: Running in the parent directory of a monorepo may load the wrong configuration or miss modules.
2. Automatic tool downloads: Maven/npm etc. may access the network during checks; a network failure should not be treated as a code failure.
3. Generated file noise: Follow the repository ignore; do not scan vendor or generated artifacts on your own.
4. Tool version drift: When local and CI versions differ, a local PASS cannot predict a CI PASS.
5. Timeout semantics: A timeout is UNVERIFIED, not zero findings.
6. Compilation and lint layering：compile Exit code 0 does not mean javadoc, style, or security gates passed.

Load resources on demand

• To interpret exit codes and status, read references/rules/result-semantics.md。
• To reproduce CI or design an evidence bundle, read references/operations/check-playbook.md。
• When a reproducible scenario is needed, open only examples/ a matching file in .