pasika 0.2.0 → 0.3.0

package/dist/enforcement/docs-check.js

@@ -0,0 +1,159 @@
+import path from "node:path";
+import { parseDocs, RFC_2119 } from "./parse-docs.js";
+/**
+ * Identifiers of the documentation checks. The enforcement registry points at
+ * these, so renaming one is a change the registry has to follow.
+ */
+export const DOCS_CHECKS = [
+    "doc-kind-suffix",
+    "title-matches-file-name",
+    "overview-present",
+    "overview-length",
+    "guide-overview-no-links",
+    "guide-step-single-sentence",
+    "guide-step-single-link",
+    "guide-states-no-requirement",
+    "guide-folder-entry-point",
+    "requirement-present",
+    "rule-paired-examples",
+    "example-heading-description",
+    "policy-no-examples",
+    "policy-single-document",
+    "no-cross-document-link",
+    "reference-no-rfc-vocabulary",
+    "reference-block-headings",
+    "support-document-placement",
+    "no-template-prompt",
+];
+function countSentences(text) {
+    // Abbreviations inside requirement text are rare, so a period followed by
+    // whitespace is a reliable sentence boundary here.
+    return text.split(/[.!?](?:\s+|$)/).filter((part) => part.trim() !== "").length;
+}
+function checkDoc(doc, allDocs) {
+    const findings = [];
+    const add = (line, check, message) => {
+        findings.push({ doc: doc.doc, line, check, message });
+    };
+    if (!doc.kind) {
+        add(1, "doc-kind-suffix", "file name carries no -guide, -rule, -reference, or -policy suffix");
+        return findings;
+    }
+    const expectedFileName = `${doc.title
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")}.md`;
+    if (doc.title === "") {
+        add(1, "title-matches-file-name", "document has no `# Title` heading");
+    }
+    else if (expectedFileName !== doc.fileName) {
+        add(1, "title-matches-file-name", `title "${doc.title}" expects file name ${expectedFileName}`);
+    }
+    if (doc.overview === undefined) {
+        add(2, "overview-present", "no overview follows the title");
+    }
+    else if (countSentences(doc.overview) > 2) {
+        add(2, "overview-length", `overview uses ${String(countSentences(doc.overview))} sentences, at most two are allowed`);
+    }
+    if (doc.kind === "guide") {
+        if (doc.overview?.includes("](")) {
+            add(2, "guide-overview-no-links", "guide overview links another document");
+        }
+        for (const step of doc.steps) {
+            if (countSentences(step.text) > 1) {
+                add(step.line, "guide-step-single-sentence", `step uses ${String(countSentences(step.text))} sentences`);
+            }
+            if (step.links.length > 1) {
+                add(step.line, "guide-step-single-link", `step links ${String(step.links.length)} documents`);
+            }
+        }
+        if (doc.requirements.length > 0) {
+            const first = doc.requirements[0];
+            add(first?.line ?? 1, "guide-states-no-requirement", "guide states a requirement with RFC 2119 vocabulary");
+        }
+    }
+    else {
+        for (const link of doc.docLinks) {
+            add(link.line, "no-cross-document-link", `${doc.kind} links another document: ${link.target}`);
+        }
+    }
+    if ((doc.kind === "rule" || doc.kind === "policy") && doc.requirements.length === 0) {
+        add(1, "requirement-present", `${doc.kind} document states no requirement`);
+    }
+    if (doc.kind === "rule") {
+        const incorrect = doc.exampleHeadings.filter((heading) => heading.text.startsWith("Incorrect"));
+        const correct = doc.exampleHeadings.filter((heading) => heading.text.startsWith("Correct"));
+        if (incorrect.length === 0 || incorrect.length !== correct.length) {
+            add(1, "rule-paired-examples", `${String(incorrect.length)} Incorrect and ${String(correct.length)} Correct examples`);
+        }
+        for (const heading of doc.exampleHeadings) {
+            if (!/^(?:Incorrect|Correct) — .+/.test(heading.text)) {
+                add(heading.line, "example-heading-description", `example heading has no em-dash description: ${heading.text}`);
+            }
+        }
+    }
+    if (doc.kind === "policy") {
+        for (const heading of doc.exampleHeadings) {
+            add(heading.line, "policy-no-examples", `policy document contains an example: ${heading.text}`);
+        }
+        const policyDocs = allDocs.filter((other) => other.kind === "policy");
+        if (policyDocs.length > 1 && policyDocs[0] === doc) {
+            add(1, "policy-single-document", `${String(policyDocs.length)} policy documents exist`);
+        }
+    }
+    if (doc.kind === "reference") {
+        doc.proseWithoutCode.forEach((line, index) => {
+            const match = RFC_2119.exec(line);
+            if (match) {
+                add(index + 1, "reference-no-rfc-vocabulary", `reference uses RFC 2119 vocabulary: ${match.groups?.keyword ?? ""}`);
+            }
+        });
+        if (doc.sectionHeadings.length === 1) {
+            add(doc.sectionHeadings[0]?.line ?? 1, "reference-block-headings", "reference has exactly one section heading, so either a single block is headed or a first block is not");
+        }
+    }
+    // Rules and references a guide owns live in its rules/ and references/ folders.
+    const parentFolder = path.basename(path.dirname(doc.filePath));
+    if (doc.kind === "rule" && parentFolder !== "rules") {
+        add(1, "support-document-placement", `rule lives in "${parentFolder}/" instead of "rules/"`);
+    }
+    if (doc.kind === "reference" && parentFolder !== "references") {
+        add(1, "support-document-placement", `reference lives in "${parentFolder}/" instead of "references/"`);
+    }
+    doc.prose.forEach((line, index) => {
+        if (/^\s*\[[A-Z0-9].*\]\s*$/.test(line)) {
+            add(index + 1, "no-template-prompt", "leftover bracketed template prompt");
+        }
+    });
+    return findings;
+}
+/**
+ * A folder that holds `rules/` or `references/` is a guide folder, so it needs a
+ * guide named after it as its entry point. Other guides may share that folder.
+ */
+function checkGuideFolders(docs) {
+    const guideFolders = new Set(docs
+        .filter((doc) => ["rules", "references"].includes(path.basename(path.dirname(doc.filePath))))
+        .map((doc) => path.dirname(path.dirname(doc.filePath))));
+    return [...guideFolders]
+        .sort((left, right) => left.localeCompare(right))
+        .flatMap((folder) => {
+        const expectedEntryPoint = `${path.basename(folder)}.md`;
+        const hasEntryPoint = docs.some((doc) => doc.kind === "guide" && path.dirname(doc.filePath) === folder && doc.fileName === expectedEntryPoint);
+        if (hasEntryPoint)
+            return [];
+        const anyDoc = docs.find((doc) => doc.filePath.startsWith(`${folder}${path.sep}`));
+        return [
+            {
+                doc: anyDoc ? path.dirname(path.dirname(anyDoc.doc)) : path.basename(folder),
+                line: 1,
+                check: "guide-folder-entry-point",
+                message: `folder holds support documents but has no ${expectedEntryPoint} entry point`,
+            },
+        ];
+    });
+}
+export function checkDocs(docsRoot) {
+    const docs = parseDocs(docsRoot);
+    return { docs, findings: [...docs.flatMap((doc) => checkDoc(doc, docs)), ...checkGuideFolders(docs)] };
+}

package/dist/enforcement/normalize.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reduces a requirement bullet to the text its meaning depends on.
+ *
+ * Markdown links collapse to their link text and code spans lose their
+ * backticks, so editing a URL or adding backticks does not read as a change in
+ * what the requirement demands. Whitespace collapses so re-wrapping a long
+ * bullet is not a change either.
+ */
+export declare function normalizeRequirement(bullet: string): string;
+/** Short, stable fingerprint of a canonical requirement text. */
+export declare function hashRequirement(canonicalText: string): string;

package/dist/enforcement/normalize.js

@@ -0,0 +1,21 @@
+import { createHash } from "node:crypto";
+/**
+ * Reduces a requirement bullet to the text its meaning depends on.
+ *
+ * Markdown links collapse to their link text and code spans lose their
+ * backticks, so editing a URL or adding backticks does not read as a change in
+ * what the requirement demands. Whitespace collapses so re-wrapping a long
+ * bullet is not a change either.
+ */
+export function normalizeRequirement(bullet) {
+    return bullet
+        .replace(/^\s*[-*]\s+/, "")
+        .replaceAll(/\[(?<text>[^\]]+)\]\([^)]*\)/g, "$<text>")
+        .replaceAll("`", "")
+        .replaceAll(/\s+/g, " ")
+        .trim();
+}
+/** Short, stable fingerprint of a canonical requirement text. */
+export function hashRequirement(canonicalText) {
+    return createHash("sha256").update(canonicalText).digest("hex").slice(0, 10);
+}

package/dist/enforcement/parse-docs.d.ts

@@ -0,0 +1,58 @@
+/** The four document kinds the documentation guide defines. */
+export type DocKind = "guide" | "rule" | "reference" | "policy";
+/** Words that carry requirement strength, longest first so `MUST NOT` wins over `MUST`. */
+declare const RFC_2119: RegExp;
+export interface ParsedRequirement {
+    /** Canonical text used for identity. */
+    text: string;
+    hash: string;
+    /** The bullet as written, without its list marker. */
+    raw: string;
+    line: number;
+}
+export interface ParsedStep {
+    line: number;
+    text: string;
+    /** Documents this step links, as written. */
+    links: string[];
+}
+export interface ParsedDoc {
+    /** Absolute path on disk. */
+    filePath: string;
+    /** Path relative to the docs root, with forward slashes. */
+    doc: string;
+    fileName: string;
+    /** Undefined when no file-name suffix identifies the kind. */
+    kind?: DocKind;
+    title: string;
+    /** First non-empty prose line under the title. */
+    overview?: string;
+    /** Prose lines with fenced code blocks blanked and code spans unwrapped, indexed from 0. */
+    prose: string[];
+    /**
+     * Prose lines with code spans removed rather than unwrapped, so a backticked
+     * keyword counts as naming the keyword rather than using it.
+     */
+    proseWithoutCode: string[];
+    requirements: ParsedRequirement[];
+    /** Numbered list items, which only a Guide is expected to have. */
+    steps: ParsedStep[];
+    /** `## Incorrect`/`## Correct` headings in document order. */
+    exampleHeadings: {
+        line: number;
+        text: string;
+    }[];
+    /** Every link to another Markdown document, outside fenced code. */
+    docLinks: {
+        line: number;
+        target: string;
+    }[];
+    /** `## ` section headings, excluding the example headings. */
+    sectionHeadings: {
+        line: number;
+        text: string;
+    }[];
+}
+export declare function parseDoc(filePath: string, docsRoot: string): ParsedDoc;
+export declare function parseDocs(docsRoot: string): ParsedDoc[];
+export { RFC_2119 };

package/dist/enforcement/parse-docs.js

@@ -0,0 +1,94 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { hashRequirement, normalizeRequirement } from "./normalize.js";
+const KIND_BY_SUFFIX = [
+    ["-rule.md", "rule"],
+    ["-guide.md", "guide"],
+    ["-reference.md", "reference"],
+    ["-policy.md", "policy"],
+];
+/** Words that carry requirement strength, longest first so `MUST NOT` wins over `MUST`. */
+const RFC_2119 = /\b(?<keyword>MUST NOT|MUST|SHOULD NOT|SHOULD|MAY)\b/;
+function listMarkdownFiles(dir) {
+    return readdirSync(dir).flatMap((entry) => {
+        const entryPath = path.join(dir, entry);
+        if (statSync(entryPath).isDirectory()) {
+            // Underscore folders hold templates and other support assets, not documents.
+            return entry.startsWith("_") ? [] : listMarkdownFiles(entryPath);
+        }
+        return entry.endsWith(".md") ? [entryPath] : [];
+    });
+}
+/**
+ * Blanks fenced code blocks and unwraps inline code spans, keeping one entry per
+ * source line so reported line numbers still match the file.
+ */
+function toProse(body, codeSpanReplacement) {
+    let insideFence = false;
+    return body.split("\n").map((line) => {
+        if (/^\s*(?:```|~~~)/.test(line)) {
+            insideFence = !insideFence;
+            return "";
+        }
+        if (insideFence)
+            return "";
+        return line.replaceAll(/`(?<content>[^`]*)`/g, codeSpanReplacement);
+    });
+}
+function findDocLinks(line) {
+    return [...line.matchAll(/\]\((?<target>[^)]*\.md[^)]*)\)/g)].map((match) => match.groups?.target ?? "");
+}
+export function parseDoc(filePath, docsRoot) {
+    const body = readFileSync(filePath, "utf8");
+    const prose = toProse(body, "$<content>");
+    const proseWithoutCode = toProse(body, "");
+    const fileName = path.basename(filePath);
+    const kind = KIND_BY_SUFFIX.find(([suffix]) => fileName.endsWith(suffix))?.[1];
+    const requirements = [];
+    const steps = [];
+    const exampleHeadings = [];
+    const sectionHeadings = [];
+    const docLinks = [];
+    prose.forEach((line, index) => {
+        const lineNumber = index + 1;
+        for (const target of findDocLinks(line)) {
+            docLinks.push({ line: lineNumber, target });
+        }
+        if (/^\s*[-*]\s/.test(line) && RFC_2119.test(line)) {
+            const text = normalizeRequirement(line);
+            requirements.push({ text, hash: hashRequirement(text), raw: line.replace(/^\s*[-*]\s+/, ""), line: lineNumber });
+        }
+        if (/^\s*\d+\.\s/.test(line)) {
+            steps.push({ line: lineNumber, text: line.replace(/^\s*\d+\.\s+/, ""), links: findDocLinks(line) });
+        }
+        if (/^## (?:Incorrect|Correct)\b/.test(line)) {
+            exampleHeadings.push({ line: lineNumber, text: line.slice(3).trim() });
+        }
+        else if (line.startsWith("## ")) {
+            sectionHeadings.push({ line: lineNumber, text: line.slice(3).trim() });
+        }
+    });
+    const title = /^# (?<title>.+)$/m.exec(body)?.groups?.title?.trim() ?? "";
+    const overview = prose.slice(1).find((line) => line.trim() !== "" && !line.startsWith("#"));
+    return {
+        filePath,
+        doc: path.relative(docsRoot, filePath).split(path.sep).join("/"),
+        fileName,
+        kind,
+        title,
+        overview,
+        prose,
+        proseWithoutCode,
+        requirements,
+        steps,
+        exampleHeadings,
+        docLinks,
+        sectionHeadings,
+    };
+}
+export function parseDocs(docsRoot) {
+    return listMarkdownFiles(docsRoot)
+        .sort((a, b) => a.localeCompare(b))
+        .map((filePath) => parseDoc(filePath, docsRoot));
+}
+export { RFC_2119 };

package/dist/enforcement/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The enforcement registry — the record of how every documented requirement is
+ * checked.
+ *
+ * A requirement is identified by the hash of its canonical text, not by a
+ * hand-written id. Rewording a requirement therefore changes its hash, which
+ * makes `pasika coverage` report it as changed until someone re-confirms that
+ * the recorded enforcement still covers it.
+ */
+import { z } from "zod";
+export declare const enforcementKindSchema: z.ZodEnum<{
+    eslint: "eslint";
+    doctor: "doctor";
+    "docs-check": "docs-check";
+    judgment: "judgment";
+    permission: "permission";
+    planned: "planned";
+}>;
+export declare const requirementSchema: z.ZodObject<{
+    doc: z.ZodString;
+    text: z.ZodString;
+    hash: z.ZodString;
+    kind: z.ZodEnum<{
+        eslint: "eslint";
+        doctor: "doctor";
+        "docs-check": "docs-check";
+        judgment: "judgment";
+        permission: "permission";
+        planned: "planned";
+    }>;
+    ref: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const registrySchema: z.ZodObject<{
+    requirements: z.ZodArray<z.ZodObject<{
+        doc: z.ZodString;
+        text: z.ZodString;
+        hash: z.ZodString;
+        kind: z.ZodEnum<{
+            eslint: "eslint";
+            doctor: "doctor";
+            "docs-check": "docs-check";
+            judgment: "judgment";
+            permission: "permission";
+            planned: "planned";
+        }>;
+        ref: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EnforcementKind = z.infer<typeof enforcementKindSchema>;
+export type Requirement = z.infer<typeof requirementSchema>;
+export type Registry = z.infer<typeof registrySchema>;
+/** Every kind, in the order the coverage summary prints them. */
+export declare const ENFORCEMENT_KINDS: EnforcementKind[];
+/** The kinds that count as mechanically enforced today. */
+export declare const MECHANICAL_KINDS: EnforcementKind[];

package/dist/enforcement/types.js

@@ -0,0 +1,59 @@
+/**
+ * The enforcement registry — the record of how every documented requirement is
+ * checked.
+ *
+ * A requirement is identified by the hash of its canonical text, not by a
+ * hand-written id. Rewording a requirement therefore changes its hash, which
+ * makes `pasika coverage` report it as changed until someone re-confirms that
+ * the recorded enforcement still covers it.
+ */
+import { z } from "zod";
+export const enforcementKindSchema = z.enum([
+    /** An ESLint rule reports it. */
+    "eslint",
+    /** A `pasika doctor` check reports it. */
+    "doctor",
+    /** A `pasika docs` check reports it. */
+    "docs-check",
+    /** No mechanical check can decide it; a reviewer or agent applies it. */
+    "judgment",
+    /** The requirement grants permission, so there is nothing to check. */
+    "permission",
+    /** A mechanical check is possible but not written yet. */
+    "planned",
+]);
+export const requirementSchema = z.object({
+    /** Document path relative to the docs root. */
+    doc: z.string(),
+    /** Canonical requirement text: links flattened, code spans unwrapped, whitespace collapsed. */
+    text: z.string(),
+    /** Short hash of `text`. */
+    hash: z.string(),
+    kind: enforcementKindSchema,
+    /**
+     * Identifier of the check that covers this requirement: an ESLint rule id, a
+     * doctor check id, or a docs-check id. Several ids are comma-separated.
+     * Absent for judgment and permission.
+     */
+    ref: z.string().optional(),
+    /**
+     * For `judgment`, why no mechanical check can decide it. For `planned`, the
+     * check that should cover it. For `eslint` and `doctor`, what the existing
+     * check does not cover.
+     */
+    note: z.string().optional(),
+});
+export const registrySchema = z.object({
+    requirements: z.array(requirementSchema),
+});
+/** Every kind, in the order the coverage summary prints them. */
+export const ENFORCEMENT_KINDS = [
+    "eslint",
+    "doctor",
+    "docs-check",
+    "planned",
+    "judgment",
+    "permission",
+];
+/** The kinds that count as mechanically enforced today. */
+export const MECHANICAL_KINDS = ["eslint", "doctor", "docs-check"];

package/dist/eslint/pasika/index.d.ts

@@ -1,20 +1,14 @@
 /**
  * Pasika ESLint Ruleset
  *
- * Each rule enforces a specific documentation Rule from the `docs/` tree.
- * Every rule file carries a `@see` annotation linking to the source doc.
- * This mapping is maintained so future agents can audit rule/doc alignment.
- *
- * Rule → Doc mapping:
- *
- *   filename-case          → docs/code-organization-guide/rules/smart-vs-dumb-component-rule.md
- *   import-boundaries      → docs/code-organization-guide/rules/exports-and-imports-rule.md
- *   no-mixed-concerns      → docs/code-organization-guide/rules/no-mixed-concerns-rule.md
- *   no-arbitrary-tailwind  → docs/styling-guide/rules/arbitrary-value-rule.md
- *   enforce-cn-merge       → docs/styling-guide/rules/class-composition-rule.md
- *   enforce-cva-variant-props → docs/styling-guide/rules/component-variant-rule.md
- *   enforce-barrel-exports → docs/code-organization-guide/rules/folder-nesting-rule.md
- *                          + docs/code-organization-guide/rules/exports-and-imports-rule.md
+ * Each rule enforces requirements from the `docs/` tree, and each rule file
+ * carries a `@see` annotation naming the document it comes from. Which
+ * documented requirement each rule covers is recorded in
+ * `enforcement/registry.json` and verified by `pasika coverage`.
  */
-import type { Linter } from "eslint";
+import type { Linter, Rule } from "eslint";
+/** Every rule the plugin provides, keyed by its unprefixed name. */
+export declare const pasikaRules: Record<string, Rule.RuleModule>;
+/** Rule ids as they appear in configuration and in lint output. */
+export declare const pasikaRuleIds: string[];
 export declare const pasikaConfig: Linter.Config;

package/dist/eslint/pasika/index.js

@@ -5,28 +5,26 @@ import { noArbitraryTailwindRule } from "./rules/no-arbitrary-tailwind.js";
 import { enforceCnMergeRule } from "./rules/enforce-cn-merge.js";
 import { enforceCvaVariantPropsRule } from "./rules/enforce-cva-variant-props.js";
 import { enforceBarrelExportsRule } from "./rules/enforce-barrel-exports.js";
+import { componentPlacementRule } from "./rules/component-placement.js";
+import { supportFilePlacementRule } from "./rules/support-file-placement.js";
+/** Every rule the plugin provides, keyed by its unprefixed name. */
+export const pasikaRules = {
+    "component-placement": componentPlacementRule,
+    "support-file-placement": supportFilePlacementRule,
+    "filename-case": filenameCaseRule,
+    "import-boundaries": importBoundariesRule,
+    "no-mixed-concerns": noMixedConcernsRule,
+    "no-arbitrary-tailwind": noArbitraryTailwindRule,
+    "enforce-cn-merge": enforceCnMergeRule,
+    "enforce-cva-variant-props": enforceCvaVariantPropsRule,
+    "enforce-barrel-exports": enforceBarrelExportsRule,
+};
+/** Rule ids as they appear in configuration and in lint output. */
+export const pasikaRuleIds = Object.keys(pasikaRules).map((name) => `pasika/${name}`);
 export const pasikaConfig = {
     files: ["src/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx}"],
     plugins: {
-        pasika: {
-            rules: {
-                "filename-case": filenameCaseRule,
-                "import-boundaries": importBoundariesRule,
-                "no-mixed-concerns": noMixedConcernsRule,
-                "no-arbitrary-tailwind": noArbitraryTailwindRule,
-                "enforce-cn-merge": enforceCnMergeRule,
-                "enforce-cva-variant-props": enforceCvaVariantPropsRule,
-                "enforce-barrel-exports": enforceBarrelExportsRule,
-            },
-        },
-    },
-    rules: {
-        "pasika/filename-case": "error",
-        "pasika/import-boundaries": "error",
-        "pasika/no-mixed-concerns": "error",
-        "pasika/no-arbitrary-tailwind": "error",
-        "pasika/enforce-cn-merge": "error",
-        "pasika/enforce-cva-variant-props": "error",
-        "pasika/enforce-barrel-exports": "error",
+        pasika: { rules: pasikaRules },
     },
+    rules: Object.fromEntries(pasikaRuleIds.map((id) => [id, "error"])),
 };

package/dist/eslint/pasika/project/ccf.d.ts

@@ -0,0 +1,48 @@
+import type { ProjectIndex } from "./index.js";
+export declare const SUPPORT_FOLDERS: Set<string>;
+/** Path of a file relative to the source root, as segments. */
+export declare function segmentsOf(file: string, sourceRoot: string): string[];
+/** Folder of a file relative to the source root, as segments. */
+export declare function folderSegmentsOf(file: string, sourceRoot: string): string[];
+export declare const isUnderApp: (segments: string[]) => boolean;
+export declare const isConfigModule: (segments: string[]) => boolean;
+export declare const isUnderCompositions: (segments: string[]) => boolean;
+export interface ComponentPlacement {
+    /** Consumers that count toward the calculation, as absolute paths. */
+    countedConsumers: string[];
+    /** Folder the component belongs in, relative to the source root. */
+    expectedFolder: string[];
+    /** Why the expected folder is what it is, for the report. */
+    reason: "ccf" | "across-features" | "across-layers";
+}
+/**
+ * Resolves where a component belongs from the files that import it.
+ *
+ * Imports from `src/app/` and from configuration modules drop out, consumers
+ * under `src/compositions/` count only when every consumer is there, and a
+ * result of `src/features/` becomes `src/shared/` because no feature may import
+ * from another. Returns undefined when no consumer counts, which is the case the
+ * "lives in the feature it represents" requirement covers instead.
+ */
+export declare function resolveComponentPlacement(componentFile: string, index: ProjectIndex): ComponentPlacement | undefined;
+export declare const formatFolder: (folder: string[]) => string;
+export interface SupportPlacement {
+    countedConsumers: string[];
+    expectedFolder: string[];
+    reason: "app-consumer" | "config-module" | "ccf" | "across-features" | "across-layers";
+}
+/**
+ * Resolves where a support file belongs from the files that import it.
+ *
+ * A consumer inside a support folder is owned by that folder's parent, so the
+ * calculation lands on the scope that uses the file rather than on a sibling
+ * support folder. A consumer under `src/app/` forces the root support folder, a
+ * set of consumers inside one configuration module keeps the file in that module,
+ * and consumers spanning features land in the root support folder.
+ */
+export declare function resolveSupportPlacement(supportFile: string, supportFolder: string, index: ProjectIndex): SupportPlacement | undefined;
+/**
+ * Consumers for a message. A widely used file can have dozens, so the list is
+ * capped: the point is to show where the requirement comes from, not to enumerate.
+ */
+export declare function describeConsumers(consumers: string[], sourceRoot: string): string;