paperlint 3.1.3 → 4.0.0

package/dist/eslint-rules/install-path-literals.js

@@ -0,0 +1,105 @@
+/**
+ * Rule 10's mechanical half: nothing outside the port may name a file by WHERE IT IS
+ * INSTALLED.
+ *
+ * The class this exists for has broken this repository five times, silently every time, and
+ * the detail is in `docs/incidents.md`. What matters for the code below is the shape of the
+ * defect: a path that is correct in one install channel and absent in another. There are
+ * three channels and each has its own give-away prefix — the consumer's skills directory
+ * (the symlink channel), the package directory npm creates, and the plugin cache. A literal
+ * naming any of them is a bet on the channel, made by a file that has no business knowing
+ * which channel it is in.
+ *
+ * WHY TWO RULES RATHER THAN ONE. The literals live in two different languages: markdown, in
+ * a skill's own prose and in its `allowed-tools` frontmatter, and JavaScript, in the modules
+ * this package ships. A single rule cannot visit both — ESLint hands a rule the AST of
+ * whatever language the file is, and the node types share nothing. So the detector is shared
+ * and the visitors are not.
+ *
+ * WHY NOT A GREP OVER THE FILE. In markdown the give-away sits inside a fenced block, inline
+ * code, or a YAML frontmatter value, and a text scan cannot tell those from a sentence that
+ * merely discusses the hazard — which is exactly what `CLAUDE.md` and `docs/incidents.md` do.
+ * The parser can: this rule sees nodes, and it is pointed only at skills.
+ */
+// Each entry is a prefix that only makes sense in ONE install channel.
+const CHANNEL_PREFIXES = [
+    ".claude/skills/", // the consumer symlinks the package's skills to here
+    "node_modules/", // npm's copy
+    ".claude/plugins/", // the plugin cache
+    "plugins/cache/", // the same cache, named from further up
+];
+/** The first channel prefix appearing in `s`, or null. Plain substring: a path IS a string. */
+function channelPrefixIn(s) {
+    if (typeof s !== "string")
+        return null;
+    for (const p of CHANNEL_PREFIXES)
+        if (s.includes(p))
+            return p;
+    return null;
+}
+// The port, named by its path INSIDE this package — the same in every channel, so naming it
+// is not the bet this rule forbids. One constant, because the advice below was once a file
+// that never existed (#67) and read fine for a week: the harness now requires it on disk.
+const PORT = "skills/paper-pipeline/scripts/consumer.mjs";
+const MESSAGES = {
+    installPath: "This names a file by where it is INSTALLED ('{{prefix}}'), so it resolves in one " +
+        "delivery channel and does not exist in another. Rule 10: every answer to *where* comes " +
+        `from the port, ${PORT}. In a skill, use the substitution the harness performs ` +
+        "(CLAUDE_SKILL_DIR / CLAUDE_PLUGIN_ROOT); in a module, ask the port.",
+};
+/** Markdown: a skill's own prose, its fenced commands, and its YAML frontmatter. */
+const mdInstallPath = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "a skill must not name its scripts by an install-specific path — rule 10, the port owns where",
+        },
+        schema: [],
+        messages: MESSAGES,
+    },
+    create(context) {
+        const check = (node) => {
+            const prefix = channelPrefixIn(node.value);
+            if (prefix)
+                context.report({ node, messageId: "installPath", data: { prefix } });
+        };
+        // `yaml` is the frontmatter block, which is where `allowed-tools` lives; the other three
+        // are the ways a command can appear in the body.
+        return { yaml: check, code: check, inlineCode: check, text: check };
+    },
+};
+/** JavaScript: the modules this package ships. */
+const jsInstallPath = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "a shipped module must not carry an install-specific path literal — rule 10, the port owns where",
+        },
+        schema: [],
+        messages: MESSAGES,
+    },
+    create(context) {
+        const report = (node, prefix) => {
+            context.report({ node, messageId: "installPath", data: { prefix } });
+        };
+        return {
+            Literal(node) {
+                const prefix = channelPrefixIn(node.value);
+                if (prefix)
+                    report(node, prefix);
+            },
+            // A template literal's static parts are just as much a path as a plain string; its
+            // interpolations are not our business, which is why the quasis are read one by one.
+            TemplateElement(node) {
+                const prefix = channelPrefixIn(node.value?.cooked ?? node.value?.raw);
+                if (prefix)
+                    report(node, prefix);
+            },
+        };
+    },
+};
+export default {
+    rules: { "md-install-path": mdInstallPath, "js-install-path": jsInstallPath },
+};
+export { channelPrefixIn, CHANNEL_PREFIXES, PORT };
+//# sourceMappingURL=install-path-literals.js.map

package/dist/eslint-rules/install-path-literals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-path-literals.js","sourceRoot":"","sources":["../../eslint-rules/install-path-literals.ts"],"names":[],"mappings":"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"}

package/dist/eslint-rules/latex-language.d.ts

@@ -0,0 +1,136 @@
+import { TextSourceCodeBase, VisitNodeStep, Directive } from "@eslint/plugin-kit";
+import type { FileProblem, Language, LanguageOptions } from "@eslint/core";
+/** A position in the `.tex`, as unified-latex and mdast both spell it. */
+export interface Point {
+    readonly offset: number;
+    readonly line: number;
+    readonly column: number;
+}
+export interface Span {
+    readonly start: Point;
+    readonly end: Point;
+}
+/**
+ * A node as the projection reads it: unified-latex's shape, with every part the projection can
+ * live without made optional — a macro without `args`, an argument without `content`, an `env`
+ * given as nodes. unified-latex's own `Ast.Root` is one of these.
+ */
+export type TexNode = {
+    readonly type: "string" | "comment";
+    readonly content: string;
+    readonly position?: Span;
+} | {
+    readonly type: "macro";
+    readonly content: string;
+    readonly args?: readonly TexArg[];
+    readonly position?: Span;
+} | {
+    readonly type: "environment" | "mathenv";
+    readonly env: string | readonly TexNode[];
+    readonly content?: readonly TexNode[];
+    readonly args?: readonly TexArg[];
+    readonly position?: Span;
+} | {
+    readonly type: "verbatim" | "verb";
+    readonly env: string;
+    readonly content: string;
+    readonly position?: Span;
+} | {
+    readonly type: "group" | "inlinemath" | "displaymath" | "root";
+    readonly content: readonly TexNode[];
+    readonly position?: Span;
+} | {
+    readonly type: "whitespace" | "parbreak";
+    readonly position?: Span;
+} | TexArg;
+/** A macro's or an environment's argument. */
+export interface TexArg {
+    readonly type: "argument";
+    readonly content?: readonly TexNode[];
+    readonly openMark?: string;
+    readonly closeMark?: string;
+    readonly position?: Span;
+}
+/** What a parser hands the projection. */
+export interface TexRoot {
+    readonly content: readonly TexNode[];
+}
+/**
+ * The projection's mdast-shaped output: the node kinds the prose rules read (`root`, `heading`,
+ * `text`, `strong`, `code`, `html`), each with its span in the `.tex`.
+ */
+export type MdNode = {
+    readonly type: "root" | "strong";
+    readonly position: Span;
+    readonly children: readonly MdNode[];
+} | {
+    readonly type: "heading";
+    readonly position: Span;
+    readonly depth: number;
+    readonly title: string;
+    readonly children: readonly MdNode[];
+} | {
+    readonly type: "text" | "html";
+    readonly position: Span;
+    readonly value: string;
+} | {
+    readonly type: "code";
+    readonly position: Span;
+    readonly lang: string;
+    readonly value: string;
+};
+/** An inline-config comment: an `html` node's text and where it sits. */
+interface ConfigNode {
+    readonly value: string;
+    readonly position: Span;
+}
+export declare function texToMdast(src: string, { parse, }?: {
+    parse?: (s: string) => TexRoot;
+}): {
+    root: MdNode;
+    text: string;
+};
+declare class TexSourceCode extends TextSourceCodeBase<{
+    LangOptions: LanguageOptions;
+    RootNode: MdNode;
+    SyntaxElementWithLoc: MdNode;
+    ConfigNode: ConfigNode;
+}> {
+    #private;
+    ast: MdNode;
+    /**
+     * `raw` is the UNPROJECTED `.tex`, and it is here because the projection is lossy by design:
+     * it blanks macros, so a rule that must count `\S\ref` or `Fig.~\ref` sees spaces. Those
+     * rules are about MARKUP, not prose, and the projection exists precisely to hide markup.
+     *
+     * 🔴 Positions stay interchangeable, which is what makes this safe rather than a second
+     * coordinate system: `blank()` overwrites characters with spaces and never changes length,
+     * so an offset computed on `raw` addresses the same byte of `text`. A rule may therefore
+     * scan `raw` and report with the offset it found.
+     */
+    raw: string;
+    constructor({ text, ast, raw, }: {
+        text: string;
+        ast: MdNode;
+        raw?: string | undefined;
+    });
+    getParent(node: MdNode): MdNode | undefined;
+    getInlineConfigNodes(): ConfigNode[];
+    getDisableDirectives(): {
+        problems: FileProblem[];
+        directives: Directive[];
+    };
+    applyInlineConfig(): {
+        configs: never[];
+        problems: FileProblem[];
+    };
+    traverse(): ArrayIterator<VisitNodeStep>;
+}
+export declare const texLanguage: Language<{
+    LangOptions: LanguageOptions;
+    Code: TexSourceCode;
+    RootNode: MdNode;
+    Node: MdNode;
+}>;
+export {};
+//# sourceMappingURL=latex-language.d.ts.map

package/dist/eslint-rules/latex-language.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latex-language.d.ts","sourceRoot":"","sources":["../../eslint-rules/latex-language.ts"],"names":[],"mappings":"AAsGA,OAAO,EACL,kBAAkB,EAClB,aAAa,EAEb,SAAS,EACV,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAGV,WAAW,EACX,QAAQ,EACR,eAAe,EAGhB,MAAM,cAAc,CAAC;AAEtB,0EAA0E;AAC1E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,GACf;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,aAAa,GAAG,MAAM,CAAC;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;CAC1B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAA;CAAE,GACtE,MAAM,CAAC;AAEX,8CAA8C;AAC9C,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,MAAM,GACd;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEN,yEAAyE;AACzE,UAAU,UAAU;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;CACzB;AAuFD,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,EACE,KAAoD,GACrD,GAAE;IAAE,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;CAAO,GACzC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAyWhC;AAaD,cAAM,aAAc,SAAQ,kBAAkB,CAAC;IAC7C,WAAW,EAAE,eAAe,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC;;IAKS,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAC;gBACA,EACV,IAAI,EACJ,GAAG,EACH,GAAG,GACJ,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC1B;IAMQ,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAGpD,oBAAoB,IAAI,UAAU,EAAE;IAOpC,oBAAoB,IAAI;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,UAAU,EAAE,SAAS,EAAE,CAAA;KAAE;IAe5E,iBAAiB,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAAC,QAAQ,EAAE,WAAW,EAAE,CAAA;KAAE;IAGzD,QAAQ,IAAI,aAAa,CAAC,aAAa,CAAC;CAkBlD;AAED,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC;IACjC,WAAW,EAAE,eAAe,CAAC;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,CAuCA,CAAC"}