@shrkcrft/inspector 0.1.0-alpha.1

package/dist/project-coupling-audit.js

@@ -0,0 +1,282 @@
+/**
+ * Project-specific coupling audit.
+ *
+ * Scans the workspace for project-specific tokens (caller supplies them
+ * via deny patterns) and reports each occurrence with a recommended
+ * externalisation target. The engine ships no built-in tokens to keep
+ * itself generic.
+ *
+ * Read-only — never writes.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const PROJECT_COUPLING_AUDIT_SCHEMA = 'sharkcraft.project-coupling-audit/v1';
+export var CouplingExternalizationTarget;
+(function (CouplingExternalizationTarget) {
+    /**
+     * Engine-category hits live in engine source (`packages/`, `apps/`,
+     * `libs/`); the audit recommends externalising them to a pack
+     * contribution. `--fail-on engine` keys on this value specifically —
+     * the bucket name matches the current source location, not the
+     * recommended target.
+     */
+    CouplingExternalizationTarget["Engine"] = "engine";
+    CouplingExternalizationTarget["LocalConfig"] = "local-config";
+    CouplingExternalizationTarget["Profile"] = "profile";
+    CouplingExternalizationTarget["FixtureOnly"] = "fixture-only";
+    CouplingExternalizationTarget["DocsExample"] = "docs-example";
+    CouplingExternalizationTarget["FalsePositive"] = "false-positive";
+    CouplingExternalizationTarget["Unclassified"] = "unclassified";
+})(CouplingExternalizationTarget || (CouplingExternalizationTarget = {}));
+export var CouplingRiskLevel;
+(function (CouplingRiskLevel) {
+    CouplingRiskLevel["Low"] = "low";
+    CouplingRiskLevel["Medium"] = "medium";
+    CouplingRiskLevel["High"] = "high";
+})(CouplingRiskLevel || (CouplingRiskLevel = {}));
+const DEFAULT_SCAN_ROOTS = [
+    'packages',
+    'sharkcraft',
+    'apps',
+    'libs',
+    'examples',
+    'docs',
+];
+const DEFAULT_EXCLUDES = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.sharkcraft',
+    'tmp',
+    '.next',
+    '.cache',
+]);
+function isCodeOrDocFile(path) {
+    return /\.(ts|tsx|js|jsx|mts|mjs|cts|cjs|md|json|yaml|yml)$/i.test(path);
+}
+function walkFiles(dir, excludeRoots, out, maxFiles) {
+    if (out.length >= maxFiles)
+        return;
+    let dirents;
+    try {
+        dirents = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const ent of dirents) {
+        if (out.length >= maxFiles)
+            break;
+        const name = String(ent.name);
+        if (excludeRoots.has(name))
+            continue;
+        if (name.startsWith('.') && DEFAULT_EXCLUDES.has(name))
+            continue;
+        const full = nodePath.join(dir, name);
+        if (ent.isDirectory()) {
+            walkFiles(full, excludeRoots, out, maxFiles);
+        }
+        else if (ent.isFile() && isCodeOrDocFile(name)) {
+            out.push(full);
+        }
+    }
+}
+function classifyHit(file, _line, _token, insideIdentifier, wordBoundary) {
+    const lower = file.toLowerCase();
+    if (wordBoundary && insideIdentifier) {
+        return {
+            externalizationTarget: CouplingExternalizationTarget.FalsePositive,
+            risk: CouplingRiskLevel.Low,
+        };
+    }
+    if (lower.includes('__tests__/') || lower.includes('.test.') || lower.includes('.spec.')) {
+        return { externalizationTarget: CouplingExternalizationTarget.FixtureOnly, risk: CouplingRiskLevel.Low };
+    }
+    if (lower.includes('/docs/') || lower.endsWith('.md')) {
+        return { externalizationTarget: CouplingExternalizationTarget.DocsExample, risk: CouplingRiskLevel.Low };
+    }
+    if (lower.includes('/sharkcraft/')) {
+        return {
+            externalizationTarget: CouplingExternalizationTarget.LocalConfig,
+            risk: CouplingRiskLevel.Medium,
+            nextCommand: 'Move this self-config entry into the relevant pack or remove if project-specific.',
+        };
+    }
+    if (lower.includes('/packages/') || lower.includes('/apps/') || lower.includes('/libs/')) {
+        return {
+            externalizationTarget: CouplingExternalizationTarget.Engine,
+            risk: CouplingRiskLevel.High,
+            nextCommand: 'Move this project-specific behavior into a pack contribution (profile / contract / etc.).',
+        };
+    }
+    return { externalizationTarget: CouplingExternalizationTarget.Unclassified, risk: CouplingRiskLevel.Medium };
+}
+function isIdentifierChar(ch) {
+    if (!ch)
+        return false;
+    return /[A-Za-z0-9_]/.test(ch);
+}
+export function auditProjectCoupling(options) {
+    if (!options.tokens || options.tokens.length === 0) {
+        return {
+            schema: PROJECT_COUPLING_AUDIT_SCHEMA,
+            projectRoot: options.projectRoot,
+            tokens: [],
+            filesScanned: 0,
+            hits: [],
+            hitsByExternalizationTarget: {},
+            hitsByToken: {},
+            verdict: 'clean',
+            nextCommands: ['Provide --token <pattern> to scan for project-specific identifiers.'],
+        };
+    }
+    const excludeRoots = new Set(options.excludeRoots ?? []);
+    const scanRoots = options.scanRoots ?? DEFAULT_SCAN_ROOTS;
+    const maxFiles = options.maxFiles ?? 5000;
+    const files = [];
+    for (const rel of scanRoots) {
+        const abs = nodePath.join(options.projectRoot, rel);
+        try {
+            const s = statSync(abs);
+            if (s.isDirectory())
+                walkFiles(abs, new Set([...DEFAULT_EXCLUDES, ...excludeRoots]), files, maxFiles);
+        }
+        catch {
+            continue;
+        }
+    }
+    const wordBoundary = options.wordBoundary !== false;
+    const hits = [];
+    const tokenCounts = {};
+    const targetCounts = {};
+    for (const file of files) {
+        let content;
+        try {
+            content = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            for (const token of options.tokens) {
+                let from = 0;
+                while (from < line.length) {
+                    const idx = line.indexOf(token, from);
+                    if (idx === -1)
+                        break;
+                    const beforeCh = idx > 0 ? line[idx - 1] : undefined;
+                    const endIdx = idx + token.length;
+                    const afterCh = endIdx < line.length ? line[endIdx] : undefined;
+                    // "inside identifier" means the match is wedged between word chars on
+                    // both sides. A token that itself ends with a non-word char (a
+                    // delimiter-suffixed prefix like `XXX-`) only needs the leading-side
+                    // check.
+                    const tokenEndsInsideWord = isIdentifierChar(token[token.length - 1]);
+                    const tokenStartsInsideWord = isIdentifierChar(token[0]);
+                    const insideIdentifier = (tokenStartsInsideWord && isIdentifierChar(beforeCh)) ||
+                        (tokenEndsInsideWord && isIdentifierChar(afterCh));
+                    const cls = classifyHit(file, line, token, insideIdentifier, wordBoundary);
+                    const rel = nodePath.relative(options.projectRoot, file);
+                    hits.push({
+                        file: rel,
+                        line: i + 1,
+                        column: idx + 1,
+                        token,
+                        snippet: line.length > 200 ? line.slice(0, 200) + '…' : line,
+                        externalizationTarget: cls.externalizationTarget,
+                        risk: cls.risk,
+                        ...(cls.nextCommand ? { nextCommand: cls.nextCommand } : {}),
+                    });
+                    tokenCounts[token] = (tokenCounts[token] ?? 0) + 1;
+                    targetCounts[cls.externalizationTarget] = (targetCounts[cls.externalizationTarget] ?? 0) + 1;
+                    from = endIdx;
+                }
+            }
+        }
+    }
+    const blockingHits = hits.filter((h) => h.risk === CouplingRiskLevel.High &&
+        h.externalizationTarget !== CouplingExternalizationTarget.FixtureOnly &&
+        h.externalizationTarget !== CouplingExternalizationTarget.DocsExample &&
+        h.externalizationTarget !== CouplingExternalizationTarget.FalsePositive);
+    return {
+        schema: PROJECT_COUPLING_AUDIT_SCHEMA,
+        projectRoot: options.projectRoot,
+        tokens: options.tokens,
+        filesScanned: files.length,
+        hits,
+        hitsByExternalizationTarget: targetCounts,
+        hitsByToken: tokenCounts,
+        verdict: blockingHits.length === 0 ? 'clean' : 'has-coupling',
+        nextCommands: blockingHits.length === 0
+            ? ['Engine packages are clean for the provided tokens.']
+            : [
+                `Move ${blockingHits.length} high-risk hit(s) into pack contributions or config.`,
+                'See `shrk audit project-coupling plan` for the suggested extraction targets.',
+            ],
+    };
+}
+export function renderProjectCouplingAuditText(report) {
+    const lines = [];
+    lines.push(`=== Project-specific coupling audit ===`);
+    lines.push(`  projectRoot   ${report.projectRoot}`);
+    lines.push(`  tokens        ${report.tokens.join(', ') || '(none)'}`);
+    lines.push(`  filesScanned  ${report.filesScanned}`);
+    lines.push(`  hits          ${report.hits.length}`);
+    lines.push(`  verdict       ${report.verdict.toUpperCase()}`);
+    lines.push('');
+    if (report.hits.length === 0) {
+        lines.push('  (no occurrences of any provided token)');
+        return lines.join('\n') + '\n';
+    }
+    lines.push(`By token:`);
+    for (const [t, n] of Object.entries(report.hitsByToken))
+        lines.push(`  ${t.padEnd(24)} ${n}`);
+    lines.push('');
+    lines.push(`By externalization target:`);
+    for (const [t, n] of Object.entries(report.hitsByExternalizationTarget))
+        lines.push(`  ${t.padEnd(20)} ${n}`);
+    lines.push('');
+    lines.push(`Top hits (first 30):`);
+    for (const h of report.hits.slice(0, 30)) {
+        lines.push(`  ${h.file}:${h.line}:${h.column}  [${h.risk}] [${h.externalizationTarget}]  ${h.token}`);
+    }
+    lines.push('');
+    lines.push(`Next:`);
+    for (const c of report.nextCommands)
+        lines.push(`  • ${c}`);
+    return lines.join('\n') + '\n';
+}
+export function renderProjectCouplingAuditMarkdown(report) {
+    const lines = [];
+    lines.push(`# Project-specific coupling audit`);
+    lines.push('');
+    lines.push(`- projectRoot: \`${report.projectRoot}\``);
+    lines.push(`- tokens: ${report.tokens.map((t) => '`' + t + '`').join(', ') || '(none)'}`);
+    lines.push(`- filesScanned: ${report.filesScanned}`);
+    lines.push(`- hits: ${report.hits.length}`);
+    lines.push(`- verdict: **${report.verdict.toUpperCase()}**`);
+    lines.push('');
+    if (report.hits.length === 0) {
+        lines.push('No occurrences of any provided token. ✓');
+        return lines.join('\n') + '\n';
+    }
+    lines.push('## By token');
+    for (const [t, n] of Object.entries(report.hitsByToken))
+        lines.push(`- \`${t}\` — ${n}`);
+    lines.push('');
+    lines.push('## By externalisation target');
+    for (const [t, n] of Object.entries(report.hitsByExternalizationTarget))
+        lines.push(`- ${t} — ${n}`);
+    lines.push('');
+    lines.push('## Hits');
+    lines.push('| File | Line | Token | Risk | Target | Next |');
+    lines.push('| --- | --- | --- | --- | --- | --- |');
+    for (const h of report.hits.slice(0, 200)) {
+        lines.push(`| \`${h.file}\` | ${h.line} | \`${h.token}\` | ${h.risk} | ${h.externalizationTarget} | ${h.nextCommand ?? ''} |`);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/project-overview.d.ts

@@ -0,0 +1,14 @@
+import type { IWorkspaceSummary } from '@shrkcrft/workspace';
+export interface IProjectOverview {
+    projectName: string;
+    description?: string;
+    packageManager: string;
+    frameworks: string[];
+    hasTypeScript: boolean;
+    hasSharkcraftFolder: boolean;
+    topLevelDirs: string[];
+    knownScripts: string[];
+}
+export declare function buildProjectOverview(summary: IWorkspaceSummary, knowledgeProjectName?: string): IProjectOverview;
+export declare function renderOverviewText(overview: IProjectOverview): string;
+//# sourceMappingURL=project-overview.d.ts.map

package/dist/project-overview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-overview.d.ts","sourceRoot":"","sources":["../src/project-overview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,EAC1B,oBAAoB,CAAC,EAAE,MAAM,GAC5B,gBAAgB,CAWlB;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAYrE"}

package/dist/project-overview.js

@@ -0,0 +1,27 @@
+export function buildProjectOverview(summary, knowledgeProjectName) {
+    return {
+        projectName: knowledgeProjectName ?? summary.packageName ?? 'unknown-project',
+        description: summary.description,
+        packageManager: summary.packageManager.manager,
+        frameworks: summary.frameworks.map((f) => f.name),
+        hasTypeScript: summary.hasTypeScript,
+        hasSharkcraftFolder: summary.hasSharkcraftFolder,
+        topLevelDirs: summary.topLevelDirs,
+        knownScripts: Object.keys(summary.scripts),
+    };
+}
+export function renderOverviewText(overview) {
+    const lines = [];
+    lines.push(`Project: ${overview.projectName}`);
+    if (overview.description)
+        lines.push(`Description: ${overview.description}`);
+    lines.push(`Package manager: ${overview.packageManager}`);
+    if (overview.frameworks.length)
+        lines.push(`Frameworks: ${overview.frameworks.join(', ')}`);
+    lines.push(`TypeScript: ${overview.hasTypeScript ? 'yes' : 'no'}`);
+    lines.push(`SharkCraft folder: ${overview.hasSharkcraftFolder ? 'present' : 'missing'}`);
+    if (overview.knownScripts.length) {
+        lines.push(`Scripts: ${overview.knownScripts.slice(0, 12).join(', ')}`);
+    }
+    return lines.join('\n');
+}

package/dist/propose-knowledge.d.ts

@@ -0,0 +1,64 @@
+export declare const KNOWLEDGE_PROPOSE_SCHEMA = "sharkcraft.knowledge-propose/v1";
+export declare enum KnowledgeProposeSkipReason {
+    AlreadyCovered = "already-covered",
+    Excluded = "excluded",
+    UnsupportedKind = "unsupported-kind",
+    Default = "default-export-skipped",
+    NotSelected = "not-selected"
+}
+export interface IProposedReference {
+    kind: 'file' | 'symbol';
+    path?: string;
+    symbol?: string;
+    required?: boolean;
+}
+export interface IProposedKnowledgeEntry {
+    id: string;
+    title: string;
+    type: string;
+    priority: string;
+    scope: readonly string[];
+    tags: readonly string[];
+    appliesWhen: readonly string[];
+    summary: string;
+    content: string;
+    references: readonly IProposedReference[];
+    source: {
+        file: string;
+        line: number;
+        kind: string;
+    };
+}
+export interface IKnowledgeProposeSkip {
+    file: string;
+    symbol?: string;
+    reason: KnowledgeProposeSkipReason;
+    coveredByEntryId?: string;
+}
+export interface IKnowledgeProposeReport {
+    schema: typeof KNOWLEDGE_PROPOSE_SCHEMA;
+    proposals: readonly IProposedKnowledgeEntry[];
+    skipped: readonly IKnowledgeProposeSkip[];
+    scannedFiles: number;
+    totalExports: number;
+    /** When true, the scan was restricted to git-changed files. */
+    gitChangedOnly: boolean;
+    /** Ref used for git-changed scan, when applicable. */
+    since?: string;
+}
+export interface IKnowledgeProposeInput {
+    cwd: string;
+    /** Restrict scan to a single file (relative or absolute). */
+    path?: string;
+    /** Propose only for a single named symbol. */
+    symbol?: string;
+    /**
+     * When set, scan files changed relative to this ref.
+     * Ignored when `path` or `symbol` is set.
+     * Pass `null` to scan the whole workspace.
+     */
+    since?: string | null;
+}
+export declare function proposeKnowledge(input: IKnowledgeProposeInput): Promise<IKnowledgeProposeReport>;
+export declare function renderKnowledgeProposeMarkdown(report: IKnowledgeProposeReport): string;
+//# sourceMappingURL=propose-knowledge.d.ts.map

package/dist/propose-knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propose-knowledge.d.ts","sourceRoot":"","sources":["../src/propose-knowledge.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAE1E,oBAAY,0BAA0B;IACpC,cAAc,oBAAoB;IAClC,QAAQ,aAAa;IACrB,eAAe,qBAAqB;IACpC,OAAO,2BAA2B;IAClC,WAAW,iBAAiB;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC1C,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,0BAA0B,CAAC;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,wBAAwB,CAAC;IACxC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC9C,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,cAAc,EAAE,OAAO,CAAC;IACxB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AA0PD,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAqElC;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,uBAAuB,GAC9B,MAAM,CA6CR"}