@shrkcrft/inspector 0.1.0-alpha.1

package/dist/generated-code.js

@@ -0,0 +1,395 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { findFiles } from '@shrkcrft/workspace';
+export const GENERATED_CODE_SCHEMA = 'sharkcraft.generated-code/v1';
+export var GeneratedConfidence;
+(function (GeneratedConfidence) {
+    GeneratedConfidence["High"] = "high";
+    GeneratedConfidence["Medium"] = "medium";
+    GeneratedConfidence["Low"] = "low";
+})(GeneratedConfidence || (GeneratedConfidence = {}));
+export var GeneratedKind;
+(function (GeneratedKind) {
+    GeneratedKind["Marker"] = "marker";
+    GeneratedKind["OpenApi"] = "openapi";
+    GeneratedKind["GraphQL"] = "graphql";
+    GeneratedKind["Protobuf"] = "protobuf";
+    GeneratedKind["PrismaClient"] = "prisma-client";
+    GeneratedKind["AngularEnv"] = "angular-environment";
+    GeneratedKind["AngularRouter"] = "angular-router";
+    GeneratedKind["Dist"] = "dist";
+    GeneratedKind["Lockfile"] = "lockfile";
+    GeneratedKind["Vendor"] = "vendor";
+    GeneratedKind["Snapshot"] = "snapshot";
+    /** Per-language markers. */
+    GeneratedKind["JavaGenerated"] = "java-generated";
+    GeneratedKind["CSharpGenerated"] = "csharp-generated";
+    GeneratedKind["PythonGenerated"] = "python-generated";
+    GeneratedKind["GoGenerated"] = "go-generated";
+    GeneratedKind["RustGenerated"] = "rust-generated";
+    GeneratedKind["Unknown"] = "unknown";
+})(GeneratedKind || (GeneratedKind = {}));
+/** Scan depth selector for generated-code detection. */
+export var GeneratedScanDepth;
+(function (GeneratedScanDepth) {
+    /** 4096 bytes / 30 lines per file, 600 files (existing default). */
+    GeneratedScanDepth["Standard"] = "standard";
+    /** 16384 bytes / 200 lines per file, 2000 files. */
+    GeneratedScanDepth["Deep"] = "deep";
+    /** 65536 bytes / capped full scan per file, 5000 files. */
+    GeneratedScanDepth["Extreme"] = "extreme";
+})(GeneratedScanDepth || (GeneratedScanDepth = {}));
+const DEFAULT_SCAN_LIMIT = 600;
+const DEFAULT_HEAD_BYTES = 4096;
+const DEFAULT_HEAD_LINES = 30;
+const DEPTH_LIMITS = {
+    [GeneratedScanDepth.Standard]: { scanLimit: 600, headBytes: 4096, headLines: 30 },
+    [GeneratedScanDepth.Deep]: { scanLimit: 2000, headBytes: 16384, headLines: 200 },
+    [GeneratedScanDepth.Extreme]: { scanLimit: 5000, headBytes: 65536, headLines: 600 },
+};
+const GENERATED_DIR_HINTS = [
+    { re: /(^|\/)dist(\/|$)/, kind: GeneratedKind.Dist, confidence: GeneratedConfidence.High, reason: 'Compiled build output directory.' },
+    { re: /(^|\/)build(\/|$)/, kind: GeneratedKind.Dist, confidence: GeneratedConfidence.Medium, reason: 'Common build output directory.' },
+    { re: /(^|\/)out(\/|$)/, kind: GeneratedKind.Dist, confidence: GeneratedConfidence.Low, reason: 'Sometimes a build output directory.' },
+    { re: /(^|\/)\.next(\/|$)/, kind: GeneratedKind.Dist, confidence: GeneratedConfidence.High, reason: 'Next.js build output.' },
+    { re: /(^|\/)\.nuxt(\/|$)/, kind: GeneratedKind.Dist, confidence: GeneratedConfidence.High, reason: 'Nuxt build output.' },
+    { re: /(^|\/)\.angular(\/|$)/, kind: GeneratedKind.Dist, confidence: GeneratedConfidence.High, reason: 'Angular CLI cache output.' },
+    { re: /(^|\/)\.svelte-kit(\/|$)/, kind: GeneratedKind.Dist, confidence: GeneratedConfidence.High, reason: 'SvelteKit build output.' },
+    { re: /(^|\/)coverage(\/|$)/, kind: GeneratedKind.Snapshot, confidence: GeneratedConfidence.High, reason: 'Test coverage report.' },
+    { re: /(^|\/)__snapshots__(\/|$)/, kind: GeneratedKind.Snapshot, confidence: GeneratedConfidence.High, reason: 'Test snapshots — auto-managed by the test runner.' },
+    { re: /(^|\/)generated(\/|$)/, kind: GeneratedKind.Marker, confidence: GeneratedConfidence.High, reason: 'Folder explicitly named generated.' },
+    { re: /(^|\/)__generated__(\/|$)/, kind: GeneratedKind.Marker, confidence: GeneratedConfidence.High, reason: 'Folder explicitly named __generated__.' },
+    { re: /(^|\/)gen(\/|$)/, kind: GeneratedKind.Marker, confidence: GeneratedConfidence.Medium, reason: 'Folder named gen (often a generated code root).' },
+    // Per-language generated source roots.
+    { re: /(^|\/)target\/generated-sources(\/|$)/, kind: GeneratedKind.JavaGenerated, confidence: GeneratedConfidence.High, reason: 'Maven generated-sources root.' },
+    { re: /(^|\/)target\/generated-test-sources(\/|$)/, kind: GeneratedKind.JavaGenerated, confidence: GeneratedConfidence.High, reason: 'Maven generated-test-sources root.' },
+    { re: /(^|\/)build\/generated(\/|$)/, kind: GeneratedKind.JavaGenerated, confidence: GeneratedConfidence.High, reason: 'Gradle build/generated root.' },
+    { re: /(^|\/)obj(\/|$)/, kind: GeneratedKind.CSharpGenerated, confidence: GeneratedConfidence.High, reason: 'C# obj/ build artifacts.' },
+    { re: /(^|\/)\.openapi-generator(\/|$)/, kind: GeneratedKind.OpenApi, confidence: GeneratedConfidence.High, reason: 'OpenAPI generator cache.' },
+    { re: /(^|\/)prisma\/generated(\/|$)/, kind: GeneratedKind.PrismaClient, confidence: GeneratedConfidence.High, reason: 'Prisma generated client root.' },
+    { re: /(^|\/)proto(\/|$)/, kind: GeneratedKind.Protobuf, confidence: GeneratedConfidence.Medium, reason: 'Proto-buffers folder.' },
+    { re: /(^|\/)graphql(\/|$)/, kind: GeneratedKind.GraphQL, confidence: GeneratedConfidence.Low, reason: 'May contain generated GraphQL types.' },
+    { re: /node_modules(\/|$)/, kind: GeneratedKind.Vendor, confidence: GeneratedConfidence.High, reason: 'Vendored dependency tree — never hand-edit.' },
+    { re: /\.nx\/cache(\/|$)/, kind: GeneratedKind.Dist, confidence: GeneratedConfidence.High, reason: 'Nx cache.' },
+];
+const LOCKFILES = new Set([
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'bun.lockb',
+    'bun.lock',
+    'composer.lock',
+    'Gemfile.lock',
+    'Cargo.lock',
+    'poetry.lock',
+    'go.sum',
+]);
+const ENV_FILE_RE = /(^|\/)src\/environments\/environment(\.[^/]+)?\.ts$/;
+const ANGULAR_ROUTES_GEN_RE = /(^|\/)\.angular\//;
+const FILE_MARKERS = [
+    { re: /\bDO NOT EDIT\b/i, kind: GeneratedKind.Marker, reason: '"DO NOT EDIT" header.' },
+    { re: /@generated\b/i, kind: GeneratedKind.Marker, reason: '@generated marker.' },
+    { re: /auto-?generated/i, kind: GeneratedKind.Marker, reason: '"auto-generated" header.' },
+    { re: /\bgenerated by\b/i, kind: GeneratedKind.Marker, reason: '"generated by ..." attribution.' },
+    { re: /this file was automatically generated/i, kind: GeneratedKind.Marker, reason: 'Auto-generation banner.' },
+    { re: /Code generated by .*; DO NOT EDIT/i, kind: GeneratedKind.GoGenerated, reason: 'Go-style generated banner.', ext: ['.go'] },
+    { re: /openapi-generator/i, kind: GeneratedKind.OpenApi, reason: 'OpenAPI generator banner.' },
+    { re: /swagger-codegen/i, kind: GeneratedKind.OpenApi, reason: 'Swagger codegen banner.' },
+    { re: /graphql-code-generator/i, kind: GeneratedKind.GraphQL, reason: 'graphql-codegen banner.' },
+    { re: /protoc-gen-/i, kind: GeneratedKind.Protobuf, reason: 'protoc-gen banner.' },
+    { re: /prisma-client-js/i, kind: GeneratedKind.PrismaClient, reason: 'Prisma client banner.' },
+    // Per-language markers.
+    { re: /@javax\.annotation\.Generated\b/, kind: GeneratedKind.JavaGenerated, reason: 'javax.annotation.Generated annotation.', ext: ['.java'] },
+    { re: /@jakarta\.annotation\.Generated\b/, kind: GeneratedKind.JavaGenerated, reason: 'jakarta.annotation.Generated annotation.', ext: ['.java'] },
+    { re: /@Generated\s*\(/, kind: GeneratedKind.JavaGenerated, reason: 'Java @Generated annotation.', ext: ['.java'] },
+    { re: /\[GeneratedCode\s*\(/i, kind: GeneratedKind.CSharpGenerated, reason: '[GeneratedCode] attribute.', ext: ['.cs'] },
+    { re: /<auto-generated[^>]*>/i, kind: GeneratedKind.CSharpGenerated, reason: '<auto-generated/> doc comment.', ext: ['.cs'] },
+    { re: /^\s*#\s*@generated\b/m, kind: GeneratedKind.PythonGenerated, reason: 'Python @generated comment.', ext: ['.py'] },
+    { re: /generated by protoc/i, kind: GeneratedKind.Protobuf, reason: 'protoc generated banner.' },
+    { re: /generated by bindgen/i, kind: GeneratedKind.RustGenerated, reason: 'rust-bindgen generated banner.', ext: ['.rs'] },
+];
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.go', '.py', '.rs', '.cs', '.java', '.kt', '.swift', '.proto', '.graphql', '.gql']);
+export function buildGeneratedCodeReport(options) {
+    const inspection = options.inspection;
+    const depth = options.depth ?? GeneratedScanDepth.Standard;
+    const depthLimits = DEPTH_LIMITS[depth];
+    const scanLimit = options.fileScanLimit ?? depthLimits.scanLimit;
+    const headBytes = options.headBytes ?? depthLimits.headBytes;
+    const headLines = depthLimits.headLines;
+    const projectRoot = inspection.projectRoot;
+    const limitations = [];
+    const generatedFiles = [];
+    const handwrittenFiles = [];
+    const mixedFiles = [];
+    const rootCounts = new Map();
+    const recordRoot = (path, kind, confidence, reason) => {
+        const key = `${path}|${kind}`;
+        const prev = rootCounts.get(key);
+        if (prev) {
+            rootCounts.set(key, { ...prev, fileCount: prev.fileCount + 1 });
+            return;
+        }
+        rootCounts.set(key, { path, kind, confidence, reason, fileCount: 1 });
+    };
+    let scanned = 0;
+    const files = enumerateRepoFiles(inspection);
+    for (const file of files) {
+        const rel = file;
+        const abs = nodePath.isAbsolute(rel) ? rel : nodePath.join(projectRoot, rel);
+        // Lockfiles + Angular environment.
+        const base = nodePath.basename(rel);
+        if (LOCKFILES.has(base)) {
+            generatedFiles.push({
+                path: rel,
+                kind: GeneratedKind.Lockfile,
+                confidence: GeneratedConfidence.High,
+                reason: 'Package-manager lockfile.',
+            });
+            recordRoot(nodePath.dirname(rel), GeneratedKind.Lockfile, GeneratedConfidence.High, 'Lockfile location.');
+            continue;
+        }
+        if (ENV_FILE_RE.test(rel)) {
+            generatedFiles.push({
+                path: rel,
+                kind: GeneratedKind.AngularEnv,
+                confidence: GeneratedConfidence.Medium,
+                reason: 'Angular environment file (often substituted at build time).',
+            });
+            continue;
+        }
+        if (ANGULAR_ROUTES_GEN_RE.test(rel)) {
+            generatedFiles.push({
+                path: rel,
+                kind: GeneratedKind.AngularRouter,
+                confidence: GeneratedConfidence.High,
+                reason: 'Under .angular/ build directory.',
+            });
+            continue;
+        }
+        let matchedDir;
+        for (const hint of GENERATED_DIR_HINTS) {
+            if (hint.re.test(rel)) {
+                matchedDir = { kind: hint.kind, confidence: hint.confidence, reason: hint.reason };
+                // Find segment that triggered the match for root attribution.
+                const m = rel.match(hint.re);
+                if (m) {
+                    const idx = rel.indexOf(m[0]);
+                    const root = rel.slice(0, idx + m[0].length).replace(/\/$/, '');
+                    recordRoot(root, hint.kind, hint.confidence, hint.reason);
+                }
+                break;
+            }
+        }
+        if (matchedDir) {
+            generatedFiles.push({
+                path: rel,
+                kind: matchedDir.kind,
+                confidence: matchedDir.confidence,
+                reason: matchedDir.reason,
+            });
+            continue;
+        }
+        const ext = nodePath.extname(rel).toLowerCase();
+        if (!SOURCE_EXTS.has(ext)) {
+            handwrittenFiles.push(rel);
+            continue;
+        }
+        // Peek at file head.
+        if (scanned >= scanLimit) {
+            handwrittenFiles.push(rel);
+            continue;
+        }
+        let head = '';
+        try {
+            if (existsSync(abs) && statSync(abs).isFile()) {
+                const fd = readFileSync(abs);
+                head = fd.slice(0, headBytes).toString('utf8');
+                scanned += 1;
+            }
+        }
+        catch {
+            head = '';
+        }
+        if (!head) {
+            handwrittenFiles.push(rel);
+            continue;
+        }
+        let matched;
+        const lines = head.split(/\r?\n/);
+        const scanLines = lines.slice(0, headLines);
+        const lowerExt = ext;
+        for (let i = 0; i < scanLines.length; i += 1) {
+            const line = scanLines[i] ?? '';
+            for (const marker of FILE_MARKERS) {
+                if (marker.ext && !marker.ext.includes(lowerExt))
+                    continue;
+                if (marker.re.test(line)) {
+                    matched = { kind: marker.kind, reason: marker.reason, line: i + 1 };
+                    break;
+                }
+            }
+            if (matched)
+                break;
+        }
+        if (matched) {
+            generatedFiles.push({
+                path: rel,
+                kind: matched.kind,
+                confidence: GeneratedConfidence.High,
+                reason: matched.reason,
+                markerLine: matched.line,
+            });
+            continue;
+        }
+        handwrittenFiles.push(rel);
+    }
+    if (scanned >= scanLimit) {
+        limitations.push(`File-content scan limited to ${scanLimit} files; some generated headers may be missed.`);
+    }
+    const generatedRoots = Array.from(rootCounts.values()).sort((a, b) => b.fileCount - a.fileCount);
+    const protectedRules = [];
+    if (generatedRoots.length > 0) {
+        protectedRules.push({
+            id: 'generated.no-manual-edit',
+            title: 'Do not hand-edit generated files',
+            content: 'Files under generated roots are produced by tooling. Manual edits will be lost on the next regeneration. If a change is needed, modify the generator input (schema/template/config) and re-run codegen.',
+            patterns: generatedRoots.map((r) => `${r.path}/**`),
+            reason: 'Generated-code policy boundary; avoids silent regressions.',
+        });
+    }
+    if (generatedFiles.some((f) => f.kind === GeneratedKind.Marker || f.kind === GeneratedKind.OpenApi || f.kind === GeneratedKind.GraphQL || f.kind === GeneratedKind.Protobuf || f.kind === GeneratedKind.PrismaClient)) {
+        protectedRules.push({
+            id: 'generated.respect-do-not-edit',
+            title: 'Respect @generated / DO NOT EDIT markers',
+            content: 'Files annotated with @generated, "DO NOT EDIT", or a code-generator banner must not be edited by hand. The change belongs in the generator source.',
+            patterns: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.go', '**/*.rs'],
+            reason: 'Marker-driven generated-code protection.',
+        });
+    }
+    const recommendedPolicyRules = [];
+    if (generatedRoots.length > 0) {
+        recommendedPolicyRules.push({
+            id: 'policy.generated-roots-readonly',
+            title: 'Treat generated roots as read-only by default',
+            description: 'Plans that modify files under generated roots require an explicit "generated" intent on the task contract. Otherwise the plan is rejected at review.',
+            suggestedId: 'policy.generated-readonly',
+            patterns: generatedRoots.map((r) => `${r.path}/**`),
+            reason: 'Prevents agents from silently overwriting generated output.',
+        });
+    }
+    return {
+        schema: GENERATED_CODE_SCHEMA,
+        projectRoot,
+        generatedFiles,
+        handwrittenFiles,
+        mixedFiles,
+        generatedRoots,
+        protectedRules,
+        recommendedPolicyRules,
+        filesScanned: scanned,
+        limitations,
+    };
+}
+function enumerateRepoFiles(inspection) {
+    const found = findFiles(inspection.projectRoot, /\.(ts|tsx|js|jsx|mjs|cjs|go|py|rs|cs|java|kt|swift|proto|graphql|gql|d\.ts)$/i, { maxDepth: 6 });
+    const rel = found.map((f) => nodePath.relative(inspection.projectRoot, f));
+    const set = new Set(rel);
+    for (const f of inspection.sourceFiles) {
+        // Drop any path that escapes the project root (e.g. absolute paths inside
+        // node_modules that the knowledge loader picked up via pack discovery).
+        if (nodePath.isAbsolute(f)) {
+            const r = nodePath.relative(inspection.projectRoot, f);
+            if (r.startsWith('..'))
+                continue;
+            if (r.includes('node_modules'))
+                continue;
+            set.add(r);
+        }
+        else {
+            if (f.includes('node_modules'))
+                continue;
+            set.add(f);
+        }
+    }
+    return Array.from(set).sort();
+}
+export function renderGeneratedCodeReportText(report) {
+    const lines = [];
+    lines.push(`=== Generated-code report ===`);
+    lines.push(`  generated files     ${report.generatedFiles.length}`);
+    lines.push(`  handwritten files   ${report.handwrittenFiles.length}`);
+    lines.push(`  generated roots     ${report.generatedRoots.length}`);
+    lines.push(`  files scanned       ${report.filesScanned}`);
+    if (report.generatedRoots.length > 0) {
+        lines.push('');
+        lines.push('Generated roots:');
+        for (const r of report.generatedRoots.slice(0, 25)) {
+            lines.push(`  - ${r.path}  [${r.kind} / ${r.confidence}]  ${r.reason} (${r.fileCount} files)`);
+        }
+    }
+    if (report.protectedRules.length > 0) {
+        lines.push('');
+        lines.push('Protected rules:');
+        for (const rule of report.protectedRules) {
+            lines.push(`  - ${rule.id} — ${rule.title}`);
+        }
+    }
+    if (report.limitations.length > 0) {
+        lines.push('');
+        lines.push('Limitations:');
+        for (const l of report.limitations)
+            lines.push(`  - ${l}`);
+    }
+    return lines.join('\n');
+}
+export function renderGeneratedCodeReportMarkdown(report) {
+    const lines = [];
+    lines.push('# Generated-code report');
+    lines.push('');
+    lines.push(`- Generated files: **${report.generatedFiles.length}**`);
+    lines.push(`- Handwritten files: **${report.handwrittenFiles.length}**`);
+    lines.push(`- Generated roots: **${report.generatedRoots.length}**`);
+    lines.push(`- Files scanned for markers: **${report.filesScanned}**`);
+    if (report.generatedRoots.length > 0) {
+        lines.push('');
+        lines.push('## Roots');
+        lines.push('');
+        lines.push('| Path | Kind | Confidence | Files | Reason |');
+        lines.push('|---|---|---|---|---|');
+        for (const r of report.generatedRoots) {
+            lines.push(`| \`${r.path}\` | ${r.kind} | ${r.confidence} | ${r.fileCount} | ${r.reason} |`);
+        }
+    }
+    if (report.protectedRules.length > 0) {
+        lines.push('');
+        lines.push('## Recommended protected rules');
+        lines.push('');
+        for (const r of report.protectedRules) {
+            lines.push(`### ${r.title}`);
+            lines.push('');
+            lines.push(r.content);
+            lines.push('');
+            lines.push(`Applies to: ${r.patterns.map((p) => `\`${p}\``).join(', ')}`);
+            lines.push('');
+        }
+    }
+    if (report.recommendedPolicyRules.length > 0) {
+        lines.push('');
+        lines.push('## Recommended policy rules');
+        lines.push('');
+        for (const r of report.recommendedPolicyRules) {
+            lines.push(`- **${r.title}** (\`${r.suggestedId}\`) — ${r.description}`);
+        }
+    }
+    if (report.limitations.length > 0) {
+        lines.push('');
+        lines.push('## Limitations');
+        lines.push('');
+        for (const l of report.limitations)
+            lines.push(`- ${l}`);
+    }
+    return lines.join('\n');
+}
+export function renderGeneratedCodeReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}

package/dist/git-helpers.d.ts

@@ -0,0 +1,38 @@
+export interface IGitChangedOptions {
+    /** Compare against the given ref (HEAD, origin/main, a SHA, …). */
+    since?: string;
+    /** When true, only staged (index) changes. */
+    staged?: boolean;
+    /** When true, include the unstaged working-tree changes too. */
+    includeWorktree?: boolean;
+}
+export interface IGitStatusSummary {
+    branch: string | null;
+    root: string | null;
+    ahead: number;
+    behind: number;
+    staged: number;
+    modified: number;
+    untracked: number;
+    conflicts: number;
+    clean: boolean;
+}
+export declare function isGitRepo(cwd: string): boolean;
+export declare function getGitRoot(cwd: string): string | null;
+export declare function getGitBranch(cwd: string): string | null;
+/**
+ * Verify that `ref` resolves to a commit. Returns `{ valid: true }` on
+ * success, otherwise `{ valid: false, suggestions }` listing nearby
+ * branch / tag names so the caller can offer a did-you-mean.
+ *
+ * Cheap (`git rev-parse --verify` + `git for-each-ref`) — only run when
+ * the user passes an explicit ref.
+ */
+export declare function verifyGitRef(cwd: string, ref: string): {
+    valid: boolean;
+    suggestions?: string[];
+};
+export declare function getChangedFiles(cwd: string, opts?: IGitChangedOptions): string[];
+export declare function getStatusSummary(cwd: string): IGitStatusSummary;
+export declare function parseLines(text: string): string[];
+//# sourceMappingURL=git-helpers.d.ts.map

package/dist/git-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-helpers.d.ts","sourceRoot":"","sources":["../src/git-helpers.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAWD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKvD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAQ5C;AA2CD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,MAAM,EAAE,CAkBpF;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAyC/D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjD"}

package/dist/git-helpers.js

@@ -0,0 +1,173 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+function runGit(cwd, args) {
+    const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+    return {
+        ok: res.status === 0,
+        stdout: (res.stdout ?? '').toString(),
+        stderr: (res.stderr ?? '').toString(),
+    };
+}
+export function isGitRepo(cwd) {
+    if (existsSync(nodePath.join(cwd, '.git')))
+        return true;
+    const r = runGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+    return r.ok && r.stdout.trim() === 'true';
+}
+export function getGitRoot(cwd) {
+    const r = runGit(cwd, ['rev-parse', '--show-toplevel']);
+    if (!r.ok)
+        return null;
+    const out = r.stdout.trim();
+    return out.length > 0 ? out : null;
+}
+export function getGitBranch(cwd) {
+    const r = runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    if (!r.ok)
+        return null;
+    const out = r.stdout.trim();
+    return out.length > 0 ? out : null;
+}
+/**
+ * Verify that `ref` resolves to a commit. Returns `{ valid: true }` on
+ * success, otherwise `{ valid: false, suggestions }` listing nearby
+ * branch / tag names so the caller can offer a did-you-mean.
+ *
+ * Cheap (`git rev-parse --verify` + `git for-each-ref`) — only run when
+ * the user passes an explicit ref.
+ */
+export function verifyGitRef(cwd, ref) {
+    if (!isGitRepo(cwd))
+        return { valid: false, suggestions: [] };
+    const r = runGit(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+    if (r.ok)
+        return { valid: true };
+    // Collect candidate names from local + remote refs, then rank by Levenshtein.
+    const candidates = listRefNames(cwd);
+    const suggestions = nearestRefs(ref, candidates, 3);
+    return { valid: false, suggestions };
+}
+function listRefNames(cwd) {
+    const out = new Set();
+    const local = runGit(cwd, ['for-each-ref', '--format=%(refname:short)', 'refs/heads']);
+    if (local.ok)
+        for (const line of parseLines(local.stdout))
+            out.add(line);
+    const remote = runGit(cwd, ['for-each-ref', '--format=%(refname:short)', 'refs/remotes']);
+    if (remote.ok)
+        for (const line of parseLines(remote.stdout))
+            out.add(line);
+    const tags = runGit(cwd, ['for-each-ref', '--format=%(refname:short)', 'refs/tags']);
+    if (tags.ok)
+        for (const line of parseLines(tags.stdout))
+            out.add(line);
+    return [...out];
+}
+function nearestRefs(query, refs, k) {
+    const scored = refs.map((r) => ({ r, d: levenshtein(query, r) }));
+    scored.sort((a, b) => a.d - b.d);
+    return scored.slice(0, k).map((s) => s.r);
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    const al = a.length;
+    const bl = b.length;
+    if (al === 0)
+        return bl;
+    if (bl === 0)
+        return al;
+    let prev = new Array(bl + 1);
+    let curr = new Array(bl + 1);
+    for (let j = 0; j <= bl; j += 1)
+        prev[j] = j;
+    for (let i = 1; i <= al; i += 1) {
+        curr[0] = i;
+        for (let j = 1; j <= bl; j += 1) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[bl] ?? Math.max(al, bl);
+}
+export function getChangedFiles(cwd, opts = {}) {
+    if (!isGitRepo(cwd))
+        return [];
+    const args = ['diff', '--name-only'];
+    if (opts.staged)
+        args.push('--cached');
+    if (opts.since)
+        args.push(opts.since);
+    const a = runGit(cwd, args);
+    const set = new Set(parseLines(a.stdout));
+    if (opts.includeWorktree && !opts.staged && !opts.since) {
+        // Include untracked + working-tree changes via `git status --porcelain`.
+        const s = runGit(cwd, ['status', '--porcelain']);
+        if (s.ok) {
+            for (const line of s.stdout.split('\n')) {
+                const trimmed = line.slice(3).trim();
+                if (trimmed)
+                    set.add(trimmed);
+            }
+        }
+    }
+    return [...set].sort();
+}
+export function getStatusSummary(cwd) {
+    const empty = {
+        branch: null,
+        root: null,
+        ahead: 0,
+        behind: 0,
+        staged: 0,
+        modified: 0,
+        untracked: 0,
+        conflicts: 0,
+        clean: true,
+    };
+    if (!isGitRepo(cwd))
+        return empty;
+    const r = runGit(cwd, ['status', '--porcelain=2', '--branch']);
+    if (!r.ok)
+        return empty;
+    const out = { ...empty };
+    out.root = getGitRoot(cwd);
+    for (const line of r.stdout.split('\n')) {
+        if (line.startsWith('# branch.head')) {
+            out.branch = line.slice('# branch.head'.length).trim();
+        }
+        else if (line.startsWith('# branch.ab')) {
+            const m = /\+(\d+)\s+-(\d+)/.exec(line);
+            if (m) {
+                out.ahead = Number(m[1]);
+                out.behind = Number(m[2]);
+            }
+        }
+        else if (line.startsWith('1 ') || line.startsWith('2 ')) {
+            const xy = line.split(' ')[1] ?? '..';
+            const x = xy[0] ?? '.';
+            const y = xy[1] ?? '.';
+            if (x !== '.')
+                out.staged += 1;
+            if (y !== '.')
+                out.modified += 1;
+        }
+        else if (line.startsWith('u ')) {
+            out.conflicts += 1;
+        }
+        else if (line.startsWith('? ')) {
+            out.untracked += 1;
+        }
+    }
+    out.clean =
+        out.staged === 0 && out.modified === 0 && out.untracked === 0 && out.conflicts === 0;
+    return out;
+}
+export function parseLines(text) {
+    return text
+        .split('\n')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}

package/dist/golden-output.d.ts

@@ -0,0 +1,33 @@
+export declare const GOLDEN_OUTPUT_SCHEMA = "sharkcraft.golden-output/v1";
+export interface IGoldenOutputCase {
+    id: string;
+    command: string;
+    goldenFile: string;
+}
+export interface IGoldenOutputCompareResult {
+    id: string;
+    match: boolean;
+    diff?: string;
+    goldenPresent: boolean;
+}
+export interface IGoldenOutputReport {
+    schema: typeof GOLDEN_OUTPUT_SCHEMA;
+    generatedAt: string;
+    cases: readonly IGoldenOutputCompareResult[];
+    summary: {
+        total: number;
+        matches: number;
+        mismatches: number;
+        missing: number;
+    };
+}
+export declare function listGoldenCases(): readonly IGoldenOutputCase[];
+/**
+ * Normalize an output blob so timestamps, durations, and absolute paths
+ * don't cause spurious diffs.
+ */
+export declare function normalizeOutput(raw: string): string;
+export declare function compareGoldenOutput(projectRoot: string, caseEntry: IGoldenOutputCase, currentOutput: string): IGoldenOutputCompareResult;
+export declare function writeGoldenOutput(projectRoot: string, caseEntry: IGoldenOutputCase, currentOutput: string): string;
+export declare function summarizeGoldenResults(results: readonly IGoldenOutputCompareResult[]): IGoldenOutputReport['summary'];
+//# sourceMappingURL=golden-output.d.ts.map

package/dist/golden-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden-output.d.ts","sourceRoot":"","sources":["../src/golden-output.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC7C,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAClF;AAUD,wBAAgB,eAAe,IAAI,SAAS,iBAAiB,EAAE,CAE9D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUnD;AAqBD,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,iBAAiB,EAC5B,aAAa,EAAE,MAAM,GACpB,0BAA0B,CAc5B;AAED,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,iBAAiB,EAC5B,aAAa,EAAE,MAAM,GACpB,MAAM,CAMR;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,0BAA0B,EAAE,GAC7C,mBAAmB,CAAC,SAAS,CAAC,CAUhC"}