@kogu/context-check 0.1.0

package/LICENSE

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

@@ -0,0 +1,213 @@
+# contextcheck
+
+> **See what your AI coding context contains, what changed, and what deserves review.**
+
+> **Beta:** `contextcheck` şu anda beta kanalında yayınlanıyor. Kullanım:
+> `npm install -g context-check@beta` veya `npx context-check@beta analyze`.
+
+contextcheck, AI coding agent'ların kullandığı instructions, rules ve skills
+dosyalarını (CLAUDE.md, AGENTS.md, .cursor/rules, SKILL.md) keşfeden,
+deterministic olarak analiz eden ve context layer'ın zaman içindeki değişimini
+takip etmeni sağlayan **local-first** bir developer tooludur.
+
+- Local-first: içerik makineden çıkmaz
+- Deterministic: LLM/embedding/API/DB yok
+- Açıklanabilir: her finding ne/neden/hangi dosya açıklamalı
+- Review, never remove: otomatik silme/düzeltme yok
+
+## Hızlı Başlangıç (ilk 30 saniye)
+
+```bash
+# 1) Mevcut AI context'ini gör
+npx context-check@beta analyze
+
+# 2) Bir anlık görüntü al
+npx context-check@beta snapshot
+
+# 3) Kurallarında değişiklik yap, ne değiştiğini gör
+npx context-check@beta diff
+```
+
+Bunların hepsi hesap gerektirmez, hiçbir içerik cihazından çıkmaz.
+
+Global kurulum tercih edersen:
+
+```bash
+npm install -g context-check@beta
+context-check analyze
+```
+
+## Kullanım
+
+```bash
+# Tüm AI configuration dosyalarını keşfet + analiz et
+context-check analyze
+
+# Detaylı bulgular
+context-check analyze --verbose
+
+# Hızlı insan çıktısı (summary + findings)
+context-check analyze --compact
+
+# Makine tarafından okunabilir, privacy-safe JSON çıktısı
+context-check analyze --json
+
+# CI'da findings eşik üstüyse başarısız ol
+context-check analyze --json --fail-on notice
+```
+
+Üç çıktı kontratı:
+
+```text
+context-check analyze          -> detaylı, varsayılan (spec §9)
+context-check analyze --compact -> hızlı insan çıktısı
+context-check analyze --json    -> CI / automation (privacy-safe)
+```
+
+## Komutlar
+
+- `context-check analyze` — keşfet ve analiz et
+- `context-check analyze --verbose` — detaylı bulgular
+- `context-check analyze --json` — privacy-safe JSON (raw content yok)
+- `context-check analyze --compact` — hızlı/kompakt insan çıktısı
+- `context-check analyze --fail-on <info|notice|warning>` — eşik üstü finding'de exit 1
+- `context-check snapshot` — AI configuration snapshot oluştur
+- `context-check snapshot list` — kayıtlı snapshot'ları listele
+- `context-check diff` — en son snapshot ile mevcut durumu karşılaştır (artifact + token + finding değişimleri)
+- `context-check diff <snapshot-id>` — belirtilen snapshot ile mevcut durumu karşılaştır
+- `context-check diff --json` — privacy-safe JSON diff
+- `context-check config` — yapılandırma (`.contextcheck.json`)
+
+## Exit code politkası
+
+Varsayılan (informational): findings CI'ı kırmaz — `no findings`, `info` ve
+`notice` hepsi `exit 0`. `--fail-on` belirtilirse eşik (veya üstü) seviyesinde
+finding varsa `exit 1`:
+
+```bash
+# notice (REVIEW/CAUTION) findings → exit 1; sadece info → exit 0
+context-check analyze --fail-on notice
+```
+
+`--fail-on` değeri finding **severity** kullanır (info < notice < warning).
+Label→severity: INFO/CONTEXT → info, REVIEW/CAUTION → notice.
+
+## Diff (snapshot → current)
+
+`context-check diff`, context layer'ın zaman içindeki değişimini gösterir:
+artifact (eklenen/silinmiş/değişen dosyalar), toplam context token değişimi ve
+**analiz bulgularının değişimi** (yeni/çözülen/değişen finding):
+
+```text
+ContextCheck Diff
+
+Snapshot: previous → current
+
+Artifacts
+  ~ CLAUDE.md
+     59 → 70 tokens
+
+Context
+  Previous  ~235 tokens
+  Current   ~246 tokens
+  Change    +11 tokens
+
+Findings
+  + 1 new
+  = 1 unchanged
+
+Summary
+  0 added · 1 modified · 0 removed
+```
+
+Bu, "context layer değişti ve bunun sonucunda hangi bulgular ortaya
+çıktı/kayboldu?" sorusunu cevaplar — model performansıyla ilgili kausal iddia
+**değildir** (Spec §28).
+
+## Snapshot list ve seçimi (v2)
+
+`context-check snapshot list` kayıtlı snapshot'ları gösterir:
+
+```text
+ContextCheck Snapshots
+
+ID        Created                 Files  Tokens  Findings
+7ebv3k    2026-09-09 00:14:22    12      4,820    3
+43d791    2026-09-08 12:03:44    10      3,980    1
+```
+
+Belirli bir snapshot'a karşı diff:
+
+```bash
+context-check diff 7ebv3k
+```
+
+`diff --json` CI/automation için privacy-safe JSON üretir (artifact token
+delta'ları, finding değişimleri, snapshot metadata — **asla raw content yok**).
+
+## GitHub Actions (CI)
+
+```yaml
+name: ContextCheck
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  contextcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # scoped-no-match Git history için tam geçmiş
+      - run: npx context-check analyze --fail-on notice # CI gate
+      - run: npx context-check analyze --compact # PR log
+```
+
+`fetch-depth: 0` önemli: shallow checkout'u ContextCheck tespit eder ve
+`scoped-no-match`'i güvenli şekilde atlar (Rule 26).
+
+İki kullanım modu:
+
+```text
+Developer workflow   analyze → snapshot → diff
+CI workflow          analyze --fail-on notice
+```
+
+`--fail-on notice` REVIEW/CAUTION findings'de CI'ı kırar; yalnızca INFO
+(duplicate/large-file) findings build'i kırmaz. Bu repo'da workflow
+`.github/workflows/contextcheck.yml` mevcut ve paket yayınlanana kadar repo
+içinden dogfooding modunda çalışır (yayın sonrası `npx`'e döner).
+
+## Geliştirme
+
+```bash
+npm install
+npm run build     # tsc
+npm test          # vitest
+npm run lint      # eslint
+```
+
+## Lisans
+
+MIT — bkz. [LICENSE](LICENSE).
+
+## Yayınlama (maintainer)
+
+Beta kanalına yayın (kontrollü, mevcut `latest`'i korur):
+
+```bash
+npm login
+npm publish --tag beta
+```
+
+Beta'yı test et:
+
+```bash
+npm install -g context-check@beta
+npx context-check@beta analyze
+```
+
+Stabil sürüm hazır olduğunda `--tag latest` ile (veya `npm dist-tag add context-check@<version> latest`)
+mevcut sürümü `latest` kanalına taşı.

package/dist/analyzer/engine.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Analyzer engine (Spec §51).
+ *
+ * Runs each registered rule independently over the discovered artifacts and
+ * aggregates their findings into an `AnalysisReport`. Rules are isolation
+ * boundaries: a failure in one must not prevent the others from running
+ * (Spec §34), and presentation never affects analysis (Rule 15).
+ */
+import type { ConfigurationArtifact } from "../types/configuration.js";
+import type { Finding } from "../types/finding.js";
+import type { AnalysisReport } from "../types/report.js";
+import type { AnalysisContext, AnalyzerRule } from "./types.js";
+export interface AnalyzeInput {
+    artifacts: ConfigurationArtifact[];
+    context: AnalysisContext;
+    /** Rules to run; defaults to the full registered set when omitted. */
+    rules?: AnalyzerRule[];
+}
+/** Rules enabled for the current MVP build (grown across sprints). */
+export declare const DEFAULT_RULES: AnalyzerRule[];
+/**
+ * Runs all rules and returns an aggregated report. Rule failures are caught
+ * and logged instead of failing the whole analysis.
+ */
+export declare function analyze(input: AnalyzeInput): Promise<AnalysisReport>;
+/** Builds the summary + report from artifacts and findings. */
+export declare function aggregate(artifacts: ConfigurationArtifact[], findings: Finding[]): AnalysisReport;

package/dist/analyzer/engine.js

@@ -0,0 +1,64 @@
+/**
+ * Analyzer engine (Spec §51).
+ *
+ * Runs each registered rule independently over the discovered artifacts and
+ * aggregates their findings into an `AnalysisReport`. Rules are isolation
+ * boundaries: a failure in one must not prevent the others from running
+ * (Spec §34), and presentation never affects analysis (Rule 15).
+ */
+import { buildContextOverheadFinding, estimateOverhead, } from "./rules/context-overhead.js";
+import { duplicateRule } from "./rules/duplicate.js";
+import { highStakesRule } from "./rules/high-stakes.js";
+import { largeFileRule } from "./rules/large-file.js";
+import { repetitionRule } from "./rules/repetition.js";
+import { scopedNoMatchRule } from "./rules/scoped-no-match.js";
+/** Rules enabled for the current MVP build (grown across sprints). */
+export const DEFAULT_RULES = [
+    duplicateRule,
+    highStakesRule,
+    largeFileRule,
+    repetitionRule,
+    scopedNoMatchRule,
+];
+/**
+ * Runs all rules and returns an aggregated report. Rule failures are caught
+ * and logged instead of failing the whole analysis.
+ */
+export async function analyze(input) {
+    const { artifacts, context, rules } = input;
+    const ruleSet = rules ?? DEFAULT_RULES;
+    const findings = [];
+    for (const rule of ruleSet) {
+        try {
+            const result = await rule.run(artifacts, context);
+            findings.push(...(Array.isArray(result) ? result : []));
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error(`[contextcheck] Analyzer rule '${rule.name}' failed:`, err instanceof Error ? err.message : String(err));
+        }
+    }
+    return aggregate(artifacts, findings);
+}
+/** Builds the summary + report from artifacts and findings. */
+export function aggregate(artifacts, findings) {
+    const totalTokens = artifacts.reduce((sum, a) => sum + a.metadata.estimatedTokens, 0);
+    const skills = artifacts.filter((a) => a.type === "skill").length;
+    // Potential Context Overhead is derived from the other findings (Spec §22).
+    const contextOverhead = estimateOverhead(artifacts, findings);
+    const overheadFinding = buildContextOverheadFinding(contextOverhead, findings.flatMap((f) => f.filePaths));
+    const allFindings = overheadFinding
+        ? [...findings, overheadFinding]
+        : findings;
+    return {
+        summary: {
+            configurationFiles: artifacts.length,
+            skills,
+            estimatedTokens: totalTokens,
+            potentialContextOverhead: contextOverhead,
+        },
+        artifacts,
+        findings: allFindings,
+    };
+}
+//# sourceMappingURL=engine.js.map

package/dist/analyzer/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/analyzer/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EACL,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAS/D,sEAAsE;AACtE,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,aAAa;IACb,cAAc;IACd,aAAa;IACb,cAAc;IACd,iBAAiB;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAAmB;IAC/C,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC;IAEvC,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAClD,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,sCAAsC;YACtC,OAAO,CAAC,KAAK,CACX,iCAAiC,IAAI,CAAC,IAAI,WAAW,EACrD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CACjD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CACvB,SAAkC,EAClC,QAAmB;IAEnB,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAClC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,eAAe,EAC5C,CAAC,CACF,CAAC;IACF,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IAElE,4EAA4E;IAC5E,MAAM,eAAe,GAAG,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC9D,MAAM,eAAe,GAAG,2BAA2B,CACjD,eAAe,EACf,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CACrC,CAAC;IACF,MAAM,WAAW,GAAG,eAAe;QACjC,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,eAAe,CAAC;QAChC,CAAC,CAAC,QAAQ,CAAC;IAEb,OAAO;QACL,OAAO,EAAE;YACP,kBAAkB,EAAE,SAAS,CAAC,MAAM;YACpC,MAAM;YACN,eAAe,EAAE,WAAW;YAC5B,wBAAwB,EAAE,eAAe;SAC1C;QACD,SAAS;QACT,QAAQ,EAAE,WAAW;KACtB,CAAC;AACJ,CAAC"}

package/dist/analyzer/rules/context-overhead.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Context overhead aggregation (Spec §22).
+ *
+ * Potential Context Overhead is a deterministic estimate of tokens that may
+ * be redundant, computed from signals already detected by other rules
+ * (duplicate content, repeated sections/blocks). The MVP does NOT detect
+ * semantic redundancy, and we never use "wasted tokens" — only "Potential
+ * Context Overhead" (Spec §22).
+ */
+import type { ConfigurationArtifact } from "../../types/configuration.js";
+import type { Finding } from "../../types/finding.js";
+/**
+ * Estimates redundant tokens from the duplicate/repetition findings. Uses
+ * only deterministic signals; bounds each category to avoid double counting.
+ */
+export declare function estimateOverhead(artifacts: ConfigurationArtifact[], findings: Finding[]): number;
+/**
+ * Builds a `context-overhead` finding when overhead is meaningful.
+ * Returns `null` when overhead is negligible (avoids noisy output).
+ */
+export declare function buildContextOverheadFinding(overhead: number, sourcePaths: string[]): Finding | null;

package/dist/analyzer/rules/context-overhead.js

@@ -0,0 +1,53 @@
+/**
+ * Context overhead aggregation (Spec §22).
+ *
+ * Potential Context Overhead is a deterministic estimate of tokens that may
+ * be redundant, computed from signals already detected by other rules
+ * (duplicate content, repeated sections/blocks). The MVP does NOT detect
+ * semantic redundancy, and we never use "wasted tokens" — only "Potential
+ * Context Overhead" (Spec §22).
+ */
+import { makeFinding } from "./mapping.js";
+/**
+ * Estimates redundant tokens from the duplicate/repetition findings. Uses
+ * only deterministic signals; bounds each category to avoid double counting.
+ */
+export function estimateOverhead(artifacts, findings) {
+    let overhead = 0;
+    // Duplicate groups: each extra copy beyond the first is redundant.
+    for (const f of findings) {
+        if (f.type !== "duplicate" || f.filePaths.length <= 1)
+            continue;
+        const group = artifacts.filter((a) => f.filePaths.includes(a.path));
+        const avg = group.length
+            ? Math.round(group.reduce((sum, a) => sum + a.metadata.estimatedTokens, 0) /
+                group.length)
+            : 0;
+        overhead += avg * (f.filePaths.length - 1);
+    }
+    // Repetitions: a bounded per-extra-occurrence contribution.
+    for (const f of findings) {
+        if (f.type !== "repetition")
+            continue;
+        overhead += Math.min(800, 200 * Math.max(0, f.filePaths.length));
+    }
+    return Math.round(overhead);
+}
+/**
+ * Builds a `context-overhead` finding when overhead is meaningful.
+ * Returns `null` when overhead is negligible (avoids noisy output).
+ */
+export function buildContextOverheadFinding(overhead, sourcePaths) {
+    if (overhead <= 0)
+        return null;
+    return makeFinding({
+        type: "context-overhead",
+        filePaths: sourcePaths.length > 0 ? sourcePaths : ["."],
+        title: "Potential context overhead",
+        description: `Potential Context Overhead ~${overhead.toLocaleString("en-US")} tokens ` +
+            `based on duplicate content and repeated sections.`,
+        recommendation: `Review the flagged duplicates and repetitions; consolidating them may ` +
+            `reduce how much of the model context your configuration uses.`,
+    });
+}
+//# sourceMappingURL=context-overhead.js.map

package/dist/analyzer/rules/context-overhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-overhead.js","sourceRoot":"","sources":["../../../src/analyzer/rules/context-overhead.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAkC,EAClC,QAAmB;IAEnB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,mEAAmE;IACnE,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC;YAAE,SAAS;QAChE,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACpE,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM;YACtB,CAAC,CAAC,IAAI,CAAC,KAAK,CACR,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC,CAAC;gBAC3D,KAAK,CAAC,MAAM,CACf;YACH,CAAC,CAAC,CAAC,CAAC;QACN,QAAQ,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,4DAA4D;IAC5D,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY;YAAE,SAAS;QACtC,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAAgB,EAChB,WAAqB;IAErB,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/B,OAAO,WAAW,CAAC;QACjB,IAAI,EAAE,kBAAkB;QACxB,SAAS,EAAE,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACvD,KAAK,EAAE,4BAA4B;QACnC,WAAW,EACT,+BAA+B,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,UAAU;YACzE,mDAAmD;QACrD,cAAc,EACZ,wEAAwE;YACxE,+DAA+D;KAClE,CAAC,CAAC;AACL,CAAC"}

package/dist/analyzer/rules/duplicate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Exact duplicate detection (Spec §19, Rule 22).
+ *
+ * Compares document BODIES only, after stripping YAML frontmatter and
+ * normalizing. Two files with identical bodies but different frontmatter
+ * (description/globs/alwaysApply/metadata) are still duplicate candidates.
+ *
+ * Cross-file duplicates produce ONE finding listing every file path (Rule 16,
+ * Spec §12). This is a high-confidence, deterministic detection.
+ */
+import type { ConfigurationArtifact } from "../../types/configuration.js";
+import type { AnalyzerRule } from "../types.js";
+/** Normalized-body fingerprint (hash) for a single artifact. */
+export declare function bodyFingerprint(artifact: ConfigurationArtifact): string;
+export declare const duplicateRule: AnalyzerRule;

package/dist/analyzer/rules/duplicate.js

@@ -0,0 +1,53 @@
+/**
+ * Exact duplicate detection (Spec §19, Rule 22).
+ *
+ * Compares document BODIES only, after stripping YAML frontmatter and
+ * normalizing. Two files with identical bodies but different frontmatter
+ * (description/globs/alwaysApply/metadata) are still duplicate candidates.
+ *
+ * Cross-file duplicates produce ONE finding listing every file path (Rule 16,
+ * Spec §12). This is a high-confidence, deterministic detection.
+ */
+import { createHash } from "node:crypto";
+import { normalizeBody } from "../../parser/normalize.js";
+import { makeFinding } from "./mapping.js";
+/** Normalized-body fingerprint (hash) for a single artifact. */
+export function bodyFingerprint(artifact) {
+    const normalized = normalizeBody(artifact.content);
+    return createHash("sha256").update(normalized).digest("hex");
+}
+export const duplicateRule = {
+    name: "duplicate",
+    run(artifacts) {
+        // Group artifacts by normalized-body fingerprint (bodies only).
+        const groups = new Map();
+        for (const artifact of artifacts) {
+            const fp = bodyFingerprint(artifact);
+            const existing = groups.get(fp);
+            if (existing) {
+                existing.push(artifact.path);
+            }
+            else {
+                groups.set(fp, [artifact.path]);
+            }
+        }
+        const findings = [];
+        for (const [, paths] of groups) {
+            if (paths.length < 2)
+                continue;
+            const sorted = [...paths].sort();
+            const sample = sorted.slice(0, 2).join(" and ");
+            findings.push(makeFinding({
+                type: "duplicate",
+                filePaths: sorted,
+                title: "Identical instructions in multiple files",
+                description: `Found ${paths.length} files with an identical instruction body ` +
+                    `(frontmatter ignored): ${sample}.`,
+                recommendation: `Consider keeping a single source of truth and referencing it, ` +
+                    `or removing the redundant copies after review.`,
+            }));
+        }
+        return findings;
+    },
+};
+//# sourceMappingURL=duplicate.js.map

package/dist/analyzer/rules/duplicate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplicate.js","sourceRoot":"","sources":["../../../src/analyzer/rules/duplicate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,gEAAgE;AAChE,MAAM,UAAU,eAAe,CAAC,QAA+B;IAC7D,MAAM,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACnD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC,IAAI,EAAE,WAAW;IACjB,GAAG,CAAC,SAAS;QACX,gEAAgE;QAChE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;QAE3C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;YACrC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChC,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,EAAE,CAAC;QAEpB,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;YAC/B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAE/B,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAChD,QAAQ,CAAC,IAAI,CACX,WAAW,CAAC;gBACV,IAAI,EAAE,WAAW;gBACjB,SAAS,EAAE,MAAM;gBACjB,KAAK,EAAE,0CAA0C;gBACjD,WAAW,EACT,SAAS,KAAK,CAAC,MAAM,4CAA4C;oBACjE,0BAA0B,MAAM,GAAG;gBACrC,cAAc,EACZ,gEAAgE;oBAChE,gDAAgD;aACnD,CAAC,CACH,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC"}

package/dist/analyzer/rules/high-stakes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * High-stakes detection (Spec §26, §27, Rule 20) — REVISED after real-world
+ * pilot, two-tier model.
+ *
+ * Tier 1 (STRONG): a single strong term in CONTENT alone justifies CAUTION
+ *   e.g. secret, credential, password, authentication, authorization,
+ *   permission, payment, private key, api key, access token.
+ *
+ * Tier 2 (CONTEXTUAL): weaker terms (deploy, production, security, database,
+ *   billing, infrastructure, migration) NEVER trigger a finding on their own.
+ *   They may only reinforce a strong signal, never substitute for it. This
+ *   removes the pilot's false positives ("docs deployed", "security gateways",
+ *   "deployment scripts").
+ *
+ * Path/scope names are never the sole trigger: `.env.example`, `config/auth.ts`,
+ * `deployment.md` must not produce CAUTION by naming alone.
+ *
+ * Practically: a finding is produced iff a STRONG term is present in a rule's
+ * content. CONTEXTUAL entries are retained as reinforcement only.
+ */
+import type { ConfigurationArtifact } from "../../types/configuration.js";
+import type { AnalyzerRule } from "../types.js";
+/** Strong terms that alone justify a CAUTION finding (word-boundary match). */
+export declare const STRONG_TERMS: readonly string[];
+/** Contextual terms that NEVER trigger alone (Spec §26 weak categories). */
+export declare const CONTEXTUAL_TERMS: readonly string[];
+/** Returns the first STRONG term present in `text`, or undefined. */
+export declare function matchStrongTerm(text: string): string | undefined;
+/** Returns the first CONTEXTUAL term present in `text`, or undefined. */
+export declare function matchContextualTerm(text: string): string | undefined;
+export declare const highStakesRule: AnalyzerRule;
+/**
+ * Returns the matched STRONG term, or undefined. Detection is content-driven
+ * (Rule 20 still reads the artifact, but path/scope names never trigger alone).
+ */
+export declare function detectHighStakes(artifact: ConfigurationArtifact): string | undefined;

package/dist/analyzer/rules/high-stakes.js

@@ -0,0 +1,96 @@
+/**
+ * High-stakes detection (Spec §26, §27, Rule 20) — REVISED after real-world
+ * pilot, two-tier model.
+ *
+ * Tier 1 (STRONG): a single strong term in CONTENT alone justifies CAUTION
+ *   e.g. secret, credential, password, authentication, authorization,
+ *   permission, payment, private key, api key, access token.
+ *
+ * Tier 2 (CONTEXTUAL): weaker terms (deploy, production, security, database,
+ *   billing, infrastructure, migration) NEVER trigger a finding on their own.
+ *   They may only reinforce a strong signal, never substitute for it. This
+ *   removes the pilot's false positives ("docs deployed", "security gateways",
+ *   "deployment scripts").
+ *
+ * Path/scope names are never the sole trigger: `.env.example`, `config/auth.ts`,
+ * `deployment.md` must not produce CAUTION by naming alone.
+ *
+ * Practically: a finding is produced iff a STRONG term is present in a rule's
+ * content. CONTEXTUAL entries are retained as reinforcement only.
+ */
+import { makeFinding } from "./mapping.js";
+/** Strong terms that alone justify a CAUTION finding (word-boundary match). */
+export const STRONG_TERMS = [
+    "secret",
+    "credential",
+    "password",
+    "authentication",
+    "authorization",
+    "permission",
+    "payment",
+    "api key",
+    "private key",
+    "access token",
+];
+/** Contextual terms that NEVER trigger alone (Spec §26 weak categories). */
+export const CONTEXTUAL_TERMS = [
+    "deploy",
+    "deployment",
+    "production",
+    "security",
+    "database",
+    "billing",
+    "infrastructure",
+    "migration",
+];
+/**
+ * Escapes a literal and anchors it to whole-word boundaries. Single-word terms
+ * accept an optional trailing `s` so (credential/credentials) both match.
+ */
+function termPattern(term) {
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const plural = term.includes(" ") ? escaped : `${escaped}(?:s|es)?`;
+    return new RegExp(`\\b${plural}\\b`, "i");
+}
+/** Returns the first STRONG term present in `text`, or undefined. */
+export function matchStrongTerm(text) {
+    return STRONG_TERMS.find((term) => termPattern(term).test(text));
+}
+/** Returns the first CONTEXTUAL term present in `text`, or undefined. */
+export function matchContextualTerm(text) {
+    return CONTEXTUAL_TERMS.find((term) => termPattern(term).test(text));
+}
+export const highStakesRule = {
+    name: "high-stakes",
+    run(artifacts) {
+        const findings = [];
+        for (const artifact of artifacts) {
+            const strong = matchStrongTerm(artifact.content);
+            if (!strong)
+                continue;
+            // A contextual term can only reinforce a strong signal; it is never sufficient.
+            const context = matchContextualTerm(artifact.content);
+            const why = context ? `(reinforced by "${context}")` : "";
+            findings.push(makeFinding({
+                type: "high-stakes",
+                filePaths: [artifact.path],
+                title: "Potentially high-stakes configuration",
+                description: `${artifact.path} contains a strong high-stakes signal related to ` +
+                    `"${strong}" ${why}. Potentially high-stakes configuration detected: ` +
+                    `this instruction may be low frequency but important. Review manually ` +
+                    `before modifying or removing it.`,
+                recommendation: `Before changing or removing this rule, confirm its scope and ` +
+                    `purpose with context of the related system.`,
+            }));
+        }
+        return findings;
+    },
+};
+/**
+ * Returns the matched STRONG term, or undefined. Detection is content-driven
+ * (Rule 20 still reads the artifact, but path/scope names never trigger alone).
+ */
+export function detectHighStakes(artifact) {
+    return matchStrongTerm(artifact.content);
+}
+//# sourceMappingURL=high-stakes.js.map

package/dist/analyzer/rules/high-stakes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"high-stakes.js","sourceRoot":"","sources":["../../../src/analyzer/rules/high-stakes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,+EAA+E;AAC/E,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC7C,QAAQ;IACR,YAAY;IACZ,UAAU;IACV,gBAAgB;IAChB,eAAe;IACf,YAAY;IACZ,SAAS;IACT,SAAS;IACT,aAAa;IACb,cAAc;CACf,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAsB;IACjD,QAAQ;IACR,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,UAAU;IACV,SAAS;IACT,gBAAgB;IAChB,WAAW;CACZ,CAAC;AAEF;;;GAGG;AACH,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,WAAW,CAAC;IACpE,OAAO,IAAI,MAAM,CAAC,MAAM,MAAM,KAAK,EAAE,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C,IAAI,EAAE,aAAa;IACnB,GAAG,CAAC,SAAS;QACX,MAAM,QAAQ,GAAG,EAAE,CAAC;QAEpB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACjD,IAAI,CAAC,MAAM;gBAAE,SAAS;YAEtB,gFAAgF;YAChF,MAAM,OAAO,GAAG,mBAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACtD,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,mBAAmB,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAE1D,QAAQ,CAAC,IAAI,CACX,WAAW,CAAC;gBACV,IAAI,EAAE,aAAa;gBACnB,SAAS,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAC1B,KAAK,EAAE,uCAAuC;gBAC9C,WAAW,EACT,GAAG,QAAQ,CAAC,IAAI,mDAAmD;oBACnE,IAAI,MAAM,KAAK,GAAG,oDAAoD;oBACtE,uEAAuE;oBACvE,kCAAkC;gBACpC,cAAc,EACZ,+DAA+D;oBAC/D,6CAA6C;aAChD,CAAC,CACH,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA+B;IAE/B,OAAO,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC"}

package/dist/analyzer/rules/large-file.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Large instruction detection (Spec §20).
+ *
+ * A file being large is not inherently bad, but a file above the token
+ * threshold may contribute significantly to model context. In the MVP both
+ * the notice and warning thresholds map to `label=CONTEXT`, `severity=info`
+ * through the normative mapping; we only ever emit `large-file` findings.
+ *
+ * Note: the `warningFileTokens` threshold is reserved (Spec §11) and produces
+ * no additional severity in the MVP — the taxonomy keeps `info` here.
+ */
+import { type AnalyzerRule } from "../types.js";
+export declare const largeFileRule: AnalyzerRule;
+/** Formats a token count with thousands separators, e.g. 4800 -> "4,800". */
+export declare function formatTokens(tokens: number): string;