sneakoscope 7.3.0 → 7.6.0

package/dist/core/triwiki/context-graph/extractors/topology/globs.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const TOPOLOGY_EXCLUDED_DIR_NAMES = new Set([
+    '.git',
+    '.cache',
+    '.claude',
+    '.next',
+    '.sneakoscope',
+    '.turbo',
+    '.venv',
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+    'target',
+    'tmp',
+    'vendor'
+]);
+const MAX_WALK_DEPTH = 24;
+export function buildFileInventory(root, maxFiles) {
+    const limit = Number.isFinite(maxFiles) && maxFiles > 0 ? Math.trunc(maxFiles) : 0;
+    const files = [];
+    let truncated = false;
+    const walk = (absoluteDir, relativeDir, depth) => {
+        if (truncated || depth > MAX_WALK_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(absoluteDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+        for (const entry of entries) {
+            if (truncated)
+                return;
+            const name = entry.name;
+            if (!name || name === '.' || name === '..' || name === '.DS_Store')
+                continue;
+            if (TOPOLOGY_EXCLUDED_DIR_NAMES.has(name))
+                continue;
+            if (entry.isSymbolicLink())
+                continue;
+            const relative = relativeDir ? `${relativeDir}/${name}` : name;
+            if (entry.isDirectory()) {
+                walk(path.join(absoluteDir, name), relative, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (files.length >= limit) {
+                truncated = true;
+                return;
+            }
+            files.push(relative);
+        }
+    };
+    walk(path.resolve(root), '', 0);
+    files.sort();
+    return { files, set: new Set(files), truncated };
+}
+export function isGlobPattern(value) {
+    return value.includes('*') || value.includes('?');
+}
+const regexCache = new Map();
+const REGEX_CACHE_LIMIT = 512;
+const REGEX_SPECIAL = /[.+^${}()|[\]\\]/;
+export function globToRegExp(glob) {
+    const cached = regexCache.get(glob);
+    if (cached)
+        return cached;
+    let body = '';
+    for (let index = 0; index < glob.length; index += 1) {
+        const char = glob[index] ?? '';
+        if (char === '*') {
+            if (glob[index + 1] === '*') {
+                index += 1;
+                if (glob[index + 1] === '/') {
+                    index += 1;
+                    body += '(?:.*/)?';
+                }
+                else {
+                    body += '.*';
+                }
+                continue;
+            }
+            body += '[^/]*';
+            continue;
+        }
+        if (char === '?') {
+            body += '[^/]';
+            continue;
+        }
+        body += REGEX_SPECIAL.test(char) ? `\\${char}` : char;
+    }
+    const compiled = new RegExp(`^${body}$`);
+    if (regexCache.size >= REGEX_CACHE_LIMIT)
+        regexCache.clear();
+    regexCache.set(glob, compiled);
+    return compiled;
+}
+export function expandGlob(inventory, pattern, cap) {
+    const raw = String(pattern ?? '').trim();
+    if (!raw)
+        return { matches: [], total: 0, capped: false };
+    if (!isGlobPattern(raw)) {
+        const hit = inventory.set.has(raw);
+        return { matches: hit ? [raw] : [], total: hit ? 1 : 0, capped: false };
+    }
+    const expression = globToRegExp(raw);
+    const matches = [];
+    let total = 0;
+    for (const file of inventory.files) {
+        if (!expression.test(file))
+            continue;
+        total += 1;
+        if (total <= cap)
+            matches.push(file);
+    }
+    if (total > cap)
+        return { matches: [], total, capped: true };
+    return { matches, total, capped: false };
+}

package/dist/core/triwiki/context-graph/extractors/topology/index.js

@@ -0,0 +1,92 @@
+import { emptyContextGraphFragment } from '../../contracts.js';
+import { compareContextGraphIds } from '../../ids.js';
+import { buildCommandGraph, collectRuntimeManifest } from './commands.js';
+import { buildGateAffectedEdges, buildGateDependencyEdges, buildGatePresetPipelines, buildGateVerificationEdges, reportUnbackedProtectedGates } from './gate-edges.js';
+import { buildGateNodes, collectTopologyGates } from './gates.js';
+import { buildFileInventory } from './globs.js';
+import { buildRouteGraph } from './routes.js';
+import { TOPOLOGY_EXTRACTOR_ID, TOPOLOGY_EXTRACTOR_REVISION, createTopologyContext, recordSkip, topologyExpired } from './shared.js';
+const INVENTORY_SKIP_PATH = 'release-gates.v2.json';
+function sortIssues(issues) {
+    return [...issues].sort((left, right) => {
+        const byCode = left.code.localeCompare(right.code);
+        if (byCode !== 0)
+            return byCode;
+        return left.message.localeCompare(right.message);
+    });
+}
+function sortSkips(skips) {
+    return [...skips].sort((left, right) => {
+        const byPath = left.path.localeCompare(right.path);
+        if (byPath !== 0)
+            return byPath;
+        const byReason = left.reason.localeCompare(right.reason);
+        if (byReason !== 0)
+            return byReason;
+        return String(left.detail ?? '').localeCompare(String(right.detail ?? ''));
+    });
+}
+function sortedHashes(hashes) {
+    const out = {};
+    for (const key of Object.keys(hashes).sort()) {
+        const value = hashes[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function finalize(ctx) {
+    const fragment = emptyContextGraphFragment(TOPOLOGY_EXTRACTOR_ID, TOPOLOGY_EXTRACTOR_REVISION);
+    fragment.nodes = [...ctx.nodes.values()].sort((left, right) => compareContextGraphIds(left.id, right.id));
+    fragment.edges = [...ctx.edges.values()].sort((left, right) => compareContextGraphIds(left.id, right.id));
+    fragment.issues = sortIssues(ctx.issues);
+    fragment.skipped = sortSkips(ctx.skipped);
+    fragment.inputHashes = sortedHashes(ctx.inputHashes);
+    return fragment;
+}
+export class TopologyGraphExtractor {
+    id = TOPOLOGY_EXTRACTOR_ID;
+    revision = TOPOLOGY_EXTRACTOR_REVISION;
+    async extract(input) {
+        const startedAt = Date.now();
+        const files = buildFileInventory(input.root, input.limits.maxFiles);
+        const ctx = createTopologyContext({
+            root: input.root,
+            observedAt: input.observedAt,
+            limits: input.limits,
+            files,
+            startedAt
+        });
+        if (files.truncated) {
+            recordSkip(ctx, INVENTORY_SKIP_PATH, 'cap_reached', `file inventory stopped at ${input.limits.maxFiles} files`);
+        }
+        const runtime = collectRuntimeManifest(ctx);
+        const gates = collectTopologyGates(ctx);
+        buildGateNodes(ctx, gates);
+        buildGateDependencyEdges(ctx, gates);
+        let presets = [];
+        if (topologyExpired(ctx)) {
+            recordSkip(ctx, INVENTORY_SKIP_PATH, 'cap_reached', 'extraction time budget reached before gate file relations');
+        }
+        else {
+            const verified = buildGateVerificationEdges(ctx, gates);
+            const affected = buildGateAffectedEdges(ctx, gates);
+            reportUnbackedProtectedGates(ctx, gates, verified, affected);
+            presets = buildGatePresetPipelines(ctx, gates);
+        }
+        if (topologyExpired(ctx)) {
+            recordSkip(ctx, INVENTORY_SKIP_PATH, 'cap_reached', 'extraction time budget reached before command topology');
+            return finalize(ctx);
+        }
+        buildCommandGraph(ctx, runtime, presets);
+        buildRouteGraph(ctx);
+        return finalize(ctx);
+    }
+}
+export function createTopologyGraphExtractor() {
+    return new TopologyGraphExtractor();
+}
+export { TOPOLOGY_EXTRACTOR_ID, TOPOLOGY_EXTRACTOR_REVISION } from './shared.js';
+export { TOPOLOGY_GATE_MANIFESTS } from './gates.js';
+export { TOPOLOGY_COMMAND_MANIFEST_PATH, TOPOLOGY_RUNTIME_SCRIPTS_PATH } from './commands.js';
+export { TOPOLOGY_ROUTES_PATH } from './routes.js';

package/dist/core/triwiki/context-graph/extractors/topology/routes.js

@@ -0,0 +1,135 @@
+import { ROUTES } from '../../../../routes.js';
+import { contextGraphNodeId } from '../../ids.js';
+import { canonicalCommandName, commandNodeIdFor } from './commands.js';
+import { addEdge, addNode, asRecord, estimateTokenCost, isCanonicalId, mapIdentifierLines, readStringArrayField, readStringField, readWorkspaceText, recordSkip, topologyLintError } from './shared.js';
+export const TOPOLOGY_ROUTES_PATH = 'src/core/routes.ts';
+const ROUTE_ID_LINE = /^\s*id:\s*'([^']+)'/;
+const CLI_VERB = /^sks\s+([a-z][a-z0-9-]*)/;
+export function routeCliCommandName(cliEntrypoint) {
+    const match = CLI_VERB.exec(String(cliEntrypoint ?? '').trim());
+    const verb = match?.[1];
+    return verb ? canonicalCommandName(verb) : null;
+}
+export function buildRouteGraph(ctx) {
+    const read = readWorkspaceText(ctx, TOPOLOGY_ROUTES_PATH);
+    if (!read)
+        return;
+    const lines = mapIdentifierLines(read.text, ROUTE_ID_LINE);
+    const entries = ROUTES;
+    if (!entries.length) {
+        topologyLintError(ctx, 'invalid_node_field', `${TOPOLOGY_ROUTES_PATH} declares no routes`, { path: TOPOLOGY_ROUTES_PATH });
+        return;
+    }
+    for (const raw of entries) {
+        const route = asRecord(raw);
+        if (!route) {
+            topologyLintError(ctx, 'invalid_node_field', `${TOPOLOGY_ROUTES_PATH} contains a non-object route`, {
+                path: TOPOLOGY_ROUTES_PATH
+            });
+            continue;
+        }
+        const id = readStringField(route, 'id').trim();
+        if (!id) {
+            topologyLintError(ctx, 'invalid_node_field', `${TOPOLOGY_ROUTES_PATH} contains a route with no id`, {
+                path: TOPOLOGY_ROUTES_PATH
+            });
+            continue;
+        }
+        const routeNodeId = contextGraphNodeId({ kind: 'route', name: id });
+        if (!isCanonicalId('route', id, routeNodeId)) {
+            topologyLintError(ctx, 'invalid_node_field', `route "${id}" is not a canonical route id`, { path: TOPOLOGY_ROUTES_PATH });
+            continue;
+        }
+        const line = lines.get(id);
+        const lifecycle = readStringArrayField(route, 'lifecycle');
+        const routeLabel = readStringField(route, 'route') || id;
+        const stopGate = readStringField(route, 'stopGate');
+        const codexAppOnly = route.codexAppOnly === true;
+        const cliEntrypoint = readStringField(route, 'cliEntrypoint');
+        const routeMetadata = {
+            source: 'routes',
+            routeId: id,
+            command: readStringField(route, 'command'),
+            mode: readStringField(route, 'mode'),
+            routeName: routeLabel,
+            stopGate,
+            context7Policy: readStringField(route, 'context7Policy'),
+            reasoningPolicy: readStringField(route, 'reasoningPolicy'),
+            requiredSkills: readStringArrayField(route, 'requiredSkills'),
+            dollarAliases: readStringArrayField(route, 'dollarAliases'),
+            hidden: route.hidden === true,
+            codexAppOnly,
+            cliEntrypointDeclared: Boolean(cliEntrypoint)
+        };
+        const routeAdded = addNode(ctx, {
+            id: routeNodeId,
+            kind: 'route',
+            label: id,
+            path: TOPOLOGY_ROUTES_PATH,
+            line,
+            contentHash: read.hash,
+            trust: 0.9,
+            risk: route.mutatesRouteState === true ? 'high' : 'medium',
+            tokenCost: estimateTokenCost([id, routeLabel, lifecycle.join(' ')]),
+            metadata: routeMetadata,
+            sourcePath: TOPOLOGY_ROUTES_PATH
+        });
+        if (!routeAdded)
+            continue;
+        if (!lifecycle.length) {
+            recordSkip(ctx, TOPOLOGY_ROUTES_PATH, 'excluded', `route ${id} declares no lifecycle pipeline`);
+            continue;
+        }
+        const pipelineNodeId = contextGraphNodeId({ kind: 'pipeline', pipelineId: `route:${id}` });
+        const pipelineMetadata = {
+            source: 'routes',
+            pipelineKind: 'route_lifecycle',
+            routeId: id,
+            stages: lifecycle,
+            stageCount: lifecycle.length,
+            stopGate,
+            codexAppOnly
+        };
+        const pipelineAdded = addNode(ctx, {
+            id: pipelineNodeId,
+            kind: 'pipeline',
+            label: routeLabel,
+            path: TOPOLOGY_ROUTES_PATH,
+            line,
+            contentHash: read.hash,
+            trust: 0.9,
+            risk: 'medium',
+            tokenCost: estimateTokenCost([routeLabel, lifecycle.join(' ')]),
+            metadata: pipelineMetadata,
+            sourcePath: TOPOLOGY_ROUTES_PATH
+        });
+        if (!pipelineAdded)
+            continue;
+        addEdge(ctx, {
+            from: routeNodeId,
+            to: pipelineNodeId,
+            type: 'routes_to',
+            confidence: 'manifest',
+            path: TOPOLOGY_ROUTES_PATH,
+            hash: read.hash,
+            line
+        });
+        if (codexAppOnly)
+            continue;
+        const commandName = routeCliCommandName(cliEntrypoint);
+        if (!commandName)
+            continue;
+        const commandId = commandNodeIdFor(commandName);
+        if (!ctx.nodes.has(commandId))
+            continue;
+        addEdge(ctx, {
+            from: commandId,
+            to: pipelineNodeId,
+            type: 'routes_to',
+            confidence: 'manifest',
+            path: TOPOLOGY_ROUTES_PATH,
+            hash: read.hash,
+            line
+        });
+    }
+}

package/dist/core/triwiki/context-graph/extractors/topology/shared.js

@@ -0,0 +1,215 @@
+import fs from 'node:fs';
+import { sha256 } from '../../../../fsx.js';
+import { lintError } from '../../contracts.js';
+import { contextGraphEdgeId, contextGraphNodeId } from '../../ids.js';
+import { ContextGraphPathError, isWorkspaceRelativePosixPath, resolveInsideWorkspace } from '../../paths.js';
+export const TOPOLOGY_EXTRACTOR_ID = 'topology';
+export const TOPOLOGY_EXTRACTOR_REVISION = '1.0.0';
+export const TOPOLOGY_GLOB_MATCH_CAP = 48;
+export const TOPOLOGY_GATE_AFFECTED_CAP = 96;
+export const TOPOLOGY_GATE_VERIFIED_CAP = 24;
+export function createTopologyContext(params) {
+    const timeout = Number.isFinite(params.limits.timeoutMs) && params.limits.timeoutMs > 0 ? params.limits.timeoutMs : 0;
+    return {
+        root: params.root,
+        observedAt: params.observedAt,
+        limits: params.limits,
+        deadline: params.startedAt + timeout,
+        files: params.files,
+        nodes: new Map(),
+        edges: new Map(),
+        issues: [],
+        skipped: [],
+        inputHashes: {},
+        fileClassification: new Map(),
+        skipKeys: new Set()
+    };
+}
+export function topologyExpired(ctx) {
+    return Date.now() > ctx.deadline;
+}
+export function estimateTokenCost(parts) {
+    let total = 0;
+    for (const part of parts)
+        total += part.length;
+    return Math.max(1, Math.ceil(total / 4));
+}
+export function recordSkip(ctx, skipPath, reason, detail) {
+    const key = `${skipPath}
${reason}
${detail ?? ''}`;
+    if (ctx.skipKeys.has(key))
+        return;
+    ctx.skipKeys.add(key);
+    ctx.skipped.push({ path: skipPath, reason, ...(detail === undefined ? {} : { detail }) });
+}
+export function topologyLintError(ctx, code, message, extra = {}) {
+    ctx.issues.push(lintError(code, message, { ...extra, extractor: TOPOLOGY_EXTRACTOR_ID }));
+}
+export function addNode(ctx, input) {
+    const existing = ctx.nodes.get(input.id);
+    if (existing) {
+        if (existing.kind !== input.kind) {
+            topologyLintError(ctx, 'duplicate_node_conflict', `node ${input.id} is claimed as both ${existing.kind} and ${input.kind}`, { nodeId: input.id, path: input.sourcePath });
+            return false;
+        }
+        return true;
+    }
+    if (ctx.nodes.size >= ctx.limits.maxNodes) {
+        recordSkip(ctx, input.sourcePath, 'cap_reached', 'node budget reached');
+        return false;
+    }
+    if (input.path !== undefined && !isWorkspaceRelativePosixPath(input.path)) {
+        topologyLintError(ctx, 'absolute_or_escaping_path', `node ${input.id} carries a non workspace-relative path`, {
+            nodeId: input.id,
+            path: input.sourcePath
+        });
+        return false;
+    }
+    ctx.nodes.set(input.id, {
+        id: input.id,
+        kind: input.kind,
+        label: input.label,
+        ...(input.path === undefined ? {} : { path: input.path }),
+        ...(input.line === undefined ? {} : { locator: { line: input.line } }),
+        ...(input.contentHash === undefined ? {} : { contentHash: input.contentHash }),
+        trust: input.trust,
+        freshness: 'fresh',
+        risk: input.risk,
+        tokenCost: input.tokenCost,
+        metadata: input.metadata
+    });
+    return true;
+}
+export function addEdge(ctx, input) {
+    if (!ctx.nodes.has(input.from) || !ctx.nodes.has(input.to)) {
+        topologyLintError(ctx, 'dangling_edge', `${input.type} edge ${input.from} -> ${input.to} has an unresolved endpoint`, { path: input.path });
+        return false;
+    }
+    if (!input.path || !input.hash || !isWorkspaceRelativePosixPath(input.path)) {
+        topologyLintError(ctx, 'edge_without_provenance', `${input.type} edge ${input.from} -> ${input.to} has no usable provenance`);
+        return false;
+    }
+    const id = contextGraphEdgeId({ from: input.from, to: input.to, type: input.type });
+    if (ctx.edges.has(id))
+        return true;
+    if (ctx.edges.size >= ctx.limits.maxEdges) {
+        recordSkip(ctx, input.path, 'cap_reached', 'edge budget reached');
+        return false;
+    }
+    ctx.edges.set(id, {
+        id,
+        from: input.from,
+        to: input.to,
+        type: input.type,
+        confidence: input.confidence,
+        provenance: {
+            path: input.path,
+            ...(input.line === undefined ? {} : { line: input.line }),
+            hash: input.hash,
+            extractor: TOPOLOGY_EXTRACTOR_ID
+        },
+        observedAt: ctx.observedAt
+    });
+    return true;
+}
+export function ensureFileNode(ctx, relativePath, role, sourcePath) {
+    if (!isWorkspaceRelativePosixPath(relativePath))
+        return null;
+    const id = contextGraphNodeId({ kind: 'file', path: relativePath });
+    const classification = ctx.fileClassification.get(relativePath);
+    const metadata = {
+        source: TOPOLOGY_EXTRACTOR_ID,
+        role,
+        ...(classification === undefined ? {} : { runtimeClassification: classification })
+    };
+    const added = addNode(ctx, {
+        id,
+        kind: 'file',
+        label: relativePath.slice(relativePath.lastIndexOf('/') + 1) || relativePath,
+        path: relativePath,
+        trust: 0.9,
+        risk: 'low',
+        tokenCost: estimateTokenCost([relativePath]),
+        metadata,
+        sourcePath
+    });
+    return added ? id : null;
+}
+export function readWorkspaceText(ctx, relativePath) {
+    let absolute = null;
+    try {
+        absolute = resolveInsideWorkspace(ctx.root, relativePath);
+    }
+    catch (error) {
+        if (error instanceof ContextGraphPathError) {
+            recordSkip(ctx, relativePath, 'symlink_escape', 'manifest resolves outside the workspace');
+            topologyLintError(ctx, 'symlink_escape', `${relativePath} resolves outside the workspace`, { path: relativePath });
+            return null;
+        }
+        throw error;
+    }
+    if (!absolute) {
+        recordSkip(ctx, relativePath, 'excluded', 'not present in this workspace');
+        return null;
+    }
+    try {
+        const stat = fs.statSync(absolute);
+        if (!stat.isFile()) {
+            recordSkip(ctx, relativePath, 'unreadable', 'not a regular file');
+            topologyLintError(ctx, 'invalid_node_field', `${relativePath} is not a regular file`, { path: relativePath });
+            return null;
+        }
+        if (stat.size > ctx.limits.maxFileBytes) {
+            recordSkip(ctx, relativePath, 'oversized', 'manifest exceeds the extraction byte limit');
+            topologyLintError(ctx, 'invalid_node_field', `${relativePath} exceeds the extraction byte limit`, { path: relativePath });
+            return null;
+        }
+        const buffer = fs.readFileSync(absolute);
+        const hash = sha256(buffer);
+        ctx.inputHashes[relativePath] = hash;
+        return { text: buffer.toString('utf8'), hash };
+    }
+    catch {
+        recordSkip(ctx, relativePath, 'unreadable', 'manifest could not be read');
+        topologyLintError(ctx, 'invalid_node_field', `${relativePath} could not be read`, { path: relativePath });
+        return null;
+    }
+}
+export function mapIdentifierLines(text, pattern) {
+    const out = new Map();
+    const lines = text.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line === undefined)
+            continue;
+        const match = pattern.exec(line);
+        const captured = match?.[1];
+        if (!captured || out.has(captured))
+            continue;
+        out.set(captured, index + 1);
+    }
+    return out;
+}
+export function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+export function readStringField(source, key) {
+    const value = source[key];
+    return typeof value === 'string' ? value : '';
+}
+export function readStringArrayField(source, key) {
+    const value = source[key];
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value)
+        if (typeof entry === 'string' && entry)
+            out.push(entry);
+    return out;
+}
+export function readNumberField(source, key) {
+    const value = source[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+export function isCanonicalId(prefix, rawId, generatedId) {
+    return generatedId === `${prefix}:${rawId}`;
+}