@lyse-labs/lyse 0.1.0-alpha.2

package/dist/types.d.ts

@@ -0,0 +1,300 @@
+export type Severity = "error" | "warning" | "info";
+export type AxisName = "tokens" | "a11y" | "components" | "stories" | "ai-surface";
+export type BuiltInRuleId = "tokens/no-hardcoded-color" | "tokens/no-hardcoded-spacing" | "tokens/no-hardcoded-typography" | "tokens/no-hardcoded-radii" | "tokens/no-hardcoded-shadow" | "tokens/no-hardcoded-motion-duration" | "tokens/no-hardcoded-motion-easing" | "tokens/no-hardcoded-breakpoints" | "tokens/no-hardcoded-z-index" | "tokens/no-hardcoded-opacity" | "tokens/no-hardcoded-border-width" | "tokens/dtcg-conformance" | "tokens/description-coverage" | "components/no-native-shadows" | "naming/component-pascalcase" | "naming/hook-prefix" | "naming/prop-camelcase" | "a11y/essentials" | "stories/coverage" | "stories/variant-coverage" | "ai-surface/agents-md-quality" | "ai-surface/component-manifest-json" | "ai-surface/ds-index-exported";
+export type RuleId = BuiltInRuleId | string;
+export interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+export interface Finding {
+    ruleId: RuleId;
+    axis: AxisName;
+    severity: Severity;
+    location: SourceLocation;
+    message: string;
+    suggestion?: string;
+    context?: string;
+    confidence?: Confidence;
+}
+export interface RuleContext {
+    repoRoot: string;
+    tokens: TokenMap | null;
+    componentsModule: string | null;
+    componentInventory: ComponentInventoryEntry[];
+    storyIndex: StoryIndex | null;
+    excludePaths: string[];
+    /**
+     * True when the repo being audited IS the design system (workspace
+     * detection found a DS-export package in the same monorepo). Some rules
+     * (no-native-shadows, stories/coverage) skip in this mode because their
+     * semantics target consumer-of-DS audits, not DS-self audits. Full
+     * DS-self rule semantics planned for v0.2.
+     */
+    dsSelfMode?: boolean;
+}
+export interface TokenMap {
+    colors: Map<string, string[]>;
+    spacing: Map<string, string[]>;
+    typography: Map<string, string[]>;
+    radii: Map<string, string[]>;
+    shadows: Map<string, string[]>;
+    motion: Map<string, string[]>;
+    breakpoints: Map<string, string[]>;
+    zIndex: Map<string, string[]>;
+    opacity: Map<string, string[]>;
+    borderWidth: Map<string, string[]>;
+    source: "tailwind-v3" | "tailwind-v4" | "dtcg" | "css-vars" | "mixed";
+}
+/** A single prop extracted from a component's TypeScript type annotation. */
+export interface ComponentPropEntry {
+    /** Prop identifier, e.g. "variant" */
+    name: string;
+    /**
+     * Raw TypeScript type text, e.g. '"primary" | "secondary" | "ghost"'.
+     * For props imported from another file, this will be the reference name
+     * (e.g. "ButtonProps") without cross-file resolution (v0.2 enhancement).
+     */
+    typeText?: string;
+    /** True when the prop is optional (`?:`). */
+    isOptional?: boolean;
+    /** Default value extracted from destructuring, e.g. "primary" for `{ variant = "primary" }`. */
+    defaultValue?: string;
+    /**
+     * True when `typeText` is a string-literal union (all members are string literals),
+     * e.g. `'"primary" | "secondary"`.
+     */
+    isVariantUnion?: boolean;
+    /** Extracted string-literal values when `isVariantUnion` is true. */
+    variants?: string[];
+}
+export interface ComponentInventoryEntry {
+    name: string;
+    module: string;
+    usageCount: number;
+    /**
+     * Props extracted from the component's TypeScript prop type definition.
+     * Populated by buildComponentInventory when the loader can parse the source files.
+     * Absent when the component source is not available for analysis.
+     */
+    props?: ComponentPropEntry[];
+}
+/**
+ * A single named export from a CSF v3 story file.
+ * Extracted from `export const Primary = { args: { variant: "primary" } }`.
+ */
+export interface StoryExport {
+    /** Export name, e.g. "Primary" */
+    name: string;
+    /**
+     * Simple literal args extracted from the story's `args` object.
+     * Only string/number/boolean literals are extracted; complex expressions are skipped.
+     * Example: { variant: "primary", size: "md", disabled: false }
+     */
+    args?: Record<string, string | number | boolean>;
+}
+/**
+ * Per-file story entry with CSF v3 export data.
+ * Extends the original minimal `{ id, importPath }` shape with parsed story exports.
+ */
+export interface StoryEntry {
+    id: string;
+    importPath: string;
+    /**
+     * Component name from the default export's `component` field (best-effort).
+     * e.g. `export default { component: Button }` → componentName = "Button"
+     * Absent when the default export is complex or uses a variable reference
+     * not visible as a direct identifier.
+     */
+    componentName?: string;
+    /**
+     * Named story exports from the file.
+     * e.g. `export const Primary = { args: { variant: "primary" } }` →
+     * stories = [{ name: "Primary", args: { variant: "primary" } }]
+     * Absent when no exports were extracted (complex factory patterns, parse errors).
+     */
+    stories?: StoryExport[];
+}
+export interface StoryIndex {
+    byTitle: Map<string, StoryEntry>;
+}
+export interface Rule {
+    id: RuleId;
+    axis: AxisName;
+    evaluate(ctx: RuleContext, parsedFiles: ParsedFiles): Promise<RuleEvalResult>;
+    classifyConfidence?: (finding: Finding, ctx: ClassifyContext) => Confidence;
+    applyCodemod?: (finding: Finding, ctx: CodemodContext) => CodemodResult;
+}
+export interface ParsedFiles {
+    ts: ParsedTsFile[];
+    css: ParsedCssFile[];
+    cssInJs: ExtractedCssInJsBlock[];
+}
+export interface ParsedTsFile {
+    path: string;
+    ast: unknown;
+    source: string;
+    imports: ImportRecord[];
+}
+export interface ImportRecord {
+    module: string;
+    named: string[];
+    default: string | null;
+    line: number;
+}
+export interface ParsedCssFile {
+    path: string;
+    source: string;
+    /**
+     * Set to `true` for `.sass` (indented syntax) files which are still skipped
+     * in v0.1. `.scss` is fully parsed via `parsers/scss-transform.ts` and the
+     * transformed CSS-equivalent source is returned in `source`.
+     * Also set to `true` if the SCSS transform throws unexpectedly so the
+     * pipeline degrades gracefully instead of crashing the audit.
+     */
+    skipped?: true;
+}
+export interface ExtractedCssInJsBlock {
+    path: string;
+    line: number;
+    content: string;
+}
+export interface ParseError {
+    file: string;
+    reason: string;
+}
+export interface RuleEvalResult {
+    findings: Finding[];
+    opportunities: number;
+    /**
+     * Files the rule attempted to analyze but had to skip because its parser
+     * could not understand them. Surfaced as `meta.parseErrors` in the audit
+     * output so users can see what was NOT analyzed (transparency over silent
+     * 100/100 scores). v0.1 limitation — see issue #155.
+     */
+    parseErrors?: ParseError[];
+}
+export interface AxisScore {
+    axis: AxisName;
+    score: number | "N/A";
+    findings: number;
+    opportunities: number;
+}
+export interface Layer4Meta {
+    /** True when the LLM response was served from cache. */
+    cacheHit?: boolean;
+    /** USD spent on LLM calls (0 on cache hit). */
+    usdSpent?: number;
+    /** Model identifier as reported by the connector. */
+    modelUsed?: string;
+    /** "higher" for frontier models, "lower" for local/free-tier. */
+    llmQuality?: "higher" | "lower";
+    /** Number of LLM-proposed findings dropped by the validator. */
+    droppedHallucinations?: number;
+    /** Set to true when Layer 4 was intentionally skipped via --static-only. */
+    staticOnly?: boolean;
+    /** Non-fatal error that occurred during Layer 4 (audit continues with Layers 1+2 score). */
+    error?: {
+        kind: string;
+        message: string;
+    };
+}
+export interface CoverageMeta {
+    /** Count of source files actually walked by the scanner (NOT a generic find of the repo). */
+    scannedFiles: number;
+    /** Audit pipeline duration in milliseconds (excludes Node boot and CLI argument parsing). */
+    durationMs: number;
+    /** Resolved path to the user's .lyse.yaml, or `null` when no config file was discovered. */
+    configPath: string | null;
+    /**
+     * Files a rule attempted to analyze but could not parse. Deterministic (same
+     * file → same reason), sorted by `file` ascending. Omitted when no rule reported
+     * a parse failure. Tracks #155.
+     */
+    parseErrors?: ParseError[];
+}
+export interface AuditResult {
+    schemaVersion: 2;
+    rulesVersion: string;
+    toolVersion: string;
+    /**
+     * The pinned scoring-formula version stamped on every emitted audit artifact.
+     * Currently always `"scoring-v1"`. Bumping to `"scoring-v2"` is a semver-major
+     * event — same input may produce a different score.
+     * (ADR 0017 + spec §3 falsifiable claim 1.)
+     */
+    scoringVersion: "scoring-v1";
+    repoRoot: string;
+    timestamp: string;
+    stack: string[];
+    finalScore: number | "N/A";
+    tier: string;
+    axes: AxisScore[];
+    findings: Finding[];
+    /** ADR-0015: Layer 4 LLM augmentation metadata + #156 audit-perimeter signals. */
+    meta?: {
+        layer4?: Layer4Meta;
+        /** Phase 1 of #156 — audit-perimeter signals so the score has a visible denominator. Includes `parseErrors` (#155) as a deterministic subfield. */
+        coverage?: CoverageMeta;
+    };
+}
+export interface RuleMeta {
+    id: RuleId;
+    axis: AxisName;
+    defaultSeverity: Severity;
+    shortDescription: string;
+    fullDescription: string;
+    helpUri: string;
+    rationale: string;
+    examples: {
+        good: string;
+        bad: string;
+    }[];
+    allowlist: string[];
+}
+export interface RulesManifest {
+    schemaVersion: "1.0.0";
+    rulesVersion: string;
+    rules: RuleMeta[];
+}
+export type Confidence = "high" | "medium" | "low";
+export declare function isValidConfidence(v: unknown): v is Confidence;
+export interface LyseConfig {
+    designSystem?: {
+        componentsModule?: string;
+        elements?: Record<string, string>;
+        excludePaths?: string[];
+    };
+    llm?: {
+        provider?: 'anthropic' | 'openai' | 'openai-compatible' | 'mcp' | 'none' | 'auto';
+        model?: string;
+        endpoint?: string;
+        /** ADR-0015: ConnectorResolver fields (Task 2) */
+        connector?: 'auto' | 'mcp-host' | 'openrouter' | 'direct-api-key' | 'ollama';
+        costCapUsd?: number;
+        cacheMaxAgeDays?: number;
+        staticOnly?: boolean;
+    };
+}
+export interface ClassifyContext {
+    tokens: TokenMap;
+    components: Set<string>;
+    config: LyseConfig;
+    /**
+     * Absolute path to the repository root being audited. Optional because
+     * historical callers built `ClassifyContext` without this field; rules
+     * that need on-demand semantic resolution (e.g. via ts-morph) should
+     * degrade gracefully when it is absent.
+     */
+    repoRoot?: string;
+}
+export interface CodemodContext extends ClassifyContext {
+    fileContent: string;
+    parsedAst: unknown;
+}
+export interface CodemodResult {
+    diff: string;
+    importsAdded: string[];
+    confidence: Confidence;
+    warnings?: string[];
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+export function isValidConfidence(v) {
+    return v === "high" || v === "medium" || v === "low";
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAiTA,MAAM,UAAU,iBAAiB,CAAC,CAAU;IAC1C,OAAO,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,KAAK,CAAC;AACvD,CAAC"}

package/dist/util/git.d.ts

@@ -0,0 +1,6 @@
+export declare function gitHeadSha(repoRoot: string): Promise<string>;
+export interface ModifiedFile {
+    path: string;
+    contentHash: string;
+}
+export declare function modifiedFilesWithHashes(repoRoot: string): Promise<ModifiedFile[]>;

package/dist/util/git.js

@@ -0,0 +1,40 @@
+// packages/core/src/util/git.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+const execFileAsync = promisify(execFile);
+export async function gitHeadSha(repoRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: repoRoot });
+        return stdout.trim();
+    }
+    catch {
+        return "no-git";
+    }
+}
+export async function modifiedFilesWithHashes(repoRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["diff", "--name-only", "HEAD"], { cwd: repoRoot });
+        const paths = stdout.split("\n").filter((p) => p.length > 0);
+        const out = [];
+        for (const p of paths) {
+            try {
+                const content = await fs.readFile(join(repoRoot, p), "utf8");
+                out.push({
+                    path: p,
+                    contentHash: createHash("sha256").update(content).digest("hex").slice(0, 16),
+                });
+            }
+            catch {
+                // file deleted or unreadable — skip
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/util/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/util/git.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QACxF,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAOD,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,QAAgB;IAC5D,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClG,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC7D,MAAM,GAAG,GAAmB,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;gBAC7D,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,CAAC;oBACP,WAAW,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;iBAC7E,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,oCAAoC;YACtC,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/util/git.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for util/git.ts — gitHeadSha + modifiedFilesWithHashes.
+ * These test the fallback paths (no git repo) so no real git state is required.
+ */
+export {};

package/dist/util/git.test.js

@@ -0,0 +1,42 @@
+/**
+ * Unit tests for util/git.ts — gitHeadSha + modifiedFilesWithHashes.
+ * These test the fallback paths (no git repo) so no real git state is required.
+ */
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gitHeadSha, modifiedFilesWithHashes } from "./git.js";
+describe("gitHeadSha", () => {
+    it("returns 'no-git' for a directory that is not a git repo", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "lyse-git-"));
+        try {
+            const sha = await gitHeadSha(dir);
+            expect(sha).toBe("no-git");
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("returns a non-empty string for a real git repo", async () => {
+        // Use the Lyse repo root itself as a real git repo
+        const sha = await gitHeadSha(process.cwd());
+        // Should be a 40-char hex SHA or "no-git"
+        expect(typeof sha).toBe("string");
+        expect(sha.length).toBeGreaterThan(0);
+    });
+});
+describe("modifiedFilesWithHashes", () => {
+    it("returns an empty array for a directory that is not a git repo", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "lyse-git-mod-"));
+        try {
+            const result = await modifiedFilesWithHashes(dir);
+            expect(Array.isArray(result)).toBe(true);
+            expect(result).toHaveLength(0);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=git.test.js.map

package/dist/util/git.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.test.js","sourceRoot":"","sources":["../../src/util/git.test.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAE/D,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC;QACrD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;YAClC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC9D,mDAAmD;QACnD,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QAC5C,0CAA0C;QAC1C,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;QACzD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC,GAAG,CAAC,CAAC;YAClD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACjC,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/util/gitignore.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Ensures that an entry exists in .gitignore at the given repository root.
+ * Idempotent: if the entry already exists, this is a no-op.
+ * If not in a git repo (no .git/ directory), this is also a no-op.
+ *
+ * @param cwd Repository root directory
+ * @param entry The .gitignore entry to ensure (e.g., ".lyse/")
+ */
+export declare function ensureGitignoreEntry(cwd: string, entry: string): Promise<void>;

package/dist/util/gitignore.js

@@ -0,0 +1,39 @@
+import { readFile, appendFile, writeFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import { constants } from "node:fs";
+/**
+ * Ensures that an entry exists in .gitignore at the given repository root.
+ * Idempotent: if the entry already exists, this is a no-op.
+ * If not in a git repo (no .git/ directory), this is also a no-op.
+ *
+ * @param cwd Repository root directory
+ * @param entry The .gitignore entry to ensure (e.g., ".lyse/")
+ */
+export async function ensureGitignoreEntry(cwd, entry) {
+    // No-op if not a git repo
+    try {
+        await access(join(cwd, ".git"), constants.F_OK);
+    }
+    catch {
+        return;
+    }
+    const gPath = join(cwd, ".gitignore");
+    try {
+        const raw = await readFile(gPath, "utf8");
+        // Check if entry exists (exact match or with/without trailing slash)
+        const normalizedEntry = entry.replace(/\/$/, "");
+        const lines = raw.split("\n");
+        if (lines.some((line) => {
+            const normalized = line.trim().replace(/\/$/, "");
+            return normalized === normalizedEntry || normalized === entry.trim();
+        })) {
+            return; // Already exists
+        }
+        await appendFile(gPath, `\n# Lyse local cache\n${entry}\n`);
+    }
+    catch {
+        // File doesn't exist, create it
+        await writeFile(gPath, `# Lyse local cache\n${entry}\n`);
+    }
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/util/gitignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.js","sourceRoot":"","sources":["../../src/util/gitignore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,GAAW,EAAE,KAAa;IACnE,0BAA0B;IAC1B,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC1C,qEAAqE;QACrE,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YACtB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAClD,OAAO,UAAU,KAAK,eAAe,IAAI,UAAU,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QACvE,CAAC,CAAC,EAAE,CAAC;YACH,OAAO,CAAC,iBAAiB;QAC3B,CAAC;QACD,MAAM,UAAU,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;QAChC,MAAM,SAAS,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC"}

package/dist/util/hash-deps.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hash selected dependencies from package.json.
+ * If `tracked` is provided, only those keys are hashed.
+ * If not provided, hashes the union of dependencies + devDependencies.
+ */
+export declare function hashDeps(repoRoot: string, tracked?: string[]): string;

package/dist/util/hash-deps.js

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Hash selected dependencies from package.json.
+ * If `tracked` is provided, only those keys are hashed.
+ * If not provided, hashes the union of dependencies + devDependencies.
+ */
+export function hashDeps(repoRoot, tracked) {
+    const pkgPath = join(repoRoot, "package.json");
+    if (!existsSync(pkgPath))
+        return "";
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const all = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (tracked) {
+        const selected = {};
+        for (const dep of tracked)
+            if (dep in all)
+                selected[dep] = all[dep];
+        return "sha256:" + createHash("sha256").update(JSON.stringify(selected)).digest("hex").slice(0, 16);
+    }
+    return "sha256:" + createHash("sha256").update(JSON.stringify(all)).digest("hex").slice(0, 16);
+}
+//# sourceMappingURL=hash-deps.js.map

package/dist/util/hash-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-deps.js","sourceRoot":"","sources":["../../src/util/hash-deps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,OAAkB;IAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAGnD,CAAC;IACF,MAAM,GAAG,GAA2B,EAAE,GAAG,GAAG,CAAC,YAAY,EAAE,GAAG,GAAG,CAAC,eAAe,EAAE,CAAC;IACpF,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,QAAQ,GAA2B,EAAE,CAAC;QAC5C,KAAK,MAAM,GAAG,IAAI,OAAO;YAAE,IAAI,GAAG,IAAI,GAAG;gBAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAE,CAAC;QACrE,OAAO,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACjG,CAAC"}

package/dist/util/spinner.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimal in-house spinner — issue #97.
+ *
+ * Why in-house? `ora` / `nanospinner` / `cli-spinners` would each pull a small
+ * dep tree we don't need. The full spec for an audit-time spinner is a redraw
+ * loop + ANSI cursor codes — well under 100 LOC. picocolors (already a dep)
+ * handles color.
+ *
+ * Design contract:
+ *   - Always writes to stderr by default. stdout is reserved for the audit
+ *     JSON / SARIF payload; the spinner must never contaminate it.
+ *   - No-op when `enabled` is false OR `isTTY` is false. Callers can pass the
+ *     spinner unconditionally; suppression logic lives here.
+ *   - On `start()` we hide the cursor and install signal handlers so a
+ *     ^C-killed audit doesn't leave the terminal in a cursor-hidden state.
+ *   - On `succeed()` / `fail()` / `stop()` we clear the spinner line first,
+ *     then optionally write the final state (succeed/fail). The final line
+ *     persists; the in-progress frame does not.
+ */
+export interface SpinnerOptions {
+    /** Whether the destination stream is a TTY. */
+    isTTY: boolean;
+    /** Master switch — false means no-op (used for --quiet, JSON/SARIF, etc.). */
+    enabled: boolean;
+    /** Destination stream (default: process.stderr). */
+    stream?: NodeJS.WriteStream;
+    /**
+     * Whether to emit ANSI color codes. Cursor + clear-line codes are emitted
+     * regardless because they're what makes the spinner visible. Default:
+     * `isTTY && NO_COLOR` is unset.
+     */
+    color?: boolean;
+}
+export interface Spinner {
+    start(label: string): void;
+    update(label: string): void;
+    succeed(label: string): void;
+    fail(label: string): void;
+    stop(): void;
+}
+export declare function createSpinner(opts: SpinnerOptions): Spinner;