功能描述

Date/time anti-pattern scanner -- detects timezone bugs, naive datetime usage, hardcoded timestamps, non-ISO formats, incorrect epoch handling, DST-unsafe co...

使用说明 (SKILL.md)

\r \r

DateGuard -- Date/Time Anti-Pattern Scanner\r

Name: dateguard
Author: suhteevah

\r DateGuard scans codebases for date/time anti-patterns, timezone bugs, naive datetime usage, hardcoded timestamps, non-ISO formats, incorrect epoch handling, DST-unsafe comparisons, locale-dependent parsing, and temporal storage issues. It uses regex-based pattern matching against 90 date/time-specific patterns across 6 categories, lefthook for git hook integration, and produces markdown reports with actionable remediation guidance. 100% local. Zero telemetry.\r \r

Commands\r

\r

Free Tier (No license required)\r

\r

`dateguard scan [file|directory]`\r

One-shot date/time quality scan of files or directories.\r \r How to execute:\r

bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [target]\r
```\r
\r
**What it does:**\r
1. Accepts a file path or directory (defaults to current directory)\r
2. Discovers all source files (skips .git, node_modules, binaries, images, .min.js)\r
3. Runs 30 date/time quality patterns against each file (free tier limit)\r
4. Calculates a date/time quality score (0-100) per file and overall\r
5. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (\x3C60)\r
6. Outputs findings with: file, line number, check ID, severity, description, recommendation\r
7. Exit code 0 if score >= 70, exit code 1 if date/time quality is poor\r
8. Free tier limited to first 30 patterns (TZ + NF categories)\r
\r
**Example usage scenarios:**\r
- "Scan my code for timezone issues" -> runs `dateguard scan .`\r
- "Check this file for date anti-patterns" -> runs `dateguard scan src/server.ts`\r
- "Find naive datetime usage" -> runs `dateguard scan src/`\r
- "Audit date/time handling in my project" -> runs `dateguard scan .`\r
- "Check for DST-unsafe date math" -> runs `dateguard scan .`\r
\r
### Pro Tier ($19/user/month -- requires DATEGUARD_LICENSE_KEY)\r
\r
#### `dateguard scan --tier pro [file|directory]`\r
Extended scan with 60 patterns covering timezone, formatting, epoch precision, and date arithmetic.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [target] --tier pro\r
```\r
\r
**What it does:**\r
1. Validates Pro+ license\r
2. Runs 60 date/time patterns (TZ, NF, EP, DA categories)\r
3. Detects epoch precision bugs (ms vs seconds confusion)\r
4. Identifies DST-unsafe date arithmetic\r
5. Full category breakdown reporting\r
\r
#### `dateguard scan --format json [directory]`\r
Generate JSON output for CI/CD integration.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format json\r
```\r
\r
#### `dateguard scan --format html [directory]`\r
Generate HTML report for browser viewing.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format html\r
```\r
\r
#### `dateguard scan --category EP [directory]`\r
Filter scan to a specific check category (TZ, NF, EP, DA, CP, ST).\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --category EP\r
```\r
\r
### Team Tier ($39/user/month -- requires DATEGUARD_LICENSE_KEY with team tier)\r
\r
#### `dateguard scan --tier team [directory]`\r
Full scan with all 90 patterns across all 6 categories including comparison/parsing and storage/serialization.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --tier team\r
```\r
\r
**What it does:**\r
1. Validates Team+ license\r
2. Runs all 90 patterns across 6 categories\r
3. Includes comparison/parsing checks (string date comparison, == on Date objects)\r
4. Includes storage/serialization checks (VARCHAR for dates, missing timezone in DB)\r
5. Full category breakdown with per-file results\r
\r
#### `dateguard scan --verbose [directory]`\r
Verbose output showing every matched line and pattern details.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --verbose\r
```\r
\r
#### `dateguard status`\r
Show license and configuration information.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" status\r
```\r
\r
## Check Categories\r
\r
DateGuard detects 90 date/time anti-patterns across 6 categories:\r
\r
| Category | Code | Patterns | Description | Severity Range |\r
|----------|------|----------|-------------|----------------|\r
| **Timezone Handling** | TZ | 15 | Missing timezone in datetime creation, implicit local timezone, hardcoded offsets, timezone conversion without DST handling | medium -- high |\r
| **Naive Formatting** | NF | 15 | Non-ISO date formats in APIs, locale-dependent parsing, ambiguous MM/DD vs DD/MM, toString() on dates | low -- high |\r
| **Epoch & Precision** | EP | 15 | Millisecond vs second confusion, Y2038 risk, timestamps as strings, floating point timestamps, epoch 0 sentinels | low -- medium |\r
| **Date Arithmetic** | DA | 15 | Manual +86400 day math, month arithmetic ignoring varying lengths, leap year bugs, DST-crossing calculations | medium -- high |\r
| **Comparison & Parsing** | CP | 15 | Lexicographic date string comparison, Date == comparison, unparsed user input, timezone-unaware comparisons | medium -- high |\r
| **Storage & Serialization** | ST | 15 | VARCHAR for timestamps in SQL, missing timezone in stored dates, JSON.stringify on Date, hardcoded date strings | low -- high |\r
\r
## Tier-Based Pattern Access\r
\r
| Tier | Patterns | Categories |\r
|------|----------|------------|\r
| **Free** | 30 | TZ, NF |\r
| **Pro** | 60 | TZ, NF, EP, DA |\r
| **Team** | 90 | TZ, NF, EP, DA, CP, ST |\r
| **Enterprise** | 90 | TZ, NF, EP, DA, CP, ST + priority support |\r
\r
## Scoring\r
\r
DateGuard uses a deductive scoring system starting at 100 (perfect):\r
\r
| Severity | Point Deduction | Description |\r
|----------|-----------------|-------------|\r
| **Critical** | -25 per finding | Severe temporal bug (Y2038, data loss from timezone) |\r
| **High** | -15 per finding | Significant quality problem (naive datetime, DST math) |\r
| **Medium** | -8 per finding | Moderate concern (ambiguous formats, missing timezone) |\r
| **Low** | -3 per finding | Informational / best practice suggestion |\r
\r
### Grading Scale\r
\r
| Grade | Score Range | Meaning |\r
|-------|-------------|---------|\r
| **A** | 90-100 | Excellent date/time handling |\r
| **B** | 80-89 | Good handling with minor issues |\r
| **C** | 70-79 | Acceptable but needs improvement |\r
| **D** | 60-69 | Poor date/time quality |\r
| **F** | Below 60 | Critical temporal problems |\r
\r
- **Pass threshold:** 70 (Grade C or better)\r
- Exit code 0 = pass (score >= 70)\r
- Exit code 1 = fail (score \x3C 70)\r
\r
## Configuration\r
\r
Users can configure DateGuard in `~/.openclaw/openclaw.json`:\r
\r
```json\r
{\r
  "skills": {\r
    "entries": {\r
      "dateguard": {\r
        "enabled": true,\r
        "apiKey": "YOUR_LICENSE_KEY_HERE",\r
        "config": {\r
          "severityThreshold": "medium",\r
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],\r
          "ignoreChecks": [],\r
          "reportFormat": "text"\r
        }\r
      }\r
    }\r
  }\r
}\r
```\r
\r
## Important Notes\r
\r
- **Free tier** works immediately with no configuration\r
- **All scanning happens locally** -- no code is sent to external servers\r
- **License validation is offline** -- no phone-home or network calls\r
- Pattern matching only -- no AST parsing, no external dependencies beyond bash\r
- Supports scanning all file types in a single pass\r
- Git hooks use **lefthook** which must be installed (see install metadata above)\r
- Exit codes: 0 = pass (score >= 70), 1 = fail (for CI/CD integration)\r
- Output formats: text (default), json, html\r
\r
## Error Handling\r
\r
- If lefthook is not installed and user tries hooks, prompt to install it\r
- If license key is invalid or expired, show clear message with link to https://dateguard.pages.dev/renew\r
- If a file is binary, skip it automatically with no warning\r
- If no scannable files found in target, report clean scan with info message\r
- If an invalid category is specified with --category, show available categories\r
\r
## When to Use DateGuard\r
\r
The user might say things like:\r
- "Scan my code for timezone issues"\r
- "Check my date/time handling"\r
- "Find naive datetime usage"\r
- "Detect DST-unsafe date math"\r
- "Are there any hardcoded timestamps?"\r
- "Check for missing timezone handling"\r
- "Audit my date/time practices"\r
- "Find ambiguous date formats"\r
- "Check for epoch precision bugs"\r
- "Scan for date/time anti-patterns"\r
- "Run a date/time quality audit"\r
- "Generate a date/time quality report"\r
- "Check if dates are stored properly in my database schema"\r
- "Find Date objects compared with == instead of getTime()"\r
- "Check my code for Y2038 risks"\r

安全使用建议

DateGuard appears to do what it says: local regex-based scans and optional git-hook integration. Before installing or enabling hooks: (1) inspect the scripts yourself (they are included) to verify patterns you expect; (2) be aware that the installer writes/edits lefthook.yml and runs lefthook install in your repo which will run scans on pre-commit/pre-push and can block commits/pushes; (3) the license key (DATEGUARD_LICENSE_KEY) is required for pro/team features and can be stored in ~/.openclaw/openclaw.json or as an env var; an optional CLAWHUB_JWT_SECRET can enable local JWT signature checks but is not required and is not documented in the SKILL.md metadata — do not set secrets you don't understand; (4) run the tool in a test repo or with --no-verify workflow first to confirm it behaves as you expect. If you need higher assurance, consider running the scripts in a sandboxed environment or reviewing the complete shipped files (they are present in the bundle).

功能分析

Type: OpenClaw Skill Name: dateguard Version: 1.0.1 DateGuard is a legitimate date/time anti-pattern scanner that performs local code analysis using a comprehensive set of 90 regex patterns defined in `patterns.sh`. The tool includes a CLI dispatcher (`dispatcher.sh`), an analysis engine (`analyzer.sh`), and a license validation module (`license.sh`) that decodes JWTs offline to determine feature access (Free, Pro, Team). It supports git hook integration via `lefthook` and generates reports in multiple formats (JSON, HTML, Markdown). No evidence of data exfiltration, malicious execution, or harmful prompt injection was found; the code logic is consistent with its stated purpose of improving temporal code quality.

能力标签

requires-sensitive-credentials

能力评估

✓ Purpose & Capability

Name/description match the implementation: scripts provide file discovery, 90 regex patterns, scoring, reports, and git hook integration. Required binaries (git, bash, python3, jq) and lefthook (brew) are consistent with cataloging files, reading config, decoding JWTs, and installing git hooks.

ℹ Instruction Scope

Runtime instructions and scripts operate locally on the repository or specified paths and produce text/json/html reports. The skill reads ~/.openclaw/openclaw.json (declared in metadata) and environment variables for a license. One undocumented optional env var (CLAWHUB_JWT_SECRET) is referenced by license.sh for JWT signature verification; it is only used locally for verifying a provided token, but it is not declared in requires.env or documented in SKILL.md.

✓ Install Mechanism

Install uses a Homebrew formula (lefthook) which is a standard package manager flow. There are no arbitrary URL downloads or archive extraction steps in the install spec.

ℹ Credentials

Primary credential DATEGUARD_LICENSE_KEY is declared and used to unlock pro/team tiers; the scripts will also try to read the same key from ~/.openclaw/openclaw.json which is declared in configPaths. Aside from the declared license key and standard HOME/git environment, the code optionally reads CLAWHUB_JWT_SECRET (undeclared) to verify JWT signatures — this is not required for normal operation but worth noting.

ℹ Persistence & Privilege

The skill can install lefthook git hooks (pre-commit and pre-push) into a repository and run scans on commit/push. That behavior is consistent with a git-hook integration but does modify repository configuration (lefthook.yml) and will execute the shipped scripts on normal developer workflows — review and consent are recommended before installing hooks.

版本历史

v1.0.1

Fix: declare all deps, JWT verification, configPaths

v1.0.0

Initial release of DateGuard: a local date/time anti-pattern scanner for codebases. - Scans code for 90 date/time anti-patterns across 6 categories: timezone handling, naive formatting, epoch/precision, date arithmetic, comparison/parsing, and storage/serialization. - Free tier offers 30 core patterns (timezone & formatting) without a license. - Pro and Team tiers unlock up to 90 patterns, category filters, JSON/HTML reporting, and additional temporal checks. - Integrates with lefthook for git hook support and provides markdown reports with actionable remediation steps. - All scanning and license validation is performed 100% locally; no telemetry or network calls.

元数据

Slug dateguard

版本 1.0.1

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 2

常见问题

dateguard 是什么？

Date/time anti-pattern scanner -- detects timezone bugs, naive datetime usage, hardcoded timestamps, non-ISO formats, incorrect epoch handling, DST-unsafe co... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 87 次。

如何安装 dateguard？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install dateguard」即可一键安装，无需额外配置。

dateguard 是免费的吗？

是的，dateguard 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

dateguard 支持哪些平台？

dateguard 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（darwin, linux, win32）。

谁开发了 dateguard？

由 suhteevah（@suhteevah）开发并维护，当前版本 v1.0.1。

dateguard