devflow-kit 2.4.0 → 3.0.0

package/dist/core/evidence-policy.js

@@ -0,0 +1,363 @@
+/**
+ * The CLI's view of the evidence policy — a typed seam onto the package's own
+ * `resolve-evidence-policy.cjs`, never a second implementation of it.
+ *
+ * D-POLICY-CJS-SEAM: the resolver is plain CommonJS under src/assets/scripts/,
+ * outside every tsconfig (PF-043, PF-069), so the interfaces below are
+ * TRANSCRIBED from its JSDoc typedefs and are the only shape authority on this
+ * side — open those typedefs before changing anything here. The module is loaded
+ * with `require()` from `scriptsDir()`, which resolves under the package root both
+ * from `dist/cli.js` and under vitest (`package.json` `files` ships src/assets/),
+ * so the CLI and the resolver it runs are always the same version. The installed
+ * `~/.devflow/scripts` copy is never loaded: it may be older than this CLI. There
+ * is deliberately no TypeScript copy of the parser, the fold or the grammar.
+ *
+ * The same seam loads the sibling `resolve-settings.cjs` (loadSettingsModule),
+ * the local resolver of the per-repository settings layer — `.devflow/project.json`,
+ * the personal `.devflow/config.json` and the machine manifest. Its shapes are
+ * transcribed the same way, and there is no TypeScript copy of its fold either.
+ * It also loads the shared strict parser both resolvers use,
+ * `lib/project-config.cjs` (loadProjectConfigLib), so the CLI judges a config
+ * file's bytes exactly as the resolvers do.
+ *
+ * D-POLICY-NO-WRITE (applies ADR-024): `.devflow/project.json` is team-owned, and
+ * devflow never writes or replaces a shared file it cannot prove it wrote. This
+ * module therefore imports no fs API; the CLI only PRINTS the bytes a team may
+ * choose to commit (`evidencePolicySuggestion`, and the migration lines of
+ * `repoComplianceStatusLines`), all from the settings resolver's project.json
+ * serializer.
+ *
+ * D-POLICY-JSON-RETIRED: the evidence resolver never parses `.devflow/policy.json`;
+ * at a source whose project.json has no `evidence`, the file's presence alone
+ * resolves `required` (see the resolver's own note). This side neither reads nor
+ * serializes it — it only names it in the migration hint.
+ */
+import { createRequire } from 'module';
+import { join } from 'path';
+import { scriptsDir } from './assets.js';
+// ── Transcribed shapes (resolve-evidence-policy.cjs JSDoc) ─────────────────────
+/** Basename of the resolver under src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const RESOLVER_SCRIPT_NAME = 'resolve-evidence-policy.cjs';
+/** Basename of the settings resolver under src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const SETTINGS_SCRIPT_NAME = 'resolve-settings.cjs';
+/** The shared strict config parser, relative to src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const PROJECT_CONFIG_LIB_NAME = join('lib', 'project-config.cjs');
+/** The team file the CLI suggests committing, relative to a repository root. */
+const PROJECT_FILE = '.devflow/project.json';
+/** The retired team file project.json's `evidence` replaces, relative to a repository root. */
+const RETIRED_POLICY_FILE = '.devflow/policy.json';
+/**
+ * Every key of EvidencePolicyModule and the runtime kind the loader requires of
+ * it. `satisfies` makes the compiler reject an interface key missing here.
+ */
+export const EVIDENCE_POLICY_MODULE_SURFACE = Object.freeze({
+    POLICIES: 'string-array',
+    SOURCES: 'string-array',
+    WARNINGS: 'string-array',
+    MECHANISM_INPUTS: 'object',
+    OUTPUT_LINE_RE: 'regexp',
+    FAIL_CLOSED_LINE: 'string',
+    complianceDefault: 'function',
+    resolve: 'function',
+});
+/** Every key of SettingsModule and the runtime kind the loader requires of it. */
+export const SETTINGS_MODULE_SURFACE = Object.freeze({
+    SETTINGS_LINE_RE: 'regexp',
+    SETTINGS_FAIL_CLOSED_LINE: 'string',
+    resolveSettings: 'function',
+    serializeProjectSuggestion: 'function',
+});
+/** Every key of ProjectConfigLib and the runtime kind the loader requires of it. */
+export const PROJECT_CONFIG_LIB_SURFACE = Object.freeze({
+    MAX_CONFIG_BYTES: 'number',
+    decodeConfigBytes: 'function',
+    readBoundedRegularFile: 'function',
+    collectDuplicateKeyPaths: 'function',
+});
+function hasKind(value, kind) {
+    switch (kind) {
+        case 'string-array': return Array.isArray(value) && value.every(v => typeof v === 'string');
+        case 'object': return typeof value === 'object' && value !== null;
+        case 'regexp': return value instanceof RegExp;
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number' && Number.isFinite(value);
+        case 'function': return typeof value === 'function';
+        default: {
+            const exhaustive = kind;
+            return exhaustive;
+        }
+    }
+}
+/** Surface keys that are absent or of the wrong kind on `value`, in surface order. */
+function surfaceMismatches(value, surface) {
+    if (typeof value !== 'object' || value === null)
+        return Object.keys(surface);
+    const record = value;
+    return Object.entries(surface)
+        .filter(([key, kind]) => !hasKind(record[key], kind))
+        .map(([key]) => key);
+}
+/**
+ * require() one package script and shape-check it against `surface`. Never
+ * throws: a missing file is `not-found`; a module that throws on load or lacks a
+ * surface key is `unusable`. The caller's type parameter is justified by the
+ * surface check, which `satisfies` ties to the interface's keys.
+ */
+function loadScript(file, surface) {
+    let loaded;
+    try {
+        loaded = createRequire(import.meta.url)(file);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'MODULE_NOT_FOUND')
+            return { ok: false, error: { kind: 'not-found', path: file } };
+        const detail = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: { kind: 'unusable', path: file, detail } };
+    }
+    const mismatches = surfaceMismatches(loaded, surface);
+    if (mismatches.length > 0) {
+        return { ok: false, error: { kind: 'unusable', path: file, detail: `missing or mistyped: ${mismatches.join(', ')}` } };
+    }
+    return { ok: true, value: loaded };
+}
+/**
+ * Load the evidence resolver from `dir` (default: the package's own scripts
+ * directory) and shape-check its surface.
+ */
+export function loadEvidencePolicyModule(dir = scriptsDir()) {
+    return loadScript(join(dir, RESOLVER_SCRIPT_NAME), EVIDENCE_POLICY_MODULE_SURFACE);
+}
+/**
+ * Load the settings resolver from `dir` (default: the package's own scripts
+ * directory) and shape-check its surface. A `resolveSettings()` call makes one
+ * local `git` call and no network call (D-SETTINGS-LOCAL-ONLY).
+ */
+export function loadSettingsModule(dir = scriptsDir()) {
+    return loadScript(join(dir, SETTINGS_SCRIPT_NAME), SETTINGS_MODULE_SURFACE);
+}
+/**
+ * Load the shared strict config parser from `dir` (default: the package's own
+ * scripts directory) and shape-check its surface.
+ */
+export function loadProjectConfigLib(dir = scriptsDir()) {
+    return loadScript(join(dir, PROJECT_CONFIG_LIB_NAME), PROJECT_CONFIG_LIB_SURFACE);
+}
+// ── Presentation (pure) ────────────────────────────────────────────────────────
+/** `Evidence policy: <policy> (source: <source>)`, plus ` [warn: a, b]` when warnings exist. */
+export function formatEvidencePolicyStatus(r) {
+    const warn = r.warnings.length > 0 ? ` [warn: ${r.warnings.join(', ')}]` : '';
+    return `Evidence policy: ${r.policy} (source: ${r.source})${warn}`;
+}
+/**
+ * The line shown in place of a policy when the resolver cannot be loaded. The
+ * remedy is a package reinstall: the CLI loads the package's own copy, which
+ * `devflow init` does not restore.
+ */
+export function formatEvidencePolicyUnavailable(error) {
+    switch (error.kind) {
+        case 'not-found': return 'Evidence policy: unavailable (resolver not found — reinstall devflow-kit)';
+        case 'unusable': return 'Evidence policy: unavailable (resolver failed to load — reinstall devflow-kit)';
+        default: {
+            const exhaustive = error;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * The `compliance --status` line: the resolved policy for `opts.dir`, or the
+ * unavailable line when the loader failed — that line is the whole handling
+ * (ADR-028). The caller passes the compliance state it already read, so the
+ * manifest is never read twice. `resolve()` makes at most three `gh` calls and
+ * bounds every subprocess with a timeout, so an offline machine degrades to a
+ * flagged result rather than a hang.
+ */
+export function evidencePolicyStatusLine(loaded, opts) {
+    if (!loaded.ok)
+        return formatEvidencePolicyUnavailable(loaded.error);
+    return formatEvidencePolicyStatus(loaded.value.resolve(opts));
+}
+/**
+ * The frameworks a compliance state names, for the suggestion: the raw list when
+ * the state is well-formed, else none. The settings resolver's serializer
+ * normalizes and drops unknown ids, so no id reaches the printed bytes unchecked.
+ */
+function suggestedFrameworks(complianceState) {
+    if (typeof complianceState !== 'object' || complianceState === null)
+        return [];
+    const frameworks = complianceState.frameworks;
+    return Array.isArray(frameworks) && frameworks.every(f => typeof f === 'string') ? frameworks : [];
+}
+/**
+ * What `--enable`/`--set` print when compliance is on: the keys to add to a
+ * repository's `.devflow/project.json` on its default branch — merged into the
+ * file when it already has one, never replacing it — to hold every developer to
+ * what this machine now gets by default: the required evidence policy and this
+ * machine's frameworks. Returned only when the evidence resolver's own
+ * `complianceDefault` says `required` (compliance enabled, at any framework
+ * count); `null` otherwise. The bytes come
+ * from the settings resolver's `serializeProjectSuggestion`, which returns them
+ * only when they read back through the shared parser as exactly what was asked.
+ * Nothing is written (D-POLICY-NO-WRITE, applies ADR-024).
+ */
+export function evidencePolicySuggestion(complianceState, policy, settings) {
+    if (policy.complianceDefault(complianceState) !== 'required')
+        return null;
+    const body = settings.serializeProjectSuggestion({
+        evidence: 'required',
+        compliance: suggestedFrameworks(complianceState),
+    });
+    if (body === null)
+        return null;
+    return [
+        'Compliance is enabled on this machine, so repositories without a committed',
+        'evidence setting default to the required evidence policy here. To apply it for',
+        `everyone working in a repository, add these keys to its ${PROJECT_FILE} on its`,
+        'default branch — merged into the file when it already has one, never replacing it:',
+        '',
+        `${body}`,
+        'devflow never writes this file: the team owns it, and once committed it applies',
+        'repo-wide.',
+    ].join('\n');
+}
+// ── The settings layer, for `--status` (pure) ──────────────────────────────────
+/** A repo layer's file, as a `--status` line names it. */
+export function settingsSourceFile(source) {
+    switch (source) {
+        case 'project': return PROJECT_FILE;
+        case 'personal': return '.devflow/config.json';
+        default: {
+            const exhaustive = source;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * The effective state of a feature switch in this repository, ONLY when a repo
+ * layer narrows it — `disabled (.devflow/project.json)` — and null otherwise, so a
+ * `--status` whose machine switch alone decides prints exactly what it always has
+ * (D-FEATURES-NARROW-ONLY). A repository file that exists but is unreadable fails
+ * every field closed but the compliance lens, and a switch that closed off is
+ * labelled with that file —
+ * `disabled (.devflow/project.json is unreadable)` — since commands act on it. Any
+ * other failure (the resolver failed to load, or git could not answer) yields
+ * null: it knows nothing about this repository.
+ */
+export function narrowedSwitchLabel(loaded, opts, feature) {
+    if (!loaded.ok)
+        return null;
+    const settings = loaded.value.resolveSettings(opts);
+    if (!settings.ok) {
+        if (settings.unreadable === null || settings.switches[feature].on)
+            return null;
+        return `disabled (${settingsSourceFile(settings.unreadable)} is unreadable)`;
+    }
+    const state = settings.switches[feature];
+    if (state.on || state.source === 'machine')
+        return null;
+    return `disabled (${settingsSourceFile(state.source)})`;
+}
+/**
+ * The tracker in effect in the repository at `opts.dir`, ONLY when a repository
+ * layer decides it — its committed project.json, or the personal config.json
+ * narrowing — and null otherwise. A machine whose own selection (or the github
+ * default) decides gets null, so `tracker --status` prints exactly what it always
+ * has there. So does a resolver that failed to load or failed closed: it knows
+ * nothing about this repository, and a fail-closed `github` is not a selection
+ * anyone made.
+ */
+export function repoTrackerSelection(loaded, opts) {
+    if (!loaded.ok)
+        return null;
+    const settings = loaded.value.resolveSettings(opts);
+    if (!settings.ok)
+        return null;
+    const source = settings.trackerSource;
+    if (source !== 'project' && source !== 'personal')
+        return null;
+    return { provider: settings.tracker, source };
+}
+/** A declared id list as a `--status` line shows it. */
+function idsLabel(ids) {
+    return ids.length > 0 ? ids.join(', ') : 'generic controls only';
+}
+/**
+ * The `compliance --status` lines about the repository in `opts.dir`, mirroring
+ * the resolver's lens fold (D-LENS-UNION: machine ∪ default branch ∪ worktree):
+ * the ids this checkout's project.json declares (`generic controls only` for an
+ * empty or malformed list), the ids the default branch's copy declares, the
+ * effective lens those add up to with the machine's, and a migration hint while
+ * the retired policy file is in the working tree.
+ *
+ * A broken file affects only the keys it owns. An unreadable project.json is a
+ * malformed declaration — generic — and says so, naming the file; an unreadable
+ * config.json owns no compliance, so the lines are those of a readable one. Empty
+ * when the resolver is unavailable or failed closed for any other reason, or no
+ * repository layer declares anything and there is no policy file — the status
+ * output is then unchanged.
+ *
+ * The hint states the rule (D-POLICY-JSON-RETIRED): the file is not read, and
+ * while project.json has no `evidence` its presence holds the repository at
+ * `required`. The value is not read either, so the hint shows the project.json
+ * line for each value the file may hold, from the settings resolver's serializer.
+ */
+export function repoComplianceStatusLines(loaded, opts) {
+    if (!loaded.ok)
+        return [];
+    const settings = loaded.value.resolveSettings(opts);
+    if (!settings.ok && settings.unreadable === null)
+        return [];
+    const lines = [];
+    if (settings.unreadable === 'project') {
+        lines.push(`Repository: generic controls only (${PROJECT_FILE} is unreadable)`);
+    }
+    else if (settings.repoCompliance !== null) {
+        lines.push(`Repository: ${idsLabel(settings.repoCompliance)} (${PROJECT_FILE})`);
+    }
+    if (settings.defaultBranchCompliance !== null) {
+        lines.push(`Default branch: ${idsLabel(settings.defaultBranchCompliance)} (its ${PROJECT_FILE})`);
+    }
+    if (lines.length > 0) {
+        const lens = settings.compliance;
+        lines.push(`Effective here: ${lens.enabled ? idsLabel(lens.frameworks) : 'off'} (this machine + the default branch + this checkout)`);
+    }
+    if (settings.retiredPolicyFile)
+        lines.push(...retiredPolicyHint(loaded.value));
+    return lines;
+}
+/**
+ * The warning a `--status` prints when this checkout's `.devflow/config.json` is
+ * tracked by git, or null (D-PERSONAL-UNTRACKED). The resolver ignores such a file
+ * and says so on stderr, but prompts run it with stderr discarded, so a status
+ * command is where the user sees why their personal settings have no effect.
+ */
+export function personalConfigTrackedWarning(loaded, opts) {
+    if (!loaded.ok)
+        return null;
+    if (!loaded.value.resolveSettings(opts).personalTracked)
+        return null;
+    const file = settingsSourceFile('personal');
+    return `${file} is tracked by git, so devflow ignores it — it holds personal settings. ` +
+        `Untrack it with: git rm --cached ${file}`;
+}
+/** The policies the hint maps, in the order it prints them. */
+const HINT_POLICIES = ['standard', 'required'];
+/**
+ * The migration hint for a working tree holding the retired policy file: what the
+ * file does now, and the project.json line that states each value it may hold.
+ * A value whose line the serializer refuses is left out rather than hand-built.
+ */
+function retiredPolicyHint(settings) {
+    const mappings = HINT_POLICIES.flatMap((policy) => {
+        const body = settings.serializeProjectSuggestion({ evidence: policy });
+        return body === null ? [] : [`              ${policy.padEnd(8)}  →  ${body.trimEnd()}`];
+    });
+    return [
+        `Migration:  ${RETIRED_POLICY_FILE} is not read. While ${PROJECT_FILE} has no "evidence",`,
+        '            its presence alone holds this repository at required. Add its value to',
+        `            ${PROJECT_FILE} as "evidence", and keep ${RETIRED_POLICY_FILE} until every`,
+        `            teammate runs devflow 3.0 or later; only then delete it:`,
+        ...mappings,
+    ];
+}
+//# sourceMappingURL=evidence-policy.js.map