codictator 0.0.0 → 0.1.2

package/dist/features/arch/codictator-modules.js

@@ -0,0 +1,180 @@
+export const CODICTATOR_PROFILE = "app";
+export const CODICTATOR_MODULES = [
+    { name: "kernel", path: "src/kernel/**", kind: "kernel", dependsOn: [] },
+    {
+        name: "config",
+        path: "src/features/config/**",
+        kind: "feature",
+        dependsOn: ["kernel"],
+    },
+    {
+        name: "engine",
+        path: "src/features/engine/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "audit"],
+    },
+    {
+        name: "packs",
+        path: "src/features/packs/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine"],
+    },
+    {
+        name: "adapters",
+        path: "src/features/adapters/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine", "steering"],
+    },
+    {
+        name: "steering",
+        path: "src/features/steering/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine", "workflow"],
+    },
+    {
+        name: "security",
+        path: "src/features/security/**",
+        kind: "feature",
+        dependsOn: ["kernel", "engine"],
+    },
+    {
+        name: "deps",
+        path: "src/features/deps/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine"],
+    },
+    {
+        name: "records",
+        path: "src/features/records/**",
+        kind: "feature",
+        dependsOn: ["kernel", "engine"],
+    },
+    {
+        name: "testing",
+        path: "src/features/testing/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine"],
+    },
+    {
+        name: "arch",
+        path: "src/features/arch/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine"],
+    },
+    {
+        name: "workflow",
+        path: "src/features/workflow/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine", "testing", "audit"],
+    },
+    {
+        name: "remediation",
+        path: "src/features/remediation/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine", "deps", "arch", "workflow"],
+    },
+    {
+        name: "integrity",
+        path: "src/features/integrity/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine"],
+    },
+    {
+        name: "ci",
+        path: "src/features/ci/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "engine"],
+    },
+    {
+        name: "generator",
+        path: "src/features/generator/**",
+        kind: "feature",
+        dependsOn: ["kernel", "config", "packs", "llm"],
+    },
+    {
+        name: "llm",
+        path: "src/features/llm/**",
+        kind: "feature",
+        dependsOn: ["kernel"],
+    },
+    {
+        name: "audit",
+        path: "src/features/audit/**",
+        kind: "feature",
+        dependsOn: ["kernel"],
+    },
+    {
+        name: "builtin-packs/core",
+        path: "src/builtin-packs/core/**",
+        dependsOn: [
+            "kernel",
+            "engine",
+            "security",
+            "deps",
+            "records",
+            "testing",
+            "arch",
+            "workflow",
+            "integrity",
+            "steering",
+            "ci",
+        ],
+    },
+    {
+        name: "builtin-packs/typescript",
+        path: "src/builtin-packs/typescript/**",
+        dependsOn: [
+            "kernel",
+            "engine",
+            "security",
+            "deps",
+            "records",
+            "testing",
+            "arch",
+            "workflow",
+            "integrity",
+            "steering",
+            "ci",
+        ],
+    },
+    {
+        name: "builtin-packs/dotnet",
+        path: "src/builtin-packs/dotnet/**",
+        dependsOn: [
+            "kernel",
+            "engine",
+            "security",
+            "deps",
+            "records",
+            "testing",
+            "arch",
+            "workflow",
+            "integrity",
+            "steering",
+            "ci",
+        ],
+    },
+    {
+        name: "builtin-packs/python",
+        path: "src/builtin-packs/python/**",
+        dependsOn: [
+            "kernel",
+            "engine",
+            "security",
+            "deps",
+            "records",
+            "testing",
+            "arch",
+            "workflow",
+            "integrity",
+            "steering",
+            "ci",
+        ],
+    },
+    {
+        name: "cli",
+        path: "src/cli/**",
+        kind: "composition",
+        dependsOn: ["*"],
+    },
+];

package/dist/features/arch/cycle-walk.d.ts

@@ -0,0 +1 @@
+export declare function findModuleCycle(names: ReadonlyArray<string>, depends: ReadonlyMap<string, ReadonlyArray<string>>, shouldSkip?: (dep: string) => boolean): Array<string> | undefined;

package/dist/features/arch/cycle-walk.js

@@ -0,0 +1,36 @@
+// SPEC §4.11: shared depth-first cycle walk over a module dependency map.
+// Both the evaluation-path check (checks.ts) and the config validation
+// (module-map-validation.ts) judge acyclicity the same way; this single
+// helper keeps the two call sites behavior-identical.
+export function findModuleCycle(names, depends, shouldSkip) {
+    const visiting = new Set();
+    const done = new Set();
+    const walk = (name, trail) => {
+        if (done.has(name)) {
+            return undefined;
+        }
+        if (visiting.has(name)) {
+            return [...trail.slice(trail.indexOf(name)), name];
+        }
+        visiting.add(name);
+        for (const dep of depends.get(name) ?? []) {
+            if (shouldSkip?.(dep) === true) {
+                continue;
+            }
+            const found = walk(dep, [...trail, name]);
+            if (found !== undefined) {
+                return found;
+            }
+        }
+        visiting.delete(name);
+        done.add(name);
+        return undefined;
+    };
+    for (const name of names) {
+        const found = walk(name, []);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return undefined;
+}

package/dist/features/arch/edge-checks.d.ts

@@ -0,0 +1,13 @@
+import type { Finding } from "../engine/index.ts";
+import type { ModuleNode } from "./index.ts";
+import { type ArchDenyRule } from "./module-mapping.ts";
+export interface ResolvedEdge {
+    readonly from: string;
+    readonly line: number;
+    readonly to: string;
+    readonly fromMod: ModuleNode | undefined;
+    readonly toMod: ModuleNode | undefined;
+    readonly external: "entry" | "deep" | undefined;
+}
+export declare function resolveEdge(modules: ReadonlyArray<ModuleNode>, from: string, line: number, spec: string): ResolvedEdge;
+export declare function checkResolvedEdge(edge: ResolvedEdge, profile: string, layerDirs: ReadonlyArray<string>, deny: ReadonlyArray<ArchDenyRule>): Array<Finding>;

package/dist/features/arch/edge-checks.js

@@ -0,0 +1,186 @@
+import { isArchProfile } from "./arch-profiles.js";
+import { assignModule, isBuiltinSpecifier, moduleBase, normalizeSeparators, resolveImportTarget, } from "./graph.js";
+import { layerMayImport, resolveLayer } from "./layer-rules.js";
+import { dependsAllowed, isPublicEntryTarget, mappedFinding, moduleEntry, profileAllowsEdge, } from "./module-mapping.js";
+function isExternalEntrySpecifier(spec) {
+    const target = normalizeSeparators(spec);
+    if (target.startsWith("@")) {
+        const rest = target.slice(1);
+        const slash = rest.indexOf("/");
+        if (slash < 0) {
+            return true;
+        }
+        return rest.indexOf("/", slash + 1) < 0;
+    }
+    return !target.includes("/");
+}
+// A bare specifier with a subpath is a deep import past the package entry
+// (SPEC §4.11 EC-9); built-ins stay external nodes for the item-3 scan.
+function boundaryFinding(from, line, message) {
+    return {
+        ruleId: "core/arch-boundaries",
+        path: from,
+        line,
+        message,
+        remediation: "Declare the edge in config.architecture modules[].dependsOn, or remove the import.",
+    };
+}
+function entryFinding(from, line, target, entry) {
+    return {
+        ruleId: "core/arch-public-entry",
+        path: from,
+        line,
+        message: `cross-module import targets ${target}, outside the public entry ${entry}`,
+        remediation: `Import from the module entry ${entry}, or move the shared code there.`,
+    };
+}
+export function resolveEdge(modules, from, line, spec) {
+    const source = normalizeSeparators(from);
+    const raw = normalizeSeparators(spec);
+    if (raw === "dynamic:expr") {
+        return {
+            from: source,
+            line,
+            to: raw,
+            fromMod: undefined,
+            toMod: undefined,
+            external: undefined,
+        };
+    }
+    const resolved = resolveImportTarget(modules, source, raw);
+    const fromMod = assignModule(modules, source);
+    if (isBuiltinSpecifier(raw)) {
+        return {
+            from: source,
+            line,
+            to: resolved,
+            fromMod,
+            toMod: undefined,
+            external: "entry",
+        };
+    }
+    const assigned = assignModule(modules, resolved);
+    if (assigned !== undefined) {
+        return {
+            from: source,
+            line,
+            to: resolved,
+            fromMod,
+            toMod: assigned,
+            external: undefined,
+        };
+    }
+    if (isRepoPath(resolved) ||
+        raw.startsWith("./") ||
+        raw.startsWith("../") ||
+        raw.startsWith("/")) {
+        return {
+            from: source,
+            line,
+            to: resolved,
+            fromMod,
+            toMod: undefined,
+            external: undefined,
+        };
+    }
+    if (isExternalEntrySpecifier(raw)) {
+        return {
+            from: source,
+            line,
+            to: resolved,
+            fromMod,
+            toMod: undefined,
+            external: "entry",
+        };
+    }
+    return {
+        from: source,
+        line,
+        to: resolved,
+        fromMod,
+        toMod: undefined,
+        external: "deep",
+    };
+}
+function isRepoPath(value) {
+    return value.startsWith("src/");
+}
+// SPEC §4.11.5 EC-5: a non-literal dynamic target is unresolvable. The
+// finding blocks in kernel and domain code and advises elsewhere.
+function dynamicFinding(edge, fromMod) {
+    const strict = fromMod?.kind === "kernel";
+    return {
+        ruleId: "core/arch-boundaries",
+        code: "unresolvable-dynamic-import",
+        path: edge.from,
+        line: edge.line,
+        message: strict
+            ? `unresolvable dynamic import in ${fromMod?.name ?? "unknown"}: kernel code must use static imports`
+            : `unresolvable dynamic import at ${edge.from}:${edge.line}: the arch guard cannot judge a non-literal target`,
+        remediation: "Replace the expression with a literal specifier so the import graph can resolve it.",
+    };
+}
+function layerFinding(from, line, fromLayer, toLayer) {
+    return {
+        ruleId: "core/arch-boundaries",
+        path: from,
+        line,
+        message: `layer ${fromLayer} must not import layer ${toLayer}`,
+        remediation: "Point the import down the layer direction (domain <- application <- infrastructure/ui), or move the shared code.",
+    };
+}
+function checkLayerEdge(edge, fromMod, toMod, profile, layerDirs) {
+    if (fromMod.name !== toMod.name || layerDirs.length === 0) {
+        return undefined;
+    }
+    const base = moduleBase(fromMod);
+    const fromLayer = resolveLayer(edge.from, base, layerDirs);
+    const toLayer = resolveLayer(edge.to, base, layerDirs);
+    if (fromLayer === undefined || toLayer === undefined) {
+        return undefined;
+    }
+    if (fromLayer !== toLayer &&
+        !layerMayImport(fromLayer, toLayer, isArchProfile(profile) ? profile : "app")) {
+        return layerFinding(edge.from, edge.line, fromLayer, toLayer);
+    }
+    return undefined;
+}
+export function checkResolvedEdge(edge, profile, layerDirs, deny) {
+    const findings = [];
+    const fromMod = edge.fromMod;
+    if (fromMod === undefined) {
+        return findings;
+    }
+    if (edge.to === "dynamic:expr") {
+        findings.push(dynamicFinding(edge, fromMod));
+        return findings;
+    }
+    if (edge.external === "entry") {
+        return findings;
+    }
+    if (edge.external === "deep") {
+        findings.push(entryFinding(edge.from, edge.line, edge.to, `${edge.to} entry`));
+        return findings;
+    }
+    const toMod = edge.toMod;
+    if (toMod === undefined) {
+        findings.push(mappedFinding(edge.from, edge.line, `import target ${edge.to} sits outside every architecture module`));
+        return findings;
+    }
+    if (toMod.name === fromMod.name) {
+        const layered = checkLayerEdge(edge, fromMod, toMod, profile, layerDirs);
+        if (layered !== undefined) {
+            findings.push(layered);
+        }
+        return findings;
+    }
+    const entry = moduleEntry(toMod);
+    if (!isPublicEntryTarget(toMod, edge.to)) {
+        findings.push(entryFinding(edge.from, edge.line, edge.to, entry));
+    }
+    if (!dependsAllowed(fromMod, toMod, deny) ||
+        !profileAllowsEdge(profile, fromMod, toMod)) {
+        findings.push(boundaryFinding(edge.from, edge.line, `module ${fromMod.name} must not import module ${toMod.name}`));
+    }
+    return findings;
+}

package/dist/features/arch/graph.d.ts

@@ -0,0 +1,32 @@
+import { type Result } from "../../kernel/index.ts";
+import type { ImportRef, ModuleNode } from "./index.ts";
+export declare function normalizeSeparators(path: string): string;
+export declare function normalizeImportPath(path: string): string;
+export declare function resolveRelativeSpecifier(fromPath: string, spec: string): string;
+export declare function isRelativeSpecifier(spec: string): boolean;
+export declare function isBuiltinSpecifier(spec: string): boolean;
+export declare function moduleBase(mod: ModuleNode): string;
+export declare function assignModule(modules: ReadonlyArray<ModuleNode>, file: string): ModuleNode | undefined;
+export declare function resolveAliasSpecifier(modules: ReadonlyArray<ModuleNode>, spec: string): string | undefined;
+export declare function resolveImportTarget(modules: ReadonlyArray<ModuleNode>, from: string, spec: string): string;
+export declare function buildGraph(modules: ReadonlyArray<ModuleNode>, refs: ReadonlyArray<ImportRef>): Array<ImportRef>;
+export interface GraphCacheEntry {
+    readonly hash: string;
+    readonly refs: ReadonlyArray<ImportRef>;
+}
+export interface GraphCacheState {
+    readonly version: 1;
+    readonly entries: Readonly<Record<string, GraphCacheEntry>>;
+}
+export declare const EMPTY_GRAPH_CACHE: GraphCacheState;
+export declare function hashGraphContent(text: string): string;
+export declare function parseGraphCache(text: string): Result<GraphCacheState>;
+export declare function serializeGraphCache(cache: GraphCacheState): string;
+export interface GraphCacheFile {
+    readonly path: string;
+    readonly text: string;
+}
+export declare function updateGraphCache(cache: GraphCacheState, files: ReadonlyArray<GraphCacheFile>, extract: (path: string, text: string) => ReadonlyArray<ImportRef>): {
+    readonly cache: GraphCacheState;
+    readonly refs: Array<ImportRef>;
+};

package/dist/features/arch/graph.js

@@ -0,0 +1,202 @@
+// SPEC §4.11.3: the language-neutral import graph. Path handling,
+// module assignment and the content-hash cache live here; the per-language
+// lexers feed it through the ImportExtractor contract (§3.4).
+import { err, makeError, normalizeText, ok, parseJson, sha256Text, stableStringify, } from "../../kernel/index.js";
+// SPEC §4.11 EC-13: Windows separators normalise before resolution.
+export function normalizeSeparators(path) {
+    return path.split("\\").join("/");
+}
+function splitSegments(path) {
+    return path.split("/");
+}
+function joinSegments(parts) {
+    return parts.join("/");
+}
+// Lexical `.`/`..` collapsing over posix segments; never touches the disk.
+export function normalizeImportPath(path) {
+    const absolute = path.startsWith("/");
+    const kept = [];
+    for (const part of splitSegments(path)) {
+        if (part === "" || part === ".") {
+            continue;
+        }
+        if (part === "..") {
+            kept.pop();
+            continue;
+        }
+        kept.push(part);
+    }
+    const joined = joinSegments(kept);
+    return absolute ? `/${joined}` : joined;
+}
+function parentDir(path) {
+    const slash = path.lastIndexOf("/");
+    if (slash < 0) {
+        return ".";
+    }
+    if (slash === 0) {
+        return "/";
+    }
+    return path.slice(0, slash);
+}
+// Relative resolution against the importing file, separators normalised.
+export function resolveRelativeSpecifier(fromPath, spec) {
+    const from = normalizeSeparators(fromPath);
+    const target = normalizeSeparators(spec);
+    const joined = parentDir(from) === "." ? target : `${parentDir(from)}/${target}`;
+    return normalizeImportPath(joined);
+}
+export function isRelativeSpecifier(spec) {
+    return (spec.startsWith("./") ||
+        spec.startsWith("../") ||
+        spec === "." ||
+        spec === "..");
+}
+export function isBuiltinSpecifier(spec) {
+    return spec.startsWith("node:") || spec === "node";
+}
+// The `path` glob is a literal prefix ending in `/**`; the first module
+// whose prefix holds the file owns it (§4.11.3 Assign).
+export function moduleBase(mod) {
+    const raw = normalizeSeparators(mod.path);
+    return raw.endsWith("/**") ? raw.slice(0, -3) : raw;
+}
+export function assignModule(modules, file) {
+    const candidate = normalizeSeparators(file);
+    for (const mod of modules) {
+        const base = moduleBase(mod);
+        if (candidate === base || candidate.startsWith(`${base}/`)) {
+            return mod;
+        }
+    }
+    return undefined;
+}
+// An "@name/..." specifier names a module only when the map declares it;
+// otherwise the checks judge it as an external package specifier.
+export function resolveAliasSpecifier(modules, spec) {
+    const target = normalizeSeparators(spec);
+    if (!target.startsWith("@")) {
+        return undefined;
+    }
+    const rest = target.slice(1);
+    const slash = rest.indexOf("/");
+    if (slash < 0) {
+        return undefined;
+    }
+    const name = rest.slice(0, slash);
+    const tail = rest.slice(slash + 1);
+    const mod = modules.find((entry) => entry.name === name || entry.name.endsWith(`/${name}`));
+    if (mod === undefined) {
+        return undefined;
+    }
+    return tail === "" ? moduleBase(mod) : `${moduleBase(mod)}/${tail}`;
+}
+// SPEC §4.11.3 Extract+Resolve: separators first, then relative targets
+// resolve against the importer. External package targets stay as written so
+// the checks judge entry versus deep imports on the specifier.
+export function resolveImportTarget(modules, from, spec) {
+    const source = normalizeSeparators(from);
+    const target = normalizeSeparators(spec);
+    if (isRelativeSpecifier(target)) {
+        return resolveRelativeSpecifier(source, target);
+    }
+    const aliased = resolveAliasSpecifier(modules, target);
+    if (aliased !== undefined) {
+        return normalizeImportPath(aliased);
+    }
+    if (!target.includes("/") || target.startsWith("@")) {
+        return target;
+    }
+    if (target.includes("://") || target.startsWith("/")) {
+        return normalizeImportPath(target);
+    }
+    return normalizeImportPath(target);
+}
+// SPEC §4.11.3: import graph construction over the module map. Pure:
+// normalise, resolve, then hand the resolved edges to the checks. Cyclic
+// dependsOn is a config error (CDX-E105 at validation); the graph itself
+// never throws so L1 can judge a single new edge.
+export function buildGraph(modules, refs) {
+    const seen = new Set();
+    const edges = [];
+    for (const ref of refs) {
+        const from = normalizeSeparators(ref.from);
+        const to = resolveImportTarget(modules, ref.from, ref.to);
+        const key = JSON.stringify([from, to, ref.line]);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        edges.push({ from, to, line: ref.line });
+    }
+    edges.sort((left, right) => left.from < right.from
+        ? -1
+        : left.from > right.from
+            ? 1
+            : left.to < right.to
+                ? -1
+                : left.to > right.to
+                    ? 1
+                    : left.line - right.line);
+    return edges;
+}
+export const EMPTY_GRAPH_CACHE = { version: 1, entries: {} };
+export function hashGraphContent(text) {
+    return sha256Text(normalizeText(text));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Bracket access through a variable keeps noPropertyAccessFromIndexSignature
+// satisfied without tripping useLiteralKeys (the config validate.ts pattern).
+function field(record, name) {
+    return record[name];
+}
+function isGraphCacheState(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (field(value, "version") !== 1) {
+        return false;
+    }
+    const entries = field(value, "entries");
+    return typeof entries === "object" && entries !== null;
+}
+export function parseGraphCache(text) {
+    const parsed = parseJson(text);
+    if (!parsed.ok) {
+        return parsed;
+    }
+    if (!isGraphCacheState(parsed.value)) {
+        return err(makeError("CDX-E101", "graph cache is not a version 1 cache state", "Delete .codictator/cache/graph.json so the arch guard rebuilds it, then retry."));
+    }
+    return ok(parsed.value);
+}
+export function serializeGraphCache(cache) {
+    return stableStringify(cache);
+}
+// Re-lex only added and changed files; dropped files leave the cache.
+export function updateGraphCache(cache, files, extract) {
+    const entries = {};
+    const refs = [];
+    const seen = new Set();
+    for (const file of files) {
+        const path = normalizeSeparators(file.path);
+        if (seen.has(path)) {
+            continue;
+        }
+        seen.add(path);
+        const hash = hashGraphContent(file.text);
+        const cached = cache.entries[path];
+        const fileRefs = cached !== undefined && cached.hash === hash
+            ? cached.refs
+            : [...extract(path, file.text)].map((ref) => ({
+                from: normalizeSeparators(ref.from),
+                to: normalizeSeparators(ref.to),
+                line: ref.line,
+            }));
+        entries[path] = { hash, refs: fileRefs };
+        refs.push(...fileRefs);
+    }
+    return { cache: { version: 1, entries }, refs };
+}

package/dist/features/arch/index.d.ts

@@ -0,0 +1,29 @@
+import type { CheckContext, Finding } from "../engine/index.ts";
+import { ARCH_PROFILES, type ArchProfile, isArchProfile } from "./arch-profiles.ts";
+import { type ArchCheckOptions, checkArchProfile, checkModuleSize, type ModuleSizeLimits, type ModuleSizeSummary } from "./checks.ts";
+import { CODICTATOR_MODULES, CODICTATOR_PROFILE } from "./codictator-modules.ts";
+import { EMPTY_GRAPH_CACHE, type GraphCacheEntry, type GraphCacheFile, type GraphCacheState, hashGraphContent, normalizeSeparators, parseGraphCache, resolveImportTarget, serializeGraphCache, updateGraphCache } from "./graph.ts";
+import { layerMayImport, resolveLayer } from "./layer-rules.ts";
+import { validateModuleMap } from "./module-map-validation.ts";
+import { deriveModules, isPublicEntryTarget } from "./module-mapping.ts";
+export interface ImportRef {
+    readonly from: string;
+    readonly to: string;
+    readonly line: number;
+}
+export interface ImportExtractor {
+    readonly language: string;
+    readonly extensions: ReadonlyArray<string>;
+    readonly extract: (path: string, text: string) => Array<ImportRef>;
+}
+export interface ModuleNode {
+    readonly name: string;
+    readonly path: string;
+    readonly kind?: string;
+    readonly entry?: string;
+    readonly dependsOn: ReadonlyArray<string>;
+}
+export type { ArchCheckOptions, ArchProfile, GraphCacheEntry, GraphCacheFile, GraphCacheState, ModuleSizeLimits, ModuleSizeSummary, };
+export { ARCH_PROFILES, CODICTATOR_MODULES, CODICTATOR_PROFILE, checkArchProfile, checkModuleSize, deriveModules, EMPTY_GRAPH_CACHE, hashGraphContent, isArchProfile, isPublicEntryTarget, layerMayImport, normalizeSeparators, parseGraphCache, resolveImportTarget, resolveLayer, serializeGraphCache, updateGraphCache, validateModuleMap, };
+export declare function buildGraph(modules: ReadonlyArray<ModuleNode>, refs: ReadonlyArray<ImportRef>): Array<ImportRef>;
+export declare function checkArch(ctx: CheckContext, refs: ReadonlyArray<ImportRef>, options?: ArchCheckOptions): Promise<Array<Finding>>;