@aid-framework/generator-sdk 0.0.0 → 0.1.48

package/dist/manifest.js

@@ -0,0 +1,357 @@
+/**
+ * The generator plugin manifest (§8.1) and its validation.
+ *
+ * A manifest is the complete contract between a target generator and everything
+ * that consumes it: which target id it serves, which IR versions it can compile,
+ * which capabilities the code it emits actually *has*, and what runtime
+ * technology that code is built against. That last field, `emitsAgainst`, is the
+ * one that makes composition honest — a target that emits Pydantic models and an
+ * OpenTelemetry tracer is not interchangeable with one that emits Zod and
+ * Langfuse, and nothing else in the IR records that.
+ *
+ * Validation is total: an unknown key is an error, capabilities are resolved
+ * through the IR's alias table before being stored, and `irRange` is a real range
+ * so "does this generator support the IR it was handed" is answered by
+ * {@link checkIRSupport} instead of at codegen time.
+ */
+import { IR_VERSION, resolveRequiredCapability } from '@aid-framework/ir';
+import { sortDiagnostics } from '@aid-framework/spec';
+import { GENERATOR_DIAGNOSTIC_CODES, generatorError, } from './diagnostics.js';
+import { DEFAULT_BUSINESS_DIR, DEFAULT_GENERATED_DIR, escapesRoot, isAbsolutePath, normalizeRelativePath, } from './ownership.js';
+import { isValidRange, isValidVersion, satisfies } from './semver.js';
+/** Current on-disk manifest format. Bumped only for a breaking reshape. */
+export const GENERATOR_MANIFEST_VERSION = 1;
+/** §8.1: what the emitted code is built against. Closed vocabularies, one value each. */
+export const ORCHESTRATIONS = [
+    'langgraph',
+    'llamaindex',
+    'dspy',
+    'vercel-ai',
+    'semantic-kernel',
+];
+export const STRUCTURED_OUTPUTS = ['pydantic', 'instructor', 'zod'];
+export const TRACING_BACKENDS = ['otel-genai', 'langfuse', 'langsmith'];
+const TOP_LEVEL_KEYS = new Set([
+    'manifestVersion',
+    'name',
+    'target',
+    'version',
+    'irRange',
+    'capabilities',
+    'emitsAgainst',
+    'output',
+    'optionsSchema',
+]);
+const EMITS_AGAINST_VOCABULARIES = {
+    orchestration: ORCHESTRATIONS,
+    structuredOutput: STRUCTURED_OUTPUTS,
+    tracing: TRACING_BACKENDS,
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function invalid(code, message, path, hint) {
+    return generatorError({ code, message, path, ...(hint === undefined ? {} : { hint }) });
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/** Parses and validates an authored manifest value. Never throws. */
+export function parseManifest(value) {
+    if (!isRecord(value)) {
+        return {
+            diagnostics: [
+                invalid(GENERATOR_DIAGNOSTIC_CODES.manifestNotAMapping, 'A generator manifest must be an object.', 'manifest'),
+            ],
+        };
+    }
+    const diagnostics = [];
+    for (const key of Object.keys(value)) {
+        if (!TOP_LEVEL_KEYS.has(key)) {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestUnknownKey, `Unknown manifest key "${key}".`, key, 'An unrecognised key is usually a typo that silently does nothing. Remove it or fix the spelling.'));
+        }
+    }
+    const manifestVersion = readManifestVersion(value, diagnostics);
+    const name = readString(value, 'name', diagnostics);
+    const target = readString(value, 'target', diagnostics);
+    const version = readVersion(value, diagnostics);
+    const irRange = readIrRange(value, diagnostics);
+    const capabilities = readCapabilities(value, diagnostics);
+    const emitsAgainst = readEmitsAgainst(value, diagnostics);
+    const output = readOutput(value, diagnostics);
+    if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
+        return { diagnostics: sortDiagnostics(diagnostics) };
+    }
+    // Every read above returns a value once no error was recorded, so these casts are
+    // unreachable-but-required by the type checker rather than runtime assertions.
+    return {
+        manifest: {
+            manifestVersion: manifestVersion,
+            name: name,
+            target: target,
+            version: version,
+            irRange: irRange,
+            capabilities: capabilities,
+            emitsAgainst: emitsAgainst,
+            output: output,
+            ...(value.optionsSchema === undefined ? {} : { optionsSchema: value.optionsSchema }),
+        },
+        diagnostics: sortDiagnostics(diagnostics),
+    };
+}
+export function validateManifest(value) {
+    return parseManifest(value).diagnostics;
+}
+export function parseManifestJson(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return {
+            diagnostics: [
+                invalid(GENERATOR_DIAGNOSTIC_CODES.manifestParseFailed, `Generator manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, 'manifest'),
+            ],
+        };
+    }
+    return parseManifest(parsed);
+}
+function readManifestVersion(value, diagnostics) {
+    const raw = value.manifestVersion;
+    if (raw === undefined)
+        return GENERATOR_MANIFEST_VERSION;
+    if (raw !== GENERATOR_MANIFEST_VERSION) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestVersionUnsupported, `manifestVersion ${JSON.stringify(raw)} is not supported; this build reads version ${GENERATOR_MANIFEST_VERSION}.`, 'manifestVersion'));
+        return undefined;
+    }
+    return GENERATOR_MANIFEST_VERSION;
+}
+function readString(value, key, diagnostics) {
+    if (!(key in value)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestMissingField, `Manifest is missing required key "${key}".`, key));
+        return undefined;
+    }
+    if (!isNonEmptyString(value[key])) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestInvalidField, `Manifest key "${key}" must be a non-empty string.`, key));
+        return undefined;
+    }
+    return value[key];
+}
+function readVersion(value, diagnostics) {
+    const version = readString(value, 'version', diagnostics);
+    if (version === undefined)
+        return undefined;
+    if (!isValidVersion(version)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestInvalidField, `Manifest version "${version}" is not a semantic version.`, 'version'));
+        return undefined;
+    }
+    return version;
+}
+function readIrRange(value, diagnostics) {
+    const irRange = readString(value, 'irRange', diagnostics);
+    if (irRange === undefined)
+        return undefined;
+    if (!isValidRange(irRange)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestInvalidField, `Manifest irRange "${irRange}" is not a supported range expression.`, 'irRange', 'Use `||` alternatives with `^`, `~`, `>=`, `<=`, `<`, `>`, or `=` comparators.'));
+        return undefined;
+    }
+    return irRange;
+}
+function readCapabilities(value, diagnostics) {
+    if (!('capabilities' in value)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestMissingField, 'Manifest is missing required key "capabilities".', 'capabilities', 'Declare the capabilities the emitted code actually has; an empty list is allowed but must be explicit.'));
+        return undefined;
+    }
+    const raw = value.capabilities;
+    if (!Array.isArray(raw)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestInvalidField, 'Manifest key "capabilities" must be an array of capability strings.', 'capabilities'));
+        return undefined;
+    }
+    const resolved = [];
+    const seen = new Set();
+    let failed = false;
+    for (const [index, entry] of raw.entries()) {
+        if (typeof entry !== 'string') {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestInvalidField, `capabilities[${index}] must be a string.`, `capabilities[${index}]`));
+            failed = true;
+            continue;
+        }
+        const capability = resolveRequiredCapability(entry);
+        if (capability === undefined) {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestCapabilityUnknown, `capabilities[${index}] "${entry}" is not a known target capability.`, `capabilities[${index}]`));
+            failed = true;
+            continue;
+        }
+        if (seen.has(capability)) {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestCapabilityDuplicate, `capabilities[${index}] "${entry}" resolves to "${capability}", already declared.`, `capabilities[${index}]`));
+            failed = true;
+            continue;
+        }
+        seen.add(capability);
+        resolved.push(capability);
+    }
+    if (failed)
+        return undefined;
+    return [...resolved].sort();
+}
+function readEmitsAgainst(value, diagnostics) {
+    const raw = value.emitsAgainst;
+    if (raw === undefined)
+        return {};
+    if (!isRecord(raw)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestInvalidField, 'Manifest key "emitsAgainst" must be an object.', 'emitsAgainst'));
+        return undefined;
+    }
+    const result = {};
+    let failed = false;
+    for (const [key, entry] of Object.entries(raw)) {
+        const vocabulary = EMITS_AGAINST_VOCABULARIES[key];
+        if (vocabulary === undefined) {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestUnknownKey, `Unknown emitsAgainst key "${key}".`, `emitsAgainst.${key}`, `Known keys: ${Object.keys(EMITS_AGAINST_VOCABULARIES).join(', ')}.`));
+            failed = true;
+            continue;
+        }
+        if (typeof entry !== 'string' || !vocabulary.includes(entry)) {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestEmitsAgainstUnknown, `emitsAgainst.${key} "${String(entry)}" is not one of: ${vocabulary.join(', ')}.`, `emitsAgainst.${key}`));
+            failed = true;
+            continue;
+        }
+        if (key === 'orchestration') {
+            result.orchestration = entry;
+        }
+        else if (key === 'structuredOutput') {
+            result.structuredOutput = entry;
+        }
+        else {
+            result.tracing = entry;
+        }
+    }
+    if (failed)
+        return undefined;
+    return result;
+}
+function readOutput(value, diagnostics) {
+    if (!('output' in value)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestMissingField, 'Manifest is missing required key "output".', 'output'));
+        return undefined;
+    }
+    const raw = value.output;
+    if (!isRecord(raw)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestInvalidField, 'Manifest key "output" must be an object with a `root`.', 'output'));
+        return undefined;
+    }
+    for (const key of Object.keys(raw)) {
+        if (key !== 'root' && key !== 'generatedDir' && key !== 'businessDir') {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestUnknownKey, `Unknown output key "${key}".`, `output.${key}`, 'Known keys: root, generatedDir, businessDir.'));
+        }
+    }
+    const root = readRelative(raw, 'root', diagnostics);
+    const generatedDir = readRelative(raw, 'generatedDir', diagnostics) ?? DEFAULT_GENERATED_DIR;
+    const businessDir = readRelative(raw, 'businessDir', diagnostics) ?? DEFAULT_BUSINESS_DIR;
+    if (root === undefined)
+        return undefined;
+    // `generatedDir` and `businessDir` are relative to `root`, and ownership is decided
+    // from the composed prefix. So the invariant is not that they sit inside `root` —
+    // they never do — but that they are distinct and neither contains the other.
+    // Otherwise one path would belong to both tiers and drift detection would have no
+    // single answer for whether a file may be overwritten.
+    if (generatedDir === businessDir) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestNotRelative, `output.generatedDir and output.businessDir are both "${generatedDir}"; the generated and business tiers must be separate directories.`, 'output.businessDir'));
+        return undefined;
+    }
+    if (isNested(generatedDir, businessDir) || isNested(businessDir, generatedDir)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestNotRelative, `output.generatedDir "${generatedDir}" and output.businessDir "${businessDir}" overlap; one must not contain the other.`, 'output.businessDir'));
+        return undefined;
+    }
+    return { root, generatedDir, businessDir };
+}
+function readRelative(source, key, diagnostics) {
+    const raw = source[key];
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestInvalidField, `output.${key} must be a non-empty string.`, `output.${key}`));
+        return undefined;
+    }
+    if (isAbsolutePath(raw)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestNotRelative, `output.${key} "${raw}" is absolute; output paths are repo-relative.`, `output.${key}`));
+        return undefined;
+    }
+    if (escapesRoot(raw)) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestEscapingRoot, `output.${key} "${raw}" escapes the repository root.`, `output.${key}`));
+        return undefined;
+    }
+    const normalized = normalizeRelativePath(raw);
+    if (normalized === undefined) {
+        diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestNotRelative, `output.${key} "${raw}" is not a relative path.`, `output.${key}`));
+        return undefined;
+    }
+    return normalized;
+}
+/** True when `child` is `parent` itself or sits below it. */
+function isNested(parent, child) {
+    return child === parent || child.startsWith(`${parent}/`);
+}
+/**
+ * The repo-relative prefixes the plan validator needs. `output.root` is repo-relative,
+ * and the managed directories are relative to it, so this is the single place that
+ * turns a manifest's output layout into the two roots ownership is decided from.
+ */
+export function managedRoots(manifest) {
+    const { root, generatedDir, businessDir } = manifest.output;
+    return {
+        generatedDir: `${root}/${generatedDir}`,
+        businessDir: `${root}/${businessDir}`,
+        manifestFilename: `${root}/aid.manifest.json`,
+    };
+}
+export function supportsIR(manifest, irVersion = IR_VERSION) {
+    return satisfies(irVersion, manifest.irRange);
+}
+/** Reports the manifest's `irRange` against the IR version it will actually be given. */
+export function checkIRSupport(manifest, irVersion = IR_VERSION) {
+    if (supportsIR(manifest, irVersion))
+        return [];
+    const diagnostic = generatorError({
+        code: GENERATOR_DIAGNOSTIC_CODES.manifestUnsupportedIr,
+        message: `Generator "${manifest.name}" supports IR ${manifest.irRange} and cannot compile IR ${irVersion}.`,
+        path: 'irRange',
+        hint: 'Regenerate with a generator whose irRange covers this IR version, or pin the IR version the generator was built for.',
+    });
+    return [diagnostic];
+}
+/**
+ * Generator ids and target ids must each be unique across the set a build loads;
+ * two generators claiming one target is a silent last-wins otherwise.
+ */
+export function validateGeneratorSet(manifests) {
+    const diagnostics = [];
+    const seenNames = new Map();
+    const seenTargets = new Map();
+    for (const [index, manifest] of manifests.entries()) {
+        const name = seenNames.get(manifest.name);
+        if (name !== undefined) {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestDuplicateGenerator, `Generator name "${manifest.name}" is declared twice (also at manifests[${name}]).`, `manifests[${index}].name`));
+        }
+        else {
+            seenNames.set(manifest.name, index);
+        }
+        const target = seenTargets.get(manifest.target);
+        if (target !== undefined) {
+            diagnostics.push(invalid(GENERATOR_DIAGNOSTIC_CODES.manifestDuplicateGenerator, `Target "${manifest.target}" is claimed by two generators (also at manifests[${target}]).`, `manifests[${index}].target`));
+        }
+        else {
+            seenTargets.set(manifest.target, index);
+        }
+    }
+    return sortDiagnostics(diagnostics);
+}
+/** The capability declarations a set of manifests contributes, in the IR gate's shape. */
+export function targetCapabilityDeclarations(manifests) {
+    const declarations = {};
+    for (const manifest of [...manifests].sort((left, right) => left.target < right.target ? -1 : left.target > right.target ? 1 : 0)) {
+        declarations[manifest.target] = manifest.capabilities;
+    }
+    return declarations;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

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

package/dist/node-sink.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The filesystem-backed {@link RegenerationSink}. Kept out of `drift.ts` so the
+ * algorithm itself has no dependency on `node:fs` and can be driven from an
+ * in-memory map in tests.
+ *
+ * Writes are atomic (temp file in the destination directory, then rename over the
+ * target) because a partially written generated file is worse than a stale one: it
+ * fails to parse, so nothing downstream can tell "regeneration was interrupted" from
+ * "the generator emitted garbage".
+ */
+import type { RegenerationSink } from './drift.js';
+export declare function createNodeSink(root: string): RegenerationSink;
+/** An in-memory sink, for tests and for dry runs against a plan. */
+export declare function createMemorySink(initial?: Record<string, string>): RegenerationSink & {
+    files: Map<string, string>;
+};
+//# sourceMappingURL=node-sink.d.ts.map

package/dist/node-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sink.d.ts","sourceRoot":"","sources":["../src/node-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CA+B7D;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,gBAAgB,GAAG;IACzF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B,CAcA"}

package/dist/node-sink.js

@@ -0,0 +1,62 @@
+/**
+ * The filesystem-backed {@link RegenerationSink}. Kept out of `drift.ts` so the
+ * algorithm itself has no dependency on `node:fs` and can be driven from an
+ * in-memory map in tests.
+ *
+ * Writes are atomic (temp file in the destination directory, then rename over the
+ * target) because a partially written generated file is worse than a stale one: it
+ * fails to parse, so nothing downstream can tell "regeneration was interrupted" from
+ * "the generator emitted garbage".
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+const TEMP_SUFFIX = '.aid-tmp';
+export function createNodeSink(root) {
+    const base = resolve(root);
+    function absoluteFor(path) {
+        const absolute = resolve(base, ...path.split('/'));
+        if (absolute !== base && !absolute.startsWith(base + sep)) {
+            throw new Error(`Path "${path}" escapes the sink root "${base}".`);
+        }
+        return absolute;
+    }
+    return {
+        read(path) {
+            try {
+                return readFileSync(absoluteFor(path), 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            }
+        },
+        write(path, content) {
+            const absolute = absoluteFor(path);
+            mkdirSync(dirname(absolute), { recursive: true });
+            const temporary = `${absolute}${TEMP_SUFFIX}`;
+            writeFileSync(temporary, content, 'utf8');
+            renameSync(temporary, absolute);
+        },
+        remove(path) {
+            rmSync(absoluteFor(path), { force: true });
+        },
+    };
+}
+/** An in-memory sink, for tests and for dry runs against a plan. */
+export function createMemorySink(initial = {}) {
+    const files = new Map(Object.entries(initial));
+    return {
+        files,
+        read(path) {
+            return files.get(path);
+        },
+        write(path, content) {
+            files.set(path, content);
+        },
+        remove(path) {
+            files.delete(path);
+        },
+    };
+}
+//# sourceMappingURL=node-sink.js.map

package/dist/node-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sink.js","sourceRoot":"","sources":["../src/node-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAIlD,MAAM,WAAW,GAAG,UAAU,CAAC;AAE/B,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B,SAAS,WAAW,CAAC,IAAY;QAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACnD,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,4BAA4B,IAAI,IAAI,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,IAAI;YACP,IAAI,CAAC;gBACH,OAAO,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;YACjD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO,SAAS,CAAC;gBACzE,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,EAAE,OAAO;YACjB,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;YACnC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,MAAM,SAAS,GAAG,GAAG,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC9C,aAAa,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAC1C,UAAU,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,CAAC,IAAI;YACT,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,OAAO,GAA2B,EAAE;IAGnE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,OAAO;QACL,KAAK;QACL,IAAI,CAAC,IAAI;YACP,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QACD,KAAK,CAAC,IAAI,EAAE,OAAO;YACjB,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3B,CAAC;QACD,MAAM,CAAC,IAAI;YACT,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ownership.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Ownership and path rules (§8.3, §8.4, §10).
+ *
+ * The three-tier split is the whole reason regeneration is safe: `generated/` is
+ * generator-owned and never hand-edited, `business/` is developer-owned and written
+ * once, and the ownership of a path is decided by *where it lives*, not by what a
+ * generator happens to say about it. Every path in a plan is normalized through this
+ * module, so a generator cannot escape its own root or claim a business path as
+ * generated (or the reverse).
+ */
+export type FileOwner = 'generated' | 'business';
+export declare const DEFAULT_GENERATED_DIR = "generated";
+export declare const DEFAULT_BUSINESS_DIR = "business";
+/** The ownership manifest. Generator bookkeeping, so it is never a planned artifact. */
+export declare const DEFAULT_MANIFEST_FILENAME = "aid.manifest.json";
+/** The rejected-content sidecar: the newly generated bytes that were *not* written. */
+export declare const REJECTION_SUFFIX = ".aid-rej";
+/**
+ * Normalizes a plan path to a repo-relative POSIX path: backslashes become
+ * separators, `.` segments are dropped, and a leading `./` or `/` is removed.
+ * Returns `undefined` for a path that cannot be expressed relative to the root.
+ * `..` segments are preserved here so `escapesRoot` can report them as an error
+ * rather than this function silently absorbing them.
+ */
+export declare function normalizeRelativePath(path: string): string | undefined;
+export declare function isRelativePath(path: string): boolean;
+/** True when the path climbs above its root. Reported instead of normalized away. */
+export declare function escapesRoot(path: string): boolean;
+export declare function isAbsolutePath(path: string): boolean;
+/**
+ * The owner of a path, from its first segment. Anything outside both roots has no
+ * owner, which is how a plan that reaches outside the two managed tiers is caught.
+ */
+export declare function ownerForPath(path: string, options?: {
+    generatedDir?: string;
+    businessDir?: string;
+}): FileOwner | undefined;
+export declare function isGeneratedPath(path: string, options?: {
+    generatedDir?: string;
+    businessDir?: string;
+}): boolean;
+export declare function isBusinessPath(path: string, options?: {
+    generatedDir?: string;
+    businessDir?: string;
+}): boolean;
+/** Where rejected generated content lands: alongside the file it could not replace. */
+export declare function rejectionPath(path: string): string;
+/** True when the path is the manifest itself or a rejection sidecar, never planned. */
+export declare function isReservedPath(path: string, manifestFilename: string): boolean;
+//# sourceMappingURL=ownership.d.ts.map

package/dist/ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership.d.ts","sourceRoot":"","sources":["../src/ownership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAEjD,eAAO,MAAM,qBAAqB,cAAc,CAAC;AACjD,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAE/C,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAE7D,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUtE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGjD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGpD;AAUD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,SAAS,GAAG,SAAS,CAUvB;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,OAAO,CAET;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,OAAO,CAET;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAI9E"}

package/dist/ownership.js

@@ -0,0 +1,90 @@
+/**
+ * Ownership and path rules (§8.3, §8.4, §10).
+ *
+ * The three-tier split is the whole reason regeneration is safe: `generated/` is
+ * generator-owned and never hand-edited, `business/` is developer-owned and written
+ * once, and the ownership of a path is decided by *where it lives*, not by what a
+ * generator happens to say about it. Every path in a plan is normalized through this
+ * module, so a generator cannot escape its own root or claim a business path as
+ * generated (or the reverse).
+ */
+export const DEFAULT_GENERATED_DIR = 'generated';
+export const DEFAULT_BUSINESS_DIR = 'business';
+/** The ownership manifest. Generator bookkeeping, so it is never a planned artifact. */
+export const DEFAULT_MANIFEST_FILENAME = 'aid.manifest.json';
+/** The rejected-content sidecar: the newly generated bytes that were *not* written. */
+export const REJECTION_SUFFIX = '.aid-rej';
+/**
+ * Normalizes a plan path to a repo-relative POSIX path: backslashes become
+ * separators, `.` segments are dropped, and a leading `./` or `/` is removed.
+ * Returns `undefined` for a path that cannot be expressed relative to the root.
+ * `..` segments are preserved here so `escapesRoot` can report them as an error
+ * rather than this function silently absorbing them.
+ */
+export function normalizeRelativePath(path) {
+    const trimmed = path.trim().replace(/\\/g, '/');
+    if (trimmed === '')
+        return undefined;
+    if (/^[A-Za-z]:\//.test(trimmed))
+        return undefined;
+    const segments = trimmed.split('/').filter((segment) => segment !== '' && segment !== '.');
+    if (segments.length === 0)
+        return undefined;
+    if (segments.includes('..'))
+        return undefined;
+    return segments.join('/');
+}
+export function isRelativePath(path) {
+    return normalizeRelativePath(path) !== undefined;
+}
+/** True when the path climbs above its root. Reported instead of normalized away. */
+export function escapesRoot(path) {
+    const segments = path.trim().replace(/\\/g, '/').split('/');
+    return segments.includes('..');
+}
+export function isAbsolutePath(path) {
+    const trimmed = path.trim();
+    return /^[A-Za-z]:[\\/]/.test(trimmed) || trimmed.startsWith('/') || trimmed.startsWith('\\\\');
+}
+/** Drops a trailing run of `/`. A loop, not `/\/+$/`, which is quadratic when the
+ *  run is not at the end of the string. Root dirs are short, but not attacker-fixed. */
+function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value[end - 1] === '/')
+        end--;
+    return value.slice(0, end);
+}
+/**
+ * The owner of a path, from its first segment. Anything outside both roots has no
+ * owner, which is how a plan that reaches outside the two managed tiers is caught.
+ */
+export function ownerForPath(path, options = {}) {
+    const normalized = normalizeRelativePath(path);
+    if (normalized === undefined)
+        return undefined;
+    const generatedDir = stripTrailingSlashes(options.generatedDir ?? DEFAULT_GENERATED_DIR);
+    const businessDir = stripTrailingSlashes(options.businessDir ?? DEFAULT_BUSINESS_DIR);
+    if (normalized === generatedDir || normalized.startsWith(`${generatedDir}/`))
+        return 'generated';
+    if (normalized === businessDir || normalized.startsWith(`${businessDir}/`))
+        return 'business';
+    return undefined;
+}
+export function isGeneratedPath(path, options = {}) {
+    return ownerForPath(path, options) === 'generated';
+}
+export function isBusinessPath(path, options = {}) {
+    return ownerForPath(path, options) === 'business';
+}
+/** Where rejected generated content lands: alongside the file it could not replace. */
+export function rejectionPath(path) {
+    return `${path}${REJECTION_SUFFIX}`;
+}
+/** True when the path is the manifest itself or a rejection sidecar, never planned. */
+export function isReservedPath(path, manifestFilename) {
+    const normalized = normalizeRelativePath(path);
+    if (normalized === undefined)
+        return false;
+    return normalized === manifestFilename || normalized.endsWith(REJECTION_SUFFIX);
+}
+//# sourceMappingURL=ownership.js.map

package/dist/ownership.js.map

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