gitlumen-screen-sdk 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# gitlumen-screen-sdk
+
+JavaScript SDK for screening public GitHub repositories and pull requests with GitLumen heuristic analysis.
+
+## Install
+
+```bash
+npm install gitlumen-screen-sdk
+```
+
+For local development from sibling folder:
+
+```bash
+npm install ../gitlumen-screen-sdk
+```
+
+## Quick Start
+
+```js
+import { GitLumenScreenSDK } from 'gitlumen-screen-sdk';
+
+const sdk = new GitLumenScreenSDK({
+  githubToken: process.env.GITHUB_TOKEN,
+  dataDir: '.gitlumen-screen-sdk'
+});
+
+const report = await sdk.screenRepository(
+  {
+    repoUrl: 'https://github.com/owner/repo',
+    scope: 'standard'
+  },
+  'compact'
+);
+
+console.log(report);
+```
+
+## API
+
+### new GitLumenScreenSDK(options)
+
+Options:
+- githubToken: optional GitHub token
+- dataDir: local directory for report storage
+- maxFileBytes: max file bytes fetched from raw GitHub file content
+- githubApiBase: override GitHub API base URL
+- rawBase: override raw content base URL
+- userAgent: custom user agent string
+
+### screenRepository(input, output)
+
+- input.repoUrl: required, repository or PR URL
+- input.scope: quick | standard | deep
+- input.branch: optional branch/ref
+- input.maxFiles: optional cap for downloaded files
+- output: compact | markdown | json
+
+Returns:
+- compact: reduced JSON object
+- markdown: markdown string
+- json: full report object
+
+### getReviewReport(reportId, output)
+
+Read previously generated report by id.
+
+### listReviewReports(limit)
+
+List stored reports from local data directory.
+
+### getRepositoryStructure(input)
+
+Get tree structure summary without generating a full report.
+
+## Low-level exports
+
+The package also exports:
+- GitLumenService
+- GitHubClient
+- ReportStore
+- reportCompact
+- formatReportOutput
+
+## Requirements
+
+- Node.js 20+

package/examples/basic-usage.js

@@ -0,0 +1,16 @@
+import { GitLumenScreenSDK } from '../src/index.js';
+
+const sdk = new GitLumenScreenSDK({
+  // githubToken: process.env.GITHUB_TOKEN,
+  dataDir: '.gitlumen-screen-sdk'
+});
+
+const result = await sdk.screenRepository(
+  {
+    repoUrl: 'https://github.com/modelcontextprotocol/typescript-sdk',
+    scope: 'quick'
+  },
+  'compact'
+);
+
+console.log(result);

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "gitlumen-screen-sdk",
+  "version": "0.1.0",
+  "description": "JavaScript SDK for GitLumen repository and pull request screening.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": [
+    "gitlumen",
+    "github",
+    "screening",
+    "sdk",
+    "risk-analysis"
+  ],
+  "author": "GitLumen",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "example": "node ./examples/basic-usage.js"
+  }
+}

package/src/config.js

@@ -0,0 +1,20 @@
+import path from 'node:path';
+
+export function createConfig(overrides = {}) {
+  return {
+    githubToken: overrides.githubToken ?? process.env.GITHUB_TOKEN ?? '',
+    dataDir: overrides.dataDir ?? path.resolve(process.cwd(), process.env.GITLUMEN_SCREEN_DATA_DIR || '.gitlumen-screen-sdk'),
+    maxFileBytes: overrides.maxFileBytes ?? Number.parseInt(process.env.GITLUMEN_MAX_FILE_BYTES || '120000', 10),
+    githubApiBase: overrides.githubApiBase ?? 'https://api.github.com',
+    rawBase: overrides.rawBase ?? 'https://raw.githubusercontent.com',
+    userAgent: overrides.userAgent ?? 'gitlumen-screen-sdk/0.1.0'
+  };
+}
+
+export const DEFAULT_LIMITS = {
+  maxTreeEntries: 2500,
+  quickMaxFiles: 40,
+  standardMaxFiles: 90,
+  deepMaxFiles: 180,
+  maxPrFiles: 300
+};

package/src/formatters.js

@@ -0,0 +1,21 @@
+import { truncateText } from './utils/text.js';
+
+export function reportCompact(report) {
+  return {
+    reportId: report.reportId,
+    generatedAt: report.generatedAt,
+    target: report.target,
+    risk: report.risk,
+    summary: report.summary,
+    findings: report.findings.slice(0, 20),
+    decisionQuestions: report.decisionQuestions,
+    recommendations: report.recommendations,
+    markdown: truncateText(report.markdown, 12000)
+  };
+}
+
+export function formatReportOutput(report, output = 'compact') {
+  if (output === 'markdown') return report.markdown;
+  if (output === 'json') return report;
+  return reportCompact(report);
+}

package/src/index.js

@@ -0,0 +1,62 @@
+import { GitLumenService } from './services/gitlumen.js';
+import { GitHubClient } from './services/github.js';
+import { ReportStore } from './services/reportStore.js';
+import { formatReportOutput, reportCompact } from './formatters.js';
+
+export class GitLumenScreenSDK {
+  constructor(options = {}) {
+    const githubOptions = {
+      token: options.githubToken,
+      dataDir: options.dataDir,
+      maxFileBytes: options.maxFileBytes,
+      githubApiBase: options.githubApiBase,
+      rawBase: options.rawBase,
+      userAgent: options.userAgent
+    };
+
+    const storeOptions = {
+      dataDir: options.dataDir,
+      config: {
+        dataDir: options.dataDir
+      }
+    };
+
+    this.service = options.service || new GitLumenService({
+      githubClient: options.githubClient,
+      store: options.store,
+      githubOptions,
+      storeOptions
+    });
+  }
+
+  async screenRepository(input, output = 'compact') {
+    const report = await this.service.screenRepository(input);
+    return formatReportOutput(report, output);
+  }
+
+  async getReviewReport(reportId, output = 'compact') {
+    const report = await this.service.getReport(reportId);
+    return formatReportOutput(report, output);
+  }
+
+  async listReviewReports(limit = 20) {
+    return this.service.listReports(limit);
+  }
+
+  async getRepositoryStructure(input) {
+    return this.service.getRepositoryStructure(input);
+  }
+}
+
+export async function screenRepository(input, options = {}) {
+  const sdk = new GitLumenScreenSDK(options);
+  return sdk.screenRepository(input, options.output || 'compact');
+}
+
+export {
+  GitLumenService,
+  GitHubClient,
+  ReportStore,
+  reportCompact,
+  formatReportOutput
+};

package/src/services/analyzer.js

@@ -0,0 +1,589 @@
+import { CategoryNames, SeverityWeights } from '../types.js';
+import { createReportId, stableHash } from '../utils/ids.js';
+import { unique } from '../utils/text.js';
+
+function normalizePath(path) {
+  return path.toLowerCase().replace(/\\/g, '/');
+}
+
+function ext(path) {
+  const lower = normalizePath(path);
+  const idx = lower.lastIndexOf('.');
+  return idx >= 0 ? lower.slice(idx) : '';
+}
+
+function base(path) {
+  return normalizePath(path).split('/').pop();
+}
+
+function hasPath(paths, matcher) {
+  return paths.some((p) => matcher(normalizePath(p)));
+}
+
+function countBy(paths, matcher) {
+  return paths.filter((p) => matcher(normalizePath(p))).length;
+}
+
+function findPackageJson(snapshot) {
+  return snapshot.files.find((file) => base(file.path) === 'package.json');
+}
+
+function parseJsonSafe(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function addFinding(findings, { category, severity = 'medium', title, evidence = [], recommendation, file, confidence = 'medium' }) {
+  findings.push({
+    id: `glf_${stableHash(`${category}|${severity}|${title}|${file || ''}`, 10)}`,
+    category,
+    severity,
+    title,
+    evidence: evidence.filter(Boolean).slice(0, 6),
+    recommendation,
+    file: file || null,
+    confidence
+  });
+}
+
+function detectLanguages(paths) {
+  const counts = new Map();
+  const map = {
+    '.js': 'JavaScript', '.jsx': 'JavaScript', '.mjs': 'JavaScript', '.cjs': 'JavaScript',
+    '.ts': 'TypeScript', '.tsx': 'TypeScript',
+    '.py': 'Python', '.go': 'Go', '.rs': 'Rust', '.java': 'Java', '.kt': 'Kotlin',
+    '.rb': 'Ruby', '.php': 'PHP', '.cs': 'C#', '.sol': 'Solidity', '.vy': 'Vyper',
+    '.sh': 'Shell', '.tf': 'Terraform', '.yaml': 'YAML', '.yml': 'YAML'
+  };
+  for (const path of paths) {
+    const lang = map[ext(path)];
+    if (lang) counts.set(lang, (counts.get(lang) || 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([language, count]) => ({ language, count }));
+}
+
+function detectFrameworks(snapshot, packageJson) {
+  const paths = snapshot.tree.map((entry) => normalizePath(entry.path));
+  const deps = packageJson ? {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies,
+    ...packageJson.peerDependencies
+  } : {};
+  const names = new Set(Object.keys(deps || {}));
+  const frameworks = [];
+
+  if (names.has('next') || hasPath(paths, (p) => p.includes('next.config'))) frameworks.push('Next.js');
+  if (names.has('react')) frameworks.push('React');
+  if (names.has('vite') || hasPath(paths, (p) => p.includes('vite.config'))) frameworks.push('Vite');
+  if (names.has('express')) frameworks.push('Express');
+  if (names.has('fastify')) frameworks.push('Fastify');
+  if (names.has('hardhat') || hasPath(paths, (p) => p.includes('hardhat.config'))) frameworks.push('Hardhat');
+  if (hasPath(paths, (p) => p === 'foundry.toml')) frameworks.push('Foundry');
+  if (hasPath(paths, (p) => p === 'go.mod')) frameworks.push('Go modules');
+  if (hasPath(paths, (p) => p === 'pyproject.toml')) frameworks.push('Python/pyproject');
+  if (hasPath(paths, (p) => p === 'dockerfile' || p.endsWith('/dockerfile'))) frameworks.push('Docker');
+  if (hasPath(paths, (p) => p.includes('.github/workflows/'))) frameworks.push('GitHub Actions');
+
+  return unique(frameworks);
+}
+
+function analyzeStructure(snapshot, findings) {
+  const paths = snapshot.tree.map((entry) => normalizePath(entry.path));
+  const fileCount = snapshot.tree.filter((entry) => entry.type === 'blob').length;
+  const dirCount = snapshot.tree.filter((entry) => entry.type === 'tree').length;
+
+  const hasReadme = hasPath(paths, (p) => base(p) === 'readme.md' || base(p) === 'readme');
+  const hasLicense = hasPath(paths, (p) => base(p) === 'license' || base(p).startsWith('license.'));
+  const hasEnvExample = hasPath(paths, (p) => ['.env.example', '.env.sample', '.env.template'].includes(base(p)));
+  const hasCI = hasPath(paths, (p) => p.startsWith('.github/workflows/') || p.includes('/.github/workflows/'));
+  const hasDocker = hasPath(paths, (p) => base(p) === 'dockerfile' || base(p) === 'docker-compose.yml' || base(p) === 'compose.yml');
+  const hasTests = hasPath(paths, (p) => p.includes('/test/') || p.includes('/tests/') || p.includes('/__tests__/') || p.endsWith('.test.js') || p.endsWith('.spec.js') || p.endsWith('.test.ts') || p.endsWith('.spec.ts') || p.endsWith('_test.go') || p.endsWith('_test.py'));
+
+  if (!hasReadme) {
+    addFinding(findings, {
+      category: 'maintainability', severity: 'medium', title: 'README not detected',
+      evidence: ['No README file found in the repository root tree.'],
+      recommendation: 'Add a README that explains project purpose, setup, environment variables, run commands, and review surface.'
+    });
+  }
+
+  if (!hasLicense) {
+    addFinding(findings, {
+      category: 'maintainability', severity: 'low', title: 'License file not detected',
+      evidence: ['No LICENSE file found in the repository root tree.'],
+      recommendation: 'Add a license file so repository usage and contribution terms are clear.'
+    });
+  }
+
+  if (!hasEnvExample && snapshot.files.some((f) => /process\.env|import\.meta\.env|os\.environ|getenv\(/.test(f.content))) {
+    addFinding(findings, {
+      category: 'operations', severity: 'medium', title: 'Environment variables used without an env template',
+      evidence: ['Code uses environment variables, but .env.example/.env.sample was not detected.'],
+      recommendation: 'Add .env.example with variable names only and no real secrets.'
+    });
+  }
+
+  if (!hasCI) {
+    addFinding(findings, {
+      category: 'operations', severity: 'medium', title: 'CI workflow not detected',
+      evidence: ['No .github/workflows directory found in the analyzed tree.'],
+      recommendation: 'Add a minimal CI pipeline for lint, test, build, and dependency/security checks.'
+    });
+  }
+
+  if (!hasTests) {
+    addFinding(findings, {
+      category: 'tests', severity: 'high', title: 'Test surface not detected',
+      evidence: ['No common test folders/files were found, such as tests/, __tests__, *.spec.ts, *.test.ts, or *_test.go.'],
+      recommendation: 'Add unit tests for core logic and integration tests for key endpoints/tools.'
+    });
+  }
+
+  if (fileCount > 1200 && snapshot.limits.treeTruncated) {
+    addFinding(findings, {
+      category: 'architecture', severity: 'medium', title: 'Large repository with truncated tree during screening',
+      evidence: [`Tree returned ${snapshot.limits.treeEntriesReturned} entries; the original tree is likely larger.`],
+      recommendation: 'Use deep scope or PR-based screening to focus review on changed files.'
+    });
+  }
+
+  return { hasReadme, hasLicense, hasEnvExample, hasCI, hasDocker, hasTests, fileCount, dirCount };
+}
+
+function analyzePackageJson(snapshot, findings, packageJsonFile) {
+  if (!packageJsonFile) return { packageManager: null, scripts: {}, dependencies: {} };
+  const pkg = parseJsonSafe(packageJsonFile.content);
+  if (!pkg) {
+    addFinding(findings, {
+      category: 'maintainability', severity: 'medium', title: 'package.json is not valid JSON',
+      evidence: [`File: ${packageJsonFile.path}`],
+      recommendation: 'Fix package.json so dependency/build tooling can process it safely.',
+      file: packageJsonFile.path
+    });
+    return { packageManager: null, scripts: {}, dependencies: {} };
+  }
+
+  const paths = snapshot.tree.map((entry) => normalizePath(entry.path));
+  const hasLock = hasPath(paths, (p) => ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb'].includes(base(p)));
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const scripts = pkg.scripts || {};
+
+  if (!hasLock && Object.keys(deps).length > 0) {
+    addFinding(findings, {
+      category: 'dependencies', severity: 'medium', title: 'Dependency lockfile not detected',
+      evidence: ['package.json declares dependencies, but no npm/pnpm/yarn/bun lockfile was found.'],
+      recommendation: 'Commit a lockfile to make installs reproducible and reduce supply-chain risk.',
+      file: packageJsonFile.path
+    });
+  }
+
+  for (const [scriptName, command] of Object.entries(scripts)) {
+    if (/preinstall|postinstall|prepare/.test(scriptName) && /(curl|wget|node|bash|sh|python|powershell)/i.test(command)) {
+      addFinding(findings, {
+        category: 'dependencies', severity: 'high', title: `Risky lifecycle script: ${scriptName}`,
+        evidence: [`${scriptName}: ${String(command).slice(0, 180)}`],
+        recommendation: 'Review lifecycle scripts. Avoid downloading/executing scripts at install time unless strictly necessary.',
+        file: packageJsonFile.path
+      });
+    }
+  }
+
+  const riskyPackages = ['request', 'node-sass', 'event-stream', 'colors', 'faker'];
+  const riskyFound = riskyPackages.filter((name) => deps[name]);
+  if (riskyFound.length) {
+    addFinding(findings, {
+      category: 'dependencies', severity: 'medium', title: 'Dependencies requiring manual review detected',
+      evidence: riskyFound.map((name) => `${name}@${deps[name]}`),
+      recommendation: 'Verify dependency status, maintainer activity, and modern alternatives. Run npm audit/pnpm audit.',
+      file: packageJsonFile.path
+    });
+  }
+
+  const directSecrets = ['dotenv'].filter((name) => deps[name]);
+  if (directSecrets.length && !snapshot.tree.some((entry) => ['.env.example', '.env.sample'].includes(base(entry.path)))) {
+    addFinding(findings, {
+      category: 'operations', severity: 'low', title: 'dotenv used without an env sample',
+      evidence: [`Dependency: ${directSecrets.join(', ')}`],
+      recommendation: 'Add .env.example and environment variable documentation.',
+      file: packageJsonFile.path
+    });
+  }
+
+  return {
+    packageManager: hasPath(paths, (p) => base(p) === 'pnpm-lock.yaml') ? 'pnpm' : hasPath(paths, (p) => base(p) === 'yarn.lock') ? 'yarn' : hasPath(paths, (p) => base(p) === 'bun.lockb') ? 'bun' : 'npm',
+    scripts,
+    dependencies: deps,
+    packageName: pkg.name || null,
+    packageVersion: pkg.version || null
+  };
+}
+
+function analyzeCodeContent(snapshot, findings) {
+  const secretPatterns = [
+    { name: 'Private key', regex: /-----BEGIN (RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/i, severity: 'critical' },
+    { name: 'GitHub token', regex: /gh[pousr]_[A-Za-z0-9_]{20,}/, severity: 'critical' },
+    { name: 'AWS access key', regex: /AKIA[0-9A-Z]{16}/, severity: 'critical' },
+    { name: 'Generic secret assignment', regex: /(api[_-]?key|secret|password|private[_-]?key)\s*[:=]\s*['"][^'"\n]{16,}['"]/i, severity: 'high' }
+  ];
+
+  for (const file of snapshot.files) {
+    const content = file.content || '';
+    const lowerPath = normalizePath(file.path);
+
+    for (const pattern of secretPatterns) {
+      if (pattern.regex.test(content) && !lowerPath.includes('.env.example') && !lowerPath.includes('.env.sample')) {
+        addFinding(findings, {
+          category: 'security', severity: pattern.severity, title: `Potential hardcoded secret: ${pattern.name}`,
+          evidence: [`Pattern detected in ${file.path}. Secret value is intentionally not shown.`],
+          recommendation: 'Rotate the secret if valid, remove it from git history, and use a secret manager/environment variables.',
+          file: file.path,
+          confidence: pattern.name === 'Generic secret assignment' ? 'medium' : 'high'
+        });
+      }
+    }
+
+    if (/\beval\s*\(|new Function\s*\(/.test(content)) {
+      addFinding(findings, {
+        category: 'security', severity: 'high', title: 'Dynamic code execution detected',
+        evidence: ['Contains eval() or new Function().'],
+        recommendation: 'Avoid dynamic code execution. Use explicit parsers/validators.',
+        file: file.path
+      });
+    }
+
+    if (/child_process|exec\s*\(|execSync\s*\(|spawn\s*\(/.test(content) && /req\.|request|params|query|body|argv/.test(content)) {
+      addFinding(findings, {
+        category: 'security', severity: 'high', title: 'Command execution potentially influenced by user input',
+        evidence: ['child_process/exec/spawn is present along with request/argv input references in the same file.'],
+        recommendation: 'Validate argument allowlists, use execFile/spawn with argument arrays, and avoid shell interpolation.',
+        file: file.path,
+        confidence: 'medium'
+      });
+    }
+
+    if (/(md5|sha1)\s*\(/i.test(content) && /(password|token|secret|hash)/i.test(content)) {
+      addFinding(findings, {
+        category: 'security', severity: 'medium', title: 'Weak hash algorithm near secret/password context',
+        evidence: ['MD5/SHA1 found in a password/token/secret/hash context.'],
+        recommendation: 'Use bcrypt/argon2 for passwords, and SHA-256/HMAC for integrity where appropriate.',
+        file: file.path
+      });
+    }
+
+    if (/(SELECT|INSERT|UPDATE|DELETE)\s+.*\$\{|`.*(SELECT|INSERT|UPDATE|DELETE)/is.test(content) && /(req\.|params|query|body)/.test(content)) {
+      addFinding(findings, {
+        category: 'security', severity: 'high', title: 'Possible SQL query string interpolation',
+        evidence: ['SQL statements and template interpolation/request input appear in the same file.'],
+        recommendation: 'Use parameterized queries/ORM query builders and validate inputs.',
+        file: file.path,
+        confidence: 'medium'
+      });
+    }
+
+    if (/dangerouslySetInnerHTML/.test(content)) {
+      addFinding(findings, {
+        category: 'security', severity: 'medium', title: 'dangerouslySetInnerHTML detected',
+        evidence: ['React dangerouslySetInnerHTML is used.'],
+        recommendation: 'Ensure HTML is sanitized with a trusted library and does not come directly from untrusted user input.',
+        file: file.path
+      });
+    }
+
+    if (lowerPath.includes('.github/workflows/') && /pull_request_target/.test(content)) {
+      addFinding(findings, {
+        category: 'operations', severity: 'high', title: 'GitHub Actions uses pull_request_target',
+        evidence: ['pull_request_target can be dangerous if checkout/head code is not properly isolated.'],
+        recommendation: 'Audit permissions and token scopes, and avoid running untrusted PR code with privileged tokens.',
+        file: file.path
+      });
+    }
+
+    if (lowerPath.includes('.github/workflows/') && /uses:\s+[^@\s]+\/[^@\s]+@(main|master|latest|v\d+)/i.test(content)) {
+      addFinding(findings, {
+        category: 'dependencies', severity: 'medium', title: 'GitHub Action not pinned to a commit SHA',
+        evidence: ['Workflow uses action tags/branches instead of immutable commit SHAs.'],
+        recommendation: 'Pin third-party GitHub Actions to commit SHAs to reduce supply-chain risk.',
+        file: file.path
+      });
+    }
+
+    if (base(file.path) === 'dockerfile') {
+      if (/curl .*\|\s*(sh|bash)|wget .*\|\s*(sh|bash)/i.test(content)) {
+        addFinding(findings, {
+          category: 'operations', severity: 'high', title: 'Dockerfile executes remote scripts directly',
+          evidence: ['Detected curl/wget piped directly to a shell.'],
+          recommendation: 'Download artifacts with verified checksum/signature and avoid piping directly to shell.',
+          file: file.path
+        });
+      }
+      if (!/\nUSER\s+[^\s#]+/.test(`\n${content}`)) {
+        addFinding(findings, {
+          category: 'operations', severity: 'medium', title: 'Dockerfile does not set a non-root USER',
+          evidence: ['No USER instruction detected.'],
+          recommendation: 'Add a non-root user for runtime containers.',
+          file: file.path
+        });
+      }
+    }
+  }
+}
+
+function analyzePullRequest(snapshot, findings) {
+  if (snapshot.mode !== 'pull_request' || !snapshot.pullRequest) return null;
+  const pr = snapshot.pullRequest;
+  if (pr.changedFiles > 40 || pr.additions + pr.deletions > 2500) {
+    addFinding(findings, {
+      category: 'architecture', severity: 'high', title: 'PR is too large for safe review',
+      evidence: [`Changed files: ${pr.changedFiles}`, `Additions: ${pr.additions}`, `Deletions: ${pr.deletions}`],
+      recommendation: 'Split the PR into reviewable chunks or require targeted reviewers per domain.'
+    });
+  }
+
+  const removedTests = snapshot.files.some((file) => normalizePath(file.path).includes('test') && file.status === 'removed');
+  if (removedTests) {
+    addFinding(findings, {
+      category: 'tests', severity: 'high', title: 'PR removes test files',
+      evidence: ['A changed file under test/spec paths has status removed.'],
+      recommendation: 'Ensure replacement tests exist or explain why test removal is safe.'
+    });
+  }
+
+  return {
+    changedFiles: pr.changedFiles,
+    additions: pr.additions,
+    deletions: pr.deletions,
+    churn: pr.additions + pr.deletions
+  };
+}
+
+function computeRisk(findings) {
+  const categoryScores = Object.fromEntries(CategoryNames.map((category) => [category, 0]));
+  let total = 0;
+
+  for (const finding of findings) {
+    const weight = SeverityWeights[finding.severity] || 0;
+    total += weight;
+    categoryScores[finding.category] = Math.min(100, (categoryScores[finding.category] || 0) + weight * 1.6);
+  }
+
+  const cappedTotal = Math.min(100, Math.round(total));
+  let level = 'low';
+  let mergeReadiness = 'ready_with_standard_review';
+  if (cappedTotal >= 75) {
+    level = 'critical';
+    mergeReadiness = 'blocked_until_remediation';
+  } else if (cappedTotal >= 50) {
+    level = 'high';
+    mergeReadiness = 'needs_senior_review';
+  } else if (cappedTotal >= 25) {
+    level = 'medium';
+    mergeReadiness = 'review_required';
+  }
+
+  return {
+    score: cappedTotal,
+    level,
+    mergeReadiness,
+    categoryScores: Object.fromEntries(Object.entries(categoryScores).map(([k, v]) => [k, Math.round(Math.min(100, v))]))
+  };
+}
+
+function buildChapters({ snapshot, findings, signals, packageInfo, frameworks, languages, risk }) {
+  const topFindings = findings.slice().sort((a, b) => (SeverityWeights[b.severity] || 0) - (SeverityWeights[a.severity] || 0)).slice(0, 8);
+  const chapterList = [
+    {
+      title: 'Repository / PR Context',
+      summary: snapshot.mode === 'pull_request'
+        ? `Screening PR #${snapshot.pullRequest.number}: ${snapshot.pullRequest.title}`
+        : `Screening repository ${snapshot.owner}/${snapshot.repo} at ref ${snapshot.ref}`,
+      bullets: [
+        `Mode: ${snapshot.mode}`,
+        `Primary language: ${snapshot.language || languages[0]?.language || 'unknown'}`,
+        `Downloaded files: ${snapshot.limits.filesDownloaded}`,
+        `Tree entries: ${snapshot.limits.treeEntriesReturned}${snapshot.limits.treeTruncated ? ' (truncated)' : ''}`
+      ]
+    },
+    {
+      title: 'Risk Map',
+      summary: `Overall risk is ${risk.level.toUpperCase()} with score ${risk.score}/100. Merge readiness: ${risk.mergeReadiness}.`,
+      bullets: Object.entries(risk.categoryScores).map(([category, score]) => `${category}: ${score}/100`)
+    },
+    {
+      title: 'Architecture & Surface',
+      summary: frameworks.length ? `Detected framework/surface: ${frameworks.join(', ')}` : 'Primary framework is not clear from the analyzed files.',
+      bullets: [
+        `Files: ${signals.fileCount}`,
+        `Directories: ${signals.dirCount}`,
+        `Package manager: ${packageInfo.packageManager || 'not detected'}`,
+        `Languages: ${languages.slice(0, 6).map((l) => `${l.language}(${l.count})`).join(', ') || 'unknown'}`
+      ]
+    },
+    {
+      title: 'Top Findings',
+      summary: topFindings.length ? 'Review these findings first.' : 'No significant findings were detected by the heuristic pass.',
+      bullets: topFindings.length ? topFindings.map((f) => `[${f.severity}] ${f.title}${f.file ? ` — ${f.file}` : ''}`) : ['Continue with manual review for business logic and edge cases.']
+    },
+    {
+      title: 'Suggested Reviewer Questions',
+      summary: 'These questions help reviewers decide merge readiness.',
+      bullets: buildDecisionQuestions({ snapshot, findings, risk })
+    }
+  ];
+
+  return chapterList;
+}
+
+function buildDecisionQuestions({ snapshot, findings, risk }) {
+  const questions = [];
+  if (risk.level === 'critical' || risk.level === 'high') {
+    questions.push('Which high/critical findings must be resolved before merge, and who owns each one?');
+  }
+  if (findings.some((f) => f.category === 'security')) {
+    questions.push('Have all user inputs, secrets, tokens, and permission boundaries been validated?');
+  }
+  if (findings.some((f) => f.category === 'tests')) {
+    questions.push('Which tests prove critical paths, error paths, and regression cases are covered?');
+  }
+  if (snapshot.mode === 'pull_request') {
+    questions.push('Is this PR still reviewable as-is, or should it be split by change domain?');
+  }
+  if (findings.some((f) => f.category === 'dependencies')) {
+    questions.push('Have new dependencies/lifecycle scripts/GitHub Actions been audited for supply-chain risk?');
+  }
+  questions.push('What is the rollback plan if this change causes an incident after deployment?');
+  return unique(questions).slice(0, 8);
+}
+
+function buildRecommendations(findings, risk) {
+  const sorted = findings.slice().sort((a, b) => (SeverityWeights[b.severity] || 0) - (SeverityWeights[a.severity] || 0));
+  const recs = sorted.map((finding) => finding.recommendation).filter(Boolean);
+  const base = [
+    risk.score >= 50 ? 'Do not merge until high/critical findings have explicit owners and resolutions.' : 'Continue manual review for business logic, data flow, and edge cases.',
+    'Run local lint/test/build and CI before declaring merge-ready.',
+    'Use this MCP output as initial screening, not as a replacement for human security review.'
+  ];
+  return unique([...recs, ...base]).slice(0, 12);
+}
+
+function buildMarkdownReport(report) {
+  const lines = [];
+  lines.push(`# GitLumen MCP Screening Report`);
+  lines.push('');
+  lines.push(`**Report ID:** ${report.reportId}`);
+  lines.push(`**Target:** ${report.target.repoUrl}`);
+  lines.push(`**Mode:** ${report.target.mode}`);
+  lines.push(`**Ref:** ${report.target.ref}`);
+  lines.push(`**Risk:** ${report.risk.level.toUpperCase()} (${report.risk.score}/100)`);
+  lines.push(`**Merge readiness:** ${report.risk.mergeReadiness}`);
+  lines.push('');
+  lines.push(`## Summary`);
+  lines.push(report.summary);
+  lines.push('');
+  lines.push(`## Category Scores`);
+  for (const [category, score] of Object.entries(report.risk.categoryScores)) {
+    lines.push(`- ${category}: ${score}/100`);
+  }
+  lines.push('');
+  lines.push(`## Findings`);
+  if (!report.findings.length) {
+    lines.push('- No significant heuristic findings. Continue manual review.');
+  } else {
+    for (const finding of report.findings) {
+      lines.push(`- **[${finding.severity}] ${finding.title}**${finding.file ? ` — \`${finding.file}\`` : ''}`);
+      for (const evidence of finding.evidence || []) lines.push(`  - Evidence: ${evidence}`);
+      lines.push(`  - Recommendation: ${finding.recommendation}`);
+    }
+  }
+  lines.push('');
+  lines.push(`## Review Chapters`);
+  for (const chapter of report.chapters) {
+    lines.push(`### ${chapter.title}`);
+    lines.push(chapter.summary);
+    for (const bullet of chapter.bullets) lines.push(`- ${bullet}`);
+    lines.push('');
+  }
+  lines.push(`## Next Actions`);
+  for (const item of report.recommendations) lines.push(`- ${item}`);
+  lines.push('');
+  lines.push('> Generated by GitLumen MCP Server prototype. This is a heuristic screening layer, not a replacement for human code/security review.');
+  return lines.join('\n');
+}
+
+export function analyzeSnapshot(snapshot, input = {}) {
+  const findings = [];
+  const paths = snapshot.tree.map((entry) => entry.path);
+  const languages = detectLanguages(paths);
+  const packageJsonFile = findPackageJson(snapshot);
+  const packageInfo = analyzePackageJson(snapshot, findings, packageJsonFile);
+  const frameworks = detectFrameworks(snapshot, packageJsonFile ? parseJsonSafe(packageJsonFile.content) : null);
+  const signals = analyzeStructure(snapshot, findings);
+  analyzeCodeContent(snapshot, findings);
+  const prSignals = analyzePullRequest(snapshot, findings);
+
+  const risk = computeRisk(findings);
+  const reportId = createReportId({ repoUrl: snapshot.repoUrl, scope: input.scope });
+  const summary = risk.score >= 75
+    ? 'The repository/PR shows critical risk signals. Remediation is required before it can be considered merge/deploy-ready.'
+    : risk.score >= 50
+      ? 'The repository/PR has high risk. Senior review and remediation of key findings are recommended before merge.'
+      : risk.score >= 25
+        ? 'The repository/PR has medium risk. Continue manual review with focus on the listed findings.'
+        : 'The repository/PR appears relatively low risk based on initial heuristic screening. Continue manual review for business logic.';
+
+  const report = {
+    reportId,
+    generatedAt: new Date().toISOString(),
+    generator: {
+      name: 'gitlumen-screen-sdk',
+      version: '0.1.0',
+      mode: 'local-heuristic-screening'
+    },
+    target: {
+      mode: snapshot.mode,
+      owner: snapshot.owner,
+      repo: snapshot.repo,
+      repoUrl: snapshot.repoUrl,
+      ref: snapshot.ref,
+      defaultBranch: snapshot.defaultBranch,
+      pullRequest: snapshot.pullRequest || null
+    },
+    input: {
+      scope: input.scope || 'standard',
+      maxFiles: input.maxFiles || null
+    },
+    repositorySignals: {
+      description: snapshot.description,
+      stars: snapshot.stars,
+      forks: snapshot.forks,
+      primaryLanguage: snapshot.language,
+      detectedLanguages: languages,
+      frameworks,
+      packageInfo: {
+        packageManager: packageInfo.packageManager,
+        packageName: packageInfo.packageName,
+        packageVersion: packageInfo.packageVersion,
+        scripts: packageInfo.scripts ? Object.keys(packageInfo.scripts) : [],
+        dependencyCount: packageInfo.dependencies ? Object.keys(packageInfo.dependencies).length : 0
+      },
+      structure: signals,
+      pullRequest: prSignals,
+      limits: snapshot.limits
+    },
+    risk,
+    summary,
+    findings: findings.sort((a, b) => (SeverityWeights[b.severity] || 0) - (SeverityWeights[a.severity] || 0)),
+    chapters: [],
+    decisionQuestions: [],
+    recommendations: []
+  };
+
+  report.decisionQuestions = buildDecisionQuestions({ snapshot, findings: report.findings, risk });
+  report.recommendations = buildRecommendations(report.findings, risk);
+  report.chapters = buildChapters({ snapshot, findings: report.findings, signals, packageInfo, frameworks, languages, risk });
+  report.markdown = buildMarkdownReport(report);
+
+  return report;
+}

package/src/services/github.js

@@ -0,0 +1,269 @@
+import { createConfig, DEFAULT_LIMITS } from '../config.js';
+import { parseGitHubUrl } from '../utils/githubUrl.js';
+
+const TEXT_EXTENSIONS = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.json', '.jsonc', '.md', '.mdx', '.yml', '.yaml', '.toml', '.ini', '.env',
+  '.py', '.rb', '.go', '.rs', '.java', '.kt', '.cs', '.php', '.sol', '.vy', '.sh', '.bash', '.zsh', '.sql', '.graphql',
+  '.css', '.scss', '.html', '.vue', '.svelte', '.dockerfile', '.tf', '.tfvars', '.gradle', '.xml', '.properties', '.txt'
+]);
+
+const IMPORTANT_FILENAMES = new Set([
+  'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb',
+  'requirements.txt', 'pyproject.toml', 'poetry.lock', 'pipfile', 'pipfile.lock',
+  'go.mod', 'go.sum', 'cargo.toml', 'cargo.lock', 'pom.xml', 'build.gradle', 'gradle.properties',
+  'dockerfile', 'docker-compose.yml', 'compose.yml', '.dockerignore',
+  '.env.example', '.env.sample', '.env.template',
+  'readme.md', 'license', 'security.md', 'codeowners',
+  'tsconfig.json', 'vite.config.js', 'vite.config.ts', 'next.config.js', 'next.config.mjs',
+  'hardhat.config.js', 'hardhat.config.ts', 'foundry.toml', 'truffle-config.js'
+]);
+
+function extnameLower(path) {
+  const name = path.toLowerCase();
+  const idx = name.lastIndexOf('.');
+  if (idx === -1) return '';
+  return name.slice(idx);
+}
+
+function basenameLower(path) {
+  return path.split('/').pop().toLowerCase();
+}
+
+function isTextLike(path) {
+  const base = basenameLower(path);
+  if (IMPORTANT_FILENAMES.has(base)) return true;
+  if (base.startsWith('.env')) return true;
+  return TEXT_EXTENSIONS.has(extnameLower(path));
+}
+
+function shouldSkipPath(path) {
+  const lower = path.toLowerCase();
+  return [
+    'node_modules/', 'vendor/', 'dist/', 'build/', '.next/', '.nuxt/', '.git/', 'coverage/', '.cache/', 'target/',
+    'public/assets/', 'static/assets/', 'assets/', '.turbo/', '.vercel/', '__pycache__/', '.venv/', 'venv/',
+    'package-lock.json' // metadata exists in tree; content usually too noisy for screening
+  ].some((segment) => lower.includes(segment));
+}
+
+function scorePathPriority(path) {
+  const lower = path.toLowerCase();
+  const base = basenameLower(path);
+  let score = 0;
+  if (IMPORTANT_FILENAMES.has(base)) score += 100;
+  if (lower.includes('/.github/workflows/') || lower.startsWith('.github/workflows/')) score += 90;
+  if (lower.includes('src/') || lower.includes('app/') || lower.includes('server/') || lower.includes('api/')) score += 40;
+  if (lower.includes('test') || lower.includes('spec')) score += 20;
+  if (lower.includes('auth') || lower.includes('security') || lower.includes('wallet') || lower.includes('payment')) score += 35;
+  if (['.js', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.sol'].includes(extnameLower(path))) score += 25;
+  return score;
+}
+
+export class GitHubClient {
+  constructor(options = {}) {
+    this.config = createConfig(options);
+    this.token = options.token ?? this.config.githubToken;
+  }
+
+  headers(extra = {}) {
+    const headers = {
+      'Accept': 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': this.config.userAgent,
+      ...extra
+    };
+    if (this.token) headers.Authorization = `Bearer ${this.token}`;
+    return headers;
+  }
+
+  async api(path, options = {}) {
+    const url = `${this.config.githubApiBase}${path}`;
+    let response;
+    try {
+      response = await fetch(url, {
+        ...options,
+        headers: this.headers(options.headers || {})
+      });
+    } catch (error) {
+      throw new Error(`Unable to reach GitHub API: ${error.cause?.code || error.code || error.message}. Check internet/DNS or set proxy/VPN if needed.`);
+    }
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new Error(`GitHub API ${response.status} ${response.statusText}: ${path}${body ? ` - ${body.slice(0, 300)}` : ''}`);
+    }
+    return response.json();
+  }
+
+  async getRepository(owner, repo) {
+    return this.api(`/repos/${owner}/${repo}`);
+  }
+
+  async getTree(owner, repo, ref) {
+    const tree = await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`);
+    return tree.tree || [];
+  }
+
+  async getPull(owner, repo, pullNumber) {
+    return this.api(`/repos/${owner}/${repo}/pulls/${pullNumber}`);
+  }
+
+  async getPullFiles(owner, repo, pullNumber, maxFiles = DEFAULT_LIMITS.maxPrFiles) {
+    const pages = [];
+    let page = 1;
+    while (pages.flat().length < maxFiles) {
+      const files = await this.api(`/repos/${owner}/${repo}/pulls/${pullNumber}/files?per_page=100&page=${page}`);
+      pages.push(files);
+      if (!files.length || files.length < 100) break;
+      page += 1;
+      if (page > 10) break;
+    }
+    return pages.flat().slice(0, maxFiles);
+  }
+
+  async getRawFile(owner, repo, ref, path, maxBytes = this.config.maxFileBytes) {
+    const url = `${this.config.rawBase}/${owner}/${repo}/${encodeURIComponent(ref).replace(/%2F/g, '/')}/${path.split('/').map(encodeURIComponent).join('/')}`;
+    let response;
+    try {
+      response = await fetch(url, { headers: this.headers({ Accept: 'text/plain,*/*' }) });
+    } catch {
+      return null;
+    }
+    if (!response.ok) return null;
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > maxBytes) {
+      const sliced = Buffer.from(buffer).subarray(0, maxBytes).toString('utf8');
+      return { content: sliced, truncated: true, size: buffer.byteLength };
+    }
+    return { content: Buffer.from(buffer).toString('utf8'), truncated: false, size: buffer.byteLength };
+  }
+
+  selectFilesForContent(treeEntries, scope, requestedMaxFiles) {
+    const maxFiles = requestedMaxFiles || {
+      quick: DEFAULT_LIMITS.quickMaxFiles,
+      standard: DEFAULT_LIMITS.standardMaxFiles,
+      deep: DEFAULT_LIMITS.deepMaxFiles
+    }[scope] || DEFAULT_LIMITS.standardMaxFiles;
+
+    return treeEntries
+      .filter((entry) => entry.type === 'blob')
+      .filter((entry) => !shouldSkipPath(entry.path))
+      .filter((entry) => isTextLike(entry.path))
+      .sort((a, b) => scorePathPriority(b.path) - scorePathPriority(a.path))
+      .slice(0, maxFiles);
+  }
+
+  async loadRepositorySnapshot({ repoUrl, branch, scope = 'standard', maxFiles }) {
+    const parsed = parseGitHubUrl(repoUrl);
+    const repoMeta = await this.getRepository(parsed.owner, parsed.repo);
+    const ref = branch || repoMeta.default_branch;
+
+    if (parsed.pullNumber) {
+      return this.loadPullRequestSnapshot({ ...parsed, repoMeta, ref, scope, maxFiles });
+    }
+
+    const tree = await this.getTree(parsed.owner, parsed.repo, ref);
+    const clippedTree = tree.slice(0, DEFAULT_LIMITS.maxTreeEntries);
+    const selected = this.selectFilesForContent(clippedTree, scope, maxFiles);
+    const files = [];
+
+    for (const entry of selected) {
+      const raw = await this.getRawFile(parsed.owner, parsed.repo, ref, entry.path);
+      if (!raw) continue;
+      files.push({
+        path: entry.path,
+        size: entry.size || raw.size || 0,
+        content: raw.content,
+        truncated: raw.truncated,
+        status: 'unchanged'
+      });
+    }
+
+    return {
+      mode: 'repository',
+      owner: parsed.owner,
+      repo: parsed.repo,
+      repoUrl: parsed.normalizedRepoUrl,
+      ref,
+      defaultBranch: repoMeta.default_branch,
+      description: repoMeta.description || '',
+      stars: repoMeta.stargazers_count || 0,
+      forks: repoMeta.forks_count || 0,
+      language: repoMeta.language || null,
+      isPrivate: Boolean(repoMeta.private),
+      tree: clippedTree.map((entry) => ({ path: entry.path, type: entry.type, size: entry.size || 0 })),
+      files,
+      limits: {
+        treeEntriesReturned: clippedTree.length,
+        treeTruncated: tree.length > clippedTree.length,
+        filesDownloaded: files.length,
+        scope
+      }
+    };
+  }
+
+  async loadPullRequestSnapshot({ owner, repo, pullNumber, repoMeta, scope = 'standard', maxFiles }) {
+    const pull = await this.getPull(owner, repo, pullNumber);
+    const prFiles = await this.getPullFiles(owner, repo, pullNumber, maxFiles || DEFAULT_LIMITS.maxPrFiles);
+    const selected = prFiles
+      .filter((file) => !shouldSkipPath(file.filename))
+      .filter((file) => isTextLike(file.filename))
+      .sort((a, b) => scorePathPriority(b.filename) - scorePathPriority(a.filename))
+      .slice(0, maxFiles || ({ quick: 60, standard: 120, deep: 240 }[scope] || 120));
+
+    const files = [];
+    const ref = pull.head?.sha || pull.head?.ref || repoMeta.default_branch;
+    for (const file of selected) {
+      let content = '';
+      let truncated = false;
+      if (file.status !== 'removed') {
+        const raw = await this.getRawFile(owner, repo, ref, file.filename);
+        content = raw?.content || '';
+        truncated = Boolean(raw?.truncated);
+      }
+      files.push({
+        path: file.filename,
+        size: file.changes || file.additions + file.deletions,
+        content,
+        truncated,
+        patch: file.patch || '',
+        status: file.status || 'modified',
+        additions: file.additions || 0,
+        deletions: file.deletions || 0
+      });
+    }
+
+    return {
+      mode: 'pull_request',
+      owner,
+      repo,
+      repoUrl: `https://github.com/${owner}/${repo}`,
+      ref,
+      defaultBranch: repoMeta.default_branch,
+      description: repoMeta.description || '',
+      stars: repoMeta.stargazers_count || 0,
+      forks: repoMeta.forks_count || 0,
+      language: repoMeta.language || null,
+      isPrivate: Boolean(repoMeta.private),
+      pullRequest: {
+        number: pullNumber,
+        title: pull.title,
+        state: pull.state,
+        author: pull.user?.login || null,
+        baseRef: pull.base?.ref || null,
+        headRef: pull.head?.ref || null,
+        changedFiles: pull.changed_files,
+        additions: pull.additions,
+        deletions: pull.deletions,
+        htmlUrl: pull.html_url
+      },
+      tree: prFiles.map((file) => ({ path: file.filename, type: 'blob', size: file.changes || 0, status: file.status })),
+      files,
+      limits: {
+        treeEntriesReturned: prFiles.length,
+        treeTruncated: prFiles.length >= DEFAULT_LIMITS.maxPrFiles,
+        filesDownloaded: files.length,
+        scope
+      }
+    };
+  }
+}

package/src/services/gitlumen.js

@@ -0,0 +1,53 @@
+import { GitHubClient } from './github.js';
+import { analyzeSnapshot } from './analyzer.js';
+import { ReportStore } from './reportStore.js';
+
+export class GitLumenService {
+  constructor({ githubClient, store, githubOptions = {}, storeOptions = {} } = {}) {
+    this.github = githubClient || new GitHubClient(githubOptions);
+    this.store = store || new ReportStore(storeOptions);
+  }
+
+  async screenRepository(input) {
+    const scope = input.scope || 'standard';
+    const snapshot = await this.github.loadRepositorySnapshot({
+      repoUrl: input.repoUrl,
+      branch: input.branch || undefined,
+      scope,
+      maxFiles: input.maxFiles || undefined
+    });
+    const report = analyzeSnapshot(snapshot, { scope, maxFiles: input.maxFiles || null });
+    await this.store.save(report);
+    return report;
+  }
+
+  async getReport(reportId) {
+    return this.store.get(reportId);
+  }
+
+  async listReports(limit) {
+    return this.store.list(limit);
+  }
+
+  async getRepositoryStructure(input) {
+    const snapshot = await this.github.loadRepositorySnapshot({
+      repoUrl: input.repoUrl,
+      branch: input.branch || undefined,
+      scope: 'quick',
+      maxFiles: 1
+    });
+    return {
+      target: {
+        mode: snapshot.mode,
+        owner: snapshot.owner,
+        repo: snapshot.repo,
+        repoUrl: snapshot.repoUrl,
+        ref: snapshot.ref,
+        defaultBranch: snapshot.defaultBranch,
+        pullRequest: snapshot.pullRequest || null
+      },
+      structure: snapshot.tree.slice(0, input.limit || 300),
+      limits: snapshot.limits
+    };
+  }
+}

package/src/services/reportStore.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createConfig } from '../config.js';
+
+export class ReportStore {
+  constructor({ dataDir, config } = {}) {
+    const runtimeConfig = createConfig(config || {});
+    this.dataDir = dataDir || runtimeConfig.dataDir;
+    this.reportsDir = path.join(this.dataDir, 'reports');
+  }
+
+  async ensure() {
+    await fs.mkdir(this.reportsDir, { recursive: true });
+  }
+
+  pathFor(reportId) {
+    if (!/^glr_[a-f0-9]{16}$/.test(reportId)) {
+      throw new Error(`Invalid report id: ${reportId}`);
+    }
+    return path.join(this.reportsDir, `${reportId}.json`);
+  }
+
+  async save(report) {
+    await this.ensure();
+    const file = this.pathFor(report.reportId);
+    await fs.writeFile(file, JSON.stringify(report, null, 2), 'utf8');
+    return file;
+  }
+
+  async get(reportId) {
+    await this.ensure();
+    const file = this.pathFor(reportId);
+    const raw = await fs.readFile(file, 'utf8');
+    return JSON.parse(raw);
+  }
+
+  async list(limit = 20) {
+    await this.ensure();
+    const entries = await fs.readdir(this.reportsDir, { withFileTypes: true });
+    const files = entries.filter((entry) => entry.isFile() && entry.name.endsWith('.json'));
+    const reports = [];
+    for (const file of files) {
+      try {
+        const fullPath = path.join(this.reportsDir, file.name);
+        const stat = await fs.stat(fullPath);
+        const parsed = JSON.parse(await fs.readFile(fullPath, 'utf8'));
+        reports.push({
+          reportId: parsed.reportId,
+          generatedAt: parsed.generatedAt,
+          target: parsed.target,
+          risk: parsed.risk,
+          summary: parsed.summary,
+          filePath: fullPath,
+          modifiedAt: stat.mtime.toISOString()
+        });
+      } catch {
+        // Skip corrupt report file.
+      }
+    }
+    return reports.sort((a, b) => new Date(b.generatedAt) - new Date(a.generatedAt)).slice(0, limit);
+  }
+}

package/src/types.js

@@ -0,0 +1,16 @@
+export const SeverityWeights = {
+  critical: 25,
+  high: 15,
+  medium: 8,
+  low: 3,
+  info: 0
+};
+
+export const CategoryNames = [
+  'security',
+  'dependencies',
+  'tests',
+  'architecture',
+  'operations',
+  'maintainability'
+];

package/src/utils/githubUrl.js

@@ -0,0 +1,48 @@
+export function parseGitHubUrl(repoUrl) {
+  if (!repoUrl || typeof repoUrl !== 'string') {
+    throw new Error('repoUrl is required');
+  }
+
+  let normalized = repoUrl.trim();
+  if (!/^https?:\/\//i.test(normalized) && !normalized.startsWith('git@')) {
+    normalized = `https://${normalized}`;
+  }
+
+  const sshMatch = normalized.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/i);
+  if (sshMatch) {
+    return {
+      owner: sshMatch[1],
+      repo: sshMatch[2],
+      pullNumber: null,
+      normalizedRepoUrl: `https://github.com/${sshMatch[1]}/${sshMatch[2]}`
+    };
+  }
+
+  let url;
+  try {
+    url = new URL(normalized);
+  } catch {
+    throw new Error(`Invalid GitHub URL: ${repoUrl}`);
+  }
+
+  if (!url.hostname.toLowerCase().includes('github.com')) {
+    throw new Error('Only github.com repositories are supported in this SDK');
+  }
+
+  const parts = url.pathname.split('/').filter(Boolean);
+  if (parts.length < 2) {
+    throw new Error('GitHub URL must include owner and repository name');
+  }
+
+  const owner = parts[0];
+  const repo = parts[1].replace(/\.git$/i, '');
+  const pullIndex = parts.findIndex((part) => part === 'pull');
+  const pullNumber = pullIndex >= 0 && parts[pullIndex + 1] ? Number(parts[pullIndex + 1]) : null;
+
+  return {
+    owner,
+    repo,
+    pullNumber: Number.isFinite(pullNumber) ? pullNumber : null,
+    normalizedRepoUrl: `https://github.com/${owner}/${repo}`
+  };
+}

package/src/utils/ids.js

@@ -0,0 +1,10 @@
+import crypto from 'node:crypto';
+
+export function createReportId(input) {
+  const seed = `${input.repoUrl}|${input.scope || 'standard'}|${Date.now()}|${Math.random()}`;
+  return `glr_${crypto.createHash('sha256').update(seed).digest('hex').slice(0, 16)}`;
+}
+
+export function stableHash(input, length = 12) {
+  return crypto.createHash('sha256').update(String(input)).digest('hex').slice(0, length);
+}

package/src/utils/text.js

@@ -0,0 +1,12 @@
+export function truncateText(text, max = 4000) {
+  if (!text || text.length <= max) return text || '';
+  return `${text.slice(0, max)}\n... [truncated ${text.length - max} chars]`;
+}
+
+export function safeJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+export function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}