archcheck 0.2.0

package/dist/emit/index.js

@@ -0,0 +1,128 @@
+/**
+ * The emit pipeline: collect → merge → write (or check).
+ *
+ * This is the half of the design that makes editor feedback work WITHOUT archcheck running. The
+ * emitted lint message carries the rule's own sentence, so the squiggle reads
+ * "domain may not import services — invert the call" rather than a rule name (LLD §1.1).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { implementedKinds } from '../contracts/index.js';
+import { RULES_JSON, renderRulesTable, replaceFencedRegion, rulesDocument, } from '../coverage/index.js';
+import { ID_LEDGER_PATH } from '../registry/ids.js';
+import { repoRelative } from '../util/paths.js';
+import { collectFragments } from './collect.js';
+import { mergeBySink } from './merge.js';
+import { checkSinks, writeSinks, } from './write.js';
+export const DEFAULT_GENERATED_DIR = 'generated';
+export function planEmit(options) {
+    const ctx = { root: options.root, rules: options.rules };
+    const { fragments, unimplemented } = collectFragments(options.rules, options.contractFor, ctx);
+    const source = repoRelative(options.root, options.configPath);
+    const files = mergeBySink(fragments, source);
+    // rules.json is DATA, so any document — or a dashboard later — can read it without archcheck
+    // knowing that document's format.
+    const document = rulesDocument(options.rules, options.coverage);
+    files.push({
+        path: RULES_JSON,
+        target: 'test',
+        content: `${JSON.stringify(document, null, 2)}\n`,
+        ruleIds: document.rules.map((rule) => rule.id),
+    });
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    const table = renderRulesTable(document);
+    const docs = [];
+    const unreadableDocs = [];
+    for (const relative of options.docs ?? []) {
+        const existing = readDocument(options.root, relative);
+        if (existing === undefined) {
+            unreadableDocs.push(relative);
+            continue;
+        }
+        const replaced = replaceFencedRegion(existing, table);
+        // No fence means the document never asked for a generated region. Not an error, and not a
+        // reason to grow one by surprise.
+        if (replaced !== undefined)
+            docs.push({ path: relative, content: replaced });
+    }
+    return {
+        files,
+        unimplemented,
+        target: { root: options.root, generatedDir: options.generatedDir ?? DEFAULT_GENERATED_DIR },
+        docs,
+        unreadableDocs,
+    };
+}
+/**
+ * What `emit` says about a rule kind it generated no configuration for.
+ *
+ * `emit` is its own command: a CI lane that runs only `archcheck emit` sees neither
+ * `RunResult.skipped` nor `Coverage.unchecked`, so without this line a `forbidden` rule emits no
+ * fragment, prints nothing, and the editor configs the rule was declared for silently lack it.
+ * Same fact `collectFragments` records as `EmitPlan.unimplemented`, read from the rules alone
+ * because the CLI holds no plan. `src/emit/emit.test.ts` → 'describeUnimplemented' pins it.
+ */
+export function describeUnimplemented(rules) {
+    const implemented = new Set(implementedKinds());
+    const kinds = [
+        ...new Set(rules.filter((rule) => rule.severity !== 'off').map((rule) => rule.kind)),
+    ]
+        .filter((kind) => !implemented.has(kind))
+        .sort();
+    if (kinds.length === 0)
+        return [];
+    const named = kinds.map((kind) => `'${kind}'`).join(', ');
+    return [
+        `warning: no configuration was generated for ${named} — no contract type implements ` +
+            `${kinds.length === 1 ? 'that kind' : 'those kinds'} yet`,
+        '  → those rules are declared, not enforced: `archcheck` reports them under skipped',
+    ];
+}
+function readDocument(root, relative) {
+    try {
+        return readFileSync(join(root, relative), 'utf8');
+    }
+    catch {
+        // Undefined means "could not read it", and whether that is news belongs to the caller:
+        // `planEmit` reports a document the manifest named, `applyEmit` and `checkEmit` treat an
+        // unreadable file as "differs from what we would write".
+        return undefined;
+    }
+}
+/** Writes the sinks, and the id ledger that makes rule ids immutable. */
+export function applyEmit(plan, ledger) {
+    const written = writeSinks(plan.target, plan.files);
+    for (const doc of plan.docs) {
+        const path = join(plan.target.root, doc.path);
+        const current = readDocument(plan.target.root, doc.path);
+        if (current === doc.content) {
+            written.push({ path: doc.path, changed: false });
+            continue;
+        }
+        writeFileSync(path, doc.content);
+        written.push({ path: doc.path, changed: true });
+    }
+    const ledgerPath = join(plan.target.root, ID_LEDGER_PATH);
+    const content = `${JSON.stringify(ledger, null, 2)}\n`;
+    mkdirSync(dirname(ledgerPath), { recursive: true });
+    writeFileSync(ledgerPath, content);
+    return { written, ledgerPath: ID_LEDGER_PATH };
+}
+export function checkEmit(plan) {
+    const stale = checkSinks(plan.target, plan.files);
+    for (const path of plan.unreadableDocs)
+        stale.push({ path, reason: 'unreadable' });
+    for (const doc of plan.docs) {
+        // Hand-editing inside the fence is the failure this catches: the region is generated, so a
+        // human edit there is lost on the next emit and disagrees with the manifest until then.
+        if (readDocument(plan.target.root, doc.path) !== doc.content) {
+            stale.push({ path: doc.path, reason: 'hand-edited' });
+        }
+    }
+    return stale;
+}
+export { collectFragments } from './collect.js';
+export { commentHeader, generatedMeta, REGENERATE_COMMAND } from './header.js';
+export { mergeBySink, SINK_PATHS, sortDeep } from './merge.js';
+export { checkSinks, describeStale, writeSinks, } from './write.js';
+//# sourceMappingURL=index.js.map

package/dist/emit/index.js.map

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

package/dist/emit/merge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Merging fragments into one file per sink.
+ *
+ * What rule this enforces: deterministic output. Keys are sorted at every depth and entries are
+ * sorted by rule id, so the same manifest produces the same bytes on every machine and every run.
+ * Without that property `emit --check` fails at random, someone disables it, and the generated
+ * files start drifting from the manifest — which is the one failure this whole pipeline exists to
+ * prevent.
+ */
+import type { Fragment, FragmentTarget } from '../types.js';
+/** Where each sink lands. One file per sink, always at the same path. */
+export declare const SINK_PATHS: Record<FragmentTarget, string>;
+export type SinkFile = {
+    /** Relative to the generated directory. */
+    path: string;
+    target: FragmentTarget;
+    content: string;
+    ruleIds: string[];
+};
+/** Sort every object key at every depth. JSON.stringify preserves insertion order. */
+export declare function sortDeep(value: unknown): unknown;
+export declare function mergeBySink(fragments: readonly Fragment[], source: string): SinkFile[];
+//# sourceMappingURL=merge.d.ts.map

package/dist/emit/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/emit/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG5D,yEAAyE;AACzE,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAMrD,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAShD;AAiCD,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAetF"}

package/dist/emit/merge.js

@@ -0,0 +1,71 @@
+import { commentHeader, generatedMeta } from './header.js';
+/** Where each sink lands. One file per sink, always at the same path. */
+export const SINK_PATHS = {
+    graph: 'graph.config.cjs',
+    lint: 'lint.overrides.json',
+    boundaries: 'boundaries.json',
+    test: 'required.json',
+    exports: 'exports.json',
+};
+/** Sort every object key at every depth. JSON.stringify preserves insertion order. */
+export function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const nested = value[key];
+        if (nested !== undefined)
+            out[key] = sortDeep(nested);
+    }
+    return out;
+}
+function jsonSink(target, fragments, source) {
+    const ruleIds = [...new Set(fragments.map((f) => f.ruleId))].sort();
+    const body = {
+        $generated: generatedMeta(source, ruleIds),
+        rules: fragments
+            .map((fragment) => ({ ruleId: fragment.ruleId, ...fragment.content }))
+            .sort((a, b) => a.ruleId.localeCompare(b.ruleId)),
+    };
+    return {
+        path: SINK_PATHS[target],
+        target,
+        content: `${JSON.stringify(sortDeep(body), null, 2)}\n`,
+        ruleIds,
+    };
+}
+function graphSink(fragments, source) {
+    const ruleIds = [...new Set(fragments.map((f) => f.ruleId))].sort();
+    const layers = fragments
+        .map((fragment) => ({ ruleId: fragment.ruleId, ...fragment.content }))
+        .sort((a, b) => a.ruleId.localeCompare(b.ruleId));
+    const body = JSON.stringify(sortDeep({ layers }), null, 2);
+    return {
+        path: SINK_PATHS.graph,
+        target: 'graph',
+        // CommonJS because this is the shape a module-graph tool's config expects to require().
+        content: `${commentHeader(source, ruleIds)}\n\nmodule.exports = ${body};\n`,
+        ruleIds,
+    };
+}
+export function mergeBySink(fragments, source) {
+    const byTarget = new Map();
+    for (const fragment of fragments) {
+        const existing = byTarget.get(fragment.target);
+        if (existing)
+            existing.push(fragment);
+        else
+            byTarget.set(fragment.target, [fragment]);
+    }
+    const files = [];
+    for (const target of Object.keys(SINK_PATHS).sort()) {
+        const group = byTarget.get(target);
+        if (!group || group.length === 0)
+            continue;
+        files.push(target === 'graph' ? graphSink(group, source) : jsonSink(target, group, source));
+    }
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+//# sourceMappingURL=merge.js.map

package/dist/emit/merge.js.map

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

package/dist/emit/write.d.ts

@@ -0,0 +1,20 @@
+import type { SinkFile } from './merge.js';
+export type EmitTarget = {
+    /** Absolute path of the repository root. */
+    root: string;
+    /** Relative to root, e.g. `generated`. */
+    generatedDir: string;
+};
+export type WrittenFile = {
+    path: string;
+    changed: boolean;
+};
+export declare function writeSinks(target: EmitTarget, files: readonly SinkFile[]): WrittenFile[];
+export type StaleFile = {
+    path: string;
+    /** `unreadable` is a document `manifest.docs` names that is not there — see `planEmit`. */
+    reason: 'missing' | 'hand-edited' | 'unreadable';
+};
+export declare function checkSinks(target: EmitTarget, files: readonly SinkFile[]): StaleFile[];
+export declare function describeStale(stale: readonly StaleFile[]): string[];
+//# sourceMappingURL=write.d.ts.map

package/dist/emit/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/emit/write.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,UAAU,GAAG;IACvB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAc7D,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,WAAW,EAAE,CAaxF;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,YAAY,CAAC;CAClD,CAAC;AAEF,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,EAAE,CAStF;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,EAAE,CAEnE"}

package/dist/emit/write.js

@@ -0,0 +1,61 @@
+/**
+ * Writing the sinks, and the staleness check.
+ *
+ * What rule this enforces: `emit --check` exits 3 — a code of its own, distinct from 1 (the code is
+ * wrong) and 2 (the config is wrong). An agent reading exit 3 knows the fix is `archcheck emit`,
+ * not an edit to any source file (LLD §6).
+ *
+ * What a caller must know: `check` re-emits into MEMORY and compares. It never writes, so running
+ * it in CI cannot mask the drift it is meant to detect.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { toPosix } from '../util/paths.js';
+function absolutePathOf(target, file) {
+    return join(target.root, target.generatedDir, file.path);
+}
+function readOrNull(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSinks(target, files) {
+    const written = [];
+    for (const file of files) {
+        const path = absolutePathOf(target, file);
+        const existing = readOrNull(path);
+        const changed = existing !== file.content;
+        if (changed) {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, file.content);
+        }
+        written.push({ path: toPosix(join(target.generatedDir, file.path)), changed });
+    }
+    return written;
+}
+export function checkSinks(target, files) {
+    const stale = [];
+    for (const file of files) {
+        const existing = readOrNull(absolutePathOf(target, file));
+        const path = toPosix(join(target.generatedDir, file.path));
+        if (existing === null)
+            stale.push({ path, reason: 'missing' });
+        else if (existing !== file.content)
+            stale.push({ path, reason: 'hand-edited' });
+    }
+    return stale;
+}
+/** A Record over the reasons, so a new reason cannot be added without a sentence for it. */
+const STALE_REASON = {
+    missing: 'has never been generated',
+    unreadable: 'is named in docs but could not be read — create it with an archcheck fence, or drop it ' +
+        'from the manifest',
+    'hand-edited': 'does not match the manifest — it was hand-edited, or the manifest changed',
+};
+export function describeStale(stale) {
+    return stale.map(({ path, reason }) => `${path} ${STALE_REASON[reason]}`);
+}
+//# sourceMappingURL=write.js.map

package/dist/emit/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/emit/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAY3C,SAAS,cAAc,CAAC,MAAkB,EAAE,IAAc;IACxD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAkB,EAAE,KAA0B;IACvE,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC1C,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,QAAQ,KAAK,IAAI,CAAC,OAAO,CAAC;QAC1C,IAAI,OAAO,EAAE,CAAC;YACZ,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAQD,MAAM,UAAU,UAAU,CAAC,MAAkB,EAAE,KAA0B;IACvE,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,UAAU,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3D,IAAI,QAAQ,KAAK,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;aAC1D,IAAI,QAAQ,KAAK,IAAI,CAAC,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4FAA4F;AAC5F,MAAM,YAAY,GAAwC;IACxD,OAAO,EAAE,0BAA0B;IACnC,UAAU,EACR,yFAAyF;QACzF,mBAAmB;IACrB,aAAa,EAAE,2EAA2E;CAC3F,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,KAA2B;IACvD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC"}

package/dist/exceptions/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Exceptions — a deliberate, owned, expiring allowance, and the only legitimate way past a rule.
+ *
+ * What rule this enforces: exceptions live in the MANIFEST, never inline. An inline suppression
+ * comment is itself a lint violation (plan 12), and this is the mechanism that makes that ban
+ * reasonable rather than merely strict — people do need exceptions, and denying them a designed
+ * route is how inline comments spread until nobody reviews any of them.
+ *
+ * Two properties make it work, and both are enforced rather than advised:
+ *   1. EXPIRY IS ENFORCED. Past the date the run fails and names the owner. An exception that
+ *      needs extending is a conversation, which is the point — one nobody has to re-justify is
+ *      just a rule that was quietly deleted.
+ *   2. ALWAYS VISIBLE. Every declared exception is reported every run, including the ones
+ *      suppressing nothing. Silent exceptions decay into permanent ones.
+ */
+import { type Result } from '../result.js';
+import type { Diagnostic, ExceptionStatus, Rule } from '../types.js';
+export type ArchitectureException = {
+    /** The rule id this allows past. */
+    rule: string;
+    /** A path glob the allowance covers. Either this or `identity` is required. */
+    path?: string | string[];
+    /** A single finding, pinned by its identity hash. */
+    identity?: string;
+    owner: string;
+    /** ISO date, YYYY-MM-DD. Enforced, not advisory. */
+    expires: string;
+    reason: string;
+};
+export declare function todayIso(now?: Date): string;
+export declare function validateExceptions(exceptions: readonly ArchitectureException[], rules: readonly Rule[]): Result<void>;
+export type AppliedExceptions = {
+    diagnostics: Diagnostic[];
+    statuses: ExceptionStatus[];
+    /** Expired exceptions. The run fails on these, naming the owner. */
+    expired: ExceptionStatus[];
+};
+/**
+ * Mark covered diagnostics as exempted, and report the state of every declared exception.
+ *
+ * An EXPIRED exception suppresses nothing: the violations it used to cover come back, and the
+ * expiry itself is reported so the failure names a person rather than only a file.
+ */
+export declare function applyExceptions(exceptions: readonly ArchitectureException[], diagnostics: readonly Diagnostic[], today?: string): AppliedExceptions;
+export declare function describeExpired(expired: readonly ExceptionStatus[]): string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/exceptions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/exceptions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAGrE,MAAM,MAAM,qBAAqB,GAAG;IAClC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAgBF,wBAAgB,QAAQ,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAEvD;AAOD,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,SAAS,qBAAqB,EAAE,EAC5C,KAAK,EAAE,SAAS,IAAI,EAAE,GACrB,MAAM,CAAC,IAAI,CAAC,CA8Bd;AAUD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,oEAAoE;IACpE,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,SAAS,qBAAqB,EAAE,EAC5C,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,KAAK,GAAE,MAAmB,GACzB,iBAAiB,CAmCnB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,EAAE,CAM7E"}

package/dist/exceptions/index.js

@@ -0,0 +1,117 @@
+/**
+ * Exceptions — a deliberate, owned, expiring allowance, and the only legitimate way past a rule.
+ *
+ * What rule this enforces: exceptions live in the MANIFEST, never inline. An inline suppression
+ * comment is itself a lint violation (plan 12), and this is the mechanism that makes that ban
+ * reasonable rather than merely strict — people do need exceptions, and denying them a designed
+ * route is how inline comments spread until nobody reviews any of them.
+ *
+ * Two properties make it work, and both are enforced rather than advised:
+ *   1. EXPIRY IS ENFORCED. Past the date the run fails and names the owner. An exception that
+ *      needs extending is a conversation, which is the point — one nobody has to re-justify is
+ *      just a rule that was quietly deleted.
+ *   2. ALWAYS VISIBLE. Every declared exception is reported every run, including the ones
+ *      suppressing nothing. Silent exceptions decay into permanent ones.
+ */
+import { err, ok } from '../result.js';
+import { matchesAny } from '../util/glob.js';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 86_400_000;
+/**
+ * A REAL calendar date, not merely a regex-shaped one. `9999-99-99` and `2030-02-30` pass the shape
+ * check, and an unreal date is the one way an exception never expires. The round trip catches both
+ * kinds of engine: one that refuses the out-of-range day, and one that rolls it over to a different
+ * date. Pinned by 'rejects an expiry that is regex-shaped but not a real calendar date'.
+ */
+function isCalendarDate(value) {
+    const parsed = new Date(`${value}T00:00:00Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+export function todayIso(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+/** Both dates are real calendar dates — `validateExceptions` refuses anything else. */
+function daysBetween(fromIso, toIso) {
+    return Math.round((Date.parse(toIso) - Date.parse(fromIso)) / DAY_MS);
+}
+export function validateExceptions(exceptions, rules) {
+    const known = new Set(rules.map((rule) => rule.id));
+    const errors = [];
+    for (const [index, exception] of exceptions.entries()) {
+        const where = `exceptions[${index}]`;
+        if (typeof exception?.rule !== 'string' || !known.has(exception.rule)) {
+            errors.push(`${where}: rule '${String(exception?.rule)}' is not defined in the manifest`);
+        }
+        if (typeof exception?.owner !== 'string' || exception.owner.trim().length === 0) {
+            errors.push(`${where}: owner is required — an unowned allowance is never re-justified`);
+        }
+        if (typeof exception?.expires !== 'string' || !ISO_DATE.test(exception.expires)) {
+            errors.push(`${where}: expires is required and must be YYYY-MM-DD — an allowance with no end is a rule quietly deleted`);
+        }
+        else if (!isCalendarDate(exception.expires)) {
+            errors.push(`${where}: expires '${exception.expires}' is not a real calendar date — a date that never arrives is an allowance that never expires`);
+        }
+        if (typeof exception?.reason !== 'string' || exception.reason.trim().length === 0) {
+            errors.push(`${where}: reason is required — the next reader has to be able to judge it`);
+        }
+        if (exception?.path === undefined && exception?.identity === undefined) {
+            errors.push(`${where}: needs a path or an identity — an exception cannot cover everything`);
+        }
+    }
+    return errors.length > 0 ? err(errors) : ok(undefined);
+}
+function covers(exception, diagnostic) {
+    if (exception.rule !== diagnostic.ruleId)
+        return false;
+    if (exception.identity !== undefined)
+        return exception.identity === diagnostic.identity;
+    if (exception.path === undefined)
+        return false;
+    const globs = typeof exception.path === 'string' ? [exception.path] : exception.path;
+    return matchesAny(globs, diagnostic.file);
+}
+/**
+ * Mark covered diagnostics as exempted, and report the state of every declared exception.
+ *
+ * An EXPIRED exception suppresses nothing: the violations it used to cover come back, and the
+ * expiry itself is reported so the failure names a person rather than only a file.
+ */
+export function applyExceptions(exceptions, diagnostics, today = todayIso()) {
+    // ONE mechanism for both halves. Suppression used to compare the ISO strings while expiry parsed
+    // them, so `expires: '9999-99-99'` suppressed forever and reported NaN days left — property 1 of
+    // this module, silently untrue. Both now ask this predicate, so they cannot disagree. Written as
+    // `!(… >= 0)` so an unparseable date reads as EXPIRED rather than as a permanent allowance; only
+    // a caller bypassing `validateExceptions` can produce one. Pinned by 'suppression and expiry are
+    // one mechanism, so they never disagree'.
+    const isExpired = (exception) => !(daysBetween(today, exception.expires) >= 0);
+    const counts = new Map();
+    const marked = diagnostics.map((diagnostic) => {
+        const index = exceptions.findIndex((exception) => !isExpired(exception) && covers(exception, diagnostic));
+        if (index === -1)
+            return diagnostic;
+        counts.set(index, (counts.get(index) ?? 0) + 1);
+        return { ...diagnostic, exempted: true };
+    });
+    const statuses = exceptions.map((exception, index) => {
+        const daysLeft = daysBetween(today, exception.expires);
+        return {
+            ruleId: exception.rule,
+            owner: exception.owner,
+            expires: exception.expires,
+            // The expiry date itself is the last day it holds, so "expired" means strictly past it.
+            expired: isExpired(exception),
+            daysLeft,
+            reason: exception.reason,
+            suppressed: counts.get(index) ?? 0,
+        };
+    });
+    return { diagnostics: marked, statuses, expired: statuses.filter((s) => s.expired) };
+}
+export function describeExpired(expired) {
+    return expired.flatMap((status) => [
+        `exception expired ${status.expires} (${-status.daysLeft} day(s) ago): ${status.ruleId}`,
+        `  owner: ${status.owner} — ${status.reason}`,
+        '  → extend it with a new date and a re-stated reason, or fix the violations and remove it',
+    ]);
+}
+//# sourceMappingURL=index.js.map

package/dist/exceptions/index.js.map

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

package/dist/fs/index.d.ts

@@ -0,0 +1,12 @@
+export type FileSystem = {
+    /** Repo-relative POSIX path. */
+    exists(path: string): boolean;
+    /** Returns undefined rather than throwing — a missing file is an answer, not a failure. */
+    read(path: string): string | undefined;
+    /** Repo-relative POSIX paths matching the globs, sorted. */
+    glob(patterns: string | string[]): string[];
+};
+export declare function createNodeFileSystem(root: string): FileSystem;
+/** The twin. Same contract, no disk. */
+export declare function createMemoryFileSystem(files: Record<string, string>): FileSystem;
+//# sourceMappingURL=index.d.ts.map

package/dist/fs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fs/index.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,UAAU,GAAG;IACvB,gCAAgC;IAChC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,2FAA2F;IAC3F,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC,4DAA4D;IAC5D,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;CAC7C,CAAC;AAIF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CA2C7D;AAED,wCAAwC;AACxC,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,UAAU,CAUhF"}

package/dist/fs/index.js

@@ -0,0 +1,78 @@
+/**
+ * The filesystem, behind one interface.
+ *
+ * What rule this enforces: the same twin discipline archcheck asks of its consumers. The memory
+ * implementation is what lets the structure tests run without touching disk, and the conformance
+ * test runs BOTH implementations against one fixture and asserts identical findings — which is
+ * the only thing that proves the twin is a twin rather than a second, subtly different tool.
+ *
+ * What a caller must know: every path is repo-relative POSIX, in and out. The Node implementation
+ * holds the one absolute root; nothing above this layer ever sees one.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { matchesAny } from '../util/glob.js';
+import { toPosix } from '../util/paths.js';
+const IGNORED = new Set(['node_modules', '.git', 'dist', '.archcheck']);
+export function createNodeFileSystem(root) {
+    let listing;
+    const walk = () => {
+        if (listing)
+            return listing;
+        const out = [];
+        const visit = (relative) => {
+            let entries;
+            try {
+                entries = readdirSync(join(root, relative));
+            }
+            catch {
+                return; // an unreadable directory is empty as far as a rule is concerned
+            }
+            for (const entry of entries) {
+                if (IGNORED.has(entry))
+                    continue;
+                const next = relative === '' ? entry : `${relative}/${entry}`;
+                try {
+                    if (statSync(join(root, next)).isDirectory())
+                        visit(next);
+                    else
+                        out.push(next);
+                }
+                catch {
+                    // a vanished entry between readdir and stat is simply not there
+                }
+            }
+        };
+        visit('');
+        listing = out.sort();
+        return listing;
+    };
+    return {
+        exists: (path) => existsSync(join(root, toPosix(path))),
+        read: (path) => {
+            try {
+                return readFileSync(join(root, toPosix(path)), 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        },
+        glob: (patterns) => {
+            const globs = typeof patterns === 'string' ? [patterns] : patterns;
+            return walk().filter((path) => matchesAny(globs, path));
+        },
+    };
+}
+/** The twin. Same contract, no disk. */
+export function createMemoryFileSystem(files) {
+    const paths = Object.keys(files).sort();
+    return {
+        exists: (path) => Object.hasOwn(files, toPosix(path)),
+        read: (path) => files[toPosix(path)],
+        glob: (patterns) => {
+            const globs = typeof patterns === 'string' ? [patterns] : patterns;
+            return paths.filter((path) => matchesAny(globs, path));
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/fs/index.js.map

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

package/dist/graph/cache.d.ts

@@ -0,0 +1,12 @@
+import type { FileFacts } from './types.js';
+export declare const CACHE_DIR = ".archcheck/cache";
+export declare function hashContent(content: string): string;
+export type FactsCache = {
+    get(file: string, contentHash: string): FileFacts | undefined;
+    set(file: string, contentHash: string, facts: FileFacts): void;
+    flush(): void;
+};
+/** A cache that remembers nothing — the default when a run has nowhere to write. */
+export declare function createNullCache(): FactsCache;
+export declare function createFactsCache(root: string, fingerprint: string): FactsCache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/graph/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/graph/cache.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAQ,SAAS,EAAE,MAAM,YAAY,CAAC;AAElD,eAAO,MAAM,SAAS,qBAAqB,CAAC;AAE5C,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAMD,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/D,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAUF,oFAAoF;AACpF,wBAAgB,eAAe,IAAI,UAAU,CAE5C;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAyC9E"}