@vibecodeqa/cli 0.19.0 → 0.20.1

package/dist/check-meta.js

@@ -136,7 +136,7 @@ export const CHECK_META = {
         label: "Architecture",
         category: "Architecture",
         priority: "high",
-        weight: 6,
+        weight: 5,
         description: "Analyzes the import graph to detect structural problems: circular dependencies, god modules (imported by >50% of files), orphan modules (dead code), high fan-out (importing too many modules), and connector modules (high coupling). Generates an SVG architecture diagram.",
         risk: "Circular dependencies create build order issues and make refactoring impossible without breaking changes. God modules become bottlenecks — any change ripples through the entire codebase. High coupling means you can't change one module without testing everything it touches.",
         recommendation: "Break circular deps by extracting shared types to a separate file. Split god modules by concern. Reduce fan-out by co-locating related code. Use dependency injection for loose coupling.",
@@ -146,7 +146,7 @@ export const CHECK_META = {
         label: "Confusion Index",
         category: "LLM Readiness",
         priority: "high",
-        weight: 7,
+        weight: 6,
         description: "Measures naming ambiguity that causes LLMs to misunderstand or edit the wrong code. Checks: file name confusability (Levenshtein distance + synonym detection), generic function/variable names, export name collisions across files, and ambiguous abbreviations.",
         risk: "GPT-4o drops 28.6 percentage points on code summarization when names are ambiguous (arXiv:2510.03178). LLMs editing similar-named files is the #1 reported failure mode in AI-assisted development. Generic names like process(), handle(), data cause models to misinterpret intent.",
         recommendation: "Use descriptive, unique names. Avoid synonym files (utils.ts + helpers.ts — pick one). Avoid generic exports. Disambiguate abbreviations (use 'authentication' not 'auth' if both auth meanings exist in the codebase).",
@@ -156,7 +156,7 @@ export const CHECK_META = {
         label: "Context Locality",
         category: "LLM Readiness",
         priority: "high",
-        weight: 6,
+        weight: 5,
         description: "Measures how self-contained code is for LLM consumption. Checks: token density per file, import count, circular dependencies, and context sinks (files that import many modules but export little). Based on the finding that LLMs lose 30%+ accuracy for information in the middle of long contexts.",
         risk: "Files over ~4000 tokens exceed the 'sweet spot' for LLM attention (Liu et al. 2023 'Lost in the Middle'). Circular dependencies create infinite loops in LLM code navigation. Heavy import chains force LLMs to load many files, burning context window budget (Chroma 'Context Rot' 2025).",
         recommendation: "Keep files under 400 lines / 4000 tokens. Limit imports to <15 per file. Break circular dependencies. Co-locate related code to reduce cross-file jumps.",
@@ -191,6 +191,16 @@ export const CHECK_META = {
         risk: "Barrel files (index.ts re-exports) prevent bundlers from tree-shaking unused code, bloating bundles by 2-10x. Heavy dependencies like moment.js add 300KB when date-fns does the same in 7KB. Static imports of visualization libraries delay initial page load.",
         recommendation: "Replace barrel re-exports with direct imports. Swap heavy deps for lighter alternatives. Use dynamic import() for large libraries only needed on interaction. Prefer zero-runtime CSS (Tailwind, CSS Modules) over styled-components.",
     },
+    "best-practices": {
+        name: "best-practices",
+        label: "Best Practices",
+        category: "Quality",
+        priority: "medium",
+        weight: 3,
+        description: "Advisory check for industry-standard CI/CD, supply chain, and repo hygiene practices. Checks: GitHub Actions with explicit permissions, OIDC instead of long-lived tokens, pinned action SHAs, frozen lockfile in CI, committed lockfile, engine constraints, SECURITY.md, CODEOWNERS, CONTRIBUTING.md, .env.example, pre-commit hooks, automated dependency updates (Dependabot/Renovate).",
+        risk: "Missing CI/CD practices lead to supply chain attacks (tj-actions breach affected 23,000 repos in 2025). Long-lived tokens can be stolen from CI logs. Unpinned actions allow tag-poisoning. No lockfile means non-reproducible builds. No SECURITY.md means vulnerabilities go unreported.",
+        recommendation: "Pin third-party actions to SHA. Use OIDC trusted publishing instead of tokens. Set explicit permissions in workflows. Add SECURITY.md, CODEOWNERS, and CONTRIBUTING.md. Configure Dependabot or Renovate for automated dependency updates. Add pre-commit hooks.",
+    },
     "doc-coherence": {
         name: "doc-coherence",
         label: "Doc Coherence",

package/dist/cli.js

@@ -5,6 +5,7 @@ import { join, resolve } from "node:path";
 import { detectRepoUrl, detectStack } from "./detect.js";
 import { generatePages } from "./report/html.js";
 import { runArchitecture } from "./runners/architecture.js";
+import { runBestPractices } from "./runners/best-practices.js";
 import { runComplexity } from "./runners/complexity.js";
 import { runConfusion } from "./runners/confusion.js";
 import { runContext } from "./runners/context.js";
@@ -79,6 +80,7 @@ async function main() {
         { name: "react", fn: () => runReact(cwd, stack) },
         { name: "accessibility", fn: () => runAccessibility(cwd) },
         { name: "docs", fn: () => runDocs(cwd) },
+        { name: "best-practices", fn: () => runBestPractices(cwd) },
         // Testing
         { name: "testing", fn: () => runTesting(cwd, stack, skipTests) },
         // Security

package/dist/report/html.js

@@ -16,7 +16,7 @@ import { categoryPage, filesPage, issuesPage, overviewPage } from "./pages.js";
 import { CSS } from "./styles.js";
 export const GROUPS = [
     { id: "foundations", label: "Foundations", file: "foundations.html", checks: ["structure", "lint", "types", "type-safety", "standards"] },
-    { id: "quality", label: "Quality", file: "quality.html", checks: ["complexity", "duplication", "error-handling", "react", "accessibility", "docs"] },
+    { id: "quality", label: "Quality", file: "quality.html", checks: ["complexity", "duplication", "error-handling", "react", "accessibility", "docs", "best-practices"] },
     { id: "testing", label: "Testing", file: "testing.html", checks: ["testing"] },
     { id: "arch", label: "Architecture", file: "architecture.html", checks: ["architecture", "performance"] },
     { id: "security", label: "Security", file: "security.html", checks: ["secrets", "security", "dependencies"] },

package/dist/runners/best-practices.d.ts

@@ -0,0 +1,13 @@
+/** Best Practices advisory — checks for industry-standard CI/CD, repo hygiene, and supply chain practices.
+ *
+ * Unlike other checks, this doesn't penalize harshly — it advises.
+ * Issues are "info" and "warning" severity, not errors.
+ *
+ * Categories:
+ *   1. CI/CD — workflows, OIDC, pinned actions, permissions
+ *   2. Supply chain — lockfile, provenance, dependency pinning
+ *   3. Repo hygiene — branch protection signals, CODEOWNERS, security policy
+ *   4. Developer experience — contributing guide, .env.example, scripts
+ */
+import type { CheckResult } from "../types.js";
+export declare function runBestPractices(cwd: string): CheckResult;

package/dist/runners/best-practices.js

@@ -0,0 +1,319 @@
+/** Best Practices advisory — checks for industry-standard CI/CD, repo hygiene, and supply chain practices.
+ *
+ * Unlike other checks, this doesn't penalize harshly — it advises.
+ * Issues are "info" and "warning" severity, not errors.
+ *
+ * Categories:
+ *   1. CI/CD — workflows, OIDC, pinned actions, permissions
+ *   2. Supply chain — lockfile, provenance, dependency pinning
+ *   3. Repo hygiene — branch protection signals, CODEOWNERS, security policy
+ *   4. Developer experience — contributing guide, .env.example, scripts
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readDeps } from "../fs-utils.js";
+import { gradeFromScore } from "../types.js";
+export function runBestPractices(cwd) {
+    const start = Date.now();
+    const issues = [];
+    let practices = 0;
+    let followed = 0;
+    const has = (f) => existsSync(join(cwd, f));
+    const read = (f) => { try {
+        return readFileSync(join(cwd, f), "utf-8");
+    }
+    catch {
+        return "";
+    } };
+    // ── 1. CI/CD Best Practices ──
+    // Check for GitHub Actions workflows
+    const hasWorkflows = has(".github/workflows");
+    practices++;
+    if (hasWorkflows) {
+        followed++;
+        const workflows = readdirSync(join(cwd, ".github/workflows")).filter(f => f.endsWith(".yml") || f.endsWith(".yaml"));
+        for (const wf of workflows) {
+            const content = read(`.github/workflows/${wf}`);
+            // Check: actions pinned to SHA (not @v4, @main)
+            const actionUses = content.match(/uses:\s*([^\n]+)/g) || [];
+            const unpinned = actionUses.filter(u => !u.includes("@") || (!u.match(/@[a-f0-9]{40}/) && !u.includes("@sha")));
+            // Only flag third-party actions (not actions/*)
+            const unpinnedThirdParty = unpinned.filter(u => !u.includes("actions/") && !u.includes("pnpm/"));
+            if (unpinnedThirdParty.length > 0) {
+                issues.push({
+                    severity: "info",
+                    message: `${wf}: ${unpinnedThirdParty.length} third-party actions not pinned to SHA — vulnerable to supply chain attacks`,
+                    file: `.github/workflows/${wf}`,
+                    rule: "pin-actions-to-sha",
+                });
+            }
+            // Check: minimal permissions
+            practices++;
+            if (content.includes("permissions:")) {
+                followed++;
+            }
+            else {
+                issues.push({
+                    severity: "warning",
+                    message: `${wf}: no explicit permissions block — defaults to read-write (overly permissive)`,
+                    file: `.github/workflows/${wf}`,
+                    rule: "explicit-permissions",
+                });
+            }
+            // Check: OIDC for publishing (no long-lived tokens)
+            if (content.includes("publish") || content.includes("deploy")) {
+                practices++;
+                if (content.includes("id-token: write")) {
+                    followed++;
+                }
+                else if (content.includes("NPM_TOKEN") || content.includes("DEPLOY_TOKEN") || content.includes("AWS_ACCESS_KEY")) {
+                    issues.push({
+                        severity: "info",
+                        message: `${wf}: uses long-lived secret tokens — consider OIDC trusted publishing/workload identity`,
+                        file: `.github/workflows/${wf}`,
+                        rule: "prefer-oidc",
+                    });
+                }
+            }
+            // Check: frozen lockfile in CI
+            practices++;
+            if (content.includes("--frozen-lockfile") || content.includes("--ci") || content.includes("npm ci")) {
+                followed++;
+            }
+            else if (content.includes("install")) {
+                issues.push({
+                    severity: "info",
+                    message: `${wf}: CI install without frozen lockfile — builds may not be reproducible`,
+                    file: `.github/workflows/${wf}`,
+                    rule: "frozen-lockfile-ci",
+                });
+            }
+        }
+    }
+    else {
+        issues.push({
+            severity: "warning",
+            message: "No .github/workflows/ — no CI/CD automation. Add GitHub Actions for automated testing and deployment.",
+            rule: "no-ci",
+        });
+    }
+    // ── 2. Supply Chain ──
+    // Lockfile committed
+    practices++;
+    const hasLockfile = has("pnpm-lock.yaml") || has("package-lock.json") || has("yarn.lock") || has("bun.lockb") || has("pubspec.lock");
+    if (hasLockfile) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "warning", message: "No lockfile committed — dependency versions not deterministic", rule: "lockfile" });
+    }
+    // .npmrc or package.json engine constraints
+    practices++;
+    const pkg = read("package.json");
+    if (pkg.includes('"engines"') || has(".nvmrc") || has(".node-version") || has(".tool-versions")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No engine constraints (engines in package.json or .nvmrc) — Node version not pinned", rule: "pin-node-version" });
+    }
+    // npm provenance / package.json has repository field
+    if (pkg) {
+        practices++;
+        if (pkg.includes('"repository"')) {
+            followed++;
+        }
+        else {
+            issues.push({ severity: "info", message: "package.json missing repository field — provenance attestation won't link to source", rule: "repository-field" });
+        }
+    }
+    // ── 3. Repo Hygiene ──
+    // SECURITY.md or security policy
+    practices++;
+    if (has("SECURITY.md") || has(".github/SECURITY.md")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No SECURITY.md — users don't know how to report vulnerabilities", rule: "security-policy" });
+    }
+    // CODEOWNERS
+    practices++;
+    if (has("CODEOWNERS") || has(".github/CODEOWNERS") || has("docs/CODEOWNERS")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No CODEOWNERS file — no mandatory reviewers for critical paths", rule: "codeowners" });
+    }
+    // Branch protection signal: require PR (check for documented merge strategy)
+    practices++;
+    if (has("CONTRIBUTING.md") || has(".github/CONTRIBUTING.md")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No CONTRIBUTING.md — onboarding is harder for new contributors", rule: "contributing-guide" });
+    }
+    // ── 4. Developer Experience ──
+    // .env.example
+    practices++;
+    const hasEnvFiles = has(".env") || has(".env.local") || has(".env.development");
+    if (hasEnvFiles && !has(".env.example")) {
+        issues.push({ severity: "info", message: "Has .env files but no .env.example — new developers won't know what vars are needed", rule: "env-example" });
+    }
+    else {
+        followed++;
+    }
+    // Pre-commit hooks (husky, lefthook, lint-staged)
+    practices++;
+    const deps = readDeps(cwd);
+    if (deps.husky || deps.lefthook || deps["lint-staged"] || has(".husky") || has(".lefthook.yml")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No pre-commit hooks (husky/lefthook) — lint/format not enforced before commit", rule: "pre-commit-hooks" });
+    }
+    // Renovate/Dependabot for automated dependency updates
+    practices++;
+    if (has(".github/dependabot.yml") || has("renovate.json") || has(".renovaterc") || has(".renovaterc.json")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No Dependabot/Renovate — dependency updates are manual and often forgotten", rule: "automated-deps" });
+    }
+    // ── 5. Code Quality Tooling ──
+    // Linter configured
+    practices++;
+    if (has("biome.json") || has(".eslintrc.json") || has(".eslintrc.js") || has("eslint.config.js") || has("eslint.config.ts") || has("analysis_options.yaml")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "warning", message: "No linter config (ESLint/Biome/dart analyze) — code style not enforced", rule: "linter-config" });
+    }
+    // Formatter configured
+    practices++;
+    if (has("biome.json") || has(".prettierrc") || has(".prettierrc.json") || has("prettier.config.js") || has(".editorconfig")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No formatter config (Prettier/Biome/.editorconfig) — inconsistent code formatting", rule: "formatter-config" });
+    }
+    // TypeScript strict mode
+    practices++;
+    const tsconfig = read("tsconfig.json");
+    if (!tsconfig || tsconfig.includes('"strict": true') || tsconfig.includes('"strict":true')) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "TypeScript strict mode not enabled — allows implicit any and null errors", rule: "ts-strict-mode" });
+    }
+    // ── 6. Testing Best Practices ──
+    // Test script exists
+    practices++;
+    if (pkg.includes('"test"') || has("pubspec.yaml")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "warning", message: "No test script in package.json — testing not configured", rule: "test-script" });
+    }
+    // Coverage configured
+    practices++;
+    if (pkg.includes("coverage") || has("vitest.config.ts") || has("jest.config.ts") || has("jest.config.js")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No test coverage configuration — coverage thresholds not enforced", rule: "coverage-config" });
+    }
+    // ── 7. Docker / Deployment ──
+    // Dockerfile best practices (if Docker is used)
+    if (has("Dockerfile") || has("docker-compose.yml") || has("docker-compose.yaml")) {
+        practices++;
+        const dockerfile = read("Dockerfile");
+        if (dockerfile.includes("FROM") && !dockerfile.includes("latest")) {
+            followed++;
+        }
+        else if (dockerfile.includes(":latest")) {
+            issues.push({ severity: "warning", message: "Dockerfile uses :latest tag — pin to a specific version for reproducible builds", rule: "docker-pin-version" });
+        }
+        else {
+            followed++;
+        }
+        // Multi-stage build
+        practices++;
+        const fromCount = (dockerfile.match(/^FROM /gm) || []).length;
+        if (fromCount >= 2) {
+            followed++;
+        }
+        else if (dockerfile.length > 100) {
+            issues.push({ severity: "info", message: "Dockerfile is single-stage — consider multi-stage to reduce image size", rule: "docker-multi-stage" });
+        }
+        else {
+            followed++;
+        }
+        // .dockerignore
+        practices++;
+        if (has(".dockerignore")) {
+            followed++;
+        }
+        else {
+            issues.push({ severity: "info", message: "No .dockerignore — node_modules and build artifacts will bloat Docker image", rule: "dockerignore" });
+        }
+    }
+    // ── 8. Git Practices ──
+    // .gitignore is comprehensive
+    practices++;
+    const gitignore = read(".gitignore");
+    if (gitignore.includes("node_modules") || gitignore.includes(".dart_tool") || gitignore.includes("build/")) {
+        followed++;
+    }
+    else if (gitignore) {
+        issues.push({ severity: "info", message: ".gitignore exists but may be incomplete — ensure build artifacts are excluded", rule: "gitignore-complete" });
+    }
+    else {
+        followed++; // no gitignore = handled by structure check
+    }
+    // Conventional commits signal (commitlint or similar)
+    practices++;
+    if (deps.commitlint || deps["@commitlint/cli"] || has("commitlint.config.js") || has(".commitlintrc.json") || has(".changeset")) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No commit convention enforcement (commitlint/changesets) — changelog generation is manual", rule: "conventional-commits" });
+    }
+    // ── 9. Monitoring & Observability ──
+    // Error tracking (Sentry, Bugsnag, etc.)
+    practices++;
+    if (deps["@sentry/node"] || deps["@sentry/react"] || deps["@sentry/browser"] || deps.bugsnag || deps["@bugsnag/js"]) {
+        followed++;
+    }
+    else {
+        issues.push({ severity: "info", message: "No error tracking (Sentry/Bugsnag) — production errors may go unnoticed", rule: "error-tracking" });
+    }
+    // ── 10. API & Configuration ──
+    // Environment validation (zod, joi, envalid)
+    practices++;
+    if (deps.zod || deps.joi || deps.envalid || deps["@t3-oss/env-core"] || deps["@t3-oss/env-nextjs"]) {
+        followed++;
+    }
+    else {
+        const hasEnvUsage = pkg.includes("process.env") || read("src/index.ts").includes("process.env") || read("src/main.ts").includes("process.env");
+        if (hasEnvUsage) {
+            issues.push({ severity: "info", message: "Uses env vars but no validation library (zod/envalid) — missing vars crash at runtime", rule: "env-validation" });
+        }
+        else {
+            followed++;
+        }
+    }
+    // ── Score ──
+    const pct = practices > 0 ? Math.round((followed / practices) * 100) : 100;
+    const score = pct;
+    return {
+        name: "best-practices",
+        score,
+        grade: gradeFromScore(score),
+        details: {
+            practicesChecked: practices,
+            practicesFollowed: followed,
+            adherence: `${pct}%`,
+        },
+        issues,
+        duration: Date.now() - start,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecodeqa/cli",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Code health scanner for the AI coding era. 21 checks, zero config, full report.",
   "type": "module",
   "bin": {