peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/scan/libraries-service.d.ts

@@ -0,0 +1,24 @@
+import type { LibraryReport } from './libraries-types.js';
+export type ScanLibrariesOptions = {
+    projectRoot: string;
+};
+/**
+ * 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 declare function parseMajorVersion(spec: string): number | null;
+export declare function scanLibraries(options: ScanLibrariesOptions): Promise<LibraryReport>;

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

@@ -0,0 +1,419 @@
+import { readdir } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
+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/services/scan/libraries-types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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/services/scan/libraries-types.js

@@ -0,0 +1,9 @@
+/**
+ * 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/services/scan/orphan-service.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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;