@nanocollective/sentinel 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,22 @@
+# License
+
+MIT License
+
+Copyright (c) 2026 Nano Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# Sentinel
+
+Built by the [Nano Collective](https://nanocollective.org) — a community collective building AI tooling not for profit, but for the community.
+
+Sentinel is an installable, Nanocoder-driven workflow that runs continuous, configurable security and code audits across the repositories in a GitHub organisation, and files what it finds as issues for a human to act on.
+
+You install Sentinel into your own organisation, point it at the repositories you care about, write the rule packs that describe what to look for, and a scheduled GitHub Actions workflow does the audit pass. Findings land as issues on the affected repository, written up for a reviewer. Local models are a first-class path, so the audited code never has to leave hardware you own.
+
+> Sentinel is in active development toward its v1. This repository and its documentation describe the v1 design settled in the [Sentinel whitepaper](https://docs.nanocollective.org/collective/whitepapers/sentinel). Features are being built; where something is planned rather than shipped, the docs say so.
+
+---
+
+![Build Status](https://github.com/Nano-Collective/sentinel/raw/main/badges/build.svg)
+![Coverage](https://github.com/Nano-Collective/sentinel/raw/main/badges/coverage.svg)
+![Version](https://github.com/Nano-Collective/sentinel/raw/main/badges/npm-version.svg)
+![NPM Downloads](https://github.com/Nano-Collective/sentinel/raw/main/badges/npm-downloads-monthly.svg)
+![NPM License](https://github.com/Nano-Collective/sentinel/raw/main/badges/npm-license.svg)
+![Stars](https://github.com/Nano-Collective/sentinel/raw/main/badges/stars.svg)
+
+## Quick Start
+
+From inside a fresh repository in your GitHub organisation:
+
+```bash
+npx @nanocollective/sentinel init
+# or
+pnpm dlx @nanocollective/sentinel init
+```
+
+`init` scaffolds the configuration (`sentinel.yaml`), the scheduled GitHub Actions workflow, an empty `rule-packs/` directory, and a starter pack template. Answer the prompts (model provider, schedule, first repositories), review the generated files, write your first rule pack, commit, and push. The first scheduled run lands later that day, or you can dispatch the workflow manually.
+
+Sentinel ships **no rule packs of its own**. The value comes from the packs you write for the code you actually ship — see [Writing a Rule Pack](docs/rule-packs/authoring.md).
+
+You can also run an audit locally, off-cycle, for calibrating a pack:
+
+```bash
+npx @nanocollective/sentinel run \
+  --rule-pack ./rule-packs/solana-anchor.md \
+  --repo ../my-program \
+  --output findings.md
+```
+
+## Documentation
+
+Full documentation is available online at **[docs.nanocollective.org](https://docs.nanocollective.org/sentinel/docs)** or in the [docs/](docs/) folder:
+
+- **[Getting Started](docs/getting-started/index.md)** — Install Sentinel into your organisation and get the first run green
+- **[Rule Packs](docs/rule-packs/index.md)** — The pack format, the authoring guide, and worked examples
+- **[Configuration](docs/configuration/index.md)** — The `sentinel.yaml` reference
+- **[Workflow](docs/workflow/index.md)** — The scheduled audit, run modes, and the execution model
+- **[Findings & Issues](docs/findings/index.md)** — The severity model, issue filing, dedup, and suppression
+- **[CLI](docs/cli/index.md)** — `init` and `run` command reference
+- **[Community](docs/community.md)** — Contributing, Discord, and how to help
+
+## What Sentinel is not (in v1)
+
+Sentinel is a triage layer, not a replacement for a real audit. It is **not** a substitute for a formal security audit, **not** a SAST replacement (run Semgrep/CodeQL alongside it), **not** a secret scanner, **not** a hosted service, **not** a rule pack catalogue, and **not** a fix-it tool — it files issues, it does not open PRs. See the [whitepaper](https://docs.nanocollective.org/collective/whitepapers/sentinel) for the full scope.
+
+## Community
+
+The Nano Collective is a community collective building AI tooling for the community, not for profit. We'd love your help.
+
+- **Contribute**: See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+- **The collective**: [nanocollective.org](https://nanocollective.org) · [docs](https://docs.nanocollective.org) · [GitHub](https://github.com/Nano-Collective) · [Discord](https://discord.gg/ktPDV6rekE)
+- **Support the work**: The [Support page](https://docs.nanocollective.org/collective/organisation/support) covers donations and sponsorship.
+- **Paid contribution**: The [Economics Charter](https://docs.nanocollective.org/collective/organisation/economics-charter) sets out how scoped paid bounties work.

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Sentinel CLI entry point.
+ *
+ *   sentinel init   scaffold a configuration repo
+ *   sentinel run    perform an audit pass (not yet implemented)
+ *
+ * The init command's logic lives in ./init; this file is the interactive glue
+ * (prompting, printing) and is excluded from coverage.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG"}

package/dist/cli.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Sentinel CLI entry point.
+ *
+ *   sentinel init   scaffold a configuration repo
+ *   sentinel run    perform an audit pass (not yet implemented)
+ *
+ * The init command's logic lives in ./init; this file is the interactive glue
+ * (prompting, printing) and is excluded from coverage.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseConfig } from './config/parse.js';
+import { parseInitArgs } from './init/args.js';
+import { scaffold } from './init/scaffold.js';
+import { ghIssueClient } from './issues/gh-client.js';
+import { nanocoderRunner } from './orchestrator/nanocoder-runner.js';
+import { ensureTargets } from './run/clone.js';
+import { renderPreview } from './run/preview.js';
+import { renderReport } from './run/report.js';
+import { runFromConfig, runLocal } from './run/run.js';
+import { fsPackLoader, fsRepoFiles } from './run/sources.js';
+const USAGE = `sentinel <command>
+
+Commands:
+  init    Scaffold a Sentinel configuration into the current repository
+  run     Perform an audit pass against a rule pack and a repository
+
+Run 'sentinel <command> --help' for command-specific options.`;
+const INIT_USAGE = `sentinel init [options]
+
+Scaffold sentinel.yaml, the audit workflow, an empty rule-packs/ directory,
+and a disabled starter pack into the current (or given) directory.
+
+Options:
+  --provider <name>            Model provider (ollama, lmstudio, a cloud provider)
+  --model <id>                 Model identifier
+  --schedule <cron>            Cron schedule, UTC (default "0 6 * * *")
+  --targets <a/b,c/d>          Comma-separated owner/repo targets
+  --severity-threshold <s>     low | medium | high | critical (default medium)
+  --label <name>               Issue label (default "sentinel")
+  --dir <path>                 Directory to scaffold into (default ".")
+  --force                      Overwrite existing files
+  --yes                        Non-interactive; accept defaults`;
+async function promptMissing(options) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const ask = async (label, current) => {
+            const answer = (await rl.question(`${label} [${current}]: `)).trim();
+            return answer.length > 0 ? answer : current;
+        };
+        const provider = await ask('Model provider', options.provider);
+        const model = await ask('Model', options.model);
+        const schedule = await ask('Schedule (cron, UTC)', options.schedule);
+        const label = await ask('Issue label', options.label);
+        const targetsRaw = await ask('Repositories to audit (comma-separated owner/repo)', options.targets.join(','));
+        const targets = targetsRaw
+            .split(',')
+            .map(target => target.trim())
+            .filter(target => target.length > 0);
+        return { ...options, provider, model, schedule, label, targets };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runInit(argv) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(INIT_USAGE);
+        return 0;
+    }
+    const parsed = parseInitArgs(argv);
+    if (parsed.errors.length > 0) {
+        for (const error of parsed.errors) {
+            console.error(`error: ${error}`);
+        }
+        return 1;
+    }
+    const interactive = !parsed.yes && Boolean(process.stdin.isTTY);
+    const options = interactive
+        ? await promptMissing(parsed.options)
+        : parsed.options;
+    const result = scaffold(options, parsed.dir, parsed.force);
+    for (const path of result.written) {
+        console.log(`  created  ${path}`);
+    }
+    for (const path of result.skipped) {
+        console.log(`  skipped  ${path} (exists; pass --force to overwrite)`);
+    }
+    console.log('\nNext steps:\n  1. Edit sentinel.yaml — set your real targets and model.\n  2. Write your first rule pack in rule-packs/ (see the disabled example).\n  3. Commit and push. The audit runs on schedule, or dispatch it manually.');
+    return 0;
+}
+const RUN_USAGE = `sentinel run [options]
+
+Config-driven (default): reads sentinel.yaml and audits every target. Files
+issues when GITHUB_TOKEN is set and --dry-run is not passed.
+
+Local (calibration): audit one pack against one repo, write findings to
+Markdown, and file nothing.
+
+Options:
+  --rule-pack <path>    Local mode: the rule pack to run
+  --repo <path>         Local mode: the repository directory to audit
+  --output <path>       Write the Markdown report here (default stdout)
+  --config <path>       Path to sentinel.yaml (default ./sentinel.yaml)
+  --packs-dir <path>    Rule packs directory (default ./rule-packs)
+  --workspace <path>    Where target repos are checked out (default .)
+  --config-repo <o/n>   Config repo, for routing (default $GITHUB_REPOSITORY)
+  --provider <name>     Local mode model provider (default ollama)
+  --model <id>          Local mode model id (default llama3.1:70b)
+  --dry-run             Audit but file no issues`;
+function flagMap(argv) {
+    const map = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token || !token.startsWith('--')) {
+            continue;
+        }
+        const body = token.slice(2);
+        const eq = body.indexOf('=');
+        if (eq !== -1) {
+            map.set(body.slice(0, eq), body.slice(eq + 1));
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            map.set(body, next);
+            i++;
+        }
+        else {
+            map.set(body, true);
+        }
+    }
+    return map;
+}
+function flagStr(flags, key) {
+    const value = flags.get(key);
+    return typeof value === 'string' ? value : undefined;
+}
+function writeReport(markdown, output) {
+    if (output) {
+        writeFileSync(output, markdown);
+        console.log(`Wrote report to ${output}`);
+    }
+    else {
+        console.log(markdown);
+    }
+}
+async function runRun(argv) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(RUN_USAGE);
+        return 0;
+    }
+    const flags = flagMap(argv);
+    const output = flagStr(flags, 'output');
+    // Local calibration mode.
+    const rulePack = flagStr(flags, 'rule-pack');
+    const repo = flagStr(flags, 'repo');
+    if (rulePack && repo) {
+        const model = {
+            provider: flagStr(flags, 'provider') ?? 'ollama',
+            model: flagStr(flags, 'model') ?? 'llama3.1:70b',
+        };
+        const localConfigDir = flagStr(flags, 'config-dir');
+        const outcome = await runLocal(rulePack, repo, model, { runner: nanocoderRunner, files: fsRepoFiles }, 
+        // Absolute — nanocoder runs with cwd set to the audited repo.
+        { configDir: localConfigDir ? resolve(localConfigDir) : undefined });
+        writeReport(renderReport(outcome), output);
+        return 0;
+    }
+    // Config-driven mode.
+    const configPath = flagStr(flags, 'config') ?? 'sentinel.yaml';
+    const parsed = parseConfig(readFileSync(configPath, 'utf8'));
+    if (!parsed.valid || !parsed.config) {
+        for (const error of parsed.errors) {
+            console.error(`config error — ${error.field}: ${error.message}`);
+        }
+        return 1;
+    }
+    const dryRun = flags.get('dry-run') === true;
+    const workspace = flagStr(flags, 'workspace') ?? '.';
+    // Clone any target repos not already present in the workspace.
+    if (flags.get('no-clone') !== true) {
+        const repos = parsed.config.targets
+            .map(target => target.repo)
+            .filter((repo) => Boolean(repo));
+        const ensured = ensureTargets(repos, workspace);
+        for (const repo of ensured.cloned) {
+            console.log(`cloned ${repo}`);
+        }
+        for (const { repo, error } of ensured.errors) {
+            console.error(`clone failed for ${repo}: ${error}`);
+        }
+    }
+    // The client is available whenever a token is present — a dry run uses it to
+    // read existing issues for the preview, a live run to file.
+    const hasToken = Boolean(process.env.GITHUB_TOKEN);
+    const report = await runFromConfig(parsed.config, {
+        runner: nanocoderRunner,
+        files: fsRepoFiles,
+        packs: fsPackLoader,
+        client: hasToken ? ghIssueClient : undefined,
+        now: new Date().toISOString(),
+    }, {
+        workspaceDir: workspace,
+        packsDir: flagStr(flags, 'packs-dir') ?? join(dirname(configPath), 'rule-packs'),
+        // nanocoder's agents.config.json lives beside sentinel.yaml. Absolute —
+        // nanocoder runs with cwd set to the audited repo.
+        configDir: resolve(flagStr(flags, 'config-dir') ?? dirname(configPath)),
+        configRepo: flagStr(flags, 'config-repo') ?? process.env.GITHUB_REPOSITORY,
+        dryRun,
+    });
+    // Dry run with a token renders the grouped preview; otherwise the plain
+    // findings report.
+    const markdown = dryRun && report.previews.length > 0
+        ? renderPreview(report.previews)
+        : renderReport(report.outcome);
+    writeReport(markdown, output);
+    if (report.filed) {
+        for (const { repo: repoName, result } of report.reconciled) {
+            console.log(`${repoName}: filed ${result.created.length}, touched ${result.touched}, resolved ${result.resolved}`);
+        }
+    }
+    else if (dryRun) {
+        console.log('Dry run — no issues filed.');
+    }
+    else {
+        console.log('No GITHUB_TOKEN — no issues filed.');
+    }
+    return 0;
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    switch (command) {
+        case 'init':
+            return runInit(rest);
+        case 'run':
+            return runRun(rest);
+        case undefined:
+        case '--help':
+        case '-h':
+            console.log(USAGE);
+            return 0;
+        default:
+            console.log(`Unknown command: ${command}\n`);
+            console.log(USAGE);
+            return 1;
+    }
+}
+main(process.argv.slice(2)).then(code => {
+    process.exit(code);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"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"}

package/dist/config/parse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse and validate `sentinel.yaml`. Applies sensible defaults (schedule,
+ * severity threshold, issue routing), enforces the target and model contracts,
+ * and returns a structured {@link ConfigResult} — the same error shape used by
+ * the findings validator and the rule pack parser.
+ */
+import type { ConfigResult } from './types.js';
+/**
+ * Parse `sentinel.yaml`. On success, returns the normalised config with
+ * defaults applied; on failure, returns every reason it was rejected.
+ */
+export declare function parseConfig(raw: string): ConfigResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/config/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../source/config/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAEX,YAAY,EAKZ,MAAM,YAAY,CAAC;AAgNpB;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAiFrD"}

package/dist/config/parse.js

@@ -0,0 +1,271 @@
+/**
+ * Parse and validate `sentinel.yaml`. Applies sensible defaults (schedule,
+ * severity threshold, issue routing), enforces the target and model contracts,
+ * and returns a structured {@link ConfigResult} — the same error shape used by
+ * the findings validator and the rule pack parser.
+ */
+import { parse as parseYaml } from 'yaml';
+import { isSeverity } from '../findings/types.js';
+const DEFAULT_SCHEDULE = '0 6 * * *';
+const DEFAULT_SEVERITY_THRESHOLD = 'medium';
+const DEFAULT_LABEL = 'sentinel';
+/** `owner/name`, with no whitespace or extra slashes. */
+const REPO_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+/** Kebab-case rule pack name. */
+const PACK_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A single cron field: digits, and the `* , - /` operators. */
+const CRON_FIELD_PATTERN = /^[\d*,/-]+$/;
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** Light cron validation: five fields, each using only cron characters. */
+function isValidCron(value) {
+    const fields = value.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        return false;
+    }
+    return fields.every(field => CRON_FIELD_PATTERN.test(field));
+}
+function validateTarget(value, index, errors) {
+    const field = `targets[${index}]`;
+    if (!isObject(value)) {
+        errors.push({ field, message: 'each target must be a mapping' });
+        return null;
+    }
+    const hasRepo = value.repo !== undefined;
+    const hasPattern = value.pattern !== undefined;
+    if (hasRepo === hasPattern) {
+        errors.push({
+            field,
+            message: 'each target must set exactly one of repo or pattern',
+        });
+    }
+    if (hasRepo &&
+        !(isNonEmptyString(value.repo) && REPO_PATTERN.test(value.repo))) {
+        errors.push({
+            field: `${field}.repo`,
+            message: 'repo must be in owner/name form',
+        });
+    }
+    if (hasPattern && !isNonEmptyString(value.pattern)) {
+        errors.push({
+            field: `${field}.pattern`,
+            message: 'pattern must be a non-empty string',
+        });
+    }
+    const rulePacks = [];
+    if (!Array.isArray(value.rule_packs) || value.rule_packs.length === 0) {
+        errors.push({
+            field: `${field}.rule_packs`,
+            message: 'rule_packs must be a non-empty list of pack names',
+        });
+    }
+    else {
+        for (const [i, name] of value.rule_packs.entries()) {
+            if (typeof name === 'string' && PACK_NAME_PATTERN.test(name)) {
+                rulePacks.push(name);
+            }
+            else {
+                errors.push({
+                    field: `${field}.rule_packs[${i}]`,
+                    message: 'each rule pack name must be kebab-case',
+                });
+            }
+        }
+    }
+    const target = { rulePacks };
+    if (hasRepo && typeof value.repo === 'string') {
+        target.repo = value.repo;
+    }
+    if (hasPattern && typeof value.pattern === 'string') {
+        target.pattern = value.pattern;
+    }
+    return target;
+}
+function validateModel(value, errors) {
+    if (!isObject(value)) {
+        errors.push({
+            field: 'model',
+            message: 'model is required and must be a mapping',
+        });
+        return null;
+    }
+    if (!isNonEmptyString(value.provider)) {
+        errors.push({
+            field: 'model.provider',
+            message: 'model.provider is required',
+        });
+    }
+    if (!isNonEmptyString(value.model)) {
+        errors.push({ field: 'model.model', message: 'model.model is required' });
+    }
+    const model = {
+        provider: isNonEmptyString(value.provider) ? value.provider : '',
+        model: isNonEmptyString(value.model) ? value.model : '',
+    };
+    if (value.fallback !== undefined) {
+        if (!isObject(value.fallback)) {
+            errors.push({
+                field: 'model.fallback',
+                message: 'model.fallback must be a mapping',
+            });
+        }
+        else {
+            const fb = value.fallback;
+            if (!isNonEmptyString(fb.provider) || !isNonEmptyString(fb.model)) {
+                errors.push({
+                    field: 'model.fallback',
+                    message: 'model.fallback requires provider and model',
+                });
+            }
+            else {
+                model.fallback = { provider: fb.provider, model: fb.model };
+                if (fb.endpoint_secret !== undefined) {
+                    if (isNonEmptyString(fb.endpoint_secret)) {
+                        model.fallback.endpointSecret = fb.endpoint_secret;
+                    }
+                    else {
+                        errors.push({
+                            field: 'model.fallback.endpoint_secret',
+                            message: 'endpoint_secret must be a non-empty string',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return model;
+}
+function validateIssues(value, errors) {
+    const issues = {
+        label: DEFAULT_LABEL,
+        assignee: null,
+        aggregateToConfigRepo: false,
+    };
+    if (value === undefined) {
+        return issues;
+    }
+    if (!isObject(value)) {
+        errors.push({ field: 'issues', message: 'issues must be a mapping' });
+        return issues;
+    }
+    if (value.label !== undefined) {
+        if (isNonEmptyString(value.label)) {
+            issues.label = value.label;
+        }
+        else {
+            errors.push({
+                field: 'issues.label',
+                message: 'label must be a non-empty string',
+            });
+        }
+    }
+    if (value.assignee !== undefined && value.assignee !== null) {
+        if (isNonEmptyString(value.assignee)) {
+            issues.assignee = value.assignee;
+        }
+        else {
+            errors.push({
+                field: 'issues.assignee',
+                message: 'assignee must be a GitHub login or null',
+            });
+        }
+    }
+    if (value.aggregate_to_config_repo !== undefined) {
+        if (typeof value.aggregate_to_config_repo === 'boolean') {
+            issues.aggregateToConfigRepo = value.aggregate_to_config_repo;
+        }
+        else {
+            errors.push({
+                field: 'issues.aggregate_to_config_repo',
+                message: 'aggregate_to_config_repo must be a boolean',
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Parse `sentinel.yaml`. On success, returns the normalised config with
+ * defaults applied; on failure, returns every reason it was rejected.
+ */
+export function parseConfig(raw) {
+    let data;
+    try {
+        data = parseYaml(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            valid: false,
+            config: null,
+            errors: [{ field: 'document', message: `invalid YAML: ${message}` }],
+        };
+    }
+    if (!isObject(data)) {
+        return {
+            valid: false,
+            config: null,
+            errors: [{ field: 'document', message: 'sentinel.yaml must be a mapping' }],
+        };
+    }
+    const errors = [];
+    // targets (required, non-empty)
+    const targets = [];
+    if (!Array.isArray(data.targets) || data.targets.length === 0) {
+        errors.push({
+            field: 'targets',
+            message: 'targets is required and must list at least one repository',
+        });
+    }
+    else {
+        for (const [index, entry] of data.targets.entries()) {
+            const target = validateTarget(entry, index, errors);
+            if (target) {
+                targets.push(target);
+            }
+        }
+    }
+    // schedule (optional, defaulted)
+    let schedule = DEFAULT_SCHEDULE;
+    if (data.schedule !== undefined) {
+        if (isNonEmptyString(data.schedule) && isValidCron(data.schedule)) {
+            schedule = data.schedule.trim();
+        }
+        else {
+            errors.push({
+                field: 'schedule',
+                message: 'schedule must be a 5-field cron expression',
+            });
+        }
+    }
+    // severity_threshold (optional, defaulted)
+    let severityThreshold = DEFAULT_SEVERITY_THRESHOLD;
+    if (data.severity_threshold !== undefined) {
+        if (isSeverity(data.severity_threshold)) {
+            severityThreshold = data.severity_threshold;
+        }
+        else {
+            errors.push({
+                field: 'severity_threshold',
+                message: 'severity_threshold must be one of: low, medium, high, critical',
+            });
+        }
+    }
+    const model = validateModel(data.model, errors);
+    const issues = validateIssues(data.issues, errors);
+    if (errors.length > 0 || !model) {
+        return { valid: false, config: null, errors };
+    }
+    const config = {
+        targets,
+        schedule,
+        severityThreshold,
+        model,
+        issues,
+    };
+    return { valid: true, config, errors: [] };
+}
+//# sourceMappingURL=parse.js.map