@shrkcrft/inspector 0.1.0-alpha.1

package/dist/ci-predict.js

@@ -0,0 +1,300 @@
+/**
+ * CI predict / would-fail.
+ *
+ * Deterministic local prediction of likely CI gate outcomes based on the
+ * latest JSON reports under `.sharkcraft/reports/` (the same files the CI
+ * scaffold writes). Read-only — does not run any commands; just inspects
+ * cached state.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildUncertaintyReport } from "./uncertainty-report.js";
+export const CI_PREDICT_SCHEMA = 'sharkcraft.ci-predict/v1';
+export var CiPredictProfileId;
+(function (CiPredictProfileId) {
+    CiPredictProfileId["GithubPr"] = "github-pr";
+    CiPredictProfileId["Release"] = "release";
+    CiPredictProfileId["Pack"] = "pack";
+    CiPredictProfileId["Self"] = "self";
+})(CiPredictProfileId || (CiPredictProfileId = {}));
+export var CiPredictVerdict;
+(function (CiPredictVerdict) {
+    CiPredictVerdict["Pass"] = "pass";
+    CiPredictVerdict["Warn"] = "warn";
+    CiPredictVerdict["Fail"] = "fail";
+    CiPredictVerdict["Unknown"] = "unknown";
+})(CiPredictVerdict || (CiPredictVerdict = {}));
+const PROBES = {
+    [CiPredictProfileId.Self]: [
+        {
+            id: 'doctor',
+            title: 'Workspace doctor',
+            reportFile: 'doctor.json',
+            reader: (j) => {
+                const errors = Number((j['summary']?.['errors']) ?? 0);
+                return {
+                    verdict: errors > 0 ? CiPredictVerdict.Fail : CiPredictVerdict.Pass,
+                    summary: errors > 0 ? `${errors} doctor errors` : 'doctor clean',
+                };
+            },
+            nextCommand: 'shrk doctor',
+        },
+        {
+            id: 'self-config',
+            title: 'Self-config doctor',
+            reportFile: 'self-config-doctor.json',
+            reader: (j) => {
+                const v = j['verdict'];
+                return {
+                    verdict: v === 'errors' ? CiPredictVerdict.Fail : v === 'warnings' ? CiPredictVerdict.Warn : CiPredictVerdict.Pass,
+                    summary: `verdict=${v ?? 'unknown'}`,
+                };
+            },
+            nextCommand: 'shrk self-config doctor',
+        },
+        {
+            id: 'knowledge-stale',
+            title: 'Knowledge stale-check',
+            reportFile: 'knowledge-stale.json',
+            reader: (j) => {
+                const required = Number((j['totals']?.['requiredStale']) ?? 0);
+                return {
+                    verdict: required > 0 ? CiPredictVerdict.Fail : CiPredictVerdict.Pass,
+                    summary: `requiredStale=${required}`,
+                };
+            },
+            nextCommand: 'shrk knowledge stale-check --ci',
+        },
+        {
+            id: 'template-drift',
+            title: 'Templates drift',
+            reportFile: 'template-drift.json',
+            reader: (j) => {
+                const fail = Number((j['totals']?.['fail']) ?? 0);
+                return {
+                    verdict: fail > 0 ? CiPredictVerdict.Fail : CiPredictVerdict.Pass,
+                    summary: `fail=${fail}`,
+                };
+            },
+            nextCommand: 'shrk templates drift --min-severity warning',
+        },
+        {
+            id: 'agent-tests',
+            title: 'Agent contract tests',
+            reportFile: 'agent-tests.json',
+            reader: (j) => {
+                const failed = Number((j['summary']?.['failed']) ?? 0);
+                return {
+                    verdict: failed > 0 ? CiPredictVerdict.Fail : CiPredictVerdict.Pass,
+                    summary: `failed=${failed}`,
+                };
+            },
+            nextCommand: 'shrk test agent',
+        },
+    ],
+    [CiPredictProfileId.GithubPr]: [
+        {
+            id: 'boundaries-changed-only',
+            title: 'Boundaries (changed-only)',
+            reportFile: 'boundaries.json',
+            reader: (j) => {
+                const v = Number((j['summary']?.['violations']) ?? 0);
+                return {
+                    verdict: v > 0 ? CiPredictVerdict.Fail : CiPredictVerdict.Pass,
+                    summary: `violations=${v}`,
+                };
+            },
+            nextCommand: 'shrk check boundaries --changed-only',
+        },
+        {
+            id: 'commands-doctor',
+            title: 'Commands doctor',
+            reportFile: 'commands-doctor.json',
+            reader: (j) => {
+                const e = Number((j['summary']?.['errors']) ?? 0);
+                return {
+                    verdict: e > 0 ? CiPredictVerdict.Fail : CiPredictVerdict.Pass,
+                    summary: `errors=${e}`,
+                };
+            },
+            nextCommand: 'shrk commands doctor',
+        },
+    ],
+    [CiPredictProfileId.Release]: [
+        {
+            id: 'release-readiness',
+            title: 'Release readiness',
+            reportFile: 'release-readiness.json',
+            reader: (j) => {
+                const ready = Boolean(j['ready']);
+                return {
+                    verdict: ready ? CiPredictVerdict.Pass : CiPredictVerdict.Fail,
+                    summary: `ready=${ready}`,
+                };
+            },
+            nextCommand: 'shrk release readiness --strict',
+        },
+    ],
+    [CiPredictProfileId.Pack]: [
+        {
+            id: 'pack-doctor',
+            title: 'Pack doctor',
+            reportFile: 'pack-doctor.json',
+            reader: (j) => {
+                const errors = Number((j['summary']?.['errors']) ?? 0);
+                return {
+                    verdict: errors > 0 ? CiPredictVerdict.Fail : CiPredictVerdict.Pass,
+                    summary: `errors=${errors}`,
+                };
+            },
+            nextCommand: 'shrk packs doctor',
+        },
+    ],
+};
+export function buildCiPredictReport(options) {
+    const reportsDir = options.reportsDir
+        ? (nodePath.isAbsolute(options.reportsDir) ? options.reportsDir : nodePath.resolve(options.projectRoot, options.reportsDir))
+        : nodePath.join(options.projectRoot, '.sharkcraft', 'reports');
+    const probes = PROBES[options.profileId] ?? [];
+    const gates = [];
+    const missingReports = [];
+    for (const p of probes) {
+        const file = nodePath.join(reportsDir, p.reportFile);
+        if (!existsSync(file)) {
+            missingReports.push(p.reportFile);
+            gates.push({
+                id: p.id,
+                title: p.title,
+                verdict: CiPredictVerdict.Unknown,
+                summary: 'report missing — run the command first',
+                nextCommand: p.nextCommand,
+            });
+            continue;
+        }
+        try {
+            const json = JSON.parse(readFileSync(file, 'utf8'));
+            const r = p.reader(json);
+            gates.push({
+                id: p.id,
+                title: p.title,
+                verdict: r.verdict,
+                summary: r.summary,
+                report: p.reportFile,
+                nextCommand: p.nextCommand,
+            });
+        }
+        catch (e) {
+            gates.push({
+                id: p.id,
+                title: p.title,
+                verdict: CiPredictVerdict.Unknown,
+                summary: `unable to parse: ${e.message}`,
+                nextCommand: p.nextCommand,
+            });
+        }
+    }
+    const verdict = gates.some((g) => g.verdict === CiPredictVerdict.Fail)
+        ? CiPredictVerdict.Fail
+        : gates.some((g) => g.verdict === CiPredictVerdict.Warn)
+            ? CiPredictVerdict.Warn
+            : gates.every((g) => g.verdict === CiPredictVerdict.Pass)
+                ? CiPredictVerdict.Pass
+                : CiPredictVerdict.Unknown;
+    const nextCommands = [];
+    for (const g of gates) {
+        if ((g.verdict === CiPredictVerdict.Fail || g.verdict === CiPredictVerdict.Unknown) && g.nextCommand) {
+            nextCommands.push(g.nextCommand);
+        }
+    }
+    // Uncertainty model.
+    let confidence = 'high';
+    const reasons = [];
+    const missing = [];
+    const conflicting = [];
+    if (missingReports.length > 0) {
+        confidence = 'low';
+        reasons.push(`${missingReports.length} cached report(s) missing — verdict for those gates is unknown.`);
+        for (const r of missingReports)
+            missing.push({ id: 'missing-report', message: `${r} not cached.` });
+    }
+    else if (gates.some((g) => g.verdict === CiPredictVerdict.Unknown)) {
+        confidence = 'medium';
+        reasons.push('At least one gate could not be evaluated.');
+        for (const g of gates) {
+            if (g.verdict === CiPredictVerdict.Unknown) {
+                conflicting.push({ id: g.id, message: g.summary });
+            }
+        }
+    }
+    else if (gates.some((g) => g.verdict === CiPredictVerdict.Warn)) {
+        confidence = 'medium';
+        reasons.push('At least one gate is in warn state.');
+    }
+    else if (gates.length === 0) {
+        confidence = 'unknown';
+        reasons.push('No probes defined for this profile.');
+    }
+    // Build uncertainty.
+    const uncertainty = buildUncertaintyReport({
+        confidence,
+        reasons,
+        missingSignals: missing,
+        conflictingSignals: conflicting,
+        suggestedCommands: nextCommands.slice(0, 5),
+        safeFallbackCommand: missingReports.length > 0
+            ? `# Run the cached commands first: ${missingReports.join(', ')}`
+            : 'shrk doctor',
+        whatWouldIncreaseConfidence: missingReports.length > 0
+            ? ['Run the gate commands to populate cached reports.']
+            : [],
+    });
+    return {
+        schema: CI_PREDICT_SCHEMA,
+        profileId: options.profileId,
+        generatedAt: new Date().toISOString(),
+        verdict,
+        gates,
+        missingReports,
+        nextCommands,
+        uncertainty,
+    };
+}
+export function renderCiPredictText(report) {
+    const lines = [];
+    lines.push(`=== CI predict (${report.profileId}) ===`);
+    lines.push(`  generatedAt   ${report.generatedAt}`);
+    lines.push(`  verdict       ${report.verdict.toUpperCase()}`);
+    lines.push(`  gates         ${report.gates.length}`);
+    lines.push(`  missing       ${report.missingReports.length}`);
+    lines.push('');
+    for (const g of report.gates) {
+        lines.push(`  ${g.verdict.padEnd(7)} ${g.id.padEnd(28)} ${g.title}  (${g.summary})`);
+        if (g.nextCommand && (g.verdict === 'fail' || g.verdict === 'unknown')) {
+            lines.push(`           next: ${g.nextCommand}`);
+        }
+    }
+    if (report.nextCommands.length > 0) {
+        lines.push('\nNext commands:');
+        for (const c of report.nextCommands)
+            lines.push(`  • ${c}`);
+    }
+    return lines.join('\n') + '\n';
+}
+export function renderCiPredictMarkdown(report) {
+    const lines = ['# CI predict', ''];
+    lines.push(`- profile: \`${report.profileId}\``);
+    lines.push(`- verdict: **${report.verdict.toUpperCase()}**`);
+    lines.push('');
+    lines.push('| Verdict | Gate | Summary | Next |');
+    lines.push('| --- | --- | --- | --- |');
+    for (const g of report.gates) {
+        lines.push(`| ${g.verdict} | \`${g.id}\` | ${g.summary} | ${g.nextCommand ?? ''} |`);
+    }
+    if (report.missingReports.length > 0) {
+        lines.push('');
+        lines.push(`## Missing reports`);
+        for (const r of report.missingReports)
+            lines.push(`- \`${r}\``);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/ci-scaffold.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Deterministic GitHub Actions scaffolds for SharkCraft. The CLI commands
+ * stay dry-run by default; this module only renders YAML strings.
+ *
+ * Two surfaces:
+ *  - `renderQualityCiWorkflow` — selectable gates (quality / policy / impact
+ *    / review / report-site / bundle-replay / node-compat).
+ *  - `renderBundleReplayWorkflow` — scheduled cross-bundle replay job.
+ */
+export declare const CI_SCAFFOLD_SCHEMA = "sharkcraft.ci-scaffold/v1";
+export interface ICiScaffoldOptions {
+    withQuality?: boolean;
+    withPolicy?: boolean;
+    withImpact?: boolean;
+    withReview?: boolean;
+    withReportSite?: boolean;
+    withBundleReplay?: boolean;
+    withNodeCompat?: boolean;
+    /** Include a `shrk release readiness` gate step. */
+    withReleaseReadiness?: boolean;
+    bunVersion?: string;
+    name?: string;
+}
+export type BundleReplaySchedule = 'weekly' | 'daily' | 'manual';
+export interface IBundleReplayScaffoldOptions {
+    schedule?: BundleReplaySchedule;
+    withReportSite?: boolean;
+    name?: string;
+    bunVersion?: string;
+}
+export interface ICiProviderScaffoldExtras {
+    withPolicySnapshotGate?: boolean;
+    /** Include a `shrk release readiness` gate step. */
+    withReleaseReadiness?: boolean;
+}
+export declare function renderQualityCiWorkflow(options?: ICiScaffoldOptions): string;
+export type CiProvider = 'github-actions' | 'gitlab' | 'bitbucket';
+export interface ICiProviderScaffoldOptions extends ICiScaffoldOptions, ICiProviderScaffoldExtras {
+}
+export declare function renderGitlabCiWorkflow(options?: ICiProviderScaffoldOptions): string;
+export declare function renderBitbucketCiWorkflow(options?: ICiProviderScaffoldOptions): string;
+export declare function renderCiWorkflow(provider: CiProvider, options?: ICiProviderScaffoldOptions): string;
+export declare function defaultCiOutputPath(provider: CiProvider | 'jenkins' | 'azure'): string;
+export declare function renderJenkinsCiWorkflow(options?: ICiProviderScaffoldOptions): string;
+export declare function renderAzureCiWorkflow(options?: ICiProviderScaffoldOptions): string;
+export declare function renderBundleReplayWorkflow(options?: IBundleReplayScaffoldOptions): string;
+//# sourceMappingURL=ci-scaffold.d.ts.map

package/dist/ci-scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-scaffold.d.ts","sourceRoot":"","sources":["../src/ci-scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAwBD,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,CA2DhF;AAQD,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEnE,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB,EAAE,yBAAyB;CAAG;AAEpG,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CAmHvF;AAED,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CAoH1F;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAIR;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAMtF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CAkGxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CA4ItF;AAED,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,4BAAiC,GACzC,MAAM,CAoCR"}