@njeybe/nativ 2.8.0 → 2.9.1

package/dist/core/checks/docs-check.js

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+const EXTS = [
+    '.ts', '.js', '.mjs', '.cjs', '.json', '.md', '.sh', '.py', '.yml', '.yaml', '.toml', '.sql', '.example',
+];
+const TOKEN = /`([^`\n]+)`/g;
+const PLACEHOLDER = /^<[\w-]+>$/;
+const SETTING = /^(?:[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+|[A-Z][A-Z0-9_]*(?==))/;
+const SETTING_USE = /^(?:([A-Z][A-Z0-9_]*)=|\$\{?([A-Z][A-Z0-9_]*)\}?$)/;
+const SCOPED = /^@[\w.-]+\/[\w.-]+$/;
+// Created by nativ in the user's project, so absent here is fine.
+const RUNTIME_DIRS = ['.ai', '.nativ', '.worktrees', '.claude', 'tests/contract'];
+const RUNTIME_FILES = new Set([
+    'db_schema.json', 'api_contracts.json', 'master_plan.json', 'ui_specs.md', 'context.md', '.env.example',
+    'AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.mcp.json', 'SKILL.md', 'DIGEST.md',
+]);
+const CODE_EXTS = /\.(?:ts|js|mjs|cjs|py|sh)$/;
+const codeCache = new Map();
+/** Source text of tracked code files, joined; used to find string literals. */
+function codeText(root) {
+    const hit = codeCache.get(root);
+    if (hit !== undefined)
+        return hit;
+    let files = [];
+    try {
+        const opts = { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] };
+        files = execFileSync('git', ['ls-files'], { ...opts, stdio: [...opts.stdio] })
+            .split(/\r?\n/).filter((f) => CODE_EXTS.test(f));
+    }
+    catch {
+        files = [];
+    }
+    const parts = [];
+    for (const f of files) {
+        try {
+            parts.push(fs.readFileSync(path.join(root, f), 'utf8'));
+        }
+        catch { /* removed file */ }
+    }
+    const text = parts.join('\n');
+    codeCache.set(root, text);
+    return text;
+}
+function hasLiteral(name, root) {
+    return new RegExp(`(['"\`])${name}\\1`).test(codeText(root));
+}
+function isRuntimePath(t) {
+    const clean = t.replace(/^\.\//, '').replace(/\/$/, '');
+    if (RUNTIME_DIRS.some((d) => clean === d || clean.startsWith(`${d}/`)))
+        return true;
+    if (/^[\w.-]+\/$/.test(t))
+        return true; // a bare folder name is an example
+    return !clean.includes('/') && RUNTIME_FILES.has(clean);
+}
+const PATHY = /^[\w.@~-][\w./@~-]*$/;
+function isPathLike(t) {
+    if (t.includes('://') || SCOPED.test(t) || !PATHY.test(t) || t.startsWith('-'))
+        return false;
+    return t.includes('/') || EXTS.some((e) => t.toLowerCase().endsWith(e));
+}
+function findFile(t, root, docDir) {
+    const clean = t.replace(/^\.?\//, '');
+    for (const base of [root, docDir]) {
+        const full = path.join(base, clean);
+        if (fs.existsSync(full) && fs.statSync(full).isFile())
+            return full;
+    }
+    return null;
+}
+function pathExists(t, root, docDir) {
+    const clean = t.replace(/^\.?\//, '').replace(/\/$/, '');
+    return [root, docDir].some((b) => fs.existsSync(path.join(b, clean)));
+}
+function checkFlags(words, program) {
+    let spec = program;
+    const names = [];
+    for (const w of words.slice(1)) {
+        if (w.startsWith('-') || !spec.subs[w])
+            break;
+        spec = spec.subs[w];
+        names.push(w);
+    }
+    if (names.length === 0)
+        return null;
+    for (const w of words.slice(1)) {
+        if (!w.startsWith('-'))
+            continue;
+        const flag = w.split('=')[0];
+        if (['--help', '-h'].includes(flag) || spec.flags.includes(flag))
+            continue;
+        return `nativ ${names.join(' ')} has no option ${flag}`;
+    }
+    return null;
+}
+/** Lines of prose with their paragraph index; fenced code blocks are skipped. */
+function proseLines(text) {
+    const out = [];
+    let fenced = false;
+    let para = 0;
+    let skipNext = false;
+    let ignoring = false;
+    text.split(/\r?\n/).forEach((raw, i) => {
+        if (skipNext) {
+            skipNext = false;
+            return;
+        }
+        if (/<!--\s*nativ-check-ignore-end\s*-->/.test(raw)) {
+            ignoring = false;
+            return;
+        }
+        if (/<!--\s*nativ-check-ignore-start\s*-->/.test(raw)) {
+            ignoring = true;
+            return;
+        }
+        if (/^\s*<!--\s*nativ-check-ignore\s*-->\s*$/.test(raw)) {
+            skipNext = true;
+            return;
+        }
+        if (ignoring)
+            return;
+        if (/^\s*(```|~~~)/.test(raw)) {
+            fenced = !fenced;
+            return;
+        }
+        if (fenced)
+            return;
+        if (raw.trim() === '') {
+            para += 1;
+            return;
+        }
+        out.push({ line: i + 1, text: raw, para });
+    });
+    return out;
+}
+export function checkDocText(text, docFile, ctx) {
+    const findings = [];
+    const docDir = path.dirname(path.resolve(ctx.root, docFile));
+    const rel = path.relative(ctx.root, path.resolve(ctx.root, docFile)).split(path.sep).join('/');
+    const lines = proseLines(text);
+    const add = (line, kind, token, message) => findings.push({ file: rel, line, kind, token, message });
+    // The file a paragraph names: the first path-like token that exists.
+    const paraFile = new Map();
+    for (const l of lines) {
+        for (const m of l.text.matchAll(TOKEN)) {
+            const t = m[1].trim();
+            if (paraFile.has(l.para) || !isPathLike(t))
+                continue;
+            const f = findFile(t, ctx.root, docDir);
+            if (f)
+                paraFile.set(l.para, f);
+        }
+    }
+    for (const l of lines) {
+        for (const m of l.text.matchAll(TOKEN)) {
+            const t = m[1].trim();
+            const words = t.split(/\s+/);
+            if (words[0] === 'nativ') {
+                const bare = t.replace(/"[^"]*"|'[^']*'/g, ' ').trim().split(/\s+/);
+                const msg = checkFlags(bare, ctx.program);
+                if (msg)
+                    add(l.line, 'flag', t, msg);
+            }
+            else if (PLACEHOLDER.test(t)) {
+                const f = paraFile.get(l.para);
+                if (f && !fs.readFileSync(f, 'utf8').includes(t)) {
+                    const name = path.basename(f);
+                    add(l.line, 'placeholder', t, `${t} does not appear in ${name}, which this paragraph describes`);
+                }
+            }
+            else if (isPathLike(t)) {
+                if (!isRuntimePath(t) && !pathExists(t, ctx.root, docDir))
+                    add(l.line, 'path', t, `${t} does not exist`);
+            }
+            else {
+                const use = SETTING_USE.exec(t);
+                const name = use ? use[1] ?? use[2] : '';
+                const msg = `${name} is not read by the code or listed in .env.example`;
+                if (name && !ctx.envNames.has(name) && !hasLiteral(name, ctx.root)) {
+                    add(l.line, 'setting', t, msg);
+                }
+            }
+        }
+    }
+    return findings;
+}

package/dist/core/code-shape.d.ts

@@ -8,19 +8,24 @@ export interface CodeShapeSettings {
     mode: CodeShapeMode;
     maxLineLength: number;
     maxCommentLines: number;
+    configFallback: CodeShapeMode;
 }
 export interface CodeShapeIssue {
     file: string;
     line: number;
-    kind: 'long-line' | 'long-comment';
+    kind: 'long-line' | 'long-comment' | 'config-fallback';
+    category: 'style' | 'config';
     message: string;
 }
 export interface CodeShapeReport {
     mode: CodeShapeMode;
+    configMode: CodeShapeMode;
     issues: CodeShapeIssue[];
 }
 export declare function loadCodeShapeSettings(targetDir: string): CodeShapeSettings;
 export declare function checkFileShape(file: string, text: string, s: CodeShapeSettings): CodeShapeIssue[];
+/** Env reads that silently fall back to an empty value; reported as config findings. */
+export declare function checkConfigFallbacks(file: string, text: string): CodeShapeIssue[];
 export declare function checkCodeShape(targetDir: string, targetFiles?: string[]): CodeShapeReport;
-/** Short plain-language summary; empty string when there is nothing to report. */
+/** Short plain-language summary, config findings first; empty string when nothing to report. */
 export declare function formatCodeShapeReport(report: CodeShapeReport): string;

package/dist/core/code-shape.js

@@ -2,7 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseJsonLoose } from './enforcement.js';
 import { resolveMainRoot } from './root-resolver.js';
-const DEFAULTS = { mode: 'warn', maxLineLength: 120, maxCommentLines: 2 };
+import { scanEnvReads } from './env-reads.js';
+const DEFAULTS = { mode: 'warn', maxLineLength: 120, maxCommentLines: 2,
+    configFallback: 'warn' };
 const SOURCE_EXTENSIONS = new Set([
     '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.kt', '.dart',
     '.c', '.cc', '.cpp', '.h', '.cs', '.rb', '.php', '.swift', '.vue', '.svelte', '.css', '.scss',
@@ -18,6 +20,9 @@ export function loadCodeShapeSettings(targetDir) {
             return settings;
         if (['warn', 'block', 'off'].includes(style.mode))
             settings.mode = style.mode;
+        if (['warn', 'block', 'off'].includes(style.configFallback)) {
+            settings.configFallback = style.configFallback;
+        }
         if (Number.isInteger(style.maxLineLength) && style.maxLineLength > 0) {
             settings.maxLineLength = style.maxLineLength;
         }
@@ -79,7 +84,7 @@ export function checkFileShape(file, text, s) {
     lines.forEach((line, i) => {
         if (line.length > s.maxLineLength) {
             issues.push({
-                file, line: i + 1, kind: 'long-line',
+                file, line: i + 1, kind: 'long-line', category: 'style',
                 message: `line is ${line.length} characters (max ${s.maxLineLength})`,
             });
         }
@@ -87,17 +92,28 @@ export function checkFileShape(file, text, s) {
     for (const b of findCommentBlocks(lines)) {
         if (b.length > s.maxCommentLines && !b.exempt) {
             issues.push({
-                file, line: b.start, kind: 'long-comment',
+                file, line: b.start, kind: 'long-comment', category: 'style',
                 message: `comment block is ${b.length} lines (max ${s.maxCommentLines})`,
             });
         }
     }
     return issues;
 }
+/** Env reads that silently fall back to an empty value; reported as config findings. */
+export function checkConfigFallbacks(file, text) {
+    return scanEnvReads(text, file).filter((r) => r.fallback).map((r) => ({
+        file, line: r.line, kind: 'config-fallback', category: 'config',
+        message: `${r.name} falls back to an empty value when unset; fail loudly instead`,
+    }));
+}
 export function checkCodeShape(targetDir, targetFiles = []) {
     const settings = loadCodeShapeSettings(targetDir);
-    const report = { mode: settings.mode, issues: [] };
-    if (settings.mode === 'off')
+    const report = {
+        mode: settings.mode, configMode: settings.configFallback, issues: [],
+    };
+    const style = settings.mode !== 'off';
+    const config = settings.configFallback !== 'off';
+    if (!style && !config)
         return report;
     for (const file of targetFiles) {
         if (!isCheckable(file))
@@ -106,7 +122,11 @@ export function checkCodeShape(targetDir, targetFiles = []) {
         try {
             if (!fs.statSync(full).isFile())
                 continue;
-            report.issues.push(...checkFileShape(file, fs.readFileSync(full, 'utf8'), settings));
+            const text = fs.readFileSync(full, 'utf8');
+            if (style)
+                report.issues.push(...checkFileShape(file, text, settings));
+            if (config)
+                report.issues.push(...checkConfigFallbacks(file, text));
         }
         catch {
             // File missing or unreadable: skip.
@@ -114,15 +134,25 @@ export function checkCodeShape(targetDir, targetFiles = []) {
     }
     return report;
 }
-/** Short plain-language summary; empty string when there is nothing to report. */
-export function formatCodeShapeReport(report) {
-    if (report.mode === 'off' || report.issues.length === 0)
-        return '';
-    const total = report.issues.length;
-    const head = report.mode === 'block'
-        ? `Code shape: ${total} issue(s) must be fixed before this task can pass.`
-        : `Code shape: ${total} style warning(s). Verification is not affected.`;
-    const shown = report.issues.slice(0, MAX_SHOWN).map((i) => `  ${i.file}:${i.line} ${i.message}`);
-    const more = total > MAX_SHOWN ? [`  ...and ${total - MAX_SHOWN} more`] : [];
+function formatBlock(head, issues) {
+    const shown = issues.slice(0, MAX_SHOWN).map((i) => `  ${i.file}:${i.line} ${i.message}`);
+    const more = issues.length > MAX_SHOWN ? [`  ...and ${issues.length - MAX_SHOWN} more`] : [];
     return [head, ...shown, ...more].join('\n');
 }
+/** Short plain-language summary, config findings first; empty string when nothing to report. */
+export function formatCodeShapeReport(report) {
+    const config = report.issues.filter((i) => i.category === 'config');
+    const style = report.issues.filter((i) => i.category === 'style');
+    const blocks = [];
+    if (config.length > 0) {
+        blocks.push(formatBlock(report.configMode === 'block'
+            ? `Config: ${config.length} silent fallback(s) must be fixed before this task can pass.`
+            : `Config: ${config.length} silent fallback warning(s). Verification is not affected.`, config));
+    }
+    if (style.length > 0) {
+        blocks.push(formatBlock(report.mode === 'block'
+            ? `Code shape: ${style.length} issue(s) must be fixed before this task can pass.`
+            : `Code shape: ${style.length} style warning(s). Verification is not affected.`, style));
+    }
+    return blocks.join('\n');
+}

package/dist/core/env-reads.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Scans source text for environment-variable reads (JS/TS, Python, Go) and marks reads that
+ * silently fall back to an empty value. Language is chosen by file extension.
+ */
+export interface EnvRead {
+    name: string;
+    line: number;
+    fallback: boolean;
+}
+type Lang = 'js' | 'py' | 'go';
+export declare function langForFile(file: string): Lang | null;
+export declare function scanEnvReads(text: string, file: string): EnvRead[];
+/** Variable names read in source files, plus names declared in .env.example (no other .env*). */
+export declare function listProjectEnvNames(root: string): string[];
+export {};

package/dist/core/env-reads.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+const ALLOW_MARKER = 'nativ-allow-fallback';
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git']);
+const MAX_FILE_BYTES = 1024 * 1024;
+const Q = `['"\`]`;
+const EXT_LANG = {
+    '.js': 'js', '.jsx': 'js', '.mjs': 'js', '.cjs': 'js',
+    '.ts': 'js', '.tsx': 'js', '.mts': 'js', '.cts': 'js',
+    '.py': 'py', '.go': 'go',
+};
+const id = String.raw `([A-Za-z_]\w*)`;
+const rx = (src) => new RegExp(src, 'g');
+const PATTERNS = {
+    js: [
+        rx(String.raw `\b(?:process\.env|import\.meta\.env|Bun\.env)\.` + id),
+        rx(String.raw `\b(?:process\.env|import\.meta\.env|Bun\.env)\[\s*${Q}` + id + String.raw `${Q}\s*\]`),
+        rx(String.raw `\bDeno\.env\.get\(\s*${Q}` + id + String.raw `${Q}\s*\)`),
+    ],
+    py: [
+        rx(String.raw `\bos\.environ\[\s*${Q}` + id + String.raw `${Q}\s*\]`),
+        rx(String.raw `\bos\.(?:environ\.get|getenv)\(\s*${Q}` + id + Q),
+    ],
+    go: [rx(String.raw `\bos\.(?:Getenv|LookupEnv)\(\s*"` + id + String.raw `"\s*\)`)],
+};
+const JS_FALLBACK = /^\s*(?:\?\?|\|\|)\s*(?:''|""|``|null|undefined)(?![\w$])/;
+const PY_DEFAULT = /^\s*,\s*(?:''|""|None)\s*\)/;
+const PY_OR = /^\s*or\s+(?:''|""|None)(?![\w])/;
+const GO_CMP = /(?:[=!]=\s*""|""\s*[=!]=)/;
+export function langForFile(file) {
+    return EXT_LANG[path.extname(file).toLowerCase()] ?? null;
+}
+function isFallback(lang, rest, lines, i, call) {
+    if (lang === 'js')
+        return JS_FALLBACK.test(rest);
+    if (lang === 'py') {
+        if (call.includes('environ['))
+            return false;
+        if (rest.startsWith(')'))
+            return PY_OR.test(rest.slice(1));
+        return PY_DEFAULT.test(rest);
+    }
+    if (call.includes('LookupEnv'))
+        return false;
+    return !lines.slice(i, i + 4).some((l) => GO_CMP.test(l));
+}
+export function scanEnvReads(text, file) {
+    const lang = langForFile(file);
+    if (!lang)
+        return [];
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    lines.forEach((line, i) => {
+        const seen = new Set();
+        for (const re of PATTERNS[lang]) {
+            re.lastIndex = 0;
+            for (let m = re.exec(line); m; m = re.exec(line)) {
+                if (seen.has(m.index))
+                    continue;
+                seen.add(m.index);
+                const rest = line.slice(m.index + m[0].length);
+                const allowed = line.includes(ALLOW_MARKER);
+                const fallback = !allowed && isFallback(lang, rest, lines, i, m[0]);
+                out.push({ name: m[1], line: i + 1, fallback });
+            }
+        }
+    });
+    return out.sort((a, b) => a.line - b.line);
+}
+function gitFiles(root) {
+    const r = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], {
+        cwd: root, encoding: 'utf8',
+    });
+    if (r.status !== 0 || typeof r.stdout !== 'string')
+        return null;
+    return r.stdout.split(/\r?\n/).filter(Boolean);
+}
+function walk(root, rel = '') {
+    const out = [];
+    for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true })) {
+        if (SKIP_DIRS.has(e.name))
+            continue;
+        const next = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory())
+            out.push(...walk(root, next));
+        else if (e.isFile())
+            out.push(next);
+    }
+    return out;
+}
+function skipped(rel) {
+    return rel.split('/').some((p) => SKIP_DIRS.has(p));
+}
+function exampleNames(root) {
+    const file = path.join(root, '.env.example');
+    if (!fs.existsSync(file))
+        return [];
+    const names = [];
+    for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Za-z_]\w*)\s*=/.exec(line);
+        if (m)
+            names.push(m[1]);
+    }
+    return names;
+}
+/** Variable names read in source files, plus names declared in .env.example (no other .env*). */
+export function listProjectEnvNames(root) {
+    const names = new Set(exampleNames(root));
+    const files = (gitFiles(root) ?? walk(root)).filter((f) => !skipped(f));
+    for (const rel of files) {
+        if (!langForFile(rel))
+            continue;
+        const full = path.join(root, rel);
+        try {
+            if (fs.statSync(full).size > MAX_FILE_BYTES)
+                continue;
+            for (const r of scanEnvReads(fs.readFileSync(full, 'utf8'), rel))
+                names.add(r.name);
+        }
+        catch {
+            // unreadable or removed file: skip
+        }
+    }
+    return [...names].sort();
+}

package/dist/core/human-gate.js

@@ -7,9 +7,12 @@ export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 export function isCiEnvironment() {
-    return Boolean(process.env.CI === 'true' ||
-        process.env.GITHUB_ACTIONS === 'true' ||
-        process.env.GITLAB_CI === 'true' ||
+    // Inside a verification sandbox, CI vars are set by nativ and must not open gates
+    const sandbox = process.env.NATIV_VERIFY_SANDBOX === '1';
+    return Boolean((!sandbox &&
+        (process.env.CI === 'true' ||
+            process.env.GITHUB_ACTIONS === 'true' ||
+            process.env.GITLAB_CI === 'true')) ||
         process.env.NATIV_CI_OVERRIDE ||
         process.env.NATIV_HEADLESS_OVERRIDE === '1');
 }

package/dist/core/milestone-archive.d.ts

@@ -0,0 +1,40 @@
+import { type MasterPlan } from '../scanner/types.js';
+export declare const DEFAULT_SUITE_TIMEOUT_MS = 600000;
+/** An expected "no": the message is written for the person running the command. */
+export declare class ArchiveRefusal extends Error {
+}
+/** Seams so tests can make the read-back, the removal or the plan save fail. */
+export interface ArchiveDeps {
+    readBack?: (file: string) => string;
+    save?: (planPath: string, plan: MasterPlan) => boolean;
+    remove?: (file: string) => void;
+}
+export interface ArchiveRequest {
+    ids: string[];
+    summaries: Record<string, string>;
+    check?: string;
+    timeout?: number;
+}
+export interface ArchiveResult {
+    archived: Array<{
+        id: string;
+        file: string;
+        taskCount: number;
+    }>;
+    activeMilestoneId: string;
+    commit: string | null;
+    warnings: string[];
+}
+export interface RestoreResult {
+    id: string;
+    taskCount: number;
+    warnings: string[];
+}
+/** Ids of tasks moved out to archive files; they count as existing, completed tasks. */
+export declare function archivedTaskIds(plan: MasterPlan): string[];
+/** The plan as dependency checks should see it: archived tasks appear as completed. */
+export declare function withArchivedAsDone(plan: MasterPlan): MasterPlan;
+/** Refuses without side effects, runs the suite once outside the lock, then re-checks and commits. */
+export declare function archiveMilestones(targetDir: string, request: ArchiveRequest, deps?: ArchiveDeps): Promise<ArchiveResult>;
+/** Puts the tasks back; the archive file goes only after the plan is safely saved. */
+export declare function restoreMilestone(targetDir: string, id: string, deps?: ArchiveDeps): Promise<RestoreResult>;