@kogu/context-check 0.1.0

package/dist/discovery/exclusions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Discovery boundaries (Spec §15).
+ *
+ * These directories are never scanned by default. The goal is to avoid
+ * finding third-party dependency configuration, generated output and to keep
+ * filesystem traversal fast.
+ */
+/** Directories skipped during recursive discovery. */
+export declare const EXCLUDED_DIRECTORIES: readonly string[];
+/**
+ * Returns whether the given path segment is an excluded directory name.
+ * Comparisons are case-insensitive and match at any directory level.
+ */
+export declare function isExcludedDirectory(segment: string): boolean;
+/**
+ * Returns whether an absolute/relative path (posix-normalized) traverses any
+ * excluded directory segment. Used as a second guard for exact matches.
+ */
+export declare function traversesExcludedDirectory(filePath: string): boolean;

package/dist/discovery/exclusions.js

@@ -0,0 +1,40 @@
+/**
+ * Discovery boundaries (Spec §15).
+ *
+ * These directories are never scanned by default. The goal is to avoid
+ * finding third-party dependency configuration, generated output and to keep
+ * filesystem traversal fast.
+ */
+import { posix } from "node:path";
+/** Directories skipped during recursive discovery. */
+export const EXCLUDED_DIRECTORIES = [
+    ".git",
+    ".contextcheck",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    ".next",
+    "out",
+    "coverage",
+    ".cache",
+    "tmp",
+    "temp",
+];
+/**
+ * Returns whether the given path segment is an excluded directory name.
+ * Comparisons are case-insensitive and match at any directory level.
+ */
+export function isExcludedDirectory(segment) {
+    const lower = segment.toLowerCase();
+    return EXCLUDED_DIRECTORIES.includes(lower);
+}
+/**
+ * Returns whether an absolute/relative path (posix-normalized) traverses any
+ * excluded directory segment. Used as a second guard for exact matches.
+ */
+export function traversesExcludedDirectory(filePath) {
+    const parts = posix.normalize(filePath).split("/");
+    return parts.some((part) => isExcludedDirectory(part));
+}
+//# sourceMappingURL=exclusions.js.map

package/dist/discovery/exclusions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusions.js","sourceRoot":"","sources":["../../src/discovery/exclusions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAsB;IACrD,MAAM;IACN,eAAe;IACf,cAAc;IACd,QAAQ;IACR,MAAM;IACN,OAAO;IACP,OAAO;IACP,KAAK;IACL,UAAU;IACV,QAAQ;IACR,KAAK;IACL,MAAM;CACP,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,oBAAoB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAgB;IACzD,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;AACzD,CAAC"}

package/dist/discovery/scanner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Recursive discovery scanner (Spec §14, §15).
+ *
+ * Walks the repository root, skipping excluded directories at every level,
+ * and yields the file paths that should be handed to adapters for parse.
+ * This module only discovers — it never decides what a file *is*; that is the
+ * adapter's job (Rule 14).
+ */
+export interface DiscoveredFile {
+    /** Absolute path on disk. */
+    absolutePath: string;
+    /** Path relative to the scanned root (posix-normalized). */
+    relativePath: string;
+}
+/**
+ * Recursively walks `rootPath` and returns every file path, skipping the
+ * excluded directories defined in Spec §15.
+ */
+export declare function walkFiles(rootPath: string): Promise<DiscoveredFile[]>;
+/** Reads a file's content as UTF-8. */
+export declare function readTextFile(absolutePath: string): Promise<string>;
+/**
+ * Counts lines in `content`. A trailing line terminator is treated as a line
+ * boundary rather than an extra empty line, so `"a\nb\n"` is 2 lines.
+ */
+export declare function countLines(content: string): number;
+/** Returns basic file metadata (size + line count). */
+export declare function describeFile(absolutePath: string): Promise<{
+    sizeBytes: number;
+    lineCount: number;
+}>;

package/dist/discovery/scanner.js

@@ -0,0 +1,75 @@
+/**
+ * Recursive discovery scanner (Spec §14, §15).
+ *
+ * Walks the repository root, skipping excluded directories at every level,
+ * and yields the file paths that should be handed to adapters for parse.
+ * This module only discovers — it never decides what a file *is*; that is the
+ * adapter's job (Rule 14).
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { isExcludedDirectory } from "./exclusions.js";
+/**
+ * Recursively walks `rootPath` and returns every file path, skipping the
+ * excluded directories defined in Spec §15.
+ */
+export async function walkFiles(rootPath) {
+    const results = [];
+    async function walk(dir) {
+        // readdir withFileTypes avoids a stat call per entry and lets us skip
+        // directories cheaply. ENOENT is tolerated to avoid races on deletion.
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (isExcludedDirectory(entry.name))
+                    continue;
+                await walk(fullPath);
+                continue;
+            }
+            if (entry.isFile()) {
+                results.push({
+                    absolutePath: fullPath,
+                    relativePath: normalizeRelative(rootPath, fullPath),
+                });
+            }
+        }
+    }
+    await walk(rootPath);
+    return results;
+}
+/** Normalizes a path to be relative to root with forward slashes. */
+function normalizeRelative(rootPath, filePath) {
+    const rel = relative(rootPath, filePath);
+    return rel.split(sep).join("/");
+}
+/** Reads a file's content as UTF-8. */
+export async function readTextFile(absolutePath) {
+    return readFile(absolutePath, "utf8");
+}
+/**
+ * Counts lines in `content`. A trailing line terminator is treated as a line
+ * boundary rather than an extra empty line, so `"a\nb\n"` is 2 lines.
+ */
+export function countLines(content) {
+    if (content.length === 0)
+        return 0;
+    const endsWithBreak = /\r\n|\r|\n$/.test(content);
+    const raw = content.split(/\r\n|\r|\n/).length;
+    return endsWithBreak ? raw - 1 : raw;
+}
+/** Returns basic file metadata (size + line count). */
+export async function describeFile(absolutePath) {
+    const s = await stat(absolutePath);
+    const content = await readTextFile(absolutePath);
+    return { sizeBytes: s.size, lineCount: countLines(content) };
+}
+//# sourceMappingURL=scanner.js.map

package/dist/discovery/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../../src/discovery/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAStD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAgB;IAC9C,MAAM,OAAO,GAAqB,EAAE,CAAC;IAErC,KAAK,UAAU,IAAI,CAAC,GAAW;QAC7B,sEAAsE;QACtE,uEAAuE;QACvE,IAAI,OAAmC,CAAC;QACxC,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO;YAC7D,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAEvC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,SAAS;gBAC9C,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACrB,SAAS;YACX,CAAC;YAED,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACnB,OAAO,CAAC,IAAI,CAAC;oBACX,YAAY,EAAE,QAAQ;oBACtB,YAAY,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC;iBACpD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,qEAAqE;AACrE,SAAS,iBAAiB,CAAC,QAAgB,EAAE,QAAgB;IAC3D,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACzC,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClC,CAAC;AAED,uCAAuC;AACvC,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,YAAoB;IACrD,OAAO,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACnC,MAAM,aAAa,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC;IAC/C,OAAO,aAAa,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACvC,CAAC;AAED,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,YAAoB;IAIrD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,YAAY,CAAC,CAAC;IACjD,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;AAC/D,CAAC"}

package/dist/git/history.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Changed files over a Git window (Spec §23, §24, §31).
+ *
+ * Used to check whether a scoped rule's glob patterns ever matched a file
+ * change. Only metadata is read — never configuration content — keeping the
+ * "AI configuration-specific view over Git" role (Spec §31).
+ */
+import { type GitRunner } from "./sufficiency.js";
+/**
+ * Returns the set of unique file paths changed within `winDays`, relative to
+ * the repo root (posix-normalized). Throws if git fails; callers gate this on
+ * history sufficiency first.
+ */
+export declare function changedFilesInWindow(rootPath: string, windowDays: number, run?: GitRunner): Promise<string[]>;
+/**
+ * Returns whether any changed file path matches a glob pattern relative to the
+ * repo root. Used by scoped-rule matching (Spec §23).
+ */
+export declare function matchesChangedFile(pattern: string, changedPaths: string[]): boolean;
+/**
+ * Minimal glob matcher for the MVP: supports `**` (multi-segment), `*`
+ * (within a segment) and exact/prefix matches. Not a full minimatch — enough
+ * for deterministic scoped-rule matching.
+ */
+export declare function globMatch(pattern: string, path: string): boolean;

package/dist/git/history.js

@@ -0,0 +1,71 @@
+/**
+ * Changed files over a Git window (Spec §23, §24, §31).
+ *
+ * Used to check whether a scoped rule's glob patterns ever matched a file
+ * change. Only metadata is read — never configuration content — keeping the
+ * "AI configuration-specific view over Git" role (Spec §31).
+ */
+import { runGit } from "./sufficiency.js";
+/**
+ * Returns the set of unique file paths changed within `winDays`, relative to
+ * the repo root (posix-normalized). Throws if git fails; callers gate this on
+ * history sufficiency first.
+ */
+export async function changedFilesInWindow(rootPath, windowDays, run = runGit) {
+    const since = new Date(Date.now() - windowDays * 24 * 60 * 60 * 1000).toISOString();
+    const output = await run(rootPath, [
+        "log",
+        `--since=${since}`,
+        "--name-only",
+        "--pretty=format:",
+        "HEAD",
+    ]);
+    const names = output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return [...new Set(names)];
+}
+/**
+ * Returns whether any changed file path matches a glob pattern relative to the
+ * repo root. Used by scoped-rule matching (Spec §23).
+ */
+export function matchesChangedFile(pattern, changedPaths) {
+    return changedPaths.some((p) => globMatch(pattern, p));
+}
+/**
+ * Minimal glob matcher for the MVP: supports `**` (multi-segment), `*`
+ * (within a segment) and exact/prefix matches. Not a full minimatch — enough
+ * for deterministic scoped-rule matching.
+ */
+export function globMatch(pattern, path) {
+    const p = pattern.replace(/^\.\//, "").toLowerCase();
+    const t = path.toLowerCase();
+    if (p === t)
+        return true;
+    // Fast path: directory prefix pattern.
+    if (!containsGlob(p)) {
+        return t.startsWith(p.endsWith("/") ? p : `${p}/`);
+    }
+    const regex = globToRegExp(p);
+    return regex.test(t);
+}
+function containsGlob(s) {
+    return s.includes("*") || s.includes("?") || s.includes("[");
+}
+/** Placeholder protecting a segment before the `*`/`.` replacements run. */
+const SEGMENT = "\u0000";
+function globToRegExp(glob) {
+    // Protect `**/` first so it cannot be rewritten by later `*`/`.` passes.
+    let out = glob.replace(/\*\*\//g, SEGMENT);
+    // Escape regex literals, leaving `*` and `?` (and SEGMENT) intact.
+    out = out.replace(/[.+^${}()|[\]]/g, "\\$&");
+    // Multi-segment `**` and single-segment `*`.
+    out = out.replace(/\*\*/g, ".*");
+    out = out.replace(/\*/g, "[^/]*");
+    out = out.replace(/\?/g, "[^/]");
+    // Restore `**/` as an optional zero-or-more path prefix.
+    out = out.replace(new RegExp(SEGMENT, "g"), "(?:.*/)?");
+    return new RegExp(`^${out}$`);
+}
+//# sourceMappingURL=history.js.map

package/dist/git/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/git/history.ts"],"names":[],"mappings":"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"}

package/dist/git/sufficiency.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Git history sufficiency (Spec §24, Rule 18, Rule 26).
+ *
+ * Scoped-rule activity analysis MUST be skipped when Git history is
+ * insufficient. If we only have a short sample, a "no match" is not evidence
+ * that a rule is unused — so we never emit `scoped-no-match`.
+ *
+ * Insufficient when ANY of:
+ *   1. No Git repository present.
+ *   2. Repository is a shallow clone (`.git/shallow` exists).
+ *   3. There are no commits within the analysis window.
+ *   4. Total history is shorter than the window.
+ *   5. History cannot be analyzed (e.g. git unavailable).
+ */
+export interface GitSufficiencyResult {
+    isGitRepo: boolean;
+    isShallow: boolean;
+    /** Commits within the window. */
+    windowCommitCount: number;
+    /** Total commits across all history. */
+    totalCommitCount: number;
+    sufficient: boolean;
+}
+/** Checks for a shallow clone using the presence of `.git/shallow` (Rule 26). */
+export declare function isShallowRepository(rootPath: string): boolean;
+/**
+ * Runs a git command, returning stdout. Throws if git fails; callers decide
+ * how to degrade.
+ */
+export declare function runGit(rootPath: string, args: string[]): Promise<string>;
+/** Optional injected runner to keep tests hermetic. */
+export type GitRunner = (rootPath: string, args: string[]) => Promise<string>;
+/**
+ * Determines whether there is enough git history to reason about scoped-rule
+ * activity within `windowDays`. Never throws; degrades to `sufficient:false`
+ * on any error (Spec §24 case 4).
+ */
+export declare function assessGitHistory(rootPath: string, windowDays: number, run?: GitRunner): Promise<GitSufficiencyResult>;

package/dist/git/sufficiency.js

@@ -0,0 +1,98 @@
+/**
+ * Git history sufficiency (Spec §24, Rule 18, Rule 26).
+ *
+ * Scoped-rule activity analysis MUST be skipped when Git history is
+ * insufficient. If we only have a short sample, a "no match" is not evidence
+ * that a rule is unused — so we never emit `scoped-no-match`.
+ *
+ * Insufficient when ANY of:
+ *   1. No Git repository present.
+ *   2. Repository is a shallow clone (`.git/shallow` exists).
+ *   3. There are no commits within the analysis window.
+ *   4. Total history is shorter than the window.
+ *   5. History cannot be analyzed (e.g. git unavailable).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/** Checks for a shallow clone using the presence of `.git/shallow` (Rule 26). */
+export function isShallowRepository(rootPath) {
+    return existsSync(join(rootPath, ".git", "shallow"));
+}
+/**
+ * Runs a git command, returning stdout. Throws if git fails; callers decide
+ * how to degrade.
+ */
+export async function runGit(rootPath, args) {
+    const { stdout } = await execAsync(`git ${args.join(" ")}`, {
+        cwd: rootPath,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return stdout.trim();
+}
+/**
+ * Determines whether there is enough git history to reason about scoped-rule
+ * activity within `windowDays`. Never throws; degrades to `sufficient:false`
+ * on any error (Spec §24 case 4).
+ */
+export async function assessGitHistory(rootPath, windowDays, run = runGit) {
+    const since = new Date(Date.now() - windowDays * 24 * 60 * 60 * 1000).toISOString();
+    const fallback = (partial) => ({
+        isGitRepo: false,
+        isShallow: false,
+        windowCommitCount: 0,
+        totalCommitCount: 0,
+        sufficient: false,
+        ...partial,
+    });
+    // 1. Repository present?
+    let isRepo = false;
+    try {
+        const head = await run(rootPath, ["rev-parse", "--is-inside-work-tree"]);
+        isRepo = head === "true";
+    }
+    catch {
+        return fallback({ isGitRepo: false });
+    }
+    if (!isRepo) {
+        return fallback({ isGitRepo: false });
+    }
+    // 2. Shallow clone?
+    const isShallow = isShallowRepository(rootPath);
+    if (isShallow) {
+        return fallback({ isGitRepo: true, isShallow: true });
+    }
+    // 3 & 4. Commit counts.
+    try {
+        const total = parseInt((await run(rootPath, ["rev-list", "--count", "HEAD"])) || "0", 10) || 0;
+        const window = parseInt((await run(rootPath, [
+            "rev-list",
+            "--count",
+            `--since=${since}`,
+            "HEAD",
+        ])) || "0", 10) || 0;
+        // If there is any history but none within the window, or the window count
+        // equals total count (history shorter than the window), treat as
+        // insufficient — absence of recent activity is not evidence.
+        if (total === 0 || window === 0 || window >= total) {
+            return fallback({
+                isGitRepo: true,
+                totalCommitCount: total,
+                windowCommitCount: window,
+            });
+        }
+        return {
+            isGitRepo: true,
+            isShallow: false,
+            windowCommitCount: window,
+            totalCommitCount: total,
+            sufficient: true,
+        };
+    }
+    catch {
+        return fallback({ isGitRepo: true });
+    }
+}
+//# sourceMappingURL=sufficiency.js.map

package/dist/git/sufficiency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sufficiency.js","sourceRoot":"","sources":["../../src/git/sufficiency.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * contextcheck entry point (temporary scaffold).
+ *
+ * Phase 1 - Sprint 1: ensures the TypeScript build pipeline works.
+ * The real CLI wiring (commander) lands in Sprint 2.
+ */
+export declare const version = "0.1.0";
+export declare function main(): void;

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * contextcheck entry point (temporary scaffold).
+ *
+ * Phase 1 - Sprint 1: ensures the TypeScript build pipeline works.
+ * The real CLI wiring (commander) lands in Sprint 2.
+ */
+export const version = "0.1.0";
+export function main() {
+    // Placeholder; replaced by the CLI dispatcher in Sprint 2.
+    // eslint-disable-next-line no-console
+    console.log("contextcheck scaffold ok");
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,MAAM,UAAU,IAAI;IAClB,2DAA2D;IAC3D,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAC1C,CAAC"}

package/dist/output/json.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Privacy-safe JSON output (Spec §32, §33; Rule 23, Rule 25).
+ *
+ * The public JSON model is a separate DTO from the internal
+ * `ConfigurationArtifact`. The serializer NEVER emits raw `content`. This
+ * guarantee is enforced structurally — the DTO has no `content` field to
+ * serialize, so a future CI command cannot accidentally leak configuration
+ * into logs (Spec §53).
+ */
+import type { ConfigurationArtifact, ConfigurationScope } from "../types/configuration.js";
+import type { Finding } from "../types/finding.js";
+import type { AnalysisReport } from "../types/report.js";
+import type { FileDiff, FindingChange, FindingChangesSummary, SnapshotDiff } from "../snapshot/diff.js";
+import type { Snapshot } from "../snapshot/manager.js";
+/** Privacy-safe artifact DTO (Spec §33). */
+export interface ArtifactJson {
+    id: string;
+    type: ConfigurationArtifact["type"];
+    path: string;
+    scope?: ConfigurationScope;
+    metadata: ConfigurationArtifact["metadata"];
+}
+export interface AnalysisSummaryJson {
+    configurationFiles: number;
+    skills: number;
+    estimatedTokens: number;
+    potentialContextOverhead: number;
+}
+export interface ReportJson {
+    summary: AnalysisSummaryJson;
+    artifacts: ArtifactJson[];
+    findings: Finding[];
+}
+/** Converts an internal artifact into its privacy-safe DTO. */
+export declare function toArtifactJson(artifact: ConfigurationArtifact): ArtifactJson;
+/** Converts a full report into a privacy-safe JSON shape. */
+export declare function toReportJson(report: AnalysisReport): ReportJson;
+/** Serializes a report as formatted, privacy-safe JSON. */
+export declare function serializeReport(report: AnalysisReport): string;
+/** Privacy-safe snapshot diff DTO for CI consumption. */
+export interface DiffJson {
+    before: {
+        id: string | null;
+        createdAt: string | null;
+        tokens: number;
+        files: number;
+    };
+    after: {
+        tokens: number;
+        files: number;
+    };
+    deltaTokens: number;
+    files: FileDiff[];
+    findingChanges: FindingChangesSummary;
+    findings: FindingChange[];
+}
+/** Serializes a snapshot diff as privacy-safe JSON (no raw content). */
+export declare function serializeDiff(diff: SnapshotDiff, before?: Snapshot | null): string;

package/dist/output/json.js

@@ -0,0 +1,52 @@
+/**
+ * Privacy-safe JSON output (Spec §32, §33; Rule 23, Rule 25).
+ *
+ * The public JSON model is a separate DTO from the internal
+ * `ConfigurationArtifact`. The serializer NEVER emits raw `content`. This
+ * guarantee is enforced structurally — the DTO has no `content` field to
+ * serialize, so a future CI command cannot accidentally leak configuration
+ * into logs (Spec §53).
+ */
+/** Converts an internal artifact into its privacy-safe DTO. */
+export function toArtifactJson(artifact) {
+    return {
+        id: artifact.id,
+        type: artifact.type,
+        path: artifact.path,
+        scope: artifact.scope,
+        metadata: artifact.metadata,
+    };
+}
+/** Converts a full report into a privacy-safe JSON shape. */
+export function toReportJson(report) {
+    return {
+        summary: report.summary,
+        artifacts: report.artifacts.map(toArtifactJson),
+        findings: report.findings,
+    };
+}
+/** Serializes a report as formatted, privacy-safe JSON. */
+export function serializeReport(report) {
+    return JSON.stringify(toReportJson(report), null, 2);
+}
+/** Serializes a snapshot diff as privacy-safe JSON (no raw content). */
+export function serializeDiff(diff, before) {
+    const dto = {
+        before: {
+            id: before?.id ?? null,
+            createdAt: before?.createdAt ?? null,
+            tokens: diff.beforeTokens,
+            files: before?.artifacts.length ?? 0,
+        },
+        after: {
+            tokens: diff.afterTokens,
+            files: diff.files.filter((f) => f.status !== "removed").length,
+        },
+        deltaTokens: diff.delta,
+        files: diff.files,
+        findingChanges: diff.findingChanges,
+        findings: diff.findings,
+    };
+    return JSON.stringify(dto, null, 2);
+}
+//# sourceMappingURL=json.js.map

package/dist/output/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/output/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsCH,+DAA+D;AAC/D,MAAM,UAAU,cAAc,CAAC,QAA+B;IAC5D,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;KAC5B,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,YAAY,CAAC,MAAsB;IACjD,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC;QAC/C,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,MAAsB;IACpD,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC;AAoBD,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAC3B,IAAkB,EAClB,MAAwB;IAExB,MAAM,GAAG,GAAa;QACpB,MAAM,EAAE;YACN,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,IAAI;YACtB,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,IAAI;YACpC,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,CAAC;SACrC;QACD,KAAK,EAAE;YACL,MAAM,EAAE,IAAI,CAAC,WAAW;YACxB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM;SAC/D;QACD,WAAW,EAAE,IAAI,CAAC,KAAK;QACvB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC;IACF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/dist/output/terminal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Terminal renderer (Spec §9, §28).
+ *
+ * Human-readable, non-fake-precision output (Spec §4.5). Findings are grouped
+ * and summarized; `verbose` expands each finding with explanation. Command
+ * output must never say "wasted tokens", "unused" or imply causal impact.
+ */
+import type { AnalysisReport } from "../types/report.js";
+import type { SnapshotDiff } from "../snapshot/diff.js";
+/** Formats a full report for the terminal. */
+export declare function renderReport(report: AnalysisReport, verbose?: boolean): string;
+/** Formats a token count with thousands separators, e.g. 14820 -> "14,820". */
+export declare function formatTokens(tokens: number): string;
+/**
+ * Compact human renderer — answers "how many, how big, what needs attention"
+ * at a glance. Pure presentation: it renders the same `AnalysisReport` the
+ * terminal renderer uses, adding no analysis behavior.
+ */
+export declare function renderCompactReport(report: AnalysisReport): string;
+/** Renders a snapshot diff in the Snapshot/Diff v1 format. */
+export declare function renderDiff(diff: SnapshotDiff, beforeLabel?: string, afterLabel?: string): string;