@intentset/architecture 0.1.0

package/src/ownership.ts

@@ -0,0 +1,135 @@
+/**
+ * Behavior ownership and contract surfaces (VSA001, VSA002; Core §5).
+ *
+ * VSA001 at L2 and above: an approved, implemented, released or deprecated
+ * behavior has exactly one incoming `implements` from a product slice. Core
+ * reports the same condition as CORE006 from the graph alone; VSA001 is the
+ * architecture's own statement of it, so a VSA report stands by itself.
+ *
+ * VSA002: each of a slice's entrypoints is a file in the repository and lies
+ * inside one of the slice's own source claims, and no two lie in the same
+ * package (the nearest directory above holding a package.json, or the
+ * repository root): a slice has one public surface per package it spans. An
+ * empty entrypoint module is allowed for a leaf.
+ *
+ * VSA012 (deleting or splitting a slice dispositions its behavior, paths and
+ * contracts) is a diff between two snapshots. This check sees one snapshot,
+ * so it emits nothing for VSA012; what a deletion leaves behind still shows
+ * here as VSA001 for the orphaned behavior and VSA009 or AMP004 for the
+ * orphaned files.
+ */
+import type { Artifact, Graph, Level } from "@intentset/core";
+import { LEVELS } from "@intentset/core";
+import { type Finding, finding } from "./finding.ts";
+import { compareStrings, matchPattern, validatePattern } from "./patterns.ts";
+import { describePackage, type Model } from "./regions.ts";
+
+const OWNED_STATUSES = new Set(["approved", "implemented", "released", "deprecated"]);
+
+export function checkOwnership(model: Model, graph: Graph, level: Level): Finding[] {
+  const findings: Finding[] = [];
+
+  if (LEVELS.indexOf(level) >= LEVELS.indexOf("L2")) {
+    const behaviors = [...graph.artifacts.values()]
+      .filter((artifact) => artifact.meta.type === "behavior" && OWNED_STATUSES.has(artifact.meta.status))
+      .sort((a, b) => compareStrings(a.meta.id, b.meta.id));
+    for (const behavior of behaviors) {
+      const id = behavior.meta.id;
+      const owners = (graph.in.get(id) ?? [])
+        .filter((edge) => edge.kind === "implements")
+        .map((edge) => graph.artifacts.get(edge.from))
+        .filter((slice): slice is Artifact => slice?.meta.slice?.kind === "product")
+        .map((slice) => slice.meta.id)
+        .sort(compareStrings);
+      const unique = [...new Set(owners)];
+      if (unique.length === 1) continue;
+      findings.push(
+        finding({
+          code: "VSA001",
+          artifact: id,
+          path: behavior.path,
+          message:
+            unique.length === 0
+              ? `Behavior ${id} is ${behavior.meta.status} and no product slice implements it.`
+              : `Behavior ${id} is ${behavior.meta.status} and ${unique.length} product slices implement it: ${unique.join(", ")}.`,
+          remediation:
+            unique.length === 0
+              ? "Add it to the implements of the one product slice accountable for it, or retire it with replacedBy (VSA001)."
+              : "Keep implements on the one accountable slice and express the others through dependsOn and contracts (VSA001).",
+          paths: unique.map((owner) => graph.artifacts.get(owner)!.path),
+          edges: unique.map((owner) => ({ from: owner, to: id })),
+        }),
+      );
+    }
+  }
+
+  for (const slice of model.slices) {
+    // The first entrypoint seen in each package; a second in the same package is reported against it.
+    const byPackage = new Map<string, string>();
+    slice.meta.entrypoints.forEach((entrypoint, i) => {
+      const field = `/intentset/slice/entrypoints/${i}`;
+      if (entrypoint === "" || validatePattern(entrypoint) !== null || entrypoint.includes("*")) {
+        findings.push(
+          finding({
+            code: "VSA002",
+            artifact: slice.id,
+            path: slice.path,
+            field,
+            message: `${slice.id} declares the entrypoint "${entrypoint}", which is not one repository-relative file path.`,
+            remediation:
+              "Name the file that is the slice's public contract surface in its package, such as its index.ts (VSA002, TS001).",
+          }),
+        );
+        return;
+      }
+      const pkg = model.packageOf(entrypoint);
+      const first = byPackage.get(pkg);
+      if (first !== undefined) {
+        findings.push(
+          finding({
+            code: "VSA002",
+            artifact: slice.id,
+            path: slice.path,
+            field,
+            message: `${slice.id} declares two entrypoints in ${describePackage(pkg)}, ${first} and ${entrypoint}; a slice has one public surface per package it spans.`,
+            remediation: `Export what ${entrypoint} offers from ${first} and remove it from entrypoints, or move it into the package it serves (VSA002).`,
+            paths: [first, entrypoint],
+          }),
+        );
+      } else byPackage.set(pkg, entrypoint);
+      if (!model.files.has(entrypoint)) {
+        findings.push(
+          finding({
+            code: "VSA002",
+            artifact: slice.id,
+            path: slice.path,
+            field,
+            message: `The entrypoint ${entrypoint} of ${slice.id} is not a file in the repository.`,
+            remediation: "Create the entrypoint, empty if the slice exposes nothing yet, or correct the path (VSA002).",
+            paths: [entrypoint],
+          }),
+        );
+        return;
+      }
+      const owned = slice.meta.claims.some(
+        (claim, k) =>
+          claim.kind === "source" && !slice.invalidClaims.includes(k) && matchPattern(claim.path, entrypoint),
+      );
+      if (!owned) {
+        findings.push(
+          finding({
+            code: "VSA002",
+            artifact: slice.id,
+            path: slice.path,
+            field,
+            message: `The entrypoint ${entrypoint} of ${slice.id} lies outside every source claim of the slice.`,
+            remediation: "Move the entrypoint into the slice's source claim, or extend the claim to cover it (VSA002).",
+            paths: [entrypoint],
+          }),
+        );
+      }
+    });
+  }
+
+  return findings;
+}

package/src/paths.ts

@@ -0,0 +1,53 @@
+/**
+ * Repository-relative POSIX path arithmetic. The repository root is "" and a
+ * path never starts with "/" or "./". Anything that climbs above the root is
+ * null, never clamped, because a path outside the repository is not a file
+ * this checker may attribute (VSA §3).
+ */
+
+/** Join and normalize; null when the result leaves the repository. */
+export function joinPath(base: string, relative: string): string | null {
+  const out: string[] = base === "" ? [] : base.split("/");
+  for (const segment of relative.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (out.length === 0) return null;
+      out.pop();
+    } else out.push(segment);
+  }
+  return out.join("/");
+}
+
+export function dirname(path: string): string {
+  const slash = path.lastIndexOf("/");
+  return slash === -1 ? "" : path.slice(0, slash);
+}
+
+export function basename(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+
+/** The directory and each ancestor up to the root (""), nearest first. */
+export function ancestors(directory: string): string[] {
+  const out: string[] = [];
+  let current = directory;
+  for (;;) {
+    out.push(current);
+    if (current === "") return out;
+    current = dirname(current);
+  }
+}
+
+/** A path relative to a directory, or null when it is not inside it. */
+export function within(directory: string, path: string): string | null {
+  if (directory === "") return path;
+  if (path === directory) return "";
+  return path.startsWith(`${directory}/`) ? path.slice(directory.length + 1) : null;
+}
+
+export const CODE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+
+/** A file whose imports this checker reads. Declaration files included: their imports are type-only but still edges. */
+export function isCode(path: string): boolean {
+  return CODE_EXTENSIONS.some((extension) => path.endsWith(extension));
+}

package/src/patterns.ts

@@ -0,0 +1,95 @@
+/**
+ * VSA §3 path patterns: repository-relative POSIX paths made of literal
+ * segments, `*` within one segment, and `**` across zero or more segments.
+ * Nothing else is special: `?`, `[` and `]` are literal characters, because
+ * real trees have directories named `[id]`. A `*` never matches `/`, so the
+ * only way to write a star that spans segments is `**` mixed with other
+ * characters, which validatePattern rejects.
+ */
+
+/** Why a pattern is not a v0.1 pattern, or null when it is one. */
+export function validatePattern(pattern: string): string | null {
+  if (pattern === "") return "is empty";
+  if (pattern.startsWith("/")) return "is absolute";
+  if (pattern.includes("\\")) return "uses a backslash; patterns are POSIX paths";
+  if (/[{}]/.test(pattern)) return "uses brace expansion";
+  if (pattern.includes("!")) return "uses negation";
+  const segments = pattern.split("/");
+  if (segments.includes("..")) return "contains `..`";
+  if (segments.includes(".")) return "contains a `.` segment";
+  if (segments.includes("")) return "has an empty segment";
+  for (const segment of segments) {
+    if (segment.includes("**") && segment !== "**")
+      return `puts \`**\` inside the segment \`${segment}\`; \`**\` stands alone`;
+  }
+  return null;
+}
+
+type Segment = { kind: "globstar" } | { kind: "literal"; text: string } | { kind: "glob"; regex: RegExp };
+
+const compiled = new Map<string, Segment[]>();
+
+function compile(pattern: string): Segment[] {
+  let segments = compiled.get(pattern);
+  if (segments !== undefined) return segments;
+  segments = pattern.split("/").map((text): Segment => {
+    if (text === "**") return { kind: "globstar" };
+    if (!text.includes("*")) return { kind: "literal", text };
+    const source = text
+      .split("*")
+      .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+      .join("[^/]*");
+    return { kind: "glob", regex: new RegExp(`^${source}$`) };
+  });
+  compiled.set(pattern, segments);
+  return segments;
+}
+
+/** Does a repository-relative path match a VSA §3 pattern? Invalid patterns match nothing. */
+export function matchPattern(pattern: string, path: string): boolean {
+  if (validatePattern(pattern) !== null) return false;
+  const want = compile(pattern);
+  const have = path.split("/");
+  const memo = new Map<number, boolean>();
+  const step = (p: number, s: number): boolean => {
+    const key = p * (have.length + 1) + s;
+    const known = memo.get(key);
+    if (known !== undefined) return known;
+    let result: boolean;
+    if (p === want.length) result = s === have.length;
+    else {
+      const segment = want[p];
+      if (segment.kind === "globstar") result = step(p + 1, s) || (s < have.length && step(p, s + 1));
+      else if (s === have.length) result = false;
+      else if (segment.kind === "literal") result = segment.text === have[s] && step(p + 1, s + 1);
+      else result = segment.regex.test(have[s]) && step(p + 1, s + 1);
+    }
+    memo.set(key, result);
+    return result;
+  };
+  return step(0, 0);
+}
+
+/** True when any of the patterns matches the path. */
+export function matchAny(patterns: readonly string[], path: string): boolean {
+  return patterns.some((pattern) => matchPattern(pattern, path));
+}
+
+/**
+ * Resolve each claim against the repository's files: for claim i, the sorted
+ * files it matches, minus those any ignore pattern matches (VSA §3: source
+ * enumeration uses a versioned ignore list). An invalid pattern resolves to
+ * nothing; the caller reports it.
+ */
+export function expandClaims(
+  claims: readonly { path: string }[],
+  files: Iterable<string>,
+  ignore: readonly string[],
+): string[][] {
+  const candidates = [...files].filter((file) => !matchAny(ignore, file)).sort(compareStrings);
+  return claims.map((claim) => candidates.filter((file) => matchPattern(claim.path, file)));
+}
+
+export function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/regions.ts

@@ -0,0 +1,243 @@
+/**
+ * Who owns each file (VSA §1, §3, §5). Every file the checker sees falls in
+ * exactly one region, decided in this order:
+ *
+ *   slice:<ID>       claimed by a slice (any claim kind; overlaps are VSA009)
+ *   composition      config.composition, e.g. src/app/**
+ *   shared           config.shared, e.g. src/shared/**
+ *   infrastructure   config.infrastructure, e.g. src/infrastructure/**
+ *   resource:<ID>    under a backend root and matched by a registry resource path
+ *   backend          under a backend root and owned by nothing (AMP004)
+ *   unowned          a code file under a source root owned by nothing (VSA009)
+ *   external         everything else: root configuration, scripts, documents
+ *
+ * Test files are kept apart (profile §3): they belong to the slice whose
+ * claim patterns match them, and only the foreign-internals rules apply.
+ */
+import type { Artifact, Graph, Registries, Resource, SliceMeta } from "@intentset/core";
+import type { ArchitectureConfig } from "./config.ts";
+import { ancestors, dirname, isCode, within } from "./paths.ts";
+import { compareStrings, expandClaims, matchAny, matchPattern, validatePattern } from "./patterns.ts";
+
+export type RegionKind =
+  | "slice"
+  | "composition"
+  | "shared"
+  | "infrastructure"
+  | "resource"
+  | "backend"
+  | "unowned"
+  | "external";
+
+export interface Region {
+  kind: RegionKind;
+  /** Slice ID for "slice", resource ID for "resource". */
+  owner?: string;
+}
+
+export function regionLabel(region: Region): string {
+  return region.owner === undefined ? region.kind : `${region.kind}:${region.owner}`;
+}
+
+export interface SliceInfo {
+  id: string;
+  /** The slice.md path. */
+  path: string;
+  artifact: Artifact;
+  meta: SliceMeta;
+  /**
+   * Directories of the entrypoints, sorted: where the profile's ui/, client/ and domain/ folders live, one root per
+   * package the slice spans. A file belongs to the deepest root above it (`rootOf`).
+   */
+  roots: string[];
+  dependsOn: string[];
+  exposes: string[];
+  consumes: string[];
+  /** Files per claim, in claim order; empty for an invalid pattern. */
+  claimFiles: string[][];
+  /** Claim indexes whose pattern is invalid. */
+  invalidClaims: number[];
+}
+
+export interface ResourceInfo {
+  resource: Resource;
+  index: number;
+  files: string[];
+}
+
+export interface Model {
+  config: ArchitectureConfig;
+  /** Every file not ignored, by path. */
+  files: ReadonlyMap<string, string>;
+  /** Files not ignored and not tests, sorted. */
+  production: string[];
+  /** Test files not ignored, sorted. */
+  tests: string[];
+  slices: SliceInfo[];
+  sliceById: Map<string, SliceInfo>;
+  /** Production file -> the slices (and claim index) that claim it, sorted by slice ID. */
+  claimOwners: Map<string, { slice: string; claim: number }[]>;
+  resources: ResourceInfo[];
+  regionOf(path: string): Region;
+  /** The slice a test file belongs to, by claim pattern, or null. */
+  testOwner(path: string): string | null;
+  /**
+   * A file's package (VSA §3): the nearest ancestor directory holding a package.json in the tree, or the
+   * repository root, "", when there is none.
+   */
+  packageOf(path: string): string;
+  inScope(path: string): boolean;
+  isTest(path: string): boolean;
+  underBackend(path: string): boolean;
+}
+
+/** Slices that own files: every slice artifact with slice metadata that is not retired. */
+export function activeSlices(graph: Graph): Artifact[] {
+  return [...graph.artifacts.values()]
+    .filter(
+      (artifact) =>
+        artifact.meta.type === "slice" && artifact.meta.slice !== undefined && artifact.meta.status !== "retired",
+    )
+    .sort((a, b) => compareStrings(a.meta.id, b.meta.id));
+}
+
+export function buildModel(
+  graph: Graph,
+  registries: Registries,
+  tree: ReadonlyMap<string, string>,
+  config: ArchitectureConfig,
+): Model {
+  const files = new Map<string, string>();
+  for (const path of [...tree.keys()].sort(compareStrings)) {
+    if (!matchAny(config.ignore, path)) files.set(path, tree.get(path) as string);
+  }
+  const isTest = (path: string) => matchAny(config.tests, path);
+  const production = [...files.keys()].filter((path) => !isTest(path));
+  const tests = [...files.keys()].filter(isTest);
+
+  const slices: SliceInfo[] = activeSlices(graph).map((artifact) => {
+    const meta = artifact.meta.slice as SliceMeta;
+    const invalidClaims: number[] = [];
+    meta.claims.forEach((claim, i) => {
+      if (validatePattern(claim.path) !== null) invalidClaims.push(i);
+    });
+    // A verification claim names tests, so it resolves against them as well;
+    // every other kind resolves against production files only, so a source
+    // claim over a directory does not sweep in the tests that sit beside it.
+    const withTests = [...production, ...tests].sort(compareStrings);
+    const claimFiles = meta.claims.map((claim, i) =>
+      invalidClaims.includes(i)
+        ? []
+        : (expandClaims([claim], claim.kind === "verification" ? withTests : production, [])[0] ?? []),
+    );
+    return {
+      id: artifact.meta.id,
+      path: artifact.path,
+      artifact,
+      meta,
+      roots: [...new Set(meta.entrypoints.map(dirname))].sort(compareStrings),
+      dependsOn: [...(artifact.meta.links.dependsOn ?? [])].sort(compareStrings),
+      exposes: [...(artifact.meta.links.exposes ?? [])].sort(compareStrings),
+      consumes: [...(artifact.meta.links.consumes ?? [])].sort(compareStrings),
+      claimFiles,
+      invalidClaims,
+    };
+  });
+  const sliceById = new Map(slices.map((slice) => [slice.id, slice]));
+
+  const claimOwners = new Map<string, { slice: string; claim: number }[]>();
+  for (const slice of slices) {
+    slice.claimFiles.forEach((list, claim) => {
+      for (const file of list) {
+        const owners = claimOwners.get(file) ?? [];
+        owners.push({ slice: slice.id, claim });
+        claimOwners.set(file, owners);
+      }
+    });
+  }
+  // A file two slices claim is VSA009 either way; for its region, the slice whose directory holds it is the
+  // likelier owner, so an overlap reports once rather than turning every import of the file into a boundary error.
+  const home = (file: string, id: string) => rootOf(sliceById.get(id)!, file)?.length ?? -1;
+  for (const [file, owners] of claimOwners) {
+    owners.sort(
+      (a, b) => home(file, b.slice) - home(file, a.slice) || compareStrings(a.slice, b.slice) || a.claim - b.claim,
+    );
+  }
+
+  const resources: ResourceInfo[] = registries.resources.map((resource, index) => ({
+    resource,
+    index,
+    files:
+      validatePattern(resource.path) === null ? production.filter((file) => matchPattern(resource.path, file)) : [],
+  }));
+
+  const underBackend = (path: string) => matchAny(config.backendRoots, path);
+  const regions = new Map<string, Region>();
+  const regionOf = (path: string): Region => {
+    const cached = regions.get(path);
+    if (cached !== undefined) return cached;
+    let region: Region;
+    const owners = claimOwners.get(path);
+    if (owners !== undefined && owners.length > 0) region = { kind: "slice", owner: owners[0].slice };
+    else if (matchAny(config.composition, path)) region = { kind: "composition" };
+    else if (matchAny(config.shared, path)) region = { kind: "shared" };
+    else if (matchAny(config.infrastructure, path)) region = { kind: "infrastructure" };
+    else if (underBackend(path)) {
+      const resource = resources.find((info) => info.files.includes(path));
+      region = resource !== undefined ? { kind: "resource", owner: resource.resource.id } : { kind: "backend" };
+    } else if (isCode(path) && matchAny(config.sourceRoots, path)) region = { kind: "unowned" };
+    else region = { kind: "external" };
+    regions.set(path, region);
+    return region;
+  };
+
+  const packages = new Map<string, string>();
+  const packageOf = (path: string): string => {
+    const directory = dirname(path);
+    const cached = packages.get(directory);
+    if (cached !== undefined) return cached;
+    const found =
+      ancestors(directory).find((dir) => files.has(dir === "" ? "package.json" : `${dir}/package.json`)) ?? "";
+    packages.set(directory, found);
+    return found;
+  };
+
+  const testOwner = (path: string): string | null => {
+    for (const slice of slices) {
+      if (slice.meta.claims.some((claim, i) => !slice.invalidClaims.includes(i) && matchPattern(claim.path, path)))
+        return slice.id;
+    }
+    return null;
+  };
+
+  return {
+    config,
+    files,
+    production,
+    tests,
+    slices,
+    sliceById,
+    claimOwners,
+    resources,
+    regionOf,
+    testOwner,
+    packageOf,
+    inScope: (path) => matchAny(config.scope, path),
+    isTest,
+    underBackend,
+  };
+}
+
+/** The deepest of the slice's entrypoint directories above a file, or null when it lies under none (a backend claim, say). */
+export function rootOf(slice: SliceInfo, path: string): string | null {
+  let found: string | null = null;
+  for (const root of slice.roots) {
+    if (within(root, path) !== null && (found === null || root.length > found.length)) found = root;
+  }
+  return found;
+}
+
+/** "the repository root" or "the package at apps/web", for messages. */
+export function describePackage(directory: string): string {
+  return directory === "" ? "the repository root" : `the package at ${directory}`;
+}