peaks-loop 4.0.0-beta.6 → 4.0.0-beta.8

package/dist/src/services/scan/libraries-service.js

@@ -1,419 +0,0 @@
-import { readdir } from 'node:fs/promises';
-import { join, sep } from 'node:path';
-import { isDirectory, pathExists, readText } from '../../shared/fs.js';
-const SCOPES = [
-    'dependencies',
-    'devDependencies',
-    'peerDependencies',
-    'optionalDependencies'
-];
-const SCOPE_ORDER = {
-    dependencies: 0,
-    devDependencies: 1,
-    peerDependencies: 2,
-    optionalDependencies: 3
-};
-/**
- * Parse the major version from a semver-ish spec.
- *
- * Handles the common shapes:
- *   "^5.18.0"      → 5
- *   "~1.2.3"       → 1
- *   "1.2.3"        → 1
- *   ">=1.0.0"      → 1
- *   "5"            → 5
- *   "5.x"          → 5
- *
- * Returns null for non-semver specs that the LLM should not assume a
- * major for:
- *   "workspace:*"  → null
- *   "file:../..."   → null
- *   "git+https..." → null
- *   "npm:@scope/x@1" → 1 (alias spec, we extract what we can)
- */
-export function parseMajorVersion(spec) {
-    // Strip npm alias prefix "npm:" and take whatever comes after the LAST "@"
-    // (since alias specs are "npm:<name>@<version>")
-    let versionPart = spec;
-    if (versionPart.startsWith('npm:')) {
-        const atIdx = versionPart.lastIndexOf('@');
-        versionPart = atIdx >= 0 ? versionPart.slice(atIdx + 1) : versionPart.slice(4);
-    }
-    // Strip semver range operators (caret, tilde, comparison ops, exact)
-    versionPart = versionPart.replace(/^[\^~>=<]+\s*/, '').trim();
-    // Take the first numeric component
-    const match = /^(\d+)/.exec(versionPart);
-    if (!match)
-        return null;
-    const n = Number(match[1]);
-    return Number.isSafeInteger(n) ? n : null;
-}
-async function readPackageJson(packageJsonPath) {
-    if (!(await pathExists(packageJsonPath))) {
-        return { exists: false, record: null };
-    }
-    try {
-        const raw = await readText(packageJsonPath);
-        const record = JSON.parse(raw);
-        return { exists: true, record };
-    }
-    catch (error) {
-        return { exists: true, record: null, error: error.message };
-    }
-}
-/**
- * Hand-rolled YAML parser for `pnpm-workspace.yaml`.
- *
- * Only consumes the top-level `packages:` list. Ignores all other top-level
- * keys (`allowBuilds:`, `catalog:`, etc.) and indented blocks. Returns
- * `null` when the file is present but does not contain a `packages:`
- * list — callers should fall through to the next detection source.
- *
- * Supports the common shapes:
- *   packages:
- *     - 'packages/*'
- *     - "apps/web"
- *     - tools
- *     - packages/hermes-agent/*
- */
-function parsePnpmWorkspaceYaml(content) {
-    const lines = content.split(/\r?\n/);
-    let inPackagesList = false;
-    let packagesIndent = -1;
-    const result = [];
-    for (const rawLine of lines) {
-        // Strip comments (anything after # not inside quotes — close enough for our use)
-        const commentIdx = rawLine.indexOf('#');
-        const line = (commentIdx >= 0 ? rawLine.slice(0, commentIdx) : rawLine).replace(/\s+$/, '');
-        if (line.length === 0)
-            continue;
-        if (!inPackagesList) {
-            // Looking for the top-level `packages:` key.
-            const match = /^packages:\s*$/.exec(line);
-            if (match) {
-                inPackagesList = true;
-            }
-            continue;
-        }
-        // Inside the packages list. Items must be more indented than the key.
-        const indent = line.match(/^\s*/)?.[0].length ?? 0;
-        if (packagesIndent < 0) {
-            // First non-empty line after the key — this sets the indent.
-            if (indent === 0) {
-                // `packages:` was the last meaningful line; an unindented line
-                // means the list is empty or the format is unsupported.
-                break;
-            }
-            packagesIndent = indent;
-        }
-        else if (indent < packagesIndent) {
-            // Outdented — the list ended.
-            break;
-        }
-        else if (indent > packagesIndent) {
-            // Nested list (e.g. `packages: [{ ... }]`) — unsupported; stop.
-            break;
-        }
-        // Expect `- <value>` or `- '<value>'` or `- "<value>"`.
-        const itemMatch = /^\s*-\s+(['"]?)(.+?)\1\s*$/.exec(line);
-        if (itemMatch && itemMatch[2] !== undefined) {
-            result.push(itemMatch[2]);
-        }
-        else {
-            // Not a list item; the block ended.
-            break;
-        }
-    }
-    return result;
-}
-function extractNpmWorkspaces(value) {
-    if (Array.isArray(value))
-        return value;
-    if (value && typeof value === 'object' && Array.isArray(value.packages)) {
-        return value.packages;
-    }
-    return null;
-}
-/**
- * Discover workspace `package.json` paths from the supported monorepo
- * manifest sources. Returns the list of absolute paths plus which
- * detection source won. When no source is present, returns an empty
- * list with `source: null` (caller should fall through to single-package
- * behavior).
- */
-async function discoverWorkspacePackageJsons(projectRoot, warnings) {
-    // 1. pnpm-workspace.yaml
-    const pnpmWsPath = join(projectRoot, 'pnpm-workspace.yaml');
-    if (await pathExists(pnpmWsPath)) {
-        try {
-            const yaml = await readText(pnpmWsPath);
-            const globs = parsePnpmWorkspaceYaml(yaml);
-            if (globs && globs.length > 0) {
-                const paths = await expandWorkspaceGlobs(projectRoot, globs, warnings);
-                return { paths, source: 'pnpm-workspace' };
-            }
-        }
-        catch (error) {
-            warnings.push(`pnpm-workspace.yaml present but unreadable: ${error.message}`);
-        }
-    }
-    // 2. package.json `workspaces` field (npm or yarn classic).
-    const rootPkgPath = join(projectRoot, 'package.json');
-    if (await pathExists(rootPkgPath)) {
-        const { record } = await readPackageJson(rootPkgPath);
-        if (record) {
-            const globs = extractNpmWorkspaces(record.workspaces);
-            if (globs && globs.length > 0) {
-                const paths = await expandWorkspaceGlobs(projectRoot, globs, warnings);
-                return { paths, source: 'package-json-workspaces' };
-            }
-        }
-    }
-    // 3. lerna.json `packages` field.
-    const lernaPath = join(projectRoot, 'lerna.json');
-    if (await pathExists(lernaPath)) {
-        try {
-            const lernaRaw = await readText(lernaPath);
-            const lerna = JSON.parse(lernaRaw);
-            if (Array.isArray(lerna.packages) && lerna.packages.every((p) => typeof p === 'string')) {
-                const paths = await expandWorkspaceGlobs(projectRoot, lerna.packages, warnings);
-                return { paths, source: 'lerna' };
-            }
-        }
-        catch (error) {
-            warnings.push(`lerna.json present but unreadable: ${error.message}`);
-        }
-    }
-    return { paths: [], source: null };
-}
-/**
- * Resolve a list of workspace globs against the project tree.
- *
- * Supports shapes with up to two segments of `*` wildcards:
- *   - `packages/*`
- *   - `packages/hermes-agent/*`
- *   - `apps/web` (literal, no wildcard)
- *
- * Deeper patterns (more than one `*` segment) are silently skipped and a
- * warning is emitted. This is by design (no new dependency, narrow scope).
- */
-async function expandWorkspaceGlobs(projectRoot, globs, warnings) {
-    const found = new Set();
-    for (const glob of globs) {
-        const segments = glob.split('/').filter((s) => s.length > 0);
-        const wildcardCount = segments.filter((s) => s === '*').length;
-        if (wildcardCount > 1) {
-            warnings.push(`workspace glob "${glob}" has more than one wildcard; skipped (unsupported).`);
-            continue;
-        }
-        if (segments.length === 0)
-            continue;
-        if (wildcardCount === 0) {
-            // Literal path — treat the last segment as a directory containing package.json.
-            const literalDir = join(projectRoot, ...segments);
-            if (await isDirectory(literalDir)) {
-                const candidate = join(literalDir, 'package.json');
-                if (await pathExists(candidate)) {
-                    found.add(candidate);
-                }
-            }
-            continue;
-        }
-        // Exactly one wildcard — it must be the LAST segment.
-        const wildcardIdx = segments.indexOf('*');
-        if (wildcardIdx !== segments.length - 1) {
-            warnings.push(`workspace glob "${glob}" has non-trailing wildcard; skipped.`);
-            continue;
-        }
-        const parentSegments = segments.slice(0, wildcardIdx);
-        const parentDir = join(projectRoot, ...parentSegments);
-        if (!(await isDirectory(parentDir)))
-            continue;
-        let entries;
-        try {
-            entries = await readdir(parentDir, { withFileTypes: true });
-        }
-        catch (error) {
-            warnings.push(`workspace glob "${glob}": could not read ${parentDir}: ${error.message}`);
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            const childPkg = join(parentDir, entry.name, 'package.json');
-            if (await pathExists(childPkg)) {
-                found.add(childPkg);
-            }
-        }
-    }
-    return Array.from(found).sort();
-}
-/**
- * Parse a single `package.json` record into `LibraryEntry` rows.
- * Returns the entries and the per-scope tallies for that one package.
- */
-function extractEntriesFromPackageJson(record) {
-    const byScope = {
-        dependencies: 0,
-        devDependencies: 0,
-        peerDependencies: 0,
-        optionalDependencies: 0
-    };
-    const entries = [];
-    for (const scope of SCOPES) {
-        const deps = record[scope];
-        if (!deps)
-            continue;
-        for (const [name, version] of Object.entries(deps)) {
-            entries.push({
-                name,
-                version,
-                major: parseMajorVersion(version),
-                scope,
-                ecosystem: 'npm'
-            });
-            byScope[scope] += 1;
-        }
-    }
-    return { entries, byScope };
-}
-export async function scanLibraries(options) {
-    const { projectRoot } = options;
-    const warnings = [];
-    const libraries = [];
-    const byScope = {
-        dependencies: 0,
-        devDependencies: 0,
-        peerDependencies: 0,
-        optionalDependencies: 0
-    };
-    const workspaces = [];
-    // 1. Discover monorepo workspaces (if any). Discovery is independent of
-    //    whether the root `package.json` exists; we still attempt it.
-    const { paths: workspacePkgPaths, source } = await discoverWorkspacePackageJsons(projectRoot, warnings);
-    const isMonorepo = source !== null && workspacePkgPaths.length > 0;
-    if (isMonorepo) {
-        // Monorepo mode: scan the root + every discovered workspace package.json.
-        const rootPkgPath = join(projectRoot, 'package.json');
-        const allPaths = [];
-        if (await pathExists(rootPkgPath)) {
-            allPaths.push(rootPkgPath);
-        }
-        // Dedupe: the root might also be matched by a glob (rare, but possible).
-        for (const p of workspacePkgPaths) {
-            if (!allPaths.includes(p))
-                allPaths.push(p);
-        }
-        // Recursive descent: for each discovered workspace dir, also pick up
-        // any nested `package.json` one level deeper. This matches the pnpm
-        // convention where a workspace package (e.g. `hermes-agent`) can be
-        // a container for sub-workspaces (e.g. `hermes-agent/ui-tui`). The
-        // outer pnpm-workspace.yaml often only declares the top-level glob,
-        // so a literal-glob-only scan would miss the nested packages.
-        const expanded = new Set(allPaths);
-        for (const pkgPath of allPaths) {
-            const dir = pkgPath.replace(/[\\/]package\.json$/, '');
-            if (!(await isDirectory(dir)))
-                continue;
-            let entries;
-            try {
-                entries = await readdir(dir, { withFileTypes: true });
-            }
-            catch {
-                continue;
-            }
-            for (const entry of entries) {
-                if (!entry.isDirectory())
-                    continue;
-                const nestedPkg = join(dir, entry.name, 'package.json');
-                if (await pathExists(nestedPkg)) {
-                    expanded.add(nestedPkg);
-                }
-            }
-        }
-        allPaths.length = 0;
-        allPaths.push(...Array.from(expanded).sort());
-        for (const pkgPath of allPaths) {
-            const { exists, record, error } = await readPackageJson(pkgPath);
-            if (!exists)
-                continue;
-            if (record === null) {
-                warnings.push(`${normalizePathForDisplay(pkgPath)} is not valid JSON: ${error ?? 'unknown parse error'}`);
-                continue;
-            }
-            const { entries, byScope: pkgByScope } = extractEntriesFromPackageJson(record);
-            libraries.push(...entries);
-            for (const scope of SCOPES) {
-                byScope[scope] += pkgByScope[scope];
-            }
-            // For per-workspace `workspaces[]`, only list non-root paths; the
-            // root is implicit and lives at `projectRoot`.
-            const isRoot = pkgPath === rootPkgPath;
-            if (!isRoot) {
-                const entry = {
-                    path: pkgPath,
-                    count: entries.length
-                };
-                if (record.name !== undefined)
-                    entry.name = record.name;
-                if (record.version !== undefined)
-                    entry.version = record.version;
-                workspaces.push(entry);
-            }
-        }
-    }
-    else {
-        // Single-package mode (today's behavior). Preserved byte-for-byte
-        // apart from the new additive `workspaces: []` field.
-        const { exists, record, error } = await readPackageJson(join(projectRoot, 'package.json'));
-        if (!exists) {
-            warnings.push('package.json not found; nothing to scan.');
-            return {
-                projectRoot,
-                libraries,
-                totalCount: 0,
-                byScope,
-                workspaces: [],
-                scannedAt: new Date().toISOString(),
-                warnings
-            };
-        }
-        if (record === null) {
-            warnings.push(`package.json is not valid JSON: ${error ?? 'unknown parse error'}`);
-            return {
-                projectRoot,
-                libraries,
-                totalCount: 0,
-                byScope,
-                workspaces: [],
-                scannedAt: new Date().toISOString(),
-                warnings
-            };
-        }
-        const { entries, byScope: pkgByScope } = extractEntriesFromPackageJson(record);
-        libraries.push(...entries);
-        for (const scope of SCOPES) {
-            byScope[scope] += pkgByScope[scope];
-        }
-    }
-    // Sort: by name (alphabetical), then by scope order (deps first, then dev, peer, optional)
-    libraries.sort((a, b) => {
-        if (a.name !== b.name)
-            return a.name.localeCompare(b.name);
-        return SCOPE_ORDER[a.scope] - SCOPE_ORDER[b.scope];
-    });
-    return {
-        projectRoot,
-        libraries,
-        totalCount: libraries.length,
-        byScope,
-        workspaces,
-        scannedAt: new Date().toISOString(),
-        warnings
-    };
-}
-function normalizePathForDisplay(p) {
-    // Surface posix-style separators in warnings for consistency with the
-    // existing 'package.json is not valid JSON' message shape.
-    return p.split(sep).join('/');
-}

package/dist/src/services/scan/libraries-types.d.ts

@@ -1,59 +0,0 @@
-/**
- * Library version scan types.
- * Joins the existing scan family (archetype, existing-system, type-sanity,
- * acceptance-coverage, diff-vs-scope, file-size) but is intentionally scoped
- * to library version enumeration only. Does NOT extend scan-types.ts —
- * each scan service ships its own types to keep the scan-types module
- * focused on the archetype + existing-system pair (see src/services/scan/scan-types.ts).
- */
-export type Ecosystem = 'npm';
-export type DependencyScope = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
-export type LibraryEntry = {
-    /** npm package name (e.g. "antd", "@mui/material", "react-router-dom"). */
-    name: string;
-    /** Raw version spec as written in package.json (e.g. "^5.18.0", "workspace:*", "git+https://..."). */
-    version: string;
-    /**
-     * Parsed major version, or null when the spec is non-semver (e.g.
-     * "workspace:*", "file:../local", "git+https://..."). The LLM should
-     * treat null as "cannot determine major; consult breaking-changes table
-     * by other signals (e.g. lockfile or import statement shape)".
-     */
-    major: number | null;
-    scope: DependencyScope;
-    ecosystem: Ecosystem;
-};
-/**
- * Per-workspace provenance for monorepo scans.
- *
- * `path` is the absolute path of the `package.json` that contributed
- * libraries. `count` is the number of `LibraryEntry` rows produced by
- * reading that single `package.json` (i.e. NOT the aggregate across
- * the whole monorepo — use `LibraryReport.totalCount` for the aggregate).
- *
- * `name` and `version` are the workspace's own `name` / `version` from
- * its `package.json`, when present. They are optional because some
- * workspace `package.json` files omit them.
- */
-export type WorkspaceEntry = {
-    path: string;
-    count: number;
-    name?: string;
-    version?: string;
-};
-export type LibraryReport = {
-    projectRoot: string;
-    libraries: LibraryEntry[];
-    totalCount: number;
-    byScope: Record<DependencyScope, number>;
-    /**
-     * Per-workspace provenance for monorepo (pnpm / npm / yarn workspaces,
-     * lerna) projects. Empty for single-package projects so the field is
-     * always present (additive; consumers can rely on the shape).
-     */
-    workspaces: WorkspaceEntry[];
-    /** ISO timestamp at scan time. */
-    scannedAt: string;
-    /** Soft signals — e.g. "package.json not found" or "package.json is not valid JSON". */
-    warnings: string[];
-};

package/dist/src/services/scan/libraries-types.js

@@ -1,9 +0,0 @@
-/**
- * Library version scan types.
- * Joins the existing scan family (archetype, existing-system, type-sanity,
- * acceptance-coverage, diff-vs-scope, file-size) but is intentionally scoped
- * to library version enumeration only. Does NOT extend scan-types.ts —
- * each scan service ships its own types to keep the scan-types module
- * focused on the archetype + existing-system pair (see src/services/scan/scan-types.ts).
- */
-export {};

package/dist/src/services/scan/orphan-service.d.ts

@@ -1,76 +0,0 @@
-/**
- * Orphan scan service (Slice 4/6 — karpathy-enforcement).
- *
- * Detects 4 kinds of orphans that RD/QA should clean up before merge:
- *  - exportOrphan:     declared export with no in-repo importer
- *  - importOrphan:     import whose source no longer exports the symbol
- *                     (working-tree vs HEAD diff focus)
- *  - cliSubcommandOrphan: `.command('x')` registered but never wired
- *                     into the group registration call
- *  - docEndpointOrphan: tech-doc declares an endpoint / subcommand
- *                     that the codebase does not implement
- *
- * Pattern follows `api-surface-service.ts` (readFile + readdir; pure
- * data shape; no AST parsing). karpathy §2: minimum code, no abstractions.
- */
-export type OrphanScope = 'working-tree' | 'git-diff' | 'all';
-export type OrphanScanOptions = {
-    projectRoot: string;
-    /** Limit the walk to changed files only (default: working-tree). */
-    scope?: OrphanScope;
-    /** Strict mode: report exportOrphans even outside the working tree. */
-    strict?: boolean;
-    /**
-     * Slice 2.6.1.A.4: git ref to diff against (default: HEAD).
-     * When supplied, `git diff --name-status <baseRef>` is used instead of
-     * the implicit `git diff --name-status HEAD`. Useful for branch-vs-main
-     * scans and for cross-branch orphan detection.
-     */
-    baseRef?: string;
-};
-export type ExportOrphan = {
-    name: string;
-    kind: 'function' | 'class' | 'const' | 'interface' | 'type' | 'enum';
-    sourceFile: string;
-    line: number;
-};
-export type ImportOrphan = {
-    importedFrom: string;
-    symbol: string;
-    importer: string;
-    line: number;
-};
-export type CliSubcommandOrphan = {
-    name: string;
-    sourceFile: string;
-    reason: string;
-};
-export type DocEndpointOrphan = {
-    endpoint: string;
-    declaredIn: string;
-};
-export type OrphanReport = {
-    projectRoot: string;
-    scannedAt: string;
-    scope: OrphanScope;
-    strict: boolean;
-    counts: {
-        export: number;
-        import: number;
-        cliSubcommand: number;
-        docEndpoint: number;
-    };
-    exportOrphans: ExportOrphan[];
-    importOrphans: ImportOrphan[];
-    cliSubcommandOrphans: CliSubcommandOrphan[];
-    docEndpointOrphans: DocEndpointOrphan[];
-    warnings: string[];
-};
-/**
- * Scan the project for orphan symbols. Read-only. Never throws;
- * failures surface as warnings in the report.
- */
-export declare function scanOrphans(options: OrphanScanOptions): Promise<OrphanReport>;
-export declare function formatOrphanMarkdown(report: OrphanReport, opts?: {
-    maxPerKind?: number;
-}): string;